跳到主要内容

Hermes Agent 版本更新操作指南：从备份到回滚的完整流程

· 阅读需 7 分钟
一介布衣
一介布衣
全栈开发者

Hermes Agent 的迭代速度很快——v0.11.0 一个版本就合并了 761 个 PR、1556 次提交。版本更新是日常操作，但如果流程不规范，轻则消息丢几条，重则配置全丢、服务起不来。

这篇文章把我在实际更新过程中总结的流程整理出来，适用于当前 v0.11.0（v2026.4.23）及后续版本，重点是怎么更新不出事，出了事怎么恢复。

为什么要专门写一篇更新指南？​

很多人觉得 hermes update 一条命令的事，有什么好写的。

但实际跑起来你会发现几个问题：

  • 更新的时候网关还在跑，飞书/微信那边发来的消息直接丢了，因为更新过程中代码文件在变，模块加载可能出错
  • 更新完版本号变了，但旧配置格式和新版本不兼容，网关起不来
  • 想回退，发现没备份，只能从零开始配

所以核心思路就一句话：先停服务、再备份、再更新、最后验证。顺序不能乱。

第一步：停掉网关服务​

这是最容易被忽略的一步，也是最重要的一步。

Hermes Agent 的网关（gateway）负责接收飞书、微信、Telegram 等平台的消息。更新过程中如果网关还在运行，可能出现：

  • 消息接收了但处理到一半，代码文件被覆盖，直接报错
  • 依赖库版本变了，正在运行的进程还在用旧版本，行为不可预期
  • 数据库 schema 变了，旧进程写入的数据格式不对

操作方法：

如果网关在前台运行（终端里能看到日志滚动），直接 Ctrl+C 终止。

如果网关在后台运行（比如用 nohup 或 systemd 拉起来的），需要手动找进程杀掉：

# 找到 hermes 相关进程
ps aux | grep hermes

# 终止进程（把 PID 换成实际的进程号）
kill -9 <PID>

验证服务已停：

# 方法一：再跑一次 gateway，看是不是提示没有正在运行的实例
hermes gateway

# 方法二：直接看进程列表
ps aux | grep hermes
# 没有输出就说明停干净了

💡 小提示：如果你的 Hermes 是通过 systemd 管理的，用 systemctl stop hermes-gateway 更规范。

第二步：备份数据​

这步的目的很简单：万一更新搞砸了，能恢复到更新前的状态。

方案一：手动备份（推荐，最稳）​

直接复制整个配置目录：

cp -r ~/.hermes ~/.hermes_bak_$(date +%Y%m%d)

这一条命令会把所有核心数据都备份下来，包括：

文件/目录作用
config.yaml核心运行配置（模型、API Key、网关设置等）
state.db会话历史和记忆数据库
cron/定时任务配置
skills/自定义技能
memory/持久化记忆
.env环境变量（API Key 等敏感信息）
SOUL.md人格设定文件（如果有的话）

方案二：官方备份命令​

Hermes 提供了内置的备份命令：

# 基础备份，自动生成压缩包
hermes backup

# 指定输出路径
hermes backup -o /opt/backup/hermes_pre_update.zip

# 快速备份（只备份核心配置，跳过大体积的会话数据）
hermes backup --quick --label pre_update_$(date +%Y%m%d)

⚠️ 注意：如果你的 Hermes 版本较旧，hermes backup 命令可能还不存在。这种情况下直接用方案一的 cp -r 就行，效果是一样的。

第三步：执行更新​

备份做完了，现在可以放心更新。

hermes update

这条命令会自动完成：

  • 拉取最新代码
  • 更新 Python 依赖
  • 执行必要的数据迁移
  • 输出新版本号

执行过程中注意几点：

  1. 保持网络稳定——更新需要从 GitHub/PyPI 拉取代码和依赖，网络中断会导致更新不完整
  2. 不要中断终端——更新到一半强行关掉终端，可能导致依赖装了一半、代码拉了一半，状态不一致
  3. 如果提示依赖问题——执行 hermes doctor 自动诊断修复
# 更新完如果有异常，先跑一次诊断
hermes doctor

第四步：验证更新结果​

更新命令跑完不代表就成功了，需要做两个验证。

1. 检查版本号​

hermes --version

确认输出的版本号是你期望的目标版本。比如当前最新是 v0.11.0 (v2026.4.23)。

2. 环境健康检查​

hermes doctor

这个命令会检查：

  • Python 版本是否兼容
  • 必要依赖是否安装完整
  • 配置文件格式是否正确
  • API Key 是否有效
  • 各个工具链是否可用

所有检查项都是 ✅ 就说明更新成功。

3. 网关验证（可选但建议）​

重新启动网关，然后从飞书/微信发一条测试消息，看能不能正常收到和回复：

hermes gateway

消息收发正常 → 更新完成，收工。

出问题了？回滚恢复​

如果更新后出现服务起不来、功能异常、配置丢失等情况，不要慌，用备份恢复。

从手动备份恢复​

# 1. 先停掉可能还在跑的异常进程
ps aux | grep hermes | grep -v grep | awk '{print $2}' | xargs kill -9 2>/dev/null

# 2. 删除有问题的当前目录
rm -rf ~/.hermes

# 3. 还原备份
cp -r ~/.hermes_bak_20260426 ~/.hermes

# 4. 重启网关验证
hermes gateway

从官方备份恢复​

hermes import ~/hermes-backup-20260426.zip

恢复后还是有问题？​

几个排查方向：

现象可能原因解决方案
hermes 命令找不到虚拟环境没激活cd ~/hermes-agent && source venv/bin/activate
启动报依赖错误pip 包版本不对pip install -r requirements.txt
配置文件解析失败新版本 config 格式变了用备份的 config.yaml 替换，或执行 hermes setup 重新配置
网关连不上平台Token/Webhook 过期重新配置对应平台的认证信息

完整操作流程速查​

怕记不住的话，照着这个 checklist 走就行：

□ 1. 停网关        → Ctrl+C 或 kill 进程
□ 2. 备份数据      → cp -r ~/.hermes ~/.hermes_bak_$(date +%Y%m%d)
□ 3. 执行更新      → hermes update
□ 4. 检查版本      → hermes --version
□ 5. 环境诊断      → hermes doctor
□ 6. 启动网关      → hermes gateway
□ 7. 发测试消息    → 飞书/微信发一条消息确认收发正常

整个流程顺利的话，5 分钟以内搞定。

一些经验之谈​

  1. 养成更新前备份的习惯。哪怕只是 cp -r 一下，花不了 10 秒钟，但出问题的时候能救命。

  2. 不要在业务高峰期更新。如果你的 Hermes 连着飞书在跑业务流程，找一个消息少的时间段（比如午休或下班后）再更新。

  3. 更新频率不用太高。不是每次有新 commit 都需要更新。关注 Release 页面，有正式版本发布了再更新，比跟着 main 分支跑稳定得多。

  4. 如果你改过源码。直接 hermes update 可能会冲突。建议先 git stash 保存本地修改，更新完再 git stash pop 恢复。有冲突的话手动解决。

  5. 多机部署的情况。如果你在多台机器上跑 Hermes，不要同时更新，先更新一台验证没问题了再更新其他的。

写这篇的初衷就是把更新这件"小事"的每一步都说清楚。很多运维事故不是技术难度高，而是流程不规范、少做了一步。希望对同样在用 Hermes Agent 的朋友有帮助。