Hermes Agent 的 Docker 部署和升级方案

什么是 Hermes Agent

Hermes Agent 是 Nous Research 开发的开源 AI Agent 框架。它可以在终端、聊天平台（Telegram / Discord / 飞书等）和 IDE 中运行，支持 15+ 模型提供商（OpenRouter、Anthropic、OpenAI、DeepSeek 等），并具备自我学习能力——它会从经验中沉淀技能、在使用中持续改进。

与 Claude Code、OpenAI Codex 等同类工具相比，Hermes 最大的特色是 内置学习回路：跨会话记忆、历史对话检索、自动技能沉淀，让它越用越懂你。

为什么选 Docker 部署

Docker 是 Hermes Agent 的一等公民部署方式。官方镜像基于 Debian 13.4，预装了 Python 3.13 + Node.js 22 + Playwright（Chromium）+ ripgrep + ffmpeg + git + docker-cli + openssh-client 等全套依赖，你不需要在宿主机上折腾 Python 版本和系统库。

Docker 部署的核心优势：

• 零环境依赖：镜像自带完整运行时，拉下来就能跑
• 升级简单：拉新镜像重建容器，数据目录不受影响
• 进程守护：s6-overlay 作为 PID 1，网关崩溃秒级自动重启
• 多 Profile 自然支持：一个容器托管多个独立 Agent，资源复用率高

部署前准备

• 一台安装了 Docker 24+ 的 Linux 服务器（macOS/WSL2 也支持）
• 最低 1 vCPU + 2 GB 内存（推荐 2 vCPU + 4 GB）
• 约 2 GB 磁盘用于镜像 + 数据卷增长
• 至少一个 LLM 提供商的 API Key（OpenAI / Anthropic / OpenRouter 等）

第一步：创建数据目录

容器内所有状态（配置、会话、记忆、技能）持久化到 /opt/data，映射到宿主机的 ~/.hermes/：

mkdir -p ~/.hermes

这个目录就是你的 Hermes 全部家当——备份它就是备份了整个 Agent。

第二步：首次运行——初始化配置

拉取镜像并运行交互式初始化向导：

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

💡 镜像加速：如果拉取 Docker Hub 速度慢，可以使用毫秒镜像加速服务，支持所有版本标签的高速拉取。

初始化向导会引导你设置：

• 默认 LLM 提供商和 API Key -（可选）Telegram / Discord 等聊天平台的 Bot Token -（可选）语音模式相关密钥

所有配置写入 ~/.hermes/.env，只跑一次即可。

第三步：启动网关模式

配置完毕后，以网关模式运行持久化容器：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

关键参数说明：

⚠️ 安全提示：8642 端口的 API 默认无鉴权。如果对公网暴露，务必前置 Nginx/Caddy 反向代理并加 HTTPS + Basic Auth，或通过 Tailscale/WireGuard 组网访问。

第四步：启用 Dashboard（可选）

Hermes 内置 Web 管理面板，启用后可通过浏览器查看会话、管理技能和监控状态：

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  -e HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin \
  -e HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=your_password \
  nousresearch/hermes-agent gateway run

Dashboard 的认证方式有三种：

第五步：Docker Compose 方案（推荐生产环境）

对于需要同时运行网关和 Dashboard 的场景，docker-compose.yml 更便于管理：

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "127.0.0.1:8642:8642"   # 网关 API（仅本地）
      - "127.0.0.1:9119:9119"   # Dashboard（仅本地）
    volumes:
      - ~/.hermes:/opt/data
    environment:
      - HERMES_DASHBOARD=1
      - HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
      - HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=your_password
      # 也可以把 API Key 以 env 方式传入，而不是 .env 文件：
      # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

docker compose up -d       # 启动
docker compose logs -f     # 查看日志

多 Profile 管理

Hermes 支持在一套安装中创建多个独立 Profile——每个 Profile 有独立的 SOUL（人格）、技能、记忆、会话和凭据，可以让一个容器同时运行多个不同角色的 Agent。

# 创建新 profile（自动注册 s6 网关服务）
docker exec hermes hermes profile create baibai

