电脑自习室
AI

Hermes Agent 备份与迁移教程：backup / import 一次搬走全部数据

使用 Hermes backup 和 import 在新机器上完整迁移 Hermes Agent，包括默认 profile、开发 profile、技能、记忆、配置、会话历史、env、auth 和 gateway 恢复注意事项。

Hermes Agent 自带 backup 和 import，适合把一台机器上的 Hermes 环境完整搬到另一台机器。它不是只导出一份配置文件，而是把 profile、技能、记忆、会话历史、认证状态和本地数据库一起打包。

如果你已经有一个默认助手和一个开发助手，例如默认 profile 用来日常聊天，coder profile 用来写代码和运维，那么迁移时不需要分别手工复制两个目录。正常情况下，一个 hermes backup 就能把它们一起带走。

这篇教程按公版写法整理：旧机器备份，新机器安装，导入备份，恢复 gateway，再检查 Matrix 反向代理和客户端地址。

迁移前先确认什么

开始前建议确认三件事：

  • 旧机器上的 Hermes 能正常启动。
  • 新机器可以访问 GitHub 或能通过其他方式安装 Hermes。
  • 你知道 Hermes 运行在哪个系统用户下，例如当前登录用户、hermes 用户或其他专用用户。

后续命令默认在运行 Hermes 的那个用户下执行。不要一会儿用普通用户，一会儿用 root，否则导入后的数据可能落到不同 home 目录里。

先确认当前用户和 Hermes 命令位置：

whoami
echo "$HOME"
command -v hermes
hermes --version

如果 Hermes 是 systemd user service，后续也要用同一个用户管理 gateway：

systemctl --user list-units 'hermes*' --no-pager

备份包会包含什么

hermes backup 会把 Hermes 的本地数据打成一个 zip 包。实际包含内容会随 Hermes 版本和本机配置略有变化，但迁移时可以按下面理解：

内容说明
default profile默认助手的配置、记忆、技能和会话
其他 profile例如 coder、dev、ops 等开发或运维 profile
skills已安装或沉淀的技能
memories长期记忆和偏好
sessions会话历史
configHermes 主配置和 profile 配置
.env模型 API Key、Telegram/Matrix 等环境变量
auth.json本地认证相关状态
state.dbHermes 本地状态数据库

也就是说，备份包里通常包含敏感信息。它应该像密码库一样保管，不要上传到公开网盘、公开仓库或聊天群。

旧机器：打包 Hermes 数据

在旧机器上执行：

hermes backup -o ~/hermes-migration.zip

备份完成后检查文件大小和位置：

ls -lh ~/hermes-migration.zip

如果你想把包名写得更清楚，也可以带日期：

hermes backup -o ~/hermes-backup-$(date +%Y%m%d).zip

备份包可能只有几十 MB，例如 29 MB 左右，这很正常。Hermes 的文本配置、记忆和数据库压缩后通常不会太大。

传输备份包到新机器

可以用 scp、rsync、SFTP、U 盘或可信内网文件传输。下面以 scp 为例：

scp ~/hermes-migration.zip <user>@<new-server-ip>:~/

如果新机器只允许密钥登录：

scp -i ~/.ssh/<key> ~/hermes-migration.zip <user>@<new-server-ip>:~/

传完后在新机器确认：

ls -lh ~/hermes-migration.zip

新机器：安装 Hermes

在新机器上先安装 Hermes：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

安装完成后重新加载 shell 配置，或重新登录一次：

source ~/.bashrc

如果你使用 zsh，可以按安装脚本提示加载 ~/.zshrc：

source ~/.zshrc

确认命令可用：

command -v hermes
hermes --version

如果新机器缺少 ripgrep，建议顺手安装。它不是迁移必需项，但会明显改善代码库搜索体验：

sudo apt update
sudo apt install ripgrep -y

新机器：导入备份

确认 ~/hermes-migration.zip 已经在新机器上，然后执行：

hermes import ~/hermes-migration.zip

导入完成后可以检查 profile：

hermes profile list

如果你原来有默认 profile 和 coder profile，导入后应该都能看到。也可以分别启动一次，确认基础配置正常：

hermes
hermes --profile coder

如果你的 profile 名不是 coder，把命令里的 coder 替换成自己的名字。

重启 Gateway

导入完成后，重启 gateway。默认 profile：

hermes gateway restart

开发 profile，例如 coder：

hermes gateway restart --profile coder

如果 Hermes 使用 systemd user service，hermes gateway restart 通常会自动重建或刷新对应服务。你也可以检查服务状态：

systemctl --user list-units 'hermes*' --no-pager
systemctl --user status hermes-gateway.service --no-pager

