Hermes 实例重建手册 🔄

Hermes 实例重建手册

版本: 1.0 | 更新日期: 2026-05-16 | 基准实例: Oracle H02

📑 两种重建路径

重建当前 Hermes 实例有两种方法，适用于不同场景：

	方法一：配置法	方法二：目录映射法
核心	只用 `./data:/opt/data` 其余全走 Hermes 默认	复制整份 `./data` 和 `./www` 启动即完全一致
目录定义	零自定义	完全保留旧实例目录
恢复方式	上线后用聊天指令逐个组件恢复	上线即完全恢复
适用场景	迁移到新环境、标准化重建、旧实例有目录污染	原地恢复、备份还原、快速克隆
耗时	约 30 分钟（聊天逐项恢复）	约 5 分钟（文件复制 + 启动）

方法一：配置法（纯默认路径）

步骤 1：docker-compose.yml

services:
  hermes:
    image: nousresearch/hermes-agent:v2026.5.7
    volumes:
      - ./data:/opt/data                           # 唯一的 volume 映射
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
    restart: unless-stopped

关键约束：

没有 ./www 或其他额外映射
没有 HERMES_WORKSPACE_DIR 等环境变量
后续所有组件安装使用 Hermes 默认路径

步骤 2：首次启动

docker compose up -d
# 空 volume → 入口脚本生成 config.yaml, .env, sessions/, skills/, state.db 等
# 几秒后容器就绪

查看生成的默认文件：

docker compose stop
# 查看 ./data/config.yaml 和 ./data/.env

步骤 3：修改 config.yaml 和 .env

只改需要改的字段，其他保持默认：

# ⚙️ config.yaml — 此行以下保持原样，以下以当前 Oracle H02 示例

model:
  default: deepseek-v4-flash
  provider: opencode-go
  base_url: https://opencode.ai/zen/go/v1
  api_key: ${OPENCODE_GO_API_KEY}

telegram:
  reactions: false

terminal:
  cwd: /opt/data/home           # 不加也行，容器默认 HOME

# 🔑 .env — 仅填真实使用的 token
TELEGRAM_BOT_TOKEN=...
OPENCODE_GO_API_KEY=...
TRILIUM_ETAPI_TOKEN=...
TRILIUM_ETAPI_URL=https://trilium.atibm.com/etapi
V100_API_KEY=...

步骤 4：第二次启动

docker compose up -d
# 此时 Hermes 是用 Telegram 连接，可以接收命令

步骤 5：聊天逐项恢复组件

以下所有操作通过 Telegram 聊天向 Hermes 发送指令完成。

5.1 注册 MCP 服务器

Trilium MCP：

[at c] 安装 Trilium MCP
npm install /opt/data/home/trilium-mcp
# 编辑 config.yaml 添加 mcp_servers.trilium

PinchTab MCP：

[at c] 安装 PinchTab
mkdir -p /opt/data/tools/pinchtab
cd /opt/data/tools/pinchtab && npm init -y && npm install pinchtab
# 编辑 config.yaml 注册 mcp_servers.pinchtab
# 编辑 ~/.pinchtab/config.json 设置 allowedDomains 和 browser.binary

实际聊天命令：

[at c] 安装 pinchtab，配置 mcp，允许所有域名，浏览器用 Hermes 默认路径

5.2 恢复 gbrain 知识库

二进制和包：

[at c] 安装 gbrain
# gbrain 二进制通常事先放好到 /opt/data/home/bin/gbrain
# 数据库在 /opt/data/home/.gbrain/（volume 已自动恢复）
# 执行 gbrain doctor 验证

实际聊天命令：

[at c] 安装 gbrain，验证知识库完整性

5.3 恢复 cron 定时任务

cron job 定义 在 /opt/data/cron/jobs.json 中（volume 自动恢复），但 script 字段指向的脚本文件需要重建。

创建 cron 脚本目录（使用 Hermes 默认脚本位置）：

[at c] 创建以下 cron 脚本：
mkdir -p ~/.hermes/scripts
# 编写 hermes-cron-master.sh（主编排器）
# 编写 gbrain-daily-dream/run.sh
# 编写 sitemap-auto-update/run.sh
# 编写 tasks.conf
# 编写 lib/report.sh

实际聊天命令：

[at c] 重建 cron master：脚本放 ~/.hermes/scripts/，所有路径用绝对路径硬编码，日报输出到 /opt/data/home/cron/runreport/

5.4 检查 cron job 定义

[at c] 列出目前所有 cron
# 确认 hermes-cron-master 存在且 schedule=0 1 * * *
# 如果不存在则重新创建

5.5 配置 Trilium sitemap

[at c] 配置 Trilium sitemap cron 脚本，每天 4 点更新

5.6 验证组件运行

[at c] 测试手动触发 cron
# sitemap 手动执行：排查 sitemap.xml 是否可访问

[at c] 测试 MCP 工具
# 确认 trilium MCP 和 pinchtab MCP 可用

[at c] 检查 gbrain 状态
# gbrain doctor 确认知识库正常

方法一恢复清单

