企业官网建设流程全解析

Hermes WebUI多容器部署指南：Docker三容器拉起聊天网关与监控面板

【免费下载链接】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

浏览器打开就是熟悉的会话列表，侧边面板里能看到会话历史，监控页上 CPU 和磁盘占用实时跳动——这是 Hermes WebUI 多容器部署完成后的样子。很多人第一次装，只用单容器：聊天能用，但网关进程不常驻，定时任务永远不触发，也没有监控入口。项目自带的docker-compose.three-container.yml把三种角色拆成三个容器：agent 管网关与工具，WebUI 管界面，Dashboard 管观测，一条命令全部拉起。下面按"先跑起来，再搞懂，最后排坑"的顺序走一遍。

一条命令拉起三容器

这节帮你把三个服务在 5 分钟内全部跑起来并确认可访问。克隆仓库，直接用三容器编排文件启动：

git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui docker compose -f docker-compose.three-container.yml up -d

首次执行会自动拉取镜像，等进度走完，浏览器访问两个地址：

• 聊天界面：http://localhost:8787
• 监控面板：http://localhost:9119

三个端口默认都只绑定在 127.0.0.1，本机可用、外网不通，这是刻意的安全默认，后面讲怎么开远程。

docker compose ps里三个容器都是 running，就说明部署本身成功了。

容器拆开看：三个服务各干什么

这节帮你理解架构，出问题时才知道该查哪一边。

• hermes-agent：跑gateway run，监听 8642 端口，负责定时任务的心跳、工具调用和消息通道。它是唯一"干活"的容器。
• hermes-webui：跑聊天界面，8787 端口。它自己不带 agent 的 Python 依赖，启动时会从共享卷里读 agent 源码并安装依赖，所以启动比其他两个稍慢。
• hermes-dashboard：观测面板，9119 端口，通过GATEWAY_HEALTH_URL指向 agent 的网关地址，会话数和资源数据都从那拉。

两个命名卷（Docker 帮你托管、跨容器共享的存储）是关键：hermes-home装配置、会话、技能、记忆，三个容器挂同一份，界面里建的会话 agent 侧也能看到；hermes-agent-src装 agent 源码，WebUI 以只读方式挂载。

个性化改造：工作区、UID 和定时任务

这节帮你把默认值改成贴合自己环境的样子，三处最常动。

换工作区目录。默认挂${HOME}/workspace到容器里的/workspace，想用别的项目目录，启动前设一下环境变量即可：

HERMES_WORKSPACE=/path/to/your/project docker compose -f docker-compose.three-container.yml up -d

对齐用户身份。容器内进程以 UID/GID 运行，和你主机文件属主不一致就会读不到文件。把真实值写进.env再重启：

echo "UID=$(id -u)" >> .env echo "GID=$(id -g)" >> .env

macOS 上 UID 从 501 起，务必手动确认，不能靠默认值 1000。

让定时任务真的跑。网关 API 要拿到 16 位以上的API_SERVER_KEY才会开放 8642 端口，否则 WebUI 会一直提示 "Gateway endpoint not reachable"，定时任务也就没有心跳。生成一个写进.env并强制重建容器：

echo "API_SERVER_KEY=$(openssl rand -hex 24)" >> .env docker compose -f docker-compose.three-container.yml up -d --force-recreate

需要远程访问时，再追加HERMES_WEBUI_PASSWORD（界面密码）和HERMES_DASHBOARD_BIND=0.0.0.0，并确认面板置于反向代理之后。完整变量说明可参考 .env.docker.example 和 docs/docker.md。

踩坑清单：权限报错与网关失联

这节帮你省掉一半的排查时间，四个最常见的症状对应固定解法。

• PermissionError / Permission denied 启动崩溃：UID/GID 没对齐主机文件属主，按上一节写.env后down再up。
• 工作区一片空白但主机上文件都在：同一个原因，绑定挂载的属主和容器身份对不上。
• 升级 agent 镜像后行为像旧版本：hermes-agent-src卷只在首次启动时初始化，之后 Docker 原样复用，新镜像的源码被旧卷遮住。必须先删卷再拉新（详见下一节）。
• 两个容器的HERMES_HOME_MODE含义不同：WebUI 侧是"凭证文件"权限阈值，0640 没问题；agent 侧是"目录"权限，0640 没有执行位会直接让 agent 进不了自己的家目录，要用 0750 或 0701。

⚠️ 排障先看日志：docker logs hermes-webui看界面侧，docker logs hermes-agent看网关侧。WebUI 内置了日志面板，不用只盯终端。

更细的症状对照表在 docs/troubleshooting.md。

升级与备份：数据不丢的关键一步

这节帮你把"升级"变成可重复执行的动作，而不是每次现想。核心原则：换镜像时只删hermes-agent-src，永远不碰hermes-home——前者是源码缓存，后者才是你的全部数据（配置、会话、状态）。

docker compose -f docker-compose.three-container.yml down docker volume rm <项目名>_hermes-agent-src # docker volume ls 可查名称 docker compose -f docker-compose.three-container.yml pull docker compose -f docker-compose.three-container.yml up -d

备份同理，只需打包hermes-home卷：

docker run --rm -v <项目名>_hermes-home:/source -v $(pwd):/backup alpine tar -czf hermes-backup.tar.gz -C /source .

部署完成后，你得到的是：浏览器和手机随时能开的聊天入口（8787）、常驻的网关与定时任务、一个能看到资源与会话全貌的监控面板（9119），以及一份随时可以打包走的数据。

【免费下载链接】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