如果 coder profile 有单独服务，服务名可能类似：

systemctl --user status hermes-gateway-coder.service --no-pager

不同版本或不同 profile 命名可能略有差异，以 systemctl --user list-units 'hermes*' 的实际输出为准。

Matrix 反向代理要单独处理

Hermes 备份会搬走 Hermes 自己的数据，但不会自动迁移系统层面的反向代理配置。也就是说，Nginx、Caddy、Cloudflare Tunnel、Nginx Proxy Manager 这类东西要按新机器环境重新处理。

如果新机器 IP 变了，需要检查：

  • 域名 DNS 是否指向新机器。
  • Nginx 或 Caddy 是否监听了正确端口。
  • TLS 证书是否重新签发或已正确迁移。
  • Matrix webhook、gateway URL 或回调地址是否仍然指向旧机器。
  • 防火墙是否放行了需要的端口。

如果只是内网 IP 变化，没有域名，也要把客户端或反代里的旧 IP 改掉。

Element 客户端要改服务器地址

如果用户通过 Element 连接 Matrix，而 Matrix 服务地址变了，需要在 Element 里改成新地址。

常见情况：

  • 旧机器用内网 IP，例如 http://192.168.1.10:8008。
  • 新机器换成了另一个内网 IP。
  • 原来用域名访问，现在 DNS 指向新机器。
  • 反向代理路径或端口发生变化。

如果服务端域名没有变，只是后端机器变了，Element 一般不需要重新登录。反之，如果 homeserver 地址本身变了，就需要按新地址重新配置。

系统时间和 faketime

如果旧机器上曾经为了调试使用过 faketime，迁移时不要默认照搬这种做法。新机器系统时间准确时，不需要再启用 faketime。

建议先检查时间：

date
timedatectl

如果时间不准，优先修复 NTP：

sudo timedatectl set-ntp true

只有在非常明确的测试场景里，才考虑继续使用 faketime。长期运行的 Agent、Matrix、Telegram、TLS 和 OAuth 类服务都依赖准确时间。

迁移后验证清单

导入和重启完成后，按下面顺序检查：

  1. Hermes 命令可用：
hermes --version
  1. profile 都在：
hermes profile list
  1. 默认 profile 能启动：
hermes
  1. 开发 profile 能启动：
hermes --profile coder
  1. 默认 gateway 正常：
hermes gateway status
  1. 开发 gateway 正常：
hermes gateway status --profile coder
  1. systemd user service 没有失败：
systemctl --user --failed

  1. Matrix、Telegram 或其他入口能收到回复。

  2. 新机器重启后 gateway 仍能自动恢复。

loginctl enable-linger "$(whoami)"

enable-linger 适合 systemd user service 需要在用户不登录时继续运行的场景。如果 Hermes 是普通 system service 或 Docker 服务，则按对应方式管理自启动。

常见问题

导入后找不到 profile

先确认是不是在错误用户下导入了备份：

whoami
echo "$HOME"
hermes profile list

如果旧机器是在 hermes 用户下运行，新机器却在 root 下导入，就会出现数据目录不一致的问题。切到正确用户后重新导入。

Gateway 启动了但机器人没回复

重点检查三类东西：

  • .env 里的 token 和 API Key 是否仍然有效。
  • Telegram、Matrix、Discord 等平台的回调或 home channel 是否正确。
  • 反向代理、防火墙、DNS 是否指向新机器。

Hermes 数据可以通过 import 恢复，但外部平台的网络入口仍然取决于新机器的系统和网络配置。

systemd 服务名不一致

不要硬猜服务名，先列出来：

systemctl --user list-units 'hermes*' --no-pager

再按实际服务名查看：

systemctl --user status <service-name> --no-pager

如果 Hermes gateway 命令能自动重建服务，优先使用：

hermes gateway restart
hermes gateway restart --profile coder

新机器时间不准导致登录或回调异常

先修系统时间，不要先改 Hermes：

timedatectl
sudo timedatectl set-ntp true

时间漂移会影响 TLS、OAuth、JWT、Matrix federation、Telegram webhook 等很多东西。

一句话流程

完整迁移可以浓缩成四步：

# 旧机器
hermes backup -o ~/hermes-migration.zip

# 把 ~/hermes-migration.zip 传到新机器

# 新机器
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes import ~/hermes-migration.zip
hermes gateway restart
hermes gateway restart --profile coder

如果 Matrix、Element 或反向代理也换机器了，再单独修 DNS、Nginx/Caddy、TLS、防火墙和客户端服务器地址。

核心思路就是：Hermes 自己的数据用 backup / import 搬；系统网络入口和客户端地址按新机器环境重新接好。