API7 网关 3.10.7：用证据降低升级不确定性

更新时间 9/15/2026

核心要点

  • 进程成功启动不足以证明 API 网关升级安全；团队还需要确认配置、兼容性与运行时行为符合预期。
  • API7 网关 3.10.7 发布于 2026 年 9 月 8 日，会在无法区分的路由形成新的运行时歧义前拒绝它们。
  • 兼容性问题现在会按机器可读的原因归类；对于数据面能够安全忽略的未知字段，运维人员可以忽略相应提示。
  • 在先升级控制面的过程中，旧数据面返回的空白兼容性报告可能表示状态未知，而不是兼容。
  • 诊断代理可以通过出站 mTLS 连接采集网关 Worker 的 CPU 性能剖析与内存快照，无需开放入站端口。
  • 控制台镜像、入口命令、健康检查和浏览器资源路径均有变化；部署自动化、反向代理、内容安全策略与 CDN 缓存键可能需要调整。

API 网关升级常有一个极具迷惑性的成功信号：新容器启动了。但这无法说明两条路由是否会争用同一请求、旧网关实例是否拒绝了部分配置，也无法说明看似正常的报告是否只是因为旧数据面无法用新格式描述问题而显示为空。

真正的运维问题不是“程序是否启动”，而是“哪些证据能够证明目标配置已到达目标实例，并且在真实流量下按预期工作”。

API7 网关 3.10.7 围绕这个问题形成了一条清晰的产品主线：阻止无法区分的重复路由，按根因整理兼容性问题，通过受控路径分析在线网关 Worker，并让多项健康与遥测信号更准确。这一版本也带来了必须纳入升级计划的部署变化。

1flowchart LR
2    change[升级变更] --> admission[路由准入检查]
3    admission --> report[结构化兼容性证据]
4    report --> rollout[数据面滚动升级]
5    rollout --> verify[运行时验证]
6    diagnostics[诊断代理] --> verify
7    telemetry[健康与遥测] --> verify

这并不等于自动修复或自动回滚，而是为团队提供更可靠的证据链，帮助判断升级应该继续、暂停还是进入排查。

进程成功启动，不等于升级安全

API7 网关将控制面与数据面分离：团队在控制面定义并下发配置，数据面实例负责处理流量。这种架构允许先升级控制面，再滚动升级数据面节点，但也会形成新旧版本并存的窗口。此时，最新的界面和 API 可能正在解释旧网关实例上报的数据。

因此，一道有效的升级门禁不能只检查进程是否存活，还要回答四个问题：

  1. 控制面接受的配置是否只有一种明确的运行时含义？
  2. 每个数据面是否都接受了收到的资源与插件字段？
  3. 延迟或内存发生变化时，团队能否诊断在线实例？
  4. 指标与健康检查 API 能否区分团队关注的流量和故障模式？

API7 网关 3.10.7 改进了每一层，但其中最重要的升级说明也在提醒我们：只有知道报告来自哪个版本，证据才有意义。

在无法区分的重复路由变成运行时猜谜前拒绝它

在 3.10.7 之前，控制台会提示部分路由冲突，但 ADC、a7 和直接调用 Admin API 的客户端仍能写入网关无法区分的路由。在同一网关组内，两条路由可能以相同优先级，为相同 HTTP 方法匹配同一 URL，迫使运维人员处理本不该通过准入检查的歧义。

现在，通过 POST、PUT 或 PATCH /apisix/admin/routes 创建这种结果时，控制面会返回 HTTP 400。通过 PUT 或 PATCH /apisix/admin/services/{id} 更新服务，以及导入 OpenAPI 文档创建路由时，也会执行同一检查。

这项规则的边界刻意保持得很窄：

  • 相同优先级、相同 HTTP 方法集合下的完全重复路由会被拒绝。
  • 优先级不同的路由仍然有效。
  • HTTP 方法部分重叠或完全不重叠的路由仍然有效。
  • 路径重叠但并不完全相同的路由仍然有效。
  • 携带 vars 的路由仍然有效，因为仅比较 URL 无法表达它们的条件匹配逻辑。
  • 未启用的服务不参与检查，但重新启用时会检查冲突。

升级后，已有重复路由会继续处理流量，但会成为运维债务：下一次编辑其中任一路由都会被拒绝；更新拥有这组冲突路由的服务时，即使只修改描述或标签，也会重新检查其所有路由并可能失败。

升级前，应盘点完全重复的路由，并决定应该调整路径、HTTP 方法集合还是优先级。这样可以把未来一次受阻的变更，提前转化为有计划的清理工作。

