跳到主要内容
版本：3.9.x

将 API7 网关迁移到新集群

集群迁移是在不改变控制面（CP）或数据面（DP）版本的情况下，将 API7 网关部署迁移到新的基础设施。它适用于数据中心或云服务商迁移以及基础设施更新，不应与产品升级合并实施。在使用恢复的数据库备份构建并验证独立的目标集群期间，源集群保持可用；随后由外部负载均衡器分阶段切换流量。

请求能否持续得到处理取决于两个集群的容量和健康状态、负载均衡器、连接排空、上游行为以及有状态依赖；双集群拓扑本身不能保证服务不中断。在最终源数据库备份前冻结与回滚相关的写入，并持续冻结至回滚期限结束；若需要提前恢复写入，必须使用经过测试的协调方案。

准备迁移​

在移动生产数据或流量之前，先确定目标环境、回滚边界和验收标准。

  1. 确认源集群与目标集群的 CP 和 DP 使用相同的已发布产品版本。
  2. 为目标集群准备独立的计算、网络、存储和数据库容量。在迁移及回滚窗口内，两个集群和外部负载均衡器都必须能够处理各自分配的流量。
  3. 保存源部署清单、Helm values 文件或相应部署参数、镜像标签、证书、外部依赖配置和部署自动化文件。
  4. 使用数据库原生工具创建备份，并将其恢复到隔离的数据库。在生产迁移前验证具有代表性的 CP 资源。参阅备份与恢复。
  5. 明确流量切换阶段、观察时间、验收标准、中止阈值、回滚负责人、回滚截止时间以及源集群保留期限。
  6. 使用近似生产环境的配置、具有代表性的公开和已认证流量，以及生产负载均衡器的行为，演练迁移和回滚。

冻结与回滚相关的写入​

宣布维护窗口，并阻止操作员、客户、自动化任务和集成程序通过控制台、Admin API、开发者门户、ADC、定时任务及直接数据库访问发起写入。

在冻结开始前，定义并演练后续恢复的写入如何同步到两个集群，或者如何在流量返回源集群前完成协调。记录每项允许的验证性写入，以及对应的清理或协调操作。

在最终源数据库备份和目标数据库恢复期间保持冻结。目标 CP 验证通过后，只有在经过测试的协调流程下，才能在回滚期限结束前恢复写入。该流程必须记录每项与回滚相关的写入，并支持在流量返回源集群之前协调源数据库。一旦恢复未经协调的写入，就不能再仅通过切换流量来回滚。

构建并验证目标集群​

目标集群的数据、组件和请求行为通过验证之前，不得接入生产流量。

  1. 停止或隔离所有可能访问目标数据库的目标 CP 组件。

  2. 创建最终源数据库备份，并恢复到独立的目标数据库。启动目标 CP 前，验证恢复后的数据库结构和具有代表性的资源。

  3. 以与源集群相同的产品版本启动目标 CP。确认控制台、Admin API、DP Manager、许可证、IAM 策略、网关组及集成服务运行正常。

  4. 在目标控制台打开 网关设置（Gateway Settings），将 DP Manager 地址（DP Manager Address） 设置为目标 DP 能访问的目标 DP Manager 端点。

  5. 对每个网关组，打开 网关实例（Gateway Instances），选择 添加网关实例（Add Gateway Instance），生成目标部署脚本。使用目标集群生成的连接参数和 mTLS 材料：

    • 对于 Helm 或 Kubernetes，确认生成的 values 将 etcd.host[...] 指向目标 DP Manager 端点，并使用生成的 TLS Secret。
    • 对于 Docker Compose，确认 API7_DP_MANAGER_ENDPOINTS、API7_DP_MANAGER_CERT、API7_DP_MANAGER_KEY 和 API7_CONTROL_PLANE_CA 均来自目标部署脚本。

  6. 在生产负载均衡器之外启动目标 DP，然后分别验证目标实例记录和从源数据库复制的实例记录：

    • 确认每条新建的目标 DP 记录均显示 Healthy 和 Compatible，且没有错误。
    • 恢复后的数据库还包含复制过来的源 DP 记录。其初始状态取决于复制的最后一次心跳时间。由于这些 DP 不会向目标 CP 发送心跳，尚未处于 Offline 状态的记录会随该时间戳推移先变为 LostConnection，再变为 Offline。仅在复制记录显示 Offline 后将其删除。
    • 配置并测试目标部署及负载均衡器使用的就绪和存活探针。

  7. 直接向目标 DP 发送具有代表性的公开和已认证请求。验证插件、上游、日志、指标、缓存、限流、健康检查和外部依赖。

切换生产流量​

先按计划向目标集群切换少量生产流量。典型顺序为目标流量占 5–10%、25%、50%，最后达到 100%；但应采用已针对生产负载均衡器和容量验证过的比例及观察时间。保留足够的源集群容量以供回滚。

每个阶段都需要：

  • 将响应码、延迟、日志、上游健康状态、资源使用情况和插件行为与源集群基线比较；
  • 确认两个集群都有足够容量；
  • 验证连接排空和负载均衡器的健康检查行为；
  • 检查有状态依赖和限流行为；
  • 达到中止阈值时停止切换。

只有上一阶段通过验证后才能继续增加目标流量。所有验收标准均满足后，才能将全部生产流量切换到目标 DP。

回滚​

只有在源集群仍然健康，且与回滚相关的写入一直保持冻结，或经过测试的协调流程已经完成时，才能将流量切回源 DP。流量重定向不会将目标数据库中的变更复制回源数据库。

如果仅切换流量无法安全回滚，应保持两个集群隔离并遵循事件处理计划。保留目标数据库和日志供调查。

完成迁移​

在规定的观察期内继续监控目标集群。与回滚相关的写入应持续冻结至仅切换流量的回滚截止时间。如果必须提前恢复写入，对每项新写入继续执行经过测试的协调流程；只有这些写入完成协调后才能将流量切回源集群。恢复未经协调的写入意味着仅切换流量的回滚窗口结束。

只有在回滚期限结束、监控和告警得到确认，并且保留的备份通过恢复测试后，才能记录最终验收结果并停用源 CP、DP 和数据库。

运维注意事项​

以下依赖需要单独验证，因为数据库恢复和流量切换不会自动同步其运行时状态。

有状态插件​

运行时指标和有状态插件数据不会自动同步。限流计数器可能保存在 DP 本地，也可能存储在 Redis 中。只有在测试过每个有状态插件与两个集群的兼容性后，才使用共享 Redis；否则，应量化并接受流量同时经过两个集群时出现的临时状态差异。

Ingress Controller​

最终备份后，API7 Ingress Controller 仍可能更新路由和上游端点。应规划目标集群如何接收这些更新，并在切换流量前根据当前 Kubernetes 资源核验其路由和上游。参阅Ingress Controller 资源更新。

目标连接材料​

DP 配置必须指向目标 CP，并使用为该目标签发的连接材料。将目标 DP 加入负载均衡器之前，检查其 CP 端点、网关组、证书和连接日志。