从 3.8 LTS 升级到 3.10 LTS

部分 API7 网关运维人员会从 3.8 LTS 直接升级到 3.10 LTS，而不部署 3.9。本指南介绍经过验证的 3.8.23 到 3.10.7 路径。

对于就地升级，目标控制面（Control Plane，CP）会应用中间版本的数据库迁移，包括新的服务模型。目标 CP 健康后，在将 3.8.23 数据面（Data Plane，DP）节点替换为 3.10.7 节点期间，DP 会保持可用。对于双集群升级，源集群保持不变，同时构建独立的目标集群并逐步为其导入流量。安排任一策略前，请确认部署处于支持范围内。

适用范围

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

范围	支持边界
版本线升级路径	按照本指南操作前，先将更早的 3.8.x 源版本升级到 3.8.23。
直接升级锚点	从 3.8.23 升级到 3.10.7
CP 就地生产升级	使用本指南中的 Helm 和 Kubernetes 流程及外部 PostgreSQL 15.x。使用 Chart 内置 PostgreSQL、MySQL、Microsoft SQL Server 或其他数据库前，请联系 API7 支持团队。
双集群生产升级	使用两个独立的外部 PostgreSQL 15.x 数据库、下文列出的确切 Helm 和 Kubernetes 制品以及外部负载均衡器时，可自助执行。其他数据库或部署拓扑请联系 API7 支持团队。
Helm 和 Kubernetes	使用下文列出的确切发布制品。单副本和多副本 CP 部署都使用一个控制台副本执行迁移。网关发布使用 Deployment 工作负载（apisix.kind: Deployment）。
其他部署方式	RPM、变更安装方式、DaemonSet 网关，或使用超出上述范围的 Helm Chart 与镜像组合时，请联系 API7 支持团队。
CP 就地升级后的 DP 滚动升级	3.8.23 DP 可能会在兼容性报告为空时显示 Partially Compatible，但 3.10.7 CP 会丢弃旧格式的问题详情。请将空报告视为没有信息，而不是检查结果正常。替换 DP 前，请独立验证源配置和流量。如果任何实例显示 Incompatible 或直接检查失败，请停止发布。
含结构性 DN 字符的 LDAP Auth	需要 API7 支持团队协助。源 DP 和目标 DP 对受影响用户名要求不同的 user_dn 存储形式，因此方案必须协调目标值改写、流量切换和仅 DP 回滚。
开发者门户	现有身份和资源所有权需要 API7 支持团队批准的迁移方案。本指南不提供门户自助迁移流程。

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

组件	源版本	目标版本
控制面	Chart 0.17.37，明确指定镜像 v3.8.23	Chart 3.10.10，镜像 v3.10.7
数据面	Gateway Chart 0.2.40，镜像 3.8.23	Gateway Chart 3.10.14，镜像 3.10.7

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

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

如果启用了开发者门户，请在 API7 支持团队批准的迁移方案成功通过预发布验证前，不要开始生产 CP/DP 升级或门户域名切换。方案必须说明：在分阶段网关升级期间门户是否保持离线，还是在同一维护窗口内切换域名。未启用开发者门户时，请跳过门户迁移部分。

查看关键变更

直接升级路径会一次性应用所有中间迁移。执行详细兼容性检查清单前，请查看以下产品变更。

服务模型迁移

Service Template、Service Hub 发布、服务版本和服务回滚功能已移除。目标 CP 启动时，会将每项已发布服务迁移为归网关组所有的服务。系统会保留旧的主记录以供调查，但无法使用这些记录反向迁移。

迁移会移动已发布的运行状态，不会迁移未发布的模板草稿或历史版本。创建最终备份前，请发布必须保持活动状态的内容，并归档需要留存备查的设计草稿。

开发者门户替换

3.8 内置门户前端和 SSO 模型会替换为独立的开发者门户前端和门户级身份认证。如果源部署使用开发者门户，请在安排生产升级前，获取并验证 API7 支持团队批准且在规划开发者门户迁移中说明的方案。该方案必须包含后续的门户域名切换。未使用开发者门户的部署可以跳过这些要求。

网关运行时升级

网关从 OpenResty 1.21.4.4 升级到 1.29.2.4。请使用目标镜像测试自定义插件、NGINX 代码片段、模块和运维脚本。生成的 NGINX 配置也会使用新的 HTTP/2 指令语法。

