规划 API7 网关升级
API7 网关升级始于一条受支持的源版本到目标版本路径。该路径定义了确切的制品、兼容性变更、迁移规则和回滚约定。确认路径后，可使用本页介绍的部署策略完成控制面（Control Plane，CP）和数据面（Data Plane，DP）变更。
对于 LTS 到 LTS 的升级，请从选择 LTS 升级路径开始。对于补丁版本升级或相邻次版本升级，请在发布说明或 API7 支持团队方案中确认确切的版本组合。
升级准备
准备工作需要在开始生产变更前明确源状态、目标清单、验收标准和可恢复的回滚点。
- 确认确切的源版本和目标版本，以及适用的特定版本路径指南或发布说明。
- 清点生产拓扑、数据库引擎、CP 和 DP 副本、网关组、插件、身份提供方、上游、自动化和外部有状态依赖。对于 Kubernetes 部署，请考虑 Ingress Controller 资源更新。
- 查看源版本与目标版本之间所有会影响运维的变更。
- 从目标软件包默认配置开始构建新的目标清单。固定明确的镜像和 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撤销数据库迁移。
Ingress Controller 资源更新
仅当你使用 API7 Ingress Controller 管理网关资源时，此警告才适用。
即使无人在控制台或 Admin API 中更改配置，控制器仍可能更新这些资源。准备备份、迁移到另一集群或回滚升级时，需要考虑这些自动更新。
API7 Ingress Controller 会监视 Kubernetes 资源，并通过 CP 同步网关配置。应用发布、自动扩缩容、Pod 重启和重调度都可能会更改后端端点，并在无人编辑路由的情况下触发上游更新。
如果受支持的升级流程会让 CP 保持可写，Ingress Controller 可以继续同步资源。请遵循所选升级流程的写入限制：CP 高可用不会取消数据库迁移所需的限制。
对于 PostgreSQL，pg_dump 即使在持续发生更新时也能创建一致性快照。但该备份不包含快照之后的更新。单独执行的 ADC 导出可能表示另一时间点的状态。因此，即使备份成功恢复，也不保证路由和上游与当前 Kubernetes 状态一致。
对于由 Ingress Controller 管理的部署：
- 确定控制器管理的资源和其他配置写入方，包括 ADC 任务和 GitOps 工作流。记录数据库备份和 ADC 导出的创建时间，并将 Kubernetes 资源定义与不可变的源备份一并保存。
- 对于双集群升级，备份后对源集群的更新不会自动包含在目标集群中。请规划并测试如何同步后续更改。在切换流量前，请确认控制器指向目标 CP，并使用当前 Kubernetes 资源验证目标路由和上游。
- 对于恢复或回滚，备份中可能包含已过期的后端地址。请演练在 CP 重新接受写入后如何同步控制器管理的资源。在宣布恢复完成前，检查控制器日志，根据当前 Kubernetes 端点验证网关上游，并测试受影响的路由。还需单独协调其他配置写入方引入的更改。
如果 CP 不可用或拒绝配置写入，端点更新将无法到达网关。现有 DP 节点会继续使用最后一份已接收的配置；如果已配置的 Pod IP 地址不再可用，这可能导致请求失败。计划任何 CP 写入中断时，都需要考虑后端端点的变化。
确认验收与回滚
结束写入冻结前，请验证目标版本、CP 资源、DP 兼容性报告、公开和身份认证流量、日志、指标、数据库健康状态以及每一项特定版本路径的验收标准。
如果达到中止阈值，请继续冻结写入并执行预定义的回滚。只有指定的决策负责人记录了验收结果，或确认回滚和所有必需的协调操作均已完成后，才能恢复写入。
继续执行适用指南
- LTS 到 LTS：选择确切的 LTS 升级路径，并遵循对应版本组合的流程。
- 使用 CP 就地升级的补丁版本或相邻次版本升级：确认确切的受支持版本组合，先执行控制面就地升级，再完成数据面滚动升级。
- 使用双集群的补丁版本或相邻次版本升级：确认确切的受支持版本组合，然后按照双集群升级部署目标集群并切换流量。
- 备份与恢复详情：备份与恢复。