site-migration-toolkit/README.md

Site Migration & Backup Toolkit (site-migration-toolkit)

🇨🇳 中文版在下方 | Chinese version below

Welcome to the Site Migration & Backup Toolkit. This repository provides the orchestrations, runbooks, and automated playbooks for managing the disaster recovery lifecycle of the AI Workspace infrastructure.

Phase Roadmap

This project is iteratively rolling out disaster recovery capabilities. Currently, we are heavily focused on Phase 1.

Phase 1: Migration / Cold Backup / Offline Restore (Current)

Implement only the foundation:

• Ansible automated migration skeleton
• File and configuration packaging
• PostgreSQL dump / restore skeleton
• Vault secret migration design placeholder
• DNS cutover pre-check placeholder
• GitHub Actions regression verification skeleton
• Manual recovery fallback scripts and runbook

Phase 2: Warm Standby / Scheduled Backup

Only reserve documentation and interface placeholders for:

• Scheduled backup
• Incremental sync
• Object storage archive
• Restore drill
• RPO / RTO report

Phase 3: Hot Backup / DTS / Replication

Only reserve roadmap placeholders for:

• PostgreSQL streaming replication
• Redis replication
• DTS / CDC
• Dual-write validation
• Failover plan

Phase 4: Multi-Active / DR Platform

Only reserve roadmap placeholders for:

• Multi-region deployment
• Traffic routing
• Data consistency strategy
• Active-Active / Active-Passive
• DR orchestration platform

⚠️ CI/CD Prerequisites (Important Notice)

If you are running the GitHub Actions workflow (deploy-env-migration.yaml), please ensure that your Vault environment is correctly configured:

• Vault Role: The required role name is github-actions-site-migration-toolkit.
• Role Binding: Ensure the JWT bound_claims match the new repository name (repo:ai-workspace-infra/site-migration-toolkit:ref:refs/heads/main or similar).

Vault Role Provisioning Script: To avoid CLI parsing issues, use the following JSON payload format to create or update the role:

vault write auth/jwt/role/github-actions-site-migration-toolkit - <<EOF
{
  "bound_audiences": ["vault"],
  "bound_claims_type": "glob",
  "bound_claims": {
    "sub": "repo:ai-workspace-infra/site-migration-toolkit:*"
  },
  "user_claim": "actor",
  "role_type": "jwt",
  "policies": ["CICD", "openclaw"], 
  "ttl": "1h"
}
EOF

---

站点迁移与备份工具集 (Site Migration & Backup Toolkit)

欢迎使用 Site Migration & Backup Toolkit。本代码库提供了管理 AI Workspace 基础架构灾难恢复生命周期的编排、运维手册和自动化 Playbooks。

阶段演进路线图 (Phase Roadmap)

本项目正在迭代推出灾备能力。目前，我们正重点聚焦于 Phase 1 (第一阶段)。

Phase 1: 迁移 / 冷备 / 离线恢复 (当前阶段)

仅实现基础底座：

• Ansible 自动化迁移骨架
• 文件与配置打包
• PostgreSQL 逻辑备份 / 还原骨架
• Vault 凭证迁移设计占位符
• DNS 流量切换前置检查占位符
• GitHub Actions 回归验证骨架
• 手动恢复降级脚本与运维手册

Phase 2: 温备 / 定时备份

仅保留文档与接口占位符：

• 定时计划备份
• 增量同步
• 对象存储归档
• 还原演练
• RPO / RTO 报告

Phase 3: 热备 / DTS / 复制

仅保留路线图占位符：

• PostgreSQL 流复制
• Redis 数据复制
• DTS / CDC (变更数据捕获)
• 双写验证
• 故障转移 (Failover) 计划

Phase 4: 多活 / 灾备管理平台

仅保留路线图占位符：

• 多地域 (Multi-region) 部署
• 流量智能路由
• 数据一致性策略
• 双活 (Active-Active) / 主备 (Active-Passive)
• DR 灾备编排平台

⚠️ CI/CD 前置条件 (重要提示)

如果您正在运行 GitHub Actions 流水线 (deploy-env-migration.yaml)，请确保您的 Vault 环境已正确配置：

• Vault 角色 (Role): 所需的角色名为 github-actions-site-migration-toolkit。
• 角色绑定 (Role Binding): 请确保 JWT 的 bound_claims 匹配新的代码库名称（例如 repo:ai-workspace-infra/site-migration-toolkit:ref:refs/heads/main）。

Vault 角色配置脚本: 为了避免 Vault CLI 在解析命令行 Map 类型时出现报错，推荐使用以下 JSON payload 的格式直接创建或更新角色：

vault write auth/jwt/role/github-actions-site-migration-toolkit - <<EOF
{
  "bound_audiences": ["vault"],
  "bound_claims_type": "glob",
  "bound_claims": {
    "sub": "repo:ai-workspace-infra/site-migration-toolkit:*"
  },
  "user_claim": "actor",
  "role_type": "jwt",
  "policies": ["CICD", "openclaw"], 
  "ttl": "1h"
}
EOF