更新日志

3.10.8

发布日期：2026-10-09

不兼容变更

插件

• OpenID Connect

  升级说明

  通过远程 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 Auth

  升级说明

  数据面现在会按照 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 插件元数据的配置项。如果业务依赖批量获取大响应，请在升级数据面前调大这两个值。

• Workflow

  升级说明

  每条规则的 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 匹配需要升级后的数据面

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 服务都属于这种情况。
• 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 请求头传入授权码，该方式的处理与之前相同。
• 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

  升级说明

  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 或更高版本的实例上报的是结构化问题，本控制面可以正常渲染。请预期在这类实例完成升级之前报告是空白而非可信的，不要把空白的报告当作没有问题。

实例本身仍会由版本规则标记为需要升级，因此不会悄无声息地显示为已是最新。这只影响兼容性报告的展示。它不会影响流量，也不会影响网关实例实际运行的配置；网关实例升级完成后，报告即恢复为文档描述的行为。

升级说明 — traffic-split 插件配置中的空 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 的任何修改都会被拒绝。

升级说明 — Dashboard 改由控制面进程提供服务，静态资源路径随之变化

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 中配置。
• Chaitin WAF
  • 现在可以在上报请求的同时把响应一并上报给长亭雷池（SafeLine）检测服务，这样响应体中泄露的数据、漏洞利用的输出，或者异常的状态码都能被雷池看到。插件和插件元数据上都提供了三个配置项：config.log_resp 开启响应上报，config.resp_body_size 以 KB 为单位限制上报的响应体大小（0 表示只上报响应头），config.extra_ignored_content_types 在内置忽略列表之外，以逗号分隔追加需要跳过的响应 content type。响应上报默认关闭。上报发生在响应已经返回给客户端之后，且仅供参考：它不会阻断也不会修改响应。
• 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]。

控制面

• 现在可以在网关旁边部署诊断 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] 察觉到内容被截断——出问题的上游连接也会被关闭，而不是放回连接池。
• 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 变量读取。

升级说明 — 日志插件在待处理条目达到 8192 时开始丢弃

除非在插件元数据中设置了 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 会真正执行所配置的鉴权校验

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 拒绝同名的 instance

AI Proxy Multi 此前接受两个 name 相同的 instance，这会让请求实际路由到哪个 instance 变得不确定。此类配置现在在写入时就以 HTTP 400 拒绝。

已经存储的配置仍可继续工作，但升级后会在数据面的配置兼容性报告中以 error 级别出现。请重命名重复的 instance 使每个名字唯一，配置被重新写入后该报告项即消失。

升级说明 — LDAP Auth 按转义后的绑定 DN 匹配消费者

LDAP Auth 此前通过普通字符串拼接重建一个可分辨名称（DN）来查找消费者，而只要用户名中含有在 DN 中具有结构含义的字符（, + = < > ; " \），这个 DN 就与实际用于绑定的 DN 不同。现在改为使用绑定时生成的转义 DN。

目录中所有用户名都不含上述字符的部署不受影响。如果某个消费者的 user_dn 是按旧行为以未转义形式写入的，请改写为 RFC 4514 转义形式（例如 cn=comma\,user,ou=users,dc=example,dc=org），否则该消费者在升级后不再匹配。

升级说明 — Proxy Cache 的内存缓存条目在升级后会重新回源一次

为修复下文「缺陷修复」中描述的变体键碰撞问题，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 变量传入的参数会参与成本计算，而不是被当作未提供。
• 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 拒绝。
• AI Proxy
  • 修复问题：当流式上游返回 HTTP 200 和 Content-Type: text/event-stream 后不写入任何内容就结束响应时，请求既没有被应答也没有被终止，客户端因此完全收不到 HTTP 响应，访问日志记录为长度为零的 500。现在返回 HTTP 502。
• AI Proxy Multi
  • 修复问题：请求重试到下一个 instance 时，使用的是上一次尝试已经改写过的请求体，因此上一个 instance 的 options（例如 temperature 或 max_tokens）会泄漏到发往回退 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

不兼容变更

插件

• 阿里云日志服务（SLS）

  升级说明

  该插件现在会校验日志服务器的 TLS 证书。旧版本在完成 TLS 握手时完全不校验证书，因此日志服务器出示自签名证书、私有 CA 签发的证书或已过期的证书都会被静默接受，而携带所配置访问密钥的日志记录仍会发往该服务器。

  校验行为由新增的 ssl_verify 选项控制，默认值为 true。升级后，若网关无法校验日志服务器的证书，批处理器会丢弃这批日志，并在错误日志中记录 failed to perform TLS handshake to TCP server。如果你的日志服务器出示的证书并非由公共可信 CA 签发，请在升级前把签发该证书的 CA 加入数据面的可信证书库，或在插件上把 ssl_verify 设为 false 以保持旧行为。

升级须知

升级说明 — Loki Logger 的 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 不再可能用一个各处相同的值签发。

升级前签发的会话使用的是旧的常量密钥，升级后不再被接受。控制面升级完成后，所有已登录用户都需要重新登录一次。升级前无需做任何准备，也不需要修改配置。

升级说明 — Docker Compose 部署改用 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。

升级说明 — 控制台 URL 不再带语言前缀

控制台现在在浏览器端应用界面语言，并用 Cookie 记住所选语言，因此 URL 不再带 /zh 前缀。升级后，含 /zh 的书签和已保存的链接会返回 HTTP 404，去掉该前缀后的同一路径即可访问对应页面。可选语言以及语言切换器本身没有变化。

新功能

插件

• LDAP Auth Advanced
  • 新增该插件，用于对接 LDAP 目录完成客户端认证，并把认证结果映射到消费者。插件采用「先检索、后绑定」的方式解析用户：在 base_dn 下按 attribute=username 检索，再以检索到的条目执行绑定，因此无需把目录结构写进网关配置。凭据从 Authorization 请求头读取，支持 ldap 和 basic 两种方案（header_type）；可通过 LDAPS 或 StartTLS 连接目录，且默认开启证书校验；连接在请求之间复用。消费者通过其凭据上记录的 user_dn 匹配，因此消费者级插件、限流和用量统计对 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 随推送请求一并发送。
• 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

升级须知

升级说明 — Logger 请求/响应体大小上限校验更严格

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 结构性指标标签不再允许禁用

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），方便运营者调整空闲超时时间和连接池大小。
• 需要缓冲请求/响应体的插件
  • 新增 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——使这两个上限在配置时被校验并在控制台中展示（参见「升级须知」）。

数据面

• 新增 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/https URL 的菜单项会被丢弃，不会下发给控制台。
• 服务冲突检测现在会计入路由的 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。

缺陷修复

插件

• AI Proxy、AI Proxy Multi 和 AI Request Rewrite
  • 修复问题：网关发往 LLM 服务商的请求会携带客户端自身的请求头，包括 Cookie、Authorization 以及任意自定义头，导致最终用户的凭证泄漏给上游服务商。现在网关只发送插件自身设置的请求头。
  • 修复问题：当 LLM 返回错误响应时，$apisix_upstream_response_time 和 $llm_time_to_first_token 记录的是秒（例如 0.240）或 0，而成功响应记录的是毫秒。现在错误路径也统一以毫秒上报，与成功路径一致。
• OpenID Connect
  • 修复问题：收到 state 与当前会话不匹配的授权回调时——例如在同一浏览器中先后发起了两个登录流程——会返回 HTTP 500。现在网关改为重定向到最初请求的页面。
  • 修复问题：身份提供商 userinfo 中的空 JSON 数组（例如 "roles": []）在复用已有会话的请求中会被重新编码为空对象（{}）写入 X-Userinfo 头，导致按数组解析该字段的上游服务出错。现在空数组仍然是数组。
• wolf-rbac
  • 修复问题：当鉴权服务返回成功但不带 userInfo 时，客户端自己传入的 X-UserId、X-Username、X-Nickname 请求头会被透传给上游服务，使调用方可以伪装成任意身份。现在这些请求头在转发前总是被清除。
• Limit Count
  • 修复问题：在 window_type: sliding 且开启延迟同步时，剩余配额的计算没有按滑动窗口加权，导致窗口边界附近放行的请求明显多于配置值。现在剩余计数按窗口加权计算。
• Limit Conn 和 Limit Req
  • 修复问题：Redis 连接没有归还到 keepalive 连接池，导致每个请求都新建一条 Redis 连接，已配置的 keepalive 参数完全不生效。现在连接会被正确复用。
• Prometheus
  • 修复问题：当指标使用的共享内存字典写满时，网关可能进入死循环，把某个 worker 的 CPU 占用拉满至 100%，且在流量停止后也不会恢复。现在字典写满会优雅降级，并记录「上报的指标数据可能不完整」的日志。

数据面

• 修复问题：使用 least_conn 负载均衡时，增删上游节点会丢弃已记录的连接数，导致算法退化为轮询，把新请求发给已经持有长连接的节点。现在负载状态会在上游扩缩容期间保留。
• 修复问题：当插件字段引用的密钥无法解析时——例如环境变量未设置，或密钥管理器返回错误——失败是静默的，未解析的引用会被当作字面值使用。现在网关会记录错误日志，指明具体的引用和所在字段。
• 修复问题：网关通过执行 /bin/hostname 获取主机名，因此在不包含该二进制的镜像上无法上报主机名，网关实例在控制台中显示为没有主机名。现在改为通过系统调用获取。
• 修复问题：nginx_config.envs 中值包含空格、引号或反斜杠的条目会生成非法的 NGINX 配置，导致网关启动失败。现在这些值会被正确地加引号和转义。
• 修复问题：通过 CLI 停止网关后立即启动可能失败，因为上一个实例尚未完全退出。现在 CLI 会等待其停止后再启动新实例。
• 修复问题：网关容器被强制杀死（而非正常关闭）后，残留的 worker event socket 可能导致下次启动无法绑定。现在启动时会先清理这些残留文件。
• 修复问题：在 arm64 架构上，某个依赖会把第二份 JSON 库拉入网关的模块搜索路径，遮蔽内置版本并把空数组编码成非法 JSON。现在已移除该冗余依赖，始终使用内置库。

控制面

• 修复问题：针对同一资源的两个并发 PATCH 请求可能各自在对方写入前读取资源，导致只有最后一次写入生效，而两个请求都返回成功。现在同一资源上的 PATCH 请求会被串行化。
• 修复问题：PATCH /apisix/admin/routes 在应用补丁时没有用路由 schema 校验合并结果，因此一次 PATCH 可能持久化超出 schema 限制的路由（例如超过 64 条 path），而后续的 PUT 请求和 adc sync 又会拒绝它。现在合并结果会在存储前完成校验。
• 修复问题：数据库连接池中的连接会被无限期复用，因此数据库发生主备切换后，控制面可能继续使用绑定在已被降级为只读的旧主库上的连接。现在连接生命周期默认限制为 1 小时，并可通过 database.max_lifetime 调整。
• 修复问题：导入证书链已过期的 License 时，报错信息为 license certificate comes from an invalid issuer，指向签发机构而不是过期本身。现在证书链已过期或尚未生效会返回带有相应时间戳的专门提示。确实来自未知签发机构的证书仍然报告 issuer 非法。
• 修复问题：当前数据面核数统计包含了已停止上报心跳的实例——这些实例在被标记为离线前会在 LostConnection 状态停留最长两小时——因此数据面缩容或崩溃后很久，控制台上的核数用量仍然偏高。现在只统计处于标准运行模式的已连接实例。基于心跳用量计算的 License 计费不受影响。

控制台（Dashboard）

• 修复问题：路由 path 列表和服务 host 列表允许添加超过 schema 限制（64 条 path、32 个 host）的条目。此时新建资源会返回原始的服务端错误，而编辑资源则可能存下随后被 adc validate 和 adc sync 拒绝的配置。现在列表达到上限后会隐藏 Add 控件；已经超出上限的列表仍会完整展示所有条目，便于删除多余项。

3.10.3

发布日期：2026-07-14

升级须知

升级说明 — 网关默认内存占用升高

多个数据面共享内存（lua_shared_dict）默认值被调高，因此在默认配置下，3.10.3 网关启动时预留的共享内存比 3.10.2 约多 365 MiB：

共享字典	3.10.2 默认值	3.10.3 默认值
prometheus-metrics（高级指标）	15 MiB	128 MiB
kubernetes、nacos、nacos-stream、consul（服务发现）	各 20 MiB	各 64 MiB
tracing_buffer（SkyWalking）	10 MiB	32 MiB
api-calls-for-portal	10 MiB	64 MiB

这些字典在网关启动时分配，无论对应功能是否被使用，因此该增长适用于每一个 3.10.3 网关。升级前，请调高网关容器的内存 requests 和 limits（在 Kubernetes 中还应检查节点的内存压力与驱逐阈值），避免网关被 OOM 杀死。如果你未使用某项功能——例如某种未配置的服务发现类型——可以通过网关配置或 Helm chart 的共享字典值把对应字典调回原先的大小。

升级说明 — 内置用户登录策略更严格

内置 Dashboard 用户现在会在连续密码登录失败后被临时锁定。默认策略为启用状态，同一用户和来源 IP 连续失败 5 次后锁定 15 分钟。管理员可以通过新的登录失败限制系统设置调整或关闭该策略。升级后新密码和被修改的密码也必须至少 12 个字符，并继续满足原有复杂度要求。已有密码在登录时不会重新校验长度。

如果内置用户启用了双因素认证（2FA），该用户的 HTTP Basic Auth 会被拒绝，因为 Basic Auth 无法携带第二因素。程序化集成请改用 Token 认证；Token 通过 X-API-KEY 请求头传入，不需要携带 2FA 验证码。

升级说明 — 仅信任来自可信地址的转发头

网关现在通过 apisix.trusted_addresses 判断是否信任客户端传入的 X-Forwarded-* 和 RFC 7239 Forwarded 请求头。当未配置 trusted_addresses，或请求来自不可信地址时，网关会在转发上游前用自身观测到的值覆盖 X-Forwarded-Proto、X-Forwarded-Host 和 X-Forwarded-Port，并清除 Forwarded 请求头。如果上游应用依赖可信负载均衡器或反向代理传入的原始转发协议、host 或端口，请将该代理的 IP 或 CIDR 配置到 trusted_addresses。

升级说明 — OpenID Connect 不再默认启用静默重认证

openid-connect 插件不再默认把 refresh_session_interval 设为 900 秒。现在只有显式配置 refresh_session_interval 时才会执行周期性静默重认证。如果你的部署依赖此前 900 秒刷新一次的行为，请在升级前或升级过程中显式设置 refresh_session_interval: 900。

升级说明 — SQL Server 部署首次启动会启用快照读

对于使用 SQL Server 的部署，控制面现在会先创建并准备数据库，再让其他组件连接，并启用 READ_COMMITTED_SNAPSHOT，避免网关配置读取被写事务阻塞。若既有 SQL Server 数据库尚未启用该设置，首次启动会以 ROLLBACK IMMEDIATE 应用该数据库级变更；正在进行的数据库事务和连接可能会被断开一次，之后连接池会重新连接，后续启动不会重复执行该操作。

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.10.3 的控制面会加密这些字段，而仍为 3.10.2 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• ai-cache：semantic.embedding.openai.api_key、semantic.embedding.azure_openai.api_key

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.10.3，并在两侧都升级到 3.10.3 之前避免编辑这些插件。

新功能

插件

• AI Cache
  • 在精确匹配缓存之外，新增语义（L2）缓存层，通过 RediSearch 按 embedding 相似度匹配提示词。流式 LLM 响应现在可以被缓存并回放，而不再被跳过。新增 Prometheus 指标，报告缓存命中、未命中、绕过和 embedding 延迟。
• AI Aliyun Content Moderation
  • 新增 request_check_roles，用于选择要审查的请求角色（user、tool 和/或 system）。user 和 tool 内容遵循 request_check_mode（last 或 all，默认 last）；选择 system 时，系统内容会在每个请求中检查。长内容现在以线性时间分块，且对多字节（UTF-8）安全。
• AI AWS Content Moderation
  • 请求审查现在在 AI 协议识别之后执行，检查上游 LLM 实际可见的解码后提示词内容，而不是原始 HTTP JSON 外壳。拒绝响应现在以提供商兼容格式返回，并新增可配置的 check_request、deny_code 和 deny_message。
• IP Restriction
  • 新增可配置的 response_code（403 或 404，默认 403），在请求被拦截时返回，使运营者可以用 404 隐藏资源是否存在。
• File Logger
  • 日志文件 path 现在可以在插件元数据中设置一次并在多条路由间共享，不必在每条路由的插件配置中都填写。插件配置中设置的 path 仍然优先于元数据中的值。
• Logger 插件
  • 为 HTTP Logger、RocketMQ Logger、TCP Logger、Tencent Cloud CLS 和 UDP Logger 的 schema 新增 max_req_body_bytes 和 max_resp_body_bytes，使请求/响应体大小上限（默认 524288 字节）在配置时被校验并在 Dashboard 中展示。
• 限流插件
  • 为 Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置（redis_keepalive_timeout 和 redis_keepalive_pool），方便运营者调整空闲超时时间和连接池大小。

数据面

• 新增 apisix.trusted_addresses，根据解析后的客户端地址控制网关是否信任客户端传入的 X-Forwarded-* 和 Forwarded 请求头。
• 新增 apisix.match_uri_encoded_slash。启用后，编码斜杠（%2F）在路由匹配期间保持编码状态，可作为路径参数的一部分，而不是路径分隔符。
• 在 standalone YAML 模式中，环境变量占位符现在会在 YAML 解析前替换。未加引号的占位符可以解析为原生布尔值或数字；加引号的占位符仍保持字符串，从而精确保留大整数 ID 和 Token 值。

控制面

• 为内置 Dashboard 用户新增 TOTP 双因素认证。用户可在账号设置中注册、启用、关闭和恢复 2FA；管理员可重置用户的 2FA 状态。
• 为内置用户新增登录失败限制。连续失败登录会临时锁定用户和来源 IP，写入审计事件，并返回明确的锁定提示。
• 新增双因素认证的 Dashboard UI：账号设置中的二维码和恢复码设置流程、登录时的 OTP 步骤，以及管理员重置用户 2FA 的操作。
• 密码表单和随机密码生成已更新为新的 12 字符最小长度。

开发者门户

• 新增强制双因素认证选项。当启用 2FA 且设置了 twoFactor.required 时，开发者必须先完成 2FA 注册才能访问受保护页面，该要求在登录和代理层都会强制执行。

缺陷修复

插件

• AI Proxy 和 AI Proxy Multi
  • 修复问题：包含 tool result 且混有其他内容的 Anthropic Messages 请求会被转换成非法的 OpenAI Chat 消息顺序，导致 OpenAI 兼容上游拒绝该会话后续的每个请求。现在 tool 消息会紧跟在包含 tool call 的 assistant 消息之后，旁边的文本或媒体会保留在后续 user 消息中。若干其他 Anthropic 到 OpenAI 的转换细节也已与 LiteLLM 兼容行为对齐，包括工具名清洗、长工具名冲突处理、adaptive thinking effort、结构化输出 schema 提取、空数组编码和内容块形状。
  • 修复问题：结构化 chat content 可能以 table 形式传给下游 AI 插件并导致请求处理错误。协议适配器现在会在 AI guard 和 cache 插件消费前一致地拍平文本内容。
• AI Lakera Guard
  • 修复问题：在 action: alert 且 fail_open: false 的流式响应中，Lakera API 报错或超时可能放行已流出的响应，而不是 fail closed。现在 Lakera 报错会按 fail_open 处理，严格配置下会拦截响应。
• AI AWS Content Moderation 和 AI Aliyun Content Moderation
  • 修复问题：deny_code 此前接受任意数字。现在会校验为 200–599 范围内的整数 HTTP 状态码（默认 200），超出范围的值会在配置时被拒绝。
• AI Aliyun Content Moderation
  • 修复问题：在 body filter 中返回 ngx.OK 可能中断后续 body filter 处理。现在插件会正常返回，使其他 filter 可以继续执行。
• AI Rate Limiting
  • 修复问题：部分已配置的 Redis 字段会被丢弃并替换为默认值——redis-sentinel 策略的 redis_username/redis_password，以及 redis 和 redis-cluster 策略的 redis_keepalive_timeout/redis_keepalive_pool。现在所有已配置的 Redis 字段都会被转发。
• gRPC Transcode
  • 修复问题：空的 protobuf repeated 字段会被编码为 {} 而不是 JSON 数组（[]）。现在空 repeated 字段会显示为数组，包括嵌套消息和 descriptor-set 方式的消息。
• Key Auth 和其他 Consumer 认证插件
  • 修复问题：如果 Consumer 凭据引用了无法解析的 secret，数据面可能仍把未解析的字面量加入索引，并用该字面量完成认证。现在引用的 secret 无法解析时，Consumer 认证会 fail closed。
• Secret 引用
  • 修复问题：更新或删除 /secrets 配置不会使 secret LRU 缓存失效，因此旧 secret 值可能继续使用到缓存过期，甚至无限期使用。现在 secret 配置变化后会重新解析 secret 引用。
• Proxy Rewrite
  • 修复问题：同时配置 use_real_request_uri_unsafe 和 uri 时，请求 query string 会在 URI 改写中丢失。现在会保留原始 query string，并在改写后的 URI 已含 query 时正确合并。
• Loggly
  • 修复问题：不同 route 的批量 Loggly 日志可能使用错误的 Token 或 tags，因为异步处理器复用了最新 route 的配置。现在每个批处理器都会保留自己的 route 配置。
• Datadog
  • 修复问题：较大的合并 DogStatsD datagram 可能超过常见的 8192 字节 agent 缓冲区并被静默截断。现在只有在 payload 可容纳时才合并，否则回退为每个 metric 一个 datagram。
• Zipkin
  • 修复问题：明确标记为未采样的请求仍会构造完整 span tag table 和 access 阶段子 span。现在未采样请求会跳过这些额外追踪工作，同时保留 trace 传播。
• OpenTelemetry
  • 修复问题：运行时更新 OpenTelemetry 插件元数据不会重建用于注入 core span 的 tracer，因此这些 span 可能继续使用旧 collector 或 resource 设置，直到 worker 重启。现在元数据变化后 tracer 会刷新。
  • 修复问题：additional_attributes 在 log 阶段变量填充前求值，导致依赖最终请求状态的属性缺失或过期。现在这些属性在 log 阶段求值。
  • 修复问题：当 trace_id_source 设为 x-request-id 时，非合法十六进制的 X-Request-Id 值（例如 UUID）或重复的请求头可能返回 HTTP 500。现在会校验该值，无法使用时回退为随机的合法 trace ID。
  • 修复问题：插件元数据 schema 接受 resource 属性和 collector.request_headers 的非标量值，这些值随后会在运行时被静默丢弃。现在这类值会在配置时被拒绝。
• OpenID Connect
  • 修复问题：refresh_session_interval 错误地默认设为 900，即使用户未配置也会启用静默重认证。该默认值已移除（见升级须知）。
• MQTT Proxy
  • 修复问题：protocol_name 过去是必填项，尽管标准默认值是 MQTT。现在该字段可省略，并默认使用 MQTT。
• Forward Auth
  • 修复问题：当 request_method 为 POST 时，插件在缓冲请求体后仍可能把客户端的 Transfer-Encoding、Content-Length 和 Expect 请求头转发给认证服务，导致请求 framing 不一致。现在这些客户端 framing 头不会再复制到认证服务请求中。
• Authz CASBIN
  • 修复问题：在不同 route 之间切换不同 Casbin model 或 policy 形状时，可能触发 casbin enforce error / invalid request size。内置 lua-casbin 依赖已更新，包含相关 enforce 修复。
• Request ID
  • 修复问题：配置 algorithm: range_id 但省略可选 range 对象时可能返回 HTTP 500。现在 range 对象有默认值。
• Workflow
  • 修复问题：Workflow action 插件可能在 workflow 决定跳过或执行该 action 前先运行 _meta.pre_function hook，从而影响本不应执行的 action。现在 workflow 会先决定是否运行 action，再执行这些 meta hook。
• Request Validation
  • 修复问题：Content-Type 带 charset 参数或大小写不同（例如 application/x-www-form-urlencoded; charset=utf-8）的表单请求体未被识别为 form-urlencoded，因而被当作 JSON 解析并以 HTTP 400 拒绝。现在这类 Content-Type 会被识别并按表单体校验。

数据面

• 修复问题：部分日志文件被 rotation 后，网关可能仍保持旧文件句柄。现在部分 rotation 后也会正确重新打开日志。
• 修复问题：当配置源上报的 revision 比网关已见过的更小时（例如控制面数据库被恢复到较早状态），网关可能持续下发过期配置，直到 worker 重启。现在观测到更小的 revision 时会强制进行一次完整配置重新同步。
• 修复问题：通过 global rule 或 consumer 挂载的插件（如 ai-proxy-multi）可能因网关无法在请求时获取插件的父配置而返回 HTTP 5xx。现在所有承载插件的资源类型都能被正确解析。
• 修复问题：当 client-control 配置 max_body_size: 0（不限制）时，分块请求体仍可能被以 HTTP 413 拒绝。现在 max_body_size 为 0 会正确地对分块请求禁用大小检查。

控制面

• 修复问题：配置 revision 刚变化后、下一次 heartbeat 尚未上报新 revision 前，网关实例可能短暂显示为 OutOfSync。现在新增宽限窗口，在正常同步窗口内仍保持最近有 heartbeat 的实例为 Healthy。
• 修复问题：兼容性报告被截断为 200 条且顺序不稳定，因此大报告可能隐藏 error，并在不同网关实例间显示不同结果。现在控制面会存储完整且排序后的报告，并基于全部条目计算兼容性。
• 修复问题：secret provider 的请求体可能匹配与 URL 路径中 provider 名称不同的类型，导致数据面丢弃或误读已保存 secret。现在控制面会按路径选择的 provider 类型校验请求体。
• 修复问题：控制面接受了一些数据面会静默丢弃的核心资源配置，包括非法 TLS、filter 和 IP match 配置。现在这些配置会在发布前被校验拒绝。
• 修复问题：运行时 services 端点上的插件配置未被校验，因此带有非法插件配置的 service 会被接受，随后被数据面静默丢弃。现在 service 的插件配置会被校验，非法时以 HTTP 400 拒绝。
• 修复问题：OpenAPI schema 会拒绝 IPv6 upstream node host。现在 IPv6 host 可以被接受。
• 修复问题：batch ssls 校验使用了 SNI schema 而不是 SSL schema，导致缺少证书字段的条目可能通过校验。现在 batch SSL 校验使用正确 schema。
• 修复问题：审计日志导出只返回前 256 条。现在会导出所有匹配的审计日志。
• 修复问题：凭据查询索引可能被不执行数据库迁移的组件删除，且部分启动 schema repair 会不必要地重建当前索引。现在 schema repair 会保留当前索引，仅修复过期形状。
• 修复问题：在大型部署中，heartbeat 和实例状态查询可能变慢。新增索引和 Go 侧状态计算改善了这些查询。

3.10.2

发布日期：2026-06-29

升级须知

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.10.2 的控制面会加密这些字段，而仍为 3.10.1 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• limit-count、limit-count-advanced 和 graphql-limit-count：redis_password、sentinel_password
• limit-conn：redis_password
• limit-req：redis_password
• ai-rate-limiting：redis_password、sentinel_password
• elasticsearch-logger：headers（自定义认证请求头）
• openid-connect：session.redis.password
• ai-cache：redis_password
• ai-lakera-guard：api_key

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.10.2，并在两侧都升级到 3.10.2 之前避免编辑这些插件。

升级说明 — hmac-auth 默认请求体大小上限提升至 64 MiB

当 hmac-auth 启用 validate_request_body 时，默认的 max_req_body_size 现在为 67108864 字节（64 MiB），与 Apache APISIX 对齐。在 3.10.1 中该默认值为 524288 字节（512 KiB），会以 HTTP 413 拒绝 512 KiB 到 64 MiB 之间的请求体。升级后，这类请求默认会被接受。如果你依赖较低的上限，请显式设置 max_req_body_size 以恢复。

升级说明 — 开发者门户注册同意项配置变更

开发者门户的注册同意项现在通过单个 signUpConsentLabel 选项配置（渲染在同意复选框旁边的 HTML 片段），且仅在配置了该标签时才强制要求同意。原有的 tosURL 和 beforeSignUpButtonHtml 选项已移除。如果你的门户配置设置了其中任一项，请在升级前将内容迁移到 signUpConsentLabel，否则注册同意文案将不再显示。

新功能

插件

• AI Cache（新插件）
  • 缓存 LLM 响应，使相同的请求从缓存返回，而不再重复调用上游模型。精确匹配缓存以归一化后的请求体为键，存储在 Redis 中；缓存命中时返回存储的响应，并带 X-AI-Cache-Status: HIT 和 X-AI-Cache-Age 响应头。流式请求会被跳过（X-AI-Cache-Status: BYPASS）。
• AI Lakera Guard（新插件）
  • 通过 Lakera Guard API 检测 AI 流量中的提示词注入和其他不安全内容。direction 选项（input、output 或 both）用于选择插件扫描请求提示词、LLM 响应（包括流式响应）还是两者。被标记的流量会以可配置的 deny_code 拒绝，或在 action 设为 alert 时仅记录日志。
• AI Aliyun Content Moderation
  • 新增 request_check_mode（last 或 all，默认 last），用于控制审查多轮对话的范围：last 仅检查最后一个 user 轮次，all 检查每个 user 轮次。仅审查 user 角色的内容，忽略 system 和 assistant 内容。长内容现在以线性时间分块，且对多字节（UTF-8）安全。
• AI Proxy
  • 发送给 logger 插件的结构化 llm_summary 对象（启用 logging.summaries 时）现在包含更多 AI 可观测性字段：stream、tool_count、has_tool_calls、end_user_id、cache_read_input_tokens、cache_creation_input_tokens 和 reasoning_tokens。
• Elasticsearch Logger
  • 新增通过自定义请求头向 Elasticsearch 认证的支持（headers 选项，例如 Authorization: Bearer <token> 或 API key 请求头），作为基本 auth 的替代方式。
• OpenID Connect
  • 新增 Redis 作为会话存储后端。将 session.storage 设为 redis 并配置 session.redis（host、port 等选项），即可把会话存储在 Redis 而非会话 cookie 中；默认仍为 cookie。

数据面