自定义插件作用域迁移

上传的自定义插件在 3.10.6 中会成为网关组资源。迁移会为部署了该插件的每个网关组创建一条目标记录。未分配给任何网关组的插件不会被迁移。

升级前，请清点源文件和分配关系。迁移后，验证每个所需网关组都包含预期插件，并确认第一个目标 DP 能加载插件。升级后上传的代码仅存储在新表中，因此完整回滚会恢复升级前数据库和已保存源文件中所记录的代码。

清点用于列出或上传自定义插件的自动化。将 /api/custom_plugins 调用替换为 /api/gateway_groups/{gateway_group_id}/custom_plugins，将 gateway_group_id 添加到 GET /api/plugins，并从自定义插件载荷中移除 gateway_groups。切换生产流量前，使用受影响的自动化测试目标版本的列表和上传操作；旧的自定义插件端点会返回 HTTP 410。

兼容性检查清单

升级前完成以下审查和变更。无需运维人员采取操作的功能和修复仍记录在发布说明中。

修正源配置

在生产升级窗口前应用并验证以下源状态修正。将每项会改变行为的修正视为独立的生产变更，并分别制定验证和回滚方案。不要在创建最终备份前批量应用未经验证的修正。

范围	必需的审查或操作
Service Template	发布并验证必须保持活动状态的所有配置。归档需要留存备查的未发布草稿和历史版本。
HMAC Auth	signed_headers 默认为 ["date"]。确保客户端签名包含 Date 标头，或明确配置与客户端签名匹配的 signed_headers。不兼容的签名只会在流量到达目标 DP 时开始失败，而不会在 CP 数据库迁移期间失败。
OpenID Connect	对于非 bearer-only 流程，配置至少 16 个字符的共享 session.secret。明确选择 TLS 验证策略。
SAML Auth	在每个 DP 上配置相同且长度为 8 到 32 个字符的 secret，然后测试多节点登录和退出。
CAS Auth	在每个 DP 上配置相同且至少 32 个字符的 cookie.secret。
LDAP Auth	清点 user_dn 中的用户名包含 DN 结构字符的消费者。在源备份中保留当前纯字符串值，并且在 3.8.23 DP 承载流量期间不要改写这些值。如存在受影响的消费者，请获取适用范围表中要求的 API7 支持团队协助制定的切换和回滚方案。
Workflow	为每项配置添加有效的 rules；不再需要该插件时将其移除。目标 DP 首次加载现有配置时，此字段为必填项。
日志记录器正文限制	替换 max_req_body_bytes 和 max_resp_body_bytes 中现有的零值、负值或带引号值。无效资源会出现在兼容性报告中，并且不会发布到 DP。
Prometheus 元数据	移除结构性指标标签，例如延迟指标中的 type 和状态指标中的 code；不要在 disabled_labels 中列出它们。仍可禁用非结构性标签。
OpenTelemetry 和 AI 内容审核	将 OpenTelemetry 资源属性和 Collector 标头中的数组或对象替换为标量值。将 AI 内容审核的 deny_code 设置为 200 到 599 之间的整数。
3.10.7 目标版本新增的拒绝	为每个 Basic Auth 消费者和凭据设置非空密码，包括可能解析为空值的密钥引用。移除同一网关组中 URL、HTTP 方法和优先级都相同的重复路由。为每个设置了 tls.ca_certs 的 traffic-split 上游至少配置一张证书，或者移除其 tls 配置块。已存储的这类配置可能阻塞后续编辑。

准备目标部署

将以下变更添加到目标清单，并且只在部署目标组件时应用。创建最终备份前，不要修改正在运行的源 DP 配置。

