feat(migration): 换宿主平台迁移能力（打包/恢复脚本 + runbook）

make_migration_bundle：sqlite backup API 在线快照（无需停服）打包 data/（两库+escrow+backups）与 .env，含逐文件 sha256 清单与版本/commit 元信息。restore_migration_bundle：sha256 逐文件校验（篡改即拒绝）、目标机原状态留 pre-restore 备份、兼容旧版 Python 的 tar 解包路径校验，并打印 serve/agent/CORS/源机下线等手工步骤。docs/migration-runbook.md：迁移面清单、可选预处理（agent 去 IP 化）、七步迁移、十项验收、回滚与灾难恢复。本地隔离演练验证：密码解密一致、2FA 出码可用、escrow+RESTORE_KEY 可解回 MASTER_KEY、篡改包被拦截。
2026-09-05 23:20:45 +00:00
parent 6865bb7914
commit cc8c91ddd9
3 changed files with 384 additions and 0 deletions
@@ -0,0 +1,138 @@
+"""迁移打包：把 vps-manager 的唯一状态打成单一可校验迁移包
+
+在源机器（如 cc1）运行：
+  .venv/bin/python scripts/make_migration_bundle.py [输出tar.gz路径]
+
+打包内容（唯一状态；代码/venv/systemd units/tailscale serve 均可由
+setup.sh 与一条 serve 命令重建，故不在包内）：
+  - data/assets.db、data/metrics.db：sqlite backup API 在线一致性快照（无需停服）
+  - data/master_key.escrow：MASTER_KEY 托管档（若已建立）
+  - data/backups/：历史备份（含 escrow 副本）
+  - .env：MASTER_KEY / API_KEY / AGENT_KEY / 通知渠道 / S3 配置
+  - manifest.json + manifest.sha256：版本、commit、主机、逐文件校验和
+
+安全说明：包内含 MASTER_KEY 与全部密文，等同最高机密。传输仅用 scp 或加密
+介质，恢复完成并验证后即刻删除；切勿上传公开对象存储或聊天工具。
+恢复步骤见 scripts/restore_migration_bundle.py 与 docs/migration-runbook.md。
+"""
+
+import hashlib
+import json
+import shutil
+import socket
+import sqlite3
+import subprocess
+import sys
+import tarfile
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+BASE = Path(__file__).resolve().parent.parent
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def snap_db(src: Path, dst: Path) -> None:
+    """sqlite 在线一致性快照：backup API 保证事务边界完整，源库无需停服"""
+    con = sqlite3.connect(str(src))
+    bkp = sqlite3.connect(str(dst))
+    with bkp:
+        con.backup(bkp)
+    bkp.close()
+    con.close()
+
+
+def read_git_commit() -> str:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"], cwd=BASE,
+            capture_output=True, text=True, timeout=5,
+        )
+        return out.stdout.strip() or "unknown"
+    except Exception:
+        return "unknown"
+
+
+def main() -> int:
+    out = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(
+        f"/tmp/vps-manager-bundle-{datetime.now():%Y%m%d_%H%M%S}.tar.gz"
+    )
+    env_src = BASE / ".env"
+    if not env_src.exists():
+        print("[abort] 缺少 .env（MASTER_KEY 不在包内则迁移无意义）", file=sys.stderr)
+        return 2
+
+    work = Path(tempfile.mkdtemp(prefix="vps-bundle-"))
+    root = work / "bundle"
+    data_dst = root / "data"
+    data_dst.mkdir(parents=True)
+    data_src = BASE / "data"
+
+    copied: list[str] = []
+    for db in ("assets.db", "metrics.db"):
+        src = data_src / db
+        if src.exists():
+            snap_db(src, data_dst / db)
+            copied.append(f"data/{db}")
+        else:
+            print(f"[skip] {db} 不存在")
+    escrow = data_src / "master_key.escrow"
+    if escrow.exists():
+        shutil.copy2(escrow, data_dst / "master_key.escrow")
+        (data_dst / "master_key.escrow").chmod(0o600)
+        copied.append("data/master_key.escrow")
+    else:
+        print("[warn] 未建立 MASTER_KEY 托管（master_key.escrow 不存在），恢复链不完整")
+    backups_src = data_src / "backups"
+    if backups_src.is_dir():
+        shutil.copytree(backups_src, data_dst / "backups")
+        for p in sorted((data_dst / "backups").rglob("*")):
+            if p.is_file():
+                copied.append(str(p.relative_to(root)))
+    shutil.copy2(env_src, root / ".env")
+    (root / ".env").chmod(0o600)
+    copied.append(".env")
+
+    manifest = {
+        "app": "vps-manager",
+        "version": (BASE / "VERSION").read_text(encoding="utf-8").strip()
+        if (BASE / "VERSION").exists() else "dev",
+        "commit": read_git_commit(),
+        "source_host": socket.gethostname(),
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "files": {name: {"sha256": sha256_file(root / name), "size": (root / name).stat().st_size}
+                  for name in copied},
+    }
+    (root / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    (root / "manifest.sha256").write_text(
+        "".join(f"{v['sha256']}  {name}\n" for name, v in manifest["files"].items()),
+        encoding="utf-8",
+    )
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(out, "w:gz") as tar:
+        tar.add(root, arcname="bundle")
+    shutil.rmtree(work, ignore_errors=True)
+
+    print(f"[ok] 迁移包：{out}")
+    print(f"     大小：{out.stat().st_size / 1024:.1f} KB")
+    print(f"     包校验和：{sha256_file(out)}")
+    print(f"     源主机：{manifest['source_host']} · 版本 {manifest['version']} ({manifest['commit']})")
+    print(f"     内含 {len(copied)} 个状态文件（两库快照 + escrow + backups + .env）")
+    print("     恢复：新机器跑 setup.sh 后停服，执行")
+    print(f"       .venv/bin/python scripts/restore_migration_bundle.py {out}")
+    print("     ⚠ 包等同最高机密：仅 scp/加密介质传输，验证后删除")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,113 @@
+"""迁移恢复：校验并解包迁移包到目标部署目录
+
+在新机器运行（前提：已跑 deploy/setup.sh 完成代码/venv/units 部署）：
+  sudo systemctl stop vps-manager vps-manager-update.timer
+  .venv/bin/python scripts/restore_migration_bundle.py <bundle.tar.gz> [--app-dir /opt/vps-manager]
+  sudo systemctl start vps-manager
+
+行为：
+  - 按 manifest.sha256 逐文件校验，任一不匹配即拒绝恢复（防传输损坏/调包）
+  - 目标机现有 data/ 与 .env 先备份为 *.pre-restore-<ts>（可回滚）
+  - 解包 data/（两库 + escrow + backups）与 .env（chmod 600）
+  - 打印后续手工步骤（serve/agent/CORS/源机 timer 下线，见 docs/migration-runbook.md）
+"""
+
+import argparse
+import hashlib
+import shutil
+import sys
+import tarfile
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+
+def sha256_file(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="校验并恢复 vps-manager 迁移包")
+    ap.add_argument("bundle", help="迁移包 tar.gz 路径")
+    ap.add_argument("--app-dir", default="/opt/vps-manager", help="目标部署目录")
+    args = ap.parse_args()
+
+    bundle = Path(args.bundle)
+    app_dir = Path(args.app_dir)
+    if not bundle.exists():
+        print(f"[abort] 迁移包不存在：{bundle}", file=sys.stderr)
+        return 2
+    if not (app_dir / "app" / "main.py").exists():
+        print("[abort] 目标目录不像已部署的 vps-manager（缺 app/main.py），请先跑 deploy/setup.sh",
+              file=sys.stderr)
+        return 2
+
+    work = Path(tempfile.mkdtemp(prefix="vps-restore-"))
+    try:
+        with tarfile.open(bundle) as tar:
+            try:
+                # Python >= 3.11.4/3.12：官方数据过滤器（防路径穿越/硬链接等）
+                tar.extractall(work, filter="data")
+            except TypeError:
+                # 新机自带旧版 Python（如 3.10）无 filter 参数：手工校验成员路径
+                for m in tar.getmembers():
+                    if m.name.startswith("/") or ".." in Path(m.name).parts:
+                        print(f"[abort] 包内路径异常，拒绝解包：{m.name}", file=sys.stderr)
+                        return 2
+                tar.extractall(work)
+        root = work / "bundle"
+        manifest_sha = root / "manifest.sha256"
+        if not manifest_sha.exists():
+            print("[abort] 包内缺 manifest.sha256，拒绝恢复", file=sys.stderr)
+            return 2
+        print("[1/4] 校验包内文件…")
+        for line in manifest_sha.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            digest, name = line.split("  ", 1)
+            target = root / name
+            if not target.exists():
+                print(f"[abort] 包内缺文件：{name}", file=sys.stderr)
+                return 2
+            actual = sha256_file(target)
+            if actual != digest:
+                print(f"[abort] 校验和不匹配：{name}\n  期望 {digest}\n  实际 {actual}",
+                      file=sys.stderr)
+                return 2
+            print(f"  ok {name}")
+
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        print("[2/4] 备份目标机现有状态…")
+        for src, tag in ((app_dir / "data", f"data.pre-restore-{ts}"),
+                         (app_dir / ".env", f".env.pre-restore-{ts}")):
+            if src.exists():
+                dst = app_dir / tag
+                shutil.move(str(src), str(dst))
+                print(f"  {src} -> {dst}")
+
+        print("[3/4] 恢复 data/ 与 .env…")
+        shutil.move(str(root / "data"), str(app_dir / "data"))
+        shutil.move(str(root / ".env"), str(app_dir / ".env"))
+        (app_dir / ".env").chmod(0o600)
+        escrow = app_dir / "data" / "master_key.escrow"
+        if escrow.exists():
+            escrow.chmod(0o600)
+
+        print("[4/4] 恢复完成。后续手工步骤（详见 docs/migration-runbook.md）：")
+        print("  1. systemctl start vps-manager && curl 127.0.0.1:8000/health 比对 version/commit")
+        print("  2. tailscale serve --bg --https=443 http://127.0.0.1:8000（设备名沿用旧名可保持 URL 不变）")
+        print("  3. .env 的 CORS_ORIGINS 加入新 HTTPS 域名（若 URL 变化）")
+        print("  4. 各被管 VPS 的 /etc/vps-agent.env：VPS_MANAGER_URL 指向新地址后 restart vps-agent")
+        print("  5. 确认新机数据无误后，源机 disable 全部 timer 并 stop 服务（防双写/双通知）")
+        print("  6. 删除本迁移包与源机上的包副本（等同最高机密）")
+        return 0
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())