HugAgentOS Docker Compose部署指南:10分钟搭建团队级生产部署的自托管AI Agent平台
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 |
几个值得了解的设计细节:
- 依赖自动编排: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
切换持久沙箱(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 平台就部署完成了。回顾一下关键步骤:
- ✅ 克隆仓库,
cp .env.example .env - ✅ 设置
HOST_STORAGE_PATH与DB_PASSWORD - ✅
docker compose up -d --build一键拉起 6 个服务 - ✅ 访问
http://<服务器IP>:3002,用admin登录并改密、配置模型 - ✅ 按需叠加
mem0/opensandboxprofile 扩展能力
Docker Compose 是 HugAgentOS 从「个人试用」走向「团队生产」的标准答案:一个编排文件、一条启动命令,数据持久化、服务隔离、自动迁移全部就位。更多细节可参考官方文档 Docker Compose 部署 与 环境变量参考。

