GitHub CI/CD 备份与灾备怎么做？恢复目标和演练方法

备份范围：CI/CD 管道不是只有代码

多数团队对 GitHub 仓库的备份停留在「git clone --mirror」层面，以为代码安全就等于 CI/CD 安全。实际上 GitHub Actions 的管道由多个独立配置组成，任何一个丢失都会导致构建中断。

需要备份的组件包括：

• **工作流定义文件**：位于 .github/workflows/ 目录下的 YAML 文件。这些文件定义了触发条件、作业步骤和部署逻辑。它们本身在仓库中，随代码一起备份，但容易被忽略的是分支保护规则中引用的工作流状态检查。

• **Actions Secrets**：存储在仓库或组织级别的加密变量，例如云服务商密钥、SSH 私钥、API Token。GitHub 不会在 API 响应中明文返回 secret 值，只能通过 UI 或 API 更新。备份这些 secret 意味着必须在外部系统（如密码管理器或密钥管理服务）中维护一份副本。

• **环境变量**：仓库或环境级别的普通变量，虽然不加密，但数量多、命名规范不一，手动重建容易出错。

• **自托管 Runner 配置**：如果使用自托管 Runner，其注册令牌、标签、组信息和工作目录下的工具链都需要备份。Runner 注册令牌具有时效性，过期后必须重新生成，这意味着备份 Runner 配置的重点是记录注册过程而不是保存令牌。

• **仓库设置**：包括分支保护规则、合并策略、自动链接引用、Webhook 配置。这些设置可以通过 GitHub API 导出为 JSON，但 GitHub 本身不提供一键导出功能。

• **OAuth App 或 GitHub App 的安装权限**：如果 CI/CD 流程依赖第三方应用（如部署到 AWS 的 OIDC 集成），这些应用的安装 ID 和权限配置需要记录。

一个常见的错误是只备份了 .github/workflows/ 目录，忽略了 secrets 和环境变量。当仓库被误删除或组织被意外转移时，重新构建 CI/CD 环境的时间往往不是几分钟，而是数小时甚至数天。

RPO 和 RTO：根据发布频率设定目标

恢复点目标（RPO）和恢复时间目标（RTO）不是理论值，而是由业务容忍度决定的工程约束。

**RPO 设定原则**：RPO 决定了最多能接受丢失多少变更。对于每天发布多次的团队，RPO 应在 1 小时以内；对于每周发布一次的团队，RPO 可以是 24 小时。但需要注意，GitHub Actions 的工作流定义本身变更不频繁，真正的 RPO 瓶颈在于 secrets 和 runner 配置的变更频率。

一个合理的做法是将 RPO 分为两级：

• 代码和工作流定义：RPO 0，因为每次 push 都是备份。
• Secrets 和环境变量：RPO 24 小时，因为这些变更通常由管理员手动操作，频率低，且可以通过外部密钥管理服务记录变更日志。

**RTO 设定原则**：RTO 是从灾难发生到 CI/CD 管道恢复可用所需的时间。对于大多数中小团队，RTO 在 4 小时内是可以接受的，因为 CI/CD 中断通常不会立即导致业务完全停摆，但会阻塞开发进度。

RTO 的估算必须包含以下步骤：
1. 恢复 GitHub 仓库（如果仓库丢失）。
2. 恢复 Actions Secrets 和环境变量。
3. 重新注册自托管 Runner 或确认 GitHub Hosted Runner 可用。
4. 验证至少一个关键工作流能成功运行。

如果团队没有自托管 Runner，RTO 可以压缩到 1 小时内，因为 GitHub Hosted Runner 不需要恢复。如果依赖自托管 Runner，RTO 至少要预留 2 小时用于 Runner 的重新配置和工具链安装。

备份策略：API 导出与异地保存

GitHub 没有原生的全量备份功能，因此需要借助 API 和第三方工具实现。

代码备份