• 新增 log_format_extra——一种用于 logger 插件的叠加式日志格式，它在默认的丰富日志格式上追加字段，而不像 log_format 那样替换默认格式。新增变量 $upstream_unresolved_host 记录 DNS 解析前配置的上游 host。log_format_extra 可通过插件元数据全局设置，也可按路由设置。
• 为流（L4）TCP 代理新增按端口的 PROXY protocol 控制。每个 stream_proxy.tcp 条目可独立启用接收 PROXY protocol（proxy_protocol）和向上游发送 PROXY protocol（proxy_protocol_to_upstream），覆盖全局默认值。
• 新增 max_post_args_readable_size 配置项（默认 64 MiB），用于限制在匹配 post_arg.* 路由谓词（针对 JSON 和 multipart 请求）时读取的请求体大小。设为 0 可禁用该限制。
• 调试会话现在会把每个请求的日志作为 OpenTelemetry span event 记录在请求的 root span 上，因此无需外部日志收集器即可在 trace 中查看每个请求的日志。

控制面

• 新增数据面的 RPM 安装方式，与现有的 Docker 和 Helm 方式并列。Dashboard 的网关组部署页面新增 RPM 标签页；在隔离网络主机上安装 api7-gateway RPM 后，生成的离线脚本会下发网关组客户端证书、写入网关配置，并将实例接入控制面。

开发者门户

• 禁用 API Hub：运营者可通过新增的 apiHub.enabled 配置开关完全关闭 API Hub。禁用后，导航中的 API Hub 链接会隐藏，API Hub 页面返回 not-found，且 API Hub 的 URL 会从 sitemap 中移除。
• 强制邮箱验证：可配置在注册和登录时要求开发者先验证邮箱地址才能完成认证。
• 自定义 PostgreSQL schema：门户可以部署到自定义的 PostgreSQL schema（而非 public），按连接应用该 schema 的 search_path 并运行 schema 范围内的迁移。
• 平台管理员的组织管理：管理员的 Organizations 页面现在可以接管组织（成为其 owner）或删除组织，作为对原有用户管理操作的补充。
• 文档 Markdown 与 LLM 端点：门户内文档站现在提供 Markdown 和面向 AI 工具的 LLM 友好文本端点，且可以将单个文档页面排除在这些端点之外，同时仍可在文档界面中正常阅读。

缺陷修复

插件

• AI Proxy
  • 修复问题：当上游返回的工具调用的 arguments 不是合法 JSON 时，整个响应转换会被中断，客户端收不到任何内容。现在该非法工具调用会回退为空参数对象，响应的其余部分（包括任何文本内容）得以保留。
  • 修复问题：携带 tool_choice 但没有可用 tools 的请求（例如只有一个在转换中被丢弃的内置工具）会带着孤立的 tool_choice 转发并被上游拒绝。现在这样的 tool_choice（以及 parallel_tool_calls）会被移除。另外，上游省略最后完成块的流式 Anthropic 请求不再让客户端挂起到超时——流现在会被正确终止。
  • 修复问题：当上游 LLM 返回错误状态（如 HTTP 429 或 5xx）时，错误响应体被丢弃，客户端收到空响应体。现在上游错误响应体和 content type 会被保留，ai-proxy-multi fallback 场景下也是如此。
• AI Proxy Multi
  • 修复问题：构建工作实例池失败时可能抛出 Lua 错误并破坏性地清空池状态。现在该失败路径对 nil 安全且不具破坏性。
• Limit Count
  • 修复问题：当 count 或 time_window 来自变量时，非法值（非整数、零或负数、或超出安全整数范围）会被静默忽略，从而可能完全失效限流。现在这类值会被校验并拒绝，堵住了一处限流绕过。
  • 修复问题：使用 Redis 策略和滑动窗口计数时，检查与自增不是原子操作，因此并发请求可能超过配置的上限。现在计数通过 Redis 脚本原子完成。
• Limit Req
  • 修复问题：限流计数的键设置方式导致挂在共享资源（如 Consumer）上的限流对每条路由分别计数，而不是共用一个桶。现在计数按父资源为键，因此 Consumer 级别的限流会在该 Consumer 的所有路由间共同生效。
• HMAC Auth
  • 修复问题：当启用 validate_request_body 且请求体超过 max_req_body_size 时，请求会以容易误解的 HTTP 401 被拒绝。现在改为以 HTTP 413 拒绝。默认的 max_req_body_size 也提升至 64 MiB（见升级须知）。
• Attach Consumer Label
  • 修复问题：当匹配到的 Consumer 没有标签时，客户端可以伪造已配置的请求头，因为插件只在存在标签值时才覆盖该请求头。现在已配置的请求头总会从客户端请求中剥离，即使 Consumer 没有匹配的标签。
• Redirect
  • 修复问题：http_to_https 仅重定向 scheme 恰好为 http 的请求，因此以非 HTTP、非 HTTPS scheme 到达的请求（例如通过伪造的 X-Forwarded-Proto）不会被重定向。现在它会重定向所有非 HTTPS 的 scheme。
• Response Rewrite
  • 修复问题：当上游响应被压缩（gzip 或 brotli）时，filters 作用在压缩字节上而无法匹配，产生损坏的响应体。现在会先解码响应再执行 filters。
• Batch Requests
  • 修复问题：当某个流水线子请求超时时，响应数组可能比子请求数多出条目（一个多余的空对象）。现在子响应的数量总是与子请求的数量一致。
• Loki Logger
  • 修复问题：从变量解析出的日志标签被写回共享的插件配置，导致第一个请求的值被冻结并复用于后续所有请求。现在标签会按请求解析。
• Tencent Cloud CLS
  • 修复问题：启用 include_req_body 时，由于未在 access 阶段读取请求体，请求体无法被捕获。现在会读取请求体，使其包含在上传的日志中。
• Authz Keycloak
  • 修复问题：启用 lazy_load_paths 时，按 URI 解析 Keycloak 资源时包含了请求的 query string，导致带 query 参数的请求无法匹配到资源而被拒绝。现在会在解析前剥离 query string。
• CAS Auth
  • 修复问题：CAS 单点登出（SLO）回调 POST 被代理到上游，而不是由插件处理。现在该回调由插件终止，不再转发到上游。
• gRPC Web
  • 修复问题：一条调试日志语句把解码后的请求体写入错误日志。该语句已移除，请求负载不再泄漏到日志中。

数据面

• 修复问题：在日志格式中解析点号上下文变量（如 $consumer.username 或 $llm_summary.model）时，若父对象不存在（例如没有 consumer 的未认证请求），会抛出错误并丢弃该日志行。现在缺失的值会被优雅处理。
• 修复问题：在一次瞬时 DNS 或服务发现失败后，域名上游即使在名称重新解析成功后仍可能持续返回 HTTP 503。现在上游会在解析成功后恢复。
• 修复问题：当节点健康状态变化时，一致性哈希（chash）环会按健康子集重建，导致原本属于健康节点的键被重新映射。现在该环会保持稳定，只有故障节点的键会被重新映射。
• 修复问题：配置指令中的环境变量替换在一个变量名是另一个变量名的前缀时，可能匹配到错误的变量。现在变量名会被精确解析。
• 修复问题：升级 Prometheus 指标库（nginx-lua-prometheus-api7 升至 0.20260623），移除可能导致整次抓取被拒绝的重复指标序列。

控制面

• 修复问题：运行最新网关版本的数据面在其配置报告包含错误时会被标记为 Incompatible。现在运行最新版本的数据面会保持 Compatible，配置错误仍会在兼容性报告摘要中呈现。

开发者门户

• 修复问题：启用或关闭双因素认证时并未真正校验账号密码，备份码对话框可能显示为空，且在登录时输入错误的 TOTP 验证码会跳转到首页而非显示错误。现在密码校验、备份码展示和 TOTP 错误处理都能正确工作。
• 修复问题：邮箱域名的 SSO 策略此前仅在 UI 层强制，因此直接调用认证端点可以绕过它。现在该策略在服务端强制：对于要求使用 SSO 的域名，密码登录、magic link 和密码重置请求都会被拒绝。

3.10.1

发布日期：2026-06-15

不兼容变更

插件

• JWT Auth

  升级说明

  jwt-auth 现在默认校验 Token 的 exp（过期）和 nbf（生效时间）声明。此前，未设置 claims_to_verify（或将其设为空列表）的 consumer 会接受任何签名正确的 Token，包括已过期的 Token。数据面升级后，这类 Token 会被以 HTTP 401 拒绝。

  如果你依赖已过期 Token 仍被接受，请在升级前评估此行为变更。如需只校验特定声明，请在 consumer 配置中显式设置 claims_to_verify。

• Batch Requests

  升级说明

  batch-requests 插件现在会限制批量请求的规模。流水线子请求的数量由新增的插件元数据选项 max_pipeline_items 限制（默认 1000），超过上限的批量请求会被以 HTTP 400 拒绝。包含文档之外字段的流水线条目现在会被拒绝，且每批的 timeout 至少为 1 毫秒。

  如果你发送的批量请求超过 1000 个子请求，请在插件元数据中调大 max_pipeline_items。如果客户端发送了未文档化的条目字段，请在升级前移除它们。

升级须知

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.10.1 的控制面会加密这些字段，而仍为 3.10.0 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• http-logger：auth_header
• kafka-logger：brokers.sasl_config.password
• splunk-hec-logging：endpoint.token
• loggly：customer_token
• openfunction：authorization.service_token
• azure-functions：authorization.apikey，以及插件元数据 master_apikey
• ai-aws-content-moderation：comprehend.secret_access_key
• openid-connect：session.secret
• error-log-logger（插件元数据）：kafka.brokers.sasl_config.password

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.10.1，并在两侧都升级到 3.10.1 之前避免编辑这些插件。

升级说明 — limit-count 现已包含 advanced 限流能力

此前仅 limit-count-advanced 独有的全部能力——redis-sentinel 策略、滑动窗口计数、在一份配置中设置多个独立限流（rules）、由 NGINX 变量驱动的动态 count 和 time_window、以及延迟 Redis 同步（sync_interval）——现已内置到 limit-count 插件中。既有的 limit-count-advanced 配置可继续原样使用（该插件作为薄封装保留），无需做配置迁移。

一个升级时的影响：对于基于 Redis 的策略，计数器存储格式发生了变化，且计数器 key 现在带版本号。既有计数器不会被迁移——它们会按各自的 TTL 自然过期——因此限流计数器会在升级时刻重置一次。（local 策略本就在重启时重置。）会有一个短暂的计数重置窗口，无需任何操作。

升级说明 — 多个插件新增请求体大小限制

为了限制内存占用，多个插件现在会在缓冲之前拒绝过大的请求体：

• hmac-auth：当启用 validate_request_body 时，请求体大小由新增的 max_req_body_size 选项限制（默认 524288 字节，即 512 KiB）。
• forward-auth、ai-proxy、ai-proxy-multi：请求体大小由新增的 max_req_body_size 选项限制（默认 67108864 字节，即 64 MiB），超过上限的请求会被以 HTTP 413 拒绝。

这些默认值高于 NGINX 默认的 client_max_body_size（1 MiB），因此大多数部署不受影响。如果你确实需要在使用这些插件的 route 上处理更大的请求体（并已相应调大 client_max_body_size），请将 max_req_body_size 调整到匹配的值。

升级说明 — 开发者门户凭据密钥仅展示一次

在开发者门户中，凭据的 key-auth key 和 basic-auth password 现在仅在创建或重新生成凭据时返回一次，不再包含在凭据的读取或列表响应中，这与 OAuth client_secret 的现有行为一致。basic-auth 的用户名仍然可见。

请在密钥首次展示时复制并妥善保存。如果密钥丢失，请重新生成凭据以获得新值。任何从凭据读取或列表接口回读这些密钥的集成都需要改为在创建时捕获它们。

升级说明 — Prometheus TTFT 指标改为标签

独立的 apisix_llm_ttft 指标已被 apisix_llm_latency{type="ttft"} 取代，与 apisix_http_latency 的结构保持一致。如果你的 Prometheus 查询或 Grafana 看板引用了 apisix_llm_ttft，请改为选择 apisix_llm_latency 上 type 标签的 ttft 值。

新功能

插件

• Limit Count
  • 此前仅 limit-count-advanced 提供的高级限流能力，现在可直接在 limit-count 中使用：redis-sentinel 策略、滑动窗口计数（window_type 设为 sliding）、在一份配置中设置多个独立限流（rules）、由 NGINX 变量驱动的 count 和 time_window（例如按 consumer 的动态配额）、以及延迟 Redis 同步（sync_interval）。
• AI 内容安全插件（ai-aliyun-content-moderation、ai-aws-content-moderation、ai-prompt-guard）
  • 新增 fail_mode 选项（skip、warn 或 error，默认 skip），用于控制当插件绑定在 Consumer 级别、收到非 AI 或非 JSON 请求时的处理方式。skip 会让这类请求不经检查直接放行；warn 会额外记录一条警告日志；error 则拒绝它们。这避免了 Consumer 级绑定的审核插件收到普通（非 AI）流量时报错。
• AI Proxy
  • 新增描述每个 LLM 请求的内置 NGINX 变量，可用于 access_log 格式和 logger 插件：$llm_total_tokens、$llm_stream、$llm_has_tool_calls、$llm_tool_count、$llm_end_user_id、$llm_cache_read_input_tokens、$llm_cache_creation_input_tokens 和 $llm_reasoning_tokens。已为 OpenAI（Chat 与 Responses）、Anthropic 和 DeepSeek 提供映射。
• Prometheus
  • 新增 LLM 可观测性指标：按请求统计的 prompt Token 和 completion Token 分布直方图（apisix_llm_prompt_tokens_dist、apisix_llm_completion_tokens_dist）、总延迟直方图，以及以 apisix_llm_latency{type="ttft"} 暴露的首 Token 时间（TTFT，仅流式请求）。直方图的 bucket 可通过 plugin_attr.prometheus 配置。
  • 为 http_status、http_latency 和 bandwidth 指标新增 mcp_request_type 和 mcp_tool_name 标签，从而可以按请求类型（tools/list 或 tools/call）和工具名称拆分 MCP（Model Context Protocol）流量。这两个标签都可以通过 disabled_labels 关闭。
  • 在指标日志阶段缓存 disabled-labels 映射，而不是每个请求都重建，降低了每请求开销。
• AI Proxy Multi
  • 为 fallback 机制新增 max_retries 和 retry_on_failure_within_ms。max_retries 限制单个请求在失败后最多重试多少个额外实例；retry_on_failure_within_ms 仅在上游于指定时间内失败时才进行 fallback，因此慢失败会直接返回给客户端，而不是再重试（避免长耗时 LLM 请求的延迟翻倍）。
• OpenID Connect
  • 在 session 下暴露了 lua-resty-session 选项（cookie 的 name、path、domain、secure、http_only、same_site，以及 idling、rolling、absolute 超时），因此你可以自定义会话 cookie 名称并设置真正生效的会话有效期。旧的 session.cookie.lifetime 已废弃但仍被兼容（映射为 absolute_timeout）。
  • 对于只在本地校验 Token、不调用身份提供方的流程（bearer_only 搭配 public_key 或 use_jwks、private_key_jwt、以及公共客户端 PKCE），client_secret 现在是可选的。会话/回调和 introspection 流程仍然必须提供它。
• Kafka Logger
  • 为 Kafka 生产协议新增 api_version 选项（0、1 或 2，默认 1）。将 api_version 设为 2 可让 broker 记录真实的消息时间戳（Kafka 0.10 及以上）；默认值 1 保留协议兼容性。

开发者门户

• 双因素认证：开发者可使用 TOTP 验证器 App 保护自己的账号。在账号安全设置中启用 2FA（确认密码、扫描二维码），也可在此关闭；启用后登录会要求输入六位验证码。
• 深色模式：门户支持浅色、深色和跟随系统三种主题，可通过页头的开关切换，应用于整个界面、API 用量图表和文档站，并在多次访问间保持。
• 平台管理后台：新增管理区域（仅限配置的管理员用户），其中的 Users 页面可列出、搜索和分页查看门户用户，修改用户角色、封禁或解封、删除用户；Organizations 页面可按用户成员关系筛选。
• 门户内审批：平台管理员可以在门户新增的 Approvals 页面中查看并处理开发者注册和 API Product 订阅申请。审批与 Dashboard 共享同一数据源，每次处理都会记录操作管理员的身份（Dashboard 的审批列表现在会为门户中做出的处理显示真实的管理员名称）。
• 基于策略的 SSO 登录：登录会根据所输入的邮箱把用户引导到正确的方式（密码、magic link 或 SSO）。管理员可以把邮箱域名映射到 SSO 提供方，并支持锚定、大小写不敏感的正则表达式模式，因此一条规则即可覆盖多个域名。
• 门户内文档站：门户现在在 /docs 托管一个与门户风格一致的 Markdown 文档站，带可折叠侧边栏、目录、代码复制按钮、"Copy page" 菜单，以及带高亮匹配片段的内置全文搜索。
• 注册服务条款：新用户需要同意服务条款才能完成注册；服务条款 URL 可配置。
• 简化组织创建：「创建组织」对话框不再要求填写 slug——标识符会根据名称自动分配。

缺陷修复

插件

• JWT Auth
  • 修复问题：当 Token 的签名格式有误（长度不对或不是合法的 base64url）时，校验器会抛错并返回 HTTP 500，而不是拒绝请求。现在签名格式有误的 Token 会以 HTTP 401 被拒绝。
• AI Proxy
  • 修复问题：在 passthrough 模式下，发往上游的请求总是以 POST 发送，且丢弃了客户端的查询字符串，导致需要在其他方法上携带查询参数的提供方失败（例如 Azure OpenAI 的 ?api-version=）。现在会转发客户端的方法和查询字符串。
  • 修复问题：访问上游 LLM 超时（例如 DNS 解析超时）时返回 HTTP 500 而不是 HTTP 504。现在上游 LLM 超时会正确返回 HTTP 504。
• AI Proxy Multi
  • 修复问题：在按实例创建健康检查器之后，缓存的节点选择器没有重建，导致某个 worker 可能持续把部分流量路由到已被标记为不健康的实例；对配置了 auth.query 或 auth.header 的实例，主动健康检查探测还可能破坏探测路径。这两个问题均已修复，故障转移和健康检查现在按配置工作。
• GraphQL Proxy Cache
  • 修复问题：在内存缓存增加 Vary 支持后，PURGE 请求只清除了旧的缓存槽，而保留了各 Vary 变体的缓存，因此在 TTL 过期前仍会返回过期响应。现在 PURGE 会清除所有变体。
• Body Transformer
  • 修复问题：XML 转 JSON 时会在部分 worker 进程上间歇性丢失带命名空间的 key，导致 SOAP 转换以 attempt to index field 'Body' (a nil value) 失败。现在带命名空间的 key 总能被保留。格式错误的 multipart 输入现在返回 HTTP 400 而不是 HTTP 500。
• Kafka Logger
  • 修复问题：由于无法配置 Kafka 生产 API 版本，broker 存储的消息没有可用的时间戳（显示为 1970-01-01）。将新增的 api_version 设为 2 可让 broker 记录真实的时间戳。
• Elasticsearch Logger
  • 修复问题：使用某些 {time_format} 占位符的动态索引名可能生成被破坏的索引名。现在无效的时间格式会回退为空值（并记录日志），而不是破坏索引名。
• AWS Lambda
  • 修复问题：使用 IAM（SigV4）认证时，查询字符串中包含需要转义的字符、多值或无值键会导致签名不匹配（InvalidSignatureException）。现在规范查询字符串按 SigV4 规范构建。
• Proxy Mirror
  • 修复问题：镜像 gRPC 请求时把内部 location 名称当作请求路径发送，导致镜像后端以 UNIMPLEMENTED 拒绝每次调用。现在镜像请求使用原始的 gRPC 方法路径。
• Request ID
  • 修复问题：当 algorithm 设为 nanoid 时，生成器会产生大量重复且格式错误的 ID，并且每生成一个 ID 就泄漏一个文件描述符。现已替换为基于 CSPRNG 的生成器；ID 格式不变，且 ID 现在唯一且格式正确。
• OPA
  • 修复问题：配置 send_headers_upstream 时，OPA 服务未返回的某个头会在发往上游的请求中保留客户端传入的值，而不是被清除。现在这类头会被清除。
• SAML Auth
  • 修复问题：调试日志被意外保持开启，且认证失败时可能放行请求而不是返回错误。现在已关闭调试模式，认证失败会返回明确的错误。
• CORS
  • 修复问题：当配置了 allow_origins_by_regex 时，没有 Origin 头的请求会返回 HTTP 500。现在这类请求会被正常处理而不报错。
• Multi Auth
  • 修复问题：当底层某个认证插件返回的状态没有错误信息时，插件返回 HTTP 500 而不是 HTTP 401。现在会返回 HTTP 401。
• DingTalk Auth
  • 修复问题：客户端可以传入伪造的 X-Userinfo 头并被转发到上游。插件现在会在认证前清除客户端传入的 X-Userinfo 头，确保上游只收到由插件校验的身份信息。
• Authz Casdoor
  • 修复问题：登录会话没有绑定到 Casdoor Token 的有效期，而是回退到会话库的默认值，导致会话可能比 Token 存活更久。现在会话会在 Casdoor Token 过期时一并过期。
• CAS Auth
  • 修复问题：单点登出的 POST 请求体为空时返回 HTTP 500 而不是 HTTP 400。现在空请求体的登出请求会被以 HTTP 400 拒绝。
• Limit Conn
  • 修复问题：由 NGINX 变量解析出的 burst 值为 0 时会被以 HTTP 500 拒绝，尽管静态的 burst 为 0 是合法的。现在变量解析出的 burst 为 0 会被接受。
• Limit Req
  • 修复问题：在并发压力下，由于读取和写入不是原子操作，基于 Redis 的限流可能被突破。现在限流通过单次原子操作执行。

数据面

• 修复问题：Redis 连接此前仅按地址做连接池，因此指向同一 Redis 服务器但使用不同数据库、凭据或 TLS 设置的两份插件配置可能复用彼此的连接——例如 limit-count、limit-req 或 limit-conn 的计数器可能被写到错误的 Redis 数据库。现在连接会按地址、数据库、凭据和 TLS 设置隔离，redis-sentinel 策略同样如此。
• 修复问题：当 set_header 使用与既有头不同的字母大小写调用后，缓存的头表会同时保留两个条目，导致遍历缓存头的插件（如 ext-plugin-post-resp）可能把过期的值转发到上游。现在缓存头的 key 会被规范化。
• 修复问题：当 workflow 插件运行在 global rule 中、而某个 route 插件在 rewrite 阶段就结束了请求（例如 CORS 预检）时，日志阶段会在每个这类请求上记录一条错误。现在缺少上下文时日志阶段会干净地提前返回。
• 修复问题：在启用 stream 子系统时启用 Nacos 服务发现，会因为 stream 子系统中未声明所需的共享字典而在启动时中止 stream worker；现在该字典已声明。另一个会把 Nacos 注册创建失败变成 worker 崩溃的错误处理缺陷也已修复。
• 修复问题：使用 Consul 服务发现时，单个格式错误的节点条目会导致该 service 其余节点被丢弃（甚至可能丢弃整个 service，产生 "no valid upstream node"）。现在只会跳过无效的那个节点。
• 修复问题：当 AWS Secrets Manager 的密钥名称包含斜杠时，解析会失败，因为查找在第一个斜杠处就做了切分。现在包含斜杠的密钥名称可以正确解析。
• 修复问题：Admin API 的 PATCH 会对已加密的插件字段重复加密，因此对任意字段做一次 PATCH 都可能损坏已存储的密钥（如 key-auth 的 key）。现在已加密字段会在合并前解密，并只重新加密一次。

开发者门户

• 修复问题：组织邀请未遵循邮箱验证设置。现在邀请会遵循所配置的邮箱验证行为。
• 修复问题：对于属于多个组织的开发者，门户可能使用错误的组织上下文。现在开发者身份会从当前激活的组织解析。
• 修复问题：门户中多处对话框宽度不一致；现已统一。

3.10.0

发布日期：2026-06-01

不兼容变更

插件

• HMAC Auth

  升级说明

  hmac-auth 插件现在将 signed_headers 默认设为 ["date"]。数据面升级后，任何未显式设置 signed_headers 的 hmac-auth 配置都要求客户端签名覆盖 Date 头。此前未对 Date 签名的客户端将开始收到 HTTP 401，错误信息为 client request can't be validated。

  升级前，请确保客户端对 Date 头签名，或在插件配置中显式设置 signed_headers 以匹配客户端实际签名的头。

控制面

• 移除 Service Template 与 API 发布机制

  升级说明

  Service Template / Service Hub 模型已被移除。Service 现在直接归属于 Gateway Group，并通过 APISIX Admin API 管理——不再有独立的模板、发布、版本、回滚和 runtime 配置层。在控制台中，Service Hub 区域被各 Gateway Group 下的 Services 列表取代。

  控制面升级到 3.10.0 时，既有的 service template 和 published service 会自动迁移到新的直连 service 模型。原始数据会被保留（不会删除），因此升级可以回滚。引用 service-template 或 published-service ARN 的 IAM 权限策略会被自动备份并重写。

开发者门户

• 仅对已发布的 API Product 强制开发者认证

  升级说明

  此前，处于**草稿（draft）状态的 API Product 也会把其开发者认证规则同步到网关，因此草稿产品下的 route 也会要求开发者认证。从 3.10.0 起，只有已发布（published）**的 API Product 才会向数据面下发开发者认证规则。

  升级后，属于草稿（未发布）API Product 的 route 在产品发布之前不再要求开发者认证。如果你依赖草稿产品被保护，请发布它们，或通过其他方式限制访问。

升级须知

升级说明 — 数据面 runtime 升级到 OpenResty 1.29

数据面网关 runtime 已从 OpenResty 1.21.4.4 升级到 OpenResty 1.29.2.4，并改为基于开源 apisix-runtime 构建。本次升级的主要目的是跨越多个大版本，引入上游 NGINX 内核、OpenSSL、LuaJIT 及内置依赖库的最新 安全修复。

大多数部署无需任何操作。一个可见的变化是：HTTP/2 现在通过 NGINX 1.25+ 的 http2 on; 指令启用，而不再使用 per-listen 的 http2 参数；HTTP/2 over cleartext（h2c）和 over TLS 仍照常工作。如果你维护了自定义的 NGINX 配置片段，请在升级前确认它们与较新版本的 NGINX 兼容。

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.10.0 的控制面会加密这些字段，而仍为 3.9.13 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• feishu-auth：secret_fallbacks
• dingtalk-auth：secret_fallbacks

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.10.0，并在两侧都升级到 3.10.0 之前避免编辑这些插件。

新功能

插件

• AI Proxy
  • 上游 LLM 请求体现在使用排序后的 key 进行 JSON 编码。这会为等价请求生成稳定、逐字节一致的请求体，从而提升按精确请求体缓存的 LLM 提供商的 prompt-cache 命中率。
• AI Proxy Multi
  • 当 LLM endpoint 域名解析到多个 A 记录时，插件现在会解析全部 A 记录并构建多节点 upstream，逐请求选择节点以获得更好的负载分布和故障转移。Host 头和 TLS SNI 保留原始域名，而不是解析出的 IP 地址。
• Proxy Cache
  • 内存缓存策略现在支持 Vary 响应头。响应会按 Vary 中列出的头计算出的变体分别缓存，Vary: * 的响应不会被缓存。
• CAS Auth
  • cas_callback_uri 现在支持绝对 URL，并原样用作 CAS service URL。当网关位于代理之后、对外可见的 callback URL 与请求路径不同时，这非常有用。

控制台（Dashboard）

• 新增权限策略语句的可视化编辑器。现在你可以通过选择资源类型、操作（标注了访问级别）和条件来构建 IAM 策略，无需手写策略 JSON。
• 配置兼容性告警现在会展示每个受影响资源的完整业务层级路径（例如 gateway group → service → route），而不是裸资源 ID，更便于定位需要处理的配置。

缺陷修复

插件

• Error Page
  • 修复问题：插件此前根据 upstream status 变量判断是否渲染自定义错误页，可能会替换掉真正来自上游服务的错误响应。现在插件会判定响应来源——只对网关或插件产生的错误（如上游连接失败或被插件拒绝的请求）渲染自定义错误页，而真正由上游返回的错误响应会原样透传，保留上游的原始响应体。
• Feishu Auth
  • 修复问题：客户端可以传入伪造的 X-Userinfo 头并被转发到上游。插件现在会在认证前清除客户端传入的 X-Userinfo 头，确保上游只收到由插件校验的身份信息。
• CAS Auth
  • 修复问题：登录回调未校验已签名的发起 cookie，使得构造的回调请求可以操纵登录后的跳转目标（CSRF / open-redirect）。回调现在要求携带有效的已签名发起 cookie，否则以 HTTP 401 拒绝。
• DingTalk Auth
  • 修复问题：认证失败与上游瞬时失败未做区分。插件现在对认证错误返回 HTTP 401，对 DingTalk 或上游的瞬时失败返回 HTTP 503，并提供更清晰的错误信息。
• Authz Casdoor
  • 修复问题：session cookie 名称在不同 Casdoor client 间共享，导致不同 client 的 session 可能冲突。session cookie 现在按 client（基于 client_id）隔离命名。
• Authz Keycloak
  • 修复问题：当静态 permissions 与 http_method_as_scope 同时使用时，派生出的方法 scope 会被写回复用的插件配置，导致 scope 跨请求累积。现在会在追加方法 scope 之前先克隆 permission 列表。
• GraphQL Limit Count
  • 修复问题：查询嵌套深度计算有误，导致基于深度的限流不准确。现在深度会按真实最大嵌套深度并展开 fragment 计算。Content-Type 匹配也容忍 charset 参数（如 application/json; charset=utf-8），此前这类请求会被拒绝。
• GraphQL Proxy Cache
  • 修复问题：Content-Type 带 charset 参数的请求未被识别为 GraphQL 请求。Content-Type 匹配现在容忍 charset，同时增加了 nil 守卫、更清晰的错误信息并修正了日志级别。

数据面

• 修复问题：当同一请求上有多个日志插件抓取响应体时（例如 http-logger 和 file-logger 都启用了 include_resp_body），它们的响应体缓冲区可能相互干扰，产生截断或混杂的日志输出。现在每个 logger 使用独立的缓冲区。

3.9.21

发布日期：2026-09-24

不兼容变更

插件

• OpenID Connect

  升级说明

  通过远程 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.9.20 上，introspection 路径不会应用这份白名单，这样的 Token 会被转发到上游。

  升级前，请检查所有同时配置了 introspection_endpoint 和 claim_validator.issuer.valid_issuers 的 openid-connect 路由，确认身份提供方的 introspection 响应中带有位于白名单内的 iss。

