Hermes WebUI Docker 部署教程：15 分钟跑通并学会数据备份

Hermes WebUI Docker 部署教程：15 分钟跑通并学会数据备份

【免费下载链接】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 助手入口：办公室打开浏览器就能对话，路上掏手机也能接着问。选中的就是 Hermes WebUI——按本文走一遍 Hermes WebUI 的 Docker 部署，大约 15 分钟，不用配 Python 环境，最后你手里是一个能在浏览器和手机上打开的助手页面，以及一套随时可恢复的数据。

花一分钟看懂 Hermes WebUI

Hermes WebUI 是 Hermes Agent 的浏览器端界面，用 Python 编写，跑起来后是一个三栏页面：左边是会话列表，中间是和 Agent 对话的区域，右边是能预览、拖拽、整理文件的工作区。手动安装时，Python 版本、依赖包、端口占用都要你自己处理；容器路线则把整个运行时锁在镜像里，你只需要维护一份编排文件，所以本文全程走 Docker。

Hermes WebUI 最快启动方法 ⏱️

跑起来之前先过三道检查：

• Docker：docker --version，输出一行版本号即合格。
• Compose 插件：docker compose version，同样输出一行版本号才算过关；Linux 上若提示找不到命令，需要单独安装。
• 代码：克隆到本地。

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

预期输出：无报错，当前目录切换进 hermes-webui。

接着生成配置文件，填入你的用户身份和（可选的）自定义路径：

cp .env.docker.example .env echo "UID=$(id -u)" >> .env && echo "GID=$(id -g)" >> .env echo "HERMES_HOME=/data/hermes/config" >> .env

预期输出：仓库根目录出现 .env。id -u和id -g各输出一个数字，直接写进去；HERMES_HOME 一行只在你想把数据放到非默认位置时保留。

现在一条命令启动：

docker compose up -d

预期输出：首次构建镜像需要几分钟，结束后提示容器已启动（Started / Up）。打开浏览器访问http://localhost:8787，看到会话列表、对话区、工作区三栏齐全才算部署成功。

如果页面一直转圈，先执行这一条看实时日志：

docker compose logs -f hermes-webui

预期输出：日志持续滚动，最后一行停在服务监听 8787 端口的信息；看到反复退出的记录，就说明容器没起来，报错原因就在屏幕最下方。

图为 Hermes WebUI 启动后的主界面：三栏同时出现即代表部署成功。

Hermes WebUI 数据备份怎么做 💾

删掉容器数据不会丢，因为两个目录都落在宿主机上：${HERMES_HOME}（默认~/.hermes）存会话记录、配置与系统状态，对应左侧列表和中间对话区；${HERMES_WORKSPACE}（默认~/workspace）存项目文件，对应右侧文件面板。想换位置时，在.env里覆盖这两个变量再启动即可：

echo "HERMES_HOME=/data/hermes/config" >> .env echo "HERMES_WORKSPACE=/data/projects" >> .env

预期输出：docker compose up -d之后，新会话与新文件都出现在你指定的两个目录里。

备份只需一条带日期命名的命令：

tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes/

预期输出：当前目录生成一个带今天日期的 .tar.gz 文件，且体积大于 0。建议每周执行一次（配个定时任务），备份文件放到另一块磁盘，才算完成最基本的异地保护。

图中右侧面板即工作区，文件树展示的就是挂载进来的HERMES_WORKSPACE目录。

服务不对劲时先查哪里 🩺

先看频率最高的四条日常操作：docker compose ps看容器状态与端口映射，容器显示 Up 即正常；docker compose logs -f hermes-webui实时看日志；docker compose down优雅停服，数据卷原样保留；升级时执行下面两条，服务会短暂中断，挑低峰期做。

git pull docker compose down && docker compose up -d --build

预期输出：重建完成、docker compose ps再次显示 Up，且浏览器能正常打开。

再对号入座三个高频症状：

• 启动时报端口冲突 → 8787 被占用 → 把docker-compose.yml的 ports 左侧改成空闲端口（如127.0.0.1:8888:8787），容器内右侧的 8787 不动。
• 页面能开但保存失败、目录里没有新文件 → UID/GID 与宿主机不一致 → 回.env核对id -u/id -g的真实输出，重启容器。
• 对话中弹出 429 限流卡片 → 服务商额度用尽 → 按卡片指引充值、等待额度重置或切换服务商，展开卡片还能看到 HTTP 状态码等细节。

图中错误提示直接说明失败原因并带一键复制按钮，排查时可直接带上这段上下文。

Hermes WebUI 多人使用与生产环境加固 🔐

多人共用或对外暴露端口前，先补三件：资源上限、访问控制、定期回收。

给docker-compose.yml的hermes-webui服务下加几行，防止异常进程吃满宿主机：

deploy: resources: limits: memory: 2G cpus: '1.0'

预期输出：docker stats中该容器占用不会突破你设的上限。

访问控制必须同时满足两条：.env里设置HERMES_WEBUI_PASSWORD，且 ports 保留127.0.0.1前缀。如果不给暴露的端口设密码，等于把终端执行权限交给了网络上的陌生人。

磁盘回收每月一次：docker system prune -a --volumes。预期输出：提示回收了未使用的镜像与卷；执行前确认没有正在使用的容器。

进阶方面，仓库预置了两套多容器编排，满足条件才升级：需要把后台网关（CLI、定时任务）与聊天界面隔离，就选双容器；还要一块看系统状态与资源占用的监控面板，才需要三容器。

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

预期输出：docker compose -f docker-compose.two-container.yml ps里两个服务都是 running，浏览器依旧能从 8787 访问。排障面会变大，新手先用单容器验证功能。

部署完成后先做两件事

新建一个会话，问它"当前工作区里有哪些文件"，确认右侧面板和你的项目目录联动。再拖一个文件进对话，让它总结内容，顺便用顶部搜索把这次会话找回来。

需要深入时看这三处：docs/docker.md（三种编排怎么选、常见失败模式）、docs/troubleshooting.md（按症状查诊断步骤）、docs/why-hermes.md（想了解设计取舍时）。

打开浏览器，把第一个会话跑起来。

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