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 一键启动（推荐）
# 克隆仓库
git clone https://github.com/zgiai/zgi.git
cd zgi
# 一键启动完整 Docker 栈
make dev-docker
make dev-docker 首次运行会自动完成
初始化 submodule → 复制缺失的 env 模板 → 重新生成 root compose → 启动完整 Docker 栈。无需手动操作。
中国大陆网络加速
如果镜像构建较慢或不稳定，可使用 --china 模式注入推荐镜像源配置（不会改写模板文件）：
./dev/start-docker --china
环境变量管理
# 检查本地 env 与模板的差异
make env-check
# 追加缺失项（不覆盖现有值）
make env-sync
macOS / Linux — 源码开发模式
# 初始化开发环境
make setup
# 启动中间件（数据库、缓存等）
make dev-docker
# 分别启动后端和前端
make dev-api
make dev-web
Windows 部署
Windows 最低支持 Docker Desktop + PowerShell。源码开发辅助工具依赖 Unix-like shell，在 Windows 上不可用。
# 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 部署
# 添加 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