# Hermes 备份迁移方案

适用环境：当前实例位于 /home/lin/.hermes，代码目录位于 /home/lin/.hermes/hermes-agent。

目标：
- 完整备份 Hermes 的配置、凭据、记忆、会话、技能、脚本、定时任务和本地代码
- 在新机器上可恢复为可运行状态
- 避免把无意义的大文件、缓存、虚拟环境一起打包

一、备份范围

必须备份：
1. 核心配置
- /home/lin/.hermes/config.yaml
- /home/lin/.hermes/.env
- /home/lin/.hermes/SOUL.md

2. 记忆与状态
- /home/lin/.hermes/memories/
- /home/lin/.hermes/state.db
- /home/lin/.hermes/channel_directory.json
- /home/lin/.hermes/cron/
- /home/lin/.hermes/sessions/

3. 技能与脚本
- /home/lin/.hermes/skills/
- /home/lin/.hermes/scripts/

4. 本地 Hermes 代码
- /home/lin/.hermes/hermes-agent/

建议备份：
- /home/lin/.hermes/auth.json
- /home/lin/.hermes/quick_commands.json（如果未来出现）
- /home/lin/.hermes/mcp*.json / mcp 配置相关文件
- /home/lin/.hermes/config.yaml.bak.*（仅在你想保留历史配置时）

不建议备份：
- */venv
- */.venv
- */__pycache__
- *.pyc
- /home/lin/.hermes/logs/
- /home/lin/.hermes/audio_cache/
- /home/lin/.hermes/models_dev_cache.json
- 临时 backup 文件、旧 tar.gz 包

二、迁移前检查清单

在源机器执行：
1. 检查 Hermes 当前配置是否有效

```bash
hermes config check
hermes doctor
```

2. 检查关键文件是否存在

```bash
test -f /home/lin/.hermes/config.yaml
test -f /home/lin/.hermes/.env
test -d /home/lin/.hermes/memories
test -d /home/lin/.hermes/skills
test -d /home/lin/.hermes/scripts
test -d /home/lin/.hermes/hermes-agent
test -f /home/lin/.hermes/state.db
```

3. 记录版本信息

```bash
hermes --version
python3 --version
git -C /home/lin/.hermes/hermes-agent rev-parse --short HEAD 2>/dev/null || true
uname -a
```

三、推荐备份目录

```bash
mkdir -p /home/lin/backups/hermes
```

四、标准备份命令

推荐生成两个包：
- 配置状态包：小、恢复快
- 代码技能包：大、完整

1. 配置状态包

```bash
tar -czvf /home/lin/backups/hermes/hermes_state_$(date +"%Y%m%d_%H%M%S").tar.gz \
  --exclude='*/__pycache__' \
  --exclude='*.pyc' \
  --exclude='*.lock' \
  -C /home/lin/.hermes \
  config.yaml \
  .env \
  SOUL.md \
  memories \
  state.db \
  sessions \
  cron \
  skills \
  scripts \
  channel_directory.json \
  auth.json
```

2. 代码包

```bash
tar -czvf /home/lin/backups/hermes/hermes_code_$(date +"%Y%m%d_%H%M%S").tar.gz \
  --exclude='venv' \
  --exclude='.venv' \
  --exclude='__pycache__' \
  --exclude='*.pyc' \
  --exclude='.git' \
  -C /home/lin/.hermes \
  hermes-agent
```

如果想一次性打成单包，用：

```bash
tar -czvf /home/lin/backups/hermes/hermes_full_$(date +"%Y%m%d_%H%M%S").tar.gz \
  --exclude='*/venv' \
  --exclude='*/.venv' \
  --exclude='*/__pycache__' \
  --exclude='*.pyc' \
  --exclude='/home/lin/.hermes/logs' \
  --exclude='/home/lin/.hermes/audio_cache' \
  -C /home/lin \
  .hermes
```

五、完整迁移步骤

方案 A：迁移到新 Linux 服务器

1. 新机器准备基础环境

```bash
sudo apt-get update
sudo apt-get install -y git curl tar python3 python3-venv python3-pip ripgrep ffmpeg
mkdir -p /home/lin/.hermes
mkdir -p /home/lin/backups/hermes
```

2. 传输备份包

```bash
scp /home/lin/backups/hermes/hermes_state_*.tar.gz user@NEW_HOST:/home/lin/backups/hermes/
scp /home/lin/backups/hermes/hermes_code_*.tar.gz user@NEW_HOST:/home/lin/backups/hermes/
```

3. 在新机器解压

```bash
tar -xzvf /home/lin/backups/hermes/hermes_state_YYYYMMDD_HHMMSS.tar.gz -C /home/lin/.hermes
tar -xzvf /home/lin/backups/hermes/hermes_code_YYYYMMDD_HHMMSS.tar.gz -C /home/lin/.hermes
```

