版本：3.10.x

从 3.9 LTS 升级到 3.10 LTS

API7 网关 3.9 LTS 可以直接升级到 3.10 LTS。本指南介绍经过验证的 3.9.20 到 3.10.7 路径，适用于使用外部 PostgreSQL 数据库的 Helm 和 Kubernetes 部署。

对于就地升级，一个目标控制面（Control Plane，CP）控制台会迁移现有数据库。目标 CP 健康后，3.9.20 数据面（Data Plane，DP）节点会继续承载流量，同时逐步添加、验证并启用 3.10.7 节点。对于双集群升级，源集群保持不变，同时构建独立的目标集群并逐步为其导入流量。

适用范围

只有源版本、目标版本、数据库和部署方式符合以下边界时，才能自助执行直接升级。

范围	支持边界
版本线升级路径	按照本指南操作前，先将更早的 3.9.x 源版本升级到 3.9.20。
直接升级锚点	从 3.9.20 升级到 3.10.7
CP 就地生产升级	使用本指南中的 Helm 和 Kubernetes 流程及外部 PostgreSQL 15.x。使用 Chart 内置 PostgreSQL、MySQL、Microsoft SQL Server 或其他数据库前，请联系 API7 支持团队。
双集群生产升级	使用两个独立的外部 PostgreSQL 15.x 数据库、下文列出的确切 Helm 和 Kubernetes 制品以及外部负载均衡器时，可自助执行。其他数据库或部署拓扑请联系 API7 支持团队。
Helm 和 Kubernetes	使用下文列出的确切发布制品。网关发布使用 Deployment 工作负载（`apisix.kind: Deployment`）。
其他部署方式	RPM、变更安装方式、DaemonSet 网关，或使用超出上述版本范围的 Chart 与镜像组合时，请联系 API7 支持团队。
CP 就地升级后的 DP 滚动升级	3.9.20 DP 连接 3.10.7 CP 时，如果兼容性错误为零，可能会报告 Partially Compatible。任何源 DP 报告 Incompatible 或非预期兼容性错误时，都要停止升级。
含结构性 DN 字符的 LDAP Auth	需要 API7 支持团队协助。源 DP 和目标 DP 对受影响用户名要求不同的 `user_dn` 存储形式，因此方案必须协调目标值改写、流量切换和仅 DP 回滚。
开发者门户	需要 API7 支持团队协助。本指南不提供门户前端、身份、组织或资源所有权迁移的自助流程。

不要使用 3.10.6 作为目标版本

API7 网关 3.10.7 包含此升级路径所需的 Basic Auth 修复。凭据只会按第一个冒号切分，因此 DP 升级后，包含 : 的密码仍可正常使用。

3.10.6 不包含这些修复，因此不要将它用作 3.9.20 源版本的目标版本。此时目标 DP 仍可能报告 Healthy 和 Compatible，而 Basic Auth 却拒绝有效的密码。

该自助路径已使用以下发布制品完成验证：

组件	源版本	目标版本
控制面	Chart `3.9.9`，镜像 `v3.9.20`	Chart `3.10.10`，镜像 `v3.10.7`
数据面	Gateway Chart `3.9.12`，镜像 `3.9.20`	Gateway Chart `3.10.14`，镜像 `3.10.7`

Helm Chart 版本与产品版本相互独立。CP Chart 3.10.10 部署 API7 网关 3.10.7 组件，并不代表产品版本 3.10.10。

数据库还必须满足支持的版本和互操作性中列出的目标版本要求。

查看兼容性变更

查看从 3.10.0 到目标版本的发布说明时，请以源版本作为基线。对于目标版本中行为发生变化的功能，请完成相应升级操作。

此升级路径需要处理以下变更：

