Hermes Agent 完整迁移教程

将 Hermes Agent 从一台服务器迁移到另一台服务器的完整指南

---

📦 需要备份的核心数据

路径	内容	必须备份？
~/.hermes/config.yaml	主配置（模型、工具、网关、代理设置）	✅ 必须
~/.hermes/.env	API Key、QQ Bot 密钥等所有凭据	✅ 最重要
~/.hermes/skills/	所有已安装的技能（含用户自定义）	✅ 必须
~/.hermes/sessions/hermes_state.db	记忆（memory）、会话索引、cron 任务	✅ 推荐
~/.hermes/auth.json	OAuth 登录令牌	✅ 推荐
~/.hermes/sessions/	完整对话历史记录	◻ 可选
~/.hermes/logs/	网关和运行日志	◻ 可选
~/.hermes-web-ui/	WebUI 运行时文件（如有安装）	◻ 可选

⚠️ 特别注意：~/.hermes/.env 里存着所有 API Key（DeepSeek、OpenRouter、QQ App Secret、飞书 App Secret 等），备份文件建议加密传输或用 SCP/rsync 走 SSH。

---

🔧 旧服务器：备份

1. 查看版本

hermes --version

2. 打包核心数据

# 整个 ~/.hermes 目录打包
tar -czf ~/hermes-backup.tar.gz -C ~ .hermes

# 如果有 WebUI，也一并打包
tar -czf ~/hermes-webui-backup.tar.gz -C ~ .hermes-web-ui

3. 可选：记录 pip 依赖

pip list --format=freeze > ~/hermes-pip-deps.txt

4. 传输到新服务器

# 方法一：SCP（推荐内网）
scp ~/hermes-backup.tar.gz user@新服务器IP:~/

# 方法二：rsync（断点续传）
rsync -avz ~/hermes-backup.tar.gz user@新服务器IP:~/hermes-backup.tar.gz

---

🆕 新服务器：恢复

1. 安装 Hermes Agent

# 标准安装
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 验证安装
hermes --version

2. 恢复数据

# 解压备份文件到 home 目录
tar -xzf ~/hermes-backup.tar.gz -C ~

# 设置 .env 权限（含密钥，仅自己可读）
chmod 600 ~/.hermes/.env

3. 检查配置

hermes doctor

根据需要修复提示的问题。

4. 安装额外 Python 依赖

根据你启用的功能，安装对应的包：

# QQ Bot
pip install aiohttp httpx

# 飞书
pip install lark-oapi websockets aiohttp

# 语音转文字
pip install faster-whisper

# Excel 操作
pip install openpyxl

# 系统级依赖（如需要 TTS 语音合成）
sudo apt install espeak-ng   # Debian/Ubuntu

5. 验证恢复是否成功

# 测试基础对话
hermes -q "Hello, test connection"

# 查看技能是否完整
hermes skills list

# 查看 cron 任务是否保留
hermes cron list

# 查看记忆是否存在
hermes memory status

6. 启动网关（如有配置消息平台）

# 前台启动（先测试）
hermes gateway run

# 确认正常后安装为后台服务
hermes gateway install
hermes gateway start

---

⚡ 一键迁移脚本

将以下脚本保存为 migrate-hermes.sh：

#!/bin/bash
# Hermes Agent 迁移脚本
# 用法：
#   旧服务器: bash migrate-hermes.sh backup
#   新服务器: bash migrate-hermes.sh restore <备份文件路径>

set -e

BACKUP_FILE="$HOME/hermes-backup.tar.gz"

if [ "$1" = "backup" ]; then
    echo "📦 正在备份 Hermes Agent..."
    tar -czf "$BACKUP_FILE" -C "$HOME" .hermes
    echo "✅ 备份完成: $BACKUP_FILE"
    echo "📋 请将此文件传输到新服务器:"
    echo "   scp $BACKUP_FILE user@新服务器:~/"
    
elif [ "$1" = "restore" ]; then
    SRC="${2:-$HOME/hermes-backup.tar.gz}"
    
    if [ ! -f "$SRC" ]; then
        echo "❌ 备份文件不存在: $SRC"
        exit 1
    fi
    
    echo "📦 正在安装 Hermes Agent..."
    curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
    
    echo "🔄 正在恢复数据..."
    tar -xzf "$SRC" -C "$HOME"
    chmod 600 "$HOME/.hermes/.env"
    
    echo "🔍 正在检查配置..."
    hermes doctor
    
    echo "✅ 迁移完成！"
    echo "运行 'hermes' 开始使用"
    echo "运行 'hermes gateway run' 启动消息平台"
    
else
    echo "用法:"
    echo "  备份: bash $0 backup"
    echo "  恢复: bash $0 restore [备份文件路径]"
fi

---

⚠️ 迁移后注意事项

注意事项	说明
Python 版本	新服务器需 Python 3.10+
pip 依赖	缺失的包运行时会报错，按需安装即可
绝对路径	如果 config.yaml 或 cron 任务写了绝对路径（如 workdir），需要更新
系统依赖	TTS 需要 espeak-ng，音频处理需要 libopus 等
QQ Bot / 飞书	密钥随 .env 恢复，无需重新注册
防火墙	如用 Webhook 模式连接飞书等平台，需开放对应端口
SSH 登录	网关以 systemd 服务运行时，需要 loginctl enable-linger $USER 以防 SSH 退出后服务停止

---

🔄 回滚方案

如果新服务器出现问题，旧服务器的数据仍然完整。可以随时：

# 在旧服务器上重新启动
hermes gateway start

数据没有丢失风险。

---

📁 相关路径速查

用途	路径
主配置文件	~/.hermes/config.yaml
密钥文件	~/.hermes/.env
技能目录	~/.hermes/skills/
会话数据库	~/.hermes/sessions/hermes_state.db
对话历史	~/.hermes/sessions/
网关日志	~/.hermes/logs/gateway.log
OAuth 令牌	~/.hermes/auth.json
源码（git安装）	~/.hermes/hermes-agent/

---

一句话总结：整个 ~/.hermes/ 目录打包带走，新服务器装好 Hermes 后覆盖恢复即可。