HugAgentOS 生产部署完全指南:Docker Compose、外部服务与 Kubernetes 方案对比

原创2026-11-13 12:14:141,868 阅读
文章标签:人工智能大模型AI AgentAgent 框架多智能体工具调用MCP 服务Agent 编排Agent 工作流Agent 沙箱Agent 记忆提示工程本地部署AI 技能插件系统后端前端桌面应用CLI认证鉴权

HugAgentOS 生产部署完全指南:Docker Compose、外部服务与 Kubernetes 方案对比

HugAgentOS 是一款全天候运行的开源智能体框架(Agent Harness),支持真实任务执行、经验沉淀与自主进化。本文将带你完成 HugAgentOS 的生产部署:对比 Docker Compose 标准形态、外部服务 + Kubernetes 云原生方案,覆盖服务拓扑、持久化卷、沙箱配置与上线验证,帮你在 30 分钟内选对并跑通自己的部署路径。

HugAgentOS 智能体平台部署架构:平台层、智能体层、能力组件层与数据底座

一、部署方式怎么选?先看这张对比表

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,不要动容器内端口。

HugAgentOS 开源智能体框架海报:不止会回答,更能可信地行动

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
适用对象 团队 / 生产标准形态 受限容器云、已有中间件的企业环境

选型建议:

  1. 绝大多数团队直接用 Docker Compose——它多用户、全功能、持久化清晰,是官方推荐的生产标准形态;
  2. 内网 / 离线环境按 docker-compose.md 的控制器镜像要求打包离线交付;
  3. 容器云环境已有中间件且禁止自建存储卷时,再上 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。

登录后查看全文
HugAgentOS