服务模型迁移： Service Template、Service Hub 发布、服务版本和服务回滚功能已移除。发布并验证必须保持活动状态的配置，并归档需要留存备查的草稿或历史版本。迁移后，验证服务、路由、上游、OpenAPI 文档、API 产品链接和 IAM 策略。
自定义插件迁移： 上传的自定义插件会改为以网关组为作用域。清点源文件、当前使用情况、必须列出或读取插件源代码的角色，以及调用自定义插件 API 的自动化。将 /api/custom_plugins 调用替换为 /api/gateway_groups/{gateway_group_id}/custom_plugins，将 gateway_group_id 添加到 GET /api/plugins，并从自定义插件载荷中移除 gateway_groups。迁移后，验证每个必需的网关组都分配了预期插件，并确认第一个目标 DP 能成功加载插件。现有自定义插件策略授权会被迁移，但以前无需明确权限即可读取插件源代码的角色，需要对相应网关组授予 gateway:GetCustomPlugin。在切换生产流量前，使用受影响的自动化测试目标版本的列表和上传操作，并使用只读用户验证访问权限。
控制台打包： 从目标 Chart 默认值重新构建自定义的控制台命令、探针和 Hook。集成镜像会直接启动控制台二进制文件，既不包含 Node.js，也不包含 Shell。将反向代理规则、内容安全策略和 CDN 路径从 /_next/static/ 更新为 /assets/，然后验证 UI。
网关运行时： 网关从 OpenResty 1.21.4.4 升级到 1.29.2.4。使用 3.10.7 镜像测试自定义插件、NGINX 代码片段、模块和运维脚本。
gRPC 上游信任： 对每个启用了证书验证的 grpcs 上游，确认其证书链可以追溯到已配置的 CA，且主题备用名称覆盖上游主机。在目标金丝雀实例上测试连接；证书链或主机名无效时会返回 HTTP 502。
WebSocket 指标： WebSocket 成功升级后会从 traditional_http 序列移至 request_type="websocket"。检查 Prometheus 查询、记录规则、告警和仪表板中是否存在筛选条件或分序列阈值，避免遗漏流量或意外改变行为。
身份认证和密钥： 在目标灰度节点上测试每一种身份认证流程和凭证类型。只要仍有 3.9.20 DP，就要保持管理写入冻结，因为源 DP 可能无法读取仅目标版本支持的字段和新加密的值。
LDAP Auth 可分辨名称： 升级前，清点 user_dn 中用户名包含 LDAP 可分辨名称结构字符（例如 ,、+、=、<、>、;、" 或 \）的消费者。将当前纯字符串值保存在源备份中，并且在 3.9.20 DP 承载流量期间不要改写这些值。如存在受影响的消费者，请获取 API7 支持团队方案，安排在切换到目标 DP 时执行 RFC 4514 改写，并在仅 DP 回滚前恢复原始值。Schema 验证和兼容性报告无法检测这种不匹配。
3.10.7 目标版本新增的拒绝： 3.10.7 控制面会拒绝三类 3.10.6 仍然接受的配置。升级前，请为每个 Basic Auth 消费者和凭据设置非空密码，包括解析结果为空的密钥引用。清除每个网关组中的重复路由，即在相同优先级下对相同 HTTP 方法匹配相同 URL 的两条路由。为每个设置了 tls.ca_certs 的 traffic-split 上游至少配置一张证书，或者删除它的 tls 配置块。这三类配置一旦已经存储，升级后都会阻塞对相应资源的后续修改，因此请先在源部署上修复它们。

升级 DP 前，请针对每个网关组运行目标兼容性报告。ADC lint 和 diff 只能作为配置检查，不能证明运行时兼容性。

升级准备

在数据库迁移开始前，通过准备工作确定源状态、目标清单、回滚决策权和继续或中止标准。

确认每个源 CP 和 DP 都报告 3.9.20 且处于健康状态。对于 Helm，确认 CP Chart 为 3.9.9、Gateway Chart 为 3.9.12，并记录每个 Pod 实际运行的镜像摘要。
保存每个 CP 和网关发布的用户配置项与渲染后清单。将清单和 Secret 数据存储在获准使用的加密位置。
从 CP Chart 3.10.10 和 Gateway Chart 3.10.14 的默认配置开始构建目标清单，再重新应用经过审查的生产设置。不要使用 --reuse-values。
完成兼容性审查，并定义验收标准、中止阈值、观察时长、回滚负责人和回滚期限。
使用 ADC 导出并 lint 每个网关组。使用 --gateway-group，通过 --with-id 保留资源 ID，并为每项导出使用单独的 3.9.20 文件名。否则，后续 diff 可能把未变更的资源报告为删除后重建。请参阅备份与恢复。
```
adc dump -o "api7ee-{GATEWAY_GROUP}-3.9.20.yaml" \
  --backend api7ee \
  --server "https://{DASHBOARD_ADDR}" \
  --gateway-group "{GATEWAY_GROUP}" \
  --with-id

adc lint -f "api7ee-{GATEWAY_GROUP}-3.9.20.yaml"
```
保存自定义插件源代码、DP 证书、目标侧集成配置和所有必需的源镜像。
使用代表性的公开和身份认证流量演练升级和回滚。
创建预备数据库原生备份并恢复到隔离数据库。验证恢复副本中的源版本和代表性 CP 资源。
开始冻结管理写入。阻止通过控制台、Admin API、开发者门户、ADC、部署自动化、计划任务、直接数据库集成和其他所有可以修改 CP 数据库的路径进行写入。冻结后，再次导出并 lint 每个网关组；使用这些最终导出进行验证和后备恢复。在验收或回滚完成前始终保持冻结。

升级控制面

