# 迁移 Runbook：vps-manager 换宿主平台

适用场景：当前宿主为 cc1（Tailscale `100.89.0.11`，HTTPS `https://dify.taile5765c.ts.net`）；
选定长期平台后按本手册完成整体搬迁。目标：**数据零丢失、密文零重录、服务可回滚**。

---

## 1. 迁移面：什么要搬，什么能重建

| 类别 | 内容 | 迁移方式 |
|---|---|---|
| **唯一状态（必须搬）** | `data/assets.db`、`data/metrics.db`、`data/master_key.escrow`、`data/backups/`、`.env` | `make_migration_bundle.py` 打包 → `restore_migration_bundle.py` 恢复 |
| 可重建（不搬） | 代码 | 新机 `git clone` Gitea 仓库（`setup.sh` 自动） |
| 可重建（不搬） | Python venv 与依赖 | `setup.sh`（`pip install -r requirements.txt`） |
| 可重建（不搬） | systemd units 与全部 timer | `deploy/*.service\|timer` 在仓库内，`setup.sh` 安装 |
| 可重建（不搬） | Tailscale HTTPS serve | 一条 `tailscale serve --bg --https=443 http://127.0.0.1:8000` |
| **机器外状态** | 离线 `RESTORE_KEY` 抄本、Gitea deploy key、S3 凭据 | 手工：RESTORE_KEY 抄本随身；新机需可访问 Gitea（SSH key 或 HTTPS+token） |

关键不变量：**`.env` 里的 `MASTER_KEY` 必须原样搬过去**——库内所有密文（平台账号
api_config、凭据密码、2FA secret）都用它加密。MASTER_KEY 不变，密文即可直接读，无需重录。

---

## 2. 迁移前可选预处理（让将来迁移更省事）

一次性做完，之后换平台时 agent 与访问地址都无需改动：

1. **agent 地址去 IP 化**：把各被管 VPS 的 `/etc/vps-agent.env` 中
   `VPS_MANAGER_URL=http://100.89.0.11:8000` 改为 MagicDNS 名，例如
   `http://dify.<tailnet>.ts.net:8000`；迁移时新设备沿用同名 `dify` 即可零改动。
   ```bash
   sed -i 's#http://100.89.0.11:8000#http://<新地址>:8000#' /etc/vps-agent.env && systemctl restart vps-agent
   ```
2. **建立 MASTER_KEY 托管**（若尚未做）：`python scripts/setup_key_escrow.py`，
   RESTORE_KEY 抄到 2~3 个离线位置——迁移途中 `.env` 出意外时这是唯一后路。
3. 确认备份 timer 正常：`systemctl list-timers | grep vps-`，且 `data/backups/escrow/` 有托管档。

---

## 3. 迁移步骤

### 3.1 源机（cc1）打包
```bash
ssh cc1
cd /opt/vps-manager
.venv/bin/python scripts/make_migration_bundle.py /tmp/vps-bundle.tar.gz
```
记录输出的**包校验和**与文件数。打包用 sqlite backup API 在线快照，**无需停服**。

### 3.2 传输
仅用 `scp` 或加密介质直传新机，不经第三方网盘/聊天工具：
```bash
scp /tmp/vps-bundle.tar.gz root@<新机>:/tmp/
```

### 3.3 新机部署基座
```bash
sudo tailscale up                       # 入网；建议设备名沿用 dify（保持 HTTPS URL 不变）
git clone <Gitea仓库> /tmp/vps-manager-setup && cd /tmp/vps-manager-setup
sudo bash deploy/setup.sh               # 依赖/venv/units/.env(临时)/服务启动
```
`setup.sh` 生成的临时 `.env` 会在 3.4 被包内 `.env` 覆盖（含真实 MASTER_KEY）。

