API7 网关 3.10.4：让每一道信任边界都清晰可见

更新时间 8/3/2026

一个请求抵达 API 网关时，携带的不只是方法、路径和请求体。它还可能带着浏览器 Cookie、终端用户的 Bearer Token、身份请求头、负载均衡器提供的客户端地址，以及用于指示平台下一步连接目标的配置。

这些上下文中，有些来自权威来源，有些只是调用方自行提供的内容。当请求穿过浏览器、网关、身份提供商、模型提供商、内部服务和控制面等多重边界时，真正困难的是始终分清二者。

随着 API 与 AI 流量逐渐融合，这个问题变得更加紧迫。AI 应用可能使用一种凭证认证用户，用另一种凭证路由提示词，再用第三种提供商密钥调用外部模型。如果网关转发了错误的请求头，模型提供商就可能收到原本只应由应用使用的凭证。如果身份认证插件信任调用方提供的身份请求头，上游服务就可能收到一个从未经过验证的身份。如果管理功能可以连接任意端点，一项配置值就可能变成通往内部服务或云元数据端点的路径。

API7 网关 3.10.4 发布于 2026 年 7 月 27 日，它通过更明确的信任决策来应对这些风险。新版本收紧了 AI 提供商方向的出站通信，在 wolf-rbac 中清除调用方提供的身份请求头，为控制面连接新增可选的服务端请求伪造（SSRF）防护，改进令牌转发以支持上游自主验证，并明确哪些网络对端可以为四层流量提供客户端地址。

这次发布带来的核心启示并不是一份安全修复清单，而是一条架构原则：只有当来源、用途和下一接收方都清晰明确时，上下文才应该跨越网关边界。

1flowchart LR
2    client[客户端与浏览器] -->|应用凭证与请求上下文| gateway[API7 网关 3.10.4]
3    gateway -->|身份认证请求| identity[身份提供商]
4    identity -->|已验证的身份结果| gateway
5    gateway -->|网关派生的身份| api[上游 API]
6    gateway -->|由插件管理的提供商请求头| ai[模型提供商]
7
8    control[控制面配置] --> enabled{是否启用 SSRF 防护？}
9    enabled -->|否| outbound[已配置的外部端点]
10    enabled -->|是| screen{目标是否为私有或保留地址？}
11    screen -->|否| outbound
12    screen -->|是| reject[拒绝连接]
13
14    untrusted[AI 代理请求中的调用方凭证] -. 不转发给模型提供商 .-> gateway

AI 流量带来了多凭证出站难题

在传统 API 请求中，上游服务经常需要客户端提供的凭证。但在 AI 代理流程中，沿用这一假设可能非常危险。客户端向应用或网关进行身份认证，而网关还要单独向模型提供商认证。这两类凭证的受众不同，不应一同传递。

以浏览器向 AI 助手发起请求为例。请求中可能包含会话 Cookie、应用使用的 Authorization 请求头、链路追踪请求头和自定义租户元数据。随后，AI 代理插件会加入调用已配置模型服务所需的提供商凭证。如果原始请求头也被复制给模型提供商，第三方就会收到它并不需要的认证材料和内部上下文。

API7 网关 3.10.4 修复了 AI Proxy、AI Proxy Multi 和 AI Request Rewrite 中的这一行为。网关向大语言模型（LLM）提供商发送请求时，现在只携带插件自身设置的请求头，不再继承客户端的 Cookie、Authorization 和任意自定义字段。

这项变化建立了一道重要的 AI 网关安全边界：

  • 用于进入应用的凭证留在应用一侧。
  • 用于调用模型提供商的凭证由网关配置管理。
  • 客户端上下文不会仅仅因为出现在入站请求中，就被导出到外部。
  • 提供商请求中的请求头均为有意设置，不再来自隐式继承，因此更容易审查。

这不只是凭证卫生问题，也符合数据最小化原则。请求头可能携带租户 ID、实验名称、内部主机信息和关联标识。即使这些字段单独看来不是秘密，在没有明确目的的情况下将其导出，仍会扩大系统的信息暴露面。

升级到 3.10.4 的团队应把这项变化视为一次契约变更来测试。如果某个模型提供商集成有意依赖客户端提供的自定义请求头，升级后该请求头不会再自动到达。应当把提供商真正需要的上下文移入受支持的插件配置或经过明确治理的转换流程，再在非生产环境中验证准确的出站请求头集合。不要为了保留未经记录的依赖关系而恢复整批请求头转发。

已验证身份必须取代调用方声明的身份

对上游服务来说，X-UserId、X-Username 和 X-Nickname 这类请求头看起来具有权威性。然而，只要调用方能够直接提供这些值，它们就不是可信身份。

身份认证插件应该先从入站请求中移除身份声明，再通过配置的认证系统确认身份，最后加入从认证结果中派生出的可信值。3.10.4 修复了 wolf-rbac 的一个问题：当认证服务返回成功却不包含 userInfo 时，客户端自行提供的身份请求头此前可能被传递到上游。现在，网关会在代理请求前始终清除这些请求头。