生产拓扑决定了是就地迁移现有 CP，还是构建独立的目标集群。

就地升级

此自助路径使用控制面就地升级。源 CP 停止且目标控制台迁移数据库期间，现有 DP 会继续代理其最后一份有效配置。

准备目标配置项

从 CP Chart 3.10.10 的默认配置开始创建迁移配置项和最终配置项。两个文件都必须保留外部 PostgreSQL DSN，并将 postgresql.builtin 设置为 false。

迁移配置项只启动一个控制台，不启动任何其他目标数据库客户端：

postgresql:
  builtin: false
dashboard:
  replicaCount: 1
dp_manager:
  replicaCount: 0
developer_portal:
  replicaCount: 0
developer_portal_configuration:
  enable: false
api_usage:
  enable: false
file_server:
  enabled: false
prometheus:
  builtin: false
jaeger:
  builtin: false

在 dashboard_configuration.database.dsn、dp_manager_configuration.database.dsn 和每个已启用的可选组件中设置生产数据库 DSN。只有迁移副本通过验证后，最终配置项才能恢复所需的目标副本数和组件。

执行迁移

保持写入冻结。将每个源 CP 数据库客户端缩容到零，并等待所有 3.9.20 CP Pod 停止。现有 DP 保持可用。
创建最终数据库备份，并再次进行隔离恢复检查。

使用迁移配置项升级已经停止的发布：

helm upgrade {CP_RELEASE} api7/api7ee3 \
  --namespace {CP_NAMESPACE} \
  --version 3.10.10 \
  --values api7ee-cp-3.10.7-migration-values.yaml \
  --wait \
  --timeout {TIMEOUT}

观察迁移控制台；如果它重启，请检查此前的日志。任何重启、SQLSTATE 错误、资源跳过警告、Pod 无法达到 Ready 或其他迁移错误都属于中止条件。保留迁移后的数据库和日志，继续冻结写入并执行回滚。
确认控制台报告 3.10.7，并且迁移后的服务、路由、消费者、凭证、API 产品、IAM 策略和网关组均存在。
应用最终配置项，恢复所需的控制台、DP Manager 和可选组件副本。切勿让源版本和目标版本 CP 同时连接同一个数据库。
开始替换 DP 前，确认每个源 DP 都报告 Healthy 和 Partially Compatible，且兼容性错误为零。

对于就地升级策略，请跳过双集群部分，继续执行升级数据面。

双集群升级

经过验证的双集群路径会保持源集群运行，同时让目标集群使用独立恢复的数据库。请按照双集群策略执行，并满足以下版本组合专用要求：

保持与回滚相关的业务写入冻结，并在整个回滚窗口内保持源 CP、DP 和数据库不变。
创建最终 3.9.20 数据库备份，将其恢复到新的外部 PostgreSQL 15.x 数据库，并在启动目标 CP 前验证代表性资源。
使用 CP Chart 3.10.10 连接目标数据库进行部署，只启动一个 3.10.7 控制台副本，并停止其他所有目标数据库客户端。任何控制台重启、迁移错误、资源跳过警告、就绪失败或迁移数据缺失都属于中止条件。
验证目标版本、迁移资源、IAM 策略、有效许可证和数据库健康状态。只有迁移门禁通过后，才能应用最终目标配置项。
从目标控制台生成新的 DP 证书和配置项。使用 Gateway Chart 3.10.14 和镜像 3.10.7 部署一个独立的目标网关发布，并将其置于生产负载均衡器之外。
确认每个目标 DP 都报告 Healthy 和 Compatible，且错误为零，然后通过目标 Service 直接运行代表性流量。复制的源 DP 记录会在目标控制台中显示为 LostConnection；请单独评估新的目标记录。复制的记录报告 Offline 后可以移除。
按照生产计划定义的阶段和观察期切换流量。保留足够的源容量以便回滚，并在验收或流量回滚完成前保持写入冻结。

完成流量迁移后，请跳过就地 DP 滚动升级部分，继续执行验证升级。

升级数据面

CP 就地升级后，请使用数据面滚动升级中的替换机制。以下 Chart 版本和兼容性门禁是该版本组合的权威要求。

从目标控制台为每个网关组生成新的 Helm 配置项和 DP 证书。
使用 Gateway Chart 3.10.14、apisix.kind: Deployment、一个副本并禁用自动扩缩，将一个 3.10.7 DP 部署为独立的灰度发布。将灰度 Service 置于生产负载均衡器之外。
等待灰度节点报告 Healthy 和 Compatible，且错误为零。将代表性的公开和身份认证流量直接发送到灰度节点。

记录主 Deployment 的期望副本数和 Ready 副本数。在经过验证的安全副本数下暂停自动扩缩，再配置先增后排空的替换策略：