范围	必需的审查或操作
控制台打包	从目标 Chart 默认值重新构建自定义的控制台命令、探针和 Hook。集成镜像会直接启动控制台二进制文件，既不包含 Node.js，也不包含 Shell。将反向代理规则、内容安全策略和 CDN 路径从 /_next/static/ 更新为 /assets/，然后验证 UI。
网关运行时	使用目标镜像测试自定义插件、NGINX 代码片段、模块和脚本。
OpenID Connect 信任	如果启用了 ssl_verify，请将身份提供方 CA 添加到目标 DP 信任存储，并验证证书链。
gRPC 上游信任	对每个启用了证书验证的 grpcs 上游，确认其证书链可以追溯到已配置的 CA，且主题备用名称覆盖上游主机。在目标金丝雀实例上测试连接；证书链或主机名无效时会返回 HTTP 502。
OpenAPI to MCP	网关镜像不再内置 OpenAPI2MCP。在目标 Helm 配置项中启用 openapiToMcp.enabled，以使用 openapi-to-mcp 或 mcp-tools-acl。如果 openapi-to-mcp 插件属性使用非默认端口，请将 openapiToMcp.port 设置为相同值，并验证渲染后的清单。
网关内存	目标版本提高了多个共享内存的默认值。提高目标 DP 清单中的内存请求和限制，或明确调整未使用字典的大小。请参阅共享内存容量规划。
Helm DNS	目标 Chart 默认不再提供固定的公共解析器。解析器列表为空时，会使用 Pod 的 /etc/resolv.conf。仅当集群 DNS 不适用时，才在目标配置项中设置明确的解析器，并测试服务发现和域名上游。
Alibaba Cloud Logging 信任	默认通过 ssl_verify: true 启用证书验证。将签发 CA 添加到目标 DP 信任存储。仅在明确接受并记录风险后才能禁用验证。
转发标头信任	清点并测试每个代理跃点。只有部署需要明确的信任边界，或上游应用依赖可信转发标头时，才配置 apisix.trusted_addresses。包含每个可信负载均衡器和反向代理的地址或 CIDR。

CP 迁移期间

目标 CP 启动后验证以下变更。

范围	目标行为和验证
服务和 IAM	CP 会迁移已发布的服务，并改写备份中的 Service Template 和已发布服务 IAM 引用。验证服务、路由、上游、OpenAPI 文档、API 产品链接和 IAM 策略。如果 IAM 引用未正确迁移，请联系 API7 支持团队。请参阅 3.10.0 发布说明。
自定义插件	验证分配给网关组的每个插件都已迁移到该网关组。将仍需要但未分配的源插件重新上传到每个需要它的目标网关组。确认读取插件源代码的角色拥有 gateway:GetCustomPlugin 权限。
控制台访问	现有会话会失效一次，URL 不再使用 /zh 前缀，登录失败锁定会启用，而且新密码要求至少 12 个字符。重新登录、更新保存的链接并查看登录失败策略。为启用了 2FA 的用户创建的集成必须使用访问令牌，而不能使用 HTTP Basic Auth。
SQL Server（仅限 API7 支持团队协助）	第一次启动目标版本时会启用 READ_COMMITTED_SNAPSHOT，可能会一次性断开现有会话和进行中的事务。请为此次中断做好计划。此项不适用于 PostgreSQL 或 MySQL。

混合版本窗口期间

3.10.7 CP 可以临时管理 3.8.23 DP；这些 DP 可能会报告 Partially Compatible，同时继续承载其最后一份有效配置。这些 DP 会以渲染后的文本上报兼容性问题，但目标 CP 要求结构化的问题数据，因此会丢弃旧格式记录。即使 DP 拒绝了资源或缺少插件，最终报告也可能为空。在 DP 完成升级前，请将空报告视为没有信息，并在混合版本窗口内依靠源配置修正以及直接的配置和流量测试。

切勿让 3.8.23 和 3.10.7 CP 进程同时连接同一个数据库。

目标 CP 会加密更多包含凭证的插件字段。旧 DP 无法解密目标 CP 新写入的值。在每个 DP 都完成升级并报告 Compatible 前，请勿创建或更新网关资源、启用仅目标版本支持的插件或字段，也不要变更 Secret 引用。

验证目标 DP 行为

目标 DP 加载配置时，以下变更开始生效。将第一个目标 DP 加入生产负载均衡器前，直接测试每项适用行为。每个 DP 升级后都要重复代表性检查，并在结束配置冻结前再次检查。

