---
name: hermes-server-migration
description: "Hermes Agent 服务器迁移流程 — 从旧服务器搬家到新服务器。触发条件：VPS到期、换服务器、重新部署。核心原则：先装好新服务器再拷配置，不要两边同时操作。"
---

# Hermes Agent 服务器迁移

## ⚠️ 核心原则（血泪教训）

1. **先确认自己在哪台机器** — 操作前必须运行 `hostname && ip addr show | grep 'inet '`，不要凭记忆猜IP
2. **先装新服务器，再拷配置** — 不要试图在运行中"搬家"，会两边都挂
3. **精简打包** — `.hermes/` 可能有 700MB+，排除大文件只拷关键配置
4. **不要同时操作两台机器** — 一步一步来，确认一步再做下一步

## 迁移清单

### 第一步：新服务器准备

```bash
# 1. 确认新服务器 Python 版本
sshpass -p '密码' ssh -o StrictHostKeyChecking=no root@新IP 'python3 -V'

# 2. 安装 python3-venv（Ubuntu 26.04 需要）
sshpass -p '密码' ssh root@新IP 'apt install -y python3.14-venv'

# 3. 创建虚拟环境并安装 Hermes
sshpass -p '密码' ssh root@新IP 'python3 -m venv /opt/hermes-venv && /opt/hermes-venv/bin/pip install -q hermes-agent'

# 4. 验证安装
sshpass -p '密码' ssh root@新IP '/opt/hermes-venv/bin/hermes --version'
```

### 第二步：打包老服务器配置（精简版）

**⚠️ 不要直接 tar 整个 .hermes/ 目录！** 700MB+ 会导致 tar 超时（30s/120s 都不够）。必须排除大文件。

```bash
# 在老服务器上执行 — 排除大文件（node/temp/sessions/state-snapshots）
cd /root && tar czf /tmp/hermes-migrate.tar.gz \
  .hermes/config.yaml \
  .hermes/config.yaml.bak.* \
  .hermes/.env \
  .hermes/SOUL.md \
  .hermes/skills/ \
  .hermes/state.db \
  .hermes/state.db-wal \
  .hermes/state.db-shm \
  .hermes/sessions/sessions.json \
  .hermes/logs/ \
  .hermes/bin/ \
  .hermes/cache/ \
  .hermes/cron/ \
  .hermes/kanban.db \
  .hermes/models_dev_cache.json \
  .hermes/webchat/ \
  .hermes/pastes/ \
  .hermes/response_store.db

# 检查大小（应该 < 100MB）
ls -lh /tmp/hermes-migrate.tar.gz
```

### 第三步：传输到新服务器

**⚠️ 必须同步 SOUL.md（人格定义文件）！不拷就是默认 OWL 身份**
**⚠️ 必须同步 sessions/sessions.json（QQ bot session token）！不拷 QQ 连不上**
**⚠️ 必须同步 state.db*（用户记忆）！不拷贝没有记忆**

```bash
# 关键文件传输（从老服务器到新服务器）
sshpass -p '新服务器密码' scp -o StrictHostKeyChecking=no \
  /root/.hermes/SOUL.md \
  /root/.hermes/config.yaml \
  /root/.hermes/.env \
  /root/.hermes/state.db \
  /root/.hermes/state.db-wal \
  /root/.hermes/state.db-shm \
  /root/.hermes/sessions/sessions.json \
  root@新IP:/root/.hermes/

# skills 目录用 rsync（文件多，scp 可能超时）
rsync -avz --timeout=60 -e "sshpass -p '新服务器密码' ssh -o StrictHostKeyChecking=no" \
  /root/.hermes/skills/ root@新IP:/root/.hermes/skills/

# sessions 目录（如果 sessions.json 不够，传整个目录）
rsync -avz --timeout=120 -e "sshpass -p '新服务器密码' ssh -o StrictHostKeyChecking=no" \
  /root/.hermes/sessions/ root@新IP:/root/.hermes/sessions/
```

### 第四步：启动新服务器 Gateway