• SAML Auth

  升级说明

  数据面现在会按照 SAML 规范的要求校验 SAML 响应，且无需任何新增配置。出现以下任一情况时，登录会被拒绝：断言带有 AudienceRestriction，但其中没有列出本服务提供方（未设置 sp_audiences 时即 sp_issuer）；断言的使用时间超出其 NotBefore 与 NotOnOrAfter 窗口 60 秒以上；断言的 Recipient，或响应的 Destination，与本服务提供方的断言消费服务（ACS）URL 不一致；断言对应的登录请求并非当前会话发起的那一个。此外，身份信息现在只会从已验证签名覆盖的断言中读取。在 3.9.20 上，以上各项都不会被检查。

  未设置 sp_acs_url 时，ACS URL 由回调请求的协议和主机拼出。如果网关部署在终止 TLS 却不设置 X-Forwarded-Proto、或会改写主机名的负载均衡器或 Ingress 之后，网关拼出的 URL 就会与身份提供方写入 Recipient 的 URL 不一致，升级后所有登录都会被拒绝。

  升级数据面前，请为部署在此类代理之后的路由把 sp_acs_url 设置为对外的回调 URL；如果身份提供方签发断言时使用的受众不是 sp_issuer，请设置 sp_audiences；并确保网关的时钟已同步。网关实例升级时正在进行中的登录会重新开始，而不会被拒绝。

• batch-requests

  升级说明

  在 3.9.14 引入的子请求数量上限之外，该插件现在还会限制其聚合的响应体大小。单个子响应超过 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.9.20 上，这两项限制都不存在，每个子响应体都会被完整缓存。

  两项限制都是 batch-requests 插件元数据的配置项。如果业务依赖批量获取大响应，请在升级数据面前调大这两个值。

• Workflow

  升级说明

  每条规则的 actions 现在必须恰好包含一个 [name, conf]。带有多余元素的动作和包含多个动作的规则，在 3.9.20 上会被接受、存储并正常运行。控制面现在会拒绝这两种形状，返回 HTTP 400 和指明问题的消息，例如 invalid workflow plugin: invalid action: expected [name, conf] 或 workflow plugin: rules.0.actions: Array must have at most 1 items。

  升级前已存储的这两种形状的 workflow 配置，在其网关实例升级后会成为配置兼容性报告中的 error 级别条目，需要先改正才能再次编辑。

升级须知

升级说明 — 控制面镜像不再包含 Node.js

Dashboard 控制台现在由控制面二进制程序直接提供。api7-ee-3-integrated 镜像只运行一个进程，镜像中既没有 Node.js 也没有 shell，不再监听 3000 端口，也不再读取 dashboard_configuration.console.addr 配置项。

本版本离线安装包中的 docker-compose.yaml 已经相应更新。如果您使用自己的 compose 文件或清单启动控制面，并且其中以 /nodejs/bin/node /app/server.js & /usr/local/api7/api7-ee-dashboard -c /usr/local/api7/conf/conf.yaml 作为启动命令，或者用 /nodejs/bin/node 做健康检查，升级后容器将无法启动或被判定为不健康。请把启动命令改为只传入 -c /usr/local/api7/conf/conf.yaml，把健康检查改为 /usr/local/api7/api7-ee-dashboard healthz，并删除 console.addr 配置以及对 3000 端口的暴露。使用 Helm chart 部署的环境无需修改 values。

新功能

插件

• 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 服务都属于这种情况。
• Prometheus
  • 以 101 Switching Protocols 应答的请求现在被归类为 request_type=websocket，因此 WebSocket 会话会落到各自独立的 apisix_http_status、apisix_http_latency 和 apisix_bandwidth 时间序列中，可以用 request_type!="websocket" 把它们排除在延迟查询之外。普通请求的时间序列保持不变，握手被拒绝的请求仍然是 traditional_http。如果你的仪表盘或告警规则在聚合这些指标时没有按 request_type 过滤，将会看到 WebSocket 流量从原先所在的序列中被分离出去。

控制面

• 离线安装包现在包含 api7/openapi-to-mcp 边车镜像，因此在离线环境中也可以使用 openapi-to-mcp 和 mcp-tools-acl 插件。run.sh start 会加载该镜像；边车仍需在网关旁、与网关处于同一网络命名空间中启动。

控制台（Dashboard）

• 服务、路由、Stream 路由、消费者和全局规则上的插件卡片新增了启用/禁用开关，插件编辑器中也有同样的开关。禁用插件会保留其配置，并让网关不再执行它。此前需要手动编辑 _meta.disable 才能做到。
• 控制面版本号显示在侧边菜单底部的页脚中，点击即可复制。
• License 页面会显示部署 ID，并提供复制按钮。
• 通过 ADC 同步的资源（带有 managed-by: adc 标签）会在详情页上显示 Managed by ADC 标记和提示横幅，编辑或删除这类资源前会先要求确认，以免误做会在 ADC 下次同步时被覆盖的修改。
• Dashboard 新增繁体中文和越南语界面。此前选择中文的用户会继续使用简体中文。

缺陷修复

插件

• AI Rate Limiting
  • 修复问题：使用 redis-sentinel 策略时，redis_username 和 redis_password 没有被传递下去，因此对于需要认证的 Redis，尽管配置可以保存，限流仍会在运行时失败。使用 redis 和 redis-cluster 策略时，redis_keepalive_timeout 和 redis_keepalive_pool 会被忽略，始终使用内置值。
• AI Aliyun Content Moderation
  • 修复问题：流式返回的模型响应不带 usage 字段时，最终的审核检查会被跳过，客户端收到的回答不带任何审核结果。如果响应结束时也没有 [DONE] 事件，客户端就一直收不到它。现在最终检查总会执行并报告结果，上游未发送 [DONE] 时由网关补发。
• AI Proxy
  • 修复问题：周期性刷新时如果没有新内容可发送，流式响应可能被提前截断，并被记录为客户端断开。SSE 事件被拆分到多次读取中，或者有插件缓存响应体时，都可能出现这种情况。
• feishu-auth 和 dingtalk-auth
  • 修复问题：授权码没有绑定到发起登录的浏览器会话，因此从别处获得的授权码在任何出示它的会话上都会被接受（登录 CSRF）。现在跳转到身份提供方时会携带一个随机的 state，回调中 state 缺失或与会话不匹配时，请求会被拒绝，返回 HTTP 401 和 {"message":"Invalid state"}。网关实例升级时正在进行中的登录需要重新开始。自行获取授权码的集成应通过 X-Feishu-Code 或 X-DingTalk-Code 请求头传入授权码，该方式的处理与之前相同。
• Prometheus
  • 修复问题：指标库 nginx-lua-prometheus-api7 在 3.9.18 中进行了升级。在 3.9.18、3.9.19 和 3.9.20 上，如果在网关配置文件的 plugin_attr.prometheus.metrics 下为指标设置了 expire，该指标库可能导致网关 worker 出现 CPU 突刺。为避免这一问题，本版本将指标库回滚到 3.9.15 及更早版本所用的版本。expire 选项仍然生效，无需修改任何配置。

数据面

• 修复问题：开启 apisix.normalize_uri_like_servlet 后，发往上游的请求与参与路由匹配的请求不一致。路径中百分号编码的 ?（%3F）会被解码，导致其后的内容全部变成查询字符串；客户端自己的查询字符串会被丢弃；服务的 strip_path_prefix 会被忽略，上游收到的路径仍带着前缀。
• 修复问题：引用了数据面上不存在的插件（例如未对该网关组启用的自定义插件）的 Stream 路由会被整条丢弃，导致该路由停止服务。现在会跳过该插件，路由继续工作，与 HTTP 路由原有的行为一致。
• 修复问题：配置兼容性报告不包含 Stream 路由，因此即使某些 Stream 路由的配置无效或引用了不可用的插件，网关实例仍可能被报告为没有问题。现在 Stream 路由会像其他资源一样被报告。
• 修复问题：网关启动过程中写入的配置变更可能丢失且没有任何报错，因为配置监听可能从错误的 revision 开始，或者在 etcd 可达之前就已启动。受影响的 worker 会一直运行旧配置，直到同一资源再次被修改。

控制面

• 修复问题：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。反过来，选择集为空的查询网关可以运行，现在也会被接受。

控制台（Dashboard）

• 修复问题：在每页条数不是默认值的列表中，从第二页开始，Results: X–Y of N 显示的范围是错误的。列出的数据本身是正确的。
• 修复问题：在调试会话的链路视图中，每个跨度名称前都带着同一个服务名前缀，且跨度名称列无法调宽。现在去掉了该前缀，列宽可以调整，服务名仍会显示在跨度详情中。
• 修复问题：在 API 产品的详情页上，最后一个关联的网关服务可以被删除，导致该产品没有任何后端。现在它的删除按钮会被禁用，并通过提示说明原因。
• 修复问题：较长的错误消息会溢出通知框。现在通知框宽度统一，较长的消息可以滚动查看。

3.9.20

发布日期：2026-09-03

不兼容变更

插件

• Basic Auth

  升级说明

  Basic Auth 的密码不能再为空。控制面现在会拒绝密码为空字符串的消费者或凭据，返回 HTTP 400 和 basic-auth plugin: password: String length must be greater than or equal to 1。在 3.9.19 上，同样的请求会返回 HTTP 200 并被存储下来。

  升级后，已存储的空密码消费者会在配置兼容性报告中变成一条 error 级别的条目，并且对它的任何后续修改都会被拒绝，直到设置了密码为止。

  数据面现在同样按失败关闭处理：解析结果为空字符串的密码（包括解析结果为 "" 的 $env:// 或 $secret:// 引用）会被拒绝，返回 HTTP 401 并在错误日志中记录一条 warning。在 3.9.19 上，这样的消费者用「用户名 + 冒号 + 一个空格」这样的凭据即可认证成功。

  升级前请检查是否存在密码为空、或密钥引用解析结果为空的 Basic Auth 消费者和凭据，并为它们分别设置真实的密码。

升级须知

升级说明 — 按问题分组的兼容性报告和忽略规则需要数据面同步升级

兼容性报告现在按问题分组，忽略规则则按数据面上报的机器可读 reason 进行匹配。两者都依赖数据面以结构化数据的形式上报兼容性问题，而这是 3.9.20 才有的能力。API7 企业版的升级顺序是先控制面、后数据面，因此在升级窗口内，3.9.20 的控制面面对的是仍运行 3.9.19 的网关实例，对这些实例来说两个能力都不生效。

旧版数据面把每个问题上报为一句渲染好的英文句子，其中不含机器可读的 reason。控制面在心跳到达时就会丢弃这类记录，因此只要控制面已升级而网关实例尚未升级，该实例的兼容性报告就是空的。实例上真实存在的问题——被数据面拒绝的资源、数据面没有的插件——都不会展示出来，忽略规则也没有任何可作用的对象。请预期这段时间内报告是空白而非可信的，不要把空白的报告当作没有问题。

实例本身仍会由版本规则标记为需要升级，因此不会悄无声息地显示为已是最新。这只影响兼容性报告的展示。它不会影响流量，也不会影响网关实例实际运行的配置；网关实例升级完成后，报告即恢复为文档描述的行为。

新功能

插件

• Chaitin WAF
  • 现在可以在上报请求的同时把响应一并上报给长亭雷池（SafeLine）检测服务，这样响应体中泄露的数据、漏洞利用的输出，或者异常的状态码都能被雷池看到。插件和插件元数据上都提供了三个配置项：config.log_resp 开启响应上报，config.resp_body_size 以 KB 为单位限制上报的响应体大小（0 表示只上报响应头），config.extra_ignored_content_types 在内置忽略列表之外，以逗号分隔追加需要跳过的响应 content type。响应上报默认关闭。上报发生在响应已经返回给客户端之后，且仅供参考：它不会阻断也不会修改响应。
• 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]。

控制面

• 网关实例的配置兼容性报告现在按问题组织，而不是按资源组织。GET /api/gateway_groups/{gateway_group_id}/instances/{gateway_instance_id}/compatibility_issues 为每一个不同的问题返回一个条目——包含机器可读的 reason（resource_invalid、plugin_unavailable、plugin_config_invalid、plugin_unknown_fields）、它所涉及的插件和字段，以及携带该问题的资源列表——并按错误优先、其次按受影响资源数量排序。数据面现在以结构化数据上报每个问题，而不是为每个资源渲染一句英文，因此同一个原因不会再在成千上万行里重复出现，未识别字段的告警也不会再被聚合后的错误淹没。
• 运维人员现在可以忽略某个数据面不识别但会安全跳过的插件字段，让兼容性报告只列出真正需要处理的内容。一条忽略配置指定插件和字段，对所有网关组和实例生效，并覆盖数组中的每一个元素——忽略 nodes[*].weight 即覆盖全部元素。忽略配置既可以在 Dashboard 中管理，也可以通过 /api/compatibility_dismiss_rules 接口管理，它们有自己的权限控制，每一次变更都会记入审计日志。只有未识别字段的告警可以被忽略：忽略其中一条告警既不会改变数据面对配置的处理方式，也不会把 Incompatible 的实例变成 Compatible。
• 现在可以按域名或路径前缀查找服务。服务列表接口的 search 参数除了名称、描述、标签和 ID 之外，还会不区分大小写地匹配服务 hosts 或 path_prefix 的任意子串；以空白字符分隔的多个词仍然是 AND 语义。此前，只知道服务域名或路径前缀的用户没有任何办法把它找出来。路径前缀记录在本次新增的列中，升级过程会为所有存量服务回填该列，因此升级前发布的服务无需重新发布即可按路径前缀搜索。

控制台（Dashboard）

• 配置兼容性告警现在会展示每个受影响资源的完整业务层级路径（例如 gateway group → service → route），而不是裸资源 ID，更便于定位需要处理的配置。

缺陷修复

插件

• Basic Auth
  • 修复问题：密码中包含冒号的消费者永远无法通过认证。RFC 7617 规定第一个冒号之后的全部内容都是密码，但此前的实现按每一个冒号切分凭据，把密码截断了。
  • 修复问题：密码为空的消费者——无论是直接存成空字符串，还是由 $env:// 或 $secret:// 引用解析出空值——会让任何携带其用户名和空密码的请求通过认证。现在这样的消费者会被拒绝，返回 HTTP 401，并且空密码也无法再被配置。升级前需要检查的内容请参见不兼容变更。
• 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——请求根本没有被发出去。现在模型名会被转义成单个路径段。
• 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，看不出任何原因。

数据面

• 修复问题：数据面 control API 的 GET /v1/healthcheck 在本应返回数组的位置返回了空 JSON 对象——配置了 checks 但尚未被使用的上游返回 "nodes": {}，没有任何健康检查在运行时整个结果返回 {}。两者现在都返回 []。

控制面

• 修复问题：查询网关实例时既没有带上它所属的网关组，也没有对它的运行记录排序，因此重启过的实例会被一条已经不存在的运行记录代为回答，且这种情况最长可以持续七天。兼容性问题接口返回的报告与同一屏上并排展示的摘要相互矛盾，并且永远不会收敛；删除网关实例时，可能会因为一条过期的运行记录而放行离线校验，从而删掉一个仍然在线、仍然返回 HTTP 200 的网关；此外，当同一个实例 ID 同时存在于两个网关组时，数据面上报的健康检查状态可能被归到错误的网关组下。
• 修复问题：服务的类型只在服务创建时被记录下来用于过滤，更新服务时从不更新，因此服务在 http 和 stream 之间迁移之后，?type= 过滤用的仍然是创建时的取值。
• 修复问题：当 Prometheus 返回给控制面的内容不是 JSON 时（例如带认证的代理返回了一个 HTML 的 401 页面），Dashboard 的监控页面和开发者门户的指标接口会以 HTTP 500 和 invalid character '<' looking for beginning of value 失败，完全看不出真正的原因。现在这类响应会被报告为 HTTP 502，消息中给出上游的状态，例如 prometheus returned 401 Unauthorized，响应体的前 256 字节会记入控制面日志而不是返回给客户端。Prometheus 自身返回的 JSON 错误响应仍然原样透传。

3.9.19

发布日期：2026-08-26

升级须知

升级说明 — 访问日志格式中的 $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 变量读取。

升级说明 — 日志插件在待处理条目达到 8192 时开始丢弃

除非在插件元数据中设置了 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 会真正执行所配置的鉴权校验

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 拒绝同名的 instance

AI Proxy Multi 此前接受两个 name 相同的 instance，这会让请求实际路由到哪个 instance 变得不确定。此类配置现在在写入时就以 HTTP 400 拒绝。

已经存储的配置仍可继续工作，但升级后会在数据面的配置兼容性报告中以 error 级别出现。请重命名重复的 instance 使每个名字唯一，配置被重新写入后该报告项即消失。

升级说明 — Proxy Cache 的内存缓存条目在升级后会重新回源一次

为修复下文「缺陷修复」中描述的变体键碰撞问题，Proxy Cache 在 memory 策略下的存储键布局发生了变化，缓存版本号也随之提升。因此旧版本写入的条目在新布局下不可达：每个键的第一次请求为 MISS 并重新填充缓存，而对只有升级前条目的 URL 执行 PURGE 会返回 HTTP 404。旧条目会一直留在共享内存中，直到各自的 TTL 到期。使用默认 disk 策略的部署不受影响。

新功能

插件

• 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 重试。

控制面

• 路由现在可以匹配 PURGE 方法，Proxy Cache 和 GraphQL Proxy Cache 正是用它来失效缓存条目的。网关一直接受该方法，只有控制台自身的 schema 拒绝它，因此此前无法通过接口或控制台创建用于缓存失效的路由。
• 上游与路由的超时现在接受小数秒，可以配置 0.5，而此前接口要求整数。数据面一直支持亚秒级超时。最小值为 0.001，因为低于一毫秒的部分会被截断。

数据面

• 请求携带的 X-Forwarded-* 请求头改由 NGINX 配置消毒，不再由 Lua 在每个请求上处理。插件看到的值与此前一致，而客户端发送的原始值——在 Lua 中一直可以通过 ctx.var.original_x_forwarded_* 读取——现在也成为 NGINX 变量，可以写进日志格式。唯一发生变化的记录位置参见「升级须知」。

缺陷修复

插件

• GraphQL Limit Count
  • 修复问题：当 GraphQL 文档中的片段相互展开时，每次被引用都会重新展开一次，因此很小的请求体也可能消耗不受限的 CPU。一个含 34 层链式片段的 1.4 KB 文档可以让 worker 满载运行超过 45 秒，期间网关在所有路由上都不返回任何响应，必须重启才能恢复。现在每个片段只计算一次，片段展开形成环的文档会以 HTTP 400 拒绝。
• AI Proxy
  • 修复问题：当流式上游返回 HTTP 200 和 Content-Type: text/event-stream 后不写入任何内容就结束响应时，请求既没有被应答也没有被终止，客户端因此完全收不到 HTTP 响应，访问日志记录为长度为零的 500。现在返回 HTTP 502。
  • 修复问题：流式上游在中途失败时——已经有部分流内容送达客户端之后连接断开或超时——网关仍会试图在一个已经以 HTTP 200 提交的响应上返回 HTTP 500 或 504。它会记录 attempt to set ngx.status after sending out response headers，把已损坏的连接放回 keepalive 连接池，并且在 AI Proxy Multi 上把这次失败当作可重试，在客户端已经收到部分回答之后再向下一个 instance 发出一次计费的请求。现在流会在读取失败处结束，不再合成终止事件，客户端可以据此从缺失的 [DONE]、message_stop 或 response.completed 判断响应被截断。在第一个字节送达客户端之前发生的读取错误行为不变：超时仍返回 504，其余情况仍返回 500，并且仍可触发回退。
• AI Proxy Multi
  • 修复问题：请求重试到下一个 instance 时，使用的是上一次尝试已经改写过的请求体，因此上一个 instance 的 options（例如 temperature 或 max_tokens）会泄漏到发往回退 instance 的请求中，模型名也可能被覆盖。现在每次尝试都从客户端自己的请求体开始构建。
• AI AWS Content Moderation 与 AI Aliyun Content Moderation
  • 修复问题：当流是被网关自身截断时——AI Proxy 的 max_response_bytes 或 max_stream_duration_ms 达到上限——这两个插件仍会在它们重新编码并下发的流上补出协议的完成事件。客户端收到一个格式完整的 [DONE]，无从得知内容已被丢弃，因此被截断的回答与完整回答无法区分：实测中曾出现丢弃 9 条事件中的 7 条、终止符照发的情况。现在对被中止的流不再合成终止符。
• 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 校验并非在所有情况下都生效，导致本应被配置拒绝的请求被放行。参见「升级须知」。
• HMAC Auth
  • 修复问题：启用 hide_credentials 时，Authorization 请求头虽然从发往上游的请求中移除了，却仍留在缓存的请求头中，因此同一路由上排在 HMAC Auth 之后的插件仍能读到该签名凭据。
• UA Restriction
  • 修复问题：请求携带多个 User-Agent 请求头时，denylist 的判定结果被反转。用户代理在拒绝列表中的客户端只要把该请求头发送两次就能通过，而第一个用户代理不匹配列表中任何一项的请求反而会被以 HTTP 403 拒绝。只携带一个 User-Agent 请求头的请求，以及 allowlist 模式，不受影响。
• AWS Lambda
  • 修复问题：以 Transfer-Encoding: chunked 发送的请求体在转发给函数时未重新分帧，导致调用失败，客户端收到 HTTP 503，错误日志中出现 failed to process aws-lambda, err: closed。现在转发时会携带 Content-Length。共用该代码路径的其他 serverless 上游插件同样适用。

数据面