范围	目标行为和必需操作
JWT Auth	默认验证 exp 和 nbf Claim；claims_to_verify 缺失或为空时会采用这一默认行为。测试令牌过期和生效时间处理。仅当有意缩小验证范围时，才明确设置 claims_to_verify。
OpenID Connect	ssl_verify 默认为 true，refresh_session_interval 不再默认为 900。验证身份提供方信任链。如果部署依赖旧的定期静默重新认证，请设置 refresh_session_interval: 900。测试 required_scopes、受众匹配和签发者验证，因为 3.10.6 会在以前跳过这些检查的流程中执行已配置的授权检查。
Limit Conn 和 Limit Req	下次创建或更新时必须提供 policy。现有存储配置会继续运行。下次变更前添加明确值，例如 local。
Batch Requests	批处理默认最多包含 1000 项，会拒绝额外字段，并且 timeout 必须至少为 1 毫秒。较大的批处理需要设置插件元数据 max_pipeline_items，并移除未记录的字段。
日志积压	日志批处理器默认最多保留 8192 个待处理项。检查 max_pending_entries 时，要同时考虑请求量、正文大小、batch_max_size 和日志服务器中断行为；达到限制后会丢弃条目。
LDAP Auth	消费者匹配改为使用转义后的绑定 DN。对于受影响的用户名，请按照 API7 支持团队协助方案安排目标 RFC 4514 改写，并在仅 DP 回滚前恢复源纯字符串值。Schema 验证和兼容性报告无法检测这种不匹配。
AI Proxy Multi	新写入会拒绝重复的实例名称，现有配置中的重复名称会报告为兼容性错误。接受目标 DP 前，请重命名重复实例。
限流	limit-count 增加 Redis Sentinel、滑动窗口、多条规则、变量和 sync_interval。Redis 支持的计数器会使用新的版本化键并重置一次。现有 limit-count-advanced 配置仍受支持，因此无需执行 3.9 路径要求的临时迁移。
Proxy Cache	默认按消费者隔离身份认证请求。两种存储策略都会跳过带 Set-Cookie 的响应；内存存储还会跳过带 Cache-Control: private、no-store 和 no-cache 的响应。仅在有意共享时设置 consumer_isolation: false。cache_set_cookie: true 只影响内存存储；请单独检查磁盘 NGINX 缓存规则。由于 3.10.6 变更了缓存键布局，现有内存缓存条目会重新获取一次。
GraphQL Proxy Cache	默认键包含主机、路由、服务和消费者身份。默认跳过带 Set-Cookie 的响应。仅在有意共享时设置 consumer_isolation: false；主机、路由和服务仍会保留在键中。cache_set_cookie: true 只影响内存存储。
请求和响应正文	缓冲正文的插件会强制限制大小。常见默认值为 64 MiB，日志记录器捕获默认值为 512 KiB。将其与 client_max_body_size 和生产环境最大载荷进行比较。
健康检查 API	GET /v1/healthcheck 和 GET /v1/healthcheck/{src_type}/{src_id} 会返回使用 ip、port、status 和失败计数器的新目标结构，而不再使用 healthy_nodes。更新解析器、控制台和告警。
LLM 指标	apisix_llm_ttft 替换为 apisix_llm_latency{type="ttft"}。更新 Prometheus 查询、记录规则、告警和 Grafana 仪表板。
WebSocket 指标	WebSocket 成功升级后会从 traditional_http 序列移至 request_type="websocket"。检查 Prometheus 查询、记录规则、告警和仪表板中是否存在筛选条件或分序列阈值，避免遗漏流量或意外改变行为。
Alibaba Cloud Logging	确认目标证书验证策略和信任存储下的日志记录成功。
转发标头	对于不可信对等端，网关会覆盖 X-Forwarded-Proto、X-Forwarded-Host 和 X-Forwarded-Port，并清除 Forwarded。网关会保留 X-Forwarded-For，前提是未设置 apisix.trusted_addresses；配置信任边界后，会为边界外的对等端清除该标头。测试上游应用收到的值。在自定义 NGINX 日志格式中，$http_x_forwarded_proto、$http_x_forwarded_host 和 $http_x_forwarded_port 现在会记录客户端提供的值。需要记录覆盖后的值时，请使用 $scheme、$var_x_forwarded_host 和 $var_x_forwarded_port。

规划开发者门户迁移

如果源部署未使用开发者门户，请跳过此部分。

部署独立的开发者门户前端，规划域名切换并迁移自定义内容。使用为开发者门户配置 SSO配置和测试所需身份提供方。