这遵循了与 AI 提供商请求相同的边界规则：一旦信任来源消失，一个字段就不应继续保留可信含义。

OpenID Connect 也获得了与之配套的改进。启用 set_raw_id_token_header 后，OpenID Connect 插件 现在可以通过 X-Raw-ID-Token 把原始 ID Token 转发给上游。这样，上游服务可以自行验证身份提供商签发令牌的签名，而不必只信任网关提供的解码后声明。

这项能力应该有意识地启用。原始 ID Token 属于安全敏感信息，可能包含个人或组织声明。上游必须有接收它的明确理由，还要实现验证逻辑，检查预期的签发者、受众、签名和时间约束，并通过日志规则防止令牌被记录。如果启用选项后上游并不执行验证，就只是让令牌多跨越了一道边界，却没有获得预期的安全保证。

新版本还能够更准确地保留身份数据。身份提供商返回的空数组，例如 "roles": []，在已有会话的请求中被编码到 X-Userinfo 时仍会保持为数组，不再变成空对象，从而避免依赖数组类型的上游授权逻辑出错。当认证回调携带的状态与会话不再匹配时，网关现在会重定向到最初请求的页面，而不是返回 HTTP 500。

这些变化共同区分了三个经常被混淆的概念：

  1. 调用方输入在验证前不可信。
  2. 网关派生的身份按照配置的身份认证流程建立信任。
  3. 身份提供商证据可以在风险模型需要时转发给上游，由上游独立验证。
1sequenceDiagram
2    participant C as 客户端
3    participant G as API7 网关
4    participant I as 身份提供商
5    participant U as 上游 API
6
7    C->>G: 请求与调用方提供的身份请求头
8    G->>G: wolf-rbac 清除调用方提供的身份请求头
9    G->>I: 进行身份认证或验证会话
10    I-->>G: 已验证声明与可选的原始 ID Token
11    G->>U: 网关派生的身份
12    opt 已启用 set_raw_id_token_header
13        G->>U: 用于独立验证的 X-Raw-ID-Token
14    end

控制面出站连接需要明确目标边界

谈到网关时，人们通常关注入站流量基础设施，但控制面同样会发起出站连接。它可以连接服务注册中心、SMTP 服务器，以及通过配置提供的其他端点。如果能够影响 URL 的用户可以让控制面连接到自己无法直接访问的目标，这种灵活性就会带来 SSRF 风险。

3.10.4 新增了一项由 security.ssrf_protection.enable 控制的可选防护。启用后，控制面会拒绝连接到环回、私有、链路本地和运营商级 NAT 地址，也会拒绝解析到这些地址的主机名。这有助于防止可配置集成被用来探测内部服务或云元数据端点。

这项配置采用可选方式，是因为许多私有化部署确实需要访问私有目标。服务注册中心或 SMTP 服务器可能有意部署在内部地址上。如果没有梳理这些依赖就启用 SSRF 防护，可能造成连接中断；如果不分析谁有权配置出站端点就保持关闭，则会保留一条比部分环境预期更宽的信任边界。

因此，一次切实可行的上线评估应回答四个问题：

  • API7 网关的哪些功能会发起控制面出站连接？
  • 哪些目标主机名及其解析后的地址范围符合预期？
  • 谁能够创建或编辑决定这些目标的配置？
  • 启用防护前，哪些连接应该迁移到获批代理或公共端点？

SSRF 防御还需要结合 DNS 行为进行测试。主机名文本看起来像公共地址，并不意味着它一定安全；防护会评估主机名实际解析到的地址。应测试预期目标、被阻止的私有地址、集成会跟随跳转时的重定向，以及连接生命周期内的 DNS 变化。

网络身份只有在直接对端可信时才有效

在四层流量中，负载均衡器可以通过 PROXY protocol 请求头携带原始客户端地址。网关需要这个地址来记录四层流量日志和执行基于地址的策略，但只应接受由获准使用该协议的网络对端提供的值。

API7 网关 3.10.4 为 TCP 和 UDP 监听端口新增了 nginx_config.stream.real_ip_from。该配置列出获准提供 PROXY protocol 请求头的地址。当连接来自其中一个可信地址时，网关会使用请求头中的客户端地址，而不是直接连接对端的地址。该列表默认为空，并且只对已配置接收 PROXY protocol 的端口生效。

这相当于四层流量中的可信代理边界。请求头中的值之所以有意义，是因为网关验证了提供它的网络来源，而不是因为请求头格式本身有效。

启用前，运维人员应梳理每个网关实例正前方的实际网络跳点。需要考虑网络地址转换后网关真正看到的负载均衡器地址或 CIDR 范围，并在满足运维要求的前提下尽量缩小列表。随后分别从获准和未获准的来源测试，并确认日志、允许列表、拒绝列表和限流策略所使用的客户端地址符合预期。

配置验证也是安全边界的一部分

