计划性故障转移的灾难恢复

灾难恢复的主要用途是在发生意外停机时确保业务连续性，但它也可以与计划性故障转移结合使用，以在区域间迁移您的 GitLab 实例，而不会造成长时间停机。

由于 Geo 站点之间的复制是异步的，计划性故障转移需要一个维护窗口，在此期间对 主站点 的更新会被阻塞。此窗口的长度取决于您的复制能力 - 当 从站点 与 主站点 完全同步时，就可以进行故障转移而不会造成数据丢失。

本文档假设您已经有一个完全配置好的、可正常工作的 Geo 设置。在继续之前，请完整阅读本文档和 灾难恢复 故障转移文档。计划性故障转移是一项重大操作，如果执行不当，有很高的数据丢失风险。建议您演练该流程，直到熟悉必要的步骤，并有高度信心能够准确执行它们。

故障转移建议

遵循以下建议将有助于确保故障转移过程顺利进行，并最大限度地减少数据丢失或长时间停机的风险。

解决同步和验证失败问题

如果在 预检检查 期间存在失败或排队的项目，则故障转移将被阻塞，直到这些项目被以下任一方式处理：

• 已解决：成功同步（如有必要可手动复制到从站点）并验证。
• 记录为可接受：有明确的理由，例如：
  • 对这些特定失败进行了手动校验和比较并已通过。
  • 仓库已弃用，可以排除。
  • 项目非关键，将在故障转移后复制。

有关诊断同步和验证失败的帮助，请参阅 排查 Geo 同步和验证错误。

规划数据完整性解决方案

在故障转移完成前预留 4-6 周，以解决首次设置 Geo 复制后常见的数据完整性问题，例如孤立的数据库记录或不一致的文件引用。 有关指导，请参阅 排查常见 Geo 错误。

尽早开始解决同步问题，以避免在维护窗口期间做出艰难决定：

1. 故障转移前 4-6 周：识别并开始解决 outstanding 的同步问题
2. 故障转移前 1 周：解决或记录所有剩余同步问题的目标
3. 故障转移前 1-2 天：解决任何新出现的失败
4. 故障转移前几小时：最后检查是否有任何新失败

进行/中止决策：明确因未解决的同步错误而中止故障转移的标准。

在 Geo 环境中测试备份时机

提前测试备份程序，并考虑：

• 直接从主站点进行备份（可能会影响性能）。
• 使用专用的、与复制断开连接的只读副本。
• 在低活动期间安排备份。

准备全面的回滚程序

记录恢复到原始主站点的具体步骤，包括：

• 中止故障转移的决策标准
• DNS 回滚程序
• 重新启用原始主站点的流程（参见 将降级的主站点重新上线）
• 用户沟通计划

在暂存环境中制定故障转移运行手册

详细地实践和记录高度手动化的任务，确保成功。

1. 如果您还没有类似生产环境的环境，请准备一个。
2. 冒烟测试。例如，添加组、添加项目、添加 Runner、使用 Git push、向问题添加图片。
3. 故障转移到从站点。
4. 冒烟测试。查找问题。
5. 在进行过程中，记下每个执行的操作、执行者、预期结果、资源链接。
6. 根据需要重复，以完善运行手册和脚本。

并非所有数据都会自动复制

如果您使用任何 Geo 不支持的 GitLab 功能，您必须单独采取措施确保 从站点 拥有与该功能相关的任何数据的最新副本。这可能会显著延长所需的计划维护时间。支持 Geo 的功能列表可以在 复制数据类型表 中找到。

对于存储在文件中的数据，尽可能缩短此期间的常见策略是使用 rsync 传输数据。可以在维护窗口之前执行初始 rsync；随后的 rsync（包括维护窗口内的最终传输）则只传输 主站点 和 从站点 之间的变更。

有效使用 rsync 的以 Git 仓库为中心的策略可以在 迁移仓库 文档中找到；这些策略可以适应用于任何其他基于文件的数据。

容器注册表

默认情况下，容器注册表不会自动复制到从站点，这需要手动配置，请参见 从站点的容器注册表。

如果您在当前主站点上使用本地存储来存放容器注册表，可以将容器注册表对象 rsync 到您即将故障转移到的从站点：

