企业官网建设流程全解析

Hermes WebUI Docker Compose 快速部署指南：5 分钟跑通 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

Hermes WebUI 是 Hermes Agent 的浏览器端界面，让你不用装命令行环境，就能在网页或手机上与 Agent 对话、管理会话、浏览工作区文件。本文带你用 Docker Compose 在约 5 分钟内完成部署并验证可用，不需要了解它的内部实现细节。

什么人适合用 Docker Compose 部署

• 你想在一台干净的机器上快速体验，不关心 Python 依赖和运行环境的细节；
• 你已有~/.hermes目录和 Agent 状态，希望容器直接复用宿主机上的数据；
• 你后续可能升级到多容器架构，现在先要一个能跑起来的最简版本。

项目提供了三套 Compose 配置：单容器（docker-compose.yml）、双容器（docker-compose.two-container.yml，Agent 与 WebUI 分离）、三容器（docker-compose.three-container.yml，再加独立 dashboard 监控）。推荐先从单容器开始，它是官方默认路径，权限问题最少；确认用顺手后，再按 README 中 Docker 一节的说明切换到多容器。

用一条命令确认环境就绪

部署前只需要确认两件事：Docker 和 Compose 能正常调用，以及你的宿主用户 ID（后面挂载目录要用）。执行：

docker --version && docker compose version && id -u && id -g

预期输出里能看到 Docker 版本号、Compose 版本，以及两个数字（UID 和 GID）。记下这两个数字，Linux 常见的是1000 1000，macOS 通常从501开始。如果前两条命令报错，说明 Docker 尚未安装或未启动，先按 Docker 官方文档装好再继续。

从克隆到启动的最短路径

在本地任选一个目录，把仓库拉下来并初始化配置文件：

git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui cp .env.docker.example .env

.env文件全部变量都可选，Linux 用户多数情况可以跳过编辑；macOS 用户需要把UID、GID改成上一步查到的值，否则容器可能读不了你挂载的目录。

然后启动容器：

docker compose up -d

这一步会先构建镜像，首次可能要等几分钟。完成后用docker compose ps查看状态，容器应处于Up且健康检查通过。注意请用拥有~/.hermes的那个普通用户执行 Compose 命令，用sudo会导致默认挂载路径指向 root 的家目录，WebUI 会加载不到你的配置。

用两个目录挂载保住你的数据

容器本身可以随时删掉重建，但里面未挂载的数据会一并丢失。单容器配置默认挂载了两个宿主机目录，这是你要重点理解的部分：

• ${HERMES_HOME:-${HOME}/.hermes}→ 容器内/home/hermeswebui/.hermes，存放会话记录、配置和运行状态；
• ${HERMES_WORKSPACE:-${HOME}/workspace}→ 容器内/workspace，即 WebUI 文件浏览器里看到的工作区。

如果你只想改存储位置，不用动 compose 文件，直接给.env加变量即可：

HERMES_HOME=/path/to/.hermes HERMES_WORKSPACE=/path/to/workspace UID=1000 GID=1000

若打算把端口开放到局域网（改掉默认的本机回环绑定），记得同时启用密码保护：

HERMES_WEBUI_PASSWORD=一个足够复杂的密码

打开页面，确认服务真正可用

启动成功后，在浏览器访问http://localhost:8787。页面正常加载、左侧会话列表和中间聊天区可见，即代表部署完成。界面主要由三块组成：左侧导航栏（会话管理与模型选择）、中间聊天区（输入、发送和文件上传）、右侧工作区面板（浏览和管理挂载的项目文件）。

不想打开浏览器时，也可以用健康检查接口验证：

curl http://127.0.0.1:8787/health

返回 200 就说明服务端在正常响应。

启动失败先看容器日志，维护也走这三个命令

绝大多数问题（权限报错、挂载目录为空、配置未加载）都能从日志里直接看出线索：

docker compose logs -f hermes-webui

常见的对应关系：出现PermissionError或.env: permission denied，多半是 UID/GID 没配对你的宿主用户，回到.env修正后重建容器；工作区面板显示为空，通常是 workspace 挂载目录的属主不匹配；8787 端口被占用，则修改 compose 里端口映射的宿主侧数字（如127.0.0.1:8888:8787）。

日常维护只需要三组命令：停止用docker compose down；升级到新版源码后执行git pull再重建（docker compose down加docker compose up -d --build）；需要查看渲染后的最终挂载和变量时用docker compose config。更深入的故障场景（Podman 兼容、bind-mount 迁移等）可阅读项目内的 docs/docker.md 与 docs/troubleshooting.md，以及 README.md 中 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