升级 API7 网关
本指南介绍如何将 API7 网关从旧版本升级至最新版本。你可以根据 API7 网关的部署架构确定升级路径。本文档还介绍升级过程中的重要注意事项，以及如何备份和恢复数据。
API7 网关 v3.x.x 版本之间的升级主要涉及**控制面（Control Plane，简称 CP）和数据面（Data Plane，简称 DP）**的更新。由于所有 v3.x.x 版本在架构上均保持兼容，本文档将指导你采用以下升级策略：
升级概览
准备阶段
执行升级
在完成准备阶段并确认所有操作均正确无误后，你可以按照在测试环境中执行的流程开始升级生产环境。
受支持的升级路径
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 或控制台修改或更新数据。
下图说明了整个升级过程的运作方式：
就地升级
控制面就地升级
在升级 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 版本一致，以确保万无一失。
数据面滚动升级
CP 升级完成后，你可以继续升级 DP 节点。对于 DP 升级，强烈建议采用滚动升级的方法，以避免出现停机。下图展示了如何实施滚动升级策略。
- 新的
CP B复用当前数据库，当前的DP A继续处理 API 请求。 - 使用滚动升级，将
DP A中的节点逐步替换为DP B的新节点。新的DP B节点更新后，也将开始处理 API 请求。
双集群升级
双集群升级是 API7 网关最安全、最稳健的升级方法，专为对零停机和极低风险有严格要求的关键任务环境而设计。此策略会在现有的生产集群（集群 X）旁边部署一个完全独立、并行的新集群（集群 Y）。每个集群都具有独立的控制面、数据面和数据库。
通过外部负载均衡器将流量从旧集群逐步转移到新集群。这使得在新集群承受完整的生产流量之前，可以用一小部分真实流量对其进行全面测试。由于旧集群保持原样，一旦出现任何问题，你可以立即将所有流量重新切回旧集群以实现快速回滚。
下图展示了双集群升级架构：
检查重大变更和更新日志
根据当前版本和升级的目标版本，查看两个版本之间的所有更新日志。更新日志是重大变更、弃用项和必要配置更新的事实来源，请在升级前据此完成准备。
升级注意事项
无论如何部署 API7 网关，都有一些普遍因素会影响升级过程。在开始升级之前，请注意：
- 在升级过程中，禁止对数据库进行任何更改。在升级完成之前，请勿通过 API 或控制台修改任何数据。
- 请仔细阅读当前版本和目标升级版本之间的更新日志。检查功能移除、API 变更或必要配置更新等潜在冲突。
- 如果你有自定义插件，请检查更新日志中是否有核心修改，并在新版本的测试环境中验证自定义插件可以正常工作。
- 每次升级前都必须按照备份与恢复备份数据。