# 在从站点上运行
rsync --archive --perms --delete root@<geo-primary>:/var/opt/gitlab/gitlab-rails/shared/registry/. /var/opt/gitlab/gitlab-rails/shared/registry

或者，您可以在主站点上 备份 容器注册表，并将其恢复到从站点：

1. 在您的主站点上，仅备份注册表并 从备份中排除特定目录：

   # 在 /var/opt/gitlab/backups 文件夹中创建备份
   sudo gitlab-backup create SKIP=db,uploads,builds,artifacts,lfs,terraform_state,pages,repositories,packages

2. 将从主站点生成的备份 tar 文件复制到您从站点的 /var/opt/gitlab/backups 文件夹中。

3. 在您的从站点上，按照 恢复 GitLab 文档恢复注册表。

恢复高级搜索的数据

高级搜索由 Elasticsearch 或 OpenSearch 提供支持。 高级搜索的数据不会自动复制到从站点。

要在新提升的主站点上恢复高级搜索数据：

预检检查

运行以下命令列出所有预检检查，并在计划故障转移前自动检查复制和验证是否完成，确保过程顺利进行：

gitlab-ctl promotion-preflight-checks

每个步骤在下面有更详细的描述。

DNS TTL

如果您计划 更新主站点域名的 DNS 记录，您可能希望保持较低的 TTL 以确保 DNS 变更能够快速传播。

对象存储

如果您有大型 GitLab 安装或无法容忍停机，请考虑在计划故障转移之前 迁移到对象存储。这样做可以缩短维护窗口的长度，并降低因执行不当的计划故障转移而导致数据丢失的风险。

在 GitLab 15.1 中，您可以选择允许 GitLab 管理 从站点 的对象存储复制。有关更多信息，请参阅 对象存储复制。

检查每个 从站点 的配置

数据库设置会自动复制到 从站点，但 /etc/gitlab/gitlab.rb 文件必须手动设置，并且各站点之间有所不同。如果在 主站点 上启用了 Mattermost、OAuth 或 LDAP 集成等功能，但在 从站点 上未启用，这些功能在故障转移期间将会丢失。

在计划故障转移之前，请检查两个站点的 /etc/gitlab/gitlab.rb 文件，并确保 从站点 支持 主站点 所有的功能。

运行系统检查

在 主站点 和 从站点 上运行以下命令：

gitlab-rake gitlab:check
gitlab-rake gitlab:geo:check

如果任一站点报告任何失败，应在计划故障转移之前解决这些失败。

检查节点之间的密钥和 SSH 主机密钥是否匹配

SSH 主机密钥和 /etc/gitlab/gitlab-secrets.json 文件在所有节点上应该相同。通过在所有节点上运行以下命令并比较输出来检查：

sudo sha256sum /etc/ssh/sshhost /etc/gitlab/gitlab-secrets.json

如果任何文件不同，请根据需要 手动复制 GitLab 密钥 和 复制 SSH 主机密钥 到 从站点。

检查是否安装了正确的 HTTPS 证书

如果 主站点 和 主站点 访问的所有外部站点都使用公共 CA 颁发的证书，则可以安全地跳过此步骤。

如果 主站点 使用自定义或自签名的 TLS 证书来保护入站连接，或者 主站点 连接到使用自定义或自签名证书的外部服务，则正确的证书也应安装在 从站点 上。请遵循 使用自定义证书 的说明，用于 从站点。

确保 Geo 复制是最新的

在 Geo 复制和验证完全完成之前，维护窗口不会结束。为了尽可能缩短窗口时间，您应该确保这些进程在活动使用期间尽可能接近 100%。

在 从站点 上：

1. 在左侧边栏底部，选择 管理员。

2. 选择 Geo > 站点。 复制的对象（显示为绿色）应接近 100%，并且不应有任何失败（显示为红色）。如果大部分对象尚未复制（显示为灰色），请考虑给站点更多时间来完成

   

如果有任何对象复制失败，应在安排维护窗口之前进行调查。在计划故障转移后，任何未能复制的对象都将 丢失。

复制失败的常见原因是数据在 主站点 上缺失 - 您可以通过从备份恢复数据或删除对缺失数据的引用来解决这些失败。

