规划 API7 网关升级
API7 网关升级始于一条受支持的源版本到目标版本路径。该路径定义了确切的制品、兼容性变更、迁移规则和回滚约定。确认路径后，可使用本页介绍的部署策略完成控制面（Control Plane，CP）和数据面（Data Plane，DP）变更。
对于 LTS 到 LTS 的升级，请从选择 LTS 升级路径开始。对于补丁版本升级或相邻次版本升级，请在发布说明或 API7 支持团队方案中确认确切的版本组合。
升级准备
准备工作需要在开始生产变更前明确源状态、目标清单、验收标准和可恢复的回滚点。
- 确认确切的源版本和目标版本，以及适用的特定版本路径指南或发布说明。
- 清点生产拓扑、数据库引擎、CP 和 DP 副本、网关组、插件、身份提供方、上游、自动化和外部有状态依赖。
- 查看源版本与目标版本之间所有会影响运维的变更。
- 从目标软件包默认配置开始构建新的目标清单。固定明确的镜像和 Chart 版本，并重新应用经过审查的生产设置。
- 定义变更负责人、观察期、验收标准、中止阈值、回滚负责人和回滚期限。
- 使用恢复的类生产数据库、代表性配置以及公开和身份认证流量，演练完整的升 级和回滚。
备份数据并进行恢复测试
每次升级前都要创建数据库原生备份，并将其恢复到隔离数据库。在将备份视为权威恢复来源前，验证恢复后的源版本和代表性 CP 资源。
同时使用 ADC 导出每个网关组的声明式配置。ADC 仅作为辅助配置检查：它不包含用户、角色、API 产品、审计数据或所有其他 CP 资源，因此不能替代数据库备份。
在回滚期限结束前，保留不可变的源备份、源清单、证书、Chart 和镜像。CP 迁移后创建的备份属于目标版本快照，不能替代完整回滚所需的源备份。
选择控制面策略
先升级 CP，再升级 DP。请选择确切版本路径和生产拓扑所支持的策略。
| 策略 | 适用场景 | 生产影响 | 回滚依据 |
|---|---|---|---|
| CP 就地升级 | 复用当前数据库，避免创建第二个完整集群。 | 源 CP 进程停止并启动目标 CP 期间，控制台和 Admin API 不可用。如果版本路径允许混合版本窗口，现有 DP 可以继续代理。 | 停止目标 CP，将不可变源备份恢复到新数据库，然后再恢复源版本二进制文件。 |
| 双集群升级 | 运行相互独立的源集群和目标集群，并逐步切换流量。 | 需要两个能够承载生产流量的集群、独立数据库、外部负载均衡器，以及写入冻结或经过测试的协调方案。 | 只有与回滚相关的写入保持冻结或已经协调时，流量才能返回源集群。 |
升级数据面
CP 就地升级后，在目标 CP 健康且混合版本兼容性门禁通过后，使用数据面滚动升级替换源节点。先添加并验证目标容量，再排空源节点。每个目标节点都必须报告 Healthy 和 Compatible，通过直接的代表性流量测试，并在移除源节点前加入生产负载均衡器。对于双集群策略，请遵循特定版本路径指南中的目标 DP 和流量切换顺序。
就地升级顺序如下：
升级注意事项
除非特定版本路径规定了更严格的要求，否则以下要求适用于所有策略：
- 从创建最终源备份开始，到验收或回滚完成为止，始终冻结管理写入。
- 切勿让源版本和目标版本 CP 同时连接同一个数据库。
- 仅当确切版本路径允许时，才能将 CP 和 DP 混合版本视为临时状态。
- 针对目标版本测试自定义插件、NGINX 代码片段、身份认证、日志、指标、缓存、限流、上游健康 检查和自动化。
- 保留足够的源容量和制品，以便在期限前执行文档规定的回滚。
- 不要依赖
helm rollback或--atomic撤销数据库迁移。
确认验收与回滚
结束写入冻结前，请验证目标版本、CP 资源、DP 兼容性报告、公开和身份认证流量、日志、指标、数据库健康状态以及每一项特定版本路径的验收标准。
如果达到中止阈值，请继续冻结写入并执行预定义的回滚。只有指定的决策负责人记录了验收结果，或确认回滚和所有必需的协调操作均已完成后，才能恢复写入。
继续执行适用指南
- LTS 到 LTS：选择确切的 LTS 升级路径，并遵循对应版本组合的流程。
- 使用 CP 就地升级的补丁版本或相邻次版本升级：确认确切的受支持版本组合，先执行控制面就地升级，再完成数据面滚动升级。
- 使用双集群的补丁版本或相邻次版本升级：确认确切的受支持版本组合，然后按照双集群升级部署目标集群并切换流量。
- 备份与恢复详情： 备份与恢复。