新前端会将用户和会话存储在单独的门户数据库中。恢复并迁移 3.8 CP 数据库不会让旧的本地凭证变为有效。新前端组织还会获得不同的开发者外部 ID，因此注册或 SSO 本身不会转移迁移后应用、订阅或凭证的所有权。

安排升级前，请清点开发者及其资源，并从 API7 支持团队获取受支持的关联、重新分配或重新创建流程。该流程必须涵盖 CP 数据库、独立的目标前端数据库、写入冻结、备份与恢复、快照后协调、域名切换和会话行为。在切换门户域名前测试完整流程。不要复制密码哈希，也不要在数据库中手动改写所有权。

查看其余门户变更：

范围	必需的审查或操作
API 产品草稿	身份认证规则只会为已发布的 API 产品同步。如果草稿产品的路由必须继续受到保护，请发布产品或应用其他访问控制。
凭证 Secret	Key Auth 密钥和 Basic Auth 密码只会在创建或重新生成时返回。更新集成，以便在当时捕获每个 Secret。
注册同意	tosURL 和 beforeSignUpButtonHtml 替换为 signUpConsentLabel。将同意内容迁移到 signUpConsentLabel；只有配置该字段时才会强制征得同意。
仅 SSO 域名	对于仅允许 SSO 的电子邮件域名，本地登录、注册、魔术链接（magic link）和密码重置端点会被拒绝。确认受影响的开发者使用已配置的 SSO 提供方。
门户 API 代理	前端代理默认拒绝请求，并且只公开受支持的组织作用域资源。将其他集成迁移到受支持的路径，或直接调用 CP API。

升级准备

在任何数据库迁移开始前，通过准备工作确定源状态、目标制品、回滚决策权和生产决策门禁。

1. 如果源版本早于 3.8.23，请先按照该补丁升级的备份和回滚流程完成升级。确认 CP 和每个 DP 都报告 3.8.23 且处于健康状态。

2. 查看目标版本的支持的版本和互操作性，确认部署使用的数据库、Kubernetes、Helm 和客户端工具满足要求。

3. 对于 Helm 和 Kubernetes，确认源 CP 使用 Chart 0.17.37，并明确指定 v3.8.23 控制台、DP Manager 和可选组件镜像标签。确认每个源网关发布使用 Chart 0.2.40 和镜像标签 3.8.23。记录每个 Pod 实际运行的镜像；否则，源 Chart 默认会为 CP 组件使用 v3.8.21，为网关使用 3.8.21。

4. 保存每个 CP 和网关发布的用户配置项和渲染后清单。这些制品可能包含凭证和 Secret 数据。将其存储在访问受限且获准使用的加密位置，不要提交到源代码管理系统。

   umask 077
   
   helm get values {CP_RELEASE} --namespace {CP_NAMESPACE} --output yaml \
     > api7ee-cp-3.8.23-values.yaml
   
   helm get manifest {CP_RELEASE} --namespace {CP_NAMESPACE} \
     > api7ee-cp-3.8.23-manifest.yaml

   对每个网关发布重复执行这两个命令，并使用网关组专用文件名。

5. 从 CP Chart 3.10.10 和 Gateway Chart 3.10.14 的默认配置开始构建目标配置项，再重新应用所需生产设置。不要使用 --reuse-values，也不要原样提交源 Chart 的完整配置项；这两种方式都可能保留源镜像标签并遗漏目标默认值。

6. 完成适用于该部署的源配置修正、目标部署准备和开发者门户操作。

7. 定义生产决策方案：变更负责人、观察时长、验收标准、中止阈值、回滚决策负责人，以及恢复写入前必须决定是否回滚的期限。对于双集群或开发者门户部署，请说明如何阻止或协调旧数据库与目标数据库之间的快照后写入。

8. 使用当前 ADC 版本导出每个网关组。指定 --gateway-group，使用 --with-id 保留资源 ID，并为每个组使用独立且包含源版本的文件名。否则，后续 diff 可能把未变更的资源报告为删除后重建。对每项导出运行 adc lint。请参阅备份与恢复。

   adc dump -o "api7ee-{GATEWAY_GROUP}-3.8.23.yaml" \
     --backend api7ee \
     --server "https://{DASHBOARD_ADDR}" \
     --gateway-group "{GATEWAY_GROUP}" \
     --with-id
   
   adc lint -f "api7ee-{GATEWAY_GROUP}-3.8.23.yaml"

