嵌入式C++实时内核设计与优化实践
2026/9/10 21:03:29
5 分钟跑通 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
想在浏览器或手机上随手指挥 Hermes Agent，Hermes WebUI Docker 部署是最省事的办法：不用装 Python 环境、不用纠结依赖，一个命令就能把整套服务跑起来。跟着走一遍，大约 5~10 分钟就能打开网页开始和 Agent 对话。
开始之前
你只需要两样东西：
- 一台能跑 Docker 的机器（Linux、macOS、装了 WSL2 的 Windows 都可以）
- Docker 本体 + Compose 插件（Docker Desktop 自带）
打开终端敲一条命令自检：
docker compose version能看到版本号就说明环境没问题；如果提示命令不存在，去 Docker 官网装一下 Docker Desktop 或 Docker Engine 再回来。
怎么选部署方式：三种容器方案对比
仓库里自带了三份 Compose 文件，对应三种玩法：
| 方案 | 适合谁 | 特点 |
|---|---|---|
单容器（docker-compose.yml） | 绝大多数个人用户 | 一个容器跑全部，从当前目录构建，配置最简单，权限问题最少 |
双容器（docker-compose.two-container.yml） | 想隔离 agent 和聊天界面的人 | agent 与 WebUI 分两个容器，用命名卷共享数据，镜像直接拉取不用构建 |
三容器（docker-compose.three-container.yml） | 还想盯监控面板的进阶用户 | 在双容器基础上多一个 Dashboard（9119 端口），可对 agent 做资源限额 |
拿不准就直接选第一个。单容器是最不容易出权限和路径问题的路径，后续想升级再换文件即可。
标准部署流程 🚀
下面按单容器模式走，全程在克隆下来的目录里操作。
1. 克隆仓库
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui成功后ls能看到docker-compose.yml和.env.docker.example。
2. 准备环境变量文件
cp .env.docker.example .env打开.env，把UID和GID改成你自己的值（终端敲id -u和id -g各取一个数填进去）。macOS 上用户 ID 从 501 开始，这一步必做。
⚠️ 易错提醒：UID/GID 填错是最常见的翻车点——容器会以这个 ID 读写你挂载的~/.hermes目录，对不上就会出现"Permission denied"或文件变成 root 所有。
3. 一条命令拉起
docker compose up -d首次运行会从当前目录构建镜像，需要几分钟，期间没有输出属正常现象。
4. 检查容器状态
docker compose ps看到hermes-webui一行显示Up且健康状态为 healthy，就说明服务起来了。
⚠️ 易错提醒：如果构建阶段报网络错误，多半是基础镜像拉取被墙或代理未生效，给 Docker 配好镜像加速后重新执行上一步即可。
值得知道的配置项
不用全看，这几个是真正影响日常使用的：
| 参数 | 默认值 | 什么时候改 |
|---|---|---|
UID/GID | 1000 | macOS 用户（多为 501）必改；Linux 一般默认就对 |
HERMES_HOME | ~/.hermes | 你的配置、会话、状态实际存在哪，就指到哪；默认不用动 |
HERMES_WORKSPACE | ~/workspace | 想让 Agent 操作你的代码目录时，改成对应路径 |
HERMES_WEBUI_PASSWORD | 空（无密码） | 只要端口要暴露给 127.0.0.1 以外，就必须设置，否则等于裸奔 |
API_SERVER_KEY | 空 | 双/三容器模式下想让 WebUI 探测到 gateway 时才需要，16 位以上随机串 |
顺带一句原理：卷挂载就像把数据放进一块不会随容器删除而丢的外置硬盘，~/.hermes和 workspace 就是这两块"硬盘"。
怎么确认它跑起来了
命令行层面已经用docker compose ps确认过了，再看一眼浏览器：打开http://localhost:8787，出现登录或直接进入会话页，就算彻底跑通。
界面分三块，各管一摊事：
- 左侧边栏：会话列表和模型选择器，新对话、置顶、切换 profile 都在这里
- 中间聊天区：你和 Agent 的对话，工具调用会以可折叠的卡片形式内联展示
- 右侧工作区面板：直接浏览、管理你在
HERMES_WORKSPACE里挂载的文件
想验证 Agent 真的能干活，可以丢一句"列出当前 workspace 下的文件"，右侧面板里出现的文件清单就是活证据。
出问题先查这几种
1. 端口被占用
- 现象：
docker compose up -d报port is already allocated，浏览器也打不开 - 排查：
sudo lsof -i :8787看谁占着 - 修复：把 compose 里的端口映射改成
"127.0.0.1:8888:8787"这种形式，容器端口不动，换掉主机侧端口，再docker compose up -d重建
2. 权限被拒（Permission denied / 文件读不到）
- 现象：容器反复重启，日志里大量 permission 报错，或
.hermes里的文件变成 root 属主 - 排查：
docker logs hermes-webui找具体报错路径，再id -u对照.env里的UID - 修复：把
.env里的 UID/GID 改成宿主机真实值后重建；macOS 用户尤其注意这一步。多容器模式遇到此问题，官方建议退回单容器或保持命名卷用法，详见 docs/docker.md
3. 容器起不来或反复重启
- 现象：
docker compose ps里状态是Restarting或Exit 1 - 排查：
docker compose logs -f hermes-webui看最后几行真实报错 - 修复：构建失败一般是基础镜像没拉下来，
docker compose up -d --build重来一次；启动即崩且日志指向挂载路径，9 成是 UID 问题，回到上一条处理
最后
到这里，一台干净机器上 5 分钟就能拥有一个能对话、能管文件的 Hermes Agent 网页端。数据落在挂载的卷里，容器随时可删可重建——这正是容器化部署的全部价值。
【免费下载链接】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），仅供参考