按根因阅读兼容性，而不是统计重复行

当同一根本问题出现在成百上千个资源上时，兼容性报告很容易被噪声淹没。API7 网关 3.10.7 现在按问题归类，并提供 resource_invalid、plugin_unavailable、plugin_config_invalid 或 plugin_unknown_fields 等机器可读的 reason。报告先列出错误，再按受影响资源数量排序。

这改变了运维人员处理问题的单位。团队无需逐行清理重复记录，而是可以先识别影响范围最大的插件、字段或资源规则，再修复根因。

对于 plugin_unknown_fields，如果数据面不认识某个字段但能安全忽略它，运维人员可以添加忽略规则。规则会跨网关组与实例生效，也可以用 nodes[*].weight 这样的模式匹配数组字段。

以下三项限制确保“忽略提示”不会变成“假装修复”：

  • 只有未知字段警告可以忽略。
  • 忽略警告不会改变数据面实际运行的配置。
  • 忽略规则绝不会把不兼容实例变成兼容实例。

忽略规则只能减少已经确认的噪声，不能修复资源，也不能让旧插件理解新字段。每次规则变更都受权限控制，并会进入审计记录。

新旧版本并存时，应把空白报告视为状态未知

按根因归类的报告与忽略规则依赖结构化兼容性数据。在 3.10 系列中，这类数据从数据面 3.10.7 开始提供；在 3.9 系列中，则从 3.9.20 开始提供。更早的实例只会上报渲染完成的英文句子，其中没有机器可读的 reason。

API7 企业版先升级控制面，因此 3.10.7 控制面会在一段时间内与旧数据面通信。旧实例发送这种只有句子的兼容性问题后，控制面会在心跳到达时丢弃它。因此，即使实例拒绝了某项资源或缺少某个插件，它的兼容性报告仍可能显示为空。

实例本身仍会被标记为需要升级，而且这项限制只影响报告显示，不会改变流量或实例已经运行的配置。运维规则可以归纳为一句话：

在数据面升级到 3.10.7 或其它能够上报结构化问题的版本前，应把空白兼容性报告视为状态未知，而不是一切正常。

应把版本标记也纳入证据。先升级一个网关组，确认其中的实例能够上报结构化问题，再把归类后的报告作为该网关组继续升级的门禁。

无需开放入站端口，也能诊断在线网关

如果升级后的网关 CPU 或内存用量超出预期，仅靠日志与聚合指标可能无法定位具体 Worker 或代码路径。API7 网关 3.10.7 新增诊断代理，可以采集网关自身 Worker 进程的 CPU 性能剖析与内存快照。

它的连接方式尤为重要。诊断代理通过 mTLS 主动连接控制面，复用数据面已经使用的端口；运维人员无需在网关网络中开放新的入站端口。API Runtime 下新增集群级的 Diagnostic Agents 区域，用于列出代理、展示状态、打开诊断控制台，并生成包含证书、主机 PID 命名空间和所需 Linux capabilities 的 Docker 命令或 Kubernetes 清单。

代理名称会写入其证书，因此运维人员看到的是可识别的机器，而不只是一个随机 ID。这也使诊断路径更容易盘点和审计。

无需入站端口，不代表无需权限。分析网关进程的 CPU 与内存，需要主机级进程可见性与相应 Linux capabilities。只在确有需要的环境部署诊断代理，妥善保护生成的凭据，限制诊断控制台的操作权限，并根据团队的事件访问策略移除或停用代理。

让健康与遥测信号准确描述实际情况

3.10.7 中还有多项规模较小但非常实用的改动，可以改善升级后的证据质量：

  • 返回 101 Switching Protocols 的响应会在 apisix_http_status、apisix_http_latency 与 apisix_bandwidth 中归类为 request_type=websocket；握手被拒绝时仍归类为 traditional_http。未做筛选的聚合看板可能会看到 WebSocket 流量进入独立指标序列。
  • AI Proxy Multi 实例的健康检查会通过 GET /v1/healthcheck 展示，GET /v1/healthcheck/{src_type}/{src_id}/checkers 则公开一个资源拥有的全部检查器。
  • 数据面健康检查集合为空时，现在会返回 [] 而不是 {}，让客户端获得稳定的数组结构。
  • Prometheus 返回非 JSON 内容时，控制面现在会返回带上游状态的 HTTP 502，而不是误导性的解析 HTTP 500；响应体前 256 字节会写入控制面日志，而不会返回给客户端。
  • 网关实例查询现在会带上网关组并对实例运行记录排序，避免旧运行记录与当前兼容性摘要相互矛盾，或把健康数据归到错误的网关组。