9. 创建数据库原生备份，并成功恢复到隔离数据库。验证恢复后的源版本和代表性 CP 资源。此备份是权威恢复来源，因为 ADC 不包含用户、角色、API 产品和审计数据等所有 CP 资源。

10. 除上文记录的部署制品外，还要保存源网关配置、自定义插件源代码、证书和所有镜像标签。

11. 准备目标镜像和部署配置，包括开发者门户前端、OpenAPI2MCP Sidecar、文件服务器或其他已启用的组件。

12. 在预发布环境中使用代表性的身份认证流量、缓存行为、限流、日志、自定义插件和门户流程，演练所选升级和回滚策略。

13. 创建最终生产备份前，开始冻结 CP 写入。阻止控制台、Admin API、开发者门户、ADC、部署自动化、计划任务、API 使用情况服务、直接数据库集成和其他所有能够写入 CP 数据库的路径。冻结后，再次导出并 lint ADC 文件并记录冻结开始时间。在预定义验收标准通过，或回滚和协调完成前，不要恢复写入。

ADC lint 和 diff 可以检测已存储网关配置的差异，但无法验证运行时默认值、客户端身份认证、自定义代码或所有 CP 资源。因此，接受升级前仍须完成本指南中的其他所有检查。

升级控制面

请选择与生产拓扑匹配的策略。使用链接的策略页查看特定部署的镜像、Helm、流量切换和节点替换说明。如果指导存在差异，请遵循本指南中更严格的安全要求。

策略	生产影响	数据库与回滚	数据库范围
就地升级	现有 DP 会继续代理，但 CP 停止期间控制台和 Admin API 不可用。所需并行容量较少。	迁移现有 CP 数据库。回滚时必须将不可变源备份恢复到新数据库。	外部 PostgreSQL 15.x。Chart 内置数据库、MySQL、Microsoft SQL Server 或其他数据库请联系 API7 支持团队。
双集群升级	需要可运行两个完整集群的容量，并在两个集群中冻结与回滚相关的业务写入。开始切换流量前，代理流量仍由旧 DP 承载。	将源备份恢复到新目标数据库。只有与回滚相关的业务写入保持阻止状态或已经协调时，才能通过切换流量回滚到旧集群。	两个独立的外部 PostgreSQL 15.x 数据库，并使用本指南中的 Helm 和 Kubernetes 流程。其他数据库或拓扑请联系 API7 支持团队。

无论使用哪种策略，开发者门户部署都必须事先获得 API7 支持团队批准的身份、所有权、数据库、域名和回滚流程。

就地升级

就地策略会先停止所有源 CP 数据库客户端，再由一个目标控制台副本迁移数据库。在此管理功能中断期间，现有 DP 会继续代理。

Helm 和 Kubernetes

Helm 路径以 CP Chart 0.17.37 和明确指定的 v3.8.23 镜像标签为起点，升级到 CP Chart 3.10.10；后者默认使用 v3.10.7 镜像。

基于 Chart 3.10.10 的默认配置准备三个配置项文件。每个文件都要将 postgresql.builtin 设置为 false，使所有目标组件使用外部生产数据库。

配置项文件	用途	运行的组件
迁移	使用一个写入方执行数据库迁移。	一个控制台。停止 DP Manager、开发者门户、API 使用情况服务、文件服务器和其他所有目标数据库客户端。
激活	恢复完整容量前验证迁移后的 CP。	一个控制台、一个 DP Manager，以及仅验证所需的可选组件。
最终	验证后恢复生产 CP 拓扑。	已批准的生产副本数和其余可选组件。

迁移配置项应包含：

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

1. 保持写入冻结。使用源 Chart 和配置项更新源 Helm 发布，将每个源 CP 数据库客户端缩容到零。等待所有 3.8.23 控制台、DP Manager、开发者门户后端、API 使用情况服务和其他写入数据库的 Pod 停止。同时停止外部写入方和自动化。

2. 创建最终数据库备份，并将其恢复到隔离验证数据库。恢复后的源版本和代表性资源通过继续或中止检查前，请勿继续。

