写在前面
这是 Hermes Agent 架构系列的第二篇,讲最底下的部署层。整体分层见 Hermes Agent 自托管架构总览。
部署层要解决三件事:进程长期在线、数据不随容器丢失、有一个能看状态的管理界面。Hermes 官方镜像已经把大部分事情做好了,自己要做的主要是挂好数据目录、配好 Dashboard 认证。
本文环境:Hermes Agent v0.23.0,官方镜像 nousresearch/hermes-agent:latest,服务器在内网。
Compose 配置
我的 docker-compose.yaml 放在 /usr/local/svc/hermes:
| |
逐项说明:
| 配置 | 作用 |
|---|---|
network_mode: host | 网关、Dashboard、api_server 直接用宿主机端口,不用逐个映射 |
./data:/opt/data | 容器内 HERMES_HOME 就是 /opt/data,所有状态都落在宿主机 |
/data/work:/data/work:ro | 只读挂载工作目录,Agent 能读代码和资料,但改不了宿主机文件 |
TZ=Asia/Shanghai | Cron 表达式和会话每日重置都按本地时间计算 |
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/ | 407M | Agent 执行命令时的家目录 |
tools/ | 267M | 工具运行时,包括 Playwright 浏览器 |
state.db | 259M | 会话、消息、全文检索等核心状态(SQLite) |
logs/ | 30M | 网关、Agent、错误日志 |
另外几个体积不大但很重要的文件:
config.yaml:主配置.env:密钥和平台凭证,权限是600SOUL.md:默认 Profile 的人设memories/:长期记忆MEMORY.md和用户画像USER.mdcron/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。改坏配置后可以从这里找回上一个能用的版本。
升级相关配置:
| |
用 Docker 部署时,升级就是拉取新镜像后重建容器:
| |
我跟的是 latest 标签,升级方便,但要接受上游行为变化直接生效。比如 v2026.9.11 移除了按时间自动切换会话的能力,升级后配置还在,功能却没了(后来用插件补回来了,见扩展篇)。重要环境建议固定版本标签,升级前先看更新说明。
我的做法是手动升级:想升级时执行上面两条命令,升级前不额外备份 data/。数据目录挂载在宿主机上,重建容器不会删除它;配置改坏了,还可以从 backups/config/ 的快照里找回。
踩坑:不需要自建镜像装浏览器
最早我以为官方镜像没有浏览器,写了一个 Dockerfile 基于官方镜像安装 Chromium 和中文字体:
| |
后来发现完全多余:官方镜像已经内置 Playwright,容器里设置了 PLAYWRIGHT_BROWSERS_PATH,浏览器放在数据目录的 tools/playwright-browsers 下,Agent 的浏览器工具开箱即用。
自建镜像的代价也很实在:每次上游更新都要重新构建,docker compose pull 拉不到新版本。现在 compose 里直接使用官方镜像,那个 Dockerfile 已经弃用。
结论:先确认官方镜像里有没有,再决定要不要自己构建。 检查方法:
| |
总结
- 部署只需要一个容器:官方镜像 + 数据目录挂载 +
gateway run。 - s6 负责初始化和进程守护,不要覆盖入口。
/opt/data就是全部状态,备份它,并注意state.db的 WAL 文件。- Dashboard 很好用,但认证和暴露范围要自己把关。
下一篇讲模型层:怎么接入自建的模型网关,以及如何按任务给主模型和辅助模型分工。
