核心要点
- API 安全可能在控制措施之间失效：凭据校验可能过于宽松，重复请求头可能改变策略判断，上游证书校验也可能没有按配置生效。
- API7 网关 3.10.7 发布于 2026 年 9 月 8 日，会拒绝空密码的 Basic Auth 凭据，并修复重复
User-Agent请求头命中拒绝列表时的判断。 - API7 企业版 3.10.7 新增的 JWE Decrypt 插件可以根据加密令牌认证消费者（Consumer），然后通过配置的请求头转发解密后的明文 Payload；它不负责签发令牌。
- TLS 透传和由网关终止 TLS 是两种不同的信任模型：前者将加密保持到后端，后者则由网关建立并校验上游 TLS 连接。
- HTTPS 和
grpcs证书校验现在能更准确地执行所配置的信任规则，因此升级后，过去未暴露的证书或主机名错误可能会变成可见的连接失败。 - Chaitin WAF 的响应上报有助于检测问题，但上报发生在响应送达之后，无法阻止或修改响应。
安全控制通常会被分别评审。身份团队检查认证，平台团队检查网关策略，基础设施团队检查 TLS。但一条生产请求会依次经过所有这些判断。
信任缺口往往就出现在这些判断的连接处：空凭据可能被当作有效凭据；重复请求头可能进入单请求头测试从未覆盖的解析分支；网关虽然配置了上游证书校验，实际连接路径却可能忽略该设置；响应在送达后被上报给安全服务，也可能被误认为能够阻止数据泄漏。
API7 网关 3.10.7 的多项改动共同说明了一条安全原则：信任必须针对生产环境实际使用的请求形态和传输路径来建立。该版本加强了从客户端认证到上游 TLS 的信任链，同时也更清楚地界定了透传与旁路检测的能力边界。
信任不仅会在控制措施内部失效，也会在它们之间断裂
首先要区分两种容易混淆的流量模型。
对于在网关终止的 HTTP 或 gRPC 流量，API7 网关可以认证客户端、解析请求头、应用七层策略，然后重新建立到上游的 TLS 连接。每个阶段都有独立的信任判断。
对于启用 TLS 透传的 Stream 监听器，网关会从 ClientHello 中读取 Server Name Indication（SNI），选择后端，并在不终止 TLS 的情况下转发加密会话。这可以让加密一直保持到后端，但并不会额外增加 HTTP 认证或内容检查环节。
1flowchart LR
2 client[客户端] --> mode{流量模式}
3 mode -->|在网关终止 HTTP 或 gRPC| identity[身份校验]
4 identity --> headers[请求解析]
5 headers --> tls[已配置的上游 CA 与主机名校验]
6 tls --> upstream[上游]
7 mode -->|TCP TLS 透传| sni[基于 SNI 选择后端]
8 sni --> upstream这张图并不表示每条请求都会经过所有控制措施，而是说明团队为什么必须测试实际配置的路径，不能把“网关”视为一个不可拆分的安全边界。
拒绝无法证明的身份
Basic Auth 展示了一个很小的配置值如何改变认证边界的含义。在 3.10.7 之前，如果消费者的密码被保存为空字符串，或者 $env://、$secret:// 引用解析为空字符串，该消费者仍可能使用空密码通过认证。
API7 网关 3.10.7 从两个层面弥合了这个缺口：
- 控制面会拒绝密码为空的消费者或凭据配置。
- 已存在的空密码消费者会在兼容性报告中显示为错误；在修复密码之前，对它的编辑也无法成功。
- 当配置值或解析后的密钥为空时，数据面会拒绝该凭据，返回
HTTP 401，并向错误日志写入警告。
该版本还修复了密码包含冒号时无法认证的问题。Basic Auth 只应在第一个冒号处分隔用户名与密码，之后的所有内容都属于密码。此前的实现会按每个冒号分割，从而截断合法密码。
因此，升级前必须进行一次实际的凭据盘点。不仅要查找直接配置的空值，也要检查当前解析结果为空的密钥引用。随后，再使用一个包含冒号的密码进行测试，确保预发布环境覆盖已修复的解析逻辑。Basic Auth 插件文档仍是配置参考，而特定于版本的迁移风险应以 3.10.7 发布说明为准。
将 JWE 解密视为新的明文边界
JWE Decrypt 插件从 API7 企业版 3.10.7 开始可用，为发送 JSON Web Encryption 令牌的客户端提供了一条认证路径。插件通过令牌的密钥 ID 识别消费者，使用该消费者的 32 字节密钥，并支持 dir 直接密钥管理算法与 A256GCM 内容加密算法。
令牌结构无法解析或无法解密时会被拒绝；对于将受保护头作为 AES-GCM 附加认证数据（AAD）的标准令牌，受保护头被篡改时也会被拒绝。为保持兼容性，不携带 AAD 的旧版令牌仍会被接受，其受保护头不会得到认证。令牌缺失时的处理方式可以配置。有效令牌完成解密后，插件会通过可配置的请求头将明文转发给上游。
最后一步正是需要重点设计的信任边界。令牌到达网关前，加密为其提供保护；网关解密之后，明文请求头就变成了敏感的应用数据。应限制哪些上游能够收到它，避免请求头日志记录该值，并只通过已认证、受保护的网络路径传输它。不要仅依赖 HTTPS 上游：应启用上游服务器证书校验并提供预期的 CA 证书，或使用能够校验上游身份的代理或服务网格。不要使用可能已被其它代理或应用组件赋予不同信任含义的通用请求头名称。
该插件不会创建或签发 JWE 令牌。令牌的签发、密钥分发、轮换与撤销仍由外部系统负责。在 3.10.7 中，显式设置的 alg 值如果不是 dir，或显式设置的 enc 值如果不是 A256GCM，令牌将被拒绝；但省略其中任一字段的令牌仍会被接受。对于标准 RFC 7516 令牌，编码后的受保护头会作为 AES-GCM 的附加认证数据（AAD）进行认证，因此修改该受保护头会导致认证解密失败。为保持兼容性，不携带 AAD 的旧版令牌仍会被接受；这类令牌的受保护头不会得到认证，因此当另一个消费者使用相同密钥时，修改 kid 仍可能成功。
请参考当前的 JWE Decrypt 插件文档了解配置流程。该文档中的令牌生成示例描述的是不携带 AAD 的旧版五段格式；对于 API7 企业版 3.10.7，还应测试上文所述的标准 RFC 7516/AAD 格式，并确认令牌签发方使用的是哪一种契约。还应测试从令牌签发方到上游接收方的完整契约：密钥 ID、密钥编码、算法字段处理、受保护头 AAD 兼容性、令牌缺失时的行为、输出请求头，以及上游处理方式。
测试攻击者真正能够发送的请求形态
安全测试经常使用最规整的请求：一个请求头、一个值和一种常规编码。当生产解析器遇到测试从未覆盖的形态时，攻击者就有了可乘之机。
在 3.10.7 之前，携带多个 User-Agent 请求头的请求可能会让 UA Restriction 的 denylist 判断结果反转。重复的 User-Agent 命中拒绝列表时，请求反而会被允许；未命中时却可能被拒绝。被拒绝的客户端只需发送两次相同请求头，就可能绕过规则。
3.10.7 会对重复请求头命中拒绝列表的请求返回 HTTP 403。只有一个 User-Agent 请求头的请求以及 allowlist 分支从未受到该缺陷影响。
这项修复带来的运维启示并不局限于一个插件：应在网关实际收到请求的层级测试重复请求头。某些客户端库会在发送前合并重复请求头，一些负载均衡器也会在请求到达网关前将其标准化。因此，有效的回归测试应在网关入口捕获请求，并同时确认接收到的请求形态与策略结果。
决定 TLS 在哪里终止，并测试这一实际模型
API7 网关 3.10.7 加强了两种不同的传输模型。它们解决的问题不同，不应被描述为一项组合控制措施。
对于专用的 TLS 透传 TCP 监听器，应设置 tls_passthrough: true，并不设置 tls 或将其设为 false。网关会读取 SNI、选择后端，并原样转发监听器接收的每条加密流，因此 TLS 在后端终止。如果同时启用 tls: true 和 tls_passthrough: true，监听器会以混合模式运行：由匹配到的 stream route 决定每条连接是在网关终止 TLS，还是直接透传。无论采用哪种监听器模型，在 Docker Compose 部署中，相关配置都位于 gateway_conf/config.yaml；在 Kubernetes 中则位于网关 Helm Chart 的 values 配置中。
当后端必须持有证书并拥有加密会话时，TLS 透传很有价值。对于实际被透传的连接，网关不会终止或解密 TLS，因此不要期待对该连接执行 HTTP 认证、请求头策略或响应体检查。应验证 SNI 路由、后端向客户端提供的证书，以及 SNI 缺失或异常时的行为。
第二种模型适用于网关终止客户端流量，并重新建立到 HTTPS 或 grpcs 上游的连接。3.10.7 的多项修复让配置的上游信任策略能够正确生效：
- 如果 HTTPS 上游已启用证书校验并配置了 CA 证书，但没有配置客户端证书，此前由于可信证书库未被应用，所有请求都会失败；现在，所配置的 CA 可以正常校验该上游。
grpcs上游此前会忽略证书校验配置，并使用错误的主机名进行校验；现在，证书校验、所配置的 CA 证书和上游主机名都会生效。- 解析后的 CA 证书库现在按证书集合区分，避免一个上游使用另一个上游的 CA 证书进行校验。
grpcs 修复会刻意让升级问题变得可见。如果启用了证书校验，而证书链无法通过配置的 CA 验证，或者证书的主题备用名称（Subject Alternative Name，SAN）未覆盖上游主机，连接现在会返回 HTTP 502；此前，它可能仍会成功连接。如果 502 同时伴随证书链或主机名校验错误，就说明存在信任不匹配，不应在未经排查的情况下通过关闭校验来规避。其他上游故障也可能返回 502，因此应结合相关错误日志判断原因。
区分旁路检测与强制执行
API7 网关 3.10.7 支持 Chaitin WAF 在上报请求的同时，将响应信息发送给 SafeLine 检测服务。这有助于发现响应体中的数据泄漏、攻击利用结果或异常状态码。
响应上报默认关闭。config.log_resp 用于启用响应上报，config.resp_body_size 以 KB 为单位限制上报的响应体大小，设置为 0 时只上报响应状态和响应头。config.extra_ignored_content_types 可以在内置列表之外继续增加无需上报的响应内容类型。
发送时机决定了它的安全边界：报告是在响应已经送达客户端之后发送的。该能力只用于旁路检测，绝不会阻止或修改响应。应将它用于检测、排查与后续处置，而不能将其描述为数据防泄漏能力。
采集响应也会带来新的数据处理责任。建议从仅上报响应状态和响应头，或设置最小可用的响应体限制开始，排除敏感内容类型，控制 SafeLine 检测结果的访问权限，并在大范围启用前确认数据保留与脱敏要求。
分阶段验证每一道信任边界
请结合滚动升级指南与 3.10.7 发布说明进行升级。聚焦信任边界的灰度计划应包括：
- **Basic Auth 凭据：**查找直接配置或解析后为空的密码并完成替换；测试包含冒号的密码，并确认无效凭据返回
HTTP 401。 - **JWE 契约：**测试使用标准受保护头 AAD 的令牌和不携带 AAD 的旧版令牌，包括标准 AAD 路径下的受保护头篡改场景，以及令牌缺失、格式错误、密钥错误、算法错误和省略
alg/enc等场景；确认上游只在预期请求头中、通过已认证和受保护的路径收到明文。 - **重复请求头：**通过真实入口发送多个
User-Agent请求头，确认命中拒绝列表时返回HTTP 403。 - **HTTPS 上游：**根据实际配置，测试每个自定义 CA 证书包在有无客户端证书时的行为，并确认失败信息对应预期的证书链问题。
- **
grpcs上游：**升级前，根据实际的上游主机核对 CA 证书链与 SAN；如果新的HTTP 502同时伴随证书链或主机名校验错误，应在排除其他上游故障的同时检查信任配置。 - **TLS 透传监听器：**确认 SNI 路由、后端证书呈现方式，并排除依赖网关侧明文检查的错误假设。
- **Chaitin WAF 响应上报：**确认响应体大小限制、忽略的内容类型、访问控制和响应送达后的上报时机；明确记录该信号无法阻止响应。
为每个场景记录预期的允许或拒绝结果。如果在生产流量发现问题之前就明确了失败方式，安全控制会更容易运维。
信任必须贯穿整条请求路径
API 网关安全并不等于已启用插件的总和，而是从客户端发送的第一个字节，到上游提供的证书之间，所有信任判断能够保持连续。
API7 网关 3.10.7 弥合了这条路径上的多个具体缺口：空密码的 Basic Auth 凭据不再成为可用身份；JWE Decrypt 定义了明确的加密令牌契约和明文边界；重复 User-Agent 请求头不再反转拒绝列表判断；TLS 透传将终止位置保留在后端，而由网关发起的 HTTPS 和 grpcs 连接则能更可靠地执行 CA 与主机名校验；旁路响应上报也与强制执行划清了边界。
阅读完整的 API7 网关 3.10.7 发布说明，将每项变化映射到实际使用它的流量路径，并在灰度环境中测试生产系统必须拒绝的请求与证书失败场景。