API 网关集群迁移

集群迁移是指在保持软件版本不变的情况下，将整个 API7 企业版部署从一个基础设施环境移动到另一个基础设施环境的过程。本指南专为平台工程师和架构师设计，适用于数据中心迁移、基础设施升级或在不同云服务提供商之间切换等需要零停机迁移的场景。

与版本升级不同，集群迁移侧重于将现有部署平滑地移动到一个新的、并行的环境，而控制面（CP）或数据面（DP）的版本不会改变。该策略的核心是通过备份生产数据库并将其在新的集群中恢复来确保配置和数据的完整性。接着，使用负载均衡器逐步引导流量，从而实现无缝过渡并提供可靠的回滚方案。

这种方法不仅降低了与基础设施变更相关的风险，而且有效避免了常见的潜在问题，比如新的数据面错误地连接到旧的控制面时可能会发生的 mTLS 证书不匹配问题。

迁移工作流

下图展示了零停机时间集群迁移的工作流：

上图展示了完整的迁移工作流。在准备新集群（集群 B）的同时，旧集群（集群 A）继续处理生产环境的流量。一旦新集群被验证且健康状态良好，就可以通过负载均衡器逐步将流量从旧集群切换到新集群。

前提条件

在开始集群迁移之前，请确保满足以下前提条件，以保证迁移过程顺利且成功。

前提条件	描述
新集群基础设施	必须完成新集群（集群 B）基础设施的全部配置，包括所有网络、存储和计算资源。
安装 API7 企业版	必须在新集群上安装与旧集群（集群 A）中运行版本完全相同的 API7 企业版。
数据库工具	必须为旧数据库和新数据库环境配置并测试好数据库备份和恢复工具。
负载均衡器	必须配备一个外部负载均衡器，该负载均衡器应具备管理和在旧集群与新集群之间分配流量的能力。
权限	你必须具备必要的管理员权限，以便从旧集群执行数据库备份并能够在新集群上执行恢复操作。
迁移前测试	应该在暂存或测试环境中进行一次完整的迁移演练，以验证整个流程并识别任何潜在的问题。

迁移步骤

按照以下步骤执行零停机时间集群迁移。该过程经过精心设计，采用循序渐进的方式，并在每个阶段均包含验证检查，以确保过渡安全平稳。

步骤 1：冻结旧集群的配置变更

为了防止迁移过程中的数据不一致，必须在旧集群（集群 A）上实施配置冻结。向你的开发团队宣布维护窗口期，并暂停所有通过 API7 控制台（Dashboard）、Admin API 或其他配置管理工具进行的配置变更。

此冻结操作可以确保你创建的数据库备份包含生产配置的完整且静态的快照。备份之后进行的任何变更都不会被迁移到新集群中。

步骤 2：备份和恢复数据库

一旦配置冻结生效，请继续从旧集群备份数据库，并将其恢复到新集群。

1. 备份数据库 A：从集群 A 执行数据库的完整备份。确保备份包含所有 API 配置、路由、插件、消费者凭证以及 SSL 证书。详细说明请参阅数据库备份和恢复指南。
2. 传输并恢复至数据库 B：将备份文件传输至新集群环境，并将其恢复至数据库 B。恢复完成后，通过检查 API、路由和其他关键配置对象的数量来验证数据的完整性。

步骤 3：启动并验证新集群

随着数据库恢复完毕，现在你可以将新集群（集群 B）上线。

1. 启动控制面 B：启动新集群中的控制面（CP），并确保它成功连接到已恢复的数据库（数据库 B）。
2. 验证 DP Manager 地址：在部署数据面之前，请验证新集群中的 DP Manager 地址是否已正确配置并指向新的控制面。你可以在控制面的**网关设置 > 部署（Gateway Settings > Deployment）**页面中进行检查，或者在部署方法中更新该配置：
   • 对于 Helm 部署，请更新 values.yaml 文件中的 etcd.host[0] 值。
   • 对于 Docker/Docker Compose 部署，请确保部署配置中的 API7_DP_MANAGER_ENDPOINTS 地址指向新的控制面。
3. 验证健康状态：使用网关健康探测来确认新的数据面（DP）是否已运行且状态健康。你还应该检查 CP 和 DP 的日志，以确保没有出现连接错误。