代码备份最直接的方法是定期执行 `git clone --mirror` 并将裸仓库推送到异地 Git 服务器（如 GitLab 自托管实例、AWS CodeCommit 或阿里云 Codeup）。频率建议为每小时一次，因为代码变更频繁且体积小。

需要注意，mirror 克隆会包含所有分支和标签，但不会包含 GitHub 特有的元数据（如 Issue、PR、Wiki）。如果这些元数据对 CI/CD 流程有影响（例如通过 Issue 触发的工作流），则需要额外备份。

Secrets 和环境变量备份

GitHub API 不提供读取 secret 值的接口，因此 secrets 的备份只能通过外部工具管理。推荐的做法是：

• 使用 HashiCorp Vault 或 AWS Secrets Manager 作为 secrets 的单一真实来源。
• 在 GitHub Actions 中通过 OIDC 或 API 调用从外部服务获取 secret，而不是直接存储在 GitHub 中。
• 如果必须使用 GitHub Secrets，则在创建或更新 secret 时，同时将值记录到加密的密码管理器中。

环境变量可以通过 GitHub API 获取，但需要逐仓库导出。一个实用的脚本是调用 `GET /repos/{owner}/{repo}/actions/variables` 接口，将结果保存为 JSON 文件，并与代码备份一起存储。

仓库设置备份

仓库设置可以通过 GitHub API 导出。需要备份的关键设置包括：

• 分支保护规则：`GET /repos/{owner}/{repo}/branches/{branch}/protection`
• Webhook 配置：`GET /repos/{owner}/{repo}/hooks`
• 仓库属性：`GET /repos/{owner}/{repo}`

这些 API 返回的数据结构较为复杂，建议使用 GitHub CLI 的 `gh api` 命令逐项导出，并保存为结构化文件。

自托管 Runner 配置备份

自托管 Runner 的配置主要集中在 Runner 机器上。备份策略是：

• 记录 Runner 的注册命令和标签，而不是备份注册令牌，因为令牌会过期。
• 将 Runner 机器的初始化脚本（包括安装 Docker、Node.js、Java 等工具链的步骤）版本化保存。
• 如果 Runner 使用临时文件或缓存，需要明确哪些目录可以重建，哪些需要持久化。

异地保存

备份数据必须存储在至少两个不同的地理位置。具体做法：

• 代码备份推送到另一个 Git 托管平台，例如将 GitHub 仓库镜像到 GitLab 或 Bitbucket。
• Secrets 备份存储在云服务商的密钥管理服务中，例如 AWS Secrets Manager 跨区域复制。
• 仓库设置和 Runner 配置的 JSON 文件存储在对象存储中，例如 AWS S3 跨区域复制或阿里云 OSS 跨地域复制。

异地保存的验证方法是：定期从异地存储中拉取备份数据，确认文件完整性和可读性。如果备份文件损坏或无法解密，异地保存就失去了意义。

恢复演练：从纸上谈兵到可执行

备份不做演练等于没有备份。恢复演练的核心目标是验证 RTO 和 RPO 是否可达，同时暴露文档和流程中的盲点。

演练场景设计

建议设计三个级别的演练场景：

**场景一：仓库误删除**

• 模拟条件：GitHub 仓库被删除，包括所有分支、标签和工作流。
• 恢复步骤：从异地 Git 服务器 clone 镜像仓库，推送到新创建的 GitHub 仓库，导入仓库设置和环境变量，验证工作流触发。
• 预期 RTO：30 分钟以内。

**场景二：组织级 Secrets 泄露**

• 模拟条件：组织级别的 Actions Secrets 被意外删除或需要轮换。
• 恢复步骤：从外部密钥管理服务获取最新 secret 值，通过 API 或 UI 重新创建，验证至少一个依赖该 secret 的工作流。
• 预期 RTO：15 分钟以内。

**场景三：自托管 Runner 完全失效**

• 模拟条件：Runner 机器硬盘损坏，所有配置丢失。
• 恢复步骤：按照版本化的初始化脚本重新部署 Runner，注册到 GitHub，安装工具链，验证构建。
• 预期 RTO：2 小时以内（取决于工具链安装时间）。

