核心要点
- 多租户 API 安全要求每次配置读取、指标写入、状态更新和门户数据访问都绑定到已认证身份及其授权范围。
- API7 网关 3.10.5 发布于 2026 年 8 月 11 日，在配置、指标和服务注册中心状态方面强化了网关组隔离。
- 控制面现在会校验排序参数、限制自定义插件 schema 解析器的能力，并使用严格权限的临时文件保存生成的部署凭证，从而更安全地处理输入。
- OpenID Connect 新增可选的推送授权请求（PAR）和 DPoP；LDAP Auth Advanced 则可以把目录身份映射到网关消费者。
- 开发者门户修复让解码后的路径、应用所有权、双因素认证执行和出站 SSRF 策略，与批准请求时使用的权限依据保持一致。
- 此版本包含升级可感知的变化：Alibaba Cloud Logging (SLS) 默认验证 TLS 证书、Loki Logger 请求头新增存储时加密，现有控制台会话也会失效一次。
即使 API 平台对每个请求都进行了身份认证，也仍有可能在授权环节犯错。问题往往发生在认证之后：租户标识取自请求体；系统信任指标标签，而不是从连接中推导身份；策略在路径解码前完成检查；或者上传的扩展在解析时获得了超出 schema 所需的权限。
这些都属于上下文错位。凭证可能有效、请求体可能格式正确、请求操作也确实存在，但平台仍可能把决策作用到错误的租户、网关组、应用、路径或进程边界。
API7 网关 3.10.5 在控制面、数据面、开发者门户和身份插件中系统处理了这类问题。其最重要的安全价值并非某一项新功能，而是一条反复出现的设计原则：从已认证通道推导权限，在输入改变特权行为之前加以约束，并从请求入口到状态存储始终维持同一条边界。
这条原则对于企业 API 管理尤为重要。网关平台连接多个团队和环境，因此身份与范围之间哪怕出现细微偏差，也可能演变成跨租户暴露、误导性的运维信号，甚至控制面入侵。
1flowchart LR
2 request[已认证请求或连接] --> identity[已验证身份]
3 identity --> scope[已授权租户、网关组或应用]
4 scope --> validate[校验路径、参数和请求体]
5 validate --> action[执行配置、指标或门户操作]
6 action --> audit[在同一范围内记录结果]
7
8 untrusted[不可信标签和标识] -. 不得定义权限 .-> validate多租户控制始于已认证范围
在共享 API 平台中，标识无处不在。数据面会报告所属网关组，门户用户带有开发者 ID，服务注册中心更新也会指明对应的注册中心。这些标识有助于定位记录，却不应决定调用方可以访问哪些资源。访问决策必须来自凭证及其服务端授权上下文。
API7 网关 3.10.5 修复了多个可能让标识与权限脱节的位置。数据面使用的 etcd 兼容配置端点现在会拒绝已认证调用方网关组命名空间之外的 key。数据面无法再仅通过提供另一个 key，借助这条通道读取、写入或删除其他网关组的配置。
同样的规则也适用于遥测数据。数据面推送指标时，控制面会从已认证连接中推导 gateway_group_id，而不是信任请求体中的标签。服务注册中心健康检查和探测报告也会限定在上报数据面所属的网关组内，不再只按照注册中心 ID 应用结果。
开发者门户也遵循同一模式。API 用量数据现在仅限调用方拥有的应用。即使两个门户中恰好存在相同的开发者标识，也不足以让一方看到另一方的 API 产品名称或每小时调用量。
这些修复为 API 控制面展示了一条实用的零信任原则：客户端提供的标识只能在身份认证已经确定的范围内选择资源，不能扩大这一范围。
对运维人员而言，这条原则不只适用于本次升级。审查自定义集成时，应追问它的租户或网关组上下文来自哪里。最安全的答案应是已验证凭证、会话或双向认证通道，而不是调用方可以改写的请求字段。
特权输入需要更小的执行边界
控制面会接收普通数据面请求从不携带的输入，例如插件包、查询参数、部署清单、证书和配置对象。因此，校验不仅要覆盖数据类型，还必须限制解析这些输入时允许执行的操作。
自定义插件上传流程清楚地体现了两者的区别。API7 网关现在可以把包含入口文件、依赖和元数据的完整自定义插件包作为一个单元分发。同时，3.10.5 也强化了上传时使用的 schema 解析器。解析器只能访问读取声明式 schema 所需的库；执行超过三秒预算的文件会被拒绝。Schema 检查的职责是描述配置，不应演变成在控制面主机上运行的通用程序。
列表端点也获得了类似边界。系统现在会在生成 SQL 前校验 order_by 和 direction。不支持的值会返回 HTTP 400，按有效列排序的行为则保持不变。这样，用户选择的展示方式就不会变成特权数据库查询的一部分。
生成的 Helm 安装脚本现在会通过 umask 077 创建数据面私钥、证书和 CA 文件，使用临时文件名，并在脚本退出时删除文件。在流量路径上，改写后上游 URI 中的控制字符会被百分号编码，不再原样写入上游请求行，从而避免截断请求行并注入请求头。
这些变化都遵循“限制解释范围”的共同模式：schema 只能作为 schema 处理；排序字段只能从允许列表中选择；密钥文件属于短期私密材料；URI 只是数据，不能引入新的请求行边界。
身份证明应抵御重定向篡改和令牌盗用
身份绑定控制还要求在完整认证流程中持续保留证明。API7 网关 3.10.5 为需要把网关流量接入企业身份系统的组织新增了三项能力。
OpenID Connect 插件新增可选的推送授权请求（PAR，RFC 9126）。启用 par.enabled 后，网关通过后端通道把授权参数发送给身份提供商，并仅携带 request_uri 重定向浏览器。敏感或影响安全的授权参数不再需要经过用户代理，降低暴露或篡改风险。
同一插件还新增可选的 DPoP 发送方约束令牌（RFC 9449）。启用 dpop.enabled 后，网关在令牌请求中使用密钥对证明持有权，签发的令牌会绑定到该密钥，从而降低令牌被复制后在其他客户端重放的价值。同时启用 PAR 和 DPoP 时，推送请求会按照规范携带密钥指纹。
新的 LDAP Auth Advanced 插件则为目录身份提供另一条路径。它会在配置的 base_dn 中按照用户属性进行搜索，以解析到的条目完成 bind，并可通过记录的 user_dn 把目录身份映射到网关消费者。这样，消费者级插件、限流和分析能力就可以像处理其他消费者身份一样作用于 LDAP 认证流量。LDAPS 和 StartTLS 默认启用证书验证，连接也会在请求之间复用。
这些能力都需要显式启用并谨慎配置身份提供商。它们不能代替最小权限 scope、令牌生命周期控制或消费者策略，而是强化“用户或客户端”与“网关策略所依据身份”之间的证明链路。
1sequenceDiagram
2 participant B as 浏览器或客户端
3 participant G as API7 网关
4 participant I as 身份提供商
5 participant U as 上游服务
6
7 B->>G: 请求受保护 API
8 G->>I: 推送授权请求（PAR）
9 I-->>G: request_uri
10 G-->>B: 使用 request_uri 重定向
11 B->>I: 完成认证和授权
12 I-->>G: 返回授权响应
13 G->>I: 携带 DPoP 证明请求令牌
14 I-->>G: 返回发送方约束令牌
15 G->>U: 按网关策略发送已授权请求门户安全必须使用同一份解析结果
如果代理和访问控制层采用不同的 URL 规范化方式，就可能产生分歧：策略批准了一个路径，后端却在百分号解码后收到另一个路径。API7 网关 3.10.5 通过在解码后校验路径段，修复了开发者门户后端代理中的这类错位。解码后的路径段如果包含路径分隔符、查询分隔符、片段分隔符或控制字符，请求就会被拒绝。
双因素认证的执行范围也更加精确可靠。登录豁免不再覆盖整个 /api 前缀，而是仅限于确实需要豁免的认证端点。门户在执行强制 2FA 时如果无法加载会话，会阻断请求，而不会在结果未定义的情况下继续。相关修复还确保密码对话框在判断是否需要密码之前等待账号数据，并在启用 2FA 后刷新会话状态。
出站信任策略也实现对齐。原本用于控制面出站连接的 security.ssrf_protection 设置，现在同样适用于开发者门户审批 Webhook 和动态客户端注册。启用后，门户会对环回、私有、链路本地和运营商级 NAT 地址执行相同限制，包括解析到这些地址的主机名。
这些变化共同缩小了“策略检查的路径”“实际执行的会话”和“门户允许访问的目标”之间的差距。
安全默认值可能改变升级行为
部分安全改进会在升级过程中有意呈现为可见变化。Alibaba Cloud Logging (SLS) 插件现在通过 ssl_verify: true 默认验证日志服务器的 TLS 证书。旧版本建立 TLS 连接时不会验证证书。升级后，自签名证书、私有 CA 签发证书、过期证书或其他不受信任证书会导致 TLS 握手失败，批处理器也会丢弃相应日志。升级前应把签发 CA 安装到数据面的可信证书存储中；如果必须临时设置 ssl_verify: false，则应明确评估并接受相关风险。
通过 apisix.data_encryption.enable 启用数据面加密时，控制面现在会对 Loki Logger 的 headers 进行存储时加密。在正常的“先控制面、后数据面”滚动升级期间，3.10.5 控制面可能生成 3.10.4 数据面无法解密的值。使用 Loki Logger 请求头的团队应尽快完成数据面升级，并在两侧都达到 3.10.5 之前避免编辑该插件。
控制台会话 Cookie 也从所有部署共享的编译时常量，改为首次启动时生成并按部署存储的随机 32 字节密钥。现有会话由旧值签名，因此控制面升级后所有已登录的控制台用户都需要重新登录一次。升级前无需修改配置；这次退出正是预期的安全结果。
最后，Docker Compose 部署现在默认使用 radixtree_host_uri 路由器，与 Helm 部署保持一致。普通 host 与路径匹配不受影响，但 host 特定路由和无 host 路由存在重叠路径时，解析结果可能发生变化。需要保留旧行为的团队可以显式配置 radixtree_uri，但应先确认旧结果确实符合希望长期维持的路由策略。
升级前应验证什么
请结合滚动升级指南和 3.10.5 更新日志，验证适用于当前部署的边界：
- 盘点 Alibaba Cloud Logging (SLS) 端点，从数据面验证其证书链，并在发布前安装私有签发 CA。
- 找出使用
headers的 Loki Logger 配置；保持“先控制面、后数据面”的顺序，缩短混合版本窗口，并在所有数据面达到 3.10.5 前避免编辑。 - 提前通知控制台用户需要重新登录一次，并确认按部署生成的会话密钥能够在控制面重启和多副本之间持久保存。
- 对比 Docker Compose 在
radixtree_host_uri下的路由解析结果，尤其关注 host 特定路由和无 host 路由共享重叠路径的情况。 - 使用多个网关组测试数据面配置、指标和服务注册中心上报，确认跨组标识会被拒绝或忽略。
- 在预发布环境中测试开发者门户的编码路径、应用用量可见性、强制 2FA、Webhook 和动态客户端注册。
- 审查每个自定义插件包，确认其 schema 仍为声明式内容，并能在解析器预算内完成处理。
- 只有在验证身份提供商兼容性、证书信任、消费者映射、失败行为和回滚方案后，才启用 PAR、DPoP 或 LDAP Auth Advanced。
在每条边界上明确权限来源
API 网关安全不只是认证第一个请求，还需要让已验证权限贯穿配置命名空间、运维数据、URL 解析、扩展加载、身份交换、门户操作和升级过渡。
API7 网关 3.10.5 让这些关系更加明确。网关组范围来自已认证连接，门户数据来自应用所有权，特权解析器拥有更少能力，OAuth 令牌可以绑定到密钥，而当信任或版本要求不满足时，安全传输和加密配置会以可见方式失败。
这为平台团队提供了一套清晰的采用模型：把每项敏感操作映射到授权它的身份，校验下游组件实际使用的精确表示，并跨租户和版本边界测试失败路径。请阅读完整的 API7 网关 3.10.5 更新日志，再把每项适用变更转化为生产发布前的预发布断言。