# 单独启动 / 停止 / 重启某个 profile 的网关
docker exec hermes hermes -p baibai gateway start
docker exec hermes hermes -p baibai gateway stop
docker exec hermes hermes -p baibai gateway restart

# 查看 gateway 状态
docker exec hermes hermes -p baibai gateway status

# 删除 profile
docker exec hermes hermes profile delete baibai

架构亮点：

• 每个 Profile 由 s6-overlay 独立监督，崩溃自动重启
• 容器重启或镜像升级后，上次运行中的网关自动恢复
• 日志按 profile 独立轮转，存放在 ~/.hermes/logs/gateways/<name>/current
• 一个数据目录 ~/.hermes/ 统一备份，无需管理 N 个目录

资源限制建议

浏览器自动化（Playwright）最吃内存。如果不用 browser 工具，1 GB 足够；启用浏览器需至少 2 GB。

版本升级

Hermes 更新频繁——从 GitHub Releases 可以看到，版本迭代速度快、社区贡献活跃。升级流程非常简单：

方案一：docker 命令升级

# 1. 拉取最新镜像
docker pull nousresearch/hermes-agent:latest

# 2. 删除旧容器（数据目录不受影响）
docker rm -f hermes

# 3. 重新启动
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

方案二：Docker Compose 升级

docker compose pull
docker compose up -d

升级前建议：备份数据卷

docker run --rm \
  -v ~/.hermes:/opt/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/hermes-$(date +%F).tar.gz -C /opt/data .

升级机制详解

Hermes 容器启动时自动执行以下步骤，确保平滑过渡：

1. /etc/cont-init.d/01-hermes-setup：修复卷权限、种子化首次启动的配置文件、执行非交互式 config schema 迁移（自动备份旧 config）
2. /etc/cont-init.d/02-reconcile-profiles：遍历所有 Profile，为之前运行中的网关重建 s6 服务槽位并自动启动
3. s6-rc 启动 Dashboard（如果 HERMES_DASHBOARD=1）
4. 主进程启动：路由用户 CMD 参数

💡 无需手动迁移：config.yaml 的 schema 升级由容器启动流程自动完成，旧文件会生成带时间戳的备份。

生产环境建议：锁定版本标签

日常测试可以追 :latest，生产环境建议锁定具体版本：

services:
  hermes:
    image: nousresearch/hermes-agent:v2026.7.30   # 使用具体版本标签

这样升级是显式操作，避免自动拉取引入了不兼容变更。查看所有可用标签可访问 Docker 镜像加速页面。

常见问题

容器启动后立即退出

检查 docker logs hermes。常见原因：.env 缺少 API Key、config.yaml 语法错误、或数据目录权限不对。

“Permission denied” 错误

Hermes 容器内以 hermes 用户（UID 10000）运行。容器 boot hook 会自动 chown 数据目录，一般不需要手动处理。

网关断连不恢复

s6-supervise 会秒级自动重启崩溃的网关进程。如果持续异常，重启容器即可：

docker restart hermes

两个网关容器共享同一数据目录

绝对不要这样做。 会话文件和记忆存储不支持并发写入，会快速导致数据损坏。

总结

用 Docker 部署 Hermes Agent 的核心思路：一个数据卷打天下。镜像本身是无状态的，升级就是「拉新镜像 → 删旧容器 → 新建容器」，数据目录毫发无损。

关键命令速查：

# 初始化
docker run -it --rm -v ~/.hermes:/opt/data nousresearch/hermes-agent setup

# 运行网关
docker run -d --name hermes --restart unless-stopped \
  -v ~/.hermes:/opt/data -p 8642:8642 \
  nousresearch/hermes-agent gateway run

# 升级
docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
# ... 重新 docker run ...

# 备份
tar czf hermes-backup-$(date +%F).tar.gz -C ~/.hermes .

更多信息请参考：

• GitHub Releases · NousResearch/hermes-agent
• Docker 镜像加速 - nousresearch/hermes-agent
• 官方 Docker 部署文档