安全运行时的基础，是每一项配置都只有一种明确含义。3.10.4 收紧了多条配置验证路径，并带来两项升级前必须关注的说明。

首先，日志插件字段 max_req_body_bytes 和 max_resp_body_bytes 现在必须是正整数。0、负数以及 "1024" 这类带引号的数字都会被拒绝。现有路由如果包含无效值，会在网关组兼容性报告中显示为错误，并且不会发布到数据面；其他不受影响的路由仍会正常发布。团队应把无效值改为正整数，或者删除字段以使用 524,288 字节的默认值。

其次，Prometheus 插件元数据不能再禁用决定指标结构的标签，例如延迟指标的 type 或状态指标的 code。旧配置可能让不同测量值合并到同一条指标序列中。升级后，如果更新中的 disabled_labels 包含这类结构性标签，系统会返回 HTTP 400 并拒绝更新；route、service 和 consumer 等非结构性标签仍然可以禁用。

新版本还为会把请求体或响应体读入内存的插件引入默认 64 MiB 缓冲上限。超过上限的请求会被拒绝；超过上限的响应会在限制位置被截断，但 Proxy Cache 是例外：它会直接透传超大响应而不缓存。各日志插件的配置结构现在也会一致地提供日志正文捕获上限。

这些限制把隐含的内存假设变成了可执行的边界。运维人员不应为了保留所有旧载荷而直接提高上限。应先盘点真实载荷大小，找出处理上传或超大 AI 输入的路由，再判断相关插件是否确实需要读取完整正文。提高限制前还应分析工作进程内存和并发量。

控制面的正确性也获得了类似强化。现在，同一资源的并发 PATCH 请求会按顺序执行，避免两个请求都报告成功却由其中一个悄然覆盖另一个。PATCH /apisix/admin/routes 的合并结果也会在写入存储前按照路由配置结构进行验证。

这些变化同样属于信任决策。自动化系统应该能够确信：一个被接受的更新符合配置结构，并且一次报告成功的写入没有被并发操作丢弃。

升级到 3.10.4 前需要检查什么

请结合版本专属的 3.10.4 发布说明 使用滚动升级指南。重点检查项包括：

  1. AI 提供商出站通信： 在预发布环境中捕获 AI Proxy、AI Proxy Multi 和 AI Request Rewrite 的出站请求头。把真正需要的提供商上下文迁移到显式配置中。
  2. 身份传播： 在使用 wolf-rbac 的路由上尝试伪造 X-UserId、X-Username 和 X-Nickname，确认上游只收到已验证的值。如果转发原始 ID Token，应在上游验证签名、签发者、受众和过期时间，并确保日志脱敏。
  3. SSRF 暴露面： 盘点每一个可配置的控制面目标及其解析地址，再决定启用 security.ssrf_protection.enable、重新设计私有依赖，还是记录补偿性控制措施。
  4. 四层流量客户端地址： 只为已知的 PROXY protocol 对端配置 nginx_config.stream.real_ip_from，并验证来自可信与不可信来源的行为。
  5. 日志插件兼容性： 升级前移除为零、负数或带引号的正文大小限制，再通过兼容性报告检查未发布的路由。
  6. 指标元数据： 从 disabled_labels 中移除 Prometheus 结构性标签，并确认仪表盘仍能正确区分状态和延迟指标序列。
  7. 正文缓冲： 在已配置上限处测试请求拒绝、响应截断和 Proxy Cache 透传行为。提高默认限制前重新计算内存余量。
  8. 并发自动化： 在具有代表性的控制面环境中测试并发 PATCH 操作和配置校验失败时的拒绝行为。

Apisix-Plugins 调试响应头现在也能帮助完成这项验证。它会按照真实执行顺序列出实际运行的插件，并标注各自的执行阶段，例如 limit-count#access 和 response-rewrite#header_filter，不再返回无序的已配置插件列表。这样更容易对比预期策略和测试请求真正经过的路径。应把调试响应头限制在适当的环境和工作流程中，避免无意暴露诊断信息。

让每一份上下文都有充分理由跨越网关

零信任常被概括为“从不信任，始终验证”。落实到 API 网关，更具体的原则是：每一份上下文都必须证明自己有充分理由跨越边界。

浏览器凭证不应因为由浏览器提供，就被传递给模型提供商。身份请求头不应因为名称看起来可信，就被当作权威身份。原始 ID Token 不应在上游不会验证和保护它的情况下被转发。一个可配置 URL 不应让控制面无限制访问内部网络。除非 PROXY protocol 地址来自获批对端，否则它不应重新定义客户端身份。配置更新在通过验证并得到一致应用前，也不应被信任。

API7 网关 3.10.4 把这些决策从隐式继承转变为显式行为。这不仅增强了安全性，也提升了可运维性：团队可以检查规则、测试边界，并在架构有意设置例外时明确责任人。

阅读完整的 API7 网关 3.10.4 发布说明，根据自身流量和管理拓扑审查每一道边界，并在全量滚动升级前先进行金丝雀验证。

获取方案