HugAgentOS Docker Compose部署指南:10分钟搭建团队级生产部署的自托管AI Agent平台

原创2026-10-15 19:54:40255 阅读

HugAgentOS Docker Compose部署指南:10分钟搭建团队级生产部署的自托管AI Agent平台

HugAgentOS 是一个面向企业的自托管 AI Agent 平台,把智能对话、私有知识库 RAG、子智能体、MCP 工具、沙箱代码执行和长期记忆整合到一个可私有部署的工作空间中。对于需要多用户协作、数据持久化的团队来说,Docker Compose 是官方推荐的生产部署方式:一条命令即可拉起 PostgreSQL、Redis、后端 API、MCP 工具服务和前端,全部容器化、互不干扰。本指南带你用不到 10 分钟完成这套团队级部署。

为什么选择 Docker Compose 部署 🐳

HugAgentOS 提供多种部署路径,选错方式会踩坑,先对照一下:

部署方式 适用场景 多用户 数据库
桌面端离线本机模式 个人尝鲜 ❌ SQLite
无 Docker 一键安装 个人单机、开发体验 ❌ SQLite
Docker Compose 团队 / 生产标准形态 ✅ PostgreSQL

一句话总结:多人用、要持久化、要隔离沙箱,就用 Docker Compose;个人单机体验可以用更轻的一键安装(见 quick-install.md)。

选择 Docker Compose 的核心理由:

  • 开箱即用的生产形态:关系库用 PostgreSQL、会话用 Redis,全部命名卷持久化,重新部署数据不丢
  • 服务隔离:后端、MCP、前端、沙箱各自独立容器,崩溃互不影响,日志按容器轮转(单容器 250 MB 封顶)
  • 一键扩能力:通过 profiles 按需叠加向量记忆基础设施,不用改任何代码
  • 内置沙箱:轻量沙箱 script-runner 自带 1 GB 内存 / 1 CPU 限额、只读根文件系统,Agent 跑代码不污染主机

部署前环境准备清单

开始之前,确认服务器上已满足以下条件:

项目 要求 检查命令
Docker 20.10+ docker --version
Docker Compose v2 插件 docker compose version
Git 任意稳定版 git --version
CPU / 内存 建议 4 核 / 8 GB 以上(后端默认限 6 GB) nproc && free -h
端口 3002(前端)、3001(后端)、5432、6380 未被占用 ss -tlnp

💡 如果宿主机 5432、6380 等端口已被占用,只需在 .env 里调整 POSTGRES_HOST_PORT、REDIS_HOST_PORT 等宿主侧端口,不要改容器内端口。

三步完成 Docker Compose 部署

整个过程只有三步:克隆代码 → 配置 .env → 构建启动。

第 1 步:克隆仓库并初始化配置

git clone https://gitcode.com/gh_mirrors/hu/HugAgentOS.git
cd HugAgentOS
cp .env.example .env
mkdir -p data/storage

cp .env.example .env 是很多人漏掉的一步。仓库中的 .env.example 已经内置了单机最小可用配置(社区版、本地登录、轻量沙箱),复制为 .env 后,绝大多数默认值可以直接使用。

第 2 步:配置关键环境变量

编辑 .env,必改的只有一项:

# 宿主机存储目录的绝对路径(compose 会校验,不设无法启动)
HOST_STORAGE_PATH=/var/lib/hugagent-storage

${HOST_STORAGE_PATH} 会被 bind mount 进后端和 MCP 容器的 /app/storage,用来存放文件、知识库产物等。建议用独立目录,方便备份。

其余常用变量保持默认即可:

SANDBOX_PROVIDER=script_runner    # 沙箱类型,默认轻量无状态沙箱
STORAGE_TYPE=local                 # 本地文件存储
FRONTEND_PORT=3002                 # 前端对外端口

⚠️ 注意:HOST_STORAGE_PATH 必须是宿主机绝对路径。compose 文件对它有强校验(见 docker-compose.yml),留空会直接报错退出。

第 3 步:构建并启动全部服务

docker compose up -d --build

首次构建需要下载基础镜像并编译后端、MCP、前端三个镜像,视网络状况约 5~15 分钟。看到 6 个容器全部 Up 就成功了:

docker compose ps
NAME                    STATUS
hugagent-postgres       Up (healthy)
hugagent-redis          Up (healthy)
hugagent-backend        Up (healthy)
hugagent-mcp            Up (healthy)
hugagent-frontend       Up (healthy)
hugagent-script-runner  Up (healthy)

🎉 浏览器打开 http://<服务器IP>:3002,初始账号与密码均为 admin,首次登录会强制修改密码。登录后进入「设置 → 系统管理 → 模型服务」,填入你的 OpenAI 兼容端点(base_url / api_key / 模型名)即可开始对话。

服务拓扑:6 个容器各自负责什么

HugAgentOS 的全部服务由根目录一个 docker-compose.yml 编排,核心服务拓扑如下:

服务 容器名 宿主端口 作用
postgres hugagent-postgres 5432 主关系库:业务数据、会话、用量日志
redis hugagent-redis 6380 会话存储、流式事件(Redis Streams)、限流
backend hugagent-backend 3001 FastAPI 应用,启动时自动执行数据库迁移
mcp hugagent-mcp 不对外 内置 MCP 工具:联网搜索、数据集检索、图表生成等
script-runner hugagent-script-runner 不对外 轻量代码沙箱(Agent 跑 bash / Python 的隔离环境)
frontend hugagent-frontend 3002 nginx 托管前端,/api 反代到 backend