步骤 4：逐步切换流量

一旦新集群开始运行并得到验证，你就可以开始使用外部负载均衡器将生产环境的流量逐步切换至新集群。

1. 初始流量切分：配置负载均衡器，将一小部分流量（例如 5-10%）发送到新集群的数据面（DP B）。
2. 监控和验证：密切监控新集群的性能，包括延迟、错误率和资源利用率。将这些指标与旧集群进行对比，以确保新集群按预期运行。
3. 逐步增加流量：如果新集群保持稳定，可以分阶段（例如 25%、50%、75%、100%）逐步增加流量比例。在每个阶段，都要持续监控系统的健康状况和性能表现。

步骤 5：完成迁移

当 100% 的流量都被导向新集群，并且它已稳定运行了一段时间（例如 24-48 小时）后，即可认为迁移工作已完成。

此时，你可以停用旧集群（集群 A）。作为最后一道安全防线，建议在将旧集群永久关闭之前，让其保持待命状态几天。

重要注意事项

迁移生产集群需要周密的规划和对细节的高度关注。以下是整个过程中需要牢记的一些关键注意事项。

mTLS 证书不匹配

集群迁移中常见的一个故障点是新的数据面（DP）尝试连接到旧的控制面（CP）。每个 API7 企业版集群在 CP 和 DP 之间的安全通信都使用一套独一无二的 mTLS 证书。如果来自集群 B 的 DP 尝试连接到来自集群 A 的 CP，连接将因证书不匹配而被拒绝，DP 也会因此无法启动。

为避免这种情况，请始终确保 DP 的配置文件（config.yaml）指向其所属集群内的正确 CP 地址。如果你使用域名访问控制面，请务必更新 DNS 配置，以便新数据面能够解析到新控制面的地址。

数据一致性

实施配置冻结对于维护数据一致性至关重要。如果在执行数据库备份之后在旧集群上进行了配置更改，则该更改将不会出现在新集群中。如果不可避免地需要进行紧急更改，则必须手动将其应用到两个集群，以防止出现不一致的情况。

有状态的插件

对于依赖外部状态存储的插件，例如使用 Redis 的 rate-limiting 插件，需要特别注意。如果每个集群使用独立的 Redis 实例，其状态（如限流计数器）将不会同步。在流量切分阶段，这可能会导致暂时的误差，比如用户发起的请求可能超过配置的限额。

为减轻这一影响，你可以让两个集群共享同一个 Redis 实例，或者接受在迁移期间暂时的状态不一致。

回滚计划

双集群迁移策略的一个核心优势是能够实现即时回滚。如果在流量切换阶段新集群遇到任何问题，你可以通过负载均衡器立即将所有流量重新导向旧集群。在对新集群的稳定性和性能完全建立信心之前，请保持旧集群继续运行。

最佳实践

遵循以下最佳实践将有助于确保集群平稳、成功地完成迁移。

在非生产环境中进行演练：在迁移生产集群之前，请在暂存或测试环境中进行一次完整的预演。这种演练使你能够验证迁移过程、识别潜在问题并完善你的程序，而且不会影响线上流量。

安排在非高峰时段进行：将迁移规划在业务活动较少的时段进行，以尽量减少对用户造成的影响。尽管该迁移过程是为零停机而设计的，但在非高峰时段执行可以提供额外的安全保障。

制定详细的回滚计划：记录下一份清晰、可操作的回滚计划，以便在出现问题时能够迅速执行。该计划应包含将所有流量重新引回旧集群的具体步骤以及触发回滚的条件。

保持沟通：在整个迁移过程中，与所有相关的团队（包括开发、运维和业务相关人员）保持顺畅的信息互通。建立一个沟通渠道，以便于实时更新状态和升级处理问题。

记录迁移过程：记录下迁移期间执行的所有操作，包括配置变更、流量百分比以及观察到的所有异常情况。这些文档对于迁移后的分析以及未来的迁移工作都具有很高的参考价值。

持续监控：运用全面的监控和告警工具，在迁移期间跟踪两个集群的健康状况和性能指标。需要重点监控的关键指标包括请求延迟、错误率、吞吐量、CPU 使用率、内存消耗以及数据库连接状态。