生产环境的可靠性问题，往往出现在日常变化中，而不是极端故障里。客户端上传了更大的负载，上游节点从 4 个扩容到 6 个，依赖 Redis 的限流插件遇到流量高峰，指标共享字典达到容量上限，或者数据库主节点发生角色切换。这些事件都很常见，却可能暴露两个隐藏问题：API 网关会为它们执行多少工作，以及运行时状态能否在变化后继续保留。
因此，企业级 API 网关需要满足两个实际要求。第一，昂贵操作必须有明确上限，避免单个请求或单个依赖消耗过多资源。第二，常规拓扑和基础设施变化不应清空有价值的运行时状态，否则运维人员最需要连续上下文时，系统反而会从零开始判断。
API7 网关 3.10.4 发布于 2026 年 7 月 27 日，围绕这两个要求带来了一系列改进：为多个插件增加请求体与响应体缓冲上限，让 Redis 连接复用可配置且真正生效，在上游变化时保留健康检查与 least_conn 状态，避免已满的 Prometheus 共享字典让工作进程陷入 CPU 循环，并限制控制面数据库连接的生命周期。此外，此版本还改善了重启恢复并保护并发配置更新。
这些并不是互不相关的修复，而是共同形成了一种更清晰的可靠性模型：限制请求可能产生的工作量，保留支持准确路由决策的状态，并把依赖恢复视为日常运行能力。
1flowchart LR
2 change[运行时变化] --> work{工作量是否有上限？}
3 change --> state{有价值的状态是否保留？}
4 work -- 否 --> pressure[内存、CPU 或连接压力]
5 work -- 是 --> contain[资源使用得到控制]
6 state -- 否 --> reset[冷启动或错误决策]
7 state -- 是 --> continue[健康状态与负载上下文保持连续]
8 contain --> reliable[可预测的网关运行状态]
9 continue --> reliable
10 pressure --> incident[运维事件]
11 reset --> incident可靠性始于限制单个请求的工作量
部分网关插件需要读取请求体或响应体，才能执行转换、校验、检查或缓存。如果没有明确上限，一个合法但异常大的消息体就可能迫使工作进程保留远超常规流量所需的数据。在并发场景下，这种放大效应可能让一种负载模式演变为整个网关集群的内存压力。
API7 网关 3.10.4 为缓冲消息体的插件新增 max_req_body_size 和 max_resp_body_size，默认值为 67,108,864 字节（64 MiB）。这些控制项适用于 AI Proxy、AI Proxy Multi、AI Request Rewrite、AI Prompt Decorator、AI Prompt Template、AI Prompt Guard、Request Validation、OAS Validator、Body Transformer、Response Rewrite、Proxy Cache、gRPC Transcode、SOAP 以及其他缓冲消息体的插件。
超出边界后的结果取决于发生在哪一侧。请求体超过配置上限时会被拒绝，响应体则会在上限位置截断。Proxy Cache 的行为有所不同：当上游响应过大而无法缓存时，网关会直接流式转发该响应，但不会将其写入缓存。这个例外既保护工作进程，也允许客户端接收响应。
默认值是一条安全边界，而不是适用于所有路由的容量建议。接收视频、模型输入、大型 SOAP 消息或批量数据的路由，可能需要与普通 JSON API 不同的限制。运维人员应根据路由契约和预期并发量设置上限，并测试客户端将遇到的实际超限行为。提高上限时，需要为并发缓冲请求预留足够内存；降低上限时，则需要提供清晰的客户端错误并记录负载限制。
Logger 配置还有一项相关的升级检查。ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、Alibaba Cloud Logging（SLS） 和 Syslog 的 schema 现在要求 max_req_body_bytes 和 max_resp_body_bytes 必须是正整数。0、负数或 "1024" 这类带引号的数字会以 HTTP 400 被拒绝。包含这些值的既有路由会在网关组兼容性报告中显示为错误，并且不会发布到数据面；其他路由不受影响。升级前，应将无效值替换为正整数，或者删除字段以使用 524,288 字节的默认值。
这也是可靠性的重要组成部分：在无效资源限制进入流量路径前将其拒绝，并把故障隔离在受影响的配置中，而不是影响无关路由。
连接复用让依赖容量成为一项明确策略
限流和 AI Cache 可能为每个请求做出决策，因此它们的 Redis 连接行为会成为请求路径容量的一部分。如果每个请求都新建连接，连接建立过程不仅增加延迟，还可能在应用流量达到预期吞吐量之前，就耗尽 Redis、网络地址转换表或本地套接字的容量。
API7 网关 3.10.4 为 Limit Conn、Limit Req 和 AI Cache 的 Redis 与 Redis Cluster 策略新增 redis_keepalive_timeout 和 redis_keepalive_pool。此版本还修复了 Limit Conn 和 Limit Req 未将 Redis 连接放回 keepalive 池的问题。修复后，连接可以真正复用，不必为每个请求重新建立。
这些配置让连接复用成为明确的容量决策。连接池需要足以支持每个工作进程和策略的并发量，但也不能大到让空闲连接耗尽依赖的连接预算。超时时间应足以避免反复握手，同时不能让陈旧连接无限保留。调整参数时，团队应同时观察 Redis 连接数、连接建立延迟、命令延迟、网关错误和连接池饱和度。
连接复用不会消除依赖故障。Redis 仍可能不可用、变慢或发生网络分区。它带来的运维价值在于：正常流量不再制造可避免的连接抖动，从而让更多依赖容量用于真正的策略计算，也让遥测中的异常行为更容易识别。
扩缩容不应清空路由决策依赖的状态
上游拓扑变化十分常见：自动扩缩容器增加节点，部署过程移除旧 Pod，或者运维人员调整权重。真正的风险并不在新节点列表本身，而在于此前已从未变化节点学到的状态会如何处理。
API7 网关 3.10.4 升级了健康检查引擎，目标节点不再被全部销毁和重建，而是进行增量协调。上游扩缩容时，未变化的目标会保留累积的健康状态和失败计数。网关也避免了此前重建目标集合时可能出现的短暂窗口——在该窗口中，没有任何节点处于主动健康检查之下。
least_conn 负载均衡器同样遵循状态连续原则。此前，增加或删除上游节点会清空已跟踪的连接数。算法会暂时退化为近似轮询，并可能把新请求发送给已经承载大量长连接的节点。API7 网关 3.10.4 会在上游扩缩容期间保留负载状态，使下一次路由决策仍能反映正在进行的连接。
这对流式 API、WebSocket 类长连接流量、大文件下载和 LLM 响应尤其重要。即使某个节点只有少量活跃请求，只要这些请求持续很久，它仍可能比其他节点繁忙得多。保留连接计数，可以防止常规扩缩容事件让这部分负载突然变得不可见。
运维人员应使用具有代表性的变化来验证这种行为，而不是只做静态健康检查。保持长连接请求处于活跃状态，增加或删除一个上游节点，并确认未变化节点仍保留健康状态，同时新请求不会突然集中到已经繁忙的节点。可靠性需要在变化过程中得到证明。
1sequenceDiagram
2 participant O as 运维人员或自动扩缩容器
3 participant G as API7 网关
4 participant A as 既有节点 A
5 participant B as 既有节点 B
6 participant C as 新节点 C
7
8 G->>A: 跟踪健康状态和活跃连接
9 G->>B: 跟踪健康状态和活跃连接
10 O->>G: 将节点 C 加入上游
11 G->>G: 增量协调目标集合
12 Note over G,A: 保留 A 的健康计数和负载状态
13 Note over G,B: 保留 B 的健康计数和负载状态
14 G->>C: 开始检查新目标的健康状态
15 G->>G: 使用已保留和新获得的状态进行路由可观测性应安全降级，而不能成为故障本身
只有自身资源使用受到限制，监控才能保护系统可靠性。此前，Prometheus 插件使用的共享字典已满时，可能触发循环，使一个网关工作进程持续占用 100% CPU，并且在流量停止后仍无法恢复。遥测路径中的容量上限因此可能演变为流量处理故障。
API7 网关 3.10.4 改变了这种故障模式。共享字典已满时，网关会安全降级，并通过日志说明上报的指标数据可能不完整。丢失部分新指标样本仍然是一个运维告警，但比让指标采集独占工作进程更安全。
正确的处理方式并不是忽略告警。团队应针对该日志信号设置告警，检查指标基数，审查启用的路由、服务、Consumer 等标签，并根据预期时间序列数量设置共享字典容量。此版本还会拒绝通过 disabled_labels 删除结构性标签的配置，例如延迟指标的 type 或状态指标的 code，因为删除这些维度会把不同测量结果合并成一个具有误导性的时间序列。route、service 和 consumer 等非结构性标签仍可禁用。
这些行为共同建立了两条边界：遥测不能无限占用工作进程，降低基数也不能破坏指标含义。可靠的可观测性必须同时满足两点。
依赖恢复不应依靠进程偶然重建连接
长连接很有价值，直到连接另一端发生角色变化。在 3.10.4 之前，控制面的数据库连接池可能无限复用连接。数据库故障转移后，某条连接可能仍绑定到已降级为只读的原主节点，使控制面能否恢复取决于该连接何时偶然被替换。
API7 网关 3.10.4 将数据库连接生命周期默认限制为一小时，并提供 database.max_lifetime 用于调整。这不会让故障转移瞬间完成，合适的值也取决于数据库拓扑和连接成本；但它可以保证连接最终过期，而不是无限保留。故障转移测试应测量控制面恢复写入所需的时间，并确认配置的生命周期符合恢复目标。
此版本还把相同的恢复思路应用到网关进程。CLI 现在会等待上一个网关实例完全退出，再启动替代实例。如果容器未经正常关闭就被终止，启动流程会删除残留的 worker event socket，避免新进程无法绑定。这些变化让常见的停止—启动竞争和容器异常退出成为软件能够直接处理的条件。
配置更新也获得了更强的状态保护。针对同一资源的并发 PATCH 请求现在会串行执行，不再出现两个请求都返回成功、但后一次写入悄然覆盖前一次写入的情况。PATCH /apisix/admin/routes 合并得到的路由也会在存储前根据 route schema 进行验证。运维自动化仍然需要协调和错误处理，但控制面现在可以保护资源免受两种隐蔽的无效状态影响。
API7 网关 3.10.4 可靠性检查清单
请将特定版本的更新日志与滚动升级指南结合使用。重点检查以下内容：
- 盘点缓冲消息体的路由。 记录正常和最大负载大小、并发量、客户端遇到拒绝或截断时的行为，以及 Proxy Cache 特有的直通行为。
- 校验 Logger 上限。 在查看兼容性报告前，找出值为零、负数、带引号或其他无效形式的
max_req_body_bytes和max_resp_body_bytes。 - 设置 Redis 连接复用容量。 根据观测到的并发量和 Redis 连接容量设置 keepalive 超时与连接池，并在金丝雀阶段同时监控网关和 Redis。
- 验证拓扑变化。 在健康检查和长连接请求处于活跃状态时增加或删除上游节点，确认健康计数和
least_conn决策保持连续。 - 测试遥测容量耗尽。 针对指标不完整的告警日志设置告警，测量指标基数，并确认 Prometheus 结构性标签仍然启用。
- 测试数据库故障转移。 验证控制面写入恢复，并且只在有明确恢复目标和连接成本目标时调整
database.max_lifetime。 - 测试重启恢复。 同时覆盖正常重启和容器非正常终止，然后确认替代实例可以启动并处理流量。
- 保护配置写入方。 安全重试失败更新，检查
HTTP 400校验响应，并确保自动化不会假设每个 patch 都有效。
金丝雀验证应组合这些检查。一个只能处理普通请求，却未经历负载边界、上游扩缩容、指标压力、依赖切换或重启的网关，还没有证明此版本引入的可靠性能力。
让变化成为正常运行条件
API 网关可靠性并不只是在一切保持不变时维持可用。生产系统会持续改变负载大小、流量速率、上游成员、连接状态、指标基数、数据库角色和配置版本。
API7 网关 3.10.4 通过限制内存与连接工作量、保留健康和负载状态、让遥测安全降级、使数据库连接过期、从残留进程文件中恢复，以及阻止含糊的并发更新，让这些变化更加安全。
这些改进带来的共同结果，是系统在持续变化中仍然保持可预测。运维人员获得可以规划容量的上限、拓扑变化后仍可信任的状态，以及能够在事故前验证的恢复路径。
阅读完整的 API7 网关 3.10.4 更新日志，遵循滚动升级流程，并在扩大发布范围前使用具有代表性的流量验证每一种变化。