演练执行频率

• 全量恢复演练：每季度一次。包括从零恢复仓库、secrets、runner 和验证关键工作流。
• 部分恢复演练：每月一次。只演练 secrets 恢复或 runner 恢复，交替进行。
• 验证性检查：每周自动执行一次备份文件完整性检查。

演练记录与改进

每次演练后需要记录以下内容：

• 实际恢复时间与目标 RTO 的差距。
• 文档中缺失的步骤或错误的命令。
• 需要人工干预的环节（例如 secret 值无法从外部服务获取）。
• 工具链版本不一致导致的构建失败。

根据演练结果，至少每季度更新一次备份和恢复文档。如果团队人员变动，必须在新人入职后两周内安排一次演练。

常见风险与应对

备份数据与 GitHub 状态不同步

代码备份通过 git push 实现，理论上与 GitHub 同步。但 secrets 和环境变量的备份依赖于手动操作或脚本执行，容易遗漏。应对方法是使用 GitHub Actions 自身来触发备份：创建一个专门的工作流，每天定时调用 API 导出环境变量和仓库设置，并推送到异地存储。

恢复时发现 secret 值已过期

某些云服务商的密钥有有效期（例如 AWS IAM 用户密钥最长 90 天），备份的 secret 可能在恢复时已经失效。应对方法是在密钥管理服务中设置自动轮换策略，并确保备份脚本始终获取最新版本。

自托管 Runner 注册令牌过期

GitHub 的自托管 Runner 注册令牌有效期为 1 小时。恢复时必须重新生成令牌，这需要组织管理员权限。演练中应明确记录谁有权限生成令牌，以及生成令牌的 API 调用方式。

异地存储的访问权限丢失

如果异地存储的访问密钥也存储在 GitHub 中，那么当 GitHub 不可用时，可能同时丢失备份和访问权限。应对方法是将异地存储的访问权限交给至少两个不同的管理员，并使用独立于 GitHub 的身份认证方式（例如 IAM 角色而非用户密钥）。

工具选择建议

以下工具在 GitHub CI/CD 备份场景中经过验证：

• **git clone --mirror**：最基础的代码备份方式，无需额外工具。
• **GitHub CLI (gh)**：用于导出仓库设置、环境变量和 secrets 的元数据。注意 gh 无法获取 secret 值。
• **gh-sync**：一个开源工具，可以将 GitHub 仓库镜像到其他 Git 平台，支持定时同步。
• **Terraform**：如果使用 Terraform 管理 GitHub 资源（仓库、分支保护规则、Webhook），那么 Terraform state 本身就是一份可恢复的备份。
• **HashiCorp Vault**：集中管理 secrets，支持动态密钥和自动轮换，避免在 GitHub 中存储长期有效的 secret。

选择工具时优先考虑开源和 API 驱动的方式，避免依赖单一厂商的专有备份方案。SystemDo 在多个项目中采用 Terraform 管理 GitHub 资源，结合 Vault 管理 secrets，备份和恢复的自动化程度较高。

总结：备份是手段，可恢复才是目标

GitHub CI/CD 的备份与灾备不是一次性的配置工作，而是需要持续维护的工程实践。核心要点是：

1. 明确备份范围，不要只备份代码而忽略 secrets 和 runner 配置。
2. 根据发布频率设定合理的 RPO 和 RTO，并确保团队对这些目标有共识。
3. 备份数据必须异地保存，且要定期验证可读性。
4. 恢复演练是唯一能验证备份有效性的手段，至少每季度执行一次全量演练。

如果团队目前还没有建立 CI/CD 备份机制，可以从最基础的代码镜像开始，然后逐步添加 secrets 备份和仓库设置导出。每增加一个备份项，就立即编写对应的恢复步骤，并在下一次演练中验证。这样逐步迭代，比一次性追求完美方案更可行。