3. 记录已停止源 CP 使用的外部生产数据库 DSN。确认迁移配置项中的 dashboard_configuration.database.dsn 指向该确切数据库；目标 Chart 默认指向 Chart 本地 PostgreSQL Service。然后使用迁移配置项升级已停止的 CP 发布。不要添加 --atomic 或 --reuse-values：Helm 自动回滚不会恢复迁移后的数据库，而复用源配置项可能保留旧镜像或遗漏目标默认值。

   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}

4. 观察迁移控制台 Pod；如果它重启，请检查此前的日志。发生重启、SQLSTATE 错误、资源跳过警告、Pod 无法达到 Ready 或迁移数据缺失，均属于中止条件。保留日志和迁移后的数据库，继续冻结写入，并将不可变源备份恢复到新数据库。

5. 验证激活和最终配置项中的每个目标 CP 组件都使用所记录的生产数据库 DSN。应用激活配置项并验证一个控制台副本、一个 DP Manager 副本及所需可选组件。然后应用最终配置项，恢复其余目标副本和组件。只有迁移副本健康后才能增加控制台副本；切勿让源控制台 Pod 和目标控制台 Pod 同时连接同一个数据库。

6. 重新登录并验证控制台版本、迁移后的资源和 IAM 策略。确认每个源 DP 都健康且标记为需要升级，但不要把空的兼容性报告视为检查结果正常。替换 DP 前，请再次执行源配置和流量检查。

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

双集群升级

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

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

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

升级数据面

对于 CP 就地升级策略，通用数据面滚动升级介绍了节点替换机制。以下版本锚点、兼容性门禁和 Helm 设置是该版本组合的权威要求。

在整个回滚窗口内保留不可变的最终 3.8.23 备份。如果滚动策略或本地流程要求在 CP 迁移后再次备份数据库，请将其另存为带有独立名称的目标版本快照。该快照不能替代完整回滚所需的源备份。

一次升级一个网关组。第一个目标 DP 是累积运行时和插件变更的灰度节点；只有该节点通过直接流量检查后，才能继续升级其他节点。

Helm 和 Kubernetes

经过验证的 Helm 路径适用于网关 Deployment。它会将 Gateway Chart 0.2.40（镜像标签 3.8.23）升级到 Gateway Chart 3.10.14（镜像标签 3.10.7）。DaemonSet 网关请联系 API7 支持团队。

1. 从目标控制台为网关组生成新的目标 Helm 配置项和 DP 证书。查看目标默认值后，将源发布的生产资源、调度、Service、自动扩缩、解析器和插件设置重新应用到目标 Chart 配置项。

2. 将一个 3.10.7 DP 部署为独立的灰度 Helm 发布。将 apisix.kind 设置为 Deployment、apisix.replicaCount 设置为 1、autoscaling.enabled 设置为 false。为灰度节点使用独立的 Kubernetes Service，并将该 Service 置于生产负载均衡器之外。

3. 等待灰度节点报告 Healthy 和 Compatible，且没有兼容性错误。通过其 Service 直接发送代表性的公开和身份认证请求，并验证兼容性检查清单中的目标 DP 行为。

4. 暂停自动扩缩前，记录 Deployment 当前的期望副本数和 Ready 副本数。将 apisix.replicaCount 设置为经过验证的安全容量，该容量不得低于上述任一副本数，并且必须满足生产负载要求。然后将主网关发布配置为先启动目标 Pod，再让源 Pod 不可用：

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

5. 将主网关发布升级到 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。Kubernetes 应在终止源 Pod 前启动每个目标 Pod 并使其达到 Ready。

6. 确认每个主发布 DP 都报告 Healthy 和 Compatible，并且代表性生产流量通过。只有主发布通过验收后，才能移除灰度发布并恢复生产自动扩缩策略。

在回滚期限结束前，保留足够的已排空 3.8.23 DP 容量、清单、证书和镜像，以便恢复流量。只要仍有源 DP，就不要启用仅目标版本支持的插件、字段或 Secret 引用。

验证升级

结束配置冻结前，请完成以下检查：

1. 确认每个 CP 组件都处于健康状态并报告 3.10.7。