### 3.4 停服并恢复状态
```bash
cd /opt/vps-manager
sudo systemctl stop vps-manager vps-manager-update.timer
sudo .venv/bin/python scripts/restore_migration_bundle.py /tmp/vps-bundle.tar.gz
sudo systemctl start vps-manager
```
脚本逐文件校验 sha256（不匹配即拒绝），并把新机原有 `data/`、`.env` 备份为
`*.pre-restore-<ts>` 以便回滚。

### 3.5 访问入口
```bash
sudo tailscale serve --bg --https=443 http://127.0.0.1:8000
sudo tailscale status                     # 确认 https://<设备名>.<tailnet>.ts.net
```
若 URL 与旧的不同：把新域名加入 `/opt/vps-manager/.env` 的 `CORS_ORIGINS`，
`sudo systemctl restart vps-manager`，并更新浏览器书签 / 手机 PWA。

### 3.6 agent 与通知
- 各被管 VPS：若未做 §2.1 预处理，逐台改 `VPS_MANAGER_URL` 指向新机并 `systemctl restart vps-agent`；
- 通知渠道（Telegram/SMTP）配置随 `.env` 迁移，无需改动，可用一次「立即同步」验证送达。

### 3.7 源机（cc1）下线 —— 防双写双通知
确认新机运行正常**至少一个同步/备份周期**后：
```bash
ssh cc1
sudo systemctl disable --now vps-manager vps-manager-update.timer \
  vps-backup-assets.timer vps-backup-metrics.timer vps-sync-ai.timer vps-renewal-check.timer
sudo rm -f /tmp/vps-bundle.tar.gz         # 迁移包等同最高机密，用完即删
```
新机侧同样删除 `/tmp/vps-bundle.tar.gz`。

---

## 4. 验收清单（迁移后逐项打勾）

- [ ] `curl https://<新地址>/health` 返回 `status=ok`，version/commit 与源机一致
- [ ] 前端各视图数据完整：资产、订阅、域名、平台账号、监控、AI
- [ ] **凭据可解密**：`/api/credentials/{id}/password` 能解出明文（抽查 1~2 条）
- [ ] **2FA 动态码正确**：`/api/credentials/{id}/otp` 出的码能在目标站点通过验证
- [ ] 平台账号 api_config 可解密：一次手动同步成功（验证 API 凭据未失效）
- [ ] `systemctl list-timers | grep vps-` 五个 timer 全部 enabled 且有下次触发时间
- [ ] 监控数据开始进新机（`metrics.db` 有 agent 上报的新指标）
- [ ] 备份 timer 跑过一次：`data/backups/assets/`、`data/backups/escrow/` 有新文件（含 S3）
- [ ] 源机所有 timer 已 disable、服务已 stop（防双写）
- [ ] 源机与新机上的迁移包均已删除

---

## 5. 回滚

新机异常时（源机尚未下线）：
```bash
sudo systemctl stop vps-manager
cd /opt/vps-manager && sudo mv data data.bad && sudo mv data.pre-restore-<ts> data
sudo mv .env .env.bad && sudo mv .env.pre-restore-<ts> .env
sudo systemctl start vps-manager
```
源机已下线的极端情况：在源机重新 `systemctl enable --now` 各服务与 timer 即可
（其数据未被改动，打包过程只读）。

---

## 6. 灾难恢复（与迁移不同的场景）

- **仅 `.env`/MASTER_KEY 丢失**（库还在）：`python scripts/recover_master_key.py --key <RESTORE_KEY> --write`
- **整机丢失**（只有备份）：新机 `setup.sh` → 从 S3/离线取最新 `data/backups/assets/assets_*.db`
  与 `metrics_*.db` 放回 `data/` → 取 `data/backups/escrow/master_key.escrow` 放回 `data/` →
  用离线 RESTORE_KEY 解出 MASTER_KEY 写入 `.env` → 起服验证解密。
- **RESTORE_KEY 也丢**：无解，密文不可恢复（这正是 §2.2 要求多处离线抄本的原因）。