这些细节之所以重要，是因为升级门禁通常由自动化程序执行。稳定的响应结构、准确的状态码、当前实例身份与明确的流量分类，可以降低监控规则和验证脚本得出错误结论的概率。

更新围绕控制台形成的部署假设

在 3.10.7 中，控制台再次由 Dashboard 进程提供服务，并以 Vite 构建的静态单页应用形式运行。它的容器镜像改为 distroless：既不包含 Node.js，也不包含 shell，入口程序现在是 api7-ee-dashboard 二进制文件。

如果部署继续沿用 3.10.6 中启动 node /app/server.js 的旧 command，控制台容器将无法启动。围绕旧命令编写的健康检查也会失效。应以 3.10.7 离线包中的 docker-compose.yaml 为基础，再重新应用有意保留的定制，并使用离线包提供的 api7-ee-dashboard healthz 健康检查。

浏览器资源也从 /_next/static/ 迁移到 /assets/ 下带内容哈希的文件。需要检查引用旧路径的反向代理规则、内容安全策略来源、可观测性排除规则与 CDN 缓存键。

开发者门户前端镜像同样改为 distroless 且不含 shell，但其启动检查与非 root 运行方式保持不变。任何依赖 docker exec ... sh 或 shell 入口覆盖的运维手册，都应改用产品支持的健康检查与诊断路径。

升级到 3.10.7 前应验证什么

**3.10.7 已知阻断项：**若从 3.8.x 或 3.9.x 直接升级到已发布的 3.10.7 控制面，并且某项已发布服务引用了旧版自定义插件，Dashboard 进程可能在完成启动前反复崩溃重启。相关迁移修复在 v3.10.7 版本标签之后合并，未包含在已发布的 3.10.7 镜像中。如果部署符合这一范围，不要继续执行通用的 3.10.7 直接升级流程。请联系 API7 Support，等待明确包含该修复的版本；或者只采用经过 API7 工程团队审查并批准的分阶段升级路径。

请结合 API7 网关升级指南、滚动升级流程与更新日志执行以下检查：

  1. 查找密码为空的 Basic Auth 消费者或凭据，包括解析结果为 "" 的 $env:// 与 $secret:// 引用；在控制面和数据面开始拒绝它们前设置真实密码。
  2. 盘点相同优先级、相同 HTTP 方法集合下完全重复的路由，包括 OpenAPI 导入创建的路由，以及属于未启用但未来可能重新启用的服务的路由。
  3. 查找 tls.ca_certs 为空列表的 traffic-split 插件配置；添加 CA 证书或删除 tls 配置块。
  4. 记录每个数据面的版本，并定义其兼容性报告从何时开始可信；不要因为旧实例的报告为空就批准它。
  5. 先升级一个网关组，检查归类后的原因和受影响资源，并且只针对能够安全忽略的 plugin_unknown_fields 测试忽略规则。
  6. 针对 distroless 镜像和 /assets/ 路径，更新控制台命令、健康检查、反向代理路径、内容安全策略、CDN 行为与依赖 shell 的运维手册。
  7. 对比升级前后的 WebSocket 看板、AI Proxy Multi 健康检查、Prometheus 错误处理与实例身份。
  8. 预先授权并限定诊断代理的使用范围，让事件响应人员无需在故障期间临时扩大网络暴露面或访问权限，就能采集性能剖析。

升级期间不要修改网关配置。应备份数据库与声明式配置，在预发布环境测试相同升级路径，先升级控制面，再按照文档流程滚动升级数据面节点。

用证据推进升级，而不是依赖假设

API7 网关 3.10.7 无法让升级风险凭空消失，但它让多个重要的未知状态更容易预防或解释：无法区分的重复路由会在准入阶段被拒绝，兼容性问题按根因组织，可以通过受控的出站路径采集运行时性能剖析，遥测也能更准确地反映协议、健康状态与上游故障。

这一版本也说明了为什么版本上下文如此重要。旧数据面的空白兼容性报告并不能证明兼容，健康的容器也不能证明迁移到 distroless 镜像后，原有部署假设仍然成立。

请阅读完整的 API7 网关 3.10.7 更新日志，把每项必需变更映射为可测量的检查项，并让这些证据——而不是没有看到明显错误——决定升级何时可以继续。

获取方案