2. 确认每个生产 DP 都报告 Healthy 和 Compatible，且兼容性报告中没有错误。对于双集群策略，请将目标 DP 记录与报告 LostConnection 的复制源记录分开评估。

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

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

4. 验证迁移后的服务、路由、上游、消费者、凭证、SSL 资源、插件元数据、全局规则、API 产品链接、IAM 策略和有效许可证。

5. 如果启用了开发者门户，请验证注册或 SSO，并确认每位迁移后的开发者都能访问和管理预期的应用、订阅和凭证。

6. 运行代表性的公开和身份认证请求，包括适用的限流、缓存、日志、自定义插件和大请求正文。

7. 在预定义观察期内查看网关和 CP 日志、指标、数据库健康状态和资源利用率，并与文档化的验收标准和中止阈值进行比较。

ADC diff 为空并不能证明运行时默认值、客户端身份认证、自定义插件或门户身份兼容。如果达到中止阈值，请保持写入冻结并执行预定义回滚。只有指定的决策负责人记录所有验收标准都在回滚期限前通过后，才能恢复写入。

回滚

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

仅回滚数据面

如果在替换 DP 期间出现问题，请先确认没有写入仅目标版本支持的配置。如果没有，请从负载均衡器中移除新节点，并让流量返回保留的 3.8.23 节点。调查期间，3.10.7 CP 可以暂时将其作为部分兼容 DP 进行管理。

对于 Helm 管理的 DP，请恢复 Gateway Chart 0.2.40、保存的源配置项和镜像标签 3.8.23。保持明确的先增后排空策略。在允许 Kubernetes 移除目标 Pod 前验证源 Pod。

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

如果已经写入仅目标版本支持的配置，请不要让流量返回 3.8.23 DP。执行下文的完整 CP 和数据库回滚，或保持受影响节点隔离并获取 API7 支持团队指导。

回滚控制面和数据库

请使用升级前数据库备份，不要依赖迁移后数据库中的旧记录。

对于 Helm 和 Kubernetes，不要单独运行 helm rollback，也不要依赖此前的 --atomic 回滚。Helm 会恢复 Kubernetes 对象，但不会恢复迁移前的 PostgreSQL 状态。先停止目标 CP，将备份恢复到新数据库，再使用 CP Chart 0.17.37、保存的源配置项和明确的 v3.8.23 镜像标签连接该数据库进行恢复。

1. 保持 CP 写入冻结。停止每个 3.10.7 CP 进程和其他数据库写入方。通过网络隔离 3.10.7 DP 的管理连接，使其无法访问源 CP 和目标 CP 端点。
2. 如果目标 DP 仍能安全代理，请在重建源路径期间将其保留在负载均衡器中。如果继续使用目标流量并不安全，请立即移除目标 DP，并将由此产生的请求中断作为紧急故障处理，直至源 DP 就绪。
3. 将不可变的最终 3.8.23 备份恢复到新数据库。
4. 恢复保存的 3.8.23 CP 配置和镜像标签。仅将源 CP 组件连接到恢复后的数据库，并使用已隔离的 3.10.7 DP 无法访问的管理端点。
5. 启动 3.8.23 CP 和保留或重新部署的 3.8.23 DP。直接在源 DP 上验证源版本、有效许可证、原始 Service Hub 资源和代表性流量。
6. 将生产流量切换到已经验证的 3.8.23 DP，然后停止并隔离每个 3.10.7 DP。
7. 将恢复后的部署与升级前 ADC 导出进行比较，并运行代表性流量检查。
8. 在查明升级失败原因前，保持迁移后的数据库和目标组件隔离。

恢复后的数据库不包含最终备份之后发生的变更。在完成回滚验证和所有必需的协调操作前，请保持写入冻结。如果开发者门户已根据 API7 支持团队批准的方案启用，还要按照该方案处理独立的前端数据库、域名和会话。

回滚双集群升级

只有与回滚相关的业务写入始终保持冻结，或经过测试的协调过程已经完成时，才能安全地将流量重定向到旧 DP。仅目标版本产生且可丢弃的运行状态会随目标集群一起放弃。否则，请勿仅回滚流量；应按照事件处理方案保持两个集群隔离，并联系 API7 支持团队。仅当旧数据库经过迁移、损坏或因其他原因不再适合源集群时，才恢复该数据库。