Hermes WebUI Docker部署教程：三步跑通，新手友好

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 WebUI 让你在浏览器或手机上直接使用 Hermes Agent。本文带你走通 Hermes WebUI Docker部署：一条命令拉起容器，.env 调端口和持久化挂载，三个常见坑一次解决。

Hermes WebUI Docker部署，三条命令跑通（Docker Compose 一键启动）

你只需要机器上装好 Docker 和 Compose。先确认环境没问题，两条命令都应能输出版本号：

docker --version docker compose version

哪条报错就按 Docker 官方文档补齐对应组件，装好回来继续。

接下来把代码拿下来，进到项目目录：

git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui

clone 完成后目录里已带好 docker-compose.yml，不用自己手写配置。

如果你什么都不想改，可以跳过 .env；想改端口或开密码，先复制一份模板出来：

cp .env.docker.example .env

然后启动容器，首次会现场构建镜像，给它几分钟：

docker compose up -d

命令返回后看一眼容器状态，STATUS显示Up就正常：

docker compose ps

最后打开浏览器访问 http://localhost:8787，页面出来即成功。

Hermes WebUI Docker部署按需调：改端口、开密码、数据持久化挂载

只想跑起来 → 本节整体跳过。下面是几个分支，命中哪个做哪个。

想改端口（比如 8787 被占）→ 编辑 docker-compose.yml，把ports里冒号前的宿主机端口换掉：

ports: - "127.0.0.1:8888:8787" # 宿主机端口改成 8888

改完docker compose up -d重跑一次即生效。

想开密码保护→ 在.env里写上密码。注意：只要端口放开到127.0.0.1之外，这一步就是必做项，省得陌生人拿到端口就能替你指挥 agent：

HERMES_WEBUI_PASSWORD=换成你的强密码

想让删容器时数据不丢→ compose 文件默认已挂好两个目录，不用额外操作：

volumes: - ${HERMES_HOME:-${HOME}/.hermes}:/home/hermeswebui/.hermes - ${HERMES_WORKSPACE:-${HOME}/workspace}:/workspace

• .hermes：会话、配置和状态数据，默认对应宿主机的~/.hermes
• workspace：WebUI 文件浏览器里展示的项目文件，默认对应~/workspace

目录不在默认位置的话，在.env里用环境变量覆盖即可，compose 文件不用动：

HERMES_HOME=/path/to/your/.hermes HERMES_WORKSPACE=/path/to/your/workspace

遇到文件权限报错→ 把容器的 UID/GID 对齐到宿主机用户。macOS 的用户 ID 从 501 开始，这一条基本必配：

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

升级选项：从双容器到三容器

单容器跑顺之后，想要更强隔离或监控，仓库里还有两份现成 compose 文件可以切换。

双容器（agent + webui）：把 agent 和 webui 拆成两个独立容器，适合想把 gateway 和聊天界面隔离开、或 agent 本来就在单独容器里跑的用户：

docker compose -f docker-compose.two-container.yml up -d

三容器（agent + webui + dashboard）：在双容器基础上多加一个 dashboard，看 agent 活动和资源占用，聊天仍在 http://localhost:8787，监控面板在 http://localhost:9119：

docker compose -f docker-compose.three-container.yml up -d

两种方案默认用命名卷，开箱即用。完整选型表和升级流程见 完整 Docker 文档。

📋 日常运维命令速查

日常维护基本就这四件事：

# 看实时日志，Ctrl+C 退出 docker compose logs -f hermes-webui # 停止并删除容器（挂载目录里的数据不受影响） docker compose down # 更新到最新代码并重建 git pull docker compose down docker compose up -d --build # 清理无用镜像和容器 docker system prune

down只删容器，宿主机的.hermes和workspace都还在，数据不会跟着丢。

⚠️ 常见坑速解：权限、端口冲突、启动失败

文件访问权限报错

• 症状：容器读挂载文件报Permission denied，或页面起不来
• 修复：.env里补上UID=$(id -u)和GID=$(id -g)，再docker compose up -d --build重建
• 验证：docker compose ps状态为Up，浏览器打开 8787 文件能正常读写

8787 端口冲突

• 症状：启动时报Bind for 127.0.0.1:8787 failed: port is already allocated
• 修复：docker-compose.yml 里把映射改成127.0.0.1:8888:8787（写法见上面改端口分支）
• 验证：浏览器访问 http://localhost:8888 页面能打开

启动失败或页面空白

• 症状：容器起不来，或起来后页面打不开
• 修复：docker compose logs hermes-webui看具体报错，排除后docker compose up -d重启
• 验证：日志里没有错误输出，页面正常加载

更多疑难杂症去 故障排查文档 里按图索骥。

跑起来之后：界面与功能一览

页面一共三个区域，分工很清晰：

• 左侧导航栏：会话管理和模型选择，随时切换会话
• 中央聊天区：文本输入和文件上传，直接跟 Hermes Agent 对话
• 右侧工作区面板：浏览、上传和管理项目文件

整个 Hermes WebUI Docker部署链路到这就齐了：三条命令跑起来，.env 管端口和密码，挂载管数据持久化。照抄命令即可，踩坑按速解对号入座。

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