安装指南

部署方式速查

方式	适用	周期
Docker Compose 单机	POC / 演示 / 小团队	30 分钟内
Docker Compose 多机	中型团队	1–3 天
Kubernetes (Helm)	大型集群 / 有容器平台	2–5 天
离线安装包	无公网内网 / 信创	按场地安排

前置准备

硬件（最低 / 推荐）

组件	最低	推荐
CPU	8 核	16 核
内存	32G	64G
磁盘	200G SSD	1T+ NVMe SSD
GPU（可选，自部署 LLM）	—	A10 / A100 / H800 / 昇腾

操作系统

Ubuntu 22.04 LTS（推荐）/ Ubuntu 20.04
CentOS Stream 9 / RHEL 9
统信 UOS / 麒麟 V10（信创）

依赖软件

软件	版本	用途
Docker	24.0+	容器运行时
Docker Compose	v2.20+	单机编排
Git	2.30+	源码拉取（私有化）
Nginx	1.22+	反向代理（可选）

方式 A：Docker Compose 单机

1. 拉取部署包

git clone https://git.your-org.com/combo-agent.git
cd combo-agent

2. 配置环境

cp .env.example .env
vim .env   # 修改关键变量

关键变量：

# 访问地址
EXTERNAL_URL=https://combo.example.com
 
# LLM 凭据（至少一个）
OPENAI_API_KEY=sk-...
# 或国产模型
DEEPSEEK_API_KEY=...
QWEN_API_KEY=...
 
# 数据库（默认内置，可替换外部）
DB_PASSWORD=change-me
 
# MinIO
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=change-me-strongly

3. 启动

docker compose up -d

等待 3–5 分钟，所有容器起来后访问 http://<server-ip>:9380 进入。

4. 首次初始化

浏览器打开 http://<server-ip>:9380
创建管理员账号
配置 LLM 渠道
测试一个对话

方式 B：Docker Compose 多机

把"数据层"（数据库 + ES + MinIO + Redis）和"应用层"（API + Agent 运行时 + Web）分节点部署。

典型拓扑：

Rendering diagram…

详细 compose 文件在部署包的 deploy/multi-node/ 下。

方式 C：Kubernetes (Helm)

helm repo add combo-agent https://charts.your-org.com/combo-agent
helm repo update
 
helm install combo combo-agent/combo-agent \
  --namespace combo --create-namespace \
  --values values.yaml

values.yaml 的关键配置：

image:
  repository: your-registry.com/combo-agent
  tag: "v1.0.0"
 
ingress:
  enabled: true
  host: combo.example.com
 
llm:
  provider: deepseek
  apiKey: "ref:secret/llm-api-key"
 
storage:
  minio:
    persistence:
      size: 500Gi

方式 D：离线安装（无公网 / 信创）

1. 在一台有公网的机器上"拼包"

# 提前下载所有镜像
docker pull your-registry.com/combo-agent:v1.0.0
# ...其他依赖镜像
 
# 打包
docker save -o combo-agent-v1.0.0.tar $(docker images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>')

同时把部署包（源码 + compose 文件 + 配置模板）一起打包。

2. 运输到客户内网

物理光盘 / 移动硬盘 / 跨网闸传输。

3. 在客户内网加载

docker load -i combo-agent-v1.0.0.tar
cd combo-agent
cp .env.offline .env
docker compose up -d

首次启动后的验证

健康检查

curl http://<server>:9380/v1/health
# 预期：{"status": "ok", ...}

端到端冒烟

Web 端创建一个对话，发一条消息
预期：几秒内看到 Agent 回复
检查日志无 ERROR

功能冒烟

功能	操作
文件上传	上传一份 PDF，看是否能解析
知识库检索	问一个文档里的问题
Agent 工具调用	触发一个 Skill（例："帮我写一个 hello world 的 py"）
渠道接入	飞书 / 企微发消息，看是否路由到 Session

升级

cd combo-agent
git pull
./scripts/upgrade.sh v1.1.0

升级脚本会：

备份数据库
执行 schema 迁移
拉新镜像
滚动重启
健康检查

回滚

./scripts/rollback.sh v1.0.0

回滚窗口：升级后 24 小时内可一键回滚；超过 24 小时如有 schema 破坏性变更，需走数据恢复流程。

常见问题

Q：启动后某些容器反复重启？ A：检查 .env 中的数据库密码是否包含特殊字符未转义；检查磁盘空间；看容器日志 docker compose logs <service>。

Q：Web 能打开但 Agent 不回复？ A：检查 LLM 凭据是否正确；检查是否能从服务器访问 LLM 端点（私有化环境常见网络不通问题）。

Q：内网没有 Docker Hub，怎么办？ A：走离线安装方式 D；或让部署方把镜像推到客户内网 registry。