验证复制数据的完整性

此 内容已移至其他位置。

通知用户计划维护

在 主站点 上：

1. 在左侧边栏底部，选择 管理员。
2. 选择 消息。
3. 添加一条关于维护窗口的通知消息。 您可以在 Geo > 站点 下查看以估计完成同步所需的时间。
4. 选择 添加广播消息。

Runner 故障转移

根据您的实例 URL 配置方式，故障转移后可能需要额外步骤来保持您的 Runner 队列在 100% 状态。

用于注册 Runner 的令牌应该在主站点或从站点实例上都能正常工作。如果您在故障转移后看到连接问题，可能是密钥在 从站点配置 期间没有复制过来。您可以 重置 Runner 令牌，但请注意，如果密钥不同步，您可能会遇到与 Runner 无关的其他问题。

如果 Runner 反复无法连接到 GitLab 实例，它会在一段时间内（默认为 1 小时）停止尝试连接。如果您想避免这种情况，应该关闭 Runner 直到 GitLab 实例可访问。请参阅 the check_interval documentation，以及配置选项 unhealthy_requests_limit 和 unhealthy_interval。

• 如果您使用我们的位置感知 URL，在旧主站点从 DNS 配置中移除后，Runner 应该会自动连接到最近的实例。
• 如果您使用单独的 URL，则任何连接到当前主站点的 Runner 在提升后都需要更新以连接到新的主站点。
• 如果您有任何连接到当前从站点的 Runner，请参阅 如何处理它们。

阻止对 主站点 的更新

为确保所有数据都复制到从站点，需要在 主站点 上禁用更新（写入请求）：

1. 在 主站点 上启用 维护模式。

2. 在左侧边栏底部，选择 管理员。

3. 选择 监控 > 后台任务。

4. 在 Sidekiq 仪表板上，选择 Cron。

5. 选择 禁用全部 以禁用非 Geo 定期后台任务。

6. 为以下 cronjob 选择 启用：

   • geo_metrics_update_worker
   • geo_prune_event_log_worker
   • geo_verification_cron_worker
   • repository_check_worker

   这重新启用了几个对成功完成计划故障转移至关重要的 cron 任务。

完成所有数据的复制和验证

1. 如果您手动复制任何不由 Geo 管理的数据，现在触发最终复制过程。

2. 在 主站点 上：

   1. 在左侧边栏底部，选择 管理员。

   2. 在左侧边栏，选择 监控 > 后台任务。

   3. 在 Sidekiq 仪表板上，选择 队列，并等待除名称中包含 geo 的队列外，所有队列都降至 0。 这些队列包含您的用户提交的工作；在完成之前进行故障转移会导致工作丢失。

   4. 在左侧边栏，选择 Geo > 站点，并等待您要故障转移到的 从站点 满足以下条件：

      • 所有复制指标都达到 100% 已复制，0% 失败。
      • 所有验证指标都达到 100% 已验证，0% 失败。
      • 数据库复制延迟为 0 毫秒。
      • Geo 日志游标是最新的（0 个事件落后）。

3. 在 从站点 上：

   1. 在左侧边栏底部，选择 管理员。
   2. 在左侧边栏，选择 监控 > 后台任务。
   3. 在 Sidekiq 仪表板上，选择 队列，并等待所有 geo 队列降至 0 个排队和 0 个正在运行的任务。
   4. 运行完整性检查 以验证文件存储中的 CI 工件、LFS 对象和上传的完整性。

此时，您的 从站点 包含 主站点 所有的最新副本，这意味着您在故障转移时没有丢失任何内容。

提升 从站点

复制完成后，将 从站点 提升为 主站点。此过程会导致 从站点 出现短暂中断，用户可能需要重新登录。如果您正确遵循步骤，旧的 Geo 主站点应该仍然被禁用，用户流量应该流向新提升的站点。

提升完成后，维护窗口结束，您的新 主站点 现在开始与旧站点分离。如果此时出现问题，回退到旧的主站点 是可能的，但很可能会导致在此期间上传到新 主站点 的任何数据丢失。

故障转移完成后，别忘了删除广播消息。

最后，您可以将 旧站点作为从站点带回。