升级 API7 网关
本指南介绍了如何将 API7 网关从旧版本升级至最新版本的全过程。你可以根据你的 API7 网关部署架构来确定升级路径。此外，本文档还解释了升级过程中需要考虑的重要因素以及如何备份和恢复数据。
API7 网关 v3.x.x 版本之间的升级主要涉及**控制面（Control Plane，简称 CP）和数据面（Data Plane，简称 DP）**的更新。由于所有 v3.x.x 版本在架构上均保持兼容，本文档将指导你采用以下升级策略：
- 原地升级（In-Place Upgrade）
- 控制面（CP）原地升级：此策略在原地升级控制面的同时，复用现有的数据库。
- 数据面（DP）滚动升级：此策略通过逐步添加新版本的数据面节点并关闭旧节点，确保实现零停机。
- 双集群升级（Dual-Cluster Upgrade）
- 此策略涉及在现有的生产集群（集群 X）旁边，部署一个全新的、并行的 集群（集群 Y）。
升级概览
准备阶段
- 查看当前版本与目标版本之间的完整更新日志和兼容性说明。
- 确认要执行的升级策略。
- 查看升级注意事项；对于 Kubernetes 部署，还需包含 Ingress Controller 资源更新。
- 数据库备份。
- 在测试或预发环境中进行升级测试。
执行升级
在完成准备阶段并确认所有操作均正确无误后，你可以按照在测试环境中执行的流程开始升级生产环境。
受支持的升级路径
API7 网关的版本号遵循标准的语义化结构，以 a.b.c 为例，分别代表主版本号（a）、次版本号（b）和修订版本号（c）。默认情况下，API7 网关 v3 在以下版本之间执行了升级测试，以确保升级过程平滑顺利：
- 相同主版本号和次版本号下的修订版本之间的升级，例如（
3.3.0至3.3.1）。 - 相同主版本号下相邻次版本之间的升级，例如（
3.3.x至3.4.x）。
虽然 API7 网关已经进行了升级测试，但在执行升级之前，你仍应遵循文档中的步骤并在你自己的环境中进行测试。
数据备份策略
在执行升级之前，请确保已经备份数据库和声明式配置文件。
- 数据库备份：API7 网关默认使用 PostgreSQL 数据库。你可以使用原生的导出（
pg_dump）和导入（pg_restore）命令来备份或恢复你的数据库。 - 声明式配置文件备份：API7 网关提供了声明式管理工具 ADC，支持通过声明式配置文件来管理 API7 网关的服务、路由、消费者、插件等配置。
强烈建议尽可能同时使用这两种方法备份数据，以便在恢复时获得更大的灵活性。如果在测试升级期间遇到问题并需要立即回滚，请参阅备份和恢复指南恢复旧数据。
升级策略
建议根据本指南中描述的升级策略来完成升级。
在升级过程中，你应该考虑 API7 网关的停机时间并制定合理的升级计划，因为在升级过程中无法通过 API 或控制台（Dashboard）修改或更新数据。
下图说明了整个升级过程的运作方式：
原地升级
控制面（CP）原地升级
在升级 DP 之前必须先升级 CP。由于 CP 需要与数据库交互，所以在升级过程中请勿使用 API 或其他方式更改你当前的数据。下图展示了如何实施原地升级策略。
- 直接用新版
CP B替换现有的CP A，升级过程中它 们共享同一个数据库。 - 升级完成后，现有的
DP A节点将自动连接到新的CP B。
在控制面（CP）的升级过程中，如上图所示，DP A 中的节点会保持与 CP A 或 CP B 的连接。API7 网关确保了新版本控制面与旧版本数据面之间的向下兼容。因此，在运行不同版本的 CP 和 DP 时，请在控制面的**网关实例（Gateway Instances）**页面检查每个 DP 节点的状态，并根据提示升级被标记为不兼容的任何 DP 节点。
建议每次升级时保持 CP 和 DP 版本一致，以确保万无一失。
数据面（DP）滚动升级
CP 升级完成后，你可以继续升级 DP 节点。对于 DP 升级，强烈建议采用滚动升级的方法，以避免出现停机。下图展示了如何实施滚动升级策略。
- 新的
CP B复用当前数据库，当前的DP A继续处理 API 请求。 - 使用滚动升级，将
DP A中的节点逐步替换为DP B的新节点。新的DP B节点更新后，也将开始处理 API 请求。
双集群升级
双集群升级是 API7 网关最安全、最稳健的升级方法，专为那些对零停机和极低风险有严苛要求的关键任务环境而设计。此策略包含在现有的生产集群（集群 X）旁边，部署一个完全独立、并行的全新集群（集群 Y）。每个集群都是完全独立的，具有各自的控制面、数据面和数据库。
通过外部负载均衡器将流量从旧集群逐步转移到新集群。这使得在新集群承受完整的生产流量之前，可以用一小部分真实流量对其进行全面测试。由于旧集群保持原样，一旦出现任何问题，你可以立即将所有流量重新切回旧集群以实现快速回滚。
下图展示了双集群升级架构：
检查重大变更和更新日志
根据当前版本和目标版本，请查看两个版本之间的所有 Release Notes，并以此为准，在升级前了解重大变更、废弃功能和所需的配置更新。
升级注意事项
无论你如何部署 API7 网关，有一些普遍因素会影响升级过程。在开始升级之前，请注意：
- 在升级过程中，禁止对数据库进行任何更改。在升级完成之前，请勿通过 API 或控 制台（Dashboard）修改任何数据。
- 请仔细阅读当前版本与目标版本之间的所有 Release Notes，检查功能移除、API 变更或所需配置更新等潜在冲突。
- 如果使用自定义插件，请检查 Release Notes 中的核心修改，并在运行新版本的测试环境中验证自定义插件。
- 始终必须执行数据库备份。请确保每次升级前都已备份数据。
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 写入中断时，都需要考虑后端端点的变化。