如何 5 分钟用 Docker 部署 Hermes WebUI：三种容器模式完整指南
【免费下载链接】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 部署就是最省事的路子：用 Docker Compose 把 Hermes WebUI 装进一个容器，它就是 Hermes Agent 的网页入口，负责会话、聊天和工作区管理。
5 分钟从零到可访问
先花 10 秒确认环境里装了 Docker 和 Compose 工具：
docker --version docker compose version两条命令都能输出版本号就够用了。接着克隆仓库并启动容器：
git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui docker compose up -d这里默认走单容器模式：一个 WebUI 容器把 agent 一并跑起来（agent 就是替你执行任务的 AI 程序）。首次启动会自动构建镜像，多等几分钟很正常。
想改端口或密码也不用改 YAML，把模板拷一份再编辑即可：
cp .env.docker.example .env浏览器打开http://localhost:8787，能看到会话列表和聊天框，就说明部署成功：
一步确认成功
docker compose ps判定标准只有一条：hermes-webui状态为Up，端口映射显示8787→8787。状态在restarting或exited，直接用下一节的命令查日志定位原因。
选对模式：三种容器化部署对比
部署跑通后再考虑选型，Hermes WebUI 提供了三套 Docker Compose 文件：
| 配置文件 | 容器组成 | 适合谁 | 一句话区别 |
|---|---|---|---|
| docker-compose.yml | 1 个 WebUI 容器 | 个人尝鲜、快速上手 | agent 和界面同容器，最省事 |
| docker-compose.two-container.yml | agent + webui | 想让两者故障互不拖累 | agent 独立成容器，经共享卷通信 |
| docker-compose.three-container.yml | agent + webui + dashboard | 需要独立监控面板 | 多一个 dashboard 容器 |
多数人用单容器模式就够了，升级时机见后文。
用 .env 定制：一行命令改默认端口
打开 .env，只有三个参数值得动：
| 参数 | 怎么取 / 怎么设 | 作用 |
|---|---|---|
UID/GID | 执行id -u、id -g把结果填进去 | 让容器内进程和宿主机同一身份，能读写挂载的目录 |
| 端口 | 把端口映射改成"127.0.0.1:8888:8787" | 换掉默认 8787，避开端口冲突 |
HERMES_WEBUI_PASSWORD | 填任意你记得住的字符串 | 给 WebUI 加登录密码，端口对外暴露时必填 |
改完保存，docker compose up -d重新加载即可生效。
两个关键挂载，数据不随容器消失
容器删了数据就没了，Docker 部署里靠卷挂载解决这个问题。Hermes WebUI 默认挂两个目录：
.hermes：会话、配置和状态数据的家，宿主机默认在~/.hermes；workspace：工作区文件，也就是聊天界面里浏览和编辑的项目文件，默认在~/.workspace同级的~/workspace。
两个路径都可以用环境变量改，不用动 compose 文件：
export HERMES_HOME=/data/hermes export HERMES_WORKSPACE=/data/my-workspace docker compose up -d什么时候才需要升级多容器
单容器能满足绝大多数个人场景，出现下面情况再考虑升级：
- 你已经在独立容器里跑 agent，或希望 agent 网关和 WebUI 故障互不影响，用双容器：
docker compose -f docker-compose.two-container.yml up -d- 还要一个独立的 dashboard 容器做监控管理，用三容器：
docker compose -f docker-compose.three-container.yml up -d⚠️ 避坑清单
权限报错（Permission denied）
- 现象：容器起不来，或读写挂载目录失败
- 原因：容器内 UID/GID 与宿主机用户不一致
- 解决：.env 写入
UID=$(id -u)、GID=$(id -g)的值，再docker compose up -d
端口被占用
- 现象：启动即报错，提示 8787 端口已绑定
- 原因：机器上已有程序占着 8787
- 解决：把 docker-compose.yml 的映射改为
"127.0.0.1:8888:8787"，改docker compose up -d后用http://localhost:8888访问
启动失败
- 现象：
docker compose ps显示restarting或exited - 原因：日志里写明了，多数是挂载目录权限或 .env 拼写问题
- 解决：
docker compose logs hermes-webui定位后，修复再docker compose up -d
维护速查
docker compose logs -f hermes-webui # 跟踪实时日志 docker compose down # 停止全部容器 git pull && docker compose down && docker compose up -d --build # 更新到最新代码并重建 docker system prune # 清理无用镜像和容器上手之后
界面分三个区域：左侧是会话列表和模型选择，中间是聊天框，支持文字输入和文件上传，右侧是工作区文件浏览器，项目的文件都从这里管理：
个人在笔记本上开一个，团队在同一台机器上共用一个，都是这条最短路径能覆盖的用法。
【免费下载链接】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），仅供参考