apisix:
  kind: Deployment
  replicaCount: {SAFE_REPLICA_COUNT}
updateStrategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1
    maxUnavailable: 0
autoscaling:
  enabled: false

将主发布从 Gateway Chart 3.9.12 和镜像 3.9.20 升级到 Gateway Chart 3.10.14 和镜像 3.10.7：

helm upgrade {GATEWAY_RELEASE} api7/gateway \
  --namespace {GATEWAY_NAMESPACE} \
  --version 3.10.14 \
  --values api7-gateway-3.10.7-values.yaml \
  --wait \
  --timeout {TIMEOUT}

在整个发布过程中观察 Pod、流量和 Gateway Instances。每个目标 Pod 都必须先达到 Ready，才能排空源 Pod。
确认每个主发布 DP 都报告 Healthy 和 Compatible，且错误为零。只有主发布和代表性流量通过验收后，才能移除灰度节点并恢复生产自动扩缩策略。

只要仍有 3.9.20 DP 连接，就不要创建或修改网关资源。在回滚期限结束前，请保留最终源备份、源清单、证书、Chart 和镜像。

验证升级

结束写入冻结前：

确认每个 CP 组件都报告 3.10.7 且处于健康状态。
确认每个生产 DP 都报告 Healthy 和 Compatible，且没有兼容性错误。对于双集群策略，请将目标 DP 记录与报告 LostConnection 的复制源记录分开评估。

将每个网关组与匹配的升级前导出进行 adc diff：

adc diff -f "api7ee-{GATEWAY_GROUP}-3.9.20.yaml" \
  --backend api7ee \
  --server "https://{DASHBOARD_ADDR}" \
  --gateway-group "{GATEWAY_GROUP}"

验证服务、路由、上游、消费者、凭证、SSL 资源、插件元数据、全局规则、API 产品链接、IAM 策略和有效许可证。
通过生产 Service 运行代表性的公开和身份认证流量。
验证自定义插件、身份认证、限流、缓存、日志、指标、健康检查和上游集成。
在预定义观察期内查看 CP、DP 和 PostgreSQL 日志及指标。

只有指定的决策负责人记录所有验收标准都在回滚期限前通过后，才能恢复管理写入。

回滚

根据失败的组件和策略选择相应的回滚部分。在恢复后的部署和所需协调完成前，始终冻结管理写入。

仅回滚数据面

如果没有写入仅目标版本支持的配置，请从负载均衡器中移除目标 DP，并将主发布回滚到 Gateway Chart 3.9.12、保存的源配置项和镜像 3.9.20。保持 maxSurge: 1 和 maxUnavailable: 0，在移除目标 Pod 前验证每个源 Pod，并确认源 DP 连接目标 CP 时报告 Healthy 和 Partially Compatible，且错误为零。

如果 API7 支持团队方案为目标 DP 改写了 LDAP Auth user_dn 值，请在让 LDAP 流量返回 3.9.20 DP 前恢复源纯字符串值。

如果写入了仅目标版本支持的配置，请不要让流量返回 3.9.20 DP。请执行下文的完整 CP 和数据库回滚。

回滚控制面和数据库

不要依赖 helm rollback 或 --atomic；Helm 不会恢复 PostgreSQL 状态。

停止并隔离每个 3.10.7 DP，防止其连接恢复后的源 CP。
停止每个 3.10.7 CP 进程和其他数据库写入方。
将不可变的 3.9.20 备份恢复到新数据库。
使用 CP Chart 3.9.9、保存的源配置项和明确的 v3.9.20 镜像连接新数据库进行恢复。先启动一个控制台并完成验证，再恢复其余源 CP 和 DP Manager 副本。
恢复 Gateway Chart 3.9.12、保存的源配置项和证书，以及镜像 3.9.20。
确认源 CP 报告 3.9.20，许可证和代表性资源存在，每个源 DP 都为 Healthy 和 Compatible，并且公开和身份认证流量通过。
在查明升级失败原因前，保持迁移后的数据库和目标组件隔离。

恢复后不会包含最终源备份之后发生的变更。在回滚验证和所有必需的协调操作完成前，请保持写入冻结。

回滚双集群升级

只有与回滚相关的写入始终保持冻结，或经过测试的协调过程已经完成时，才能将流量重定向到源集群。仅目标版本产生的运行状态会随目标集群一起放弃。如果数据库已经分叉且没有经过测试的协调路径，请勿仅回滚流量。

适用范围​

查看兼容性变更​

升级准备​

升级控制面​

就地升级​

准备目标配置项​

执行迁移​

双集群升级​

升级数据面​

验证升级​

回滚​

仅回滚数据面​

回滚控制面和数据库​

回滚双集群升级​