hermes-webui Docker Compose 部署：三个容器，一条命令全部跑通
【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui
hermes-webui 把 Hermes Agent 搬进浏览器，会话、工作区、监控都能网页操作。按本 hermes-webui Docker Compose 部署方案，三个容器一条命令拉起。
方案速览：三容器各管一摊
| 容器 | 干什么 | 你访问的入口 |
|---|---|---|
| hermes-agent | Hermes 网关：API、cron 调度、工具执行（限 4GB 内存 / 2 核） | 127.0.0.1:8642，仅容器网络内被调用 |
| hermes-webui | 浏览器聊天界面，会话管理与工作区文件操作 | http://localhost:8787 |
| hermes-dashboard | 监控面板：健康状态、会话与资源用量（限 512MB 内存） | http://localhost:9119 |
三个容器挂在同一张hermes-net桥接网络上，共享hermes-home卷，所以配置、会话、记忆在三个界面之间始终一致。你日常只需要碰 8787 和 9119 两个端口。
部署前自检：三项硬指标
开工前逐项打勾，缺一项先补齐再往下走：
- Docker Engine ≥ 20.10.0
- Docker Compose ≥ 2.0.0
- 可用内存 ≥ 4GB（光 agent 容器就限到 4GB）
- 可用磁盘 ≥ 10GB（两张镜像 + 两个命名卷）
- 网络能拉取 Docker Hub 与 ghcr.io 的镜像
- 仓库已克隆，当前目录在 hermes-webui 内
先克隆仓库并进入项目目录，后面所有命令都在这里执行。
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui进入目录后，你应该能看到 docker-compose.three-container.yml 和 docs/docker.md 等部署相关文件。
角色与端口映射
谁在监听什么，一张表讲清楚：
| 谁 | 负责什么 | 监听端口 |
|---|---|---|
hermes-agent（gateway run） | 会话状态、cron 定时任务、工具调用、对外 API | 8642 |
| hermes-webui | 聊天界面、SSE 流式输出、工作区文件读写 | 8787 |
hermes-dashboard（dashboard --insecure） | 健康检查、CPU/内存/磁盘、会话统计 | 9119 |
容器之间不走宿主机端口，而是用容器名互访：webui 通过HERMES_API_URL=http://hermes-agent:8642调网关，dashboard 通过GATEWAY_HEALTH_URL=http://hermes-agent:8642取数据。8642 在主机侧默认只绑 127.0.0.1，且只有设置了 16 位以上的API_SERVER_KEY才真正开放监听。一个已知限制：从 WebUI 触发的工具运行在 webui 容器里，而不是 agent 容器。
docker-compose.three-container.yml 的核心内容如下，注释已省略：
services: hermes-agent: image: nousresearch/hermes-agent:latest command: gateway run ports: - "127.0.0.1:8642:8642" volumes: - hermes-home:/home/hermes/.hermes - hermes-agent-src:/opt/hermes environment: - HERMES_HOME=/home/hermes/.hermes - HERMES_UID=${UID:-1000} - HERMES_GID=${GID:-1000} - API_SERVER_ENABLED=true - API_SERVER_KEY=${API_SERVER_KEY:-} hermes-dashboard: image: nousresearch/hermes-agent:latest command: dashboard --host 0.0.0.0 --insecure ports: - "127.0.0.1:9119:9119" volumes: - hermes-home:/home/hermes/.hermes environment: - GATEWAY_HEALTH_URL=http://hermes-agent:8642 depends_on: - hermes-agent hermes-webui: image: ghcr.io/nesquena/hermes-webui:latest ports: - "127.0.0.1:8787:8787" volumes: - hermes-home:/home/hermeswebui/.hermes - hermes-agent-src:/home/hermeswebui/.hermes/hermes-agent:ro - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace environment: - HERMES_API_URL=http://hermes-agent:8642 - WANTED_UID=${UID:-1000} - WANTED_GID=${GID:-1000} - HERMES_WEBUI_PASSWORD=${HERMES_WEBUI_PASSWORD:-} volumes: hermes-home: hermes-agent-src:看完这段应记住两件事：三个端口默认都只绑 127.0.0.1；hermes-home三容器共享，hermes-agent-src只读挂给 webui 用于安装 agent 依赖。
一键拉起与验证
执行拉起命令
这条命令会拉取镜像（首次需要几分钟）并后台启动全部三个容器，随后ps复核状态。
docker compose -f docker-compose.three-container.yml up -d docker compose -f docker-compose.three-container.yml ps执行后你应看到 hermes-agent、hermes-dashboard、hermes-webui 三行状态均为running，且 agent 先于另外两个启动完成。
打开页面看到什么
浏览器访问 http://localhost:8787，会进入 WebUI 主界面：左侧会话列表，中间聊天区，右侧可按需打开的工作区面板。
怎么判断部署成功
不发页面也能验证：请求 WebUI 的健康接口，确认服务进程活着。
curl -s http://127.0.0.1:8787/health返回一段 JSON（含运行时长等字段）即说明 WebUI 正常。再打开 http://localhost:9119 的 Dashboard，能看到 CPU、内存、磁盘的系统健康页。
最后在 WebUI 里发一条消息，agent 正常回话，整条链路就算打通了。
调优与加固：三个可调项
自定义工作目录
WebUI 默认把工作目录设为${HOME}/workspace并挂进容器的/workspace。想换成自己的项目目录，设置HERMES_WORKSPACE后重建容器即可。
export HERMES_WORKSPACE=/path/to/your/workspace docker compose -f docker-compose.three-container.yml up -d改完后打开 WebUI 右侧文件面板，看到的应该是你指定目录下的文件。
对齐 UID/GID 权限
三个容器以同一个 UID/GID 运行，默认 1000。macOS 上用户 UID 通常从 501 开始，直接沿用默认值会出现文件属主混乱，建议显式写入.env。
echo "UID=$(id -u)" >> .env echo "GID=$(id -g)" >> .env写入后，.env文件末尾应能看到你机器的真实 UID 和 GID 两行。
给 WebUI 加密码保护
🔑 端口默认只暴露在本机；一旦你要从远程访问，先设置密码再放开绑定。
echo "HERMES_WEBUI_PASSWORD=你的强密码" >> .env保存后打开 8787 会先出现登录页，输入密码才能进入会话界面。
任何.env改动都要靠这条命令让容器重建后生效。
docker compose -f docker-compose.three-container.yml up -d看到三个容器依次重建并回到running状态即完成。
排障速查表
| 现象 | 原因 | 对策 |
|---|---|---|
| WebUI 提示 "Hermes agent is not responding" | 8642 网关监听未开启：API_SERVER_KEY未设置或少于 16 位 | 在.env写入 ≥16 位的API_SERVER_KEY，重建容器 |
| Permission denied | 宿主机绑定挂载时 UID/GID 不匹配，agent 用错误用户初始化了状态目录 | .env写入正确的UID/GID，或改用默认命名卷 |
| 容器启动失败、反复重启 | 8787 / 9119 / 8642 被本机其他进程占用 | 修改 yml 里主机侧端口，如"127.0.0.1:18787:8787" |
| 运行缓慢或 OOM 被杀 | 宿主机给 Docker 的内存低于 4GB 硬指标 | 调大 Docker 资源配额后重启 |
| 升级 agent 镜像后行为异常 | hermes-agent-src卷沿用了旧镜像内容 | 按下一节流程删卷重建 |
各服务日志直接按容器名查，报错信息基本都在里面。
docker logs hermes-agent docker logs hermes-webui docker logs hermes-dashboard执行后应看到对应服务的滚动日志，错误行一般带ERROR或 Traceback 关键字。
升级镜像与备份数据
升级 agent 镜像
hermes-agent-src卷只在首次up时从镜像的/opt/hermes初始化，之后原样复用——即使docker pull了新镜像，卷里还是旧内容。所以升级必须删卷。
⚠️ 删卷会清掉卷内 agent 源码，下次启动会按新镜像重新初始化，这是预期行为。
docker compose -f docker-compose.three-container.yml down docker volume rm hermes-webui_hermes-agent-src docker compose -f docker-compose.three-container.yml pull docker compose -f docker-compose.three-container.yml up -d完成后ps里三个容器应全部running，且 WebUI 里 agent 健康状态恢复正常。
备份 hermes-home 卷
配置、会话、记忆都在hermes-home卷里，备份它等于备份全部重要数据。这条命令把卷打包成一个 tar 包放到当前目录。
docker run --rm -v hermes-webui_hermes-home:/source -v $(pwd):/backup alpine tar -czf /backup/hermes-backup.tar.gz -C /source .执行后当前目录应多出一个hermes-backup.tar.gz文件，建议定期重跑一次。
结语
到这里，Agent、WebUI、Dashboard 三个容器已在同一张网络上跑通，数据落在共享卷里。日常维护就是改.env、up -d重建、按速查表排障，升级和备份各是四行命令的事。
延伸阅读
- 架构文档 ARCHITECTURE.md：前后端结构、SSE 引擎与状态目录的完整说明
- 三容器 Compose 文件 docker-compose.three-container.yml：含远程访问与卷升级注释的完整配置
- Docker 部署文档 docs/docker.md：单容器 / 双容器 / 三容器方案对比
- 测试目录 tests/：可验证各组件行为的自动化测试用例
【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