4. 重建虚拟环境

```bash
cd /home/lin/.hermes/hermes-agent
python3 -m venv venv
source venv/bin/activate
pip install -U pip
pip install -e .
```

如果项目不是 editable 安装方式，则改为：

```bash
pip install -r requirements.txt
```

5. 校验配置与依赖

```bash
source /home/lin/.hermes/hermes-agent/venv/bin/activate
hermes config check
hermes doctor
```

6. 验证关键能力

```bash
hermes chat -q "test"
hermes sessions list
hermes skills list
hermes cron list
```

7. 如果使用 gateway，恢复并重启服务

```bash
hermes gateway status
hermes gateway restart
```

六、回滚方案

如果新机器恢复失败：
1. 不要覆盖源机器
2. 保留原始 tar.gz 包不删除
3. 重新在临时目录验证恢复

```bash
mkdir -p /tmp/hermes-restore-test
cd /tmp/hermes-restore-test
mkdir .hermes
```

先在测试目录验证归档完整性：

```bash
tar -tzf /home/lin/backups/hermes/hermes_state_YYYYMMDD_HHMMSS.tar.gz | head
tar -tzf /home/lin/backups/hermes/hermes_code_YYYYMMDD_HHMMSS.tar.gz | head
```

七、恢复后的重点检查

1. API key 是否生效
- /home/lin/.hermes/.env
- config.yaml 中环境变量引用是否正常解析

2. fallback/custom provider 是否正常
重点检查：
- NVIDIA_NIM_API_KEY
- GOOGLE_API_KEY
- TELEGRAM_BOT_TOKEN
- EXA_API_KEY
- GITHUB_TOKEN

3. 路径是否仍然正确
当前配置中包含绝对路径，迁移到新机器时要重点检查：
- /home/lin/.hermes/skills/leisure/lunar-calendar/scripts/lunar.py
- /home/lin/.hermes/hermes-agent
- quick_commands 中的脚本路径

如果新机器用户名不是 lin，需要批量替换：

```bash
grep -R "/home/lin" /home/NEWUSER/.hermes/config.yaml /home/NEWUSER/.hermes/skills /home/NEWUSER/.hermes/scripts
```

八、推荐的最终做法

生产上建议保留：
1. 每日状态备份
- 只备份 config/.env/memories/state.db/sessions/cron/skills/scripts

2. 每周完整备份
- 额外包含 hermes-agent 代码目录

3. 升级前强制备份
- 在执行 `hermes update` 前先打一份完整包

九、建议增加的自动化脚本

建议最终落地为两个脚本：
- /home/lin/.hermes/scripts/hermes/backup_state.sh
- /home/lin/.hermes/scripts/hermes/backup_full.sh

并加一个定时任务，例如：

```bash
0 3 * * * /home/lin/.hermes/scripts/hermes/backup_state.sh
0 4 * * 0 /home/lin/.hermes/scripts/hermes/backup_full.sh
```

十、当前环境的实际注意点

基于当前实例，我建议你迁移时特别注意：
- 当前 /home/lin/.hermes 约 1.3G，其中 hermes-agent 代码目录占主要体积
- config.yaml 已经把部分敏感字段改为环境变量引用，.env 必须一起迁移
- 你有本地 skills、scripts、quick_commands，自定义程度较高，不能只迁移 config.yaml
- 旧的 config.yaml.bak.* 很多，不建议全部打包到新机器

十一、最简执行版

如果你现在只想要一个最实用的最简流程，就按下面做：

源机器：

```bash
mkdir -p /home/lin/backups/hermes

tar -czvf /home/lin/backups/hermes/hermes_state_$(date +"%Y%m%d_%H%M%S").tar.gz \
  --exclude='*/__pycache__' \
  --exclude='*.pyc' \
  -C /home/lin/.hermes \
  config.yaml .env SOUL.md memories state.db sessions cron skills scripts channel_directory.json auth.json

tar -czvf /home/lin/backups/hermes/hermes_code_$(date +"%Y%m%d_%H%M%S").tar.gz \
  --exclude='venv' --exclude='.venv' --exclude='__pycache__' --exclude='*.pyc' \
  -C /home/lin/.hermes hermes-agent
```

新机器：

```bash
mkdir -p /home/lin/.hermes

tar -xzvf hermes_state_YYYYMMDD_HHMMSS.tar.gz -C /home/lin/.hermes
tar -xzvf hermes_code_YYYYMMDD_HHMMSS.tar.gz -C /home/lin/.hermes

cd /home/lin/.hermes/hermes-agent
python3 -m venv venv
source venv/bin/activate
pip install -U pip
pip install -e .

hermes config check
hermes doctor
hermes chat -q "恢复验证"
```