```bash
# 正确启动方式（后台运行）
sshpass -p '密码' ssh root@新IP '
pkill -f "hermes" 2>/dev/null
sleep 2
cd /root
nohup /opt/hermes-venv/bin/python -m hermes_cli.main gateway run --replace > /tmp/hermes-gateway.log 2>&1 &
echo "PID: $!"
sleep 8
cat /tmp/hermes-gateway.log
'
```

**或者用 hermes 命令（等效）：**
```bash
sshpass -p '密码' ssh root@新IP '
pkill -f "hermes" 2>/dev/null
sleep 2
cd /root
nohup /opt/hermes-venv/bin/hermes gateway run > /tmp/hermes-gateway.log 2>&1 &
sleep 8
cat /tmp/hermes-gateway.log
'
```

**⚠️ 注意：多次重启 gateway 会导致 SSH 连接断开（SIGTERM 影响）。每次重连后先检查状态再操作。等用户确认后再重启。**

等几秒后检查日志

### 第五步：检查并修复常见问题

**问题1：No messaging platforms enabled（QQ bot 没启动）**
- 原因：gateway 启动后没加载 QQ 平台
- 确认 config.yaml 第 528-529 行有：
  ```yaml
  platform_toolsets:
    qqbot:
      - hermes-qqbot
  ```
- 确认 `.env` 里有 QQ 配置：
  ```bash
  QQ_APP_ID=你的APPID
  QQ_CLIENT_SECRET=你的SECRET
  QQ_ALLOW_ALL_USERS=true
  ```
- QQ bot 是内置在 hermes-agent 里的（`/opt/hermes-venv/lib/python3.14/site-packages/gateway/platforms/qqbot/`），不需要额外 pip 安装
- **如果确认配置正确但 QQ 仍不启动**：尝试用 `python -m hermes_cli.main gateway run --replace` 代替 `hermes gateway run`
- 详见 `references/qqbot-troubleshooting.md`

**问题2：No user allowlists configured**
- 解决：确认 `.env` 中有 `QQ_ALLOW_ALL_USERS=true` 或 `GATEWAY_ALLOW_ALL_USERS=true`

**问题3：kanban.db 报错**
- 解决：如果不需要 kanban，可以删除 `~/.hermes/kanban.db` 让它重建

### 第六步：验证

```bash
# 检查 gateway 进程
sshpass -p '密码' ssh root@新IP 'ps aux | grep hermes | grep -v grep'

# 检查平台连接状态（应该看到 qqbot: connected）
sshpass -p '密码' ssh root@新IP 'cat ~/.hermes/gateway_state.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get(\"platforms\",{}))"'
```

## 迁移后清理

```bash
# 删除临时文件
rm /tmp/hermes-migrate.tar.gz
sshpass -p '密码' ssh root@新IP 'rm /tmp/hermes-migrate.tar.gz'
```

## 注意事项

