> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zgi.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 部署指南

> 从云端体验到私有化上线 — 选择适合你的部署方式

## 部署方式对比

| 方式                 | 适合场景       | 数据位置         | 上线时间   |
| ------------------ | ---------- | ------------ | ------ |
| **云端 SaaS**        | 快速验证、中小团队  | ZGI 云端（加密存储） | 即开即用   |
| **Docker Compose** | 开发环境、小规模生产 | 企业内网         | 1 小时   |
| **Kubernetes**     | 生产高可用      | 企业内网         | 30 分钟  |
| **私有化企业版**         | 金融、政务、医疗合规 | 完全自控         | 3 个工作日 |

## 系统要求（私有化部署）

| 组件     | 最低配置                  | 推荐配置             |
| ------ | --------------------- | ---------------- |
| 操作系统   | Linux (Ubuntu 20.04+) | Ubuntu 22.04 LTS |
| 处理器    | 8 核                   | 16 核+            |
| 内存     | 16 GB                 | 32 GB+           |
| 存储     | 100 GB SSD            | 500 GB SSD+      |
| Docker | 20.10+                | Kubernetes 1.24+ |

## 开源版部署 — 快速开始

ZGI 核心框架在 GitHub 完全开源，任何人都可以直接从源码启动完整服务栈。

### 仓库结构

采用 **git submodule** 方式组织多仓库，顶层仓库负责产品级聚合：

| 目录               | 说明          | 仓库地址                      |
| ---------------- | ----------- | ------------------------- |
| `api/`           | 后端服务（Go）    | `zgiai/zgi-api`           |
| `web/`           | 前端应用（React） | `zgiai/zgi-web`           |
| `sandbox/`       | 代码执行沙箱      | `zgiai/zgi-sandbox`       |
| `plugin-runner/` | 插件执行服务      | `zgiai/zgi-plugin-runner` |
| `docker/`        | 共享中间件与部署资产  | —                         |

### macOS / Linux — Docker 一键启动（推荐）

```shell theme={null}
# 克隆仓库
git clone https://github.com/zgiai/zgi.git
cd zgi

# 一键启动完整 Docker 栈
make dev-docker
```

> **make dev-docker 首次运行会自动完成**
>
> 初始化 submodule → 复制缺失的 env 模板 → 重新生成 root compose → 启动完整 Docker 栈。无需手动操作。

### 中国大陆网络加速

如果镜像构建较慢或不稳定，可使用 `--china` 模式注入推荐镜像源配置（不会改写模板文件）：

```shell theme={null}
./dev/start-docker --china
```

### 环境变量管理

```shell theme={null}
# 检查本地 env 与模板的差异
make env-check

# 追加缺失项（不覆盖现有值）
make env-sync
```

### macOS / Linux — 源码开发模式

```shell theme={null}
# 初始化开发环境
make setup

# 启动中间件（数据库、缓存等）
make dev-docker

# 分别启动后端和前端
make dev-api
make dev-web
```

### Windows 部署

Windows 最低支持 **Docker Desktop + PowerShell**。源码开发辅助工具依赖 Unix-like shell，在 Windows 上不可用。

```powershell theme={null}
# PowerShell
.\dev\start-docker.ps1

# PowerShell（国内镜像）
.\dev\start-docker.ps1 -china
```

### 默认服务地址

| 服务            | 地址                       | 说明       |
| ------------- | ------------------------ | -------- |
| **Web 前端**    | `http://localhost:13000` | 控制台界面    |
| **API 后端**    | `http://localhost:2678`  | REST API |
| PostgreSQL    | `localhost:15432`        | 主数据库     |
| Redis         | `localhost:16379`        | 缓存与消息队列  |
| Weaviate      | `http://localhost:18080` | 向量数据库    |
| Neo4j HTTP    | `http://localhost:17474` | 知识图谱     |
| Sandbox       | `http://localhost:18194` | 代码执行沙箱   |
| Plugin Runner | `http://localhost:15000` | 插件执行服务   |

## Kubernetes 部署

```shell theme={null}
# 添加 ZGI Helm 仓库
helm repo add zgi https://charts.zgi.cn

# 安装
helm install zgi zgi/zgi \
  --namespace zgi --create-namespace \
  --set global.storageClass=your-storage-class \
  --values values-production.yaml
```