• 修复问题：解析作为 CNAME 的上游主机时，只有当应答的最后一条记录恰好是所请求的类型时，解析结果才会被折叠到被查询的名字上。解析器附加 EDNS(0) OPT 记录、或应答段未按链的顺序返回，都会使这一判断失效，于是解析到的记录被记在规范名而不是被查询的名字下——并且一条属于无关名字的同类型记录可能被改记到被查询的名字上并缓存。现在会沿链走到它最终指向的名字，只折叠该名字拥有的记录。
• 修复问题：网关会把刚刚从 conf/apisix.uid 读出的实例 ID 再写回该文件。对于以运行用户不可写的方式挂载该文件的部署——Docker Compose 部署包正是这样——因此每次启动都会以 error 级别记录 failed to open file [/usr/local/apisix//conf/apisix.uid] for writing——在 3.9.18 上是 4 条，配置了 apisix.stream_proxy 时是 6 条。实例 ID 一直都能被正确读取并用于注册；现在去掉的是这次多余的写入以及它产生的错误日志。

控制面

• 修复问题：任何已登录用户都能列出某个服务的上游（包括节点地址），因为列出上游的端点没有任何权限校验，而同一份数据的其他视图都按权限过滤。现在列出服务的上游需要该服务的查看权限。
• 修复问题：为同一个 SNI 同时配置 cert/key 和 certs/keys 的 SSL 配置（即 RSA 与 ECDSA 证书并存的常见形态）会被以 input matches more than one oneOf schemas 拒绝。现在两者可以一起使用，数据面会按客户端偏好协商相应的证书。
• 修复问题：使用非对称算法的 jwt-auth 消费者凭据在写入配置存储时会带上一个用户从未配置过的占位 private_key 字段，数据面将其报告为无法识别的字段，且该字段以明文存储。现在不再添加该字段。升级前写入的凭据会保留该字段，直到下一次被保存。
• 修复问题：运行仅数据面热修复版本的网关实例——例如 3.9.18-patch.1 这种不随附控制面版本发布的版本——会被判定为 PartiallyCompatible 并在版本旁给出 Upgrade Recommended 提示，尽管它比控制面更新；而同一网关组中运行基线版本的另一个实例则被判定为 Compatible。此外，其兼容性报告中出现 error 级别条目时会把该实例变为 Incompatible，并触发提示升级网关的横幅。现在，只在预发布部分与控制面版本不同的版本，会按它所基于的发布版本来判定。

控制台（Dashboard）

• 修复问题：在同一个页面会话中重复打开 YAML 模式的插件编辑器，会使补全列表中的每个字段按打开次数重复，打开五次后每个字段出现五次。现在编辑器的 YAML 支持在每个页面只配置一次。

3.9.18

发布日期：2026-08-12

不兼容变更

插件

• 阿里云日志服务（SLS）

  升级说明

  该插件现在会校验日志服务器的 TLS 证书。旧版本在完成 TLS 握手时完全不校验证书，因此日志服务器出示自签名证书、私有 CA 签发的证书或已过期的证书都会被静默接受，而携带所配置访问密钥的日志记录仍会发往该服务器。

  校验行为由新增的 ssl_verify 选项控制，默认值为 true。升级后，若网关无法校验日志服务器的证书，批处理器会丢弃这批日志，并在错误日志中记录 failed to perform TLS handshake to TCP server。如果你的日志服务器出示的证书并非由公共可信 CA 签发，请在升级前把签发该证书的 CA 加入数据面的可信证书库，或在插件上把 ssl_verify 设为 false 以保持旧行为。

升级须知

升级说明 — Loki Logger 的 headers 字段落盘加密

在启用数据面数据加密（apisix.data_encryption.enable）时，控制面现在会对 Loki Logger 的 headers 字段做落盘加密。由于 API7 EE 的升级顺序是先控制面、后数据面，在升级窗口内 3.9.18 的控制面会加密该字段，而仍为 3.9.17 的数据面无法解密，可能导致该插件在数据面升级完成前无法正常工作。

如果你使用了 Loki Logger 的 headers，请在控制面升级后尽快把数据面也升级到 3.9.18，并在两侧都升级完成前避免编辑该插件。

升级说明 — 升级后所有控制台用户需要重新登录一次

控制台会话 Cookie 的签名密钥此前是编译期常量，所有部署完全相同。现在改为首次启动时生成的 32 字节随机密钥，并按部署持久化保存，因此会话 Cookie 不再可能用一个各处相同的值签发。

升级前签发的会话使用的是旧的常量密钥，升级后不再被接受。控制面升级完成后，所有已登录用户都需要重新登录一次。升级前无需做任何准备，也不需要修改配置。

升级说明 — Docker Compose 部署改用 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。

新功能

插件

• 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 随推送请求一并发送。
• 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；控制台会读取其中的元数据自动填充插件的分类、描述、文档链接和作者。整个包作为一个整体下发到数据面，因此不会出现插件只发布了部分文件的情况；更新时所有文件一并替换，且无需重启网关。
• Docker Compose 部署包新增 portal.sh，用于在已运行的部署上启动开发者门户。该脚本会创建门户实例及其 Token、写入前端配置与数据库，并以 Compose profile 的方式启动前端，因此试用门户不再需要按手册逐步手工操作。执行 portal.sh stop 后再 start，开发者账号与会话都会保留。

数据面

• 全局规则筛选出的插件集现在每个请求只计算一次并跨阶段复用，而不是在每个阶段中重复计算。在通过全局规则启用 Prometheus 插件的部署上，单个 Worker 实测吞吐提升 12%。

控制台（Dashboard）

• 语言切换器不再显示与语言并不对应的国旗图标，并会标出当前生效的语言。

缺陷修复

插件

• 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。
• 修复问题：产品内的多个帮助链接指向已冻结的文档归档，而不是当前的文档集。

3.9.17

发布日期：2026-07-28

升级须知

升级说明 — Logger 请求/响应体大小上限校验更严格

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 结构性指标标签不再允许禁用

Prometheus 插件元数据现在会拒绝那些会移除指标赖以成立的标签的 disabled_labels 配置——例如 latency 的 type，或 status 的 code。旧版本接受这类配置，导致本应区分的多组测量值被合并成同一条指标序列。

如果你的 Prometheus 插件元数据禁用了这类标签，升级后对它的任何更新都会被拒绝并返回 HTTP 400。请在升级前把这些结构性条目从 disabled_labels 中移除。route、service、consumer 等非结构性标签仍然可以禁用。

升级说明 — OpenTelemetry 元数据与内容审查 deny_code 校验更严格

另有两处 schema 现在会拒绝旧版本接受过的值：

• OpenTelemetry 插件元数据的 resource 属性和 collector.request_headers 只接受标量值——字符串、数字和布尔值。旧版本接受但会在运行时静默丢弃的数组和对象，现在会被拒绝并返回 HTTP 400。
• AI Aliyun Content Moderation 的 deny_code 必须是 200–599 范围内的整数 HTTP 状态码。AI AWS Content Moderation 在控制面侧此前就已按此校验，本次发布使数据面与之保持一致。

升级后，带这类值的已有配置会在网关组的兼容性报告中被报告为错误，对其进行的任何更新都会被拒绝并返回 HTTP 400。网关实例仍保持 Healthy，流量不受影响。升级前请检查 OpenTelemetry 插件元数据以及 AI Aliyun Content Moderation 的配置，替换或删除不符合要求的值。

新功能

插件

• 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），方便运营者调整空闲超时时间和连接池大小。
• 需要缓冲请求/响应体的插件
  • 新增 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——使这两个上限在配置时被校验并在控制台中展示（参见「升级须知」）。

数据面

• 新增 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/https URL 的菜单项会被丢弃，不会下发给控制台。
• 服务冲突检测现在会计入路由的 methods。同一 host 和 path 下方法集合互不相交的路由（例如 GET /foo 和 POST /foo）不再被判为冲突；方法范围完全相同判为 duplicate，部分重叠判为 overlapping。未配置 methods 的路由仍然匹配所有方法。
• 新增可选的出站 SSRF 防护。开启 security.ssrf_protection.enable 后，控制面会拒绝连接环回地址、私网地址、链路本地地址和运营商级 NAT 地址——包括解析后落到这些网段的主机名——从而防止服务注册中心、SMTP 设置等功能被用来探测内网服务或云元数据端点。

控制台（Dashboard）

• 服务与路由的冲突提示弹窗新增 Methods 列，便于判断两条路由在哪些方法上发生冲突。未配置 methods 的路由显示为 All。

缺陷修复

插件

• AI Proxy、AI Proxy Multi 和 AI Request Rewrite
  • 修复问题：网关发往 LLM 服务商的请求会携带客户端自身的请求头，包括 Cookie、Authorization 以及任意自定义头，导致最终用户的凭证泄漏给上游服务商。现在网关只发送插件自身设置的请求头。
  • 修复问题：当 LLM 返回错误响应时，$apisix_upstream_response_time 和 $llm_time_to_first_token 记录的是秒（例如 0.240）或 0，而成功响应记录的是毫秒。现在错误路径也统一以毫秒上报，与成功路径一致。
• AI AWS Content Moderation 和 AI Aliyun Content Moderation
  • 修复问题：deny_code 此前接受任意数字。现在会校验为 200–599 范围内的整数 HTTP 状态码（默认 200），超出范围的值会在配置时被拒绝。其中 ai-aws-content-moderation 的该校验此前已在控制面生效，本次发布使数据面与之对齐；ai-aliyun-content-moderation 则是控制面与数据面同时启用该校验。
• OpenID Connect
  • 修复问题：收到 state 与当前会话不匹配的授权回调时——例如在同一浏览器中先后发起了两个登录流程——会返回 HTTP 500。现在网关改为重定向到最初请求的页面。
  • 修复问题：身份提供商 userinfo 中的空 JSON 数组（例如 "roles": []）在复用已有会话的请求中会被重新编码为空对象（{}）写入 X-Userinfo 头，导致按数组解析该字段的上游服务出错。现在空数组仍然是数组。
• wolf-rbac
  • 修复问题：当鉴权服务返回成功但不带 userInfo 时，客户端自己传入的 X-UserId、X-Username、X-Nickname 请求头会被透传给上游服务，使调用方可以伪装成任意身份。现在这些请求头在转发前总是被清除。
• Limit Count
  • 修复问题：在 window_type: sliding 且开启延迟同步时，剩余配额的计算没有按滑动窗口加权，导致窗口边界附近放行的请求明显多于配置值。现在剩余计数按窗口加权计算。
• Limit Conn 和 Limit Req
  • 修复问题：Redis 连接没有归还到 keepalive 连接池，导致每个请求都新建一条 Redis 连接，已配置的 keepalive 参数完全不生效。现在连接会被正确复用。
• Prometheus
  • 修复问题：当指标使用的共享内存字典写满时，网关可能进入死循环，把某个 worker 的 CPU 占用拉满至 100%，且在流量停止后也不会恢复。现在字典写满会优雅降级，并记录「上报的指标数据可能不完整」的日志。
• OpenTelemetry
  • 修复问题：插件元数据 schema 接受 resource 属性和 collector.request_headers 的非标量值，这些值随后会在运行时被静默丢弃。现在这类值会在配置时被拒绝。

数据面

• 修复问题：使用 least_conn 负载均衡时，增删上游节点会丢弃已记录的连接数，导致算法退化为轮询，把新请求发给已经持有长连接的节点。现在负载状态会在上游扩缩容期间保留。
• 修复问题：当插件字段引用的密钥无法解析时——例如环境变量未设置，或密钥管理器返回错误——失败是静默的，未解析的引用会被当作字面值使用。现在网关会记录错误日志，指明具体的引用和所在字段。
• 修复问题：网关通过执行 /bin/hostname 获取主机名，因此在不包含该二进制的镜像上无法上报主机名，网关实例在控制台中显示为没有主机名。现在改为通过系统调用获取。
• 修复问题：nginx_config.envs 中值包含空格、引号或反斜杠的条目会生成非法的 NGINX 配置，导致网关启动失败。现在这些值会被正确地加引号和转义。
• 修复问题：通过 CLI 停止网关后立即启动可能失败，因为上一个实例尚未完全退出。现在 CLI 会等待其停止后再启动新实例。
• 修复问题：网关容器被强制杀死（而非正常关闭）后，残留的 worker event socket 可能导致下次启动无法绑定。现在启动时会先清理这些残留文件。
• 修复问题：在 arm64 架构上，某个依赖会把第二份 JSON 库拉入网关的模块搜索路径，遮蔽内置版本并把空数组编码成非法 JSON。现在已移除该冗余依赖，始终使用内置库。

控制面

• 修复问题：针对同一资源的两个并发 PATCH 请求可能各自在对方写入前读取资源，导致只有最后一次写入生效，而两个请求都返回成功。现在同一资源上的 PATCH 请求会被串行化。
• 修复问题：数据库连接池中的连接会被无限期复用，因此数据库发生主备切换后，控制面可能继续使用绑定在已被降级为只读的旧主库上的连接。现在连接生命周期默认限制为 1 小时，并可通过 database.max_lifetime 调整。
• 修复问题：导入证书链已过期的 License 时，报错信息为 license certificate comes from an invalid issuer，指向签发机构而不是过期本身。现在证书链已过期或尚未生效会返回带有相应时间戳的专门提示。确实来自未知签发机构的证书仍然报告 issuer 非法。
• 修复问题：当前数据面核数统计包含了已停止上报心跳的实例——这些实例在被标记为离线前会在 LostConnection 状态停留最长两小时——因此数据面缩容或崩溃后很久，控制台上的核数用量仍然偏高。现在只统计处于标准运行模式的已连接实例。基于心跳用量计算的 License 计费不受影响。

控制台（Dashboard）

• 修复问题：路由 path 列表和服务 host 列表允许添加超过 schema 限制（64 条 path、32 个 host）的条目。此时新建资源会返回原始的服务端错误，而编辑资源则可能存下随后被 adc validate 和 adc sync 拒绝的配置。现在列表达到上限后会隐藏 Add 控件；已经超出上限的列表仍会完整展示所有条目，便于删除多余项。

3.9.16

发布日期：2026-07-10

升级须知

升级说明 — 网关默认内存占用升高（Helm）

3.9.16 Helm chart 调高了多个数据面共享内存（lua_shared_dict）默认值，因此通过 Helm 部署的网关启动时预留的共享内存比之前的 chart 约多 365 MiB：

共享字典	之前	3.9.16 chart
prometheus-metrics（高级指标）	15 MiB	128 MiB
kubernetes、nacos、nacos-stream、consul（服务发现）	各 20 MiB	各 64 MiB
tracing_buffer（SkyWalking）	10 MiB	32 MiB
api-calls-for-portal	10 MiB	64 MiB

该变更位于 Helm chart 的共享字典值中（网关镜像默认值未变），因此适用于基于 Helm 的部署。升级 chart 前，请调高网关容器的内存 requests 和 limits，避免网关被 OOM 杀死。你可以通过 chart 的共享字典值把不需要的字典调回原先大小。

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.9.16 的控制面会加密这些字段，而仍为 3.9.15 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• limit-count、limit-count-advanced 和 graphql-limit-count：redis_password、sentinel_password
• limit-conn：redis_password
• limit-req：redis_password
• ai-rate-limiting：redis_password、sentinel_password
• elasticsearch-logger：headers（自定义认证请求头）
• ai-cache：redis_password、semantic.embedding.openai.api_key、semantic.embedding.azure_openai.api_key
• ai-lakera-guard：api_key

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.9.16，并在两侧都升级到 3.9.16 之前避免编辑这些插件。

升级说明 — 仅信任来自可信地址的转发头

网关现在通过 apisix.trusted_addresses 判断是否信任客户端传入的 X-Forwarded-* 和 RFC 7239 Forwarded 请求头。当未配置 trusted_addresses，或请求来自不可信地址时，网关会在转发上游前用自身观测到的值覆盖 X-Forwarded-Proto、X-Forwarded-Host 和 X-Forwarded-Port，并清除 Forwarded 请求头。如果上游应用依赖可信负载均衡器或反向代理传入的原始转发协议、host 或端口，请将该代理的 IP 或 CIDR 配置到 trusted_addresses。

升级说明 — OpenID Connect 不再默认启用静默重认证

openid-connect 插件不再默认把 refresh_session_interval 设为 900 秒。现在只有显式配置 refresh_session_interval 时才会执行周期性静默重认证。如果你的部署依赖此前 900 秒刷新一次的行为，请在升级前或升级过程中显式设置 refresh_session_interval: 900。

升级说明 — 内置用户登录策略更严格

内置 Dashboard 用户现在会在连续密码登录失败后被临时锁定。默认策略为启用状态，同一用户和来源 IP 连续失败 5 次后锁定 15 分钟。管理员可以通过新的登录失败限制系统设置调整或关闭该策略。升级后新密码和被修改的密码也必须至少 12 个字符，并继续满足原有复杂度要求。已有密码在登录时不会重新校验长度。

如果内置用户启用了双因素认证（2FA），该用户的 HTTP Basic Auth 会被拒绝，因为 Basic Auth 无法携带第二因素。程序化集成请改用 Token 认证；Token 通过 X-API-KEY 请求头传入，不需要携带 2FA 验证码。

升级说明 — SQL Server 部署首次启动会启用快照读

对于使用 SQL Server 的部署，控制面现在会先创建并准备数据库，再让其他组件连接，并启用 READ_COMMITTED_SNAPSHOT，避免网关配置读取被写事务阻塞。若既有 SQL Server 数据库尚未启用该设置，首次启动会以 ROLLBACK IMMEDIATE 应用该数据库级变更；正在进行的数据库事务和连接可能会被断开一次，之后连接池会重新连接，后续启动不会重复执行该操作。

新功能

插件

• AI Cache（新插件）
  • 在 Redis 中缓存 LLM 响应，使重复提示词无需再次调用上游模型。支持精确匹配缓存、通过 embedding 和 RediSearch 实现的可选语义（L2）匹配、流式响应缓存与回放、可配置绕过规则，以及缓存命中、未命中、绕过和 embedding 延迟的 Prometheus 指标。
• AI Lakera Guard（新插件）
  • 通过 Lakera Guard API 检测 AI 流量中的提示词注入和其他不安全内容。direction 选项（input、output 或 both）用于选择插件扫描请求提示词、LLM 响应（包括流式响应）还是两者。被标记的流量会以可配置的 deny_code 拒绝，或在 action 设为 alert 时仅记录日志。
• AI Aliyun Content Moderation
  • 新增 request_check_roles，用于选择要审查的请求角色（user、tool 和/或 system）。user 和 tool 内容遵循 request_check_mode（last 或 all，默认 last）；选择 system 时，系统内容会在每个请求中检查。长内容现在以线性时间分块，且对多字节（UTF-8）安全。
• AI AWS Content Moderation
  • 请求审查现在在 AI 协议识别之后执行，检查上游 LLM 实际可见的解码后提示词内容，而不是原始 HTTP JSON 外壳。拒绝响应现在以提供商兼容格式返回，并新增可配置的 check_request、deny_code 和 deny_message。
• Elasticsearch Logger
  • 新增通过自定义请求头向 Elasticsearch 认证的支持（headers 选项，例如 Authorization: Bearer <token> 或 API key 请求头），可作为基本 auth 的替代或补充。
• 限流插件
  • 为 Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置（redis_keepalive_timeout 和 redis_keepalive_pool），方便运营者调整空闲超时时间和连接池大小。

数据面

• 新增 apisix.trusted_addresses，根据解析后的客户端地址控制网关是否信任客户端传入的 X-Forwarded-* 和 Forwarded 请求头。
• 新增 apisix.match_uri_encoded_slash。启用后，编码斜杠（%2F）在路由匹配期间保持编码状态，可作为路径参数的一部分，而不是路径分隔符。
• 新增 apisix.max_post_args_readable_size（默认 64 MiB），用于限制匹配 JSON 或 multipart 请求的 post_arg.* 路由谓词时读取的请求体大小。设为 0 可禁用该限制。
• 在 standalone YAML 模式中，环境变量占位符现在会在 YAML 解析前替换。未加引号的占位符可以解析为原生布尔值或数字；加引号的占位符仍保持字符串，从而精确保留大整数 ID 和 Token 值。

控制面

• 为内置 Dashboard 用户新增 TOTP 双因素认证。用户可在账号设置中注册、启用、关闭和恢复 2FA；管理员可重置用户的 2FA 状态。
• 为内置用户新增登录失败限制。连续失败登录会临时锁定用户和来源 IP，写入审计事件，并返回明确的锁定提示。
• 新增双因素认证的 Dashboard UI：账号设置中的二维码和恢复码设置流程、登录时的 OTP 步骤，以及管理员重置用户 2FA 的操作。
• 密码表单和随机密码生成已更新为新的 12 字符最小长度。

缺陷修复

插件

• AI Proxy 和 AI Proxy Multi
  • 修复问题：包含 tool result 且混有其他内容的 Anthropic Messages 请求会被转换成非法的 OpenAI Chat 消息顺序，导致 OpenAI 兼容上游拒绝该会话后续的每个请求。现在 tool 消息会紧跟在包含 tool call 的 assistant 消息之后，旁边的文本或媒体会保留在后续 user 消息中。
  • 修复问题：若干 Anthropic 到 OpenAI 的转换细节与 LiteLLM 兼容行为不一致，包括工具名清洗、长工具名冲突处理、adaptive thinking effort、结构化输出 schema 提取、空数组编码和内容块形状。
  • 修复问题：结构化 chat content 可能以 table 形式传给下游 AI 插件并导致请求处理错误。协议适配器现在会在 AI guard 和 cache 插件消费前一致地拍平文本内容。
  • 修复问题：构建 ai-proxy-multi 工作实例池失败时可能抛出 Lua 错误并破坏性地清空池状态。现在该失败路径对 nil 安全且不具破坏性。
• gRPC Transcode
  • 修复问题：空的 protobuf repeated 字段会被编码为 {} 而不是 JSON 数组（[]）。现在空 repeated 字段会显示为数组，包括嵌套消息和 descriptor-set 方式的消息。
• Key Auth 和其他 Consumer 认证插件
  • 修复问题：如果 Consumer 凭据引用了无法解析的 secret，数据面可能仍把未解析的字面量加入索引，并用该字面量完成认证。现在引用的 secret 无法解析时，Consumer 认证会 fail closed。
• Secret 引用
  • 修复问题：更新或删除 /secrets 配置不会使 secret LRU 缓存失效，因此旧 secret 值可能继续使用到缓存过期，甚至无限期使用。现在 secret 配置变化后会重新解析 secret 引用。
• Proxy Rewrite
  • 修复问题：同时配置 use_real_request_uri_unsafe 和 uri 时，请求 query string 会在 URI 改写中丢失。现在会保留原始 query string，并在改写后的 URI 已含 query 时正确合并。
• Loggly
  • 修复问题：不同 route 的批量 Loggly 日志可能使用错误的 Token 或 tags，因为异步处理器复用了最新 route 的配置。现在每个批处理器都会保留自己的 route 配置。
• Datadog
  • 修复问题：较大的合并 DogStatsD datagram 可能超过常见的 8192 字节 agent 缓冲区并被静默截断。现在只有在 payload 可容纳时才合并，否则回退为每个 metric 一个 datagram。
• Zipkin
  • 修复问题：明确标记为未采样的请求仍会构造完整 span tag table 和 access 阶段子 span。现在未采样请求会跳过这些额外追踪工作，同时保留 trace 传播。
• OpenTelemetry
  • 修复问题：运行时更新 OpenTelemetry 插件元数据不会重建用于注入 core span 的 tracer，因此这些 span 可能继续使用旧 collector 或 resource 设置，直到 worker 重启。现在元数据变化后 tracer 会刷新。
  • 修复问题：additional_attributes 在 log 阶段变量填充前求值，导致依赖最终请求状态的属性缺失或过期。现在这些属性在 log 阶段求值。
• OpenID Connect
  • 修复问题：refresh_session_interval 错误地默认设为 900，即使用户未配置也会启用静默重认证。该默认值已移除（见升级须知）。
• MQTT Proxy
  • 修复问题：protocol_name 过去是必填项，尽管标准默认值是 MQTT。现在该字段可省略，并默认使用 MQTT。
• Forward Auth
  • 修复问题：当 request_method 为 POST 时，插件在缓冲请求体后仍可能把客户端的 Transfer-Encoding、Content-Length 和 Expect 请求头转发给认证服务，导致请求 framing 不一致。现在这些客户端 framing 头不会再复制到认证服务请求中。
• Authz CASBIN
  • 修复问题：在不同 route 之间切换不同 Casbin model 或 policy 形状时，可能触发 casbin enforce error / invalid request size。内置 lua-casbin 依赖已更新，包含相关 enforce 修复。
• AI Aliyun Content Moderation
  • 修复问题：在 body filter 中返回 ngx.OK 可能中断后续 body filter 处理。现在插件会正常返回，使其他 filter 可以继续执行。
• Request ID
  • 修复问题：配置 algorithm: range_id 但省略可选 range 对象时可能返回 HTTP 500。现在 range 对象有默认值。
• Workflow
  • 修复问题：Workflow action 插件可能在 workflow 决定跳过或执行该 action 前先运行 _meta.pre_function hook，从而影响本不应执行的 action。现在 workflow 会先决定是否运行 action，再执行这些 meta hook。
• Redirect
  • 修复问题：http_to_https 只重定向 scheme 恰好为 http 的请求，因此以非 HTTP、非 HTTPS scheme 到达的请求（例如通过伪造的 X-Forwarded-Proto）不会被重定向。现在它会重定向所有非 HTTPS 的 scheme。
• Response Rewrite
  • 修复问题：当上游响应被压缩（gzip 或 brotli）时，filters 作用在压缩字节上而无法匹配，产生损坏的响应体。现在会先解码响应再执行 filters。
• Batch Requests
  • 修复问题：当某个流水线子请求超时时，响应数组可能比子请求数多出条目。现在子响应数量总是与子请求数量一致。
• Tencent Cloud CLS
  • 修复问题：启用 include_req_body 时，由于未在 access 阶段读取请求体，请求体无法被捕获。现在会在采样允许时读取请求体，使其包含在上传的日志中。
• Attach Consumer Label
  • 修复问题：当匹配到的 Consumer 没有标签时，客户端可以伪造已配置的请求头，因为插件只在存在标签值时才覆盖该请求头。现在已配置的请求头总会从客户端请求中剥离，即使 Consumer 没有匹配的标签。
• Authz Keycloak
  • 修复问题：启用 lazy_load_paths 时，按 URI 解析 Keycloak 资源时包含了请求的 query string，导致带 query 参数的请求可能无法匹配目标资源。现在会在解析前剥离 query string。
• CAS Auth
  • 修复问题：CAS 单点登出（SLO）回调 POST 被代理到上游，而不是由插件处理。现在该回调由插件终止，不再转发到上游。
• gRPC Web
  • 修复问题：一条调试日志语句把解码后的请求体写入错误日志。该语句已移除，请求负载不再泄漏到日志中。

数据面

• 修复问题：部分日志文件被 rotation 后，网关可能仍保持旧文件句柄。现在部分 rotation 后也会正确重新打开日志。
• 修复问题：配置指令中的环境变量替换在一个变量名是另一个变量名的前缀时，可能匹配到错误的变量。现在变量名会被精确解析。
• 修复问题：在一次瞬时 DNS 或服务发现失败后，域名上游即使在名称重新解析成功后仍可能持续返回 HTTP 503。现在上游会在解析成功后恢复。
• 修复问题：升级 Prometheus 指标库（nginx-lua-prometheus-api7 升至 0.20260623），移除可能导致整次抓取被拒绝的重复指标序列。

控制面

• 修复问题：配置 revision 刚变化后、下一次 heartbeat 尚未上报新 revision 前，网关实例可能短暂显示为 OutOfSync。现在新增宽限窗口，在正常同步窗口内仍保持最近有 heartbeat 的实例为 Healthy。
• 修复问题：兼容性报告被截断为 200 条且顺序不稳定，因此大报告可能隐藏 error，并在不同网关实例间显示不同结果。现在控制面会存储完整且排序后的报告，并基于全部条目计算兼容性。
• 修复问题：secret provider 的请求体可能匹配与 URL 路径中 provider 名称不同的类型，导致数据面丢弃或误读已保存 secret。现在控制面会按路径选择的 provider 类型校验请求体。
• 修复问题：控制面接受了一些数据面会静默丢弃的核心资源配置，包括非法 TLS、filter 和 IP match 配置。现在这些配置会在发布前被校验拒绝。
• 修复问题：OpenAPI schema 会拒绝 IPv6 upstream node host。现在 IPv6 host 可以被接受。
• 修复问题：batch ssls 校验使用了 SNI schema 而不是 SSL schema，导致缺少证书字段的条目可能通过校验。现在 batch SSL 校验使用正确 schema。
• 修复问题：审计日志导出只返回前 256 条。现在会导出所有匹配的审计日志。
• 修复问题：凭据查询索引可能被不执行数据库迁移的组件删除，且部分启动 schema repair 会不必要地重建当前索引。现在 schema repair 会保留当前索引，仅修复过期形状。
• 修复问题：在大型部署中，heartbeat 和实例状态查询可能变慢。新增索引和 Go 侧状态计算改善了这些查询。

3.9.15

发布日期：2026-06-22

升级须知

升级说明 — 新增插件字段需要控制面和数据面均升级到 3.9.15

本次发布新增了插件配置字段：日志类插件的 log_format_extra，以及 openid-connect 的 Redis 会话存储（session.storage 和 session.redis）。由于 API7 EE 升级时先升级控制面、再升级数据面，3.9.15 的控制面会接受这些字段，而较旧的数据面尚未实现它们。请在控制面和数据面都升级到 3.9.15 之后再配置这些新选项。

升级说明 — 仅限 SSO 的域名不再允许本地登录

在开发者门户中，仅限 SSO 的域名策略现在在服务端强制执行，而不再仅在浏览器侧生效。对于域名被映射到仅限 SSO 提供方的邮箱，本地登录与注册方式——邮箱密码登录与注册、魔法链接、密码重置——现在都会被拒绝。此前这些端点可以被直接调用，从而绕过 SSO 要求。如果 SSO 托管域名下的用户依赖本地登录，请在升级后让他们改用 SSO 登录。

升级说明 — 开发者门户 API 代理改为默认拒绝

开发者门户的 API 代理不再转发任意后端端点。现在只有组织维度资源的显式白名单（API Product、application、credential、subscription 和 DCR provider）会被代理，其他路径一律返回 HTTP 404。只读资源对写方法返回 HTTP 405；对 application、credential、subscription 的写操作需要 owner 或 admin 角色（否则 HTTP 403）；组织维度的请求需要已认证会话（否则 HTTP 401）。如果你有集成通过门户代理访问其他端点，请改为使用受支持的 API 路径，或直接调用控制面。

升级说明 — 开发者门户注册同意配置变更

开发者门户的注册同意选项 tosURL 和 beforeSignUpButtonHtml 已被合并为单个 signUpConsentLabel，用于承载同意复选框旁展示的自定义 HTML。服务条款（Terms of Service）的接受校验现在仅在配置了 signUpConsentLabel 时才强制执行。如果你的部署设置了 tosURL 或 beforeSignUpButtonHtml，请在升级前将其值迁移到 signUpConsentLabel。

新功能

插件

• OpenID Connect
  • 新增 Redis 作为会话存储后端。将 session.storage 设为 redis（默认仍为 cookie），并在 session.redis 下配置连接（host、port、认证、database、key 前缀、TLS 和超时）。将会话存储在 Redis 中可以让多个网关节点和 route 共享同一会话并集中刷新 Token。Redis 密码在存储时加密，已有的基于 cookie 的配置不受影响。

数据面

• 日志类插件现在支持 log_format_extra 选项，它在默认日志条目之上叠加字段，而不是替换整个条目。此前，设置 log_format 会替换整个默认条目，并丢弃没有标量变量的字段（如各类头部的 map、解析后的查询字符串、拼接出的 URL、计算出的各类 latency）；log_format_extra 会保留完整的默认条目，并在其上叠加你的额外字段。当设置了 log_format 时，仍以 log_format 为准，log_format_extra 会被忽略。同时新增 $upstream_unresolved_host 变量，记录 DNS 解析前所配置的上游 host 或域名。
• stream（TCP）代理的 PROXY protocol 现在可以按监听端口启用。每个 stream_proxy.tcp 条目可设置两个可选字段——proxy_protocol（在该端口接收 PROXY protocol）和 proxy_protocol_to_upstream（向上游发送 PROXY protocol）——它们会覆盖全局的 proxy_protocol.enable_tcp_pp 和 enable_tcp_pp_to_upstream 默认值。未设置这些字段的端口沿用全局行为，因此已有配置保持不变。
• Debug session 现在会捕获每个被采样请求的日志行（所有级别），并作为 span event 附加到该请求的 trace 上。每请求日志会与 trace 一起展示在 debug session 视图中，便于将日志输出与具体被追踪的请求关联。

开发者门户

• 开发者门户现在可以运行在自定义的 PostgreSQL schema 中，而不再仅限默认的 public schema。该 schema 在门户配置中设置（不放在连接 URL 中）；门户会按连接应用该 schema，并在其中运行数据库迁移。

缺陷修复

插件

• JWT Auth
  • 修复问题：签名格式错误（长度不对或不是合法的 base64url）的 Token 会导致校验器抛错并返回 HTTP 500，而不是拒绝请求。格式错误的签名现在会以 HTTP 401 拒绝。
• AI Proxy 和 AI Proxy Multi
  • 修复问题：当上游 LLM 提供商返回 HTTP 429 或 5xx 响应时，网关只返回状态码而响应体为空，丢弃了提供商的错误详情（如限流信息）。当请求未重试时，上游错误响应体及其 Content-Type 现在会转发给客户端。
• Loki Logger
  • 修复问题：当标签值引用每请求变量（例如 $service_name 或 $host）时，某个请求解析出的值会被同一批次内的其他请求复用，并可能在多次请求间被固定下来，导致日志被打上错误的标签。现在标签按请求解析，每个请求的日志会按其自身的标签集分组到独立的 Loki stream 中。
• HMAC Auth
  • 修复问题：启用 validate_request_body 后，插件为校验签名而缓冲的请求体默认上限为 512 KiB，会拒绝上游本可接受的较大请求体，且超限请求体会被报告为误导性的 HTTP 401。max_req_body_size 默认值现在为 64 MiB（与 APISIX 对齐），超过上限的请求体会以 HTTP 413 拒绝。

数据面

• 修复问题：使用一致性哈希（chash）负载均衡时，每当节点健康状态变化，哈希环都会仅用当前健康的节点重建，这（尤其在节点权重不均时）会打乱环并迁移那些本已映射到健康节点的 key。现在哈希环只在配置或权重变化时重建，节点健康在选择时评估，因此瞬时的健康变化不再扰乱未受影响 key 的粘性路由。这同时适用于 upstream 的 chash 和 ai-proxy-multi 的 chash 负载均衡。

控制面

• 修复问题：已经运行控制面期望的精确版本的数据面，在其上报了非法的插件或配置字段时，仍可能在 Dashboard 中被显示为 Upgrade Required，尽管并不存在可供升级的更新版本。运行在期望版本上的数据面现在会保持兼容；上报的配置问题仍会以配置错误（error）和警告（warning）指示单独呈现。

开发者门户

• 修复问题：若干双因素认证（2FA）错误未被正确呈现——使用错误密码启用或关闭 2FA 看似成功、备份码弹窗可能显示为空、登录时输入错误的 TOTP 验证码会静默地进入门户。现在错误的密码和 TOTP 验证码会被正确拒绝并给出明确错误。

3.9.14

发布日期：2026-06-15

不兼容变更

插件

• JWT Auth

  升级说明

  jwt-auth 现在默认校验 Token 的 exp（过期）和 nbf（生效时间）声明。此前，未设置 claims_to_verify（或将其设为空列表）的 consumer 会接受任何签名正确的 Token，包括已过期的 Token。数据面升级后，这类 Token 会被以 HTTP 401 拒绝。

  如果你依赖已过期 Token 仍被接受，请在升级前评估此行为变更。如需只校验特定声明，请在 consumer 配置中显式设置 claims_to_verify。

• HMAC Auth

  升级说明

  hmac-auth 插件现在将 signed_headers 默认设为 ["date"]。数据面升级后，任何未显式设置 signed_headers 的 hmac-auth 配置都要求客户端签名覆盖 Date 头。此前未对 Date 签名的客户端将开始收到 HTTP 401，错误信息为 client request can't be validated。

  升级前，请确保客户端对 Date 头签名，或在插件配置中显式设置 signed_headers 以匹配客户端实际签名的头。

• Batch Requests

  升级说明

  batch-requests 插件现在会限制批量请求的规模。流水线子请求的数量由新增的插件元数据选项 max_pipeline_items 限制（默认 1000），超过上限的批量请求会被以 HTTP 400 拒绝。包含文档之外字段的流水线条目现在会被拒绝，且每批的 timeout 至少为 1 毫秒。

  如果你发送的批量请求超过 1000 个子请求，请在插件元数据中调大 max_pipeline_items。如果客户端发送了未文档化的条目字段，请在升级前移除它们。

开发者门户

• 仅对已发布的 API Product 强制开发者认证

  升级说明

  此前，处于**草稿（draft）状态的 API Product 也会把其开发者认证规则同步到网关，因此草稿产品下的 route 也会要求开发者认证。从 3.9.14 起，只有已发布（published）**的 API Product 才会向数据面下发开发者认证规则。

  升级后，属于草稿（未发布）API Product 的 route 在产品发布之前不再要求开发者认证。如果你依赖草稿产品被保护，请发布它们，或通过其他方式限制访问。

升级须知

升级说明 — 请求体大小默认上限

forward-auth、ai-proxy 和 ai-proxy-multi 插件在读取请求体时现在会强制 max_req_body_size 上限（默认 64 MB）。请求体超过上限时会以 HTTP 413 Request Entity Too Large 拒绝。

如果你通过这些插件代理较大的请求体，请在升级前显式将 max_req_body_size 设为适配你业务的值。

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.9.14 的控制面会加密这些字段，而仍为 3.9.13 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• AI AWS Content Moderation：comprehend.secret_access_key
• Azure Functions：master_apikey、authorization.apikey
• DingTalk Auth：secret_fallbacks
• Error Log Logger：kafka.brokers.sasl_config.password
• Feishu Auth：secret_fallbacks
• HTTP Logger：auth_header
• Kafka Logger：brokers.sasl_config.password
• Loggly：customer_token
• OpenFunction：authorization.service_token
• OpenID Connect：session.secret
• Splunk HEC Logging：endpoint.token

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.9.14，并在两侧都升级到 3.9.14 之前避免编辑这些插件。

新功能

插件

• Limit Count
  • 此前由 limit-count-advanced 提供的高级限流能力现已内置到 limit-count。你可以配置滑动窗口（window_type 设为 sliding）、redis-sentinel 策略、多条限流规则（rules）、由请求变量推导的 count，以及通过 group 和 sync_interval 实现的共享计数器。独立的 limit-count-advanced 插件仍保留以兼容旧配置。
• AI Proxy
  • 上游 LLM 请求体现在使用排序后的 key 进行 JSON 编码。这会为等价请求生成稳定、逐字节一致的请求体，从而提升按精确请求体缓存的 LLM 提供商的 prompt-cache 命中率。
• AI Proxy Multi
  • 新增 max_retries 以限制 fallback 重试次数，以及 retry_on_failure_within_ms，使得只有在配置时间窗内发生的失败才触发 fallback。慢速失败会直接返回客户端，避免在多个 fallback 实例间成倍累加等待时间。
• AI Prompt Guard 及各 AI 内容审核插件
  • 新增 fail_mode（skip、warn 或 error，默认 skip），用于控制 consumer 绑定的插件在遇到无法识别格式的请求时的行为：skip 放行请求，warn 放行并记录日志，error 以 HTTP 400 拒绝。
• OpenID Connect
  • 新增对 lua-resty-session 的 session 选项支持（如 cookie_name、cookie_path），从而可以自定义 session cookie。
  • 对于本地 JWT 校验模式（例如 bearer_only 配合 public_key、use_jwks 或 private_key_jwt），client_secret 现在为可选项，因为这些模式不需要 client secret。
• CAS Auth
  • cas_callback_uri 现在支持绝对 URL，并原样用作 CAS service URL。当网关位于代理之后、对外可见的 callback URL 与请求路径不同时，这非常有用。
• Proxy Cache
  • 内存缓存策略现在支持 Vary 响应头。响应会按 Vary 中列出的头计算出的变体分别缓存，Vary: * 的响应不会被缓存。
• Kafka Logger
  • 新增 api_version 选项（Produce API 版本 0、1 或 2）。将其设为 2 后，消息时间戳会被携带并由 broker 存储；否则消息可能在记录时缺少时间戳。

数据面

• 新增面向 AI 请求的内建 NGINX 变量（$llm_model、$request_llm_model、$llm_prompt_tokens、$llm_completion_tokens、$llm_total_tokens、$llm_time_to_first_token、$llm_stream），可在 NGINX access log 格式中引用，以记录每个请求的 LLM 模型和 Token 用量。
• Prometheus 插件现在导出 LLM Token 分布直方图（apisix_llm_prompt_tokens_dist 和 apisix_llm_completion_tokens_dist），以及包含首 Token 时间（type="ttft"）的 apisix_llm_latency 直方图。
• Prometheus 插件现在为 HTTP 指标增加 MCP 工具维度（mcp_tool_name 和 mcp_request_type），从而可以按工具和请求类型拆分 MCP tools/call 流量。

开发者门户

• 为开发者门户新增**审批（Approvals）**流程。平台管理员可以在门户中审核并接受或拒绝 API Product 订阅和开发者注册请求，申请人的组织名称会被解析以便展示。执行操作的管理员会被记录为操作者以便审计，Dashboard 也会展示解析后的操作者。
• 凭证密钥（如 key-auth、basic-auth 的 key）现在只在创建时返回一次。后续读取凭证时不再包含密钥值。
• 新增管理员**用户（Users）**页面，用于管理门户用户——列表、搜索、修改角色、封禁/解封以及删除。
• 新增门户登录的双因素认证（2FA）。
• 新增基于策略的 SSO 登录：可根据开发者的邮箱域名将其路由到指定的 SSO 提供方，支持锚定的、大小写不敏感的正则表达式匹配。
• 新增注册时可配置的服务条款（Terms of Service）确认步骤。
• 新增暗色模式。

缺陷修复

插件

• Error Page
  • 修复问题：插件此前根据 upstream status 变量判断是否渲染自定义错误页，可能会替换掉真正来自上游服务的错误响应。现在插件会判定响应来源——只对网关或插件产生的错误渲染自定义错误页，而真正由上游返回的错误响应会原样透传。
• Feishu Auth 和 DingTalk Auth
  • 修复问题：客户端可以传入伪造的 X-Userinfo 头并被转发到上游。两个插件现在都会在认证前清除客户端传入的 X-Userinfo 头，确保上游只收到由插件校验的身份信息。
• DingTalk Auth
  • 修复问题：认证失败与上游瞬时失败未做区分。插件现在对认证错误返回 HTTP 401，对 DingTalk 或上游的瞬时失败返回 HTTP 503，并提供更清晰的错误信息。
• CAS Auth
  • 修复问题：登录回调未校验已签名的发起 cookie，使得构造的回调请求可以操纵登录后的跳转目标。回调现在要求携带有效的已签名发起 cookie，否则以 HTTP 401 拒绝。
  • 修复问题：单点登出（SLO）的空 body POST 请求此前返回 HTTP 500，现在返回 HTTP 400。
• Authz Casdoor
  • 修复问题：session cookie 名称在不同 Casdoor client 间共享，导致不同 client 的 session 可能冲突。session cookie 现在按 client 隔离命名。
  • 修复问题：网关 session 未与 Casdoor Token 的生命周期绑定，Token 过期后仍可能被复用。现在 session 会在 Casdoor Token 过期时失效，强制重新认证。
• Authz Keycloak
  • 修复问题：当静态 permissions 与 http_method_as_scope 同时使用时，派生出的方法 scope 会被写回复用的插件配置，导致 scope 跨请求累积。现在会在追加方法 scope 之前先克隆 permission 列表。
• OPA
  • 修复问题：对于在 send_headers_upstream 中列出但 OPA 响应中未返回的头，客户端传入的值可能被转发到上游。现在这类头会被清除，确保只有 OPA 提供的值到达上游。
• SAML Auth
  • 修复问题：重构了插件加载和错误处理——移除了 load_resty_saml wrapper，默认关闭 debug 输出，并在认证出错时返回干净的 HTTP 500。
• AI Proxy
  • 修复问题：上游 LLM 超时此前被映射为 HTTP 500，现在映射为 HTTP 504 Gateway Time-out。
  • 修复问题：在 passthrough 模式下，客户端的 HTTP 方法和查询字符串未被转发到上游。现在它们会被保留。
• AI Proxy Multi
  • 修复问题：基于域名的 upstream 健康检查可能不稳定——缓存的节点选择器在健康检查器创建后可能变陈旧，且健康检查配置可能在请求间被就地修改。
• GraphQL Limit Count
  • 修复问题：查询嵌套深度计算有误，导致基于深度的限流不准确。现在深度会按真实最大嵌套深度并展开 fragment 计算，Content-Type 匹配也容忍 charset 参数。
• GraphQL Proxy Cache
  • 修复问题：Content-Type 带 charset 参数的请求未被识别为 GraphQL 请求。Content-Type 匹配现在容忍 charset。
  • 修复问题：PURGE 请求未清除缓存条目的所有 Vary 变体。现在所有变体都会被清除。
• AWS Lambda
  • 修复问题：对带 URL 编码或多值查询参数的请求，IAM（SigV4）认证因 canonical query string 计算错误而失败。
• AWS Secret Manager
  • 修复问题：解析名称中包含斜杠的 secret 会失败。现在这类名称可以被正确解析。
• Request ID
  • 修复问题：nanoid 算法可能产生重复或非法的 ID。现在 ID 使用密码学安全的随机源生成，并始终使用合法的 nanoid 字母表。
• Proxy Mirror
  • 修复问题：镜像 gRPC 请求时，原始的 method path 未在镜像请求中保留。现在它会被完整保留。
• Body Transformer
  • 修复问题：XML 转 JSON 时，使用 XML 命名空间前缀的 key 偶尔会丢失。现在带命名空间的 key 会被保留并可在模板中访问。
• Elasticsearch Logger
  • 修复问题：使用日期占位符的动态索引模板在模板非法时可能报错。现在日期格式化已加守卫。
• 限流插件（Limit Count、Limit Req、Limit Conn）
  • 修复问题：仅在 database 编号或凭证上不同的 Redis 连接可能共享同一 keepalive 连接池，导致连接被复用到错误的 database 或身份上。现在连接会按 database、凭证和 TLS 设置隔离；这也覆盖了 redis-sentinel 策略。
• Limit Conn
  • 修复问题：解析后为 0 的动态 burst 值此前被错误地判为非法。现在它被允许。

数据面

• 修复问题：当同一请求上有多个日志插件抓取响应体时，它们的响应体缓冲区可能相互干扰，产生截断或混杂的日志输出。现在每个 logger 使用独立的缓冲区。
• 修复问题：部分 logger 插件写入的 debug 日志可能泄漏凭证。这些日志已被移除。
• 修复问题：当 access 阶段被短路（例如被认证拒绝）时，log 阶段的日志插件可能失败。
• 修复问题：当插件用不同大小写设置同一个头时，缓存的请求头可能保留陈旧值。现在头的缓存键会被归一化。
• 修复问题：consul 服务发现在某个节点条目无效时会丢弃该 service 的其余所有节点。现在无效节点会被逐个跳过，其余健康节点仍会被使用。
• 修复问题：nacos 服务发现在 stream 子系统中因所需的共享字典未在该子系统声明而失败。

控制面

• 修复问题：openid-connect 允许省略 client_secret 的豁免适用范围过宽。现在该豁免被限定到确实不需要 client secret 的 OIDC flow。
• 修复问题：按 gateway group 维度列出 label 时，返回的是该资源类型的全局 label，而不是限定到该 gateway group 的 label。
• 修复问题：开发者门户的组织邀请未遵循所配置的邮箱验证要求。

3.9.13

发布日期：2026-05-22

不兼容变更

插件

• CAS Auth

  升级说明

  cas-auth 插件现在要求配置长度至少为 32 个字符的 cookie.secret。插件使用该密钥对 CAS_REQUEST_URI cookie 进行 HMAC 签名和校验，防止客户端可控 cookie 修改登录后的跳转目标。

  升级前，请为所有已有 cas-auth 配置补充 cookie.secret，并确保所有网关节点使用相同密钥。

升级须知

升级说明 — proxy cache 行为变化

proxy-cache 和 graphql-proxy-cache 插件现在默认使用更安全的缓存行为。

对于 proxy-cache，当请求存在已认证 consumer 或 remote user 时，缓存会按 consumer 隔离，除非配置的 cache_key 已经包含身份相关变量。内存缓存策略也不再缓存上游 Cache-Control 包含 private、no-store 或 no-cache 的响应；内存和磁盘缓存策略都默认跳过带 Set-Cookie 的响应，除非设置 cache_set_cookie: true。

对于 graphql-proxy-cache，缓存键默认包含 host、route、service 和 consumer 身份，带 Set-Cookie 的响应默认也会被跳过，除非设置 cache_set_cookie: true。

如果你确实需要跨 consumer 共享缓存，请设置 consumer_isolation: false。如果你确实需要缓存带 Set-Cookie 的响应，请设置 cache_set_cookie: true。

新功能

插件

• AI Proxy
  • 优化 OpenAI 兼容流式响应吞吐，降低逐 Token flush 和 SSE 解析开销。在使用 mock OpenAI 上游的内部单 worker benchmark 中，峰值流式吞吐从 44,102.6 tokens/s 提升到 138,158.7 tokens/s，约提升 3.13 倍。
  • 优化使用 post_arg.* 路由变量的 AI 大 JSON 请求体处理。在 1 MB、5 MB、10 MB OpenAI Chat Completions 兼容请求体的内部 benchmark 中，当网关透传原始请求体时吞吐提升 5.15-5.35 倍；当网关转发前改写请求体时吞吐提升 2.47-2.67 倍。
  • 新增 streaming_flush_interval_ms，用于控制流式响应的周期性 flush。默认值为 10 ms，可降低逐 chunk flush 开销，同时保持有界的流式响应延迟。
• OpenAPI to MCP
  • 新增 allowed_hosts，用于限制动态解析后的 base_url 可访问的目标主机。未配置 allowed_hosts 时，既有行为不变。插件现在也会对解析后的 URL 进行校验，对非法 URL 或非 HTTP(S) scheme 返回 HTTP 400。
• Proxy Cache 和 GraphQL Proxy Cache
  • 新增 consumer_isolation 和 cache_set_cookie 选项，用于控制升级说明中描述的更安全缓存行为。

控制面

• Alert Policy 现在支持在告警条件触发时自动创建 Debug Session。Alert History 会记录 Debug Session 创建是否成功，并包含创建出的 session ID 或错误详情。
• Fallback Control Plane 存储现在支持 S3-compatible path-style endpoint，可用于 MinIO 等要求 bucket 名称出现在 URL path 中的 S3 兼容服务。

控制台（Dashboard）

• Gateway Group 下新增 Debug Sessions UI，包括 session 列表、创建、停止、删除、trace 列表、trace waterfall 详情、搜索和过滤、minimap、URL 状态同步、字段格式化和键盘导航。
• 删除/停用确认弹窗新增复制按钮，用户可在执行破坏性操作前复制资源标识。
• 监控页面的 service 和 route 选择器支持搜索。

开发者门户

• 新增用于在 Kubernetes 中部署 Developer Portal 的 Helm chart。

缺陷修复

插件

• OpenID Connect
  • 修复问题：客户端传入的身份头（X-Access-Token、X-Userinfo、X-ID-Token、X-Refresh-Token）可能被转发到上游，而不是使用插件校验后的值。现在这些头会被清除或覆盖，确保上游只收到由插件控制的身份信息。
• Data Mask
  • 修复问题：插件在处理多值 query 参数、无值 query 参数、非字符串 JSON 值、regex 失败和表单解析错误时可能崩溃或产生错误脱敏结果。regex 替换失败时也不再把原始敏感值写入日志。
• ACL
  • 修复问题：external_user_label_field_parser 和 external_user_label_field_separator 可能错误地应用到 consumer labels，导致错误的允许或拒绝决策。现在它们只用于 external-user label 提取路径。
• Chaitin WAF 和 Wolf RBAC
  • 修复问题：插件向后端服务发送客户端 IP 时使用了客户端可伪造的原始 IP 请求头。现在改为使用网关解析后的可信真实客户端 IP。
• Client Control
  • 修复问题：当 Global Rule 插件在 access 阶段读取请求体时，路由或服务上的 client-control 无法先应用请求体大小覆盖，导致大请求被意外拒绝。

控制面

• 修复问题：删除仍被其他资源引用的 Secret 会留下悬空引用，并可能导致网关运行时错误。现在 Secret 仍存在引用时会拒绝删除。
• 修复问题：当 dp_manager_address 同时包含域名和 IP 地址时，Data Plane Manager 证书可能无法通过旧版 Data Plane 的主机名校验。
• 修复问题：心跳上报中的非法网关版本字符串可能导致兼容性校验崩溃。现在会将其作为不兼容版本处理，而不是触发 panic。
• 修复问题：非法的 stream route CIDR/IP 值和非法的 post_arg.* JSON path 表达式可能被控制面接受，随后在数据面被拒绝或丢弃。现在这些配置会在 API 层被拒绝。
• 修复问题：解密 AesEncrypt 字段失败时，敏感加密字段值可能出现在日志中。现在日志只记录值长度。

数据面

• 修复问题：引用 service 的 stream route 可能持续使用旧的 service 级插件配置，直到 route 变更或 worker 重启。
• 修复问题：etcd 或 DP Manager 响应缺少预期 revision header 时，网关 worker 可能在启动阶段崩溃。现在网关会记录问题并重试。
• 修复问题：启用 status report 时，stream worker 可能在配置同步期间崩溃。
• 修复问题：标准网关 runtime 镜像缺少时区数据，导致 TZ 环境变量对 IANA 时区名称不生效。
• 修复问题：启用 tracing 时，tracer 可能在 HTTPS 或 HTTP/2 keepalive 连接上崩溃。
• 修复问题：网关 CLI 将控制面 mTLS client certificate 文件写入系统临时目录，且权限过宽。现在这些文件会写入网关配置证书目录，并使用更严格的权限。

控制台（Dashboard）

• 修复问题：OpenID Connect 插件代码编辑器在小视口或高缩放比例下可能折叠或无法访问。
• 修复问题：从服务列表删除 Published Service 成功后，可能显示误导性的 "service not found" 错误 toast。
• 修复问题：一个页面可能修改列表表格默认值，并将非法排序参数泄漏到 Gateway Instances 页面。
• 修复问题：插件查看抽屉在 local、global 和 metadata 标签页之间切换时，可能显示过期或错误的 JSON。
• 修复问题：缓存的 gateway group 或 portal ID 不存在时，页面可能空白或显示 404 错误 toast，而不是跳转到有效的兜底资源。

3.9.12

发布日期：2026-05-08

新功能

插件

• AI Proxy
  • 新增 AWS Bedrock 提供商支持，使用 Converse API。通过配置 "provider": "bedrock"、auth.aws 中的 AWS IAM 凭证和 provider_conf.region 中的 AWS 区域即可使用。支持非流式和流式（ConverseStream）两种模式——在请求体中设置 "stream": true 即可获取流式响应。
• OAS Validator
  • 新增 spec_url 字段，支持从远程 HTTP(S) URL 加载 OpenAPI 规范，替代在插件配置中内嵌完整 JSON 字符串。当规范文件超过 spec 字段的 2 MB 内联大小限制时特别有用。获取的规范使用可配置的 TTL 进行缓存（默认 1 小时，通过插件元数据 spec_url_ttl 设置），过期条目在后台刷新期间继续提供服务。另提供 spec_url_request_headers（自定义 HTTP 头，如用于认证）和 timeout（请求超时，毫秒，默认 10000）字段。spec 和 spec_url 互斥。

缺陷修复

插件

• File Logger
  • 修复问题：当路由同时配置了 gzip 插件和 file-logger（启用 include_resp_body）时，file-logger 错误地尝试解压响应体。由于 APISIX 自身执行了 gzip 编码，日志器可用的响应体仍然是明文，导致产生虚假的 inflate gzip err: INFLATE: data error 日志条目，并且日志输出中丢失了响应体内容。
• Elasticsearch Logger
  • 修复问题：使用日期时间占位符的动态索引模式（如 gateway-{%Y.%m.%d}）在第一个请求后停止轮转。解析后的日期字符串被回写到共享配置对象中，永久覆盖了模板，直到工作进程重启。
• OAS Validator
  • 修复问题：请求头参数校验区分大小写，当请求中的头名称大小写与 OpenAPI 规范定义不完全匹配时（例如发送 X-Request-Id 而规范定义的是 x-request-id），请求会被拒绝。现已按照 RFC 7230 §3.2 实现大小写不敏感匹配。

3.9.11

发布日期：2026-04-30

升级须知

升级说明 — Secret 引用 CP→DP 兼容性

本版本将 secret 引用（$secret://、$env://）扩展为所有插件集中支持。升级控制面到 3.9.11 后，如果在之前不支持 secret 引用的插件字段中配置了 secret 引用，仍运行 3.9.10 或更早版本的数据面将不会解析这些引用——它会将字面量 $secret://... 字符串传递给插件。

推荐升级路径：在配置新支持的插件字段中的 secret 引用之前，先将所有数据面升级到 3.9.11。之前已支持 secret 的插件（jwt-auth、openid-connect、limit-count、authz-keycloak、csrf、limit-req、limit-conn）不受影响。

新功能

插件

• AI Proxy
  • 新增 passthrough 协议适配器，可将无法识别的 API 格式（如 /v1/images/generations）透传至上游而不进行转换。此前，不匹配已知协议（OpenAI Chat、Completions、Embeddings 等）的请求会被拒绝。
  • 使用白名单构建方式重写了 Anthropic 到 OpenAI 的协议转换器。这防止了 Anthropic 特有字段（如 metadata、top_k、thinking、output_config）泄漏到 OpenAI 兼容的上游提供商，并改善了工具调用、系统提示和多模态内容的转换准确性。
  • 当 ai-proxy 使用 cosocket 传输调用 LLM 后端时，访问日志中的上游 nginx 变量（$upstream_status、$upstream_addr、$upstream_response_time、$upstream_header_time、$upstream_connect_time、$upstream_response_length）现在能正确填充。此前由于绕过了 nginx 的 upstream 模块，这些变量为空。
• OAS Validator
  • 用纯 Lua 实现（lua-resty-openapi-validator）替换了基于 Go FFI 的 OpenAPI 验证器。基于真实大规模 OpenAPI 规范（Stripe，约 414 个端点）的内部基准测试显示，新验证器每次请求校验快 2-7 倍，规范编译快 20 倍，同时消除了 Go 共享库从而减小了网关镜像体积。新验证器还修复了路径参数路由、nullable schema、allOf/anyOf 合并的正确性问题，并新增了对 form-encoded 请求体校验的支持（此前实现无法处理）。
• 所有插件现在自动支持在任何配置字段中使用 $secret:// 和 $env:// 引用。此前仅少数插件（jwt-auth、openid-connect、limit-count、authz-keycloak、csrf、limit-req、limit-conn）显式支持 secret 引用。这消除了每个插件单独实现 secret 解析的需要。

数据面

• 新增 distroless 网关镜像变体（api7-ee-3-gateway-distroless）。该镜像从零构建，仅包含运行网关所需的共享库、CA 证书和时区数据，消除了运行时未使用但携带 CVE 的操作系统包。

控制台（Dashboard）

• 配置兼容性警告和错误现在通过数据面实例卡片上的可点击徽章单独显示。点击徽章打开一个详细模态框，展示所有配置问题的表格（资源类型、ID、严重级别和消息），便于识别和解决配置 schema 问题，而不会与版本兼容性状态混淆。

缺陷修复

插件

• AI Proxy Multi
  • 修复问题：控制面推送配置更新后，健康检查验证记录大量噪声警告日志（unable to construct upstream for plugin: ai-proxy-multi），因为 DNS 解析状态在配置表替换时丢失。
• AI Rate Limiting
  • 修复问题：包含点号的 AI 实例名称（如 Qwen3.5-397B-10.249.238.157）导致 HTTP 500 错误，因为名称被错误地解析为 ctx.var 路径表达式而非常量键。
• AI Request Rewrite
  • 修复问题：无请求体的请求产生模糊的上游错误，而非返回明确的 HTTP 400 Bad Request。
• AI Prompt Template
  • 修复问题：JSON 解析错误消息显示为混乱的 Lua 表引用（如 table: 0x...），而非可读的错误字符串。
• OpenTelemetry
  • 修复问题：additional_attributes 中的非字符串值（如来自 nginx 变量的数字或布尔值）被 OpenTelemetry SDK 静默丢弃。现在在添加到 span 之前会强制转换为字符串。
• Limit Count
  • 修复问题：Redis 凭证（redis_password、redis_username、sentinel_password）被嵌入速率限制分组键中，在 Redis 键空间和 APISIX 日志中暴露敏感信息。
• Traffic Split
  • 修复问题：在 stream（L4）上下文中 ctx.var.route_id 始终返回 nil，导致 traffic-split 规则中基于 route_id 的匹配条件永远无法生效。
  • 修复问题：在 stream 上下文中，traffic-split 通过 upstream_id 选择的上游被忽略，始终使用路由原始的上游。

控制面

• 修复问题：配置兼容性报告中的警告级别条目错误地导致数据面实例显示“建议升级”，即使控制面和数据面版本一致。

数据面

• 修复问题：批处理器在 nginx worker 关闭期间进入无限定时器循环，阻止优雅关闭并产生大量 [alert] 日志。
• 修复问题：批处理器的 processed_entries 计数器在过期缓冲区清理时被重置，导致批处理插件（如 http-logger、kafka-logger）的投递指标不准确。
• 修复问题：活跃健康检查的 request_body 配置被静默忽略，因为底层健康检查库期望字段名为 http_req_body。schema 字段已重命名以匹配。
• 修复问题：加密/解密操作失败时，错误日志中暴露敏感字段值。错误消息不再包含原始值。
• 修复问题：升级过程中新增 encrypt_fields 后，预存明文数据的预期解密失败产生噪声的 warn 级别日志。这些日志现在记录为 info 级别并附带解释说明。

3.9.10

发布日期：2026-04-22

不兼容变更

插件

• OpenAPI to MCP

  升级说明

  OpenAPI2MCP 服务不再内置于网关镜像中，现作为独立 sidecar 容器（api7/openapi-to-mcp）运行，网关镜像体积因此减少约 150 MB。如果你使用了 openapi-to-mcp 或 mcp-tools-acl 插件，需要在网关旁部署 OpenAPI2MCP sidecar 容器。Kubernetes 环境中，在网关 Helm chart 中启用 openapiToMcp.enabled=true。Docker Compose 环境中，将 api7/openapi-to-mcp 容器与网关置于同一网络命名空间下。

升级须知

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.9.10 的控制面会加密这些字段，而仍为 3.9.9 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• AI Proxy：auth.header、auth.query、auth.gcp.service_account_json
• AI Proxy Multi：instances.* 下的相同字段
• AI RAG：embeddings_provider.azure_openai.api_key、vector_search_provider.azure_ai_search.api_key
• AWS Lambda：authorization.apikey、authorization.iam.accesskey、authorization.iam.secretkey
• OpenID Connect：client_rsa_private_key
• SAML Auth：secret_fallbacks

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.9.10，并在两侧都升级到 3.9.10 之前避免编辑这些插件。

新功能

插件

• AI Proxy、AI Proxy Multi
  • 新增 override.request_body 支持按协议深度合并请求体覆盖，以及 override.llm_options 提供感知提供商的 max_tokens 映射。运维人员可通过 request_body_force_override 标志将协议特定参数（如 max_tokens、stop_sequences）设置为默认值或强制值。优先级顺序：model options → LLM options（始终强制）→ request body（按协议深度合并）。这三个新增字段（request_body、llm_options、request_body_force_override）同样可在 AI Proxy Multi 每个实例的 instances[].override 下配置。
  • 新增 max_stream_duration_ms 和 max_response_bytes 安全限制，防止无界限的 LLM 流式响应导致 worker 进程 CPU 占用过高。超出任一限制时，流将被优雅终止并返回相应错误信号。
  • 网关现在可在流式传输过程中检测客户端断开连接，并立即停止从 LLM 上游读取数据，释放 worker 资源并避免不必要的 API 配额消耗。
• AI RAG
  • 新增顶层 ssl_verify 字段（默认为 true），用于控制插件调用 embeddings 和向量搜索服务时是否校验 TLS 证书。
• Prometheus、OpenTelemetry、Zipkin
  • 新增 response_source 标签（Prometheus）和 apisix.response_source span 属性（OpenTelemetry、Zipkin），用于分类每个响应的来源："apisix"（由 APISIX 生成，如插件拒绝或路由未找到）、"nginx"（NGINX 代理错误，如连接被拒绝或上游超时）或 "upstream"（来自上游服务的真实响应）。这使得在监控面板和告警中可以更精确地归因错误来源。

控制面

• 新增 Consul 服务发现支持。网关现在可以发现注册在 Consul 中的上游服务，支持基于元数据的过滤和健康检查感知的节点选择。
• 控制面现在可通过心跳动态推送遥测配置（如追踪采样率和导出端点）至数据面，无需重启网关。
• SSL/SNI 配置新增 skip_mtls_uri_regex 字段，允许指定的 URI 模式跳过 mTLS 客户端证书校验，同时对其他所有 URI 保持 mTLS 强制校验。
• 新增 POST /apisix/admin/configs/validate 批量配置校验接口。运维人员可在应用配置前校验路由、服务、上游和插件配置，在不影响线上流量的情况下捕获 schema 错误。
• DP Manager 现在在 7943 端口通过 cmux 支持原生 gRPC etcd 协议，为数据面在现有 HTTP etcd 协议基础上提供额外的连接选项。
• encrypt_fields 机制现在支持嵌套和复杂字段结构，包括任意深度的点分路径、数组和 map。包含深层嵌套敏感字段的插件配置（如 auth.gcp.service_account_json）现在可以正确加密存储。

控制台（Dashboard）

• Key Auth 和 Basic Auth 插件新增表单模式配置，支持可视化凭证设置，无需手动编辑 JSON。
• 新增 OpenID Connect 快速启动预设模板，为常见身份提供商提供预填充的配置模板，简化 OIDC 插件初始配置。
• 上游配置界面新增 Consul 作为可选的服务发现类型。
• SSL/SNI 配置界面支持配置 skip_mtls_uri_regex，允许指定 URI 模式跳过 mTLS 客户端证书校验。

缺陷修复

插件

• AI Proxy
  • 修复问题：当 LLM 提供商每秒发送大量小型 SSE 数据块（如单字符推理 Token）时，单个流式请求可能导致 worker 进程 CPU 占用率达到 100%，影响该 worker 上所有其他流量的可用性。
  • 修复问题：当协议转换器处于活跃状态（例如 Anthropic 转 OpenAI）且上游返回了格式不兼容的 SSE 事件时，网关返回 500 错误而非 502。现在当上游响应格式与配置的协议转换不兼容时，网关正确返回 502 Bad Gateway。
  • 修复问题：当 LLM 提供商在可空响应字段（如 prompt_tokens_details 或 usage）中返回 JSON null 时，网关崩溃，因为 JSON null 哨兵值通过了 Lua 真值检查但无法作为 table 索引。
• AI Rate Limiting
  • 修复问题：上游提供的用量键（来自 LLM 响应用量数据）与保留的表达式环境名称（如 math 或 abs）冲突时，可能遮蔽内置函数，导致限速表达式求值异常或绕过限制。

控制面

• 修复问题：通过开发者门户使用 OIDC 类型的 DCR 提供者创建 OAuth 凭证时，在要求 client_name 字段的身份提供者（如 Keycloak）上失败。client_name 现已包含在 DCR 注册和更新请求中，使用应用名称作为值。

Ingress Controller

• 修复问题：Ingress Controller 在翻译 ApisixRoute 资源时同时在 Route 和 Service 上设置了 hosts。对于不支持路由级 hosts 的后端，这会导致每个同步周期产生虚假差异，触发不必要的 PUT 请求并产生大量审计日志。在一个生产环境中，这导致了 8 GB / 420 万条冗余的 UpdateService 审计日志记录。

控制台（Dashboard）

• 修复问题：服务发现请求失败时，加载指示器持续显示不消失。
• 修复问题：IAM 删除角色操作使用了错误的权限动作（iam:UpdateRole 而非 iam:DeleteRole）。
• 修复问题：在上游配置中切换 Nacos 服务时，服务元数据未刷新。
• 修复问题：切换登录选项提供者类型时，上一个提供者的配置字段未清除，导致表单中残留旧值。
• 修复问题：IAM 策略语句编辑器在策略数据尚未加载时因空引用错误而崩溃。
• 修复问题：InviteUser 和 ResetPassword 操作在 API 调用失败时未显示错误信息，导致无法判断操作失败原因。
• 修复问题：登录选项名称唯一性检查不必要地加载了完整的登录选项列表，现改为轻量级 API 调用。

3.9.9

发布日期：2026-04-10

新功能

控制面

• Upstream 标签现在可通过 API 正确持久化和返回。此前，通过 ADC 或 Ingress Controller 设置的 upstream 标签在持久化过程中被静默丢弃，导致每次同步周期产生虚假差异和不必要的审计日志增长。
• 文件服务器地址现在可通过 Dashboard 系统设置页面动态配置，与 DP Manager 地址和 Admin API 地址使用相同的双数据源模式。

缺陷修复

插件

• AI Proxy
  • 修复问题：使用 AI Proxy 进行协议转换时（例如 Anthropic 客户端转 OpenAI 提供商），stream_options.include_usage=true 被注入到转换前的请求体而非转换后的 OpenAI 请求体中，导致转换协议的流式响应中缺少用量统计信息。
• Forward Auth
  • 修复问题：当认证服务返回 HTTP 200 但未包含 upstream_headers 中配置的某个请求头时，客户端原始请求中携带的该请求头值被直接转发到上游，而非被清除。这可能导致客户端通过在原始请求中携带该请求头来伪造上游请求头。
• JWT Auth
  • 修复问题：JWT Auth 插件在签名验证前未校验 JWT 的 alg 头是否与消费者配置的算法一致，可能导致算法混淆攻击。

数据面

• 修复问题：数据面兼容性报告对有效的插件配置显示了虚假的警告信息。使用 patternProperties、条件 schema（if/then/else）、allOf、dependencies 或 additionalProperties=true 的插件被错误地报告了"未识别字段"警告。受影响的插件包括 ai-proxy、ai-proxy-multi、openapi-to-mcp、acl、http-logger、limit-count-advanced、portal-auth、jwt-auth、proxy-rewrite 和 grpc-transcode。

3.9.8

发布日期：2026-04-07

不兼容变更

插件

• Limit Count

  升级说明

  limit-count 插件中的 sync_interval（Redis 延迟同步）功能已被移除，该功能现在仅在 Limit Count Advanced 插件中提供。如果你正在使用配置了 sync_interval 的 limit-count 插件，请在升级前将配置迁移至 limit-count-advanced 插件。

• OpenID Connect

  升级说明

  ssl_verify 的默认值已从 false 改为 true。如果你的 OpenID Connect 插件配置未显式设置 ssl_verify，且身份提供商（IdP）使用自签名证书或内部 CA 签发的证书，升级后 TLS 验证将失败。请在升级前为相关配置添加 "ssl_verify": false，或确保 IdP 证书已被网关的 CA 证书库信任。

新功能

插件

• MCP Tools ACL（新插件）
  • 新增用于 MCP 服务的工具级访问控制插件，适用于通过 OpenAPI-to-MCP 插件暴露的 MCP 服务。支持白名单（allow_tools）和黑名单（deny_tools）模式，并可通过表达式匹配条件实现路由级或服务级工具访问策略。支持消费者和消费者组的优先级规则评估。SSE 响应会自动过滤 tools/list 结果中被拒绝的工具。
• AI Proxy、AI Proxy Multi
  • 新增原生 Anthropic Messages API 支持。使用 Anthropic SDK 格式发送到 /v1/messages 的请求现在可直接透传至 Anthropic 兼容后端，无需协议转换，保留 Anthropic 特有的字段（如缓存 Token 用量）。
  • 新增 OpenAI Responses API（POST /v1/responses）完整支持。流式和非流式响应均可正确处理，所有下游插件（RAG、内容审核、Prompt Decorator、Prompt Guard、日志）均可与 Responses API 格式正常协作。两个插件共享同一套 AI 协议处理层，因此该能力同样适用于 ai-proxy-multi 路由。
• AI Rate Limiting
  • 新增 expression 限速策略，支持通过 cost_expr 字段使用自定义 Lua 算术表达式动态计算 Token 成本。例如，input_tokens + cache_creation_input_tokens 可实现 Anthropic Claude 的缓存感知输入 Token 每分钟（ITPM）限速。
• OAS Validator
  • 新增 OpenAPI 3.1 规范校验支持，包括 exclusiveMinimum/exclusiveMaximum 数值格式、if/then/else 条件 schema、["string", "null"] 可空类型、const、patternProperties、prefixItems 以及 JSON Schema $dynamicRef/$dynamicAnchor 等特性。
  • 新增可配置的 rejection_status_code 选项（400–599，默认 400），可区分语义校验错误（如 422 Unprocessable Entity）和请求格式错误（400 Bad Request）。
• Request ID
  • 新增 uuidv7 算法选项。UUID v7 生成按时间排序、字典序可排序的唯一标识符，比随机 UUID v4 更适合分布式追踪和日志关联。
• OpenAPI to MCP
  • 新增 OpenAPI in: header 参数支持。OpenAPI 规范中定义的 Header 参数现在可正确包含在 MCP 工具 schema 中，并在调用上游 API 时作为 HTTP 请求头转发。

控制面

• 新增 Vault 动态角色数据库凭证轮换支持。动态角色会创建具有可配置租约 TTL 的临时数据库用户，相比静态角色安全性更高。动态角色现为默认模式，并支持指数退避自动重试启动。
• 新增独立的文件服务器组件，用于托管 MCP 服务器可访问的文件。文件可通过 Dashboard API 上传，通过专用端口提供服务。文件服务器默认关闭，可在系统设置中启用。
• 新增 HTTP Bridge 动态客户端注册（DCR）提供者类型。HTTP Bridge 通过可配置的 HTTP 端点将 DCR 操作（注册、更新、删除、轮换密钥）代理至外部身份提供者。
• 新增数据面兼容性报告功能。当控制面与数据面版本不一致时，数据面通过心跳上报不兼容资源详情（schema 校验失败、未知插件字段、缺失插件），兼容性状态可通过运行时实例 API 查看。
• 发布服务时 upstream 配置现在为可选项，支持 AI Proxy 等无需后端 upstream 的纯插件场景。
• 优化自定义插件同步机制，采用增量缓存刷新。定时同步任务现在仅查询变更部分而非全表扫描，显著降低数据库负载。

数据面

• 优化 Redis Sentinel 连接性能。Master 节点地址现通过可配置 TTL 的本地缓存进行缓存，减少每次新建连接时对 Sentinel 的查询往返。此外，连接池中复用的连接跳过重复的 AUTH 和 SELECT DB 命令，降低高吞吐 Redis 操作的延迟。

开发者门户

• 新增管理员身份模拟功能。门户管理员可模拟组织 Owner 身份进行问题排查，模拟会话有效期 1 小时，模拟期间显示持久性警告横幅。
• 新增 HTTP Bridge 凭证的 OAuth 客户端密钥重新生成功能。组织 Owner 可通过凭证管理界面中的确认弹窗重新生成密钥。
• 新增可配置的 TOTP 双因素认证（2FA），用于开发者门户登录。
• 新增基于角色的访问控制（RBAC），包含三种角色：Owner（完全控制，包括删除组织）、Admin（除删除组织外的所有权限）和 Member（仅查看权限）。
• 组织设置页面现使用 slug 前缀 URL。切换组织或重命名组织 slug 时，页面 URL 自动更新。
• 应用详情页现根据门户配置文件中的设置展示相关配置。
• 新增可选的注册提示 HTML 插槽，用于在认证页面的注册按钮前展示自定义可信内容。

缺陷修复

插件

• AI Aliyun Content Moderation
  • 修复问题：空白内容导致阿里云审核 API 返回 400 错误。此外，LLM 错误响应（状态码 ≥ 400）在响应审核阶段触发 500 错误，多模态内容数组导致文本提取崩溃。
• AI Proxy
  • 修复问题：当插件通过 ngx.exit() 提前退出时，apisix_llm_active_connections Prometheus 指标永远不会递减，导致该指标持续增长并报告不准确的活跃连接数。
• AI Rate Limiting、Limit Conn、Limit Req
  • 修复问题：Redis 主机配置中的 $env:// 和 $secret:// 引用被当作字面字符串传递，未能解析为实际值，导致 Redis 连接失败。
• 修复问题：多个插件和 Agent 日志输出中，API 密钥、认证 Token、OAuth 凭证和完整插件配置以明文形式记录。敏感数据现已脱敏处理。

控制面

• 修复问题：当服务未配置 upstream 时，通过 PATCH 更新服务运行时配置（如切换服务状态）会因 schema 校验错误而失败。
• 修复问题：HTTP 和 Stream 子系统中同名插件共享同一缓存条目，导致两个子系统同时启用时使用了错误的插件 schema 进行校验。
• 修复问题：删除订阅时未校验订阅是否属于目标 API 产品，可跨 API 产品删除订阅。
• 修复问题：未配置 upstream 的服务在 upstream 列表 API 中显示了虚假的空 upstream 记录。
• 修复问题：升级迁移过程中处理未配置 upstream 的服务时，控制面因空指针引用而崩溃。
• 修复问题：同一开发者门户内的多个 API 产品可关联相同的网关服务（相同服务 ID 和网关组），导致配置冲突。
• 修复问题：更新 SSL 证书时，新增域名与已有证书的 SNI 冲突未被检测到。
• 修复问题：删除与其他 API 产品共享网关服务的 API 产品时，错误地移除了共享服务上的所有系统插件，破坏了其他产品的认证配置。
• 修复问题：DCR 提供者的认证 Header（如 Bearer Token）在数据库中未加密存储。
• 修复问题：由于值/指针接收者不匹配，消费者凭证的密钥未在审计日志中脱敏。
• 修复问题：审批处理器（接受/拒绝订阅）在返回 403 状态后继续执行，绕过了权限检查并处理了请求。
• 修复问题：开发者门户只读用户可取消 API 产品订阅，因为该接口使用了读权限检查而非写权限检查。
• 修复问题：路由和 Stream 路由运行时配置的 PATCH 操作使用了只读/仅查看权限检查，允许无写入权限的用户修改配置。
• 修复问题：upstream 资源未校验是否属于请求的服务，允许跨服务访问 upstream。
• 修复问题：CAS SSLVerify 配置标志被反转，导致配置启用 TLS 证书校验时实际被禁用，可能使 CAS 认证连接遭受中间人攻击。
• 修复问题：ADC 发起的并发请求导致路由校验器因未同步访问延迟初始化的 schema 缓存 map 而崩溃（concurrent map writes）。
• 修复问题：API 调用统计刷新在 IO 操作期间持有数据库锁，导致高流量下性能下降。刷新机制现使用交换释放和批量写入。

控制台（Dashboard）

• 修复问题：当服务名称为空或缺失时，Service Hub 页面和相关弹窗崩溃。
• 修复问题：将同一服务从不同网关组添加为关联服务时，被前端校验错误地阻止。

数据面

• 修复问题：DNS 解析间歇性返回错误的 IP 地址。当网关在缓存模式下运行时，DNS Additional section 中的记录（域名服务器 glue 记录）被错误地包含在解析结果中，且其域名被覆写为查询域名。这导致随机的上游连接失败，因为网关偶尔会选中域名服务器的 IP 而非实际服务 IP。
• 修复问题：使用 service_id 的 Stream 路由在引用的服务通过 etcd 同步晚于路由到达时静默失效。服务状态变更（启用/禁用）和删除也未触发 Stream 路由器重建。

开发者门户

• 修复问题：每个未认证请求都会生成 "No developer ID in session" 日志条目，导致生产日志被大量无效信息淹没，掩盖了真实错误。
• 修复问题：OIDC 提供者凭证的"重新生成密钥"选项显示为禁用状态而非隐藏。现在该选项仅对 HTTP Bridge 凭证可见。
• 修复问题：未注销直接重新登录后，Owner 角色未正确恢复，导致受角色限制的 UI 按钮显示为禁用状态，需手动刷新页面。

3.9.7

发布日期：2026-03-25

升级须知

升级说明 — 更多插件密钥字段在存储时加密

控制面现在会在存储时加密更多保存凭证的插件字段。由于 API7 EE 升级时先升级控制面、再升级数据面，在升级间隙中，3.9.7 的控制面会加密这些字段，而仍为 3.9.6 的旧数据面无法解密，可能导致相关插件失效，直到数据面也完成升级。

本次新增加密的字段，按插件列出如下：

• CSRF：key
• Kafka Proxy：sasl.password

如果你使用了上述插件的相关字段，请在控制面升级后尽快将数据面升级到 3.9.7，并在两侧都升级到 3.9.7 之前避免编辑这些插件。

新功能

插件

• AI Proxy
  • 新增 Anthropic 与 OpenAI 协议之间的双向透明转换。用户可以使用 Anthropic SDK 格式的请求访问 OpenAI 兼容的后端服务（如 DeepSeek、OpenRouter 等），网关自动完成请求和响应格式的转换，包括 SSE 流式传输。
• OpenAPI to MCP
  • 新增 MCP Tool Annotations 支持。通过 OpenAPI 规范中的 x-mcp-annotations 扩展字段，可为生成的 MCP 工具添加行为元数据标注（只读、破坏性、幂等等），帮助 AI Agent 更准确地理解和调用 API。

控制面

• Dashboard 新增 Limit Count 插件的图形化表单，支持 Local、Redis 和 Redis Cluster 三种策略的可视化配置，无需手动编辑 JSON/YAML。
• Dashboard 侧边栏新增自定义菜单分组功能，可通过 YAML 配置文件添加外部链接（如内部文档、Wiki 等）。
• 优化高频 API 调用场景下的数据库写入性能：通过写入防抖和内存缓存减少热路径操作（如 Token 使用时间戳、网关心跳时间戳等）的数据库写入频率，同时优化分布式锁获取延迟。

数据面

• Stream Proxy 的 TCP 和 UDP 监听器新增端口范围配置支持（如 2000-2100），大量代理端口场景下无需逐个列出端口号。
• CSRF 插件新增 encrypt_fields（key），Kafka Proxy 插件新增 encrypt_fields（sasl.password）。

缺陷修复

插件

• AI Proxy
  • 修复问题：当上游返回的 HTTP chunk 边界与 SSE 事件边界不对齐时，AI 请求的 Token 用量统计（prompt_tokens、completion_tokens）可能不准确。
• Prometheus
  • 修复问题：未启用 AI 插件的 API 路由在 Prometheus 监控中也产生 apisix_llm_* 系列指标，导致不必要的指标基数和存储开销。同时新增 disabled_labels 对 LLM 指标的支持，允许按需关闭高基数标签。

控制面

• 修复问题：多个并发 API 请求同时修改 Global Rule 时，仅最后一次写入的配置在网关中生效，尽管 Dashboard 显示所有修改均已成功。
• 修复问题：通过 ADC 同步包含非 HTTPS 主动健康检查的服务配置时，报错 Unrecognized key: "https_verify_certificate" 导致同步失败。
• 修复 Dashboard 中新增 Kubernetes 网关实例时 workers 数量的默认值为 1。

数据面

• 修复问题：网关 worker 进程重启（如异常崩溃）后，API 调用次数统计出现偏差。

3.9.6

发布日期：2026-03-09

新功能

插件

• Error Log Collect
  • 新增插件，支持错误日志的统一收集。
• OAS Validator
  • 新增参数 reject_if_not_match。当设置为 false 时，即使请求未通过 OAS 验证，也允许其转发至上游服务。
• Limit Count Advanced
  • 新增更多日志信息，方便调试。

控制面

• 资源名称 API 支持已发布的服务和路由。
• 在告警策略中，告警条件新增对服务和路由的支持。
• 支持通过 Vault 实现 Postgres 凭证的动态轮换。

数据面

• 新增 rate-limiting-info 变量，支持获取限流插件的详细状态信息。
• Docker 镜像加固：使用 distroless 作为基础镜像，并升级 busybox 以修复安全漏洞。

缺陷修复

插件

• Limit Count Advanced
  • 修复问题：同步函数发生 panic 时导致共享字典锁无法释放，导致同步中断。

3.9.5

发布日期：2026-02-14

新功能

插件

• Feishu Auth
  • 新增基于 OAuth 2.0 Authorization Code 流程的飞书认证插件，支持在工作台集成内部业务。
• Dingtalk Auth
  • 新增钉钉认证插件，认证过程记录关键日志，方便追踪认证过程。

控制面

• 每日许可证信息记录：控制面每天记录许可证的 CPU 限制、过期时间及当前核心数，并在到期前 3 个月开始提醒。用户可直接通过日志查看 CPU 用量。

• OpenTelemetry 数据收集与查看：控制面可向数据面下发调试和采样任务，接收上报数据，支持通过 API 导出及前端界面可视化展示。

  说明

  此功能引入了额外的组件 Jaeger。如果使用 Helm 部署，请注意控制平面的 values 文件默认会启用 Jaeger。官方 Helm Chart 仓库地址为：https://charts.api7.ai。

缺陷修复

数据面

• 修复问题：当插件的 encrypt_fields 包含带 maxLength 约束的 schema 字段时（如 hmac-auth 的 secret_key 最大 32 字符），由于 schema 校验在解密之前执行，加密后的密文超出了长度限制。

3.9.4

发布日期：2026-02-03

新功能

控制面

• 禁用 SCIM 后，允许在 API7 中删除从 IdP 同步过的 SCIM 历史用户。
• 上传 OpenAPI 文件现已支持 OpenAPI 3.1.0 和 3.1.1 版本。

缺陷修复

插件

• Limit Conn
  • 修复问题：在网关意外崩溃时，计数器数据不准确。

数据面

• 修复问题：当配置多个控制平面地址时，心跳和指标上报时仅会使用第一个连接地址。

控制面

• 修复问题：在路由的 URL 未以 / 开头时，冲突检测 API 会报 500 错误。
• 修复问题：插件配置代码编辑器中偶发代码提示失效。

3.9.3

发布日期：2026-01-26

新功能

插件

• AI Request Rewrite
  • 新增对 Gemini、Vertex AI 提供商的支持。
• SAML Auth
  • 新增 auth_protocol_binding_method 配置项，支持配置 SAML 协议绑定方法，支持 HTTP-POST 和 HTTP-Redirect 两种方式，默认为 HTTP-Redirect（兼容之前版本）。注意，当 Azure AD 作为身份提供商时，必须使用 HTTP-POST。

缺陷修复

插件

• SAML Auth

  • 修复问题：无法在多个网关实例间共享 SAML 会话。新增必填字段 secret 用于配置加密 session 数据的密钥。

    升级说明

    旧版本升级上来的 saml-auth 插件可以正常工作，但无法在多个网关实例间共享会话，配置 secret 后即可解决该问题。

  • 修复问题：执行登出请求时，SAML Request 中缺少 NameID 字段。注意，当 Azure AD 作为身份提供商时，缺少 NameID 字段会导致登出失败。

3.9.2

发布日期：2026-01-19

不兼容变更

插件

• OpenID Connect

  • 当 bearer_only 为 false（默认值）时，session.secret 字段现为必填项。此前未配置该字段时，每个数据面实例会各自自动生成随机密钥，导致会话无法在多个网关实例间共享。

    升级说明

    升级后，未配置 session.secret 的存量 openid-connect 插件配置（bearer_only 为 false 或未设置）将无法通过数据面的 schema 校验，其所在路由将停止服务。请在升级数据面之前配置 session.secret 字段（至少 16 个字符，所有网关实例使用相同的值）。

新功能

插件

• AI Proxy/AI Proxy Multi
  • 新增对 Gemini、Vertex AI、OpenRouter、Anthropic 四个提供商的支持。
• Basic Auth/JWT Auth/Key Auth/HMAC Auth/LDAP Auth
  • 新增 realm 配置项，用于在响应头 WWW-Authenticate 中设置 Realm 值。
• OpenID Connect
  • 支持通过配置 claim_schema 对声明进行校验。

控制面

• 禁止版本高于控制面的网关节点接入。
• 查询上游中节点健康检查状态的功能，现已支持多上游场景。

缺陷修复

插件

• Limit Count
  • 修复问题：在多个消费者中配置了相同的限流配置时，限流计数器被共享（3.8.5 引入）。
• Limit Count Advanced
  • 修复问题：重置请求头时出现数据错误（3.8.19 引入）。
  • 修复问题：开启 Redis 延迟同步功能后，限流数据未正确提交（3.8.19 引入）。
  • 修复问题：Redis Sentinel 模式下无法指定 Redis 密码。
  • 修复问题：Redis Sentinel 模式下连接 Redis 未启用连接保活。
• Syslog
  • 修复问题：在 UDP 模式下，发送一条超长日志后，后续日志发送阻塞。
• Request ID
  • 修复问题：在客户端传递的 request-id 为空字符串时，系统未自动生成新的 request ID。

数据面

• 修复问题：启动过程可能出现 deepcopy table overflow 错误。
• 修复问题：未启用 enable_server_tokens 时，server header 返回 APISIX。
• 修复问题：在 ai-proxy-multi 插件更新后，健康检查器导致网关持续输出错误日志。

控制面

• 修复问题：SSL 资源默认的 client.depth 过小，导致 Cloud v2 用户 mTLS 功能迁移失败。
• 修复问题：并发调用 SSL API 时可能引发数据重复。
• 修复问题：控制台中前端组件的健康状态未反映在 /healthz API 返回值中。

3.9.1

发布日期：2026-01-08

缺陷修复

开发者门户

• 修复在旧版本开发者门户中创建的“开发者”无法被删除的问题。

3.9.0

发布日期：2026-01-06

不兼容变更

开发者门户

• 全新重构的开发者门户

  升级说明

  开发者门户已完全重构。本版本包含以下不兼容变更，升级前需采取操作：

  • 内置的 Portal SSO 功能已被移除。请通过新的 Portal 级别认证机制配置认证。
  • Portal 前端现已开源。现有的 Portal 自定义配置需要迁移到基于 SDK 的新架构。

数据面

• 健康检查状态查询接口

  升级说明

  健康检查引擎已重写，控制接口 GET /v1/healthcheck 和 GET /v1/healthcheck/{src_type}/{src_id}（由数据面控制端口提供，默认 9090）的响应体结构发生变化，请求路径、方法和状态码保持不变。升级前请先更新解析这些响应的监控脚本、告警规则和仪表盘。

  3.8.x 及更早版本的响应：

  [
    {
      "name": "upstream#/apisix/upstreams/1",
      "src_type": "upstreams",
      "src_id": "1",
      "nodes": [
        { "host": "127.0.0.1", "port": 1980, "weight": 1, "priority": 0 },
        { "host": "127.0.0.2", "port": 1988, "weight": 1, "priority": 0 }
      ],
      "healthy_nodes": [
        { "host": "127.0.0.1", "port": 1980, "weight": 1, "priority": 0 }
      ]
    }
  ]

  3.9.0 及之后版本的响应：

  [
    {
      "name": "/apisix/upstreams/1",
      "type": "http",
      "nodes": [
        {
          "ip": "127.0.0.1",
          "port": 1980,
          "status": "healthy",
          "counter": { "success": 0, "http_failure": 0, "tcp_failure": 0, "timeout_failure": 0 }
        },
        {
          "ip": "127.0.0.2",
          "port": 1988,
          "status": "unhealthy",
          "counter": { "success": 0, "http_failure": 0, "tcp_failure": 2, "timeout_failure": 0 }
        }
      ]
    }
  ]

  逐字段说明：

  • 移除 src_type 和 src_id，资源改为仅通过 name 标识。
  • name 不再带 upstream# 前缀，其值为资源路径，例如 /apisix/upstreams/1。
  • 移除 healthy_nodes。nodes 中的每一项都带有各自的 status，取值为 healthy、unhealthy、mostly_healthy 或 mostly_unhealthy。节点处于服务中的条件是 status 为 healthy 或 mostly_healthy（mostly_healthy 表示节点出现过若干次探测失败但仍在接收流量），因此还原原先 healthy_nodes 列表的判断条件是 status == "healthy" || status == "mostly_healthy"。若仅按字面值 healthy 过滤，会漏掉网关仍在转发流量的节点。
  • nodes 中的元素不再描述上游配置中的节点（host、port、weight、priority），而是描述健康检查的探测目标：ip、port、status，以及记录连续 success、http_failure、tcp_failure 和 timeout_failure 次数的 counter 对象。当健康检查配置了 host 时，目标还会带 hostname；当探测请求改写了 Host 请求头时，还会带 hostheader。
  • 新增顶层字段 type，表示所配置的检查类型，例如 http、https 或 tcp。

  接口返回内容还有两处变化：

  • nodes 现在列出的是健康检查器注册的探测目标，而非上游配置中的节点。当 checks.active.host 或 checks.active.port 覆盖了节点地址时，多个上游节点会合并为同一个探测目标，因此该列表可能比上游的节点列表短。
  • 配置了 checks 的资源在加载后即会出现在结果中，在其健康检查器创建完成之前 nodes 为空列表。旧版本只有在健康检查器已存在时才会列出该资源。

新功能

• 所有 API7 企业版 Docker 镜像通过 Cosign 签名，提升镜像安全性。

开发者门户

• 提供开源 SDK 和前端脚手架项目，方便用户二次开发。
• 新增 Portal 级别认证机制用于对接 API。

插件

• Limit Conn/Limit Req

  • 支持使用 Redis 和 Redis Cluster 作为限流数据存储后端。
  升级说明

  • 新增必填字段：policy，已有配置无须修改，在数据面可以正常工作，但更新配置时需要补充该字段（policy=local），否则更新会被拒绝。

• Request ID

  • 新增 KSUID 生成器选项。

• Loki Logger

  • 支持自定义发送给 Loki 服务器的 HTTP 请求头。

• File Logger

  • 支持通过 match 字段匹配并记录指定的请求。

• Workflow

  • rules 字段现已设置为必填项。

控制面

• 允许在启用 SSO 登录后，完全禁用内置的用户名密码登录方式。
• 支持配置数据库语句的最大执行时间。
• 可观测性优化
  • 默认开启 pprof 性能分析功能。
  • 监控指标端点新增数据库连接池监控指标。
  • 支持分别记录访问日志和错误日志。
  • 访问日志和错误日志中增加 request_id 字段。

缺陷修复

插件

• OpenAPI to MCP
  • 修复问题：使用 query 参数传递认证参数可能导致敏感信息泄露。

数据面

• 优化 DNS 解析结果同时包含 CNAME 和 A 记录时的缓存行为。

控制面

• 在网关实例列表中展示 IP 和 Port，已移除，避免误导用户。
• 修复问题：在 API 调用次数统计表并发批量插入时可能引发数据库死锁的情况。
• 修复问题：在 PostgreSQL 中使用非 public schema 时控制台启动失败。

3.8.23

发布日期：2026-02-03

新功能

控制面

• 上传 OpenAPI 文件现已支持 OpenAPI 3.1.0 和 3.1.1 版本。

缺陷修复

数据面

• 修复问题：当配置多个控制平面地址时，心跳和指标上报时仅会使用第一个连接地址。

控制面

• 修复问题：在路由的 URL 未以 / 开头时，冲突检测 API 会报 500 错误。

3.8.22

发布日期：2026-01-19

缺陷修复

插件

• Limit Count
  • 修复问题：在多个消费者中配置了相同的限流配置时，限流计数器被共享（3.8.5 引入）。
• Limit Count Advanced
  • 修复问题：重置请求头时出现数据错误（3.8.19 引入）。
  • 修复问题：开启 Redis 延迟同步功能后，限流数据未正确提交（3.8.19 引入）。
  • 修复问题：Redis Sentinel 模式下无法指定 Redis 密码。
  • 修复问题：Redis Sentinel 模式下连接 Redis 未启用连接保活。
• Syslog
  • 修复问题：在 UDP 模式下，发送一条超长日志后，后续日志发送阻塞。
• Request ID
  • 修复问题：在客户端传递的 request-id 为空字符串时，系统未自动生成新的 request ID。

数据面

• 修复问题：启动过程可能出现 deepcopy table overflow 错误。

控制面

• 修复问题：SSL 资源默认的 client.depth 过小，导致 Cloud v2 用户 mTLS 功能迁移失败。
• 修复问题：并发调用 SSL API 时可能引发数据重复。

3.8.21

发布日期：2025-12-23

新功能

插件

• gRPC Web
  • 支持在使用非通配符路径的路由中启用 grpc-web 插件。
• OpenAPI to MCP
  • 提供 flatten_parameters 参数，以控制是否将 OpenAPI 中的路径和查询参数放在 tools input schema 的最顶层。

数据面

• Fallback CP
  • 支持使用网关作为备份节点，向 AWS S3 和 Azure Blob 同步数据。注意：备份节点不提供 HTTP/HTTPS 服务，不计入许可限额。
  • 支持使用 AWS IAM Role 和 Azure Managed Identity 进行身份验证。

控制面

• 支持使用 MSSQL Server 2022 作为控制面的数据库。
• 提供使用 docker compose 部署网关实例的脚本生成。
• 优化 kubernetes 部署网关实例时各个参数的文本提示。

缺陷修复

插件

• AI Proxy/AI Proxy Multi
  • 修复问题：插件中配置的 header 无法覆盖下游同名 header，即大小写不敏感的问题。
• Limit Conn/Limit Count Advanced/AI Rate Limiting
  • 修复问题：rules.key 无法使用变量默认值语法。
• OpenAPI to MCP
  • 修复问题：在 Cursor、Cline 等 AI 客户端中配置 MCP 服务器时出现报错或持续加载。

数据面

• 修复问题：网关在启动过程中连接控制面失败时仍然继续启动。
• 修复问题：网关在使用不同 IP 监听相同端口时出现的心跳失败。
• 修复问题：Fallback CP 功能无法正确加载凭证数据。
• 修复问题：优化 Prometheus 插件启用后的性能表现。

控制面

• 修复问题：通过 Admin API 创建的服务无法在控制台的监控页面选择路由及查看监控数据。
• 修复问题：上游配置了主动健康检查后，控制台的上游页面中“不健康比例”的数据错误。

3.8.20

发布日期：2025-12-11

缺陷修复

插件

• OpenAPI to MCP
  • 修复问题：未正确替换 base_url 字段的变量。

3.8.19

发布日期：2025-12-09

新功能

插件

• OpenAPI to MCP
  • 支持在 base_url 中使用变量语法。
• AI Rate Limiting

  • 支持使用 Redis、Redis Cluster、Redis Sentinel 作为存储。

    升级说明

    ai-rate-limiting 插件新增必填字段：policy。已有配置无须修改，在数据面可以正常工作；但更新配置时需要补充 policy=local 字段，否则更新会被拒绝。

数据面

• 变量系统支持使用 ${external_user.*} 语法获取外部用户信息的字段值。目前该变量由 openid-connect 插件及门户中的 OAuth 认证注入。

缺陷修复

插件

• AI Proxy/AI Proxy Multi
  • 修复问题：未向上游透传客户端或其他插件产生的请求头。
• AI Rate Limiting/Limit Count Advanced
  • 修复问题：多个 rules 同时命中时，限流 header 无法区分。默认通过 rules 的 index 进行区分，支持配置 header_prefix 来自定义前缀。
  • 修复问题：在 limit 字段中使用变量时，在变量值发生变化后，无法实时更新限流状态。

控制面

• 修复问题：用户的 Token 过期后仍然可以用于访问 API。
• 修复问题：控制台中创建路由时“标签”字段出现大量重复输入框。
• 修复问题：路由中禁用状态的插件无法覆盖服务中启用状态下的同名插件。
• 修复问题：控制台中 Portal 下拉选项值频繁变化。
• 修复问题：控制台中插件配置自动填充默认值。

3.8.18

发布日期：2025-11-25

important

为支持创建多个 Portal 实例，数据面的 Portal 认证插件（portal-auth）进行了升级。用户在升级控制面后应尽快升级数据面，在已升级控制面，还未完成数据面升级前，请勿更新已有的 API 产品，否则这部分变更将无法生效。

新功能

数据面

• 支持为监听端口指定 backlog 配置。
• fallback_cp 功能支持 Azure Blob 存储类型。

控制面

• 新增动态客户端注册（DCR）提供者管理功能。
• API 产品新增 DCR 认证类型。
• Developer Credential 新增 OAuth 认证类型（基于 DCR 获取 Client ID 和 Client Secret）。
• 支持创建多个 Portal 实例，已有 Portal 的使用数据会归属于系统自动创建的 default Portal 实例中。
• 控制台支持在配置文件中指定许可证的存放路径。

缺陷修复

数据面

• 所有日志插件
  • 修复问题：客户端请求体较大导致产生临时文件时，日志插件获取请求体失败。
• AI Proxy Multi
  • 修复问题：健康检查器在请求命中不同消费者时会触发重建。

控制面

• 修复问题：Ingress Controller 安装脚本中未锁定 Helm Chart 版本号。
• 修复问题：处于离线状态的网关实例展示兼容性标签。
• 修复问题：创建/更新上游时，pass_host 为 rewrite 时，未检查 upstream_host 是否为空。
• 修复问题：开发者门户中，当 OpenAPI 文档包含多个 server_url 时，开发者发起测试请求时无法选择 server_url。
• 修复问题：订阅状态为“待审批”的开发者，仍能向网关发起请求。

3.8.17

发布日期：2025-11-10

新功能

插件

• Limit Conn
  • 支持在 conn 和 burst 字段中使用变量语法。
  • 添加了一个 rules 字段，用于同时配置多个限流规则。
• Limit Count Advanced
  • 支持在 count 和 time_window 字段中使用变量语法。
  • 添加了一个 rules 字段，用于同时配置多个限流规则。
• AI Rate Limiting
  • 支持在 limit 和 time_window 字段中使用变量语法。
  • 添加了一个 rules 字段，用于同时配置多个限流规则。
• AI Proxy/AI Proxy Multi/AI Request Rewrite
  • 支持 aimlapi 供应商.
• OpenAPI to MCP
  • 在向上游服务发送请求时，考虑 OpenAPI 中定义的查询参数默认值。
• 所有访问日志记录插件
  • 支持配置 max_pending_entries，即批处理器中的最大待处理条目数。
  • 在工作进程退出前将待处理日志写入日志服务。

控制面

• 支持为访问 Dashboard 配置 IP 白名单和黑名单。

缺陷修复

数据面

• AI Proxy Multi
  • 修复问题：多个 worker 无法共享 AI 实例的健康检查器。

控制面

• 修复问题：当浏览器没有权限时无法上传许可证书。
• 修复问题：当上游节点数量非常多时网关转发性能不佳。
• 修复问题：插件如 limit-count 和 limit-count advanced 的 policy 字段是可选的（应为必填）。
• 修复问题：创建新的 SSO 页面并点击返回时，页面重定向到 SMTP Server 页。

3.8.16

发布日期：2025-10-28

新功能

插件

• Kafka Logger
  • SASL 机制支持 scram-sha-512。

数据面

• SSL 证书支持通配符 SNI 匹配，单个证书可覆盖多个子域名。

控制面

• API 门户支持在发布网关服务时指定 Host。
• 网关 secret 模块支持查询失败场景的缓存配置。
• Ingress Controller 安装表单支持配置命名空间和名称。
• 在 Dashboard UI 中导入 OpenAPI 时显示受支持的版本。
• 从网关部署页面移除裸金属 Linux 选项卡。

缺陷修复

插件

• OpenAPI to MCP
  • 修复问题：当服务中配置了 path_prefix 和 strip_path_prefix 时，SSE 模式不工作。
  • 修复问题：MCP 工具名称之前是根据 OpenAPI 路径生成的，因此可能超出工具名称的长度限制。现在，MCP 工具名称将根据 OpenAPI 操作 ID 生成。
  • 修复问题：如果未配置 headers 字段，将会抛出 500 状态码错误。

控制面

• 修复问题：当组名称相似时，ADC 同步可能会同步到错误的网关组。
• 修复问题：即使没有匹配的规则，登录选项角色映射也会保留之前的角色。
• 修复问题：OIDC 登录选项的请求范围字段中存在多余的添加按钮。
• 修复问题：旧配置有时不会显示在“编辑登录选项”表单中。
• 修复问题：由于核心资源架构过于复杂，ADC diff 比较期间会发生不必要的更改。
• 修复问题：更新用户角色时，用户的 updated_at 时间戳未刷新。

3.8.15

发布日期：2025-10-13

新功能

插件

• Lago
  • 新增插件。
• 在 Stream 类型 service 中支持 Traffic Split 插件。
• OpenAPI to MCP
  • 支持 streamable HTTP 作为 MCP 传输协议。

数据面

• 新增 GCP Secret Manager 作为密钥管理后端。

控制面

• 支持自定义 Prometheus 查询 API 的路径前缀。

缺陷修复

数据面

• 修复问题：为同一网关组创建多个GatewayProxy/IngressClass将导致资源冲突和路由覆盖。
• 修复问题：错误日志中包含敏感信息。
• 修复问题：grpc-web 在响应体为空时丢失 trailers 的问题。

3.8.14

发布日期：2025-09-25

缺陷修复

数据面

• 修复问题：在 Ingress Controller v2.0.6 中，配置多个服务且设置多个相同的后端时，出现上游引用错误。
• 修复问题：使用非 UTC 时区的 PostgreSQL 数据库时，网关实例状态计算错误。

3.8.13

发布日期: 2025-09-23

新功能

插件

• OpenAPI to MCP
  • 新增插件。

控制台（Dashboard）

• API7 Helm Chart 支持 Admin API 与 DPM 地址配置。

数据面

• DP Manager 支持配置 Prometheus remote write 端点 URL。
• Certificate Usage API 的返回字段现已与 OpenAPI 规范保持一致。

缺陷修复

控制台（Dashboard）

• 修复问题：API7 控制台集成内部登录邮箱时的提示信息处理。
• 修复问题：自定义插件 Schema 不合法时错误信息提示只在浏览器控制台显示，现支持在 API7 控制台展示。
• 修复问题：不同日志插件间 include_resp_body 配置相互干扰。
• 修复问题：前端控制台构建过程中出现的警告信息。

数据面

• 修复问题：密钥无法动态更新。

开发者门户

• 修复问题：在开发者门户中为使用 ADC 创建的服务创建产品时无法查询 OAS。
• 修复问题：在开发者门户中下载 OpenAPI 文档时的层级结构问题。

3.8.12

发布日期: 2025-09-17

缺陷修复

控制台（Dashboard）

• 修复问题：具有 service_label 范围策略的用户无法编辑相应服务或服务模板。
• 修复问题：服务模板的标签授权问题，在列表 API 授权过程中，不再错误地复用同 ID 已发布服务的标签。

3.8.11

发布日期: 2025-08-25

新功能

插件

• AI Request Rewrite
  • 新增插件。
• AI RAG
  • 新增插件。
• AI AWS Content Moderation
  • 新增插件。

控制台（Dashboard）

• 改进了根用户生成 Token 时的引导。UI 现在清晰地引导用户创建新用户并在该账号下生成 Token。
• 支持在企业版控制面通过配置开关启用 pprof。监听 127.0.0.1，默认关闭。

依赖项

• 在企业版离线发布包中包含了最新版本的 ADC。

缺陷修复

插件

• 自定义插件
  • 修复问题：上传缺少 schema 的自定义插件会返回 500。
• Basic Auth
  • 修复问题：将 scheme 部分（“Basic”）改为不区分大小写。
• AI Proxy Multi
  • 修复问题：流量分配异常。
• AI Prompt Decorator
  • 修复问题：用户历史消息被错误地追加到日志/配置的 messages 中。现在插件仅按预期插入系统提示。

数据面

• 修复问题：在 EWMA 负载均衡算法下，历史统计未被清理，可能耗尽分配的共享内存并导致错误。

控制台（Dashboard）

• 修复问题：用户在多设备登录时可能卡在许可证激活页。
• 修复问题：/plugins 键仅在自定义插件操作或控制台启动时写入，导致在新建网关组下创建新网关时无法从控制面同步已启用插件列表。现已正确创建该键。
• 修复问题：通过 ADC 创建服务时，路由冲突检查器未检测到跨不同服务的重复路由。
• 修复问题：UI 中较长的标签未完整显示。
• 修复问题：并发创建相同 ID 的服务可能导致重复创建。
• 修复问题：同时创建两条路由时，可能错误地提示对应的服务已存在。
• 修复问题：登录页在登录选项过多时，页头重叠且页面无法滚动。

3.8.10

发布日期: 2025-08-25

新功能

插件

• SOAP
  • 新增插件。

数据面

• 支持通过 API7 控制台的配置文件来配置 DP Manager 和 Admin API 的地址。

控制台（Dashboard）

• 支持在网关部署配置中指定 Admin API 地址，该地址将用于填充 API7 Ingress Controller 部署脚本中的 GatewayProxy 端点地址。
• 合并了 API7 控制台前端的 allow_access API 调用，以减少冗余请求。
• 在上游连接配置中增加了 hash_on 配置项。

缺陷修复

插件

• AI Proxy Multi
  • 修复问题：因与上游服务连接超时而引发 panic。
• 从企业版中移除了 ext-plugin-pre-req、ext-plugin-post-req 和 ext-plugin-post-resp 插件。

数据面

• 修复问题：当控制面更新服务 API 时，由于数据库连接不足可能导致死锁。
• 修复问题：重启后，工作进程可能会从主进程加载到旧数据。这可能导致在新创建或修改的路由上，工作进程从 etcd 同步最新数据前出现临时性请求失败（例如 404 错误）。
• 修复问题：etcd 的历史记录压缩可能会触发 APISIX 中的全量数据加载，从而对 etcd 服务造成显著的性能影响，尤其是在网关节点数量庞大的环境中。

控制台（Dashboard）

• 修复问题：当消费者的权限策略配置为基于标签授予所有权限时，无法创建该消费者。
• 修复问题：在消费者列表页面，分页偶尔会失败。尝试导航到另一页会导致短暂的加载状态，但视图仍停留在当前页面。

3.8.9

发布日期: 2025-08-11

新功能

插件

• JWT Auth
  • 新增 store_in_ctx 参数，用于在请求上下文中存储已验证的 JWT 对象。当设置为 true（默认为 false）时，插件会将已验证的 JWT 对象存储在请求上下文中，这对于需要解析 JWT 以提取权限的自定义插件非常有用。
• Workflow
  • 新增对 limit-conn 插件集成的支持，允许根据用户请求和当前 APISIX 负载压力动态调整连接限制策略。

数据面

• API7 企业版 Ingress Controller 支持 Kubernetes 1.18。
• 从 APISIX 迁移 Chaitin WAF 插件到 API7 企业版。

控制台（Dashboard）

• 新增审计日志记录 TTL 配置选项，允许用户设置审计日志表数据的自动删除时间。默认值为 60 天。
• 优化了更新缓存的消费者数据时数据面管理器（Dataplane manager）的 SQL 语句。

开发者门户

• 新增对 CAS 登录的支持。

缺陷修复

插件

• OAS Validator
  • 修复问题：当 verbose_errors 启用时，将详细响应错误的错误级别从 error 调整为 warn。
• JWT Auth
  • 修复问题：当设置 claims_to_verify: ["exp"] 时，插件无法验证 exp 声明。
• Consumer Restriction
  • 修复问题：改进了将 consumer-restriction 与 basic-auth 插件一起使用时的错误消息。当 type 设置为 consumer_group_id 并配置黑名单时，未被列入黑名单的消费者现在会收到适当的错误消息。
• Kafka Logger
  • 修复问题：在服务配置中启用 max_pending_entries 且存在大量路由时，性能下降。该问题是由于在服务和路由合并期间插件配置深度复制，导致每个路由创建单独的批处理器缓冲区。
• Limit Count Advanced
  • 修复问题：插件 panic 引发共享内存死锁。

数据面

• 修复问题：在 ctx 变量中读取请求体时，错误信息无法被正确记录。

控制台（Dashboard）

• 修复问题：从 OpenAPI 文件导入的中文标签显示为中文拼音而非原始中文字符。
• 修复问题：频繁切换路由后，路由信息偶尔会卡在加载状态。
• 修复问题：PUT API 会为不存在的消费者创建凭证。
• 修复问题：语言切换不一致，在登录页面切换到英文后，登录后会恢复为中文。

开发者门户

• 修复问题：SAML/OIDC 注销未从 IDP 登录状态正确签出。SSO 注销后，仅清除了控制面登录状态，而 IDP 登录状态仍然存在，导致再次点击 SSO 登录按钮时自动登录成功。

3.8.8

发布日期: 2025-07-28

新功能

数据面

• 支持 Consul 服务发现去重和节点排序。
• 支持在使用 radixtree_uri_with_parameter 路由时访问 uri_arg_ 变量。
• 将 API7-EE-3-Gateway 的基础镜像升级至 Ubuntu 24.04。

开发者门户

• 支持开发者在应用中查看当前 API 用量统计。
• 将 Scalar 升级至 0.7.25 版本。

依赖项

• 将 Casbin 升级至 1.41.9 版本。

控制台（Dashboard）

• 通过添加 config.controllerName 优化了 Ingress 网关组部署脚本。

缺陷修复

插件

• API Breaker
  • 修复问题：由于实现中的时间点（breaker_time）不准确，api-breaker 插件未能正确触发。
• AI Proxy
  • 新增 upstream_response_time 变量。

数据面

• 修复问题：由于健康检查数据导致 routes() 响应数据损坏。
• 修复问题：grpc-web 响应可能包含重复的 trailer chunk。
• 修复问题：proxy-cache 插件中不同策略的响应头不一致。

控制台（Dashboard）

• 修复问题：并发请求为新网关组生成部署脚本可能导致 admin key 重复生成。
• 修复问题：在不同路由间重复点击 “查看 ID” 会导致路由 ID 重复生成。
• 修复问题：资源详情中的创建和更新时间戳位置不正确。
• 修复问题：已发布服务中的插件操作（创建/删除/编辑）未记录审计日志。
• 修复问题：由于服务器时间戳异常导致 CAS 登录期间无限重定向。
• 修复问题：监控页面上的资源选择器过窄，导致文本截断。

3.8.7

发布日期: 2025-07-17

新功能

插件

• Limit Count Advanced
  • 新增支持 Redis Sentinel 模式。

数据面

• 支持组件升级顺序控制，确保 dp-manager 在数据库迁移完成后启动。

控制台（Dashboard）

• 支持 OpenAPI 编辑器预填充服务 OpenAPI 规范的历史数据，避免简单修改时需重新完整输入。
• 支持配置并默认启用内容安全策略（CSP）。
• 支持同时显示 Gateway API 和 Ingress 部署脚本（针对 Ingress Controller 网关组）。

开发者门户

• 支持在服务提供商门户中删除开发者账号。
• 新增“应用”资源，支持在应用层级管理 API 产品订阅与凭证。

缺陷修复

插件

• Zipkin
  • 修复问题：access.log 中 zipkin_trace_id 显示乱码。
• Forward Auth
  • 修复问题：使用 forward-auth 插件转发 POST 请求可能会导致请求主体丢失，从而引发 504 错误。通过引入 extra_headers 解决了此问题。

安全

• 修复问题：部分控制面接口（/api/license、/api/system_infos、/api/developer-portal-url）未授权即可访问。

数据面

• 修复问题：delay_encode 在同一日志行中仅能使用一次。
• 修复问题：因证书问题导致启动后指标上报失败。

控制台（Dashboard）

• 修复问题：编辑自定义插件时删除源代码会清空整个表单。

开发者门户

• 修复问题：未认证用户筛选已订阅 API 产品后仍可见不可订阅产品。
• 修复问题：移除单一筛选条件下 API 产品的"清除所有"按钮，因其功能与选择"全部"条件重复。

3.8.6

发布时间: 2025-06-27

新功能

插件

• Elasticsearch Logger
  • 新增对 Elasticsearch 9.0.2 的支持。

缺陷修复

数据面

• 修复问题：执行 quit 或 reload 命令时工作进程未退出。
• 修复问题：错误地允许了大于 65535 的端口值。
• 修复问题：当键包含特殊字符时，etcd 数据同步失败。
• 修复问题：Kubernetes 服务发现由于 watch 进度重新列出所有数据导致性能下降。
• 修复问题：Kafka Logger 中存在内存泄漏，导致 nginx 工作进程崩溃。

控制台（Dashboard）

• 修复问题：点击插件的“删除”按钮只会禁用插件而不是删除插件。
• 修复问题：当使用 Kubernetes 服务发现时，上游缺少命名空间或服务数据。

安全

• 修复问题：TLSv1.3 跨 SNI 会话恢复漏洞（从 nginx 1.21.4 回退 HTTP 修复）。

3.8.5

发布日期: 2025-06-16

新功能

控制台（Dashboard）

• 在状态码相关告警事件中，为告警信息添加了路由 URI 信息。

缺陷修复

依赖项

• 将 OpenSSL 从 3.2.3 版本升级至 3.2.4 版本。
• 将 Debian 基础镜像升级至 Bookworm 版本。

数据面

• 修复问题：当 OAS 插件规范文件过大时会导致严重的性能影响。
• 修复问题：当 content-type 包含 charset 时，post_arg 匹配失败。
• 修复问题：在 limit-count 插件中，消费者未共享相同的计数器。
• 修复问题：缺少 etcd 的 init_dir 会导致无法列出资源。
• 修复问题：在 jwt-auth 插件中，real_payload 可能被恶意负载覆盖。
• 修复问题：upstream_schema 中存在错误的变量和冗余的 TLS 配置。

控制台（Dashboard）

• 修复问题：服务中的路由插件更新会错误地覆盖现有插件。

3.8.4

发布日期: 2025-06-11

缺陷修复

数据面

• 优化了控制面升级时数据量较大的表迁移的速度。
• 为 post_arg 添加了缓存逻辑以优化性能，避免重复的低效解析。
• 修复问题：以 http_ 和 graph_ 为前缀的 ctx 变量缓存未生效。
• 修复问题：降级恢复后 Prometheus 指标未正确保留。

控制台（Dashboard）

• 修复问题：插件的编辑方式（表单或代码）未正确显示。
• 修复问题：Response Rewrite 插件编辑器中的代码提示错误。

3.8.3

发布日期: 2025-06-04

新功能

数据面

• 支持在 conf/config.yaml 中配置 apisix.disable_upstream_healthcheck，通过单个开关禁用所有健康检查。
• 通过减少内存消耗优化 Prometheus 性能。
• 发布了 API7 Ingress Controller 2.0。

插件

• 自动在自定义插件模式中插入 _meta 字段。

控制台（Dashboard）

• 优化了 Ingress Controller 类型网关组的部署流程。
• 新增许可证即将过期的告警策略触发事件。

缺陷修复

数据面

• 修复问题：当使用 post_arg 读取 GraphQL 请求体时偶尔出现路由匹配错误。

控制台（Dashboard）

• 修复问题：升级依赖 ramda 至 0.30.1 和 cross-spawn 至 7.0.5 以避免高危漏洞。
• 修复问题：使用控制台表单配置 cors 插件详情时 max-age 字段显示不正确。
• 修复问题：当 ADC 从 17.x 版本升级到 19.x 后，如果同时更新同一服务下的多条路由，控制台仍显示过时的配置。
• 修复问题：在控制台中，拥有 gateway:GetPublishedService 或 gateway:GetServiceTemplate 权限的用户无法查看服务内的插件配置。
• 修复问题：当两个自定义插件包含错误代码时，API7 企业版内置插件无法正常工作。
• 修复问题：Kubernetes 服务发现在上游节点数量较多时出现性能问题。
• 修复问题：表格表头大小写不一致，现已统一为首字母大写格式。

3.8.2

发布日期: 2025-05-19

新功能

插件

• AI Proxy Multi
  • 新增对 429/5xx 响应码的重试逻辑，提高请求成功率。

AI 网关

• 新增支持反向代理 AzureAI 服务。

控制台（Dashboard）

• 支持 CAS 作为 API7 企业版的 SSO 登录选项。

缺陷修复

控制台（Dashboard）

• 修复问题：已发布服务在编辑基本信息时报错。
• 修复问题：retry_timeout 和 retries 不能在 Stream 类型服务上游编辑。
• 修复问题：当网关实例缺少兼容性字段时页面崩溃。

数据面

• 修复问题：standalone 模式下使用大体积的配置文件时启动时间过长。
• 修复问题：OAS Validator 插件错误拒绝 1.11-1.19 范围内符合 multipleOf: 0.01 规则的数字。
• 修复问题：AI Proxy 插件会接受无效的端点 URL（例如，“http//localhost” 缺少冒号的情况）。

3.8.1

发布日期: 2025-05-07

新功能

插件

• Limit Count Advanced
  • 当 Redis 不可用时，自动回退到本地 shared dict，防止 Redis 故障期间请求失败。

数据面

• 支持 Stream（四层）路由的主动和被动健康检查。

控制台（Dashboard）

• 在添加网关实例时，指定网关实例证书的有效期。
• 在网关实例列表中，当证书即将过期时添加警告提示。
• 支持在控制台中查看网关实例的证书续期方法，并生成新的网关实例证书。

缺陷修复

数据面

• 修复问题：使用 TCP 服务时健康检查未按预期工作，请求仍被转发到不健康的上游节点。
• 修复问题：由于 Redis 服务故障导致网关请求延迟高。
• 修复问题：AI Gateway 中 llm_time_to_first_token 默认值判断错误。

插件

• 移除 request-id 插件的 snowflake 算法，因其存在潜在风险。

控制台（Dashboard）

• 修复问题：监控页面上的总带宽图表数据与 Prometheus 不一致。
• 修复问题：当启用强制发布时，已发布服务中不允许修改路由的超时和插件配置。

3.8.0

发布日期: 2025-04-22

新功能

数据面

• 支持在路由条件中使用用户请求体中数组对象的值。虽然 post_arg 已在路由条件中允许使用，但本次更新引入了对类型字段位置的数组场景支持。
• 支持在访问日志中记录额外的 AI 请求上下文信息。
• 支持向 Prometheus 指标添加请求类型标识符，以收集更细粒度的 AI 请求数据。

插件

• AI Proxy
  • 实现了新的标识字段 logging 和 summaries，用于收集 LLM 请求和响应内容。
• AI Proxy Multi
  • 支持 HTTP POST 方法的健康检查。
  • 如果触发了回退，则在警告日志级别显示记录。
  • 实现了新的标识字段，用于收集 LLM 请求和响应内容。
• AI Aliyun Content Moderation
  • 新增对流式（HTTP SSE）场景的支持。
• AI Prompt Guard
  • 新增插件。
• Kafka Logger
  • 支持读取缓存在 ctx 中的用户请求和响应体内容，并将其推送到指定的 Kafka 服务。

控制台（Dashboard）

• 在状态码告警消息中添加了服务名称和路由名称的详细统计信息。
• 优化插件配置：在服务或路由上配置 Traffic Split 插件时，验证配置的 upstream_id 确实属于当前服务的上游。
• 在已发布服务中将上游连接配置字段名称与 API 对齐。
• 为 CORS 插件配置引入了基于表单的 UI。

缺陷修复

数据面

• 修复问题：当上游类型为 Kubernetes 服务发现时，健康检查中的节点在节点变更后未更新，导致大量健康检查失败日志。
• 修复问题：当 Kubernetes 服务发现的 shared_size 参数调整为 100m 时出现错误。#11857
• 修复问题：使用 Kubernetes 发现的 APISIX/API7 企业版在 Token 文件过期后会失败。#11779
• 修复问题：更新 Vault Secret 提供商的 prefix 后，数据面仍使用旧配置。

控制台（Dashboard）

• 修复问题：上游中的 retries 字段被错误地设置为必填。
• 修复问题：由于缺少服务模板权限，已发布服务页面出现错误。
• 修复问题：在已发布服务中更新服务发现的服务名称未生效。
• 修复问题：快速点击创建多条记录。
• 修复问题：使用大规模消费者时数据库 CPU 使用率高。
• 优化 Permission Policy 的通配符配置方法：
  • 现在支持在授权语句中使用 * 进行通配符配置，其含义与当前的 <.*> 相同；
  • 限制星号 * 不允许出现在任何资源 ID 字段中，以防止授权失败。

3.7.8

发布日期: 2025-06-16

缺陷修复

控制台（Dashboard）

• 修复问题：服务中的路由插件更新会错误地覆盖现有插件。

3.7.7

发布日期: 2025-06-11

缺陷修复

数据面

• 优化了控制面升级时数据量较大的表迁移的速度。

3.7.6

发布日期: 2025-06-04

缺陷修复

数据面

• 修复问题：Kubernetes 服务发现在上游节点数量较多时出现性能问题。

控制台（Dashboard）

• 修复问题：当两个自定义插件包含错误代码时，API7 企业版内置插件无法正常工作。
• 修复问题：当 ADC 从 17.x 版本升级到 19.x 后，如果同时更新同一服务下的多条路由，控制台仍显示过时的配置。

3.7.5

发布日期: 2025-05-19

缺陷修复

控制台（Dashboard）

• 修复问题：已发布服务在编辑基本信息时报错。

数据面

• 修复问题：standalone 模式下使用大体积的配置文件时启动时间过长。
• 修复问题：OAS Validator 插件错误拒绝 1.11-1.19 范围内符合 multipleOf: 0.01 规则的数字。

3.7.4

发布日期: 2025-04-30

新功能

控制台（Dashboard）

• 在添加网关实例时，指定网关实例证书的有效期。
• 在网关实例列表中，当证书即将过期时添加警告提示。
• 支持在控制台中查看网关实例的证书续期方法，并生成新的网关实例证书。

缺陷修复

数据面

• 修复问题：使用 TCP 服务时健康检查未按预期工作，请求仍被转发到不健康的上游节点。
• 修复问题：由于 Redis 服务故障导致网关请求延迟高。
• 修复问题：AI Gateway 中 llm_time_to_first_token 默认值判断错误。

插件

• 移除 request-id 插件的 snowflake 算法，因其存在潜在风险。

控制台（Dashboard）

• 修复问题：监控页面上的总带宽图表数据与 Prometheus 不一致。
• 修复问题：当启用强制发布时，已发布服务中不允许修改路由的超时和插件配置。

3.7.3

发布日期: 2025-04-22

缺陷修复

控制台（Dashboard）

• 修复问题：使用大规模消费者时数据库 CPU 使用率高。
• 优化 Permission Policy 的通配符配置方法：
  • 现在支持在授权语句中使用 * 进行通配符配置，其含义与当前的 <.*> 相同；
  • 限制星号 * 不允许出现在任何资源 ID 字段中，以防止授权失败。

3.7.2

发布日期: 2025-03-24

缺陷修复

插件

• OpenTelemetry
  • 修复问题：动态路由 /v2/:customerNumber 上的 404 响应导致报告路径为空。

管理 API

• 修复问题：资源缺乏一致的 name 和 desc 长度限制（最多 65535 个字符），导致用户输入有效长字符串时出错。

控制台（Dashboard）

• 修复问题：用户在数据库存储后看到的是加密密文，而非原始明文输入的服务和路由敏感字段。
• 修复问题：控制台重启后，之前删除的默认网关组被错误地重新生成。
• 修复问题：Token 名称更新未在通知区域展示。

依赖项

• 升级至 Go 1.23。
• 升级至 Next.js 14.2.25 以解决 CVE-2025-29927。

3.7.1

发布日期: 2025-03-14

缺陷修复

插件

• OpenID Connect
  • 修复问题：无法配置验证颁发者。
  • 修复问题：无法验证受众声明。#11018。

3.7.0

发布日期: 2025-03-10

新功能

数据面

• 引用 Kubernetes Secret 中的密钥：Secret 提供商现在支持 Kubernetes Secret。这允许您从 Kubernetes Secret 中引用敏感值，用于 SSL 证书、SSL 私钥、消费者凭据和各种插件配置。

插件

• AI Rate Limiting
  • 引入新的 AI 插件，用于对发送到 LLM 服务的请求实施基于 Token 的速率限制。它通过控制指定时间范围内消耗的 Token 数量来管理 API 使用，确保资源公平分配并防止服务过载。通常与 AI Proxy Multi 插件一起使用。
• AI Proxy
  • 支持 openai 兼容的提供者。
  • 支持代理嵌入模型 API。
• AI Proxy Multi
  • 支持 openai 兼容的提供者。
  • 支持在使用插件时绕过上游配置。
  • 支持主动健康检查。
  • 支持代理嵌入模型 API。

控制台（Dashboard）

• 支持引用 Kubernetes Secret 中的特定密钥：详情请参阅 引用 Kubernetes Secret 中的密钥。
• 为所有表格添加页面大小选择器。
• 在服务页面标题中显示服务 ID 和服务模板 ID，在路由页面标题中显示路由 ID 和路由模板 ID。

管理 API

• 新增引用 Kubernetes Secret 中的密钥相关 API：
  • 获取网关组上的 Kubernetes Secret 提供商。
  • 更新网关组上的 Kubernetes Secret 提供商。
  • 删除网关组上的 Kubernetes Secret 提供商。

缺陷修复

数据面

• 修复问题：重复的网关实例 ID 导致 CPU 计数不准确。

控制台（Dashboard）

• 修复问题：由于 SMTP 服务器配置中的 From Name 格式无效，导致告警邮件发送失败。
• 修复问题：删除自定义插件时未删除插件元数据。
• 修复问题：手动添加流服务时未移除 Skip Path Prefix 字段。
• 修复问题：路由的优先级不能设置为负数。

3.6.1

发布日期: 2025-03-14

缺陷修复

插件

• Limit Count Advanced
  • 修复问题：在负载测试期间间歇性出现 500 错误。
• OpenID Connect
  • 修复问题：插件不支持配置验证颁发者。

3.6.0

发布日期: 2025-02-26

重大变更

• 移除服务模板中的服务运行时配置，以便更好地跨网关组重用模板。服务模板中现有的服务运行时配置将被移除，但您的已发布服务配置将保持不变。 此外，发布流程得到简化和优化，发布过程中不允许配置服务运行时配置。请参阅更新的发布服务指南。

新功能

数据面

• 支持配置上游 mTLS：详情请参阅配置 API7 企业版与上游之间的 mTLS。

控制台（Dashboard）

• 支持使用邮箱登录：API7 企业版控制台现在支持使用用户名或邮箱地址和密码登录。要使用邮箱登录或接收通知，请将邮箱地址绑定到您的用户资料。
• 支持为上游配置 mTLS。
• 支持引用环境变量作为 SSO 连接信息。
• 为插件配置引入基于表单的 UI。
• 将 Basic Authentication 添加为开发者门户凭据的认证选项。如果 API 产品允许多种认证类型，则可以使用任何有效的凭据。

缺陷修复

数据面

• 修复问题：更新 upstream.nodes 时的竞态条件问题。#11916。
• 修复服务发现问题：在克隆节点表后填充节点信息结构时，上游 original_nodes 未更新。#10722。

3.5.5

发布日期: 2025-03-14

缺陷修复

插件

• Limit Count Advanced
  • 修复问题：在负载测试期间间歇性出现 500 错误。
• OpenID Connect
  • 修复问题：插件不支持配置验证颁发者。
  • 修复问题：无法验证受众声明。#11018

3.5.4

发布日期: 2025-03-07

缺陷修复

插件

• Elasticsearch Logger
  • 修复问题：插件无法配置索引以根据当前日期动态发送数据。

控制台（Dashboard）

• 修复问题：使用模板重新发布可能导致上游配置丢失。
• 修复问题：使用 ADC 重建服务后，页面上的 OpenAPI 缓存失效失败。
• 优化慢查询。

3.5.3

发布日期: 2025-02-18

缺陷修复

• 修复问题：告警邮件主题不能包含变量。

3.5.2 版本

发布日期： 2025-02-13

缺陷修复

• 修复了问题：无法启用 log rotate 插件。
• 修复了问题：在升级过程中，尤其是在使用 MySQL 数据库时，网关实例中偶尔会出现重复数据。
• 修复了问题：删除自定义插件偶尔会失败。

3.5.1 版本

发布日期： 2025-02-06

缺陷修复

• 修复了问题：无法配置 Azure SMTP 服务器发送警报电子邮件。
• 支持在 OTEL 插件报告动态路由 /v2/:customerNumber 时将 request.url 报告为 route.url。

3.5.0 版本

发布日期： 2025-01-27

新功能

服务中的多个上游

对于高级场景，例如灰度部署、蓝绿部署或管理多个集群，服务现在可以使用多个上游。在这种情况下，默认上游充当大多数请求的主要目标，而其他上游可用于特定目的，例如将流量路由到灰度部署或辅助集群。有关详细信息，请参阅更新后的配置灰度流量转移。

信息

旧的 灰度规则 功能不再可用。

功能优化

• 支持通过 Prometheus 插件元数据自定义配置 DP 指标标签。
• 优化了数据面 Prometheus 指标报告的性能。
• 禁止由于超过许可证 CPU 限制而创建新资源。
• 为 API7 门户的控制台页面添加了页面大小选择。
• 支持 YAML/JSON 格式的插件配置。
• 改进了上游健康检查配置的 UI。
• [Beta] 为上游配置了 mTLS。API 支持当前可用。完整支持即将推出。

缺陷修复

• 修复了问题：Traffic Split 插件的 LRU 缓存对象创建函数导致客户端请求异常。
• 将“启用/禁用插件”重命名为“新增/删除插件”以提高准确性。

3.4.1 版本

发布日期： 2025-01-14

缺陷修复

• 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。
• 修复了问题：在 DP 中配置 access_log_format 并将 access_log_format_escape 设置为 json 时，结果会附加一个额外的 request_id。

3.4.0 版本

发布日期： 2025-01-07

新功能

SNI 管理

引入了 SNI 作为管理 TLS 和 mTLS 身份验证以及证书匹配的新机制。有关详细信息，请参阅 在客户端和 API7 网关之间配置 mTLS。

API7 门户监控

提供监控数据和可视化，以跟踪 API 产品指标。

功能优化

• 自定义插件配置现在应用于网关组级别。有关详细信息，请参阅 添加自定义插件。
• 数据面升级到 LuaJit 2.1-20240815。
• 删除了 grpc-client-nginx-module。

缺陷修复

• 修复了问题：Redis 延迟同步功能使用的共享内存泄漏。
• 修复了问题：批量发布超多 service 时审计日志记录失败。

3.3.3 版本

发布日期： 2025-01-14

缺陷修复

• 修复了问题：在 API7 门户中使用 BasicAuth 身份验证进行在线调试时，粘贴密码失败。
• 修复了问题：在 DP 中配置 access_log_format 并将 access_log_format_escape 设置为 json 时，结果会附加一个额外的 request_id。

3.3.2 版本

发布日期： 2024-12-24

缺陷修复

• 修复了问题：从 3.2.16.2 或更旧版本升级到 3.3.1 及更高版本时，控制台无法启动。

3.3.1 版本

发布日期： 2024-12-19

缺陷修复

• 修复了问题：运行在 rewrite 阶段的插件在命中消费者后会重复执行。

3.3.0 版本

发布日期： 2024-12-16

新功能

API7 门户

宣布 API7 门户正式发布 (GA)，这是一个用于 API 发现和使用的综合解决方案。探索 API7 门户 和 开发者 的关键概念，并开始你的 服务产品化 之旅。

功能优化

• 为 OpenID Connect 插件同步了开源代码。
• 在访问日志和错误日志中记录请求 ID。
• 重构了数据面中的过期和淘汰机制。
• 当告警策略未配置通知通道时，在告警历史记录中添加了提示。
• 支持与外部 Prometheus 指标集成。

安全

• 解决了 CVE 报告中的漏洞。

缺陷修复

• 解决了问题：数据面到 DPM 的消费者查询（404 错误除外）不应被缓存。
• 解决了问题：禁用 API7 集成身份验证后，登录页面上的密码登录不可用。
• 修复了插件全局规则搜索问题。

3.2.16.7 版本

发布日期： 2024-12-13

缺陷修复

• 修复了问题：当 DP 管理器收到截断的 Prometheus 指标时，它会进入无限循环。
• 修复了问题：由于 watch 中断，数据面与控制面的同步可能会中断。
• 修复了问题：速率限制插件的 Redis 延迟同步功能对于低频请求无法按预期工作。
• 修复了问题：Limit Count Advanced 插件使用的共享内存存在故障。
• 修复了问题：radixtree_uri_with_parameter 无法匹配包含带有特殊字符的路径参数的请求。
• 修复了问题：Limit Count Advanced 插件滑动窗口中的剩余值应向下舍入，重置值应保留两位小数。

3.2.16.6 版本

发布日期： 2024-11-25

功能优化

• JWT Auth 插件支持 key_claim_name。
• 为监控添加了网关组过滤。

缺陷修复

• 解决了告警页面中的 UI 问题。
• 解决了问题：多个数据面容器在控制面中被识别为单个实例，这损害了许可证控制功能和一些指标报告显示功能。
• 解决了问题：发布大量服务时，审计日志无法记录。
• 修改了 SSL 证书到期告警条件文本。
• 解决了问题：由于节点 IP 地址未更新，导致健康检查失败。
• 将插件中 Lua 代码合法性的验证添加到控制面代码中。
• 为 Multi Auth 插件添加了子插件错误消息的记录。
• 删除了 Basic Auth 插件中的额外警告日志。
• 修复了添加新凭据时 Secret 提供商的权限验证错误。
• 修复了问题：在网关组上添加的已发布服务缺少 skip path prefix 配置项。

3.2.16.5 版本

发布日期： 2024-11-21

功能优化

• 为 Body Transformer 插件添加了 multipart content type。
• 将资源 ID 长度限制从 64 调整为 256。
• Workflow 插件支持 limit-count-advanced 作为操作项。
• 重构了 core.response.exit 以阐明参数定义。
• 在请求上下文中记录已执行的插件，以确保在使用 Workflow 插件时，同一插件仅被执行一次。

缺陷修复

• 解决了问题：在 Prometheus 插件中启用 prefer_name 选项将导致监控页面上的过滤器发生故障。
• 解决了问题：匹配匿名消费者时，不会将 x-consumer-custom-id 标头添加到请求中。
• 解决了问题：当同时配置时，Body Transformer 插件和 CORS 插件会导致 OPTIONS 请求出错。
• 临时删除了 Exit Transformer 插件中的沙箱机制。

3.2.16.4 版本

发布日期： 2024-11-01

新功能

通过电子邮件发送通知

告警策略现在可以通过利用新的联系人同时通过 webhook 和电子邮件发送通知。联系人 定义了一组可由多个告警策略使用的电子邮件地址或 webhook URL。

有关说明，请参阅触发网关告警。

备注

现有的 Webhook 模板 将迁移到新的联系人和告警策略内的通知，确保告警策略的无缝过渡和向后兼容性。

新的 Limit Count Advanced 插件

使用滑动窗口算法增强了开源的 limit count 插件，以实现更准确的速率限制。

有关详细信息，请参阅 Limit Count Advanced插件。

新的 Exit Transformer 插件

Exit Transformer 插件支持根据 APISIX 插件返回的状态码、标头和正文来自定义网关响应。当配置为全局插件时，它还支持在请求不存在的路由时自定义响应。

通过告警策略计算网关组中的健康网关实例数

如果网关组中健康网关实例的数量低于临界阈值，则表明可能会出现服务中断并影响流量处理。 这种情况在 Kubernetes 部署中尤其重要，因为网关实例可能会遇到故障或意外缩减。

创建用于统计网关组中健康网关实例数的告警策略 并向相关人员发送通知。

功能优化

• JWT Auth 插件 现在支持更多算法。
• 支持利用表达式匹配来更精确地路由流量。
• 在 Grafana 控制台模板 中丰富了更多指标。
• 允许用户按 Enter 键登录。

缺陷修复

• 解决了问题：CORS插件 expose_header 的默认值不应为 *。
• 解决了问题：添加四层服务时可以成功添加第一个四层路由。
• 解决了问题：max_req_body_bytes 限制在日志记录器插件中不起作用。
• 解决了问题：Limit Count 插件中速率限制参数的动态更新现在会反映在数据面中。
• 解决了问题：通过 API 删除的服务可以从数据面中一致地删除。

3.2.16.3 版本

发布日期： 2024-10-21

新功能

引用在 AWS Secrets Manager 中的密钥（Secrets）

密钥（Secrets） 对象是一条需要防止未经授权访问的敏感信息，而 Secret 提供商（Secret Provider） 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。

有关更多详细信息，请参阅 引用在 AWS Secrets Manager 中的密钥。

用于 API 身份验证的匿名消费者

匿名消费者无需身份验证，但可以限制访问速率。你可以在服务/路由上的身份验证插件中配置匿名消费者，然后与速率限制插件结合使用。

有关详细信息，请参阅以下文档：

• 对匿名消费者进行速率限制

安全

• 在数据面上添加了用于自身健康检查的状态接口。有关详细信息，请参阅 启用数据面健康检查以实现高可用性。

功能优化

• 支持 200 万量级消费者。
• 消费者列表支持按名称排序。
• 从 API7 网关中删除了 conf_server。
• 改进了速率限制相关插件以使其更加灵活，允许针对每个服务/路由进行特定于消费者的速率限制。有关详细信息，请参阅 Limit Count 插件 和 Limit Req 插件。
• 升级请求和响应转换插件：
  • 在请求转换期间，支持传递 Lua 代码以获取值。
  • 对齐 Kong 的请求转换和响应转换的功能。
• 显示服务中添加的路由总数。
• 将插件列表从数据面配置更改为控制面配置。与 3.2.15.0 以下版本不兼容
• 在告警策略中添加了证书到期提醒。
• 在因多设备登录而重定向到登录页面之前显示通知，说明登出原因。
• 改善了前端页面响应速度和加载速度。
• 优化了“使用上游超时”UI。
• 优化了 API7 Portal (Beta) 列表页渲染速度。

缺陷修复

• 解决了问题：现在可以在控制台上为单个路由配置多个路径。
• 解决了问题：OpenTelemetry 插件不支持 set_ngx_var。
• 解决了问题：ACL 插件 在正常使用情况下不应输出警告日志。
• 增强了数据面 lua_ssl_trusted_certificate 配置项。
• 将 Body Transformer 插件代码与 APISIX 主线版本同步。
• 解决了问题：当在服务上配置了流模块不可用的插件时，数据面会打印错误日志。
• 将 Token 的 Edit 操作更改为 Edit Name。
• 解决了问题：编辑服务注册中心时，服务发现类型与表单不符。

3.2.16.2 版本

发布日期： 2024-10-11

缺陷修复

• 修复了消费者中插件配置更新不生效的问题。

3.2.16.1 版本

发布日期： 2024-10-04

功能优化

• 提升了 API7 Portal(Beta) 性能。

缺陷修复

• 解决了删除路由时 radixtree_host_uri 路由模式下的 panic 问题。
• 解决了自定义认证类型插件与Multi Auth 插件不兼容的问题。

3.2.16.0 版本

发布日期： 2024-09-30

新功能

引用在 HashiCorp Vault 中的密钥

信息

这是一项不兼容变更。secrets 资源已重命名为 secret provider（Secret 提供商），以符合最佳实践并促进与外部密钥管理工具的集成。所有相关的 API 都已相应更新。

密钥（Secrets） 对象是一条需要防止未经授权访问的敏感信息，而 Secret 提供商（Secret Provider） 对象用于设置与外部密钥管理器（HashiCorp Vault、AWS Secret Manager 等）的集成，以便 API7 网关可以在运行时动态地建立连接并从密钥管理器中获取密钥。

有关更多详细信息，请参阅 在 HashiCorp Vault 中引用密钥。

功能优化

• 【不兼容变更】删除了 JWT 插件签发 Token 的功能，并删除了上传私钥的功能。 有关详细信息，请参阅 JWT Auth 插件文档。
• 增加了对删除离线网关实例的支持。
• 为使用 Redis 的插件添加了 sync_rate 参数，以控制与 Redis 同步计数器的频率。实时同步会给 Redis 带来很大的压力。
• 支持通过 URL 访问特定的路由详情页。
• 支持 API7 Portal(Beta) 的 API 在线测试。
• UI 改进：缩短了自定义主机输入框。
• UI 改进：将负载均衡算法下拉框改为单选框。
• UI 改进：新建标签样式修改。

缺陷修复

• 修复了问题：未正确清理的 config_listen.sock 导致数据面无法启动。
• 修复了问题：禁用服务后请求接口报 404 错误。
• 为 Splunk HEC Logging 插件添加了 keepalive_timeout 配置。
• 修复了消费者的标签分割后各元素还保留分隔符前后的空白问题。
• 修复了问题：Skywalking 插件销毁后无法重新启动。
• 修复了问题：数据面没有正确处理非认证插件配置在消费者上时的加解密。
• 修复了问题：内置权限策略应无法删除。
• 修复了问题：ingress controller 类型网关组应能够删除。
• 修复了问题：数据面 path prefix 应当支持配置 /。
• 修复了 UI 问题：点击标签页面跳转到搜索框。
• 修复了 UI 问题：新建 Token 并删除 Token 后，新建提示没有消失。
• 为插件分类添加了中文翻译。
• 扩大了插件描述文字框，以完整显示插件的介绍。
• 修复了新建 Token 并删除 Token 后，新建提示没有消失的问题。

3.2.15.2 版本

发布日期： 2024-09-19

缺陷修复

• 调整 Attach Consumer Label 插件到 before_proxy 阶段执行。

3.2.15.1 版本

发布日期： 2024-09-18

缺陷修复

• 解决了使用 Token 获取 instance_token 返回 401 的问题。

3.2.15.0 版本

发布日期： 2024-09-14

新功能

消费者凭据

信息

这是一项不兼容变更。不再支持为消费者创建新的身份验证插件（Key Auth、Basic Auth、JWT Auth 或 HMAC Auth）。请改用消费者凭据。现有的插件配置将保持可访问和可编辑，直到被禁用。

消费者凭据通过允许多个凭据对应每个消费者来增强灵活性。它们取代了传统的身份验证插件，如 Key Auth、Basic Auth、JWT Auth 和 HMAC Auth，提供了更友好的用户体验。有关详细信息，请参阅管理消费者凭据。

安全

• 根用户 admin 成为受保护帐户，角色、权限策略或其他用户无法对其进行修改。其他用户无法删除它或重置其密码。

功能优化

• 现在支持按名称按字母顺序对服务列表进行排序。
• 向每个审计日志添加了网关组 ID，以便你可以按网关组搜索或过滤审计日志。
• 为已离线超过 7 天的自动删除的网关实例记录了审计日志。
• 支持按标签过滤网关组上发布的服务。
• 确保控制面地址不以斜杠结尾。
• 在 Helm 中支持注释。
• 提供配置项控制数据面心跳、遥测请求的超时，并且调整默认值为 30s。

缺陷修复

• 优化了在启用 SCIM 后用户通过 SSO 登录但系统中不存在该用户时的错误消息。
• 修复了修改未发布版本的服务后灰度配置调整失败的问题。

3.2.14.4 版本

发布日期： 2024-08-14

新功能

覆盖每个路由的上游超时

API7 网关允许为各个路由配置不同的上游超时，以覆盖上游侧的超时配置，从而实现对请求处理的精细控制。

用户权限边界

权限边界定义了用户的最大允许权限，作为防止用户越权的保障措施。

安全提升

• 升级了前端依赖项。
• 确保单设备登录 - 新登录将撤销之前存在的活跃会话。
• 禁止导入旧许可证。
• 升级了 OpenResty 版本以修复安全漏洞。

功能优化

• 在服务中心列表和已发布服务列表中添加了服务描述。
• 为服务注册中心添加了“连接中”状态，以避免误解。
• 自定义插件支持代码混淆和加密存储。
• 在使用测试环境许可证时显示通知。
• 为插件管理和修改实现了基于卡片的 UI。
• 支持配置自定义插件元数据。
• 最小化了 API7 企业版的镜像大小。

缺陷修复

• 修复了将服务版本发布到网关组时，服务运行时配置参数（例如，主机、路径前缀）的空值丢失的问题。
• 消除了 dry-run 模式下调用许可证上传时生成的不必要的审计日志。
• 解决了路由创建和修改时间戳不正确的问题。
• 解决了插件元数据 Schema 的校验报错。
• 提高了服务搜索准确性。
• 解决了服务模板发布期间插件丢失的问题。

3.2.14.3 版本

发布日期： 2024-08-06

缺陷修复

• 支持在 SSL 证书中引用 $env。
• 解决了标签包含句点时 UI 不稳定的问题。

3.2.14.2 版本

发布日期： 2024-07-30

缺陷修复

• 解决了在控制台上查看 Ingress Controller 路由时的报错。
• 修复了在 Kubernetes 上安装网关实例时缺少默认 Helm release 名称的问题。
• 通过使用 ID Token 优化了与 Azure AD 的集成。
• 修复了服务模板和已发布的网关组之间可能出现插件不一致的问题。

3.2.14.1 版本

发布日期： 2024-07-22

功能优化

导入 OpenAPI 以在网关组上创建服务

只需将 OpenAPI 文件直接导入网关组，即可创建新服务及其所有路由。

通过 API7 Portal 实现精细的访问控制

利用自定义角色和权限策略对 API 产品的访问进行精细控制。

安全提升

• 控制面地址必须为 HTTPs。
• 移除 ngx.req.get_post_args(0) 的使用，改用默认值以避免潜在的攻击。
• 重新生成 Ingress Controller 部署脚本现在需要二次确认。

无需版本控制即可管理已发布服务基础信息

现在可以修改服务名称/描述/标签，而无需发布新版本。

服务设置期间首次创建路由

你可以选择从一开始就定义服务里的第一条初始路由，无需额外的步骤，简化了工作流程。

缺陷修复

• 将 Datadog 插件修复（#11354）合并到 API7 企业版。
• 修复了控制台上数据面不可见的问题。
• 修复了一个问题：将 Prometheus 数据报告方法从远程写入更改为抓取后，服务注册表状态始终显示为“断开连接”。
• 修复了通过控制台部署自定义插件后，数据面遇到错误的问题。
• 修复了前端错误：不应该允许通过控制台在 Ingress Controller 网关组上修改已发布服务的上游。
• 去掉不该出现的报错通知：切换到节点时，即使启用了健康检查，仍然存在提示用户启用健康检查的提示。
• 修复问题：上传自定义插件时，如果出现解析错误，错误消息中显示的插件名称与实际文件名不匹配。

3.2.14.0 版本

发布日期： 2024-07-08

新功能

全新的访问控制机制

信息

这是一项不兼容变更。旧版本的规则不能保留。

API7 企业版改进了传统的基于角色的权限，采用了权限策略架构，通过分配给角色的可复用策略来实现精细的访问控制。请参阅角色和权限策略。

功能优化

配置路由优先级

在特定场景下，你可以在两个不同的服务中配置相同的路由。通过优先级确定哪个路由处理请求。具有较高指定优先级的路由将首先被使用。

强化 mTLS 证书安全

改进了以下问题：

• 过长的证书：证书字符串太长，应该缩短。
• 不必要的标记：证书包含不必要的标记，应该删除。
• 共享 CA：为多个证书使用相同的证书颁发机构 (CA) 是不安全的。
• 证书不匹配处理：当发生证书不匹配时，握手应立即失败，拒绝客户端的请求，而不是继续进行进一步的验证。

在 API7 Helm Chart 中包含新的参数 lua_shared_dict

为 Helm chart 引入了一个新的参数。

缺陷修复

• 从旧版本升级可能会导致上游数据丢失或 404 错误。
• 服务请求 URL 更新期间遇到 UI 错误。
• 修复了 API7 Portal (Beta) 库问题。
• 修复了 HTTP Logger 插件内存泄漏。
• 前端和后端密码策略不一致。
• 当 GET 请求与任何路由都不匹配时，Data Mask 插件会报告错误。
• ApisixUpstream CRD 的 status 字段记录不正确。
• 数据面支持配置监控数据的报告间隔。
• 修复了配置插件元数据后的警告日志。
• 修复了插件重新加载问题。
• 减少 PostgreSQL 连接数。
• 优化前端资源消耗。
• 删除 FQDN 中的尾随点。
• 插件元数据应该能够被删除。

3.2.11.8 版本

发布日期： 2024-06-26

缺陷修复

• 通过减少 etcd 调用来降低 API 延迟。
• Kine 数据库连接池配置可以正常工作。

3.2.11.7 版本

发布日期： 2024-06-24

缺陷修复

• 提升 API 性能。
• 数据面支持禁用遥测数据收集和配置报告间隔。
• 自定义插件即使没有 schema 定义也可以正常工作。

3.2.11.6 版本

发布日期： 2024-06-24

缺陷修复

• 大数据集不再导致 etcd range API 错误。

3.2.13.0 版本

发布日期： 2024-06-19

Admin API 不兼容变更

1. 服务模板 API 已迁移到 "/api/services/template" 路径前缀下。

• 服务模板 API
• 路由模板 API

2. 原始的 "/apisix/admin/services" 端点现在需要 gateway_group_id 参数。

• 网关组上的服务 API
• 网关组上的路由 API

新增功能

在网关组上创建/更新服务而不发布

如果版本控制不是你的要求，你现在可以直接在网关组上创建服务。这些服务会立即生效，无需单独的发布步骤。这简化了部署过程并节省了时间。

但是，重要的是要考虑所涉及的权衡。通过绕过发布阶段，你也失去了轻松回滚到以前版本或跟踪版本更改的能力。

有关详细信息，请参阅最新的入门教程：启动你的第一个 API。

与 Ingress Controller 集成（UI 支持）

API7 Gateway 正式推出 Ingress Controllers，这是一种新型的网关组。虽然控制台提供了方便的管理功能来创建和查看你的 Ingress Controller，但配置修改需要对任何配置更改采用声明方式。

功能优化

搜索网关组名称并按标签过滤

使在网关组列表中查找所需的特定网关组变得更加容易。

保护配置文件中的敏感数据

数据库的 DSN 配置（包括访问地址、用户名和密码）可以通过环境变量和 Helm 图表进行配置。

支持 Prometheus 认证

Prometheus 远程写入现在支持 Basic Auth/mTLS。

支持 SSL 变量的 Secret 功能

使用加密的 Secret 保护 ssl.certs 和 ssl.keys。

缺陷修复

• 设置标头后，ctx.var 变量将立即更新。
• 无法上传重复的 SSL 证书。

3.2.11.5 版本

发布日期： 2024-06-18

缺陷修复

• ssl_verify 配置现在适用于登录选项 OIDC 和 LDAP 协议。

3.2.11.4 版本

发布日期： 2024-06-07

缺陷修复

• 保护与 API 相关的登录选项中的敏感字段。

版本 3.2.12.0

发布日期: 2024-05-24

Admin API 不兼容变更

1. service status 字段从“0: 启用，1: 禁用”变更为“0: 禁用，1: 启用”

• Publish a service
• Update service runtime configurations by ID
• Get all published services in Gateway Group

2. consumer api 移除 id 字段，使用 gateway group id & username 做查询、删除

• Consumers APIs

3. ssl 相关 api 强制 gateway group id 参数

• SSL APIs

新增功能

四层路由（Stream Route）

API7 网关现在可以处理四层流量，比如与数据库或 Kafka 的连接。 添加一个四层类型的服务，并在其中添加若干个四层路由（Stream Route，即可转发四层流量。

自定义角色 (控制台支持)

当默认提供的角色无法满足需求时，你可以自行设计自定义角色，实现精细化权限控制。可参阅添加自定义角色

Ingress Controller（Beta 测试版，仅 API 支持）

集成 Ingress Controller。

功能优化

优化左侧导航菜单

• 用户登录后落地页改为网关组菜单中已发布服务。
• 服务 菜单项改名为 服务中心。

缺陷修复

• 使用 Key Auth 插件时，禁止出现重复的 API 密钥。
• 使用 UA Restriction 插件时，允许同时配置黑名单和白名单。
• 重置用户密码时不会引起访问 Token 失效。
• 使用 Loggly 插件时配置能校验成功。
• API7 网关中的状态字段取值含义和 Apache APISIX 保持一致。

版本 3.2.11.3

**发布日期: 2024-05-20

缺陷修复

• etcd watch 可以正确地传递 SNI。
• API7 企业版在安装时会先尝试创建新的数据库。如果没有对应权限导致失败，会使用预先指定的已有数据库，避免安装失败。

版本 3.2.11.2

发布日期: 2024-05-20

缺陷修复

• 标签支持最长 64 个字符，且可以包含空格。
• 即使包含 schema 校验错误，也可以正常完成与数据面的配置同步，避免数据丢失或工作流中断。

版本 3.2.11.1

发布日期: 2024-05-08

新增功能

SSO 角色映射

设置自动角色映射，可以避免超级管理员需要频繁为 SSO 登陆的用户分配角色。 满足预先设置的映射条件的用户，在登陆 API7 企业版时会自动获得相应的角色权限。详情参阅设置角色映射。

SCIM 用户同步

使用 SCIM 用户同步协议简化 SSO 用户管理。它可以自动从所有支持了 SCIM 协议的、已经添加了登陆选项的身份提供商同步用户数据，确保用户信息一致性。新用户在身份提供商注册，或用户在身份提供商注销，API7 企业版即可得到及时通知，避免新用户无法登陆或已注销用户非法登陆。详情参阅Sync User Data from IdP。

自定义角色 (Beta, 仅 API 支持)

如默认角色不满足业务需求，现在你可以设计自定义角色，自由组合权限，进行细粒度权限控制。 该功能即将在后续版本支持控制台配置。

功能优化

升级到 OpenSSL 3

提升安全性，性能，和可靠性。

全局插件执行顺序优化

为了简化全局插件的管理，API7 企业版会将多个全局插件配置整合到一起，确保插件配置和执行顺序不会产生冲突。

缺陷修复

前端补全 HTTP 协议检测

生成的网关实例部署脚本有时无法正确检测是否需要 HTTP 或 HTTPS 协议，这可能会导致部署时出现错误。

上传 SSL 证书错误

为网关组 A 上传的 SSL 证书可能会意外分配给网关组 B。

支持主机级动态设置 TLS 协议版本

同步集成了在 Apache APISIX 中已解决的问题。

版本 3.2.10.1

发布日期：2024-04-28

新增功能

支持 MySQL 5.7

现在起 API7 企业版支持使用 MySQL 5.7 作为持久化数据存储。

版本 3.2.10.0

发布日期: 2024-04-22

不兼容变更

Token 绑定用户

Token 改为和具体用户绑定，且和用户享有相同的角色权限。如果用户被删除，绑定的 Token 也将立刻失效被删除。

版本 3.2.9.5

发布日期：2024-04-16

新增功能

上游 mTLS（仅 API 支持）

支持在 API7 网关和上游服务之间配置 mTLS 认证。 mTLS 是一种通信安全形式，要求双方彼此展示证书。这确保了双方都是其声称的身份，并且在它们之间传输的数据是加密的。 该功能即将在后续版本支持控制台配置。

版本 3.2.9.4

发布日期: 2024-04-07

缺陷修复

CPU 核心数判断

修复了当 CPU 核心数达到最大限制时出现的问题。

版本 3.2.9.3

发布日期: 2024-04-03

新增功能

集成 Vault(Beta)

将敏感信息存储到 Vault中。仅支持通过 Admin API 使用，UI 使用即将推出。

版本 3.2.9.2

发布日期: 2024-04-01

新增功能

支持 SAML 第三方登录

API7 企业版新增支持对接 SAML 第三方登录。详情见如何设置第三方登录。

新插件： Data Mask

Data Mask 插件提供了在请求头、请求体和 URL 查询中移除或替换敏感信息的能力。

功能优化

忽略路径前缀

你可以选择在向上游发送请求时跳过路径前缀。这种调整对用户来说是不感知的，并且在使用不同的路径前缀来识别发送到不同网关组的 API 时可能很有用。

优化健康检查配置 UI

提供一个更直观友好的健康检查配置交互界面。

升级加密算法

从 AES128 升级到 AES 256。

性能提升

消除了禁用插件后带来的性能损耗。

版本 3.2.9.1

*发布日期: 2024-03-19

新增功能

支持自定义插件管理

API7 企业版支持上传你自行编写的自定义插件，以扩展 API 管理的功能。详情见新增自定义插件.

支持 OIDC 第三方登录

API7 企业版即 LDAP 之后，新增支持对接 OIDC 第三方登录。详情见如何设置第三方登录.

将服务标签作为 API 提供者授权范围

通过将服务标签作为为 API 提供者的范围，你可以授予他们访问带有特定标签的所有服务的权限。这将有助于减轻超级管理员的工作负担。通常，可以使用“部门”标签对服务进行分组。此后该部门的用户将能够访问属于该部门的所有服务。

版本 3.2.8.1

发布日期： 2024-02-08

新增功能

支持 Nacos 服务发现

API7 企业版利用服务发现功能自动检测可用的上游服务，并将其地址保存在数据库（也被称之为服务注册中心）中。因此，API 网关能够通过服务注册中心获取最新的上游地址列表，确保所有请求都被转发到健康的上游节点。

在本版本中，API7 企业版支持与 Nacos 服务发现集成。用户可以使用 Nacos 服务发现来发布服务和在网关组之间同步服务。

支持 LDAP SSO 登录

API7 企业版支持 LDAP 单点登录（Single Sign-On，SSO）。将 API7 企业版与 LDAP 集成后，用户可以直接使用 LDAP 用户名和密码登录 API7 控制台，创建和管理 API7 网关资源。有关如何配置 LDAP SSO 登录方法的具体信息，参见配置 LDAP 单点登录。

支持使用 Kubernetes 添加网关实例

用户使用网关实例来处理流量。在本版本中，API7 企业版支持使用 Kubernetes 向网关组添加网关实例。有关如何通过 Kubernetes 添加网关实例的具体信息，参见添加网关实例。