HugAgentOS Docker Compose 部署服务架构全景图

几个值得了解的设计细节:

  • 依赖自动编排:backend 会等待 postgres、redis 健康检查通过后才启动,无需手工控制启动顺序
  • 自动数据库迁移:backend 容器入口脚本自动执行 alembic upgrade head(失败自动重试 20 次),常规部署无需手工建表
  • 容器间按服务名互访:都接在同一 bridge 网络 hugagent-network 上,例如后端通过 http://mcp:91XX/mcp/ 调用工具
  • 只暴露一个入口:日常访问只需 3002 前端端口,其余端口仅在需要直连调试时才用到

生产环境关键配置速查

面向生产部署,建议重点确认这几组配置(完整清单见 environment-variables.md):

变量 默认值 生产建议
DB_PASSWORD hugagent_dev_password 必改为强密码
HOST_STORAGE_PATH ./data/storage 必设宿主机绝对路径
ENV dev 设为 prod
TZ Asia/Shanghai 按需调整
DB_POOL_SIZE 100 按数据库连接数上限调整
RATE_LIMIT_ENABLED true 保持开启,可加 Redis 存储计数
MEM0_ENABLED false 需要向量记忆时配合 mem0 profile 开启

后端在进程启动时一次性读取 .env(配置集中在 src/backend/core/config/settings.py),改完 .env 记得重启容器生效:

docker compose restart backend

可选能力:Profiles 按需叠加

Compose 文件用 profiles 把可选项隔离开了,默认只启动核心 6 个服务,资源占用低。需要时按下面方式叠加:

开启向量记忆(mem0 profile)

HugAgentOS 支持 L1 画像 / L2 事实 / L3 知识图谱的分层记忆。L3 图谱记忆依赖 Milvus 向量库与 Neo4j 图库,通过 mem0 profile 一并启动 etcd、minio、milvus、neo4j 四个容器:

# 在 .env 中
COMPOSE_PROFILES=script_runner,mem0
MEM0_ENABLED=true

HugAgentOS 自托管 AI Agent 平台功能全景海报

切换持久沙箱(opensandbox profile)

默认 script_runner 是轻量无状态沙箱;商业版还支持持久沙箱 opensandbox(Jupyter kernel 跨轮保持上下文)。两个沙箱 sidecar 互斥,切换流程:

# 1. .env 中保持一致:
#    SANDBOX_PROVIDER=opensandbox
#    COMPOSE_PROFILES=opensandbox
# 2. 停旧起新
docker compose down
docker compose up -d --build

部署后验证与日常运维

三步验证部署成功

# 1. 健康检查(经 nginx 反代)
curl -fsS http://localhost:3002/api/health

返回 {"status":"healthy",...} 即后端正常。

# 2. 查看各容器日志
docker compose logs -f backend

# 3. 浏览器打开 http://<服务器IP>:3002 登录

改代码后如何更新服务

所有服务都跑在容器里,改代码后必须重建对应镜像才生效:

# 后端改动(重建镜像 + 重启)
docker compose up -d --build backend

# MCP 工具改动(源码是 bind mount,重启即可)
docker compose restart mcp

# 前端改动
docker compose up -d --build frontend

💡 如果「改了没生效」,90% 是 Docker 缓存层没拉到新代码。用无缓存重建: docker compose build --no-cache backend frontend && docker compose up -d backend frontend

常用运维命令速查

docker compose ps                 # 查看状态
docker compose logs -f --tail 100 backend   # 跟踪日志
docker compose restart redis      # 重启单个服务
docker compose down               # 停止(保留数据卷)
docker compose down -v            # 停止并删除数据(危险!会丢库)

数据备份重点:postgres_data 命名卷 + HOST_STORAGE_PATH 目录,这两处备份齐了才算完整备份。

常见问题排查

现象 原因与解决
启动报 HOST_STORAGE_PATH must be set in .env .env 未设置或写了相对路径,改为宿主机绝对路径
3002 端口访问不了 宿主机 3002 被占用,改 FRONTEND_PORT;或服务器防火墙/安全组未放行
backend 反复重启 docker compose logs backend 看启动日志;多为数据库连接或迁移失败
改了 .env 不生效 环境变量只在进程启动时读取,需 docker compose restart 相关服务
沙箱执行报权限错误 backend 挂了 docker.sock,需设 DOCKER_GID 为宿主 docker 组 GID(stat -c '%g' /var/run/docker.sock 查询)
首次构建某可选工具下载失败 钉钉/飞书/邮件/浏览器渲染等可选源不可达时,核心服务仍会构建完成,属预期行为

总结

到这里,一套团队级的 HugAgentOS 自托管 AI Agent 平台就部署完成了。回顾一下关键步骤:

  1. ✅ 克隆仓库,cp .env.example .env
  2. ✅ 设置 HOST_STORAGE_PATH 与 DB_PASSWORD
  3. ✅ docker compose up -d --build 一键拉起 6 个服务
  4. ✅ 访问 http://<服务器IP>:3002,用 admin 登录并改密、配置模型
  5. ✅ 按需叠加 mem0 / opensandbox profile 扩展能力

Docker Compose 是 HugAgentOS 从「个人试用」走向「团队生产」的标准答案:一个编排文件、一条启动命令,数据持久化、服务隔离、自动迁移全部就位。更多细节可参考官方文档 Docker Compose 部署 与 环境变量参考。

登录后查看全文
HugAgentOS