Featured image of post Hermes Agent 部署篇:Docker Compose、数据目录与 Dashboard

Hermes Agent 部署篇:Docker Compose、数据目录与 Dashboard

讲解用官方 Docker 镜像长期运行 Hermes Agent 的部署方式,包括 Compose 配置、s6 进程守护链、/opt/data 数据目录结构与体积分布、Dashboard 登录认证、配置备份和升级注意事项,以及自建镜像安装浏览器的多余操作。

-- 次浏览
-- 条评论

写在前面

这是 Hermes Agent 架构系列的第二篇,讲最底下的部署层。整体分层见 Hermes Agent 自托管架构总览。

部署层要解决三件事:进程长期在线、数据不随容器丢失、有一个能看状态的管理界面。Hermes 官方镜像已经把大部分事情做好了,自己要做的主要是挂好数据目录、配好 Dashboard 认证。

本文环境:Hermes Agent v0.23.0,官方镜像 nousresearch/hermes-agent:latest,服务器在内网。

Compose 配置

我的 docker-compose.yaml 放在 /usr/local/svc/hermes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    network_mode: host

    volumes:
      - ./data:/opt/data
      - /data/work:/data/work:ro

    environment:
      - TZ=Asia/Shanghai

      # Dashboard
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_HOST=0.0.0.0
      - HERMES_DASHBOARD_PORT=9119

      # Dashboard 登录认证
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=<your-username>
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=<your-password>
      - HERMES_DASHBOARD_BASIC_AUTH_SECRET=<random-secret>

    command: ["gateway", "run"]

逐项说明:

配置作用
network_mode: host网关、Dashboard、api_server 直接用宿主机端口,不用逐个映射
./data:/opt/data容器内 HERMES_HOME 就是 /opt/data,所有状态都落在宿主机
/data/work:/data/work:ro只读挂载工作目录,Agent 能读代码和资料,但改不了宿主机文件
TZ=Asia/ShanghaiCron 表达式和会话每日重置都按本地时间计算
HERMES_DASHBOARD=1在同一个容器里顺带启动 Dashboard
command: ["gateway", "run"]容器以网关模式常驻,接收各聊天平台消息

和官方仓库里的 docker-compose.yml 相比,主要区别有三点:

  • 官方示例是本地 build,并挂载 ~/.hermes;我直接用发布的镜像,数据放在服务目录下,方便和其他服务统一管理。
  • 官方示例通过 HERMES_UID / HERMES_GID 把容器内用户映射成宿主机用户。我没设置,容器内进程使用默认的 10000 用户,所以宿主机上 data/ 的属主也是 10000。
  • 官方建议 Dashboard 只绑定 127.0.0.1,远程访问走 SSH 隧道或带认证的反向代理。我的服务器只在内网,才直接监听 0.0.0.0 并只加 Basic Auth。公网服务器不要照抄这一点。

容器里是怎么启动的

镜像的入口是 /opt/hermes/docker/entrypoint-dispatch.sh。它判断自己是不是 PID 1:正常 Docker 环境下会交给 s6-overlay 的 /init,由 s6 负责后续的初始化和进程守护。

这条链路带来两个实际影响:

  • 不要随便覆盖 entrypoint。官方 compose 注释写得很明确:/init 必须是第一条命令,它负责执行 cont-init.d 中的权限修正、Profile 校正等初始化脚本。绕过它,网关不能正常工作。
  • 进程挂了不用手动重启。网关由 s6 守护,异常退出会被重新拉起;restart: unless-stopped 只负责整个容器层面的重启。

用 docker exec hermes ps aux 能看到 s6-supervise 和以 10000 用户运行的 Python 网关进程。

数据目录结构

/opt/data(宿主机上的 ./data)就是 Hermes 的全部家当。跑了三个月后,我的数据目录是 7.8G,主要构成如下:

路径体积内容
cache/2.8G各类缓存,可以清理
profiles/2.5G每个 Profile 的独立数据,结构和根目录类似
skills/689M默认 Profile 的技能
lazy-packages/456M按需安装的 Python 依赖,例如语音识别用的 faster_whisper
home/407MAgent 执行命令时的家目录
tools/267M工具运行时,包括 Playwright 浏览器
state.db259M会话、消息、全文检索等核心状态(SQLite)
logs/30M网关、Agent、错误日志

