Hermes WebUI 多容器部署完整指南：三条命令跑通 Agent、WebUI 与 Dashboard
项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui 部署完成后，你会得到三个服务入口：8787 端口的聊天界面、9119 端口的监控面板，以及只监听本机 127.0.0.1 的 8642 网关 API。这就是 Hermes WebUI 多容器部署的最终形态——Agent、WebUI、Dashboard 三个容器跑在同一个 Docker 网络里，共享一套数据，配置和会话不会错位。这篇 Hermes 三容器教程直接给你可照抄的操作。
先跑起来：Docker Compose 部署 Hermes 只需三条命令
环境核对：动手前确认这 4 项
- Docker Engine 20.10.0 及以上版本
- Docker Compose 2.0.0 及以上版本
- 至少 4GB 可用内存
- 至少 10GB 可用磁盘空间（拉镜像要用）
拉代码与一键启动
把项目克隆到本地：
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui
cd hermes-webui
进入目录后执行下面这条一键启动命令，三件套会一起跑起来：
docker compose -f docker-compose.three-container.yml up -d
✅ 首次运行要拉取 nousresearch/hermes-agent 和 ghcr.io/nesquena/hermes-webui 两个镜像，慢几分钟是正常的，等它下完即可。
验证：启动后你应该看到什么
命令跑完后，三个入口的分工如下：
| 服务 | 端口 | 访问地址 | 职责 |
|---|---|---|---|
| hermes-agent | 8642 | 仅本机 127.0.0.1:8642 | 核心网关，提供 API 接口与工具调用能力 |
| hermes-webui | 8787 | http://localhost:8787 | 你日常对话用的 Web 聊天界面 |
| hermes-dashboard | 9119 | http://localhost:9119 | 监控面板，查看 agent 活动与资源占用 |
打开 8787，左侧是会话列表，中间是聊天区，右侧能看到工作区里的文件：
再打开 9119，dashboard 会给出 CPU、内存和磁盘的实时占用情况：
为什么要拆成三个容器
三个角色各占一个容器，不是为了好看：
- 单独升级更省事：只更新监控面板时，不用动聊天和 agent 容器，停服窗口更短
- 资源各管各的：compose 文件里给每个容器单独限定了内存和 CPU，监控面板忙起来也挤不占聊天界面的额度
- 数据不分裂：三者挂同一个 hermes-home 卷，会话、配置、记忆在任意入口看都是同一份
配置文件里必须动的三处
docker-compose.three-container.yml 很长，但你只需要关注三个位置。
第 1 处：两个数据卷
hermes-home 存配置、会话和记忆，被三个容器共享；hermes-agent-src 放 agent 源码，供 WebUI 安装依赖时读取。它们都是命名卷（Docker 自己管理的存储目录，不用你手动建路径）：
volumes:
hermes-home:
hermes-agent-src:
第 2 处：端口与工作目录
默认三个端口都绑定 127.0.0.1，也就是只有本机访问得到，这是最安全的状态。端口映射（把容器内端口转发到本机）在 ports 段里：
ports:
- "127.0.0.1:8787:8787"
想让 WebUI 读写你自己的项目目录，把环境变量 HERMES_WORKSPACE 指过去即可，默认值是 ${HOME}/workspace：
export HERMES_WORKSPACE=/path/to/your/workspace
第 3 处：访问密码
只要准备把 8787 暴露给局域网或远程访问，先在 .env 里加一行密码，再重启容器，否则任何能连上端口的人都能登进来：
echo "HERMES_WEBUI_PASSWORD=your-secure-password" >> .env
⚠️ 如果你改用绑定挂载（把宿主机现有目录直接挂进容器）来共享一个已有的 ~/.hermes 目录，三个容器必须用同一个用户身份运行，记得同步写入 UID 和 GID：
echo "UID=$(id -u)" >> .env
echo "GID=$(id -g)" >> .env
踩坑了怎么办：最常见的三个报错
出问题时别慌，先看日志。WebUI 内置了日志页签，不切终端也能翻：
权限报错 Permission denied
- 症状：容器起来后读写文件报权限错，WebUI 每次请求都可能抛异常
- 原因：卷里文件的属主和你的宿主用户不一致，UID/GID 没配置
- 修复：按上面的命令把
id -u、id -g的结果写进.env，然后重建容器：
docker compose -f docker-compose.three-container.yml down && docker compose -f docker-compose.three-container.yml up -d
端口被占用
- 症状：某个服务起不来，报错里提到端口已被占用
- 原因：8642、8787 或 9119 被本机其他程序占着
- 修复：改 compose 文件里对应服务的
ports，把宿主侧端口换个号（例如127.0.0.1:18787:8787），再用同一条up -d命令启动
运行缓慢或容器反复重启
- 症状：响应明显变卡，或容器不停自动拉起
- 原因：分给容器的资源不够用
- 修复：调大 compose 文件中各服务
deploy.resources段的内存与 CPU 限额，重启后观察是否恢复
💡 三种情况修完后，都可以用下面维护小节的日志命令确认状态。
日常维护：日志、升级、备份
看日志
分别查看三个容器的输出，定位到具体是哪个服务出问题：
docker logs hermes-agent
docker logs hermes-webui
docker logs hermes-dashboard
升级镜像版本
⚠️ hermes-agent-src 卷只在首次启动时用镜像内容初始化，之后一直原样复用——光 pull 新镜像它不会跟着变。所以升级顺序必须是：停 → 删旧卷 → 拉新 → 起：
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
备份数据
真正值钱的数据（配置、会话、记忆）都在 hermes-home 卷里，下面这条命令把它打包成 tar.gz 存到当前目录：
docker run --rm -v hermes-webui_hermes-home:/source -v $(pwd):/backup alpine tar -czf /backup/hermes-backup.tar.gz -C /source .
收尾
这套 Hermes WebUI Docker 部署方案适合想把"对话、网关、监控"拆开维护的场景：个人服务器或小团队用一份 compose 文件就能全部拉起，单个组件坏了只影响自己那块。想深入了解容器间的数据流、两容器与三容器的取舍，以及更完整的升级说明，看文末的文档就够了。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
