HugAgentOS 生产部署完全指南:Docker Compose、外部服务与 Kubernetes 方案对比
HugAgentOS 生产部署完全指南:Docker Compose、外部服务与 Kubernetes 方案对比
HugAgentOS 是一款全天候运行的开源智能体框架(Agent Harness),支持真实任务执行、经验沉淀与自主进化。本文将带你完成 HugAgentOS 的生产部署:对比 Docker Compose 标准形态、外部服务 + Kubernetes 云原生方案,覆盖服务拓扑、持久化卷、沙箱配置与上线验证,帮你在 30 分钟内选对并跑通自己的部署路径。
一、部署方式怎么选?先看这张对比表
HugAgentOS 官方支持从「个人单机尝鲜」到「团队生产」再到「内网离线交付」的多种部署形态。生产环境主要涉及下面三种方案,官方文档入口见 部署指南:
| 部署方式 | 适用场景 | 数据库 | 多用户 | 完整文档 |
|---|---|---|---|---|
| 无 Docker 一键安装 | 个人单机尝鲜、二次开发体验 | SQLite | 否(单进程单用户) | quick-install.md |
| Docker Compose | 团队 / 生产标准形态,全功能 | PostgreSQL | 是 | docker-compose.md |
| 外部服务 + Kubernetes | 已有 PG/Redis/MinIO 的受限容器云 | 外部 PostgreSQL | 是 | external-services-kubernetes.md |
💡 选型一句话:个人试用选一键安装;团队生产首选 Docker Compose;容器云平台禁止自建持久卷、且已有外部 PostgreSQL / Redis / MinIO 时,走 Kubernetes 外部服务方案。
二、Docker Compose 生产部署:一个文件编排全部服务
HugAgentOS 的全部服务由根目录 docker-compose.yml 一个文件编排,分为常驻核心服务、互斥的沙箱 sidecar(script_runner / opensandbox)和可选的记忆基础设施(mem0)三层。
核心服务拓扑:5 个容器撑起整条链路
| 服务 | 镜像 / 构建 | 宿主→容器端口 | 作用 |
|---|---|---|---|
postgres |
postgres:15-alpine |
5432:5432 |
主关系库(业务数据、content_blocks、用量日志) |
redis |
redis:7-alpine |
6380:6379 |
会话存储、流式 follower、限流 |
backend |
docker/Dockerfile(target production) |
3001:3001 |
FastAPI 应用,启动时自动执行 alembic 迁移 |
mcp |
docker/Dockerfile.mcp | 无对外端口 | MCP 工具进程,backend 经内部网络调用 |
frontend |
src/frontend/Dockerfile | 3002:80 |
nginx 托管静态资源 + /api 反代到 backend |
依赖关系是 frontend → backend → postgres/redis/mcp,全部容器接在同一 bridge 网络 hugagent-network 中,容器间用服务名互访(如 http://backend:3001)。每个容器统一配置了 json-file 日志轮转(50 MB × 5),防止日志写满磁盘。
⚠️ 端口技巧:
BACKEND_PORT是容器内监听端口,nginx、MCP 和健康检查都依赖它,通常保持3001。宿主机端口被占用时,只改.env里的BACKEND_HOST_PORT、POSTGRES_HOST_PORT、REDIS_HOST_PORT,不要动容器内端口。
CE Docker 默认沙盒:OpenSandbox 一键初始化
CE(社区版)的 Docker 部署默认使用 OpenSandbox 持久沙箱。首次安装只需三条命令:
python3 scripts/configure-ce-docker.py
docker build -f docker/sandbox/Dockerfile.opensandbox -t hugagent-opensandbox-custom:latest .
docker compose up -d --build
初始化脚本 scripts/configure-ce-docker.py 会自动生成绝对宿主路径、项目名和随机控制器密钥,并拒绝覆盖已有 .env;可用 --project-name 和 --storage 指定项目名与存储目录。注意两点:
- 沙箱 sidecar 二选一、互斥:
script_runner(轻量沙箱,1 GB 内存 / 只读 rootfs)与opensandbox(持久沙箱)不能同时跑,切换时保持.env中SANDBOX_PROVIDER与COMPOSE_PROFILES一致即可。 - 运行镜像必须先构建:普通
docker compose build不会构建按需运行的沙盒镜像。
需要向量记忆 / 自建知识库时,在 COMPOSE_PROFILES 上叠加 mem0 即可启动 Milvus、etcd、MinIO、Neo4j 一组记忆基础设施:
COMPOSE_PROFILES=opensandbox,mem0 docker compose up -d
持久化卷:哪些数据会跨重新部署保留
| 卷 / 挂载 | 内容 | 注意 |
|---|---|---|
postgres_data |
全部业务数据 | 跨重新部署保留,删除即丢库 |
redis_data |
AOF 持久化 | — |
${HOST_STORAGE_PATH}(bind mount) |
文件存储、myspace、sandbox_skills | 必须是宿主机绝对路径,供沙盒 host-bind 同一路径 |
opensandbox_config / opensandbox_data |
渲染后的沙箱配置 / 运行数据 | 配置由 init 服务生成,只读挂载 |
/var/run/docker.sock |
宿主 docker daemon | 用于「重建沙盒镜像」,需 DOCKER_GID 与宿主 docker 组一致 |
改代码后的 rebuild 与迁移
- 后端改动:
docker compose up -d --build backend;MCP 改动源码是 bind mount,docker compose restart mcp即生效。 - 「改了没生效」90% 是 cached layer 没拉到新代码,必要时
docker compose build --no-cache backend frontend。 - 数据库迁移全自动:backend 容器入口脚本 src/backend/scripts/backend_entrypoint.sh 启动时执行
alembic upgrade head(默认重试 20 次 × 2s,可用DB_MIGRATION_RETRIES调整),常规部署无需手工操作。
三、外部服务 + Kubernetes 方案:受限容器云的云原生部署
如果你所在的容器云已有外部 PostgreSQL、Redis、MinIO,且不能新增持久卷,HugAgentOS 源码版支持 Kubernetes OpenSandbox 的外部服务部署(商业版 EE),完整步骤见 external-services-kubernetes.md。
平台必须先过的「硬门槛」
- Kubernetes 1.29+,具备 OpenSandbox CRD / namespace 管理权限;
- 有效的 NetworkPolicy,受控 helper 需要 privileged / FUSE / Bidirectional mountPropagation(用于「我的空间」真实 FUSE 挂载);
- 平台禁止特权时,可设
HUGAGENT_SPACE_MOUNT_MODE=sync退化为命令边界一致的 HTTP 增量同步,一致性降低但不需要特权。
关键环境变量与预检流程
容器通过 ConfigMap/Secret 的 envFrom 获取环境变量(设 PYTHON_DOTENV_DISABLED=1),真实凭据不进入源码或镜像。主要配置项:
DEPLOY_PROFILE=kubernetes
STORAGE_TYPE=s3 # MinIO 保存文件与 artifact 元数据
SESSION_STORE=redis
DATABASE_URL / REDIS_URL # 由渲染器对密码特殊字符编码后生成
HUGAGENT_SPACE_MOUNT_MODE=sidecar
MEM0_VECTOR_PROVIDER=pgvector # 向量记忆复用 PostgreSQL 的 pgvector
Redis 必须使用独立库号(应用不给键加前缀,不能与其他系统共用)。上线前先跑 external preflight,真实检查 PG/Redis/MinIO 连通性、FUSE 读写与凭据隔离、会话 NetworkPolicy,再执行迁移和上线——本地验证不能代替目标平台预检。
四、方案对比与选型建议
| 维度 | Docker Compose | 外部服务 + K8s |
|---|---|---|
| 上手成本 | ⭐ 低,一个 yml 文件 | 高,需平台权限与预检 |
| 数据库 / 存储 | 容器内置 PG + Redis + 本地存储 | 外部 PG / Redis / MinIO(S3) |
| 沙箱 | script_runner 或 OpenSandbox 二选一 | Kubernetes OpenSandbox + FUSE 空间挂载 |
| 向量记忆 | mem0 profile(Milvus 等) | pgvector 复用 PostgreSQL |
| 适用对象 | 团队 / 生产标准形态 | 受限容器云、已有中间件的企业环境 |
选型建议:
- 绝大多数团队直接用 Docker Compose——它多用户、全功能、持久化清晰,是官方推荐的生产标准形态;
- 内网 / 离线环境按 docker-compose.md 的控制器镜像要求打包离线交付;
- 容器云环境已有中间件且禁止自建存储卷时,再上 Kubernetes 外部服务方案,且务必先通过 preflight 预检。
五、部署后验证清单
无论哪种方式,起服务后按顺序验证:
# Docker Compose(默认前端端口 3002,经 nginx 反代 /api)
curl -fsS http://localhost:3002/api/health
返回 {"status":"healthy",...} 即后端正常,随后用浏览器打开对应地址、以管理员账号登录。生产上线建议再检查:
- ✅
/health、/ready两个健康检查端点 - ✅ 连续命令文件保留、用户隔离(沙箱)
- ✅ 后端重启后的会话接管与空闲快照恢复
- ✅ 全量环境变量逐组核对:environment-variables.md
📦 获取源码后从根目录执行部署即可,所有编排与镜像定义都在仓库内:docker-compose.yml、docker/Dockerfile、docker/sandbox/Dockerfile.opensandbox、src/frontend/nginx.conf。

