更新日志
3.10.10
发布日期:2026-11-11
不兼容变更
插件
-
升级说明
header_prefix现在配置在使用该插件的路由或服务上(包括在 Multi Auth 中配置的 Wolf RBAC),消费者上不再支持该字段。消费者上的appid现在为必填:此前不带appid的消费者也能保存,并匹配为应用 IDunset签发的 Token。网关升级后,会丢弃 Wolf RBAC 配置中header_prefix不是默认值X-的消费者(日志为header_prefix is no longer supported in consumer configuration),以及未设置appid的消费者(日志为property "appid" is required)。使用这些消费者 Token 的请求随后会认证失败,返回HTTP 401。控制面升级时不会转换这些消费 者,重新保存它们会被拒绝,返回HTTP 400。升级前,请把每个自定义的
header_prefix从消费者移到所有使用 Wolf RBAC 的路由或服务上,并从消费者中删除;同时为所有未设置appid的消费者设置appid,依赖此前默认值的消费者设置为unset即可继续接受原来的 Token。header_prefix为X-的消费者无需修改。尚未升级的网关实例只从消费者读取header_prefix,会忽略路由或服务上的该字段,因此从自定义header_prefix从消费者中删除起,到网关组的所有实例完成升级为止,这些实例会以默认前缀X-命名身份请求头。
升级须知
SNI 的 ssl_protocols 中保存的 TLS 协议版本此前从未下发到网关,因此无论保存的是什么,每个 SNI 接受的都是网关全局配置 apisix.ssl.ssl_protocols 中的版本:限制为 TLSv1.3 的 SNI 仍能完成 TLS 1.2 握手。/apisix/admin/ssls API 会忽略该字段,在其写入的每个 SNI 上都保存 TLSv1.2 和 TLSv1.3,响应中也不返回该字段。现在两个 API 都会下发该设置,网关也会执行它。SNI 的协议版本会替换网关全局配置,而不是在其基础上收窄,因此 SNI 也可以放开全局配置不允许的版本。未设置 ssl_protocols 的 SNI 跟随全局配置;SNI API 在请求不带该字段时不再自动填入 TLSv1.2 和 TLSv1.3,未设置时两个 API 的响应中都不包含该字段。此前可以保存的 [] 和包含重复版本的列表,现在会被拒绝,返回 HTTP 400。
升级控制面时,控制面会把保存为 [],或只含 TLSv1.2 和 TLSv1.3(顺序不限,含重复项)的 SNI 的 ssl_protocols 清空,使这些 SNI 继续跟随全局配置,并去掉其他列表中重复的版本。其余保存了列表的 SNI 会立即下发到网关并从此开始生效,尚未升级的网关实例同样会执行。升级前,请检查保存了其他列表(例如只有 TLSv1.3)的 SNI:使用列表之外的版本连接这些 SNI 的客户端将无法完成 TLS 握手。
在 Dashboard 中,未设置 ssl_protocols 的 SNI(升级后大多数存量 SNI 都属于这种情况)的编辑表单必须选择协议才能保存,保存后所选列表会写入该 SNI,它从此不再跟随全局配置。如需修改这样的 SNI 并让它继续跟随全局配置,请通过 API 更新,且不要带 ssl_protocols。Dashboard 的创建表单同样要求选择协议(默认为 TLSv1.2 和 TLSv1.3),因此在 Dashboard 中创建的 SNI 会保存一个显式列表;如需让其跟随全局配置,请通过 API 创建,且不要带 ssl_protocols。
控制面现在会拒绝一些此前接受的 JSON Web Key,且只要有一个 Key 被拒绝,整个 Key Set 都无法使用:
- 身份提供方在
jwks_uri发布的 Key Set 中含有模数超过 4096 位或指数e超出范围的 RSA Key,或者是低阶点的 Ed25519 Key 时,通过 OpenID Connect 进行的 SSO 登录会失败,无论身份提供方是否用该 Key 签名。 - API Usage 服务以
jwks.enable: true运行时(默认关闭),如果jwks.url处的 Key Set 含有上述 Key、长度不是 32 字节的 Ed25519 Key,或含有以带=填充的 base64url 编码的成员,该服务会以HTTP 401拒绝所有携带 Token 的请求。
升级前,请检查 SSO 所用的每个 OpenID Connect 身份提供方 jwks_uri 处的 Key Set;如果 API Usage 服务启用了 JWKS,还要检查 jwks.url 处的 Key Set,确认两者都不含上述 Key。
控制面镜像现在基于 Debian 13 构建,其 CA 证书包中不再包含 emSign ECC Root CA - G3 和 AAA Certificate Services 两个根证书。控制面发起的 TLS 连接(例如连接身份提供方、SMTP 服务器或 Webhook)在服务器证书只能链到这两个根证书之一时,现在会证书校验失败。posix/ 下的时区名称也不再提供,使用此类名称的 TZ 设置或数据库时区需要改为去掉该前缀的名称。网关镜像不受影响。
Token 内省失败时,OpenID Connect 插件现在返回不带 WWW-Authenticate 质询的 HTTP 503,而不是带 invalid_token 质询的 HTTP 401。这包括内省端点返回错误状态码、超时或无法连接,以及响应不是 JSON、active 声明缺失或不是布尔值的情况。只有身份提供方报告 Token 无效时,才返回带 invalid_token 的 HTTP 401。把所有 HTTP 401 都当作需要重新获取 Token 的客户端,在身份提供方不可用时现在会收到 HTTP 503。
active 声明为字符串(例如 "true")的响应此前会被当作有效,请求会被转发。这样的响应现在会被拒绝。如果你的 身份提供方以字符串返回 active,请在升级前修正。
Forward Auth 插件现在通过另一个 HTTP 客户端向授权服务发送请求,每个请求消耗的 CPU 更少。授权服务可能会注意到以下差异:
- 不再发送
User-Agent请求头,此前为lua-resty-http/<version>。 GET请求带有Content-Length: 0。- 会发送
Connection: keep-alive,keepalive为false时也是如此,此时连接仍会在请求结束后关闭。 - 通过
extra_headers设置的空Host会被替换为网关连接的地址。 timeout限制的是读取整个响应的时间,而不是每次读取的时间。
如需恢复此前的客户端,请在网关配置文件中把 plugin_attr.forward-auth.http_client 设为 lua-resty-http;默认值为 ngx_http_ffi_client。
last_retrieve_config_timeGET /api/instances 和 GET /api/gateway_groups/{gateway_group_id}/instances 不再返回 last_retrieve_config_time。该字段记录的是网关实例发起配置请求的时间,而不是收到配置的时间,也没有任何产品功能使用它。如需判断实例是否在线,请使用 last_heartbeat_time。
请在网关组的所有网关实例都升级到 3.10.10 之后,再配置 OpenID Connect 插件的 upstream_headers。较早版本的网关实例会忽略该字段,既不会设置这些请求头,也会把客户端以相同名称发送的请求头原样转发给上游。
新功能
插件
- OpenID Connect
- 新增
upstream_headers选项,可以把已验证 Token 中选定的声明作为请求头转发给上游,不解析 Token 的上游不再需要通过 Serverless 函数再次解码 Token。每一项指定一个请求头以及指向声明的键路径,每一层嵌套对应一个键,因此包含/、.或://的声明名称可以直接使用。声明取自已验证的 Token 或内省响应;在授权码流程中先取自 ID Token,ID Token 中没有的声明再取自用户信息。字符串原样转发,数字和true以文本转发,数组和对象以 base64 编码的 JSON 转发;空数组或空对象以 base64 编码的{}转发;声明缺失、为null或false时不设置请求头。无论认证结果如何(包括以unauth_action: pass放行的未认证请求),所列的每个请求头都会先从请求中移除,因此它要么是已验证的声明,要么不存在。
- 新增
- Wolf RBAC
header_prefix现在可以在路由或服务上设置,路由的身份请求头不再取决于 Token 匹配到的消费者。参见上文的升级说明。
控制面
- 现在可以要求内置用户定期修改密码,并禁止重复使用最近用过的密码。在 Dashboard 中,该策略位于 Organization > Settings > Login Options > Password Policy,也可以通过
/api/system_settings/password_policy管理。password_max_age_days设置密码最长有效期,取值 1 到 365 天;0(默认值)表示关闭策略。password_history_count取值 0 到 24,默认 5,设置策略开启时用户修改自己的密码不能重复使用的历史密码个数;0表示只拒绝当前密码。管理员重置的密码不检查历史。密码超过最长有效期后,用户仍可以登录,但必须先修改密码才能进行其他操作:用该用户的会话或 Basic Auth 发起的其他请求都返回HTTP 401和password expired,Dashboard 会要求输入新密码。访问令牌和 SSO 用户不受约束。GET /api/me在password_expires_at中返回到期时间。升级控制面时,所有存量密码的有效期从升级时刻开始计算,因此升级后开启策略不会立即锁住任何用户。 - 现在可以要求所有内置用户(包括
admin)启用双因素认证,开关位于 Dashboard 的 Organization > Settings > Login Options,也可以通过/api/system_settings/two_factor_policy设置。该开关默认关闭,内置用户只有在为自己的账号启用双因素认证后才能打开它。开关打开时,未启用双因素认证的内置用户仍可以用密码登录,但登录后只能启用双因素认证(Dashboard 会引导完成)或退出登录,其他请求都返回HTTP 401和two factor enrollment required。这类用户的 Basic Auth 请求也会以同样的方式被拒绝;已启用双因素认证的用户的 Basic Auth 本来就会被拒绝,因此 Basic Auth 对所有内置用户都不再可用。访问令牌、Admin API Key 和 SSO 会话不受该开关约束。内置用户(包括admin)同时丢失验证器和恢复码时,可以在 Dashboard 容器中(例如通 过kubectl exec或docker exec)运行/usr/local/api7/api7-ee-dashboard two-factor reset --username <name>恢复;配置文件不在/app/conf/config.yaml时(例如 Docker Compose 部署)需加上-c <配置文件>,即-c /usr/local/api7/conf/conf.yaml。该命令会清除该用户的双因素认证并使其会话失效。 - 现在未激活有效 License 时,用户也可以为自己的账号设置并启用双因素认证。此前这些请求会返回
HTTP 404或HTTP 400,需要启用双因素认证的用户在上传 License 之前无法完成启用。 - 现在不指定网关组也可以读取内置插件目录和内置插件的 Schema。
GET /api/plugins、GET /apisix/admin/plugins/list和GET /apisix/admin/plugins/{plugin_name}不带gateway_group_id时返回内置插件;带上该参数或使用网关组的 Admin API Key 时,与此前一样返回内置插件和该网关组的自定义插件。GET /api/plugins此前不带gateway_group_id时返回HTTP 400。GET /apisix/admin/plugins/list上取值为空的gateway_group_id=参数现在会被拒绝,返回HTTP 400。 - Docker Compose 安装现在也可以在 Podman 上运行,包括启用了 SELinux(Enforcing)的主机,无需手动重新标记或编写覆盖文件。Podman API Socket 未运行时,安装会在做任何改动之前停止,并打印启动它的
systemctl命令。安装脚本启动的 PostgreSQL、Prometheus 和网关容器,以及通过 Dashboard 生成的 Docker 部署命令启动的网关容器,现在都会自动重启。
数据面
- 插件现在最多读取
apisix.max_request_headers_readable个请求头,该项在网关配置文件中设置。默认值100与此前的限制相同,0表示不限制。此前 Request Validation、OPA 和 Forward Auth 等插件只能看到请求的前 100 个请求头。超出限制的请求头仍会转发给上游。 - 在使用 Forward Auth、Request ID 和 Prometheus 插件的路由上,以及
key或count中包含变量的 Limit Count 和 Limit Count Advanced 配置下,网关处理每个请求消耗的 CPU 更少。
缺陷修复
插件
- Forward Auth
- 修复问题:
allow_degradation为true时,如果无法连接授权服务,客户端以upstream_headers中所列名称发送的请求头会原样传给上游,因此客户端可以自行设置上游认为来自授权服务的值,例如用户 ID。现在这些请求头会在转发请求前被移除。
- 修复问题:
- JWE Decrypt
- 修复问题:
strict为false时,不带 Token 的请求会连同客户端发送的forward_header所指定的请求头一起转发,因此客户端可以传入上游认为是解密后 Token 的值。现在请求不带 Token 时会移除该请求头。
- 修复问题:
- Wolf RBAC
- 修复问题:在 Multi Auth 中配置了 Wolf RBAC 且由其他插件完成认证时,客户端发送的
X-UserId、X-Username和X-Nickname请求头会原样传给上游,因此客户端可以自行设置上游认为已由 Wolf 验证的身份。现在这些请求头会从每个请求中移除,只有 Wolf 授权成功后才会设置。
- 修复问题:在 Multi Auth 中配置了 Wolf RBAC 且由其他插件完成认证时,客户端发送的
- OpenID Connect
- 修复问题:携带同一个尚未缓存的 Token 的并发请求会各自调用内省端点。现在它们共用同一次内省请求。
- Prometheus
- 修复问题:为避免为指标设置
expire时出现 CPU 峰值,3.10.8 把指标库回退到了较早的版本,这又带回了两个问题:指标所用的共享字典写满后,Worker 可能进入循环,CPU 持续 100%,流量停止后也无法恢复;该字典中的过期条目也不会被回收。现在指标库已升级到 1.1.1,修复了这两个问题,并减少了导致上述 CPU 峰值的过期条目清理工作。
- 修复问题:为避免为指标设置
- Limit Count、Limit Count Advanced、GraphQL Limit Count、AI Rate Limiting、Limit Req 和 Limit Conn
- 修复问题:使用
redis-cluster策略并设置了redis_cluster_ssl或redis_password时,出现过故障的 Redis Cluster 节点恢复后仍被标记为不健康,因为其健康检查连接时既不使用 TLS 也不带密码。计数存放在该节点上的请求会一直失败(Limit Count 返回HTTP 500),直到重启网关。
- 修复问题:使用
数据面
- 修复问题:在网关配置中启用
apisix.match_uri_encoded_slash时,请求可以通过在路径中编码斜杠,跳过启用了 mTLS 的 SNI 的客户端证书校验。skip_mtls_uri_regex的规则是针对解码后的路径检查的,而路由匹配使用的是把%2F保留在路径段内的路径,因此/public%2Fstatus这样的请求会被^/public/status$这样的规则豁免,却可能被路由到另一条路由(例如/:resource),无需客户端证书即可访问。现在只有当路径的两种形式都匹配规则时,请求才会跳过校验;不带客户端证书的此类请求会被拒绝,返回HTTP 400。 - 修复问题:
gzip插件的buffers.size小于内存页大小(大多数系统上为 4 KiB)时,压缩一个放不进单个缓冲区的响应会导致网关 Worker 崩溃,客户端收不到任何响应。 - 修复问题:请求复用一个仍在建立中的多路复用上游连接时,
dubbo-proxy插件可能返回HTTP 500。
控制面
- 修复问题:已知启用了双因素认证的用户的密码后,可以无限次尝试验证码,已被接受的验证码在其有效期内还可以再次使用,并发请求也是如此。现在连续 5 次输入错误的验证码或恢复码后,该用户的第二因素会被锁定 15 分钟,期间所有验证码(包括正确的)都会被拒绝,返回
HTTP 400和too many failed login attempts, this account is temporarily locked; please try again in about N minute(s),恢复码也不会被消耗。每次锁定都会记录到审计日志。已被接受的验证码及更早的验证码现在都会被拒绝,因此例如登录后立即关闭双因素认证需要使用下一个验证码。关闭双因素认证时输错的验证码也计入同一上限。 - 修复问题:携带无法解码的会话 Cookie(例如为空、被截断或被篡改)的请求返回
HTTP 500而不是HTTP 401,带着这样的 Cookie 登录也会失败。浏览器在修改密码后就会发回这样的 Cookie,因此 Dashboard 显示的是错误而不是登录页。现在这样的 Cookie 会被忽略:请求返回HTTP 401和user not logged in,登录也能正常完成。 - 修复问题:网关实例的每次配置请求都会同时更新数据库中该实例的记录,因此只有在持有该记录的事务(例如心跳)结束后,或者等到数据库超时(默认 5 秒)后,配置才会下发。现在配置请求不再写数据库。
- 修复问题:不指定 网关组时,
GET /apisix/admin/plugins/{plugin_name}、POST /apisix/admin/configs/validate和GET /apisix/admin/plugin_metadata/{plugin_name}/default会在所有网关组中查找自定义插件,因此会返回其他网关组自定义插件的 Schema 或元数据默认值,使用该插件的配置也能通过校验。现在不指定网关组时,对自定义插件的答复与对不存在的插件完全相同。 - 修复问题:Docker Compose 安装在某一步失败时(例如
docker compose up无法启动某个服务)仍会打印API7-EE is ready!并以状态码0退出。现在会以非 0 状态码退出,并打印失败原因、docker compose ps -a以及每个服务最近的日志。以较严格的umask(例如027)解压安装包时,Dashboard 和网关无法读取各自的配置文件而无法启动;现在启动前会把这些文件设为可读。安装包中的文件现在归root所有。由较早的安装包启动的网关容器不会自动重启,请先执行bash run.sh stop,再执行bash run.sh重新创建。
控制台(Dashboard)
- 修复问题:删除 SNI 的确认对话框中显示的是未解析的
{{name}}占位符,而不是需要输入的 SNI 名称。
3.10.9
发布日期:2026-10-29
不兼容变 更
插件
-
升级说明
现在只有当 Keycloak 授予了路由请求的每个权限以及其中的每个 Scope 时,请求才会被转发。此前插件一次性向 Keycloak 请求所有权限的判定,只要其中至少一个被授予就转发请求,因此列出了多个权限或一个权限包含多个 Scope 的路由,会放行只持有其中一部分的用户。这样的请求现在返回
HTTP 403;配置了access_denied_redirect_uri时则跳转到该地址。对于本身已列出 Scope 的静态权限,
http_method_as_scope同样适用:以请求方法命名的 Scope 现在也必须被授予。Scope 名称现在发送时不带前后空格,因此像res#view, delete这样的权限,此前向 Keycloak 请求的是被其忽略的delete,现在要求delete被授予。Keycloak Token 端点的响应无法解析时,插件现在返回HTTP 503。升级前,请确认列出多个权限或 Scope 的路由的用户在 Keycloak 中被授予了全部权限和 Scope。
数据面
-
上游收到的是路由匹配时使用的路径
升级说明路由按 Nginx 规范化之后的请求路径进行匹配:完成百分号解码,解析
..、..%2F、%2e%2e等点段,在#处截断,并合并连续的斜杠。但上游此前收到的是原始请求路径,因此像/admin/..%2Fapi/x这样的请求会匹配/api/*的路由,而上游收到的却是/admin/..%2Fapi/x。现在当 Nginx 规范化了路径时,上游会收到由 Nginx 转义后的规范化路径,其中编码的分隔符会以解码后的形式到达:/a/./b%2Fc到达上游时是/a/b/c。Nginx 只做了百分号解码或只合并了连续斜杠的请求不受影响。没有选项可以恢复之前的行为。如果某个上游依赖于按客户端发送的原样收到点段或编码的斜杠,请在升级前检查它。
-
网关镜像改为基于精简基础镜像构建
升级说明api7-ee-3-gateway镜像现在就是此前以api7-ee-3-gateway-distroless发布的精简镜像,基于 Ubuntu 的镜像不再构建。镜像的名称、标签和默认用户保持不变,但只包含网关所需的库和 BusyBox 工具:没有apt、没有bash,也没有 Perl,因此resty命令行工具无法在其中运行。api7-ee-3-gateway-distroless这个名称不再发布,请改用api7-ee-3-gateway。以root运行的api7-ee-3-gateway-root镜像现在也基于同一精简镜像构建。如果你基于
api7-ee-3-gateway构建自定义镜像,或者在网关容器中运行依赖包管理器、bash或 Perl 的脚本或调试命令,请在升级前做相应调整。
升级须知
上游设置了 tls_verify: true、但没有引用客户端 证书或 CA 证书对象(client_certificate 或 ca_certificates)时,无论是单独设置,还是与已弃用的内联 tls 块一起设置,下发给网关的配置都不带证书校验,网关会接受任意上游证书。现在控制面会下发该设置,网关会校验上游证书。上游未引用 CA 证书时,网关使用其 apisix.ssl.ssl_trusted_certificate 配置中的 CA 证书(默认为系统 CA 证书包)校验,并在配置了 proxy_ssl_crl 指令时检查其中的吊销列表。设置了 tls_verify: true 的上游,如果其证书不被网关信任,此前请求成功,现在会返回 HTTP 502。这是该配置本应有的行为。
升级前已保存的这类上游,升级后仍然不会校验证书,因为下发给网关的配置只在服务被保存时才会重新生成。要为它们启用校验,请在控制面升级后重新保存每个受影响的服务。在此之前,请确认网关信任每个上游的证书(通过 ca_certificates 引用签发该证书的 CA,或将其加入 ssl_trusted_certificate),或者在不需要校验的地方把 tls_verify 设为 false。
本版本中的上游证书校验有两项限制:上游在 ca_certificates 中引用了 CA 证书时,不会对其检查 proxy_ssl_crl 指令中的吊销列表;通过 tls_verify 启用的校验不应用 proxy_ssl_verify_depth。
tls 不能再与证书引用一起使用创建或更新服务或上游时,如果上游同时设置了已弃用的内联 tls 块与 client_certificate 或 ca_certificates,现在会被拒绝,返回 HTTP 400 和 upstream tls cannot be used together with client_certificate or ca_certificates: tls is deprecated, configure the certificates with client_certificate and ca_certificates instead。在 3.10.8 上,这样的写入会被接受,但下发给网关时内联 tls 块会被丢弃,因此内联的客户端证书从未提交给上游。tls_verify 只是一个开关,不属于证书引用,仍可与两者任一同时使用。
已经保存的这类上游会照旧下发给网关,但在删掉内联 tls 块或证书引用中的一方之前,对其服务或上游的下一次更新都会被拒绝。编辑之前,请先把证书改为通过 client_certificate 和 ca_certificates 配置。
控制面不再包含 3.8.0 之前版本的数据库升级步骤。要从这类版本升级,请先升级到 3.10.8 或更早的 3.8、3.9、3.10 版本,再升级到 3.10.9。
3.4 及更早版本的网关实例用于上报指标的接口也已移除。这类网 关实例仍然可以连接控制面,但其指标会被以 HTTP 404 拒绝,因此它们的流量不再出现在监控中。请将这些网关实例升级到更新的版本。
3.10.9 控制面首次启动时,会为没有主键的数据库表添加主键,每张表会因此被重写一次。所需时间以及表被锁定的时间随表的大小增长,最大的表通常是 dataplane_api_calls、gateway_instance 和 consumer_identifier。请据此规划升级窗口。如果你曾为规避 PostgreSQL 逻辑复制报错把这些表设为 REPLICA IDENTITY FULL,升级后可以改回 DEFAULT。
请在网关组的所有网关实例都升级到 3.10.9 之后,再启用新的 Request Decompress 插件以及使用 https:// 服务器地址的 Consul 注册中心。更早版本的网关实例没有该插件,会丢弃使用它的配置,并且会跳过使用 https:// 地址的 Consul 注册中心。
网关运行时现在使用 OpenSSL 3.5,它在 TLS 1.3 握手中增加了后量子混合密钥交换组 X25519MLKEM768。网关发往上游的 TLS ClientHello 因此变大,网关与上游之间的部分老旧网络设备可能无法正确处理。
新功能
插件
- Request Decompress
- 新插件会解压以
Content-Encoding: gzip或deflate发送的请求体,使路由上的插件(例如 OAS Validator)读取解压后的请求体。默认情况下上游收到解压后的请求体,forward_compressed为true时则收到压缩的请求体。max_req_body_size同时限制收到的请求体和解压后的请求体的大小。
- 新插件会解压以
- Prometheus
- 全部四个流指标
apisix_stream_connection_total、apisix_stream_active_connections、apisix_stream_status和apisix_stream_bandwidth现在都带有service和service_id标签,表示所匹配流路由的服务,并与 HTTP 指标遵循相同的prefer_name规则。活动连接数与带宽在会话仍处于打开状态时就会按服务拆分。没有到达带服务的流路由的会话,仍计入其监听地址的无标签合计。监听地址上出现的每个服务都会占用流指标共享内存区域(nginx_config.stream.metrics_zone_size,默认1m,约可容纳 750 个槽位)中的一个槽位。该区域占满后,新服务的活动连接数与带宽只计入其监听地址的合计。
- 全部四个流指标
控制面
- Consul 注册中心现在可以使用
https://服务器地址,同一注册中心中可以混用http与https地址;不带端口的https地址使用端口443。新增的ssl_verify选项默认为true,控制是否校验 Consul 服务器的证书,同时作用于网关和控制面自身发起的注册中心查询。在 Dashboard 中,Consul 注册中心表单新增了 SSL Verify 开关。 - Nacos 或 Consul 注册中心现在可以通过新增的
allow_control_plane_access选项标记为控制面不可访问,默认值为true。设为false时,控 制面不会向该注册中心发出任何请求,用于填充命名空间、分组、数据中心和服务选择框的注册中心查询会直接被拒绝,返回HTTP 400和control plane access to this service registry is disabled (allow_control_plane_access is false),而不是以连接错误失败。网关仍会像以前一样从该注册中心发现服务节点。在 Dashboard 中,注册中心表单新增了 Allow Control Plane Access 开关;使用已关闭该开关的注册中心的服务,以手动输入文本的方式填写要发现的服务(Nacos 还包括命名空间、分组和元数据),而不是从选择框中选择。 - 注册中心的状态现在反映网关组内所有在线网关实例的情况,而不再取决于最后一个上报的实例。所有在线实例都能连接时为
healthy,都无法连接时为lost_connection,只有部分实例能连接时为新增的partially_lost_connection;注册中心的 API 响应会在lost_connection_instances中列出已失去连接的实例,包括主机名和各自失去连接的时间。离线实例不参与统计。新增告警事件 Service Registry Lost Connection(service_registry_lost_connection):网关组内任一在线网关实例与某个注册中心失去连接超过所配置的时长时通知一次,恢复后再次失去连接时才会再次通知。在 Dashboard 中,部分失去连接的注册中心以单独的标签显示,鼠标悬停在状态上会列出失去连接的实例。 - 当用于监控的 Prometheus 中还保存着其他系统(例如开源 APISIX)的同名指标时,现在可以配置额外的标签匹配器,例如
job != "apisix",它们会被加到监控页面、共享字典监控以及基于 Prometheus 的告警策略的每个指标查询中。可以在 Dashboard 的 Gateway Settings > Monitoring 中管理,也可以通过/api/system_settings/monitoring管理。
控制台(Dashboard)
- 在编辑表单中,内容发生修改之前 Save 按钮处于禁用状态。
- OpenID Connect 插件的快速开始模板现在可以折叠,为配置编辑器留出更多空间。添加插件时模板默认展开;编辑已有配置或应用模板后,模板会折叠。
缺陷修复
插件
- Limit Count、Limit Count Advanced 和 GraphQL Limit Count
- 修复问题:
rules列表中两条规则的key相同时,控制面会接受,但网关会拒绝该配置。路由、服务、全局规则、消费者或 Workflow 动作被保存了,但网关会丢弃它:新建的路由返回HTTP 404,更新的路由则继续运行之前的配置。现在这样的配置会被拒绝,返回HTTP 400和invalid limit-count plugin: duplicate key '<key>' in rules。
- 修复问题:
- AI Proxy 和 AI Proxy Multi
- 修复问题:对于 Anthropic Messages 协议,prompt token 数没有包含缓存读取和缓存写入 token;在流式响应中,只在最后的
message_delta事件里上报的缓存 token 完全没有被读取。因此对于使用了 prompt 缓存的请求,$llm_prompt_tokens、$llm_total_tokens、apisix_llm_prompt_tokens,以及 AI Rate Limiting 在total_tokens或prompt_tokens策略下消耗的配额都偏低。现在 prompt token 包含缓存读取和缓存写入 token,与 OpenAI 兼容服务商一致。Anthropic 客户端经由 OpenAI 兼容上游提供服务时,转换后响应中的input_tokens不再包含缓存写入 token,因此不会再被重复计算。 - 修复问题:对于 Amazon Bedrock,prompt token 数没有包含 Converse API 单独上报的缓存读取和缓存写入 token,缓存 token 计数也始终为零,流式和非流式响应都是如此。因此对于使用了 prompt 缓存的请求,日志和指标中的 token 用量,以及 AI Rate Limiting 消耗的配额都偏低。现在 prompt token 包含缓存读取和缓存写入 token。
- 修复问题:对于 Anthropic Messages 协议,prompt token 数没有包含缓存读取和缓存写入 token;在流式响应中,只在最后的
- OAS Validator
- 修复问题:从
spec_url获取的规范在没有任何路由再使用后,仍然留在每个 worker 的内存中;修改插件元数据中的spec_url_ttl后,之前缓存中的所有规范也都不会释放。对于spec_url经常变化的路由(例如带版本号的规范地址),worker 内存会随每次变化而增长,直到 worker 内存耗尽。现 在在spec_url_ttl秒内没有被任何请求使用的规范会被释放。
- 修复问题:从
数据面
- 修复问题:Consul 的 catalog 与 health 两个监听几乎同时返回时,Consul 服务发现可能停滞。网关记录
bad argument #1 to 'str_sub' (string expected, got boolean),不再从注册中心获取变更,使用该注册中心的路由可能返回HTTP 503和consul service not found。每次发生还会在网关的特权进程中泄漏一个连接,泄漏到一定数量后,其所有后台任务都无法运行,包括向控制面发送心跳。 - 修复问题:网关实例启动时或注册中心配置变更时就已经无法连接的注册中心,从来不会被上报为失去连接,其状态会一直停留在
connecting,直到恢复连接。健康检查只失败了一次探测的注册中心,也可能被上报为失去连接。现在每个网关实例只在健康检查达到不健康阈值后才把注册中心上报为失去连接,并且只在一次探测成功之后才上报为健康。
控制面
- 修复问题:Nacos 或 Consul 注册中心的服务器地址不带端口(例如
http://registry.example)且配置了健康检查时,下发给网关的健康检查端口为空。网关随后会中止服务发现的初始化,因此使用该网关组其他注册中心的路由(包括带端口的注册中心)也可能返回HTTP 503。现在控制面对http使用端口80、对https使用端口443,即网关的注册中心客户端实际连接的端口。已有的注册中心无需编辑即可获得该端口。 - 修复问题:从 Dashboard 发起的 Nacos 或 Consul 查询失败时,错误信息(也会显示在 Dashboard 中)可能包含注册中心的凭据:Nacos 访问令牌、AK/SK 签名参数,以及
user:password@形式服务器地址中的用户名。现在错误信息只包含主机、路径和失败原因。 - 修复问题:并发写入多个全局规则时(例如 ADC 并行同步全局规则插件时),部分插件可能从下发给网关的配置中丢失,而控制面中仍然列出它们,之后再执行
adc sync也发现不了差异,无法修复。在 SQL Server 上,这类并发写入还可能因死锁返回HTTP 500或HTTP 504。现在写入的每个插件都会被下发,并发写入也不再死锁。 - 修复问题:审计日志表很大时,每晚的过期审计日志清理会超时并回滚,一条也没有删掉,过期日志因此不断累积。现在过期日志按事件时间分批删除,积压的数据会在升级后的第一次清理中删除。
- 修复问题:DP Manager 的访问日志会记录网关每次按 key-auth 查询消费者以及查询开发者门户凭据时使用的明文 API key,查询不存在的 key 时,
HTTP 404响应体中也会包含该 key。现在访问日志中的 key 会被屏蔽为***,响应中也不再包含它。 - 修复问题:配置规模很大(例如数万个服务和路由)时,Dashboard 启动失败并报
Failed to start: context deadline exceeded,之后每次重启都会失败。现在 Dashboard 启动时加载配置更快,并且不再设置固定的启动期限,启动可以耗时多久交由部署平台(例 如 Kubernetes 探针)约束。 - 修复问题:部署多个 Dashboard 副本时,通过一个副本写入的服务或路由,最长要过五分钟才会被其他副本的路由冲突检查纳入,在此期间可能创建出相互冲突的路由。
- 修复问题:证书、CA 证书和 SNI 的使用情况列表,以及服务列表的
hosts过滤,匹配服务的方式与网关匹配 SNI 的方式不一致,结果还因数据库而异。视数据库不同,通配 SNI 中的点号可能匹配任意字符,通配 SNI 可能一个服务都匹配不到或匹配多级子域,host 中的_可能匹配任意单个字符。现在所有数据库上通配值只匹配一级 label,其他值只匹配完全相同的 host。 - 修复问题:在开启了逻辑复制的 PostgreSQL 上(托管数据库的蓝绿部署就使用逻辑复制),由于多张控制面数据表没有主键,对它们的更新和删除会失败,导致网关心跳和网关实例删除返回
HTTP 500。现在每张控制面数据表都有主键。参见上文的升级说明。
控制台(Dashboard)
- 修复问题:在告警策略中,为状态码类事件选择了服务或路由后再切换到其他事件,隐藏的服务或路由仍会保留在策略的作用范围中。
- 修复问题:资源详情页的标题会截断较长的标签值。现在会显示完整的值。
- 修复问题:打开 Jaeger 中已不存在的调试会话链路时,只显示通用的错误信息。现在 Dashboard 会说明该链路在 Jaeger 中已不可用。
3.10.8
发布日期:2026-10-09
不兼容变更
插件
-
升级说明
通过远程 introspection 校验 Token 时,
claim_validator.issuer.valid_issuers中的签发者白名单现在会真正生效。introspection 响应中的iss缺失或不在白名单内时,请求会被拒绝,返回HTTP 401和WWW-Authenticate: Bearer realm="apisix", error="invalid_token", error_description="issuer validation failed",请求不会到达上游。在 3.10.7 上,introspection 路径不会应用这份白名单,这样的 Token 会被转发到上游。升级前,请检查所有同时配置了
introspection_endpoint和claim_validator.issuer.valid_issuers的openid-connect路由,确认身份提供方的 introspection 响应中带有位于白名单内 的iss。 -
升级说明
数据面现在会按照 SAML 规范的要求校验 SAML 响应,且无需任何新增配置。出现以下任一情况时,登录会被拒绝:断言带有
AudienceRestriction,但其中没有列出本服务提供方(未设置sp_audiences时即sp_issuer);断言的使用时间超出其NotBefore与NotOnOrAfter窗口 60 秒以上;断言的Recipient,或响应的Destination,与本服务提供方的断言消费服务(ACS)URL 不一致;断言对应的登录请求并非当前会话发起的那一个。此外,身份信息现在只会从已验证签名覆盖的断言中读取。在 3.10.7 上,以上各项都不会被检查。未设置
sp_acs_url时,ACS URL 由回调请求的协议和主机拼出。如果网关部署在终止 TLS 却不设置X-Forwarded-Proto、或会改写主机名的负载均衡器或 Ingress 之后,网关拼出的 URL 就会与身份提供方写入Recipient的 URL 不一致,升级后所有登录都会被拒绝。升级数据面前,请为部署在此类代理之后的路由把
sp_acs_url设置为对外的回调 URL;如果身份提供方签发断言时使用的受众不是sp_issuer,请设置sp_audiences;并确保网关的时钟已同步。网关实例升级时正在进行中的 登录会重新开始,而不会被拒绝。 -
batch-requests
升级说明在 3.10.1 引入的子请求数量上限之外,该插件现在还会限制其聚合的响应体大小。单个子响应超过
max_response_body_size(默认1048576字节,即 1 MiB),或一个批次的子响应合计超过max_response_body_size_total(默认10485760字节,即 10 MiB)时,会返回HTTP 502,例如{"error_msg":"response body of pipeline request 1 exceeds max_response_body_size"}。没有Content-Length的子响应同样会被计量。在 3.10.7 上,这两项限制都不存在,每个子响应体都会被完整缓存。两项限制都是
batch-requests插件元数据的配置项。如果业务依赖批量获取大响应,请在升级数据面前调大这两个值。 -
升级说明
每条规则的
actions现在必须恰好包含一个[name, conf]。带有多余元素的动作和包含多个动作的规则,在 3.10.7 上会被接受、存储并正常运行。控制面现在会拒绝这两种形状,返回HTTP 400和指明问题的消息,例如invalid workflow plugin: invalid action: expected [name, conf]或workflow plugin: rules.0.actions: Array must have at most 1 items。升级前已存储的这两种形状的 workflow 配置,在其网关实例升级后会成为配置兼容性报告中的 error 级别条目,需要先改正才能再次编辑。
升级须知
Stream 路由现在可以通过控制面配置 sni、snis 和 tls_passthrough。Stream 路由带有数据面不支持的字段时,数据面会拒绝整条 Stream 路由,该路由在对应网关实例上随即停止服务。snis 从 3.10.8 起才被支持,因此 3.10.7 及更早版本的数据面会拒绝设置了它的 Stream 路由;tls_passthrough 从 3.10.7 起被支持。
API7 企业版按先控制面、后数据面的顺序升级。在网关组的所有数据面都运行 3.10.8 之前,不要在 Stream 路由上配置 snis;只要还有数据面低于 3.10.7,就不要使用 tls_passthrough。单个 sni 在本控制面接受的所有数据面版本上都受支持。
新功能
插件
- SAML Auth
- 新增若干配置项,用于收紧或调整登录响应的校验方式。
idp_issuers限定接受哪些签发者;sp_audiences设置本服务提供方所对应的受众;sp_acs_url固定断言消费服务 URL,而不是由请求拼出;clock_skew设置断言时间戳的容差(默认60秒)。replay_dict指定一个共享字典,已接受的断言会在其中保存到它不再可被接受为止再加上clock_skew,不带过期时间的断言则保存replay_ttl秒(默认600),使每条断言在同一个网关实例上只能被接受一次。字典已满时,登录仍会成功,但该断言不会被记录,网关会记录一条错误日志。网关默认为此声明了plugin-saml-auth-replay(10 MiB),其大小可在网关配置文件的nginx_config.http.lua_shared_dict下修改。
- 新增若干配置项,用于收紧或调整登录响应的校验方式。
- OpenAPI to MCP
- 新增
cache_enabled(默认true)和cache_ttl(默认3600秒),使每条路由可以自行决定其 OpenAPI 文档生成的工具缓存多久。把cache_enabled设为false后,每个会话都会重新读取文档,适合文档仍在变动的情况。这两个配置项需要api7/openapi-to-mcp边车 1.0.5 或更高版本;本版本随附 1.0.6。
- 新增
- Limit Count、Limit Count Advanced、GraphQL Limit Count、Limit Conn、Limit Req、AI Rate Limiting 和 AI Cache
- 与 Redis 建立 TLS 连接时现在会发送服务器名称(SNI),新增的
redis_server_name配置项用于设置它。未设置时发送redis_host,但redis_host为 IP 地址时不发送。此前不会发送任何服务器名称,因此开启redis_ssl后,无法连接按名称路由 TLS 连接的 Redis 端点,许多托管 Redis 服务都属于这种情况。
- 与 Redis 建立 TLS 连接时现在会发送服务器名称(SNI),新增的
- AI Rate Limiting
cost_expr现在可以使用嵌套在对象中的数值型 usage 字段,字段名由各层键名以__连接而成。例如,OpenAI Responses API 把缓存 Token 数放在input_tokens_details下的cached_tokens中,表达式中写作input_tokens_details__cached_tokens。顶层字段的名称不变,现有表达式不受影响。连接后的字段名需要 3.10.8 的数据面;较早版本的数据面会把它们计为0,导致请求的计费低于表达式的本意。
- Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting
$rate_limiting_info变量现在还会描述请求所计入的窗口:窗口类型和大小、请求是被放行还是被拒绝、请求给计数器增加了多少、当前窗口的起止时间和计数、滑动窗口中加权后的上一个窗口,以及延迟同步判定时所依据的快照。计数器无法更新的请求(例如 Redis 不可达时)会被记录为decision为error,而不会看起来像被拒绝;键中含有引号或反斜杠时,该变量的值也不再是非法 JSON。字段顺序不再固定,并且新增了字段,因此按位置解析该值的日志处理流程必须改为按 JSON 解析。
控制面
- Stream 路由现在可以按客户端 TLS 握手中的服务器名称(SNI)匹配,并可以把 TLS 会话透传给后端。
sni设置一个名称,snis设置多个;*.example.com这样的名称匹配example.com下的所有名称,单独的*匹配任意名称,匹配不区分大小写,两个字段不能同时设置。在网关配置文件中同时声明了tls和tls_passthrough的监听端口上,由匹配到的 Stream 路由上的tls_passthrough决定连接是原样透传,还是在网关上终止 TLS。这些字段可以通过 Admin API 和 Dashboard 的 Stream 路由表单配置。此前控制面会丢弃它 们,因此同一端口上的 Stream 路由无法按 SNI 区分。各字段所需的数据面版本参见升级须知。 - 现在可以通过路由 ID 查找服务。服务列表接口的
search参数还会完整或部分匹配网关组中 HTTP 路由和 Stream 路由的 ID,并返回该路由所属的服务。以空白分隔的多个关键词仍按 AND 语义组合,因此一次查询可以同时包含服务字段和路由 ID。Dashboard 的服务搜索提示也已加入这一匹配方式。 - 离线安装包现在包含
api7/openapi-to-mcp边车镜像,因此在离线环境中也可以使用openapi-to-mcp和mcp-tools-acl插件。run.sh start会加载该镜像;边车仍需在网关旁、与网关处于同一网络命名空间中启动。
控制台(Dashboard)
- 服务、路由、Stream 路由、消费者和全局规则上的插件卡片新增了启用/禁用开关,插件编辑器中也有同样的开关。禁用插件会保留其配置,并让网关不再执行它。此前需要手动编辑
_meta.disable才能做到。 - 控制面版本号显示在侧边菜单底部的页脚中,点击即可复制。
缺陷修复
插件
- AI Aliyun Content Moderation
- 修复问题:流式返回的模型响应不带
usage字段时,最终的审核检查会被跳过,客户端收到的回答不带任何审核结果。如果响应结束时也没有[DONE]事件,客户端就一直收不到它。现在最终检查总会执行并报告结果,上游未发送[DONE]时由网关补发。被网关的max_response_bytes或max_stream_duration_ms截断的流仍然不会以[DONE]结束。
- 修复问题:流式返回的模型响应不带
- AI Proxy
- 修复问题:周期性刷新时如果没有新内容可发送,流式响应可能被提前截断,并被记录为客户端断开。SSE 事件被拆分到多次读取中,或者有插件缓存响应体时,都可能出现这种情况。
- feishu-auth 和 dingtalk-auth
- 修复问题:授权码没有绑定到发起登录的浏览器会话,因此从别处获得的授权码在任何出示它的会话上都会被接受(登录 CSRF)。现在跳转到身份提供方时会携带一个随机的
state,回调中state缺失或与会话不匹配时,请求会被拒绝,返回HTTP 401和{"message":"Invalid state"}。网关实例升级时正在进行中的登录需要重新开始。自行获取授权码的集成应通过X-Feishu-Code或X-DingTalk-Code请求头传入授权码,该方式的处理与之前相同。
- 修复问题:授权码没有绑定到发起登录的浏览器会话,因此从别处获得的授权码在任何出示它的会话上都会被接受(登录 CSRF)。现在跳转到身份提供方时会携带一个随机的
- Prometheus
- 修复问题:指标库
nginx-lua-prometheus-api7在 3.10.5 中进行了升级。在 3.10.5、3.10.6 和 3.10.7 上,如果在网关配置文件的plugin_attr.prometheus.metrics下为指标设置了expire,该指标库可能导致网关 worker 出现 CPU 突刺。为避免这一问题,本版本将指标库回滚到 3.10.1 及更早版本所用的版本。expire选项仍然生效,无需修改任何配置。
- 修复问题:指标库
- Limit Count、Limit Count Advanced 和 GraphQL Limit Count
- 修复问题:设置了
sync_interval时,只拒绝请求的网关实例在其本地计数过期后,就不再从 Redis 刷新缓存的配额,而是依据过时的数值持续拒绝请求,直到缓存的配额本身过期。使用滑动窗口时,这样的实例会在窗口剩余时间内一直沿用上一个窗口的权重,放行的请求远少于限额允许的数量。Redis 不可达时,这样的实例还会在每次同步时给本地的回退计数器计数,尽管它没有放行任何请求。
- 修复问题:设置了
数据面
- 修复问题:开启
apisix.normalize_uri_like_servlet后,发往上游的请求与参与路由匹配的请求不一致。路径中百分号编码的?(%3F)会被解码,导致其后的内容全部变成查询字符串;客户端自己的查询字符串会被丢弃;服务的strip_path_prefix会被忽略,上游收到的路径仍带着前缀。 - 修复问题:引用了数据面上不存在的插件(例如未对该网关组启用的自定义插件)的 Stream 路由会被整条丢弃,导致该路由停止服务。现在会跳过该插件,路 由继续工作,与 HTTP 路由原有的行为一致。被跳过的插件不会执行,因此如果它承担访问控制(例如
ip-restriction),请确认该插件已对网关组启用。 - 修复问题:配置兼容性报告不包含 Stream 路由,因此即使某些 Stream 路由的配置无效或引用了不可用的插件,网关实例仍可能被报告为没有问题。现在 Stream 路由会像其他资源一样被报告。
- 修复问题:网关启动过程中写入的配置变更可能丢失且没有任何报错,因为配置监听可能在 etcd 可达之前就已启动。受影响的 worker 会一直运行旧配置,直到同一资源再次被修改。
- 修复问题:网关的 RPM 安装包不包含 S3 和 Azure Blob 客户端库,因此通过 RPM 安装的网关无法使用以 S3 或 Azure Blob 存储为后端的回退控制面。
控制面
- 修复问题:Workflow 规则中的动作没有配置时(例如
[["return"]]),控制面会返回HTTP 500,路由也不会被创建。现在这样的规则会被拒绝,返回HTTP 400和invalid workflow plugin: invalid action: expected [name, conf]。 - 修复问题:控制面会接受网关无法运行的 DeGraphQL
query,包括 subscription、null字面量、块字符串,以及片段定义或变量定义上的指令。路由可以保存,但网关会丢弃它,访问该路由返回HTTP 404。现在这样的查询会被拒绝,返回HTTP 400和指明具体语法的消息,例如degraphql does not support subscription operations。反过来,选择集为空的查 询网关可以运行,现在也会被接受。 - 修复问题:JWE Decrypt 消费者的密钥以
$env://或$secret://引用给出时会被拒绝,返回HTTP 400和the secret length should be 32 chars(设置了is_base64_encoded时为the secret should be a base64url encoded string),因为控制面把引用本身当作密钥来校验。现在引用会按原样保存,由网关在运行时解析。 - 修复问题:将 3.8.x 或 3.9.x 的控制面直接升级到 3.10.6 或 3.10.7 时,如果有服务使用了自定义插件,升级会失败:dashboard 不断重启并报
custom plugin encrypt fields not found in cache,始终无法启动;先升级到 3.10.5 再继续升级则不受影响。直接升级到 3.10.8 可以完成,结果数据与分两步升级相同。 - 修复问题:调试会话中列出的链路已不在 Jaeger 中时(超出保留期,或者在内存中保存链路的 Jaeger 重启后丢失),打开或下载该链路会返回空的
HTTP 500;Jaeger 无法访问时,任何此类请求也会返回同样的错误。现在链路详情和下载接口会返回HTTP 410并说明该链路在 Jaeger 中已不可用,或返回HTTP 503和Jaeger is unavailable。
控制台(Dashboard)
- 修复问题:在调试会话的链路视图中,每个跨度名称前都带着同一个服务名前缀,且跨度名称列无法调宽。现在去掉了该前缀,列宽可以调整,服务名仍会显示在跨度详情中。
- 修复问题:点击顶部菜单中的菜单项时,如果正 要离开的页面在下一个页面仍在加载时更新了自己的地址,点击可能没有任何反应,或者跳回首页。
3.10.7
发布日期:2026-09-08
不兼容变更
插件
-
升级说明
Basic Auth 的密码不能再为空。控制面现在会拒绝密码为空字符串的消费者或凭据,返回
HTTP 400和basic-auth plugin: password: String length must be greater than or equal to 1。在 3.10.6 上,同样的请求会返回HTTP 200并被存储下来。升级后,已存储的空密码消费者会在配置兼容性报告中变成一条 error 级别的条目,并且对它的任何后续修改都会被拒绝,直到设置了密码为止。
数据面现在同样按失败关闭处理:解析结果为空字符串的密码( 包括解析结果为
""的$env://或$secret://引用)会被拒绝,返回HTTP 401并在错误日志中记录一条 warning。在 3.10.6 上,这样的消费者用「用户名 + 冒号 + 一个空格」这样的凭据即可认证成功。升级前请检查是否存在密码为空、或密钥引用解析结果为空的 Basic Auth 消费者和凭据,并为它们分别设置真实的密码。
控制面
-
网关无法区分的路由会被拒绝
升级说明创建或更新路由(
POST/PUT/PATCH /apisix/admin/routes)以及更新服务(PUT/PATCH /apisix/admin/services/{id})时,如果结果会让同一个网关组中出现两条在相同优先级下、对相同 HTTP 方法匹配相同 URL 的路由,请求现在会被拒绝,返回HTTP 400。从 OpenAPI 规范导入服务同样会因此被拒绝,因为它经由同一条路径创建路由——因此其操作会归并成两条无法区分的路由的规范,现在无法再导入。错误信息中会指出与之冲突的那条路由,例如route "get-again" conflicts with route "get" (id: ...) of service "first" (id: ...): both match "httpbin.org/get" for all HTTP methods at priority 0.只有相同优先级下的完全重复才会被拒绝。匹配相同 URL 但优先级不同、HTTP 方法只是部分重叠或完全不相交、路径是包含关系而非完全相同的两条路由,仍然会被接受;带
vars的路由同样不受影响,因为它们基于 URL 比较无法表达的条件进行匹配。未激活的服务被排除在外,而重新激活时会进行检查,因此无法借由未激活的服务把重复路由夹带进来。此前只有 Dashboard 的路由冲突弹窗划出了这条界线,因此 ADC、
a7以及直接调用 Admin API 的调用方都可以写入网关无法区分的路由,而且没有任何地方会提示。升级后已有的重复路由仍然继续处理流量,但对其中任意一条路由的下一次修改都会被拒绝;对拥有这样一对路由的服务而言,任何更新都会被拒绝——包括仅修改描述或标签——因为每一次更新服务都会重新校验它下面的所有路由。升级前请检查网关组中是否存在重复路由,并为每一对中的一条改用不同的路径、不同的 HTTP 方法或不同的优先级。
升级须知
兼容性报告现在按问题分组,忽略规则则按数据面上报的机器可读 reason 进行匹配。两者都依赖数据面以结构化数据的形式上报兼容性问题,这一能力在 3.10 线自 3.10.7 起具备,在 3.9 线自 3.9.20 起具备。API7 企业版的升级顺序是先控制面、后数据面,因此在升级窗口内,3.10.7 的控制面面对的是尚未以这种方式上报的网关实例,对这些实例来说两个能力都不生效。
这类数据面把每个问题上报为一句渲染好的英文句子,其中不含机器可读的 reason。控制面在心跳到达时就会丢弃这类记录,因此该实例的兼容性报告是空的。实例上真实存在的问题——被数据面拒绝的资源、数据面没有的插件——都不会展示出来,忽略规则也没有任何可作用的对象。受影响的是 3.10 线上低于 3.10.7、3.9 线上低于 3.9.20,以及所有 3.9 线之前的网关实例——支持范围从 3.2 起算,这些版本同样不会上报结构化问题。运行 3.9.20 或更高版本的实例上报的是结构化问题,本控制面可以正常渲染。请预期在这类实例完成升级之前报告是空白而非可信的,不要把空白的报告当作没有问题。
实例本身仍会由版本规则标记为需要升级,因此不会悄无声息地显示为已是最新。这只影响兼容性报告的展示。它不会影响流量,也不会影响网关实例实际运行的配置;网关实例升级完成后,报告即恢复为文档描述的行为。
ca_certs 列表现在会被拒绝控制面现在会拒绝上游中把 tls.ca_certs 设为空列表的 traffic-split 插件配置,返回 HTTP 400。在 3.10.6 上,同样的写入会被接受。
这只涉及插件配置这条路径。以常规方式配置的上游不受影响:控制面在下发之前就会丢弃空的 ca_certs,这种形态从来不会被下发到数据面。
这类配置在 3.10.6 上其实也从未生效:数据面的上游 schema 校验会失败并丢弃该配置,而控制面却报告成功。真正的变化是,原本静默的失败现在会被明确地报出来。
如果已经存有 tls.ca_certs 为空的 traffic-split,请为它配置 CA 证书或删除其中的 tls 块。在此之前,对该 traffic-split 的任何修改都会被拒绝。
Console 重新由 dashboard 进程提供服务,形式是一个用 Vite 构建的静态单页应用。对于不是直接使用发行包中原始文件的部署,这会带来三点影响。
一体化镜像中不再包含 Node.js,也不再包含 shell:它的基础镜像换成了 static distroless 镜像,entrypoint 变成 dashboard 二进制本身。离线包中的 docker-compose.yaml 直接启动该二进制,并用 api7-ee-dashboard healthz 做健康检查。如果你把 3.10.6 中自定义的 command 或 healthcheck(即在 dashboard 之外再启动 node /app/server.js 的那一份)原样沿用过来,容器将无法启动。请以新离线包中的 compose 文件为基础,再把你自己的改动叠加上去。由于镜像中没有 shell,docker exec ... sh 进入 dashboard 容器以及基于 shell 的 entrypoint 覆盖都不再可用。
浏览器静态资源从 Next.js 的 /_next/static/ 路径迁移到了 /assets/ 下带内容哈希的文件。任何固定匹配 /_next/static 的反向代理规则、Content-Security-Policy 或 CDN 缓存键都将不再命中,需要改指向 /assets/。
开发者门户前端镜像(api7-ee-developer-portal-fe)现在同样是 distroless 镜像,也不含 shell,因此上述限制同样适用;它原本就以非 root 用户运行,启动行为(包括数据库与门户连通性检查)也保持不变。
新功能
插件
- JWE Decrypt
- 新增的认证插件,用于解密客户端提交的 JSON Web Encryption Token,根据 Token 的 key ID 确定消费者,并把解密出的内容通过可配 置的请求头转发给上游。消费者的密钥为 32 字节,可以直接以明文提供,也可以使用 base64url 编码;Token 必须使用
dir密钥管理算法和A256GCM内容加密算法。Token 缺失、格式非法、被篡改或无法解密的请求都会被拒绝,其中 Token 缺失时的处理方式可以配置。该插件只负责解密 Token,不提供任何签发 Token 的接口。它可以像其他认证插件一样在 Dashboard 中配置。
- 新增的认证插件,用于解密客户端提交的 JSON Web Encryption Token,根据 Token 的 key ID 确定消费者,并把解密出的内容通过可配 置的请求头转发给上游。消费者的密钥为 32 字节,可以直接以明文提供,也可以使用 base64url 编码;Token 必须使用
- Chaitin WAF
- 现在可以在上报请求的同时把响应一并上报给长亭雷池(SafeLine)检测服务,这样响应体中泄露的数据、漏洞利用的输出,或者异常的状态码都能被雷池看到。插件和插件元数据上都提供了三个配置项:
config.log_resp开启响应上报,config.resp_body_size以 KB 为单位限制上报的响应体大小(0表示只上报响应头),config.extra_ignored_content_types在内置忽略列表之外,以逗号分隔追加需要跳过的响应 content type。响应上报默认关闭。上报发生在响应已经返回给客户端之后,且仅供参考:它不会阻断也不会修改响应。
- 现在可以在上报请求的同时把响应一并上报给长亭雷池(SafeLine)检测服务,这样响应体中泄露的数据、漏洞利用的输出,或者异常的状态码都能被雷池看到。插件和插件元数据上都提供了三个配置项:
- AI Proxy Multi
- 实例的健康检查状态现在可以通过数据面 control API 查看。
GET /v1/healthcheck会为每个声明了checks的实例列出一个条目,条目中带有新增的plugin和meta字段(meta.instance给出实例名),同时新增了子资源GET /v1/healthcheck/{src_type}/{src_id}/checkers,以数组形式返回某个资源拥有的全部健康检查器。此前,真实上游是 LLM 实例的路由什么都不会上报,GET /v1/healthcheck/{src_type}/{src_id}也只会返回HTTP 404和no checker for routes[1]。
- 实例的健康检查状态现在可以通过数据面 control API 查看。
控制面
- 现在可以在网关旁边部署诊断 Agent,并从 Dashboard 对运行中的数据面做诊断——采集网关自身 worker 进程的 CPU profile 和内存快照——而无需在网关所在网络上开放任何入站端口。Agent 通过 mTLS 主动向控制面拨号,使用的正是数据面已经在用的端口,Dashboard 再经由这条连接把请求转发过去。API Runtime 下新增了集群级的 Diagnostic Agents 板块:列出各个 Agent 及其状态,为每个在线的 Agent 打开诊断控制台,并为新 Agent 生成可直接运行的 Docker 命令或 Kubernetes 清单,其中已经填好证书、与宿主机共享的 PID 命名空间以及诊断运行所需的各项 capability。每个 Agent 在部署时命名,该名称写入它被签发的证书中,因此列表里展示的是机器标识而不是一串裸 ID。
- 网关实例的配置兼容性报告现在按问题组织,而不是按资源组织。
GET /api/gateway_groups/{gateway_group_id}/instances/{gateway_instance_id}/compatibility_issues为每一个不同的问题返回一个条目——包含机器可读的reason(resource_invalid、plugin_unavailable、plugin_config_invalid、plugin_unknown_fields)、它所涉及的插件和字段,以及携带该问题的资源列表——并按错误优先、其次按受影响资源数量排序。数据面现在以结构化数据上报每个问题,而不是为每个资源渲染一句英文,因此同一个原因不会再在成千上万行里重复出现,未识别字段的告警也不会再被聚合后的错误淹 没。Dashboard 的网关实例页面即以这种分组形式展示该报告。 - 运维人员现在可以忽略某个数据面不识别但会安全跳过的插件字段,让兼容性报告只列出真正需要处理的内容。一条忽略配置指定插件和字段,对所有网关组和实例生效,并覆盖数组中的每一个元素——忽略
nodes[*].weight即覆盖全部元素。忽略配置既可以在 Dashboard 的网关实例页面上维护,也可以通过/api/compatibility_dismiss_rules接口管理,它们有自己的权限控制,每一次变更都会记入审计日志。只有未识别字段的告警可以被忽略:忽略其中一条告警既不会改变数据面对配置的处理方式,也不会把 Incompatible 的实例变成 Compatible。 - 现在可以按域名或路径前缀查找服务。服务列表接口的
search参数除了名称、描述、标签和 ID 之外,还会不区分大小写地匹配服务hosts或path_prefix的任意子串;以空白字符分隔的多个词仍然是 AND 语义。此前,只知道服务域名或路径前缀的用户没有任何办法把它找出来。升级前发布的服务无需重新发布即可按这种方式搜索。
数据面
- stream 代理现在可以把 TLS 会话透传给后端,而不是在网关上终结。在网关配置文件的
apisix.stream_proxy下声明了tls_passthrough: true的 TCP 监听端口,会读取客户端 ClientHello 中的 SNI,据此选择后端,并把加密的会话原样转发过去,TLS 会话因此在后端终结。到达该端口的每一条连接都会被透传;该端口在网关自身的配置中声明——Docker Compose 部署中位于gateway_conf/config.yaml,Kubernetes 上则位于网关 Helm chart 的 values 中。 - 以
101 Switching Protocols应答的请求现在被归类为request_type=websocket,因此 WebSocket 会话会落到各自独立的apisix_http_status、apisix_http_latency和apisix_bandwidth时间序列中,可以用request_type!="websocket"把它们排除在延迟查询之外。普通请求的时间序列保持不变,握手被拒绝的请求仍然是traditional_http。如果你的仪表盘或告警规则在聚合这些指标时没有按request_type过滤,将会看到 WebSocket 流量从原先所在的序列中被分离出去。
缺陷修复
插件
- Basic Auth
- 修复问题:密码中包含冒号的消费者永远无法通过认证。RFC 7617 规定第一个冒号之后的全部内容都是密码,但此前的实现按每一个冒号切分凭据,把密码截断了。
- 修复问题:密码为空的消费者——无论是直接存成空字符串,还是由
$env://或$secret://引用解析出空值——会让任何携带其用户名和空密码的请求通过认证。现在这样的消费者会被拒绝,返回HTTP 401,并且空密码也无法再被配置。升级前需要检查的内容请参见不兼容变更。
- UA Restriction
- 修复问题:携带多个
User-Agent头的请求,在这些 User-Agent 命中denylist时反而被放行,未命中时反而被拒绝——只要请求带有一个以上的该请求头,判定就是反的。因此被拒绝的客户端只要把同一个User-Agent发送两次就能绕过限制。现在这类请求会被正确拒绝,返回HTTP 403。只带一个User-Agent头的请求,以及allowlist分支,从来不受此问题影响。
- 修复问题:携带多个
- Chaitin WAF
- 修复问题:在路由或服务级别的
config中设置任意一个配置项,都会重置该config未设置的其余所有配置项,丢弃插件元数据中配置的值。只设置了read_timeout的路由会静默地把req_body_size、connect_timeout等等都退回到内置默认值。现在插件级别的config会逐字段覆盖元数据,与文档中此前的描述一致。
- 修复问题:在路由或服务级别的
- AI Cache
- 修复问题:在
passthrough协议下,请求体相同但方法、路径或查询字符串不同的请求会共用同一条缓存,因此通配路由上发往/v1/images/generations的请求可能被返回此前发往/v1/chat/completions的请求的缓存响应。该协议的缓存键现在包含客户端的方法、路径和查询字符串。其他协议的缓存键保持不变,因此升级前已缓存的条目仍然有效。
- 修复问题:在
- AI Proxy 和 AI Proxy Multi
- 修复问题:使用 Vertex AI 提供方时,
model中包含/、?或空格的向量嵌入请求会被发往错误的路径,或者干脆失败。名为models/text-embedding-004的模型会在预测 URL 上多出一段路径,而不是用于指定模型;?或空格则会产生HTTP 500,错误日志中记录invalid characters found in path——请求根本没有被发出去。现在模型名会被转义成单个路径段。 - 修复问题:当 LLM 上游在流式响应已经有一部分发送给客户端之后断开连接时,网关仍会尝试把已经提交的
HTTP 200改成500,而响应一旦开始返回,状态码是改不了的。客户端拿到的仍然是被截断的流,但错误日志会被attempt to set status 500 via ngx.exit after sending out the response status 200刷屏;并且 AI Proxy Multi 会把这次失败视为可重试,从而在客户端已经收到部分内容之后,再向第二个实例发出一次会产生费用的请求。现在流就在中断处结束——不会补发协议的结束标记,因此客户端可以通过缺失的[DONE]察觉到内容被截断——出问题的上游连接也会被关闭,而不是放回连接池。
- 修复问题:使用 Vertex AI 提供方时,
- AI AWS Content Moderation 和 AI Aliyun Content Moderation
- 修复问题:被网关自身的
max_response_bytes或max_stream_duration_ms限制截断的流式响应,会被补上一个表示结束的事件,于是客户端会把一段被截断的回答当作模型已经完整作答。现在只有真正正常结束的流才会补发该结束事件。
- 修复问题:被网关自身的
- Traffic Label
- 修复问题:在配置了
ipmatch规则的路由上,编译后的匹配器被存进了插件自身的配置中,因此从第一个匹配的请求开始,该路由就再也无法被序列化为 JSON。数据面 control API 的GET /v1/routes会失败,info日志级别下的路由 dump 为空,匹配的请求还会记录failed to encode: Cannot serialise table: excessively sparse array。
- 修复问题:在配置了
- AWS Lambda、Azure Functions 和 OpenFunction
- 修复问题:不带路径的
function_uri(例如末尾没有斜杠的https://xxx.lambda-url.us-east-1.on.aws)会产生请求目标为空的请求,严格的函数端点会以HTTP 400 Bad Request拒绝它。现在这类请求会被发往/。此外,状态码大于等于400的函数响应现在会以warn级别记录其状态码和响应体;此前错误日志中只有exits with http status code 403,看不出任何原因。
- 修复问题:不带路径的
数据面
- 修复问题:配置了证书校验并提供了自己的 CA 证书的 HTTPS 上游,即便上游证书确实由该 CA 签发,每个请求也都会失败,返回
HTTP 502,错误日志中记录upstream SSL certificate verify error: (20:unable to get local issuer certificate)。原因是对于只提供了 CA 证书、没有同时提供客户端证书的上游,信任库从来没有被真正应用。现在这类上游可以正常建连。 - 修复问题:
grpcs上游完全忽略了它的证书校验配置,因此无论上游证书由哪个 CA 签发都会被接受。这些配置被分发 gRPC 流量的内部跳转丢弃了,而且上游证书本来也是拿错误的名称去校验的。现在grpcs与https一样会真正执行校验并使用所配置的 CA 证书,同时按上游主机名核对证书。启用了校验、但证书无法回溯到所配置的 CA、或者证书的 subject alternative name 未覆盖上游主机名的grpcs上游,此前可以连通,现在会返回HTTP 502;升级前请先检查这类上游。 - 修复问题:两个上游可能共用同一份解析后的 CA 证书信任库,导致某个上游被用另一个上游的 CA 证书去校验。信任库现在以 CA 证书本身作为缓存键。
- 修复问题:网关 worker 在关闭多路复用的上游连接时可能崩溃,因为连接的日志对象所指向的内存已经先被释放。这个问题在实际使用中通过 Dubbo Proxy 插件触发,它使用的正是多路复用的上游连接。
- 修复问题:当
conf/apisix.uid对运行用户不可写时(离线包出厂即是这种形态),网关每次启动都会以 error 级别记录failed to open file[/usr/local/apisix//conf/apisix.uid] for writing。实例 ID 本身读取正确、实例也正常注册,功能并没有出问题,但这些行在排查时看起来像是真的故障。现在只有在确实需要持久化一个 ID 时才会写文件。 - 修复问题:数据面 control API 的
GET /v1/healthcheck在本应返回数组的位置返回了空 JSON 对象——配置了checks但尚未被使用的上游返回"nodes": {},没有任何健康检查在运行时整个结果返回{}。两者现在都返回[]。
控制面
- 修复问题:在 PostgreSQL 上从 3.8.x 直接升级时,数据库迁移刚一完成,控制面就会崩溃,报出
ERROR: cached plan must not change result type和panic: init ETCD custom_plugins for gateway groups failed。原因是某张表在迁移前被读过一次、迁移后又被读了一次,复用了按旧表结构准备好的语句。现在迁移所使用的连接会在迁移结束后被丢弃,那些语句也随之失效。该问题只影响 PostgreSQL,且只在从低于 3.9.2 的版本升级时出现。 - 修复问题:运行「只发数据面的 hotfix 构建」的网关会被按错误的版本判定。上报的版本与控制面版本只在预发布后缀上不同的网关——例如 3.10.7 控制面下的
3.10.7-patch.1——会被显示为 PartiallyCompatible 并带上建议升级的提示;而且只要它的兼容性报告中出现一条 error 级别的条目,就会被判为 Incompatible 并触发「网关实例需要升级」的横幅,而配置完全相同、运行正式版本的网关则保持 Compatible。现在这类构建会按它所基于的正式版本判定,并且两个方向都适用:hotfix 版本的控制面也不会再对运行正式版本的网关做出同样的误判。 - 修复问题:查询网关实例时既没有带上它所属的网关组,也没有对它的运行记录排序,因此重启过的实例会被一条已经不存在的运行记录代为回答,且这种情况最长可以持续七天。兼容性问题接口返回的报告与同一屏上并排展示的摘要相互矛盾,并且永远不会收敛;删除网关实例时,可能会因为一条过期的运行记录而放行离线校验,从而删掉一个仍然在线、仍然返回
HTTP 200的网关;此外,当同一个实例 ID 同时存在于两个网关组时,数据面上报的健康检查状态可能被归到错误的网关组下。 - 修复问题:当 Prometheus 返回给控制面的内容不是 JSON 时(例如带认证的代理返回了一个 HTML 的
401页面),Dashboard 的监控页面和开发者门户的指标接口会以HTTP 500和invalid character '<' looking for beginning of value失败,完全看不出真正的原因。现在这类响应会被报告为HTTP 502,消息中给出上游的状态,例如prometheus returned 401 Unauthorized,响应体的前 256 字节会记入控制面日志而不是返回给客户端。Prometheus 自身返回的 JSON 错误响应仍然原样透传。
控制台(Dashboard)
- 修复问题:分页表格与卡片列表下方的
Results: X–Y of N标签,在每页条数不是默认的 10 时,从第二页开始显示的区间都是错的,因为该区间是按固定的每页条数计算的,而不是按实际使用的每页条数。列表中呈现的数据始终是正确的,出错的只有这个标签。
开发者门户
- 修复问题:对于外部 API 产品,下载 OpenAPI 文档保存下来的文件名始终是
api-1.json或api-1.yaml,而不是根据 API 生成的名称。由网关服务支撑的产品此前已经是正确的。 - 修复问题:在交互式 API 文档查看器的输入框中粘贴内容(包括 Basic Auth 的凭据输入框)无法生效,或者对换行处理有误,导致粘贴进去的凭据在请求发出前就被丢弃或变形。
3.10.6
发布日期:2026-08-25
不兼容变更
控制面
-
自定义插件改为按网关组管理
升级说明自定义插件此前是控制面级资源,一份代码全局共用,因此为预发布环境上传一个新构建会立刻同时生效到该插件绑定的所有网关组。现在它归属于单个网关组,接口、权限以及升级后的现有部署形态都随之变化。
接口从
/api/custom_plugins迁移到/api/gateway_groups/{gateway_group_id}/custom_plugins,旧路径的所有方法都返回HTTP 410,并在消息中给出替代路径。PUT按插件名做「创建或替换」,因此流水线一次调用即可上传,且只写入自己的网关组。请求和响应体中不再有gateway_groups,改为携带gateway_group_id。GET /api/plugins现在必须带gateway_group_id查询参数,因为插件目录已经是按网关组给出的结果。权限随资源一起迁移,从
arn:api7:gateway:gatewaysetting/*变为arn:api7:gateway:gatewaygroup/{gateway_group_id}。gateway:CreateCustomPlugin不再存在——上传是同一个端点上的「创建或替换」,由gateway:UpdateCustomPlugin覆盖——读取自定义插件则需要新增的gateway:GetCustomPlugin权限。此前读取不需要任何权限,任何已登录用户都能读到任意自定义插件的源码;升级后,从未被授予自定义插件权限的角色无法列出或读取它们,需要额外授予gateway:GetCustomPlugin。升级程序会改写已存储的策略:原本在旧资源上授予自定义插件动作的语句保留其余动作,自定义插件相关动作迁移到arn:api7:gateway:gatewaygroup/*上的新语句,效果与条件不变,其中gateway:CreateCustomPlugin被改写,并补上gateway:GetCustomPlugin。被替换的策略文档保存在permission_policy_backup中。同一个升级程序会把每个已有插件展开成它曾部署到的每个网关组各一条记录,因此插件在升级后无需任何操作即可继续工作。升级后有两种情况需要留意:未部署到任何网关组的插件没有归属,会被记录到日志而不迁移,需要手动上传到需要它的网关组;此前路由可以引用一个从未部署到其所在网关组的插件,控制面接受该配置而数据面忽略它,因此插件从未真正运行过,升级后该网关组没有这个插件,下一次写入该路由时会报告插件未知,直到 移除这段失效的插件配置。
最后请注意,在 3.10.6 上上传的插件代码只存在于新表中,因此回滚到更早的版本会使用升级前的旧表中保存的代码。
升级须知
$http_x_forwarded_* 现在记录的是客户端发送的值对于来自不受信任对端的请求,网关一直会覆盖 X-Forwarded-Proto、X-Forwarded-Host 和 X-Forwarded-Port 并清除 Forwarded。这部分工作现在由 NGINX 配置完成,不再由 Lua 执行。上游收到的内容没有变化,插件看到的也没有变化:core.request.header 与 ctx.var.http_x_forwarded_* 返回的仍是覆盖后的值,ctx.var.original_x_forwarded_* 返回的仍是客户端发送的值。
不同的是 NGINX 配置层。在访问日志格式、if 或 map 中引用 $http_x_forwarded_proto、$http_x_forwarded_host、$http_x_forwarded_port 或 $http_forwarded 时,现在读到的是客户端发送的值,而此前读到的是覆盖后的值。因此,用 $http_x_forwarded_host 记录审计日志的格 式会开始记录由客户端控制的值:伪造 X-Forwarded-Host: evil.example.com 的请求在升级前记录的是真实 host,升级后记录的是 evil.example.com。
如需记录覆盖后的值,请改用 $scheme、$var_x_forwarded_host 和 $var_x_forwarded_port。$http_x_forwarded_for 不受影响。客户端发送的值也可以通过新增的 $original_x_forwarded_proto、$original_x_forwarded_host、$original_x_forwarded_port、$original_x_forwarded_for 和 $original_forwarded 这几个 NGINX 变量读取。
除非在插件元数据中设置了 max_pending_entries,所有日志插件背后的批处理器都会把未投递的条目无上限地保留在 worker 内存中,因此日志服务器变慢或不可达时,worker 内存会随请求速率一起增长。该上限现在默认为 8192 条,同时 datadog、lago、loggly、sls-logger 以及 stream 子系统的 syslog 首次暴露该配置项。
日志服务器能正常消费的部署不受影响:待处理量取决于 batch_max_size 而不是请求速率,通常远低于一千条。达到上限后,新条目会被丢弃,并以每秒至多一条日志的频率报告累计丢弃数。如果你记录了大于几 KB 的请求体或响应体,请在插件元数据中调低 max_pending_entries,使待处理量符合你的内存预算;如果调高过 batch_max_size,也应同步调高该值。
OpenID Connect 上可配置的三项校验此前并非在所有情况下都生效,导致本应被拒绝的请求被放行。现在这些配置会被真正执行,此前能通过的流量可能开始收到 HTTP 401 或 403。
required_scopes 此前只作用于通过内省校验的 Token。使用授权码流程的路由(即未设置 bearer_only 的默认形态)从不读取会话被授予的 scope,因此任何完成登录的用户都会被放行。现在 scope 会从 access Token 中读取,无法确定所授予 scope 的会话会被拒绝而不是放行。在授权码流程中依赖 required_scopes 之前,请确认你的身份提供方签发的 access Token 是携带 scope 的 JWT,或者 ID Token 中携带该字段。
claim_validator.audience.match_with_client_id 此前只在 aud 声明存在时才与 client id 比对,因此不带 aud 的 Token 会跳过该校验。现在该选项隐含要求该声明必须存在,不带 aud 的 Token 会收到 HTTP 403。
在 bearer_only 模式下且未配置 valid_issuers 时,受信任的 issuer 来自提供方的 discovery 文档;此前该请求失败时网关只记录一条 warning,并在完全没有 issuer 约束的情况下校验 Token。现在会返回 HTTP 401,并携带 error_description="issuer validation unavailable"。如果不希望请求路径依赖 discovery 端点的可用性,请显式配置 valid_issuers。
AI Proxy Multi 此前接受两个 name 相同的 instance,这会让请求实际路由到哪个 instance 变得不确定。此类配置现在在写入时就以 HTTP 400 拒绝。
已经存储的配置仍可继续工作,但升级后会在数据面的配置兼容性报告中以 error 级别出现。请重命名重复的 instance 使每个名字唯一,配置被重新写入后该报告项即消失。
LDAP Auth 此前通过普通字符串拼接重建一个可分辨名称(DN)来查找消费者,而只要用户名中含有在 DN 中具有结构含义的字符(, + = < > ; " \),这个 DN 就与实际用于绑定的 DN 不同。现在改为使用绑定时生成的转义 DN。
目录中所有用户名都不含上述字符的部署不受影响。如果某个消费者的 user_dn 是按旧行为以未转义形式写入的,请改写为 RFC 4514 转义形式(例如 cn=comma\,user,ou=users,dc=example,dc=org),否则该消费者在升级后不再匹配。
为修复下文「缺陷修复」中描述的变体键碰撞问题,Proxy Cache 在 memory 策略下的存储键布局发生了变化,缓存版本号也随之提升。因此旧版本写入的条目在新布局下不可达:每个键的第一次请求为 MISS 并重新填充缓存,而对只有升级前条目的 URL 执行 PURGE 会返回 HTTP 404。旧条目会一直留在共享内存中,直到各自的 TTL 到期。使用默认 disk 策略的部署不受影响。
新功能
插件
- GraphQL Limit Count
- 新增按查询成本限流的能力,使一个 GraphQL 请求按其请求的工作量消耗配额,而不是一律计为一次请求。
cost_strategy选择成本的计算方式——depth按选择集的嵌套深度计算,complexity按查询解析的节点数计算,node_quantifier按参数要求每个字段返回的对象数量计算——score_factor对结果进行缩放。设置max_cost后,超过该成本的查询在到达上游之前即以HTTP 403拒绝,计算出的成本通过X-Graphql-Query-Cost响应头返回。当服务上配置了成本装饰时,需要内省上游 schema 才能与之匹配,该内省按服务执行一次,端点由introspection_endpoint指定,introspection_headers携带该端点所需的凭据。启用resolve_variables后,通过 GraphQL 变量传入的参数会参与成本计算,而不是被当作未提供。
- 新增按查询成本限流的能力,使一个 GraphQL 请求按其请求的工作量消耗配额,而不是一律计为一次请求。
- Prometheus
- 新增三个四层流量指标,与原本就已导出的
apisix_stream_connection_total计数器并列: 按终止状态、监听地址和上游节点统计已结束会话的apisix_stream_status,按监听地址反映当前 TCP 连接与 UDP 会话数的apisix_stream_active_connections,以及按监听地址、方向和连接侧统计代理字节数的apisix_stream_bandwidth。采集这些指标需要在 stream 路由上启用该插件。插件元数据的disabled_labels现在支持stream_status键,用于关闭apisix_stream_status上的标签,与status对 HTTP 计数器的作用相同。
- 新增三个四层流量指标,与原本就已导出的
- AI Proxy Multi
- 新增
fallback_http_statuses,用于列出哪些上游 HTTP 状态码会让网关把请求重试到下一个 instance。此前只有在完全无法连接某个 instance 时才会回退,因此提供方因密钥过期返回401、或因该账号配额耗尽返回429时,这些响应会直接返回给客户端,而不会转由其他 instance 重试。
- 新增
- LDAP Auth 与 LDAP Auth Advanced
- 两个插件都新增
hide_credentials,在客户端通过认证后移除Authorization请求头,使目录凭据不会被转发到上游。默认值为false,与此前行为一致。
- 两个插件都新增
控制面
- 自定义插件现在归属于单个网关组而不是整个部署,因此同一个插件名可以在预发布和生产环境运行不同的代码,向一个环境上传也不会影响其他环境。接口、权限与迁移细节参见「不兼容变更」。
- GraphQL 查询成本现在可以通过服务上新增的
graphql_cost_decorations子资源按服务调整。一条装饰指定一个字段路径(如Query.products或Product)并调整该字段对成本的贡献:既可以是固定的add_value,也可以按mul_arguments中列出的参数值对其子节点做乘法——例如返回first: 10个对象的字段按十倍计价。装饰会针对其所属服务做校验,同一个字段路径只能被装饰一次,且改动无需触碰承载该插件的路由即可下发到数据面。 - 路由现在可以匹配
PURGE方法,Proxy Cache 和 GraphQL Proxy Cache 正是用它来失效缓存条目的。网关一直接受该方法,只有控制台自身的 schema 拒绝它,因此此前无法通过接口或控制台创建用于缓存失效的路由。 - 上游与路由的超时现在接受小数秒,可以配置
0.5,而此前接口要求整数。数据面一直支持亚秒级超时。最小值为0.001,因为低于一毫秒的部分会被截断。
数据面
- 请求携带的
X-Forwarded-*请求头改由 NGINX 配置消毒,不再由 Lua 在每个请求上处理。插件看到的值与此前一致,而客户端发送的原始值——在 Lua 中一直可以通过ctx.var.original_x_forwarded_*读取——现在也成为 NGINX 变量,可以写进日志格式 。唯一发生变化的记录位置参见「升级须知」。
控制台(Dashboard)
- 新增繁体中文(台湾)与越南语。中文的语言标签现在明确区分是哪一种中文——
zh-Hans-CN与zh-Hant-TW——因此缺失的繁体文案会明显地回退到英文,而不是静默显示简体文案。此前已选择中文的用户,语言设置保持不变。 - License 页面现在把部署 ID(Deployment ID)作为许可证表格的第一行展示,并带复制按钮。部署 ID 是申请签发或续期许可证时需要提供给 API7 的信息,此前只出现在「更新 License」对话框中,而该对话框受更新许可证权限限制,没有该权限的用户根本无法读到它。即使尚未激活许可证,该行也会显示。
开发者门户
- 门户前端已在 TanStack Start 上重建,取代原有的 Next.js 应用。部署方式没有变化——同一个镜像、同一个端口、同一份
config.yaml——因此升级无需修改任何配置。 - 尚未被接受的组织邀请现在可以在成员页面重新发送,而不必先撤销再重新签发。
- 当只配置了一个身份提供商时,登录页会自动选中它,而不是让开发者从只有一项的列表中选择。
- 顶栏中的组织头像与个人头像现在有明显区分,便于确认当前处于哪个组织的上下文中。
- 组织标识字段的名称从 “URL” 改为 “Slug”,与该值的实际含义一致。
缺陷修复
插件
- GraphQL Limit Count
- 修复问题:当 GraphQL 文档中的片段相互展开时,每次被引用都会重新展开一次,因此很小的请求体也可能消耗不受限的 CPU。一个含 34 层链式片段的 1.4 KB 文档可以让 worker 满载运行超过 45 秒,期间网关在所有路由上都不返回任何响应,必须重启才能恢复。现在每个片段只计算一次,片段展开形成环的文档会以
HTTP 400拒绝。
- 修复问题:当 GraphQL 文档中的片段相互展开时,每次被引用都会重新展开一次,因此很小的请求体也可能消耗不受限的 CPU。一个含 34 层链式片段的 1.4 KB 文档可以让 worker 满载运行超过 45 秒,期间网关在所有路由上都不返回任何响应,必须重启才能恢复。现在每个片段只计算一次,片段展开形成环的文档会以
- AI Proxy
- 修复问题:当流式上游返回
HTTP 200和Content-Type: text/event-stream后不写入任何内容就结束响应时,请求既没有被应答也没有被终止,客户端因此完全收不到 HTTP 响应,访问日志记录为长度为零的500。现在返回HTTP 502。
- 修复问题:当流式上游返回
- AI Proxy Multi
- 修复问题:请求重试到下一个 instance 时,使用的是上一次尝试已经改写过的请求体,因此上一个 instance 的
options(例如temperature或max_tokens)会泄漏到发往回退 instance 的请求中,模型名也可能被覆盖。现在每次尝试 都从客户端自己的请求体开始构建。
- 修复问题:请求重试到下一个 instance 时,使用的是上一次尝试已经改写过的请求体,因此上一个 instance 的
- Redirect
- 修复问题:启用
http_to_https时,X-Forwarded-Proto请求头以大小写敏感的方式比较,因此发送HTTPS的客户端或负载均衡器会被重定向到它已经访问到的 HTTPS 地址,形成重定向环。现在改为大小写不敏感比较。
- 修复问题:启用
- Data Mask
- 修复问题:对于由网关自身应答而不是转发到上游的请求——例如被认证插件、限流或 Fault Injection 拒绝的请求——请求头脱敏不生效。随后运行的日志插件读取的是未经修改的请求,因此本应被脱敏的凭据以明文形式发送到了日志接收端。现在脱敏在所有路径上都生效。
- 修复问题:从 JSON 数组中删除一个元素后会留下空洞而不是压实数组,导致被删元素之后的元素在记录的请求体中丢失:对
["a","b","c"]脱敏$.items[1]记录出的是["a"]而不是["a","c"]。
- Proxy Cache
- 修复问题:在
memory策略下,Vary变体的存储键是缓存键加上变体签名,而缓存键由请求 URI 推导得出。因此一个把他人变体签名构造进自身 URI 的请求会得到相同的存储键,于是读到了该请求缓存的响应,并且它自己的响应会被写入下一个请求查找该变体的位置。现在存储键的推导方式保证任何构造出的请求都无法重现另一个请求的键。 升级前已缓存条目的影响参见「升级须知」。
- 修复问题:在
- OpenID Connect
- 修复问题:身份提供方带
error=temporarily_unavailable回跳时(规范将其定义为临时性状况),网关返回HTTP 500。现在会从原始 URL 重新发起认证流程,同一会话最多重试三次,而access_denied等其他错误码仍按最终结果处理。 - 修复问题:
required_scopes、claim_validator.audience.match_with_client_id以及 issuer 校验并非在所有情况下都生效,导致本应被配置拒绝的请求被放行。参见「升级须知」。
- 修复问题:身份提供方带
- LDAP Auth
- 修复问题:查找消费者时使用的是字符串拼接重建的可分辨名称,而不是插件实际用于绑定的转义 DN,因此名称中含 DN 元字符的目录条目虽然认证成功,却匹配不到消费者,或匹配到属于另一个条目的消费者。参见「升级须知」。
- HMAC Auth
- 修复问题:启用
hide_credentials时,Authorization请求头虽然从发往上游的请求中移除了,却仍留在缓存的请求头中,因此同一路由上排在 HMAC Auth 之后的插件仍能读到该签名凭据。
- 修复问题:启用
- AWS Lambda
- 修复问题:以
Transfer-Encoding: chunked发送的请求体在转发给函数时未重新分帧,导致调用失败,客户端收到HTTP 503,错误日志中出现failed to process aws-lambda, err: closed。现在转发时会携带Content-Length。共用该代码路径的其他 serverless 上游插件同样适用。
- 修复问题:以
数据面
- 修复问题:解析作为 CNAME 的上游主机时,只有当应答的最后一条记录恰好是所请求的类型时,解析结果才会被折叠到被查询的名字上。解析器附加 EDNS(0) OPT 记录、或应答段未按链的顺序返回,都会使这一判断失效,于是解析到的记录被记在规范名而不是被查询的名字下——并且一条属于无关名字的同类型记录可能被改记到被查询的名字上并缓存。现在会沿链走到它最终指向的名字,只折叠该名字拥有的记录。
控制面
- 修复问题:任何已登录用户都能列出某个服务的上游(包括节点地址),因为列出上游的端点没有任何权限校验,而同一份数据的其他视图都按权限过滤。现在列出服务的上游需要该服务的查看权限。
- 修复问题:更新 CA 证书或客户端证书后,引用它的上游只有在是服务的默认上游时才会重新下发,因此非默认上游会一直使用旧证书,直到被手动编辑一次。
- 修复问题:为同一个 SNI 同时配置
cert/key和certs/keys的 SSL 配置(即 RSA 与 ECDSA 证书并存的常见形态)会被以input matches more than one oneOf schemas拒绝。现在两者可以一起使用,数据面会按客户端偏好协商相应的 证书。 - 修复问题:使用非对称算法的
jwt-auth消费者凭据在写入配置存储时会带上一个用户从未配置过的占位private_key字段,数据面将其报告为无法识别的字段,且该字段以明文存储。现在不再添加该字段。升级前写入的凭据会保留该字段,直到下一次被保存。
控制台(Dashboard)
- 修复问题:在同一个页面会话中重复打开 YAML 模式的插件编辑器,会使补全列表中的每个字段按打开次数重复,打开五次后每个字段出现五次。现在编辑器的 YAML 支持在每个页面只配置一次。
开发者门户
- 修复问题:访问不存在的组织、或开发者不属于的组织时,只弹出一个错误提示,而没有说明发生了什么的页面。
- 修复问题:邀请链接和落地页在开发者接受邀请后,可能把已登录的开发者跳转到错误的位置。
- 修复问题:文档中的 “Copy page” 按钮换行到了第二行,而不是与页面标题的第一行对齐。
3.10.5
发布日期:2026-08-11
不兼容变更
插件
-
升级说明
该插件现在会校验日志服务器的 TLS 证书。旧版本在完成 TLS 握手时完全不校验证书,因此日志服务器出示自签名证书、私有 CA 签发的证书或已过期的证书都会被静默接受,而携带所配置访问密钥的日志记录仍会发往该服务器。
校验行为由新增的
ssl_verify选项控制,默认值为true。升级后,若网关无法校验日志服务器的证书,批处理器会丢弃这批日志,并在错误日志中记录failed to perform TLS handshake to TCP server。如果你的日志服务器出示的证书并非由公共可信 CA 签发,请在升级前把签发该证书的 CA 加入数据面的可信证书库,或在插件上把ssl_verify设为false以保持旧行为。
升级须知
headers 字段落盘加密在启用数据面数据加密(apisix.data_encryption.enable)时,控制面现在会对 Loki Logger 的 headers 字段做落盘加密。由于 API7 EE 的升级顺序是先控制面、后数据面,在升级窗口内 3.10.5 的控制面会加密该字段,而仍为 3.10.4 的数据面无法解密,可能导致该插件在数据面升级完成前无法正常工作。
如果你使用了 Loki Logger 的 headers,请在控制面升级后尽快把数据面也升级到 3.10.5,并在两侧都升级完成前避免编辑该插件。
控制台会话 Cookie 的签名密钥此前是编译期常量,所有部 署完全相同。现在改为首次启动时生成的 32 字节随机密钥,并按部署持久化保存,因此会话 Cookie 不再可能用一个各处相同的值签发。
升级前签发的会话使用的是旧的常量密钥,升级后不再被接受。控制面升级完成后,所有已登录用户都需要重新登录一次。升级前无需做任何准备,也不需要修改配置。
radixtree_host_uri 路由器Docker Compose 部署包现在会把 apisix.router.http 设为 radixtree_host_uri,与 Helm Chart 一直使用的默认值保持一致。此前该部署包不设置这一项,回落到 radixtree_uri,因此同一份配置在不同部署形态下的路由匹配结果可能不同。
仅依赖普通 host 与路径匹配的配置不受影响。差异出现在「指定了 host 的路由」与「未指定 host 的路由」共享重叠路径时:radixtree_host_uri 会先查按 host 划分的子路由器,只有都未命中时才回落到未指定 host 的路由;而 radixtree_uri 把所有路由放在同一棵树中,按路径特异性与 priority 排序。如需保留旧的匹配引擎,可在 gateway_conf/config.yaml 中把 apisix.router.http 设为 radixtree_uri。
控制台现在在浏览器端应用界面语言,并用 Cookie 记住所选语言,因此 URL 不再带 /zh 前缀。升级后,含 /zh 的书签和已保存的链接会返回 HTTP 404,去掉该前缀后的同一路径即可访问对应页面。可选语言以及语言切换器本身没有变化。
新功能
插件
- LDAP Auth Advanced
- 新增该插件,用于对接 LDAP 目录完成客户端认证,并把认证结果映射到消费者。插件采用「先检索、后绑定」的方式解析用户:在
base_dn下按attribute=username检索,再以检索到的条目执行绑定,因此无需把目录结构写进网关配置。凭据从Authorization请求头读取,支持ldap和basic两种方案(header_type);可通过 LDAPS 或 StartTLS 连接目录,且默认开启证书校验;连接在请求之间复用。消费者通过其凭据上记录的user_dn匹配,因此消费者级插件、限流和用量统计对 LDAP 认证的流量与其它身份一视同仁。
- 新增该插件,用于对接 LDAP 目录完成客户端认证,并把认证结果映射到消费者。插件采用「先检索、后绑定」的方式解析用户:在
- OpenID Connect
- 新增对推送式授权请求(PAR,RFC 9126)的支持。设置
par.enabled后,网关会通过后通道把完整的授权请求发送到身份提供方的 PAR 端点,浏览器重定向中只携带request_uri,授权参数因此不再经过用户代理,也无法在那里被篡改。端点及其客户端认证方式通过par.endpoint与par.endpoint_auth_method配置。 - 新增对 DPoP 发送方约束 Token(RFC 9449)的支持。设置
dpop.enabled后,网关会用dpop.private_key为 Token 请求签发 DPoP 证明,并声明与之匹配的dpop.public_jwk,使签发的 Token 绑定到该密钥,Token 即使被窃取也无法从其它客户端重放。同时启用 PAR 时,密钥指纹还会按规范要求以dpop_jkt随推送请求一并发送。
- 新增对推送式授权请求(PAR,RFC 9126)的支持。设置
- AI AWS Content Moderation
- 新增
check_response,在审查请求之外同时审查 LLM 的回复。非流式回复在返回客户端之前完成审查;流式回复的处理方式由stream_check_mode决定:默认值final_packet对拼装完成的响应审查一次,并在最后一个分片上标注风险等级;取值realtime时,在响应转发过程中按最多stream_check_cache_size个字符分批审查,一旦某批命中就把流的剩余部分替换掉,因此中途才出现有害内容的流会被截断,而不是完整送达。被拦截的回复以该服务商自身的响应格式返回,并使用配置的deny_code与deny_message。 - 新 增
request_check_roles与request_check_mode,用于选择审查哪些消息角色,以及只审查最后一条消息还是所选角色的全部消息,与 AI Aliyun Content Moderation 中已有的选项保持一致。
- 新增
- AI Proxy Multi
- 新增
semantic负载均衡算法:不再按权重或哈希选择实例,而是把请求路由到examples与当前提示词语义最接近的实例。嵌入向量服务在semantic_opts.embeddings下配置,全局或按实例设置的threshold决定匹配需要多接近,匹配度均不达标的请求转发到semantic_opts.fallback。若嵌入服务不可达,请求同样转发到备用实例而不是直接失败。开启semantic_opts.debugging后,各实例的得分与最终选中的实例会通过响应头返回。
- 新增
控制面
- 自定义插件现在可以以完整包的形式上传,包内包含入口文件及其依赖文件,不再限于单个 Lua 文件。压缩包的顶层是
$NAME.lua,依赖模块放在$NAME/目录下,另有metadata.json;控制台会读取其中的元数据自动填充插件的分类、描述、文档链接和作者。整个包作为一个整体下发到数据面,因此不会出现插件只发布了部分文件的情况;更新时所有文件一并替换,且无需重启网关。 - 数据面 CPU 核数的许可用量现在可以按生产与非生产环境分开计量。每个网关组带有
environment属性,取 值为production(默认)或non_production;许可证中相应地包含max_dp_cores与max_non_production_dp_cores。两份额度各自独立地运行用量、宽限与限制状态机,超出其中一份不会限制另一份所管辖的写操作。无法归属到已知网关组的用量计入生产额度。已有网关组按生产环境处理,本次改动之前签发的许可证不包含非生产额度,因此在把某个网关组标记为non_production之前行为不变——而一旦标记,该组就需要一张授予非生产核数的许可证。 - Stream 服务的上游现在支持
tls协议,网关会终止客户端的明文 TCP 连接,并与后端建立 TLS 会话。此前控制面只接受tcp和udp,尽管数据面一直支持四层上游使用tls。 - Docker Compose 部署包新增
portal.sh,用于在已运行的部署上启动开发者门户。该脚本会创建门户实例及其 Token、写入前端配置与数据库,并以 Compose profile 的方式启动前端,因此试用门户不再需要按手册逐步手工操作。执行portal.sh stop后再start,开发者账号与会话都会保留。 - API7 Gateway Admin API 参考文档中,每个接口现在只出现在一个位置。原先内容过载的 Service 分组已拆分为 Service、Route、Stream Route、Upstream 和 OpenAPI,同一个接口不会再重复出现在多个导航分组下。
数据面
- 全局规则筛选出的插件集现在每个请求只计算 一次并跨阶段复用,而不是在每个阶段中重复计算。在通过全局规则启用 Prometheus 插件的部署上,单个 Worker 实测吞吐提升 12%。
控制台(Dashboard)
- 语言切换器不再显示与语言并不对应的国旗图标,并会标出当前生效的语言。
开发者门户
- 新增
emailAndPassword.revokeSessionsOnPasswordReset,用于控制开发者重置密码时是否吊销其它会话。默认值为true,与此前行为一致。
缺陷修复
插件
- AI Aliyun Content Moderation
- 修复问题:当
request_check_roles选中system时,放在developer角色消息中的内容不会被送去审查。developer是 OpenAI 在较新模型和 Responses API 中用来替代system的角色,因此客户端可 以把指令放在该角色下,绕过审查直达 LLM。现在两个角色的内容会一并提取,已有的system条目同时覆盖这两个角色。 - 修复问题:在
realtime流式审查模式下使用协议转换器时(例如 Anthropic 客户端对接 OpenAI 兼容上游),同一段回复文本会按转换后的分片数重复提交给审查服务,而不是按上游分片提交一次。审查结果本身不受影响,但stream_check_cache_size会远早于配置值被触发,审查调用次数也随转换器的输出规模放大,带来额外的延迟和费用。
- 修复问题:当
- AI AWS Content Moderation
- 修复问题:超出 Amazon Comprehend 单段与单次请求限制的内容会被拒绝或静默截断,导致较长的提示词和回复只有一部分被审查。现在内容会按文档规定的上限切分,并分成所需数量的批次提交;同一请求内的多次调用复用同一个 HTTP 客户端,而不是每次都新建连接。
- Loki Logger
- 修复问题:
headers字段通常携带 Loki 端点的认证 Token,此前以明文存储。在启用数据面数据加密时,该字段现在会落盘加密(参见升级须知)。
- 修复问题:
- Limit Conn
- 修复问题:当该插件配置在服务上时,该服务下的每个路由各自独立统计并发连接数,实际生效的上限因此被路由数量放大。现在计数键按插件所配置的资源确定,服务级别的限制会在其所有路由之间共享。
- Prometheus
- 修复问题:承载指标的共享内存字典中已过期的条目不会被 回收,用量只增不减,最终一直处于写满状态,此后新的指标序列会被丢弃。现在过期条目会被正常回收。
- OpenID Connect
- 修复问题:在
bearer_only模式下,首尾带空白字符的Authorization请求头会被拒绝,因为空白字符被一并带进了提取出的 Token。现在会先去除首尾空白再读取 Token。
- 修复问题:在
数据面
- 修复问题:当网关使用
radixtree_host_uri路由器(Kubernetes 部署下的默认值)时,服务上配置的hosts与请求Host头之间是大小写敏感匹配。由于请求头在匹配前会被归一为小写,hosts中只要含有大写字母,该服务就永远无法匹配,其下所有路由对任何请求都返回HTTP 404。现在服务的 hosts 会被归一化,与路由 hosts 一贯的行为保持一致。本次发布之前,Docker Compose 部署因使用radixtree_uri路由器而不受影响(参见升级须知)。 - 修复问题:重写后的上游 URI 中的控制字符——例如从百分号编码的请求路径中带入的回车换行——会被原样写入上游请求行,客户端因此可以截断请求行,并向网关发往上游的请求中注入任意请求头。现在控制字符会被百分号编码。
- 修复问题:TCP/UDP TLS 监听所用的证书与私钥若以
$ENV://或$secret://引用形式存储,则不会被解析,TLS 握手因此以 PEM 解析错误失败。现在 TCP/UDP 子系统会像 HTTP 监听那样解析这些引用。 - 修复问题:配置存储的监视在无事件超时时,数据面会把修订版本推进到该时间点,仿佛已消费完所有事件,因此在超时前后到达的配置变更可能被跳过。现在超时不再推进修订版本,监视断开后的恢复重载开销也更低。
- 修复问题:全量配置重载中若某一项数据面无法接受,该项此前可用的值会被丢弃而不是保留,因此单个非法资源可能在重连后让本已正常的配置失效。现在会保留此前的值。
控制面
- 修复问题:列表接口的
order_by与direction参数未经校验就被拼接进生成的 SQL,因此非列名的取值会改变查询而不是被拒绝。现在这两个参数在所有使用处都会被校验;此前未声明这两个参数的六个列表接口——四个 AI Gateway 列表、证书 SNI 用量、告警联系人用量——现在会明确列出可用于排序的列,其它取值一律返回HTTP 400。按合法列排序的行为不变;向这些接口传入不受支持的取值时,现在会收到错误响应,而不是一个排序不确定的结果。 - 修复问题:上传自定义插件时用于读取其 Schema 的 Lua 解析器会在完整标准库可用的环境下求值上传的文件,因此一个文件可以在读取 Schema 的过程中在控制面主机上执行命令。现在解析器只加载 Schema 定义所需的库,且超过三秒预算的文件会被拒绝。普通插件的 Schema 是声明式表,不受影响。
- 修复问题:为网关组生成的 Helm 安装脚本会把数据面的私钥、证书和 CA 以运维默认的文件权限写入
/tmp下的固定路径 ,并且从不删除。现在脚本使用umask 077创建临时文件,文件名随机,并在退出时删除。 - 修复问题:数据面上报的指标此前按数据载荷中携带的
gateway_group_id标签存储,而不是按建立连接时认证到的凭据,因此一个数据面可以把指标序列写进其它网关组。现在该标签一律取自认证得到的身份。 - 修复问题:数据面读取配置所用的 etcd 兼容端点会转发调用方网关组命名空间之外的键,因此一个数据面可以读取、写入乃至删除其它网关组的配置。现在命名空间之外的键会被拒绝。
- 修复问题:数据面上报的注册中心健康检查与探测结果此前仅按注册中心 ID 应用,因此一个数据面可以覆盖属于其它网关组的注册中心的服务发现结果与连接状态。现在这类更新会限定在上报方所属的网关组内。
- 修复问题:
security.ssrf_protection设置对开发者门户进程不生效,因此启用后审批 webhook 与动态客户端注册仍可访问内网地址。开发者门户现在与控制面应用相同的策略。 - 修复问题:开发者门户的 API 用量接口按门户提供的开发者标识过滤统计数据,而该标识仅在单个门户内唯一,因此一个开发者可以看到另一个门户中同名开发者的 API 产品名称与小时级调用量。现在统计数据被限定在调用方自己拥有的应用范围内。
- 修复问题:导入许可证后,控制台可能在缓存条目的整个生命周期内对所有请求返回
license clock signature is invalid,因为许可证与为其签名的时钟此前分别缓存、可以各自独立刷新。现在两者作为一个整体读取和缓存,并会相互校验,导入时也在同一个事务中写入。 - 修复问题:导入一张提高了许可核数额度的 许可证之后,此前已经拦截过写操作的控制面副本仍会继续拒绝写操作,最长持续到许可证缓存过期。现在许可限制在每次请求时都按当前状态重新判定,不再缓存。
- 修复问题:在 SQL Server 上,中途被中断的查询与空结果无法区分,因此删除操作可能报告成功却没有真正记录删除,查询也可能对确实存在的配置返回空结果。现在被中断的查询会正确报错。另外,压缩事务所设置的隔离级别会残留在归还连接池的连接上,导致后续查询以可串行化级别执行,可能长时间排队在写操作之后直至超时,或与并发写操作死锁。现在压缩在独占连接上执行,并在归还连接池前复位其隔离级别。PostgreSQL 与 MySQL 部署不受这些问题影响。
控制台(Dashboard)
- 修复问题:监控页面在所选时间窗口内没有流量时,或后端上报的失败数超过请求数时,会把成功率显示为
0%,看上去像是所有请求都失败了。这两种情况现在都显示为长破折号,因为此时并不存在可供展示的成功率。请求数与失败数本身的展示不变。 - 修复问题:离线网关实例的状态徽标在两种语言下都显示为断裂的文案,例如
Offline - In 6 DaysUntil Deletion。 - 修复问题:调试会话的采样规则预设使用了
http_uri、http_method和http_status。在数据面上,带http_前缀的变量解析为请求头,因此这些预设从不匹配,由预设创建的调试会话什么也捕获不到。预设现在改用uri、method和status。 - 修复问题:产品内的多个帮助链接指向已冻结的文档归档,而不是当前的文档集。
开发者门户
- 修复问题:发往门户后端代理的请求中若含有百分号编码的路径分隔符,实际发往上游的路径可能与代理执行访问控制检查时所用的路径不一致。现在路径分段会在解码之后再校验,含有路径分隔符、查询或片段定界符以及控制字符的分段会被拒绝。
- 修复问题:在强制启用双因素认证时,为放行登录流程而设置的豁免覆盖了整个
/api前缀,范围大于实际需要豁免的端点。现在豁免范围收窄到认证相关端点;此外,在执行该强制策略过程中若加载会话失败,请求会被拦截,而不是处于行为不确定的状态。 - 修复问题:双因素认证的密码对话框把尚未加载完成的账号列表当作「该账号没有密码」处理,因此启用双因素认证时可能跳过密码校验,强制启用流程也可能停在一个笼统的错误提示上无法继续。对话框现在会等待账号列表加载完成,并在需要时提示输入密码。
- 修复问题:启用双因素认证后会话缓存没有刷新,界面在页面重新加载之前仍显示此前的状态。
- 修复问题:缺少用于添加双因素认证锁定相关列的数据库迁移,因此从旧版本升级上来的部署在记录一次锁定时可能失败。
- 修复问题:使用已存在账号的邮箱注册时,没有提示该邮箱已被占用。
- 修复问题:门户发往控制面的请 求没有设置超时时间,控制面无响应时可能导致门户请求长时间挂起。
3.10.4
发布日期:2026-07-27
升级须知
ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、阿里云日志服务(SLS) 和 Syslog 插件的 max_req_body_bytes 与 max_resp_body_bytes 现在会被校验为不小于 1 的整数。旧版本接受的值——0、负数,以及带引号的数字(如 "1024")——现在会被拒绝并返回 HTTP 400。
升级后,已有的、带这类值的路由会在网关组的兼容性报告中被列为错误,并且不会下发到数据面;其他路由不受影响。升级前请检查这些插件的配置中是否存在设置为 0、负数或带引号数字的 max_req_body_bytes / max_resp_body_bytes,将其改为正整数,或删除该字段以使用默认值 524288。
Prometheus 插件元数据现在会拒绝那些会移除指标赖以成立的标签的 disabled_labels 配置——例如 latency 的 type,或 status 的 code。旧版本接受这类配置,导致本应区分的多组测量值被合并成同一条指标序列。
如果你的 Prometheus 插件元数据禁用了这类标签,升级后对它的任何更新都会被拒绝并返回 HTTP 400。请在升级前把这些结构性条目从 disabled_labels 中移除。route、service、consumer 等非结构性标签仍然可以禁用。
新功能
插件
- OpenID Connect
- 新增
set_raw_id_token_header。启用后,身份提供商签发的原始 ID Token 会通过X-Raw-ID-Token请求头转发给上游服务,使上游可以自行校验 Token 签名,而不必信任网关解码后的声明。
- 新增
- Proxy Rewrite
headers.set和headers.add现在支持为同一个请求头名称配置数组值,转发到上游时会生成多条独立的请求头,而不是用逗号拼接成一条。这对只读取首个同名请求头、或对重复请求头与逗号拼接值解析方式不同的上游服务尤为重要。
- Kafka Logger
- 新增
tls,支持通过 TLS 连接 Kafka broker,并由tls.verify控制是否校验 broker 证书。此前插件只能以明文连接,因此监听 TLS 端口的 broker 完全收不到日志。
- 新增
- 限流与缓存插件
- 为 Limit Conn、Limit Req 和 AI Cache 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
redis_keepalive_timeout和redis_keepalive_pool),方便运营者调整空闲超时时间和连接池大小。
- 为 Limit Conn、Limit Req 和 AI Cache 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
- 需要缓冲请求/响应体的插件
- 新增
max_req_body_size和max_resp_body_size,用于限制插件读入内存的请求体或响应体大小,默认值为 67108864 字节(64 MiB)。超过上限的请求体会被拒绝,响应体则会在上限处截断——Proxy Cache 例外,超限的响应会直接透传而不被缓存——从而避免单个超大 body 耗尽 worker 内存。该能力可用于 AI Proxy、AI Proxy Multi、AI Request Rewrite、AI prompt 系列插件、Request Validation、OAS Validator、Body Transformer、Response Rewrite、Proxy Cache、gRPC Transcode、SOAP 等会缓冲 body 的插件。
- 新增
- Logger 插件
- 为其余 logger 插件的 schema 补充
max_req_body_bytes和max_resp_body_bytes——ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、阿里云日志服务(SLS) 和 Syslog——使这两个上限在配置时被校验并在控制台中展示(参见「升级须知」)。
- 为其余 logger 插件的 schema 补充
数据面
- 新增
nginx_config.stream.real_ip_from,用于列出在 stream(TCP/UDP)端口上被信任、可以发送 PROXY protocol 头的地址。当连接来自受信任地址时,客户端地址取自 PROXY protocol 头而非直连对端,使 stream 日志和基于地址的插件看到的是真实客户端,而不是网关前面的负载均衡器。该配置默认为空,且仅在启用了 PROXY protocol 的端口上生效。 - 升级健康检查引擎。检查目标现在以增量方式协调,不再整体销毁重建,因此上游扩缩容时不会出现「没有任何节点被检查」的窗口,未变更节点已累计的健康状态和失败计数也会被保留而不是被重置。
- 调试响应头
Apisix-Plugins现在按执行顺序列出实际执行过的插件,并标注各自执行的阶段(例如limit-count#access、response-rewrite#header_filter),而不是无序地列出已配置的插件。
控制面
/api/fe-config端点改由控制面二进制提供,并由console.*配置项驱动,因此控制台的 hybrid 模式、浏览器错误上报(Sentry)和侧边栏自定义外部链接分组都可以通过控制面配置或 Helm chart 配置。缺少名称或没有绝对http/httpsURL 的菜单项会被丢弃,不会下发给控制台。- 服务冲突检测现在会计入路由的 methods。同一 host 和 path 下方法集合互不相交的路由(例如
GET /foo和POST /foo)不再被判为冲突;方法范围完全相同判为 duplicate,部分重叠判为 overlapping。未配置methods的路由仍然匹配所有方法。 - 新增可选的出站 SSRF 防护。开启
security.ssrf_protection.enable后,控制面会拒绝连接环回地址、私网地址、链路本地地址和运营商级 NAT 地址——包括解析后落到这些网段的主机名——从而防止服务注册中心、SMTP 设置等功能被用来探测内网服务或云元数据端点。
控制台(Dashboard)
- 控制面版本号现在展示在顶部栏的组织菜单旁边,并支持一键复制,不再需要展开组织下拉菜单才能查看。
- 由 ADC 同步的资源(带
managed-by=adc标签)现在会在详情页展示 Managed by ADC 标记和提示横幅,对其执行编辑、删除、新建操作时会提示:下一次 ADC 同步会覆盖手工修改并移除手工添加的子资源。归属于被 ADC 管理的 Service 或 Consumer 的子资源,即使自身没有该标签也会给出提示。这些提示仅作告知,不会阻断操作。 - 服务与路由的冲突提示弹窗新增 Methods 列,便于判断两条路由在哪些方法上发生冲突。未配置
methods的路由显示为 All。