5 步部署指南：Hermes WebUI 用 Docker 最快启动方式
项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui Hermes WebUI 是 Hermes Agent 的浏览器入口，让你在电脑或手机上与 Agent 对话、管理会话和工作区文件。这篇文章带你用 Docker 完成 Hermes WebUI 部署并跑通第一个真实任务，全程 15–30 分钟。
30 秒判断：这篇适不适合你
- 你想在本机用 Docker 跑一套自用的 Hermes WebUI，看聊天界面就行：往下走，单容器方案够用。
- 你的定时任务需要后台网关常驻，或团队要隔离网关与界面：先看看仓库里的 docker-compose.two-container.yml 和 docker-compose.three-container.yml，那套编排更合适。
最快路径：从 0 到跑通的 5 步
第 1 步，确认 Docker 就绪。
docker --version && docker compose version
两条都输出版本号即过关。Linux 上若 compose 命令不存在，需先安装 Compose 插件。
第 2 步，拿到项目代码。
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui
cd hermes-webui
仓库自带 Dockerfile 和 compose 编排，无需额外安装任何依赖。
第 3 步，生成配置文件。
cp .env.docker.example .env
新手可以什么都不改直接进下一步，改配置的事放下一节再讲。
第 4 步，启动容器。
docker compose up -d
首次执行会构建镜像，耗时几分钟；看到 Started 字样即代表容器就绪。
第 5 步，双重确认。
docker compose ps
预期输出中 STATUS 列显示 Up。再打开浏览器访问 http://localhost:8787——看到左侧会话列表、中间对话区、右侧工作区文件树的三栏界面，就跑通了。
上图为部署成功后的主界面：会话列表、对话区与工作区面板同时出现，三栏齐全即代表 Hermes WebUI 部署成功。
把配置调对：3 个值得动手的地方
UID / GID：挂载目录权限问题的总根源。
容器内进程必须以和你宿主机相同的用户身份读写挂载目录，否则读不了你的配置、也写不进会话记录。在 .env 里改这两个值，Linux 用户通常就是 1000；macOS 用户 UID 一般从 501 起步，务必实测：
id -u && id -g
改完执行 docker compose up -d --force-recreate，确认日志里没有 Permission denied。
HERMES_WORKSPACE：把工作区指向你的真实项目目录。
默认挂载的是 ~/workspace，你的代码不在这就改这一项。在 .env 里取消注释并修改 HERMES_WORKSPACE 后重建容器，预期结果：右侧工作区面板直接列出你的项目文件树。
图中演示了工作区配置的预期效果：文件树按目录展开，文件可直接拖入对话区让 Agent 处理。
HERMES_WEBUI_PASSWORD：端口一旦出本机就必填。
只在 127.0.0.1 上访问可以暂不设；要把 Hermes WebUI 暴露给局域网或公网，必须先在 .env 中取消注释 HERMES_WEBUI_PASSWORD 并改成强密码，再重建容器。预期结果：访问首页先出现登录框，输错密码进不去。
让数据不丢
容器本身可以随便删，状态都在两个卷挂载里：~/.hermes 存会话、配置和状态，~/workspace 存项目文件，删容器重建数据原样回来。备份一条命令就够：
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes
建议配个每周任务自动跑，再把备份文件放到另一块磁盘。
出了问题怎么办：3 个高频故障
| 现象 | 原因 | 一条修复命令 |
|---|---|---|
启动报 port is already allocated | 8787 端口被占用 | 把 docker-compose.yml 端口映射改成 127.0.0.1:8888:8787，再 docker compose up -d |
| 挂载目录无读写权限、会话存不进 | .env 的 UID/GID 与宿主机不一致 | 按上一节修正 .env 后执行 docker compose up -d --force-recreate |
Linux 上 sudo 启动后 WebUI 读不到 ~/.hermes | ${HOME} 被展开成 /root，挂错了目录 | 用 sudo -E docker compose up -d，或改用普通用户并在 .env 里写绝对路径 |
更细的排查流程见 docs/troubleshooting.md。
什么时候需要升级
个人自用单容器就到这里，先跑通再谈优化。判断标准只有一个：你需要定时任务在无人值守时后台执行——单容器里网关守护进程无法独立常驻。团队部署直接换双容器编排，一条命令切换：
docker compose -f docker-compose.two-container.yml up -d
两种架构的差异、升级时卷的处理细节，都写在 docs/docker.md 里。
部署完立刻做的第一件事
新建一个对话，问 Hermes："当前工作区里有哪些文件？" 右侧面板会同步展示文件树——这就验证了文件与对话的联动。接着把任意一个文件拖进对话区，让它总结内容。30 秒，你得到的不是一个"能打开的网页"，而是一个真正干活的助手。
现在就打开浏览器，跑起来。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