组件	自动恢复（来自 volume）	需聊天命令重建
config.yaml	已修改的文件在 volume 中	—
.env	已修改的文件在 volume 中	—
Skills	`/opt/data/skills/`	—
Sessions / Memories	`/opt/data/sessions/` `/opt/data/memories/`	—
Cron 定义	`/opt/data/cron/jobs.json`	脚本文件放到 `~/.hermes/scripts/`
Trilium MCP	`/opt/data/home/trilium-mcp/`	config.yaml 加 `mcp_servers.trilium`
PinchTab	—	npm install + config.yaml + pinchtab config
gbrain 数据库	`/opt/data/home/.gbrain/`	gbrain 二进制 + gbrain init
gbrain 包目录	`/opt/data/home/gbrain/`	—
SOUL.md	volume 中	—

方法二：目录映射法（完全一致克隆）

步骤 1：docker-compose.yml

与旧实例完全相同的 docker-compose.yml：

services:
  hermes:
    image: nousresearch/hermes-agent:v2026.5.7
    volumes:
      - ./data:/opt/data
      - ./www:/www
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - HERMES_WORKSPACE_DIR=/www
    restart: unless-stopped

步骤 2：复制数据目录

# 从旧实例打包
tar czf hermes-backup.tar.gz \
  ./data \
  ./www

# 传到新机器，解压
tar xzf hermes-backup.tar.gz
# 确认目录结构：
# ./data/  → 映射到 /opt/data
# ./www/   → 映射到 /www

建议排除的运行时产物：

--exclude='data/gateway.lock' \
--exclude='data/gateway.pid' \
--exclude='data/state.db-wal' \
--exclude='data/state.db-shm' \
--exclude='data/memory_store.db-wal' \
--exclude='data/memory_store.db-shm' \
--exclude='data/response_store.db-wal' \
--exclude='data/response_store.db-shm' \
--exclude='data/*.lock' \
--exclude='data/home/.cache' \
--exclude='data/home/.local' \
--exclude='data/home/.npm' \
--exclude='data/cache' \
--exclude='data/.local' \
--exclude='data/bin'

步骤 3：启动

docker compose up -d
# 完全一致，所有组件即刻可用

方法二自动恢复的组件

组件	路径	状态
config.yaml	`/opt/data/config.yaml`	✅ 完全一致
.env	`/opt/data/.env`	✅ 完全一致
Skills	`/opt/data/skills/`	✅ 完全一致
Sessions	`/opt/data/sessions/`	✅ 完全一致
Memories	`/opt/data/memories/`	✅ 完全一致
Cron 定义	`/opt/data/cron/jobs.json`	✅ 完全一致
Cron 脚本	`/www/kc-ai-hermes/cron/`	✅ 完全一致
Trilium MCP	`/opt/data/home/trilium-mcp/`	✅ 完全一致
PinchTab	`/www/kc-ai-hermes/pinchtab/`	✅ 完全一致
gbrain	`/opt/data/home/.gbrain/` + `/opt/data/home/gbrain/`	✅ 完全一致
Cron symlink	`~/.hermes/scripts/hermes-cron-master.sh`	⚠️ 注意：在 volume 外，需手动重建符号链接
pm/pip 缓存	`/opt/data/home/.npm/` `/opt/data/home/.cache/` `/opt/data/home/.local/`	⚠️ 缓存可选，不恢复不影响功能

⚠️ 方法二唯一需手动修复：cron symlink

# 容器启动后执行：
ln -sf /www/kc-ai-hermes/cron/run.sh ~/.hermes/scripts/hermes-cron-master.sh

# 或通过聊天命令：
[at c] 恢复 cron symlink

两方法对照：组件层级

层级	包含	方法一	方法二
L0 配置	`config.yaml` `.env`	volume 自动恢复	volume 自动恢复
L1 核心数据	`sessions/` `memories/` `skills/` `state.db`	volume 自动恢复	volume 自动恢复
L2 附加工具	gbrain、trilium-mcp、pinchtab	聊天逐个安装	volume + /www 自动恢复
L3 定时任务	cron jobs.json + 脚本	定义自动恢复，脚本聊天重建	完全自动恢复
L4 缓存	.npm、.cache、.local	—	volume 自动恢复（可选）

Oracle H02 实例快照

当前组件清单

组件	版本/配置	备注
Hermes 引擎	v2026.5.7	Docker image
Model	deepseek-v4-flash @ opencode-go	500K context
Telegram	Oracle H02 Group (-1003995375876)	主接入通道
gbrain	0.30.2, PGLite	1240 pages
Trilium MCP	/opt/data/home/trilium-mcp/	ETAPI at trilium.atibm.com
PinchTab	0.12.0 at /www/kc-ai-hermes/pinchtab/	MCP registered
Cron Master	01:00 daily	no_agent mode
Cron gbrain	顺序 #1, timeout 600s	gbrain dream --pull --json
Cron sitemap	顺序 #2, timeout 120s	Trilium sitemap update
Sitemap 缓存	/tmp/sitemap-latest.xml	~90KB, 519 URLs
Cron 日报	/www/kc-ai-hermes/cron/runreport/	Markdown 格式

重建对照

如果你的实例缺少…	用方法一	用方法二
旧实例有 /www 目录映射	忽略，走默认路径	保留 /www 映射
旧实例自定义了 terminal.cwd	不设置，用默认	保留原 config.yaml 即可
旧实例 gbrain 在 .gbrain/	volume 自动恢复	volume 自动恢复
旧实例有复杂 cron 脚本	聊天逐一重建脚本内容	脚本文件在 /www 中自动恢复

— 本文档由 Hermes Agent 维护于 Trilium