更新日志
3.10.4
发布日期:2026-07-27
升级须知
ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、阿里云日志服务(SLS) 和 Syslog 插件的 max_req_body_bytes 与 max_resp_body_bytes 现在会被校验为不小于 1 的整数。旧版本接受的值——0、负数,以及带引号的数字(如 "1024")——现在会被拒绝并返回 HTTP 400。
升级后,已有的、带这类值的路由会在网关组的兼容性报告中被列为错误,并且不会下发到数据面;其他路由不受影响。升级前请检查这些插件的配置中是否存在设置为 0、负数或带引号数字的 max_req_body_bytes / max_resp_body_bytes,将其改为正整数,或删除该字段以使用默认值 524288。
Prometheus 插件元数据现在会拒绝那些会移除指标赖以成立的标签的 disabled_labels 配置——例如 latency 的 type,或 status 的 code。旧版本接受这类配置,导致本应区分的多组测量值被合并成同一条指标序列。
如果你的 Prometheus 插件元数据禁用了这类标签,升级后对它的任何更新都会被拒绝并返回 HTTP 400。请在升级前把这些结构性条目从 disabled_labels 中移除。route、service、consumer 等非结构性标签仍然可以禁用。
新功能
插件
- OpenID Connect
- 新增
set_raw_id_token_header。启用后,身份提供商签发的原始 ID Token 会通过X-Raw-ID-Token请求头转发给上游服务,使上游可以自行校验 Token 签名,而不必信任网关解码后的声明。
- 新增
- Proxy Rewrite
headers.set和headers.add现在支持为同一个请求头名称配置数组值,转发到上游时会生成多条独立的请求头,而不是用逗号拼接成一条。这对只读取首个同名请求头、或对重复请求头与逗号拼接值解析方式不同的上游服务尤为重要。
- Kafka Logger
- 新增
tls,支持通过 TLS 连接 Kafka broker,并由tls.verify控制是否校验 broker 证书。此前插件只能以明文连接,因此监听 TLS 端口的 broker 完全收不到日志。
- 新增
- 限流与缓存插件
- 为 Limit Conn、Limit Req 和 AI Cache 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
redis_keepalive_timeout和redis_keepalive_pool),方便运营者调整空闲超时时间和连接池大小。
- 为 Limit Conn、Limit Req 和 AI Cache 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
- 需要缓冲请求/响应体的插件
- 新增
max_req_body_size和max_resp_body_size,用于限制插件读入内存的请求体或响应体大小,默认值为 67108864 字节(64 MiB)。超过上限的请求体会被拒绝,响应体则会在上限处截断——Proxy Cache 例外,超限的响应会直接透传而不被缓存——从而避免单个超大 body 耗尽 worker 内存。该能力可用于 AI Proxy、AI Proxy Multi、AI Request Rewrite、AI prompt 系列插件、Request Validation、OAS Validator、Body Transformer、Response Rewrite、Proxy Cache、gRPC Transcode、SOAP 等会缓冲 body 的插件。
- 新增
- Logger 插件
- 为其余 logger 插件的 schema 补充
max_req_body_bytes和max_resp_body_bytes——ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、阿里云日志服务(SLS) 和 Syslog——使这两个上限在配置时被校验并在控制台中展示(参见「升级须知」)。
- 为其余 logger 插件的 schema 补充
数据面
- 新增
nginx_config.stream.real_ip_from,用于列出在 stream(TCP/UDP)端口上被信任、可以发送 PROXY protocol 头的地址。当连接来自受信任地址时,客户端地址取自 PROXY protocol 头而非直连对端,使 stream 日志和基于地址的插件看到的是真实客户端,而不是网关前面的负载均衡器。该配置默认为空,且仅在启用了 PROXY protocol 的端口上生效。 - 升级健康检查引擎。检查目标现在以增量方式协调,不再整体销毁重建,因此上游扩缩容时不会出现「没有任何节点被检查」的窗口,未变更节点已累计的健康状态和失败计数也会被保留而不是被重置。
- 调试响应头
Apisix-Plugins现在按执行顺序列出实际执行过的插件,并标注各自执行的阶段(例如limit-count#access、response-rewrite#header_filter),而不是无序地列出已配置的插件。
控制面
/api/fe-config端点改由控制面二进制提供,并由console.*配置项驱动,因此控制台的 hybrid 模式、浏览器错误上报(Sentry)和侧边栏自定义外部链接分组都可以通过控制面配置或 Helm chart 配置。缺少名称或没有绝对http/httpsURL 的菜单项会被丢弃,不会下发给控制台。- 服务冲突检测现在会计入路由的 methods。同一 host 和 path 下方法集合互不相交的路由(例如
GET /foo和POST /foo)不再被判为冲突;方法范围完全相同判为 duplicate,部分重叠判为 overlapping。未配置methods的路由仍然匹配所有方法。 - 新增可选的出站 SSRF 防护。开启
security.ssrf_protection.enable后,控制面会拒绝连接环回地址、私网地址、链路本地地址和运营商级 NAT 地址——包括解析后落到这些网段的主机名——从而防止服务注册中心、SMTP 设置等功能被用来探测内网服务或云元数据端点。
控制台(Dashboard)
- 控制面版本号现在展示在顶部栏的组织菜单旁边,并支持一键复制,不再需要展开组织下拉菜单才能查看。
- 由 ADC 同步的资源(带
managed-by=adc标签)现在会在详情页展示 Managed by ADC 标记和提示横幅,对其执行编辑、删除、新建操作时会提示:下一次 ADC 同步会覆盖手工修改并移除手工添加的子资源。归属于被 ADC 管理的 Service 或 Consumer 的子资源,即使自身没有该标签也会给出提示。这些提示仅作告知,不会阻断操作。 - 服务与路由的冲突提示弹窗新增 Methods 列,便于判断两条路由在哪些方法上发生冲突。未配置
methods的路由显示为 All。
缺陷修复
插件
- AI Proxy、AI Proxy Multi 和 AI Request Rewrite
- 修复问题:网关发往 LLM 服务商的请求会携带客户端自身的请求头,包括
Cookie、Authorization以及任意自定义头,导致最终用户的凭证泄漏给上游服务商。现在网关只发送插件自身设置的请求头。 - 修复问题:当 LLM 返回错误响应时,
$apisix_upstream_response_time和$llm_time_to_first_token记录的是秒(例如0.240)或0,而成功响应记录的是毫秒。现在错误路径也统一以毫秒上报,与成功路径一致。
- 修复问题:网关发往 LLM 服务商的请求会携带客户端自身的请求头,包括
- OpenID Connect
- 修复问题:收到 state 与当前会话不匹配的授权回调时——例如在同一浏览器中先后发起了两个登录流程——会返回
HTTP 500。现在网关改为重定向到最初请求的页面。 - 修复问题:身份提供商 userinfo 中的空 JSON 数组(例如
"roles": [])在复用已有会话的请求中会被重新编码为空对象({})写入X-Userinfo头,导致按数组解析该字段的上游服务出错。现在空数组仍然是数组。
- 修复问题:收到 state 与当前会话不匹配的授权回调时——例如在同一浏览器中先后发起了两个登录流程——会返回
- 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 插件不再默认把 refresh_session_interval 设为 900 秒。现在只有显式配置 refresh_session_interval 时才会执行周期性静默重认证。如果你的部署依赖此前 900 秒刷新一次的行为,请在升级前或升级过程中显式设置 refresh_session_interval: 900。
对于使用 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。
- 请求审查现在在 AI 协议识别之后执行,检查上游 LLM 实际可见的解码后提示词内容,而不是原始 HTTP JSON 外壳。拒绝响应现在以提供商兼容格式返回,并新增可配置的
- 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 中展示。
- 为 HTTP Logger、RocketMQ Logger、TCP Logger、Tencent Cloud CLS 和 UDP Logger 的 schema 新增
- 限流插件
- 为 Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
redis_keepalive_timeout和redis_keepalive_pool),方便运营者调整空闲超时时间和连接池大小。
- 为 Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
数据面
- 新增
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 可以继续执行。
- 修复问题:在 body filter 中返回
- AI Rate Limiting
- 修复问题:部分已配置的 Redis 字段会被丢弃并替换为默认值——redis-sentinel 策略的
redis_username/redis_password,以及 redis 和 redis-cluster 策略的redis_keepalive_timeout/redis_keepalive_pool。现在所有已配置的 Redis 字段都会被转发。
- 修复问题:部分已配置的 Redis 字段会被丢弃并替换为默认值——redis-sentinel 策略的
- gRPC Transcode
- 修复问题:空的 protobuf
repeated字段会被编码为{}而不是 JSON 数组([])。现在空 repeated 字段会显示为数组,包括嵌套消息和 descriptor-set 方式的消息。
- 修复问题:空的 protobuf
- 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 修复。
- 修复问题:在不同 route 之间切换不同 Casbin model 或 policy 形状时,可能触发
- Request ID
- 修复问题:配置
algorithm: range_id但省略可选 range 对象时可能返回HTTP 500。现在 range 对象有默认值。
- 修复问题:配置
- Workflow
- 修复问题:Workflow action 插件可能在 workflow 决定跳过或执行该 action 前先运行
_meta.pre_functionhook,从而影响本不应执行的 action。现在 workflow 会先决定是否运行 action,再执行这些 meta hook。
- 修复问题:Workflow action 插件可能在 workflow 决定跳过或执行该 action 前先运行
- 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 启用 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)。
- 缓存 LLM 响应,使相同的请求从缓存返回,而不再重复调用上游模型。精确匹配缓存以归一化后的请求体为键,存储在 Redis 中;缓存命中时返回存储的响应,并带
- AI Lakera Guard(新插件)
- 通过 Lakera Guard API 检测 AI 流量中的提示词注入和其他不安全内容。
direction选项(input、output或both)用于选择插件扫描请求提示词、LLM 响应(包括流式响应)还是两者。被标记的流量会以可配置的deny_code拒绝,或在action设为alert时仅记录日志。
- 通过 Lakera Guard API 检测 AI 流量中的提示词注入和其他不安全内容。
- 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。
- 发送给 logger 插件的结构化
- Elasticsearch Logger
- 新增通过自定义请求头向 Elasticsearch 认证的支持(
headers选项,例如Authorization: Bearer <token>或 API key 请求头),作为基本auth的替代方式。
- 新增通过自定义请求头向 Elasticsearch 认证的支持(
- OpenID Connect
- 新增 Redis 作为会话存储后端。将
session.storage设为redis并配置session.redis(host、port 等选项),即可把会话存储在 Redis 而非会话 cookie 中;默认仍为cookie。
- 新增 Redis 作为会话存储后端。将
数据面
- 新增
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-gatewayRPM 后,生成的离线脚本会下发网关组客户端证书、写入网关配置,并将实例接入控制面。
开发者门户
- 禁用 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-multifallback 场景下也是如此。
- 修复问题:当上游返回的工具调用的
- 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。
- 修复问题:当上游响应被压缩(gzip 或 brotli)时,
- 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被代理到上游,而不是由插件处理。现在该回调由插件终止,不再转发到上游。
- 修复问题:CAS 单点登出(SLO)回调
- 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现在默认校验 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 独有的全部能力——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 的用户名仍然可见。
请在密钥首次展示时复制并妥善保存。如果密钥丢失,请重新生成凭据以获得新值。任何从凭据读取或列表接口回读这些密钥的集成都需要改为在创建时捕获它们。
独立的 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 提供映射。
- 新增描述每个 LLM 请求的内置 NGINX 变量,可用于
- 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 映射,而不是每个请求都重建,降低了每请求开销。
- 新增 LLM 可观测性指标:按请求统计的 prompt Token 和 completion Token 分布直方图(
- AI Proxy Multi
- 为 fallback 机制新增
max_retries和retry_on_failure_within_ms。max_retries限制单个请求在失败后最多重试多少个额外实例;retry_on_failure_within_ms仅在上游于指定时间内失败时才进行 fallback,因此慢失败会直接返回给客户端,而不是再重试(避免长耗时 LLM 请求的延迟翻倍)。
- 为 fallback 机制新增
- 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保留协议兼容性。
- 为 Kafka 生产协议新增
开发者门户
- 双因素认证:开发者可使用 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被拒绝。
- 修复问题:当 Token 的签名格式有误(长度不对或不是合法的 base64url)时,校验器会抛错并返回
- AI Proxy
- 修复问题:在 passthrough 模式下,发往上游的请求总是以
POST发送,且丢弃了客户端的查询字符串,导致需要在其他方法上携带查询参数的提供方失败(例如 Azure OpenAI 的?api-version=)。现在会转发客户端的方法和查询字符串。 - 修复问题:访问上游 LLM 超时(例如 DNS 解析超时)时返回
HTTP 500而不是HTTP 504。现在上游 LLM 超时会正确返回HTTP 504。
- 修复问题:在 passthrough 模式下,发往上游的请求总是以
- AI Proxy Multi
- 修复问题:在按实例创建健康检查器之后,缓存的节点选择器没有重建,导致某个 worker 可能持续把部分流量路由到已被标记为不健康的实例;对配置了
auth.query或auth.header的实例,主动健康检查探测还可能破坏探测路径。这两个问题均已修复,故障转移和健康检查现在按配置工作。
- 修复问题:在按实例创建健康检查器之后,缓存的节点选择器没有重建,导致某个 worker 可能持续把部分流量路由到已被标记为不健康的实例;对配置了
- 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。
- 修复问题:XML 转 JSON 时会在部分 worker 进程上间歇性丢失带命名空间的 key,导致 SOAP 转换以
- Kafka Logger
- 修复问题:由于无法配置 Kafka 生产 API 版本,broker 存储的消息没有可用的时间戳(显示为 1970-01-01)。将新增的
api_version设为2可让 broker 记录真实的时间戳。
- 修复问题:由于无法配置 Kafka 生产 API 版本,broker 存储的消息没有可用的时间戳(显示为 1970-01-01)。将新增的
- Elasticsearch Logger
- 修复问题:使用某些
{time_format}占位符的动态索引名可能生成被破坏的索引名。现在无效的时间格式会回退为空值(并记录日志),而不是破坏索引名。
- 修复问题:使用某些
- AWS Lambda
- 修复问题:使用 IAM(SigV4)认证时,查询字符串中包含需要转义的字符、多值或无值键会导致签名不匹配(
InvalidSignatureException)。现在规范查询字符串按 SigV4 规范构建。
- 修复问题:使用 IAM(SigV4)认证时,查询字符串中包含需要转义的字符、多值或无值键会导致签名不匹配(
- Proxy Mirror
- 修复问题:镜像 gRPC 请求时把内部 location 名称当作请求路径发送,导致镜像后端以
UNIMPLEMENTED拒绝每次调用。现在镜像请求使用原始的 gRPC 方法路径。
- 修复问题:镜像 gRPC 请求时把内部 location 名称当作请求路径发送,导致镜像后端以
- 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会被接受。
- 修复问题:由 NGINX 变量解析出的
- 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插件现在将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.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 地址。
- 当 LLM endpoint 域名解析到多个 A 记录时,插件现在会解析全部 A 记录并构建多节点 upstream,逐请求选择节点以获得更好的负载分布和故障转移。
- 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拒绝。
- 修复问题:登录回调未校验已签名的发起 cookie,使得构造的回调请求可以操纵登录后的跳转目标(CSRF / open-redirect)。回调现在要求携带有效的已签名发起 cookie,否则以
- DingTalk Auth
- 修复问题:认证失败与上游瞬时失败未做区分。插件现在对认证错误返回
HTTP 401,对 DingTalk 或上游的瞬时失败返回HTTP 503,并提供更清晰的错误信息。
- 修复问题:认证失败与上游瞬时失败未做区分。插件现在对认证错误返回
- Authz Casdoor
- 修复问题:session cookie 名称在不同 Casdoor client 间共享,导致不同 client 的 session 可能冲突。session cookie 现在按 client(基于
client_id)隔离命名。
- 修复问题:session cookie 名称在不同 Casdoor client 间共享,导致不同 client 的 session 可能冲突。session cookie 现在按 client(基于
- Authz Keycloak
- 修复问题:当静态
permissions与http_method_as_scope同时使用时,派生出的方法 scope 会被写回复用的插件配置,导致 scope 跨请求累积。现在会在追加方法 scope 之前先克隆 permission 列表。
- 修复问题:当静态
- GraphQL Limit Count
- 修复问题:查询嵌套深度计算有误,导致基于深度的限流不准确。现在深度会按真实最大嵌套深度并展开 fragment 计算。Content-Type 匹配也容忍 charset 参数(如
application/json; charset=utf-8),此前这类请求会被拒绝。
- 修复问题:查询嵌套深度计算有误,导致基于深度的限流不准确。现在深度会按真实最大嵌套深度并展开 fragment 计算。Content-Type 匹配也容忍 charset 参数(如
- GraphQL Proxy Cache
- 修复问题:
Content-Type带 charset 参数的请求未被识别为 GraphQL 请求。Content-Type 匹配现在容忍 charset,同时增加了 nil 守卫、更清晰的错误信息并修正了日志级别。
- 修复问题:
数据面
- 修复问题:当同一请求上有多个日志插件抓取响应体时(例如
http-logger和file-logger都启用了include_resp_body),它们的响应体缓冲区可能相互干扰,产生截断或混杂的日志输出。现在每个 logger 使用独立的缓冲区。
3.9.17
发布日期:2026-07-28
升级须知
ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、阿里云日志服务(SLS) 和 Syslog 插件的 max_req_body_bytes 与 max_resp_body_bytes 现在会被校验为不小于 1 的整数。旧版本接受的值——0、负数,以及带引号的数字(如 "1024")——现在会被拒绝并返回 HTTP 400。
升级后,已有的、带这类值的路由会在网关组的兼容性报告中被列为错误,并且不会下发到数据面;其他路由不受影响。升级前请检查这些插件的配置中是否存在设置为 0、负数或带引号数字的 max_req_body_bytes / max_resp_body_bytes,将其改为正整数,或删除该字段以使用默认值 524288。
Prometheus 插件元数据现在会拒绝那些会移除指标赖以成立的标签的 disabled_labels 配置——例如 latency 的 type,或 status 的 code。旧版本接受这类配置,导致本应区分的多组测量值被合并成同一条指标序列。
如果你的 Prometheus 插件元数据禁用了这类标签,升级后对它的任何更新都会被拒绝并返回 HTTP 400。请在升级前把这些结构性条目从 disabled_labels 中移除。route、service、consumer 等非结构性标签仍然可以禁用。
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),方便运营者调整空闲超时时间和连接池大小。
- 为 Limit Conn、Limit Req 和 AI Cache 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
- 需要缓冲请求/响应体的插件
- 新增
max_req_body_size和max_resp_body_size,用于限制插件读入内存的请求体或响应体大小,默认值为 67108864 字节(64 MiB)。超过上限的请求体会被拒绝,响应体则会在上限处截断——Proxy Cache 例外,超限的响应会直接透传而不被缓存——从而避免单个超大 body 耗尽 worker 内存。该能力可用于 AI Proxy、AI Proxy Multi、AI Request Rewrite、AI prompt 系列插件、Request Validation、OAS Validator、Body Transformer、Response Rewrite、Proxy Cache、gRPC Transcode、SOAP 等会缓冲 body 的插件。
- 新增
- Logger 插件
- 为其余 logger 插件的 schema 补充
max_req_body_bytes和max_resp_body_bytes——ClickHouse Logger、Elasticsearch Logger、File Logger、Loggly、Loki Logger、SkyWalking Logger、阿里云日志服务(SLS) 和 Syslog——使这两个上限在配置时被校验并在控制台中展示(参见「升级须知」)。
- 为其余 logger 插件的 schema 补充
数据面
- 新增
nginx_config.stream.real_ip_from,用于列出在 stream(TCP/UDP)端口上被信任、可以发送 PROXY protocol 头的地址。当连接来自受信任地址时,客户端地址取自 PROXY protocol 头而非直连对端,使 stream 日志和基于地址的插件看到的是真实客户端,而不是网关前面的负载均衡器。该配置默认为空,且仅在启用了 PROXY protocol 的端口上生效。 - 升级健康检查引擎。检查目标现在以增量方式协调,不再整体销毁重建,因此上游扩缩容时不会出现「没有任何节点被检查」的窗口,未变更节点已累计的健康状态和失败计数也会被保留而不是被重置。
- 调试响应头
Apisix-Plugins现在按执行顺序列出实际执行过的插件,并标注各自执行的阶段(例如limit-count#access、response-rewrite#header_filter),而不是无序地列出已配置的插件。
控制面
/api/fe-config端点改由控制面二进制提供,并由console.*配置项驱动,因此控制台的 hybrid 模式、浏览器错误上报(Sentry)和侧边栏自定义外部链接分组都可以通过控制面配置或 Helm chart 配置。缺少名称或没有绝对http/httpsURL 的菜单项会被丢弃,不会下发给控制台。- 服务冲突检测现在会计入路由的 methods。同一 host 和 path 下方法集合互不相交的路由(例如
GET /foo和POST /foo)不再被判为冲突;方法范围完全相同判为 duplicate,部分重叠判为 overlapping。未配置methods的路由仍然匹配所有方法。 - 新增可选的出站 SSRF 防护。开启
security.ssrf_protection.enable后,控制面会拒绝连接环回地址、私网地址、链路本地地址和运营商级 NAT 地址——包括解析后落到这些网段的主机名——从而防止服务注册中心、SMTP 设置等功能被用来探测内网服务或云元数据端点。
控制台(Dashboard)
- 服务与路由的冲突提示弹窗新增 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,而成功响应记录的是毫秒。现在错误路径也统一以毫秒上报,与成功路径一致。
- 修复问题:网关发往 LLM 服务商的请求会携带客户端自身的请求头,包括
- 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头,导致按数组解析该字段的上游服务出错。现在空数组仍然是数组。
- 修复问题:收到 state 与当前会话不匹配的授权回调时——例如在同一浏览器中先后发起了两个登录流程——会返回
- 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的非标量值,这些值随后会在运行时被静默丢弃。现在这类值会在配置时被拒绝。
- 修复问题:插件元数据 schema 接受
数据面
- 修复问题:使用
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
升级须知
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 插件不再默认把 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 的部署,控制面现在会先创建并准备数据库,再让其他组件连接,并启用 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时仅记录日志。
- 通过 Lakera Guard API 检测 AI 流量中的提示词注入和其他不安全内容。
- 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。
- 请求审查现在在 AI 协议识别之后执行,检查上游 LLM 实际可见的解码后提示词内容,而不是原始 HTTP JSON 外壳。拒绝响应现在以提供商兼容格式返回,并新增可配置的
- Elasticsearch Logger
- 新增通过自定义请求头向 Elasticsearch 认证的支持(
headers选项,例如Authorization: Bearer <token>或 API key 请求头),可作为基本auth的替代或补充。
- 新增通过自定义请求头向 Elasticsearch 认证的支持(
- 限流插件
- 为 Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
redis_keepalive_timeout和redis_keepalive_pool),方便运营者调整空闲超时时间和连接池大小。
- 为 Limit Count、Limit Count Advanced、GraphQL Limit Count 和 AI Rate Limiting 的 Redis 与 Redis Cluster 策略新增 Redis 连接 keepalive 设置(
数据面
- 新增
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 方式的消息。
- 修复问题:空的 protobuf
- 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 修复。
- 修复问题:在不同 route 之间切换不同 Casbin model 或 policy 形状时,可能触发
- AI Aliyun Content Moderation
- 修复问题:在 body filter 中返回
ngx.OK可能中断后续 body filter 处理。现在插件会正常返回,使其他 filter 可以继续执行。
- 修复问题:在 body filter 中返回
- Request ID
- 修复问题:配置
algorithm: range_id但省略可选 range 对象时可能返回HTTP 500。现在 range 对象有默认值。
- 修复问题:配置
- Workflow
- 修复问题:Workflow action 插件可能在 workflow 决定跳过或执行该 action 前先运行
_meta.pre_functionhook,从而影响本不应执行的 action。现在 workflow 会先决定是否运行 action,再执行这些 meta hook。
- 修复问题:Workflow action 插件可能在 workflow 决定跳过或执行该 action 前先运行
- Redirect
- 修复问题:
http_to_https只重定向 scheme 恰好为http的请求,因此以非 HTTP、非 HTTPS scheme 到达的请求(例如通过伪造的X-Forwarded-Proto)不会被重定向。现在它会重定向所有非 HTTPS 的 scheme。
- 修复问题:
- Response Rewrite
- 修复问题:当上游响应被压缩(gzip 或 brotli)时,
filters作用在压缩字节上而无法匹配,产生损坏的响应体。现在会先解码响应再执行 filters。
- 修复问题:当上游响应被压缩(gzip 或 brotli)时,
- 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被代理到上游,而不是由插件处理。现在该回调由插件终止,不再转发到上游。
- 修复问题:CAS 单点登出(SLO)回调
- 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
升级须知
本次发布新增了插件配置字段:日志类插件的 log_format_extra,以及 openid-connect 的 Redis 会话存储(session.storage 和 session.redis)。由于 API7 EE 升级时先升级控制面、再升级数据面,3.9.15 的控制面会接受这些字段,而较旧的数据面尚未实现它们。请在控制面和数据面都升级到 3.9.15 之后再配置这些新选项。
在开发者门户中,仅限 SSO 的域名策略现在在服务端强制执行,而不再仅在浏览器侧生效。对于域名被映射到仅限 SSO 提供方的邮箱,本地登录与注册方式——邮箱密码登录与注册、魔法链接、密码重置——现在都会被拒绝。此前这些端点可以被直接调用,从而绕过 SSO 要求。如果 SSO 托管域名下的用户依赖本地登录,请在升级后让他们改用 SSO 登录。
开发者门户的 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 的配置不受影响。
- 新增 Redis 作为会话存储后端。将
数据面
- 日志类插件现在支持
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 中,而不再仅限默认的
publicschema。该 schema 在门户配置中设置(不放在连接 URL 中);门户会按连接应用该 schema,并在其中运行数据库迁移。
缺陷修复
插件
- JWT Auth
- 修复问题:签名格式错误(长度不对或不是合法的 base64url)的 Token 会导致校验器抛错并返回
HTTP 500,而不是拒绝请求。格式错误的签名现在会以HTTP 401拒绝。
- 修复问题:签名格式错误(长度不对或不是合法的 base64url)的 Token 会导致校验器抛错并返回
- AI Proxy 和 AI Proxy Multi
- 修复问题:当上游 LLM 提供商返回
HTTP 429或5xx响应时,网关只返回状态码而响应体为空,丢弃了提供商的错误详情(如限流信息)。当请求未重试时,上游错误响应体及其Content-Type现在会转发给客户端。
- 修复问题:当上游 LLM 提供商返回
- 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现在默认校验 Token 的exp(过期)和nbf(生效时间)声明。此前,未设置claims_to_verify(或将其设为空列表)的 consumer 会接受任何签名正确的 Token,包括已过期的 Token。数据面升级后,这类 Token 会被以HTTP 401拒绝。如果你依赖已过期 Token 仍被接受,请在升级前评估此行为变更。如需只校验特定声明,请在 consumer 配置中显式设置
claims_to_verify。 -
升级说明
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),从而可以按工具和请求类型拆分 MCPtools/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。
- 修复问题:登录回调未校验已签名的发起 cookie,使得构造的回调请求可以操纵登录后的跳转目标。回调现在要求携带有效的已签名发起 cookie,否则以
- 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_samlwrapper,默认关闭 debug 输出,并在认证出错时返回干净的HTTP 500。
- 修复问题:重构了插件加载和错误处理——移除了
- AI Proxy
- 修复问题:上游 LLM 超时此前被映射为
HTTP 500,现在映射为HTTP 504 Gateway Time-out。 - 修复问题:在 passthrough 模式下,客户端的 HTTP 方法和查询字符串未被转发到上游。现在它们会被保留。
- 修复问题:上游 LLM 超时此前被映射为
- 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策略。
- 修复问题:仅在 database 编号或凭证上不同的 Redis 连接可能共享同一 keepalive 连接池,导致连接被复用到错误的 database 或身份上。现在连接会按 database、凭证和 TLS 设置隔离;这也覆盖了
- 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_URIcookie 签名和校验,防止客户端可控 cookie 修改登录后的跳转目标。升级前,请为所有已有
cas-auth配置补充cookie.secret,并确保所有网关节点使用相同密钥。
升级须知
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无法先应用请求体大小覆盖,导致大请求被意外拒绝。
- 修复问题:当 Global Rule 插件在 access 阶段读取请求体时,路由或服务上的
控制面
- 修复问题:删除仍被其他资源引用的 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即可获取流式响应。
- 新增 AWS Bedrock 提供商支持,使用 Converse API。通过配置
- 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 实现大小写不敏感匹配。
- 修复问题:请求头参数校验区分大小写,当请求中的头名称大小写与 OpenAPI 规范定义不完全匹配时(例如发送
3.9.11
发布日期:2026-04-30
升级须知
本版本将 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 模块,这些变量为空。
- 新增 passthrough 协议适配器,可将无法识别的 API 格式(如
- OAS Validator
- 用纯 Lua 实现(
lua-resty-openapi-validator)替换了基于 Go FFI 的 OpenAPI 验证器。基于真实大规模 OpenAPI 规范(Stripe,约 414 个端点)的内部基准测试显示,新验证器每次请求校验快 2-7 倍,规范编译快 20 倍,同时消除了 Go 共享库从而减小了网关镜像体积。新验证器还修复了路径参数路由、nullable schema、allOf/anyOf 合并的正确性问题,并新增了对 form-encoded 请求体校验的支持(此前实现无法处理)。
- 用纯 Lua 实现(
- 所有插件现在自动支持在任何配置字段中使用
$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 实例名称(如
- AI Request Rewrite
- 修复问题:无请求体的请求产生模糊的上游错误,而非返回明确的 HTTP 400 Bad Request。
- AI Prompt Template
- 修复问题:JSON 解析错误消息显示为混乱的 Lua 表引用(如
table: 0x...),而非可读的错误字符串。
- 修复问题:JSON 解析错误消息显示为混乱的 Lua 表引用(如
- OpenTelemetry
- 修复问题:
additional_attributes中的非字符串值(如来自 nginx 变量的数字或布尔值)被 OpenTelemetry SDK 静默丢弃。现在在添加到 span 之前会强制转换为字符串。
- 修复问题:
- Limit Count
- 修复问题:Redis 凭证(
redis_password、redis_username、sentinel_password)被嵌入速率限制分组键中,在 Redis 键空间和 APISIX 日志中暴露敏感信息。
- 修复问题:Redis 凭证(
- Traffic Split (Stream)
- 修复问题:在 stream(L4)上下文中
ctx.var.route_id始终返回 nil,导致 traffic-split 规则中基于route_id的匹配条件永远无法生效。 - 修复问题:在 stream 上下文中,traffic-split 通过
upstream_id选择的上游被忽略,始终使用路由原始的上游。
- 修复问题:在 stream(L4)上下文中
控制面
- 修复问题:配置兼容性报告中的警告级别条目错误地导致数据面实例显示“建议升级”,即使控制面和数据面版本一致。
数据面
- 修复问题:批处理器在 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
不兼容变更
插件
-
升级说明
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_sourcespan 属性(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 作为可选的服务发现类型。
- 配置
skip_mtls_uri_regex时,支持指定 SNI。
缺陷修复
插件
- AI Proxy
- 修复问题:当 LLM 提供商每秒发送大量小型 SSE 数据块(如单字符推理 Token)时,单个流式请求可能导致 worker 进程 CPU 占用率达到 100%,影响该 worker 上所有其他流量的可用性。
- 修复问题:当协议转换器处于活跃状态(例如 Anthropic 转 OpenAI)且上游返回了格式不兼容的 SSE 事件时,网关返回 500 错误而非 502。现在当上游响应格式与配置的协议转换不兼容时,网关正确返回 502 Bad Gateway。
- 修复问题:当 LLM 提供商在可空响应字段(如
prompt_tokens_details或usage)中返回 JSONnull时,网关崩溃,因为 JSON null 哨兵值通过了 Lua 真值检查但无法作为 table 索引。
- AI Rate Limiting
- 修复问题:上游提供的用量键(来自 LLM 响应用量数据)与保留的表达式环境名称(如
math或abs)冲突时,可能遮蔽内置函数,导致限速表达式求值异常或绕过限制。
- 修复问题:上游提供的用量键(来自 LLM 响应用量数据)与保留的表达式环境名称(如
控制面
- 修复问题:通过开发者门户使用 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 请求体中,导致转换协议的流式响应中缺少用量统计信息。
- 修复问题:使用 AI Proxy 进行协议转换时(例如 Anthropic 客户端转 OpenAI 提供商),
- Forward Auth
- 修复问题:当认证服务返回 HTTP 200 但未包含
upstream_headers中配置的某个请求头时,客户端原始请求中携带的该请求头值被直接转发到上游,而非被清除。这可能导致客户端通过在原始请求中携带该请求头来伪造上游请求头。
- 修复问题:当认证服务返回 HTTP 200 但未包含
- JWT Auth
- 修复问题:JWT Auth 插件在签名验证前未校验 JWT 的
alg头是否与消费者配置的算法一致,可能导致算法混淆攻击。
- 修复问题:JWT Auth 插件在签名验证前未校验 JWT 的
数据面
- 修复问题:数据面兼容性报告对有效的插件配置显示了虚假的警告信息。使用
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插件。 -
升级说明
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结果中被拒绝的工具。
- 新增用于 MCP 服务的工具级访问控制插件,适用于通过 OpenAPI-to-MCP 插件暴露的 MCP 服务。支持白名单(
- 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路由。
- 新增原生 Anthropic Messages API 支持。使用 Anthropic SDK 格式发送到
- 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)。
- 新增 OpenAPI 3.1 规范校验支持,包括
- Request ID
- 新增
uuidv7作为algorithm选项。UUID v7 生成按时间排序、字典序可排序的唯一标识符,比随机 UUID v4 更适合分布式追踪和日志关联。
- 新增
- OpenAPI to MCP
- 新增 OpenAPI
in: header参数支持。OpenAPI 规范中定义的 Header 参数现在可正确包含在 MCP 工具 schema 中,并在调用上游 API 时作为 HTTP 请求头转发。
- 新增 OpenAPI
控制面
- 新增 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_connectionsPrometheus 指标永远不会递减,导致该指标持续增长并报告不准确的活跃连接数。
- 修复问题:当插件通过
- AI Rate Limiting、Limit Conn、Limit Req
- 修复问题:Redis 主机配置中的
$env://和$secret://引用被当作字面字符串传递,未能解析为实际值,导致 Redis 连接失败。
- 修复问题: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。
- 新增 MCP Tool Annotations 支持。通过 OpenAPI 规范中的
控制面
- 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)可能不准确。
- 修复问题:当上游返回的 HTTP chunk 边界与 SSE 事件边界不对齐时,AI 请求的 Token 用量统计(
- Prometheus
- 修复问题:未启用 AI 插件的 API 路由在 Prometheus 监控中也产生
apisix_llm_*系列指标,导致不必要的指标基数和存储开销。同时新增disabled_labels对 LLM 指标的支持,允许按需关闭高基数标签。
- 修复问题:未启用 AI 插件的 API 路由在 Prometheus 监控中也产生
控制面
- 修复问题:多个并发 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 Count
- 修复问题:在网关意外崩溃时,计数器数据不准确。
数据面
- 修复问题:当配置多个控制平面地址时,心跳和指标上报时仅会使用第一个连接地址。
控制面
- 修复问题:在路由的 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配置项,用于在认证失败并返回 401 时设置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响应头仍返回“APISIX”。 - 修复问题:在
ai-proxy-multi插件更新后,健康检查器导致网关持续输出错误日志。
控制面
- 修复问题:SSL 资源默认的
client.depth过小,导致 Cloud v2 用户 mTLS 功能迁移失败。 - 修复问题:并发调用 SSL API 时可能引发数据重复。
- 修复问题:控制台中前端组件的健康状态未反映在
/healthzAPI 返回值中。
3.9.1
发布日期:2026-01-08
缺陷修复
开发者门户
- 修复在旧版本开发者门户中创建的“开发者”无法被删除的问题。
3.9.0
发布日期:2026-01-06
不兼容变更
开发者门户
-
全新重构的开发者门户
升级说明开发者门户已完全重构。本版本包含以下不兼容变更,升级前需采取操作:
- 内置的 Portal SSO 功能已被移除。请通过新的 Portal 级别认证机制配置认证。
- Portal 前端现已开源。现有的 Portal 定制内容需要迁移到基于 SDK 的新架构。
新功能
- 所有 API7 企业版 Docker 镜像通过 Cosign 签名,提升镜像安全性。
开发者门户
- 提供开源 SDK 和前端脚手架项目,方便用户二次开发。
- 新增 Portal 级别认证机制用于对接 API。
插件
-
- 支持使用 Redis 和 Redis Cluster 作为限流数据存储后端。
升级说明新增必填字段
policy。已有配置无须修改,在数据面可以正常工作,但更新配置时必须提供该字段(例如policy=local),否则更新会被拒绝。 -
- 新增使用
ksuid生成 ID 的算法。
- 新增使用
-
- 支持自定义发送给 Loki 服务器的 HTTP 请求头。
-
File Logger
- 支持通过
match字段匹配并记录指定的请求。
- 支持通过
-
rules字段现已设置为必填项。
控制面
- 允许在启用 SSO 登录后,完全禁用内置的用户名密码登录方式。
- 支持配置数据库语句的最大执行时间。
- 可观测性优化
- 默认开启 pprof 性能分析功能。
- 监控指标端点新增数据库连接池监控指标。
- 支持分别记录访问日志和错误日志。
- 访问日志和错误日志中增加
request_id字段。
缺陷修复
插件
- OpenAPI to MCP
- 修复问题:通过查询参数传递认证凭据可能导致敏感信息泄露。
数据面
- 优化涉及 CNAME 和 A 记录的 DNS 解析链的缓存行为。
控制面
- 在网关实例列表中展示 IP 和 Port,已移除,避免误导用户。
- 修复问题:在 API 调用次数统计表并发批量插入时可能引发数据库死锁的情况。
- 修复问题:在 PostgreSQL 中使用非
publicschema 时控制台启动失败。
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 时可能引发数据重复。
- 修复问题:控制台(Dashboard)前端组件的健康状态未反映在
/healthzAPI 响应中。
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 无法区分。默认通过匹配的rule的索引进行区分,支持配置header_prefix来自定义前缀。 - 修复问题:在
limit字段中使用变量时,在变量值发生变化后,无法实时更新限流状态。
- 修复问题:多个
控制面
- 修复问题:用户的 Token 过期后仍然可以用于访问 API。
- 修复问题:控制台中创建路由时“标签”字段出现大量重复输入框。
- 修复问题:路由中禁用状态的插件无法覆盖服务中启用状态下的同名插件。
- 修复问题:控制台中 Portal 下拉选项值频繁变化。
- 修复问题:控制台中的插件配置没有自动填充默认值。
3.8.18
发布日期:2025-11-25
为支持创建多个 Portal 实例,数据面的 Portal 认证插件(portal-auth)进行了升级。用户在升级控制面后应尽快升级数据面,在已升级控制面,还未完成数据面升级前,请勿更新已有的 API 产品,否则这部分变更将无法生效。
新功能
数据面
- 支持为监听端口指定
backlog配置。 fallback_cp功能支持 Azure Blob 存储类型。
控制面
- 新增动态客户端注册(DCR)提供者管理功能。
- API 产品新增 DCR 认证类型。
- Developer Credential 新增 OAuth 认证类型(基于 DCR 获取 Client ID 和 Client Secret)。
- 支持创建多个 Portal 实例,已有 Portal 的使用数据会归属于系统自动创建的
defaultPortal 实例中。 - 控制台支持在配置文件中指定许可证的存放路径。
缺陷修复
插件
- 所有日志插件
- 修复问题:客户端请求体过大而无法生成临时文件时,日志插件获取请求体失败。
- AI Proxy Multi
- 修复问题:健康检查器在请求命中不同消费者时会触发重建。
控制面
- 修复问题:Ingress Controller 安装脚本中未锁定 Helm Chart 版本号。
- 修复问题:处于离线状态的网关实例展示兼容性标签。
- 修复问题:创建/更新上游时,
pass_host为rewrite时,未检查upstream_host是否为空。 - 修复问题:开发者门户中,当 OpenAPI 文档包含多个
server_urls时,开发者发起测试请求时无法选择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 实例的健康检查器。
控制面
- 修复问题:当浏览器没有权限时无法上传许可证书。
- 修复问题:当
upstream.nodes的数量非常多时网关性能不佳。 - 修复问题:
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 时显示受支持的版本。
- 从网关部署页面移除裸金属选项卡。
缺陷修复
插件
- OpenAPI to MCP
- 修复问题:当服务中配置了
path_prefix和strip_path_prefix时,SSE 模式不工作。 - 修复问题:MCP 工具名称之前是根据 OpenAPI 路径生成的,因此可能超出工具名称的长度限制。现在,MCP 工具名称将根据 OpenAPI 操作 ID 生成。
- 修复问题:如果未配置
headers字段,将会抛出 500 状态码错误。
- 修复问题:当服务中配置了
控制面
- 修复问题:当组名称相似时,ADC 同步可能会同步到错误的网关组。
- 修复问题:即使没有匹配的规则,登录选项角色映射也会保留之前的角色。
- 修复问题:OIDC 登录选项的请求范围字段中存在多余的添加按钮。
- 修复问题:旧配置有时不会显示在“编辑登录选项”表单中。
- 修复问题:由于核心资源 Schema 过于复杂,ADC diff 比较期间会发生不必要的更改。
- 修复问题:更新用户角色时,用户的
updated_at时间戳未刷新。
3.8.15
发布日期:2025-10-13
新功能
插件
- Lago
- 新增插件。
- Traffic Split
- 现可用于 Stream Service。
- 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配置相互干扰。 - 修复问题:前端控制台构建过程中出现的警告信息。
数据面
- 修复问题:密钥无法动态更新。
开发者门户
- 修复问题:在 Provider Portal 中为使用 ADC 创建的服务创建产品时无法查询 OAS。
- 修复问题:在 Provider Portal 中下载 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_accessAPI 调用,以减少冗余请求。 - 在上游连接配置中增加了
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_param_*变量。 - 将 API7-EE-3-Gateway 的基础镜像升级至 Ubuntu 24.04。
开发者门户
- 支持开发者在应用中查看当前 API 用量统计。
- 将 Scalar 升级至 0.7.25 版本。
依赖项
- 将 Casbin 升级至 1.41.9 版本。
控制台(Dashboard)
- 通过添加
config.controllerName优化了 Ingress 网关组部署脚本。
缺陷修复
数据面
- 修复问题:由于健康检查数据导致
routes()响应数据损坏。 - 修复问题:
grpc-web响应可能包含重复的 trailer chunk。 - 修复问题:
proxy-cache插件中不同策略的响应头不一致。
插件
- API Breaker
- 修复问题:由于实现中的时间点(
breaker_time)不准确,api-breaker插件未能正确触发。
- 修复问题:由于实现中的时间点(
- AI Proxy
- 修复问题:通过新增
apisix_upstream_response_time变量衡量 APISIX 与上游通信并接收响应所需时间,解决upstream_response_time为空的问题。
- 修复问题:通过新增
控制台(Dashboard)
- 修复问题:并发请求为新网关组生成部署脚本可能产生重复的键。
- 修复问题:在不同路由间反复点击“查看 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 的支持。
缺陷修复
插件
- OpenID Connect
- 修复问题:发生错误时会话未正确关闭,导致资源泄漏。
数据面
- 修复问题:执行
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
新功能
插件
- 自动在自定义插件的 Schema 中插入
_meta。
数据面
- 支持在
conf/config.yaml中配置apisix.disable_upstream_healthcheck,通过单个开关禁用所有健康检查。 - 通过减少内存消耗优化 Prometheus 性能。
- 发布了 API7 Ingress Controller 2.0。
控制台(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 服务发现在上游节点数量较多时出现性能问题。
- 修复问题:HTTP 标头的大小写不一致,现已统一为词首字母大写格式。
3.8.2
发布日期: 2025-05-19
新功能
插件
- AI Proxy Multi
- 新增对 429/5xx 响应码的重试逻辑,提高请求成功率。
数据面
- 新增支持反向代理 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
新功能
插件
- AI Proxy
- 实现了新的标识字段
logging和summaries,用于收集 LLM 请求和响应内容。
- 实现了新的标识字段
- AI Proxy Multi
- 支持 HTTP POST 方法的健康检查。
- 如果触发了回退,则在警告日志级别显示记录。
- 实现了新的标识字段,用于收集 LLM 请求和响应内容。
- AI Aliyun Content Moderation
- 新增对流式(HTTP SSE)场景的支持。
- AI Prompt Guard
- 新增插件。
- Kafka Logger
- 支持读取缓存在
ctx中的用户请求和响应体内容,并将其推送到指定的 Kafka 服务。
- 支持读取缓存在
数据面
- 支持在路由条件中使用用户请求体中数组对象的值。虽然
post_arg已在路由条件中允许使用,但本次更新引入了对类型字段位置的数组场景支持。 - 支持在访问日志中记录额外的 AI 请求上下文信息。
- 支持向 Prometheus 指标添加请求类型标识符,以收集更细粒度的 AI 请求数据。
控制台(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
缺陷修复
控制台(Dashboard)
- 优化了控制面升级时数据量较大的表迁移的速度。
3.7.6
发布日期: 2025-06-02
缺陷修复
数据面
- 修复问题: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:
缺陷修复
数据面
- 修复问题:重复的网关实例 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 产品允许多种认证类型,则可以使用任何有效的凭据。
缺陷修复
数据面
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-18
缺陷修复
数据面
- 修复问题:无法启用
Log Rotate插件。 - 修复问题:升级过程中,特别是使用 MySQL 数据库时,网关实例偶尔会出现重复数据。
- 修复问题:删除自定义插件偶尔会失败。
- 修复问题:数据面上报指标时偶尔遇到 500 错误。
插件
- Proxy Rewrite
- 修复问题:插件的版本兼容性问题。
Admin API
- 列出网关组中已发布服务的所有 Stream Route
- 修复问题:响应错误。
控制台(Dashboard)
- 修复问题:版本升级期间先升级控制台、再升级 DP Manager,可能导致 DP Manager 持续重启。
3.5.1 版本
发布日期:2025-02-06
缺陷修复
插件
- OpenTelemetry
- 修复的问题:插件上报动态路由
/v2/:customerNumber时,无法将request.url作为route.url上报。
- 修复的问题:插件上报动态路由
控制台(Dashboard)
- 修复的问题:无法配置 Azure SMTP 服务器发送告警邮件。
3.5.0 版本
发布日期: 2025-01-27
新功能
数据面
- 一个服务中的多个上游:对于金丝雀部署、蓝绿部署或管理多个集群等高级场景,一个服务现可使用多个上游。在这种情况下,默认上游是大多数请求的主要目标,其他上游可用于将流量路由到金丝雀部署或备用集群等特定用途。详情请参阅更新后的灰度流量。
旧的 Canary Rule 功能不再可用。
- 支持通过 Prometheus 插件元数据自定义数据面指标标签配置。
- 优化数据面 Prometheus 指标上报性能。
- [Beta] 为上游配置 mTLS。目前已提供 API 支持,完整支持即将推出。
插件
- OpenID Connect
- 为没有
end_session_endpoint的插件新增redirect_after_logout_uri。#10653
- 为没有
- Zipkin
- 新增 Zipkin 变量。#10361
- Proxy Rewrite
- GRPC web
- 支持配置
allow-headers。#10904
- 支持配置
- Mocking
- 支持添加 HTTP 标头。#9720
- OPA
- 支持向上游发送 OPA 返回的请求头。#9710
- HTTP Logger
- Logger 支持压缩响应。#10884
- Kafka Logger
- Logger 支持压缩响应。#10884
- RocketMQ Logger
- Logger 支持压缩响应。#10884
- Traffic Split
- 支持 HTTPS。#9115
Admin API
- 新增与多个上游相关的 API:
- 为新功能上游 mTLS 配置更新了已发布服务 API:
- 在网关组中创建已发布服务
- 新增属性:
client_certificate、ca_certificate、tls_verify。
- 新增属性:
- 在网关组的已发布服务中创建上游
- 新增属性:
client_certificate、ca_certificate、tls_verify。
- 新增属性:
- 更新已发布服务(不发布)
- 新增属性:
client_certificate、ca_certificate、tls_verify。
- 新增属性:
- 在网关组的已发布服务中更新上游
- 新增属性:
client_certificate、ca_certificate、tls_verify。
- 新增属性:
- 在网关组中创建已发布服务
控制台(Dashboard)
- 一个服务中的多个上游:对于金丝雀部署、蓝绿部署或管理多个集群等高级场景,一个服务现可使用多个上游。在这种情况下,默认上游是大多数请求的主要目标,其他上游可用于将流量路由到金丝雀部署或备用集群等特定用途。详情请参阅更新后的灰度流量。
- 超过许可证 CPU 限额后,禁止创建新资源。
- 为 API7 Portal 控制台页面新增每页条目数选择。
- 插件配置同时支持 YAML 和 JSON 格式。
- 改进上游健康检查配置界面。
- 将启用/禁用插件重命名为添加/删除插件,以提高准确性。
缺陷修复
插件
- Traffic Split
- 修复问题:LRU 缓存对象创建函数导致客户端请求异常。
- Limit Conn
- 修复问题:在 Stream 模式下使用 HTTP 变量时报告属性不存在的错误。#9816
- Prometheus
- 修复问题:禁用 Prometheus 插件后,相关功能未完全关闭。#11117
- OpenID Connect
- 修复问题:未配置
redirect_uri时将其设为ngx.var.request_uri,导致底层lua-resty-openidc模块报错。#7690
- 修复问题:未配置
- Zipkin
- 修复问题:在日志阶段获取到
nil值。#10666
- 修复问题:在日志阶段获取到
- Proxy Rewrite
- 修复问题:未设置
ngx.var.uri导致不兼容。#9309
- 修复问题:未设置
- Log Rotate
- 修复问题:使用
string.byte的效率低于string.sub。#9984
- 修复问题:使用
3.4.2
发布日期:2025-02-18
缺陷修复
Admin API
- 列出网关组中已发布服务的所有 Stream Route
- 修复问题:响应错误。
控制台(Dashboard)
- 修复问题:版本升级期间先升级控制台、再升级 DP Manager,可能导致 DP Manager 持续重启。
3.4.1 版本
发布日期: 2025-01-14
缺陷修复
数据面
- 修复问题:在数据面配置
access_log_format并将access_log_format_escape设为json时,结果会额外附加一个request_id。
控制台(Dashboard)
- 修复问题:在 API7 门户中使用 BasicAuth 身份认证进行在线调试时,无法粘贴密码。
3.4.0 版本
发布日期: 2025-01-07
新功能
数据面
- SNI 管理:引入 SNI 作为管理 TLS 和 mTLS 身份认证及证书匹配的新机制。详情请参阅配置客户端与 API7 网关之间的 mTLS。
插件
- OpenID Connect
- Fault Injection
- 支持注入 HTTP 标头。#9039。
- Skywalking Logger
- Forward Auth
- Elastic Search Logger
- Prometheus
- 支持自定义
DEFAULT_BUCKETS。#9673
- 支持自定义
- CORS
- 支持
Timing-Allow-OriginHTTP 标头。#9365
- 支持
- File Logger:
- 为 Logger 插件新增 Schema 属性定义。#10738
- HTTP Logger:
- 为 Logger 插件新增 Schema 属性定义。#10738
- Syslog
- Logger 插件新增包含请求体和响应体的选项。#10888
- SLS Logger
- Logger 插件新增包含请求体和响应体的选项。#10888
- TCP Logger
- Logger 插件新增包含请求体和响应体的选项。#10888
- UDP Logger
- Logger 插件新增包含请求体和响应体的选项。#10888
- Tencent Cloud CLS
Admin API
- 新增与 SNI 相关的 API:
控制台(Dashboard)
- API7 Portal 监控:提供监控数据和可视化,以追踪 API 产品指标。
- 将自定义插件配置应用于网关组级别。详情请参阅新增自定义插件。
缺陷修复
数据面
- 修复问题:Redis 延迟同步功能使用的共享内存发生泄漏。
- 修复问题:不安全地向外部服务发送请求时产生警告日志。#11403
插件
- AI Proxy
- 修复问题:
override.endpoint中的查询参数未发送给 LLM。
- 修复问题:
- OpenID Connect
- 修复问题:使用可加锁的会话存储后端时未关闭会话,导致阻塞直到 TTL 到期。#10788
- Forward Auth
- GRPC Web:
- 修复问题:收到缺少 Trailer 的错误。#10851
- GRPC Transcode
- 修复问题:
pb_option_def中枚举值的位置错误。#11448
- 修复问题:
控制台(Dashboard)
- 修复问题:发布多个服务时未能记录审计日志。
依赖项
- 数据面升级到 LuaJit 2.1-20240815。
- 移除了
grpc-client-nginx-module。
3.3.4
发布日期:2025-02-18
缺陷修复
Admin API
- 列出网关组中已发布服务的所有 Stream Route
- 修复问题:响应错误。
控制台(Dashboard)
- 修复问题:版本升级期间先升级控制台、再升级 DP Manager,可能导致 DP Manager 持续重启。
3.3.3 版本
发布日期: 2025-01-14
缺陷修复
数据面
- 修复问题:在数据面配置
access_log_format并将access_log_format_escape设为json时,结果会额外附加一个request_id。
控制台(Dashboard)
- 修复问题:在 API7 门户中使用 BasicAuth 身份认证进行在线调试时,无法粘贴密码。
3.3.2 版本
发布日期: 2024-12-24
缺陷修复
控制台(Dashboard)
- 修复问题:从 3.2.16.2 或更早版本升级到 3.3.1 及更高版本时,控制台无法启动。
3.3.1 版本
发布日期: 2024-12-19
缺陷修复
数据面
- 修复问题:在 rewrite 阶段运行的插件命中消费者后会重复执行。
3.3.0 版本
发布日期: 2024-12-17
新功能
数据面
- 重构数据面的过期和淘汰机制。
插件
- OpenID Connect
- 同步了最新的 APISIX 代码。
- Datadog
- 上报消费者用户名标签。#11354
- Body Transformer
- 支持
content-type使用x-www-form-urlencoded格式,并解析 GET 请求的 URI 参数。#10496
- 支持
- OpenTelemetry
- 新增变量。#8871
- OpenID Connect
- 新增
proxy_opts属性。#9948
- 新增
控制台(Dashboard)
- 宣布 API7 Portal 正式发布(GA)。它为 API 发布和使用提供完整方案。了解 API 门户(API Portal)和开发者的核心概念,并开始将服务产品化。
- 在访问日志和错误日志中记录请求 ID。
- 告警策略未配置通知渠道时,在告警历史记录中显示提示。
- 支持与外部 Prometheus 指标集成。
安全
- 修复 CVE 报告中的漏洞。
缺陷修复
数据面
- 修复问题:除 404 错误外,数据面对 DPM 的消费者查询错误不应被缓存。
插件
- CORS
- 修复问题:
Access-Control-Expose-Headers响应头会被覆盖。#11136。
- 修复问题:
- Body Transformer
- 修复问题:
input_format枚举缺少防止解析和校验请求体的选项,导致不必要的警告。#10862
- 修复问题:
控制台(Dashboard)
- 修复问题:禁用 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.1 版本
发布日期:2024-12-09
缺陷修复
- 修复的问题:DP Manager 收到截断的 Prometheus 指标时会陷入无限循环。
- 修复的问题:watch 中断可能导致数据面与控制面的同步中断。
3.2.16.4 版本
发布日期: 2024-11-01
新功能
通过电子邮件发送通知
借助新的联系点,告警策略可以同时通过 Webhook 和电子邮件发送通知。一个联系点定义一组电子邮件地址或 Webhook URL,可供多个告警策略使用。
有关操作说明,请参阅网关告警通知。
现有的 Webhook Templates 会迁移为新的联系点和通知,以确保告警策略平滑过渡并保持向后兼容。
Limit Count Advanced 插件
通过滑动窗口算法增强开源 Limit Count 插件,使限流更加精确。
Exit Transformer 插件
Exit Transformer 插件支持根据 APISIX 插件返回的状态码、头部和响应体自定义网关响应。将其配置为全局插件后,请求不存在的路由时也能自定义响应。
通过告警策略统计网关组中的健康网关实例数
如果网关组中健康网关实例数量低于临界阈值,可能出现服务中断并影响流量处理。在 Kubernetes 部署中,这尤其相关,因为网关实例可能故障或意外缩容。
创建统计网关组中健康网关实例数的告警策略,并向相关人员发送通知。
使用表达式匹配
在路由上启用 Expression Match,按特定变量更精确地匹配请求,类似 nginx。使用 [[var, operator, val], [var, operator, val], ...] 格式的表达式定义匹配条件。请注意,Cookie 名称匹配区分大小写。
详情请参阅表达式和 lua-resty-expr。
安全
- 新增用于数据面自身健康检查的状态接口。详情请参阅为高可用启用数据面健康检查。
改进
- JWT Auth 插件现支持更多算法。
- 在 Grafana Dashboard 模板中增加了更多指标。
- 允许用户按 Enter 键登录。
缺陷修复
- 修复问题:CORS 插件的
expose_header默认值不应为*。 - 修复问题:添加 Stream Service 时成功添加第一条 Stream Route。
- 修复问题:
max_req_body_bytes限制在 Logger 插件中不生效。 - 修复问题:Limit Count 插件的限流参数动态更新现会反映在数据面。
- 修复问题:通过 API 删除的服务现能从数据面一致地移除。
3.2.16.3 版本
发布日期: 2024-10-21
新功能
引用在 AWS Secrets Manager 中的机密信息(Secrets)
Secret 对象是一条需要防止未经授权访问的敏感信息,而 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,以符合最佳实践并促进与外部密钥管理工具的集成。所有相关的 API 都已相应更新。
Secret 对象是一条需要防止未经授权访问的敏感信息,而 Secret 提供商(Secret Provider) 对象用于设置与外部机密信息管理器(HashiCorp Vault、AWS Secret Manager 等)的集成,以便 API7 网关可以在运行时动态地建立连接并从机密信息管理器中获取机密信息。
有关更多详细信息,请参阅 引用 HashiCorp Vault 中的密钥。
功能优化
- 【不兼容变更】删除了 JWT 插件签发 Token 的功能,并删除了上传私钥的功能。 详情请参阅 JWT 插件。
- 增加了对删除离线网关实例的支持。
- 为使用 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.1 版本
发布日期:2024-12-09
缺陷修复
- 修复的问题:DP Manager 收到截断的 Prometheus 指标时会陷入无限循环。
- 修复的问题:watch 中断可能导致数据面与控制面的同步中断。
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.6 版本
发布日期:2024-08-28
新功能
ARM 安装包
从 3.2.14.6 版本开始提供标准化的 ARM 安装包。
安全性
- 修复已知的 CVE 漏洞。
功能优化
- 通过优化组件缩小安装镜像的大小。
- 支持在四层路由中使用
mqtt-proxy插件。 - 告警策略触发条件新增
Allowed license CPU quota exceeded。
缺陷修复
- 将数据面证书写入固定的本地文件。
- 修复启动灰度发布时,无法直接将灰度上游的权重设为 100 的问题。
- 调整自定义插件在
init_worker阶段的顺序,以避免数据面重启时打印警告日志。 - 修复通过 Admin API 调用未指定方法时,界面上路由的
Methods显示为空的问题。 - 修复通过 ADC 同步时,路由名称长度被限制为 100 个字符的问题。
- 修复告警策略禁用后仍发送告警的问题。
3.2.14.5.1 版本
发布日期:2024-12-09
缺陷修复
- 修复的问题:DP Manager 收到截断的 Prometheus 指标时会陷入无限循环。
- 修复的问题:watch 中断可能导致数据面与控制面的同步中断。
3.2.14.5 版本
发布日期:2024-08-20
缺陷修复
- 修复了
response-rewrite插件在body_base64设为false时的响应体校验缺陷。
3.2.14.4.1 版本
发布日期:2024-12-09
缺陷修复
- 修复的问题:DP Manager 收到截断的 Prometheus 指标时会陷入无限循环。
- 修复的问题:watch 中断可能导致数据面与控制面的同步中断。
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 插件修复(https://github.com/apache/apisix/pull/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 错误。
- 修复了开发者门户的库问题。
- 修复了 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 不兼容变更
- 服务模板 API 已迁移到 "/api/services/template" 路径前缀下。
- 原始的 "/apisix/admin/services" 端点现在需要 gateway_group_id 参数。
新增功能
在网关组上创建/更新服务而不发布
如果版本控制不是你的要求,你现在可以直接在网关组上创建服务。这些服务会立即生效,无需单独的发布步骤。这简化了部署过程并节省了时间。
但是,重要的是要考虑所涉及的权衡。通过绕过发布阶段,你也失去了轻松回滚到以前版本或跟踪版本更改的能力。
有关详细信息,请参阅最新的入门教程:启动你的第一个 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 不兼容变更
- service status 字段从“0: 启用,1: 禁用”变更为“0: 禁用,1: 启用”
- consumer api 移除 id 字段,使用 gateway group id & username 做查询、删除
- ssl 相关 api 强制 gateway group id 参数
新增功能
四层路由(Stream Route)
API7 网关除了管理 API,还可以处理数据库或 Kafka 连接等四层流量。添加一个 Stream Service 和若干条 Stream Route,即可转发四层流量。
自定义角色 (控制台支持)
你可以自行设计自定义角色,实现精细化权限控制。可参阅添加自定义角色
Ingress Controller(Beta 测试版,仅 API 支持)
集成 Ingress Controller。
功能优化
优化左侧导航菜单
- 用户现在会看到网关组菜单作为默认落地页。
- 服务 菜单项改名为 服务中心。
缺陷修复
- 使用 Key Auth 插件时,禁止出现重复的 API 密钥。
- 使用 UA Restriction 插件时,允许同时配置黑名单和白名单。
- 重置用户密码时不会引起访问 Token 失效。
- 标签长度可达 64 个字符,并可包含空格。
- 使用 Loggly 插件时配置能校验成功。
- 即使 Schema 校验出错,也强制将配置同步到数据面,以防止数据丢失并确保工作流不中断。
- 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 角色映射
自动角色映射使超级管理员不再需要手动分配角色。满足指定键值映射规则的用户在登录时会自动获得相应角色。详情参阅设置角色映射。
SCIM 用户同步
通过 SCIM 用户预配简化身份管理。它会自动同步身份提供方的用户数据,确保用户管理保持一致且更轻松。详情参阅从 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 单点登录(SSO)
API7 企业版支持使用 SAML 实现单点登录(SSO)。有关如何配置 SAML SSO 登录方式的详情,请参阅配置 SAML SSO。
新插件: Data Mask
Data Mask 插件提供了在请求头、请求体和 URL 查询中移除或替换敏感信息的能力。
功能优化
忽略路径前缀
你可以选择在向上游发送请求时跳过路径前缀。这种调整对用户来说是不感知的,并且在使用不同的路径前缀来识别发送到不同网关组的 API 时可能很有用。
优化健康检查配置 UI
提供一个更直观友好的健康检查配置交互界面。
升级加密算法
从 AES128 升级到 AES256。
性能提升
消除了禁用插件带来的影响。
版本 3.2.9.1
发布日期:2024-03-19
新增功能
支持自定义插件管理
API7 企业版现支持开发自定义插件,以扩展功能并通过自定义流程管理 API 流量。详情见新增自定义插件。
支持 OIDC 第三方登录
API7 企业版支持基于 OIDC 实现的单点登录(SSO)。有关如何配置 LDAP SSO 登录方式的详细信息,请参阅使用 LDAP 配置 SSO。
将服务标签作为 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 添加网关实例的具体信息,参见添加网关实例。