另外几个体积不大但很重要的文件:

  • config.yaml:主配置
  • .env:密钥和平台凭证,权限是 600
  • SOUL.md:默认 Profile 的人设
  • memories/:长期记忆 MEMORY.md 和用户画像 USER.md
  • cron/jobs.json:定时任务定义
  • plugins/:插件

state.db 使用 WAL 模式(database.journal_mode: wal),所以旁边总会有 state.db-wal 和 state.db-shm。备份时不要只拷贝 state.db 一个文件,最好停容器后整体备份,或者用 SQLite 的在线备份命令。

排查问题时最常看的是 logs/ 下的这几个:

  • gateway.log:平台连接和消息收发
  • agent.log:对话和工具调用过程
  • errors.log:所有错误汇总

Dashboard

Dashboard 和网关跑在同一个容器里,由 HERMES_DASHBOARD=1 打开。它能查看会话、模型用量、Cron 任务和配置,日常检查很方便。

认证使用 Basic Auth,需要三个环境变量:用户名、密码和用于签发登录态的 SECRET。首次启动后,config.yaml 的 dashboard.basic_auth 里只会保存密码哈希,不保存明文。

Dashboard 能看到所有对话和配置,它的暴露范围要和这些数据的敏感程度相匹配。

备份与升级

Hermes 在修改配置时会自动留存快照,位置在 backups/config/,文件名类似 config.yaml.good.20261118-100122。改坏配置后可以从这里找回上一个能用的版本。

升级相关配置:

1
2
3
4
updates:
  pre_update_backup: false
  backup_keep: 5
  non_interactive_local_changes: stash

用 Docker 部署时,升级就是拉取新镜像后重建容器:

1
2
3
cd /usr/local/svc/hermes
docker compose pull
docker compose up -d

我跟的是 latest 标签,升级方便,但要接受上游行为变化直接生效。比如 v2026.9.11 移除了按时间自动切换会话的能力,升级后配置还在,功能却没了(后来用插件补回来了,见扩展篇)。重要环境建议固定版本标签,升级前先看更新说明。

我的做法是手动升级:想升级时执行上面两条命令,升级前不额外备份 data/。数据目录挂载在宿主机上,重建容器不会删除它;配置改坏了,还可以从 backups/config/ 的快照里找回。

踩坑:不需要自建镜像装浏览器

最早我以为官方镜像没有浏览器,写了一个 Dockerfile 基于官方镜像安装 Chromium 和中文字体:

1
2
3
4
5
6
7
FROM nousresearch/hermes-agent:latest
USER root
RUN apt-get update \
    && apt-get install -y --no-install-recommends \
      chromium chromium-driver fonts-noto-cjk \
    && rm -rf /var/lib/apt/lists/*
USER hermes

后来发现完全多余:官方镜像已经内置 Playwright,容器里设置了 PLAYWRIGHT_BROWSERS_PATH,浏览器放在数据目录的 tools/playwright-browsers 下,Agent 的浏览器工具开箱即用。

自建镜像的代价也很实在:每次上游更新都要重新构建,docker compose pull 拉不到新版本。现在 compose 里直接使用官方镜像,那个 Dockerfile 已经弃用。

结论:先确认官方镜像里有没有,再决定要不要自己构建。 检查方法:

1
docker exec hermes sh -c 'echo $PLAYWRIGHT_BROWSERS_PATH; ls $PLAYWRIGHT_BROWSERS_PATH'

总结

  • 部署只需要一个容器:官方镜像 + 数据目录挂载 + gateway run。
  • s6 负责初始化和进程守护,不要覆盖入口。
  • /opt/data 就是全部状态,备份它,并注意 state.db 的 WAL 文件。
  • Dashboard 很好用,但认证和暴露范围要自己把关。

下一篇讲模型层:怎么接入自建的模型网关,以及如何按任务给主模型和辅助模型分工。