- **老服务器不要急着关** — 等新服务器确认能正常聊天后再关
- **⚠️ 关闭老服务器前必须确认 QQ 消息只有一条回复** — 如果老服务器还在运行 Hermes，QQ 消息会被两个服务器都收到，导致用户收到两条不同的回复。关闭老服务器后，用户发 QQ 消息应该只收到一条回复
- **关闭老服务器用 SHUTDOWN 不是 DESTROY** — DESTROY 是销毁服务器，数据找不回来；SHUTDOWN 是关机，随时可以再开。CloudCone 后台操作顺序：先 SHUTDOWN → 确认 QQ 只剩一条回复 → 如果不放心可以 REBOOT 再 SHUTDOWN 一次
- **密码重置** — 如果忘记密码，通过 VPS 控制面板的 VNC 控制台或重置密码功能
- **Ubuntu 26.04 变化** — Python 3.14，需要 `python3.14-venv` 包
- **Hostinger 默认禁止密码登录** — 需要先开启：`sed -i 's/#PasswordAuthentication yes/PasswordAuthentication yes/' /etc/ssh/sshd_config && systemctl restart sshd`
- **`hermes-qqbot` 是内置模块** — 不需要 `pip install hermes-qqbot`，它在 `/opt/hermes-venv/lib/python3.14/site-packages/gateway/platforms/qqbot/` 目录下，是 hermes-agent 自带的
- **`hermes` 命令软链接** — 安装后建议创建软链接 `ln -sf /opt/hermes-venv/bin/hermes /usr/local/bin/hermes`，方便直接输入 `hermes` 启动
- **⚠️ 必须创建 `/root/AGENTS.md`** — SOUL.md 在 `.hermes/` 目录里，但 Hermes 读取的是 `/root/AGENTS.md`。如果不复制，星璇人格不会加载，AI 会用默认身份。执行：`cp /root/.hermes/SOUL.md /root/AGENTS.md`
- **⚠️ 检查 personality 设置** — 新服务器 config.yaml 默认 personality 可能是 `kawaii`，需要改成 `helpful`（星璇人格由 AGENTS.md 控制）：`sed -i 's/personality: kawaii/personality: helpful/' /root/.hermes/config.yaml`
- **⚠️ TTS 语音改成中文** — 默认是英文 `en-US-AriaNeural`，张哥做视频需要中文配音，改成 `zh-CN-XiaoxiaoNeural`：在 config.yaml 的 tts.edge.voice 处修改
- **⚠️ 安装视频制作工具** — `apt install -y ffmpeg`，`pip install yt-dlp`，edge-tts 已内置
- **⚠️ Gateway 不能远程 kill** — `pkill -f hermes` 会被安全机制阻止（BLOCKED）。必须让用户在服务器终端手动执行 `hermes gateway restart` 或 `pkill`。远程只能启动新进程，不能杀旧进程
- **⚠️ 重复 gateway 进程** — 如果 gateway 被多次启动（比如重启时旧进程没关），会导致 QQ 收到两条回复。用户需要确认只有一个 gateway 进程在跑：`ps aux | grep hermes | grep -v grep`
- **⚠️ 旧服务器关了后 QQ 只从新服务器收** — 旧服务器关机（SHUTDOWN）后，QQ 消息只会被新服务器收到。如果用户反映收到两条回复，说明旧服务器还没完全关掉，或者新服务器上有两个 gateway 进程在跑
- **⚠️ 旧服务器 DESTROY vs SHUTDOWN** — SHUTDOWN=关机可恢复，DESTROY=销毁数据丢失。用户想保留旧服务器作为备份时用 SHUTDOWN。CloudCone 后台操作：Power Off → 确认状态为 Stopped → 如果不放心可以 Reboot 再 Shutdown 一次
- **⚠️ 必须创建 `/root/AGENTS.md`** — SOUL.md 在 `.hermes/` 目录里，但 Hermes 读取的是 `/root/AGENTS.md`。如果不复制，星璇人格不会加载，AI 会用默认身份。执行：`cp /root/.hermes/SOUL.md /root/AGENTS.md`
- **⚠️ 检查 personality 设置** — 新服务器 config.yaml 默认 personality 可能是 `kawaii`，需要改成 `helpful`（星璇人格由 AGENTS.md 控制）：`sed -i 's/personality: kawaii/personality: helpful/' /root/.hermes/config.yaml`
- **⚠️ TTS 语音改成中文** — 默认是英文 `en-US-AriaNeural`，做视频需要中文配音，改成 `zh-CN-XiaoxiaoNeural`
- **⚠️ Gateway 不能远程 kill** — `pkill -f hermes` 会被安全机制阻止（BLOCKED）。必须让用户在服务器终端手动执行 `hermes gateway restart`。远程只能启动新进程，不能杀旧进程
- **⚠️ 重复 gateway 进程导致 QQ 双回复** — 迁移过程中如果 gateway 被多次启动，两个进程都接收 QQ 消息，用户收到两条不同回复。张哥对双回复非常敏感。解决：确认只有一个进程 `ps aux | grep hermes | grep -v grep`
- **⚠️ QQ 双回复也可能是两台服务器同时运行** — 旧服务器没关时，两台 Hermes 都回复 QQ。必须确认旧服务器已 SHUTDOWN 且新服务器只有一个 gateway 进程
- **⚠️ 视频制作附加依赖** — 安装 `Pillow`：`/opt/hermes-venv/bin/pip install Pillow`。ffmpeg、edge-tts 已内置，yt-dlp 需要 `pip install yt-dlp`
- **⚠️ 新服务器创建 hermes 软链接** — `ln -sf /opt/hermes-venv/bin/hermes /usr/local/bin/hermes`，方便直接输入 `hermes` 启动