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

升级至 API7 企业版 3.x.x

本指南介绍了如何将 API7 企业版从旧版本升级至最新版本的全过程。你可以根据你的 API7 企业版部署架构来确定升级路径。此外，本文档还解释了升级过程中需要考虑的重要因素以及如何备份和恢复数据。

API7 企业版 v3.x.x 版本之间的升级主要涉及**控制面（Control Plane，简称 CP）和数据面（Data Plane，简称 DP）**的更新。由于所有 v3.x.x 版本在架构上均保持兼容，本文档将指导你采用以下升级策略：

  1. 原地升级（In-Place Upgrade）
  2. 双集群升级（Dual-Cluster Upgrade）
    • 此策略涉及在现有的生产集群（集群 X）旁边，部署一个全新的、并行的集群（集群 Y）。

升级概览​

升级 API7 企业版通常分为两个阶段：准备阶段和实施阶段。

准备阶段​

  1. 查看当前版本与目标版本之间的完整更新日志和兼容性说明。
  2. 确认要执行的升级策略。
  3. 查看升级注意事项。
  4. 数据库备份。
  5. 在测试或预发环境中进行升级测试。

执行升级​

在完成准备阶段并确认所有操作均正确无误后，你可以按照在测试环境中执行的流程开始升级生产环境。

受支持的升级路径​

API7 企业版的版本号遵循标准的语义化结构，以 a.b.c 为例，分别代表主版本号（a）、次版本号（b）和修订版本号（c）。默认情况下，API7 企业版 v3 在以下版本之间执行了升级测试，以确保升级过程平滑顺利：

  1. 相同主版本号和次版本号下的修订版本之间的升级，例如（3.3.0 至 3.3.1）。
  2. 相同主版本号下相邻次版本之间的升级，例如（3.3.x 至 3.4.x）。
信息

虽然 API7 企业版已经进行了升级测试，但在执行升级之前，你仍应遵循文档中的步骤并在你自己的环境中进行测试。

数据备份策略​

在执行升级之前，请确保你已经备份了你的数据库和声明式配置文件。

  1. 数据库备份：API7 企业版默认使用 PostgreSQL 数据库。你可以使用原生的导出（pg_dump）和导入（pg_restore）命令来备份或恢复你的数据库。
  2. 声明式配置文件备份：API7 企业版提供了声明式管理工具 ADC，支持通过声明式配置文件来管理 API7 企业版的服务、路由、消费者、插件等配置。

强烈建议在可能的情况下同时使用这两种方法来备份数据，这可以在数据恢复时提供极大的灵活性。如果在测试升级过程中遇到任何问题并需要立即回滚，请参阅备份和恢复指南以恢复你的旧数据。

升级策略​

建议根据本指南中描述的升级策略来完成升级。

在升级过程中，你应该考虑 API7 企业版的停机时间并制定合理的升级计划，因为在升级过程中无法通过 API 或控制台（Dashboard）修改或更新数据。

下图说明了整个升级过程的运作方式：

原地升级​

控制面（CP）原地升级​

在升级 DP 之前必须先升级 CP。由于 CP 需要与数据库交互，所以在升级过程中请勿使用 API 或其他方式更改你当前的数据。下图展示了如何实施原地升级策略。

  1. 直接用新版 CP B 替换现有的 CP A，升级过程中它们共享同一个数据库。
  2. 升级完成后，现有的 DP A 节点将自动连接到新的 CP B。
信息

在控制面（CP）的升级过程中，如上图所示，DP A 中的节点会保持与 CP A 或 CP B 的连接。API7 企业版确保了新版本控制面与旧版本数据面之间的向下兼容。因此，在运行不同版本的 CP 和 DP 时，请在控制面的**网关实例（Gateway Instances）**页面检查每个 DP 节点的状态，并根据提示升级被标记为不兼容的任何 DP 节点。

建议每次升级时保持 CP 和 DP 版本一致，以确保万无一失。

数据面（DP）滚动升级​

CP 升级完成后，你可以继续升级 DP 节点。对于 DP 升级，强烈建议采用滚动升级的方法，以避免出现停机。下图展示了如何实施滚动升级策略。

  1. 新的 CP B 复用当前数据库，当前的 DP A 继续处理 API 请求。
  2. 使用滚动升级，将 DP A 中的节点逐步替换为 DP B 的新节点。新的 DP B 节点更新后，也将开始处理 API 请求。

双集群升级​

双集群升级是 API7 企业版最安全、最稳健的升级方法，专为那些对零停机和极低风险有严苛要求的关键任务环境而设计。此策略包含在现有的生产集群（集群 X）旁边，部署一个完全独立、并行的全新集群（集群 Y）。每个集群都是完全独立的，具有各自的控制面、数据面和数据库。

通过外部负载均衡器将流量从旧集群逐步转移到新集群。这使得在新集群承受完整的生产流量之前，可以用一小部分真实流量对其进行全面测试。由于旧集群保持原样，一旦出现任何问题，你可以立即将所有流量重新切回旧集群以实现快速回滚。

下图展示了双集群升级架构：

检查重大变更和更新日志​

根据当前版本和升级的目标版本，请确认版本之间的所有重大变更和更新日志。根据更新日志中的提示提前准备并调整你的配置。

升级注意事项​

无论你如何部署 API7 企业版，有一些普遍因素会影响升级过程。在开始升级之前，请注意：

  1. 在升级过程中，禁止对数据库进行任何更改。在升级完成之前，请勿通过 API 或控制台（Dashboard）修改任何数据。
  2. 请仔细阅读当前版本和目标升级版本之间的所有更新日志，特别关注重大变更。检查任何潜在的冲突，例如功能移除、API 变更等。
  3. 如果你有自定义插件，请检查更新日志中是否有任何核心修改，并在具有新版本的测试环境中使用你的自定义插件进行测试以确保它们正常工作。
  4. 在任何时候，数据库备份都是必须执行的。请确保在每次升级之前备份你的数据。

执行升级​

  1. 控制面原地升级
  2. 数据面滚动升级
  3. 双集群升级