跳到主要内容
版本：1.2.0

发布说明

本页汇总 AISIX 网关、控制面、控制台和部署包中面向用户的变更，按版本从新到旧排列。

如果一次升级跳过了若干版本，其间每个版本的升级说明依然适用。请按从旧到新的顺序阅读——从你当前版本的下一个版本开始，一直读到目标版本。支持的升级路径和升级顺序参见升级 AISIX。

发布产物包括 docker.io/api7/aisix 网关镜像、docker.io/api7/aisix-cp-* 下的控制面镜像、aisix-cp Helm Chart 和离线安装包。

1.2.0​

发布日期： 2026 年 9 月 8 日

本版本明确了最低支持版本，并加强了网关配置兼容性校验：控制面会在保存前拒绝已注册网关无法加载的配置。网关优化了配置变更处理，避免每次 watch 事件都产生与完整配置规模成正比的开销，解决批量修改配置导致请求处理阻塞的问题。此外，运维人员可以按指标选择标签集合；OpenAI 上游返回的原始缓存写入计数也会完整保留在网关响应、用量日志及其导出结果中。

行为变化​

  • Token 用量恰好达到窗口上限时，网关现在会拒绝新请求。 此前，当已提交的 Token 计数恰好达到上限时，tpm 和 tpd 仍会额外放行一个请求，只有超过上限后才会拒绝。内存和共享 Redis 两种后端现在使用相同的上限判断规则，切换后端不会改变实际限流行为。此变更适用于所有 Token 窗口，包括由策略派生的窗口和 API Key 级窗口。窗口上限显式配置为 0 时，现在会拒绝所有请求，与上限为 0 的请求计数窗口（例如 rpm）保持一致。请求计数采用预扣方式，此前已能准确执行上限，因此行为不变。

  • 控制面现在会拒绝保存已注册网关无法加载的配置。 控制面会根据目标环境中各已注册网关版本的配置读取规则，校验每份投影文档；只要某个受支持版本无法加载该文档，就返回 422 DP_INCOMPATIBLE。此前，写入会成功，响应中仅包含一条 row_rejected 告警，此时资源可能已在部分网关上停止生效。error.message 会完整说明网关版本、受影响的网关及配置中存在问题的部分；error.dp_compat 则以结构化字段提供相同信息。row_rejected 告警码已移除。新增的 below_floor 告警用于报告低于控制面最低支持版本的网关；控制面不对这些旧版本网关执行兼容性校验。

    网关停止上报后，其注册信息仍会保留 5 分钟。因此，集群升级后的一段时间内，拒绝信息仍可能列出集群中已不再运行的旧版本。这是预期的保守校验行为：旧注册信息过期前，控制面仍会将其纳入检查。拒绝信息包含 last_heartbeat_age_seconds，可在过期注册信息被清理后重试。

  • 数据库记录的上一次控制面版本低于 0.12.0 时，控制面会拒绝启动。 控制面 API 服务（cp-api）会在启动迁移时记录自身版本。如果数据库中记录的版本低于最低支持版本，服务会停止启动，并提示已记录的版本及处理方式。离线安装包的 run.sh 也会在启动任何容器前拒绝此类升级。请先升级到受支持的版本，或在完成备份后设置 AISIX_ALLOW_UNSUPPORTED_UPGRADE=1。API 服务和安装脚本均支持该环境变量，Helm Chart 中可通过 api.extraEnvVars 设置。全新安装不受此限制；上一次使用该数据库的控制面版本尚未引入版本记录机制时，也不受此限制。

  • 显式为空的 ignore_statuses 列表现在会被保留。 此前，创建或修改模型时提交的空列表会被接受，但随后会被替换为 [408, 429]，并以该默认值存储、返回和投影。这导致后台健康探测仍会忽略 408 和 429，未按用户配置将其视为失败，且没有提示输入已被覆盖。现在，空列表在存储、GET 返回结果和网关配置中均保持为空列表。省略该字段的行为不变，仍使用默认值 [408, 429]。本版本之前保存的模型会保留已被替换的默认值，需显式设置为空列表后重新保存。

  • 使用非 Anthropic 上游时，系统提示词中的 Anthropic 计费归属行会被移除。 Anthropic 原生客户端会在系统提示词开头添加一行 x-anthropic-billing-header；在某些部署中，该行的部分内容会随请求变化，导致其他模型服务提供方收到的提示词前缀每轮都不同，无法命中提示词缓存。对于 POST /v1/messages 和 POST /v1/messages/count_tokens，如果解析出的目标并非目录中的第一方 anthropic 提供方，网关会在构建上游请求前移除该行：对于数组形式的 system，移除计费归属块；对于字符串形式的 system，移除第一行。提示词其余部分（包括 cache_control 标记）逐字节保留，messages 不会被修改。判断依据是目录中的厂商 ID：指向区域性或经代理的 Anthropic 端点的第一方凭据会保留该行；OpenAI Chat 桥接、第三方 Anthropic 兼容透传，以及 Bedrock、Vertex、Azure 平台适配均会移除该行。此变更无需调整配置，未发送该行的调用方不受影响。

新功能​

  • 按指标选择标签。 新增 observability.metrics.labels 配置块，用于声明每个指标族的完整标签列表；也可通过环境变量 AISIX_OBSERVABILITY__METRICS__LABELS 以 JSON 对象形式配置。未配置的指标族保留原有默认标签，因此升级后无需调整现有指标配置。标签选择在观测值累加前生效，移除 counter 或 histogram 的标签会聚合对应的观测值，不会丢弃观测数据；gauge 会保留用于标识序列的必需标签。未知的指标名称、不支持的标签变量或重复标签会导致启动失败，配置变更需重启后生效。首 Token 时间和请求延迟指标现在支持在原生和桥接请求路径上添加模型服务提供方凭证及调用方归属标签，这些标签默认不启用。

  • 控制台的网关安装页面支持选择指标标签。 运维人员可以添加受支持的标签、移除默认标签或恢复默认配置。Docker、Compose、Helm 和 systemd 安装指令都会通过启动环境变量包含完整的标签配置。这是网关进程级设置，不新增资源字段，也不改变资源投影。

  • 完整保留 OpenAI 上游返回的原始缓存写入计数。 cache_write_tokens 现在会保留在网关响应的 usage.prompt_tokens_details.cache_write_tokens 中，并传递至用量事件、Admin API 的用量日志列表与导出结果，以及控制台的日志详情。此功能覆盖原生 OpenAI 请求、各协议桥接、旧版非流式 Completions 及可识别的透传用量。显式返回的 0 与字段缺失保持区分，上游未提供该字段时不会补值。该字段保存原始计数，与 Anthropic 可累加的 cache_creation_tokens 分开存储，不改变 Token 总数，也不影响计费。历史用量记录中的该字段不会补填。

改进​

  • 批量修改配置不再阻塞网关请求处理。 此前，每次配置写入成功后，网关都会深拷贝完整快照，重新解析所有存储文档并进行规范化序列化，以重新计算两个哈希值，随后递增全局版本号。所有派生缓存均使用该版本号判断是否失效，因此每次写入的处理开销都与完整配置规模成正比。各工作线程收到下一个请求时，还会同步重建完整的护栏索引：为每个启用的挂载创建运行时和 HTTP 客户端，并分别重新加载 CA 存储。如果构建期间快照发生变化，构建会反复重试，且没有重试次数上限。该线程上的 /livez 请求也需等待这些操作完成。

    派生缓存现在根据其读取的表判断是否失效。每个已配置的护栏仅构建一个实例，并在各挂载间共享；只要对应配置行未变化，索引重建时就会复用该实例。并发触发的索引构建会合并执行，原有的重试循环已移除。快照克隆改为结构共享，每个条目版本的摘要仅计算一次，排队的配置事件在同一个写时复制周期内批量应用。聚合式 /mcp 端点也会按配置行缓存各 MCP Server 的工具集，无需在每次调用时重新遍历所有已注册的 OpenAPI 文档。

    配置、协议结构和上报值保持不变：config_hash 和 source_hash 逐字节一致，请求所应用的护栏及被拒绝配置行的上报行为均不变。新增 info 级别日志 guardrail index rebuilt，记录各类配置行数及构建、复用的实例数量。

  • 修复三个指标族未输出的问题。 aisix_redis_failures_total、aisix_otlp_fanout_failures_total 和 aisix_otlp_fanout_drops_total 此前虽已定义输出方法，但未被调用，因此查询结果始终为空。这些指标用于观察采用失败放行策略的子系统是否发生降级。Redis 失败现在按限流存储、响应缓存和语义缓存分别计数，并通过包含子系统信息的操作标签（如 ratelimit_acquire、cache_get、semantic_lookup）区分来源，便于在共用 Redis 时识别发生降级的子系统。OTLP 扇出会统计每次失败的导出尝试，包括重试；丢弃记录按 queue_full、worker_stopped、retries_exhausted 和 permanent_error 分类计数。批次被丢弃时，按批次中的记录条数计入。

  • 控制台页面在数据加载失败时会显示明确的错误提示。 此前，列表数据为 null 同时表示“仍在加载”和“加载失败”，导致错误卡片下方持续显示加载动画，部分页面甚至没有错误提示。现在，列表页会在加载成功或失败后结束加载状态。此变更覆盖团队及团队详情、预算、A2A Agent、管理员令牌、MCP Server、模型服务提供方凭证、定价、审计、通知渠道及投递记录，以及三个用量列表；也覆盖环境内的模型、API Key、限流策略、缓存策略、Claim 映射、OIDC 提供方、透传路由、可观测性、日志和 MCP 策略页面。组织设置卡片及团队 MCP 授权卡片采用相同处理方式。设置页和通知页在组织列表加载失败时会显示标准提示条。刷新或重试时，页面会重新进入加载状态，避免在请求进行期间持续显示上一次失败的提示。

修复​

  • Redis 不可达时，不再让每一个用到它的请求挂起。 当 ratelimit.backend 为 redis，或某条缓存策略使用 Redis 后端时，运行期出故障的 Redis 此前会让这些请求等上数分钟，而不是降级；aisix_redis_failures_total 会记下这次失败，却没有任何请求结果随之而来。现在每一次 Redis 往返和连接尝试都由各 redis: 块下新增的 timeout_secs 约束，默认 5 秒。在这个预算之内，既有的失败即放行路径会接管：限流回落到进程本地计数器，缓存则记为未命中。一次失败之后，该子系统会短路 30 秒，因此中断期间大约每 30 秒只有一个探测请求会付出完整预算。熔断器按子系统共享：缓存的精确连接和向量连接算作一个，限流器是另一个。Redis 恢复之后，网关最多在 30 秒内察觉，在此之前限流按副本各自计数、缓存记为未命中；上游环节耗时超过 30 秒的请求，仍可能在缓存写入时再付出一份预算。之后共享计数会自动恢复，既不需要重启，也不需要改配置。

  • 控制面无法提交的写入，不再返回 2xx。 每请求的事务此前是在处理函数的响应已经发出之后才提交的。读取状态行后就断开的调用方会取消上下文，随后提交失败、插入被回滚，而这个调用方手里却留着一个 201，对应的记录已经不存在。现在写操作的响应会一直挂起到提交成功为止：一个事务没能保住的 2xx 会被丢弃，改为以标准错误信封返回 500，记录照旧回滚。只有 2xx 会被扣住，409、400 或 499 与此前完全一样地送达。保持连接的调用方感受不到任何差别。

  • 多行 data: 流式帧现在会正确返回调用方使用的模型别名。 事件流格式允许单个帧的负载分布在多行 data: 中，并以换行符连接。此前，模型 ID 改写逻辑只读取第一行，导致这类帧无法解析为 JSON，进而被原样转发，调用方收到的是上游模型 ID，而非请求中使用的模型别名。受影响的帧包括 /v1/messages 的 message_start 帧和 /v1/responses 的快照帧。现在，网关会读取拼接后的完整负载，改写模型 ID，并将各行写回原位置，保留原有分帧结构和换行格式。

  • 控制台不再无限重试失败的令牌签发。 此前，控制台未记录签发失败状态。当认证服务不可达时，预算提示条的轮询会使每个打开的标签页每 30 秒启动一轮新的签发，每轮尝试 3 次。现在，签发失败后会保存错误，并进入指数退避窗口：初始为 30 秒，逐次翻倍，最长为 5 分钟。窗口内的请求直接返回已保存的错误，不再发起签发尝试。下一次签发成功或退出登录时会重置退避状态。若刷新失败时旧令牌仍有效，则继续使用旧令牌，与此前行为一致。

  • 路由模型的审计记录不再包含未设置字段的 null 值。 此前，路由模型未设置 hash_on 和 fallback_on_statuses 时，审计事件会将其记录为 JSON null，但 API 既不接受也不返回该值。现在，未设置时会省略这些字段，与网关配置文档保持一致。历史记录不会被改写。

API 变化​

API 结构对比显示，本版本未新增或移除操作，未改变请求结构，新增了响应结构定义 DataPlaneIncompatibleError。破坏性变更检查未报告错误，报告的 36 条告警均为响应枚举新增取值。以下响应及行为变化仍需调用方适配。

端点变化
32 个会向网关投影配置的写操作，包括：模型、API Key（含 /rotate）、护栏及护栏挂载的 POST 和 PATCH；限流策略、缓存策略（含 /purge）、Claim 映射及透传路由的 POST 和 PATCH；可观测性导出器、OIDC 提供方、MCP Server（含 /approve）及 MCP Server 提交的 POST 和 PATCH；模型服务提供方凭证及 A2A Agent 的 POST 和 PATCH；以及 PATCH /environments/{env_id}、PUT /environments/{env_id}/mcp_policy 和 PUT /model_pricing。新增 422 响应 DataPlaneIncompatibleError，在目标环境中已注册的受支持网关无法加载待保存配置时返回。error.code 为 DP_INCOMPATIBLE，error.message 提供可直接展示给运维人员的完整错误说明。error.dp_compat 包含 kind、dp_version、path、reason、affected_dp_count、affected_dp_nodes、affected_dp_versions 和 last_heartbeat_age_seconds。调用方需在所有向网关投影配置的写操作中处理 422，并根据错误提示升级受影响的网关或移除不兼容的设置。
上述操作中会返回 warnings 的 27 个创建与更新操作，以及获取单个模型、API Key、护栏、限流策略、缓存策略、Claim 映射、透传路由、MCP Server、模型服务提供方凭证或 A2A Agent 的 GET 操作。warnings[].code 枚举移除 row_rejected，新增 below_floor。此前返回 row_rejected 告警的情况，现在改为返回 422 DP_INCOMPATIBLE。below_floor 用于报告低于控制面最低支持版本的网关，其 field 为空，因为告警针对网关版本而非具体配置字段。依赖 row_rejected 告警码进行分支处理的自动化程序需相应更新。
  • GET /environments/{env_id}/usage_events
  • GET /environments/{env_id}/usage_events/export
用量事件响应新增可选字段 cache_write_tokens。对于本版本之前的历史记录，以及上游未上报缓存写入计数的记录，该字段不返回。显式的 0 与字段缺失保持区分。该字段保存原始计数，不与提示词 Token 数相加。

另有三处行为或语义变化，无法通过结构对比识别：

  • CompatibilityWarning.min_dp_version 的类型和 unreleased 哨兵值保持不变，但含义改为能够读取该字段的最低受支持网关版本；对于 below_floor，则表示控制面支持的最低网关版本。此前，该字段表示能够完整执行字段功能的最低网关版本，取值来自手工维护的映射表。affected_dp_count 的含义也从“运行版本低于 min_dp_version 的已注册网关数量”改为“此告警适用的已注册网关数量”。数据结构不变，但部分集群返回的数量可能变化。
  • background_model_check.ignore_statuses 此前接受 []，但实际存储为 [408, 429]；现在会按空列表存储、返回和投影。请求结构不变，但调用方提交 [] 后读回的值已改变。字段描述也明确了空数组的含义，以及创建和 PATCH 操作中省略 background_model_check 时各自的行为。
  • 租户作用域下的每一个写操作，在此前会返回一个记录已被回滚的 2xx 的场景中，现在返回 500。这只有在调用方写入过程中断开时才可能触发，而那种情况下它什么也收不到。形状没有变化，对保持连接的调用方也没有变化。

升级说明​

从早于 1.2.0 的版本升级至本版本或后续版本时，均需遵循本节说明，包括跳过 1.2.0 的升级。

  • 如果当前版本低于 0.12.0，请先升级到 0.12.0 或更高的受支持版本，再升级到本版本。数据库记录的上一次控制面版本低于 0.12.0 时，控制面 API 服务和离线安装包均会拒绝升级。完成备份后，可设置 AISIX_ALLOW_UNSUPPORTED_UPGRADE=1 绕过该限制；Helm Chart 中可通过 api.extraEnvVars 设置。本控制面支持 0.12.0 及更新版本的网关。
  • 请更新依赖 row_rejected 告警码进行分支处理的自动化程序。此前返回该告警的情况，现在改为返回 422 DP_INCOMPATIBLE，所有向网关投影配置的写操作都可能返回此错误。同一告警枚举新增 below_floor，用于报告低于最低支持版本的网关。
  • 对于本版本之前曾将 background_model_check.ignore_statuses 显式设为空列表的模型，请将该字段重新设置为 [] 后保存。旧版本实际存储的是默认值 [408, 429]；仅升级不会修正该值，原样保存默认值也不会恢复空列表配置。

1.1.0​

发布日期： 2026 年 9 月 7 日

这个版本加固了控制面到网关之间的这条路径。网关现在只有在拿到可服务的配置之后才打开代理端口，能够自行从 etcd 中断、etcd Token 过期或 watch 始终未被确认中恢复，并且可以加载此前会超出内部消息大小上限的配置集。A2A Agent 补齐了调用方请求头转发契约；On-Premises 控制面 Chart 支持固定 NodePort，也不再等待一个已经被告知不使用的内置数据库。

行为变化​

  • 网关只有在应用过一次配置之后，才绑定代理监听器。 在 etcd 模式下，冷启动的实例会保持代理端口关闭，直到第一次配置读取成功；此前它会立即接受连接，并因为还不知道任何 API Key 而对每个请求返回 401 invalid_api_key。把"端口可连接"当作"该实例已就绪"的编排系统，不会再把流量路由到一个无内容可服务的实例上。这没有配置开关，也无法关闭；启动顺序现在就是如此。这段等待只会发生在从未应用过配置的实例上。文件模式会立即通过这道闸门；重启后发现磁盘快照缓存的实例同样如此——它会恢复快照并在远不到一秒内完成绑定，即使此时配置源不可达，因此已经运行过的 Pod 在控制面故障期间也能直接恢复服务。只有没有快照缓存的首次启动会等待，而在控制面可达时，这段等待在真实配置规模下是数十毫秒量级。由于 /livez 和 /readyz 由代理监听器提供，在这个窗口内针对它们的探针会收到连接被拒绝而不是响应；指标监听器上的 /status/ready 和 /status/config 全程可用。使用 Helm 的用户请在升级镜像的同时采用 1.1.0 Chart：Chart 的启动预算已经相应放宽。

  • etcd.dial_timeout_ms 和 etcd.request_timeout_ms 现在开始生效。 此前的版本会解析这两个键，但没有任何代码读取它们，所以无论配置文件里写了什么，每个部署实际上都没有 etcd 超时。两个键都是可选的，不设置即表示无上限，不存在隐式的 5000。request_timeout_ms 约束每一次单请求单响应的 etcd 调用——启动时以及每次 watch 重连时的配置范围读取、创建 watch，以及 Admin API 的读取——不会约束已建立的 watch 流。dial_timeout_ms 约束整个拨号过程，包括 TLS 握手和认证交换。从上一版本自带示例复制而来的配置文件已经带着这两个键的 5000 取值，升级前请先检查，详见升级说明。

  • 配置了 etcd 凭据的网关，在 etcd 启动时不可达的情况下不再退出。 此前设置 etcd.user 和 etcd.password_env 会让不可达的 etcd 成为致命错误：进程会在大约 20 到 25 秒后退出，此时还没有任何重试或监听器。这样的实例现在与未认证的实例行为一致——它会启动、保持代理监听器关闭、按已有的退避策略重试，并在配置到达后立即绑定。etcd 主动拒绝的凭据——用户名或密码错误、用户缺少所需权限，或者向未开启认证的集群发送了凭据——仍然是致命错误，并且现在会在 etcd 的第一次应答上就中止启动，而不是走完一整轮固定的重试阶梯。此前依赖进程退出来判断"etcd 挂了"的做法，应改为读取 /status/ready。

新功能​

  • A2A Agent 可以把入站的调用方请求头转发到上游。 A2A Agent 新增 forward_client_headers 列表，用于点名网关转发给该 Agent 的调用方请求头，写法是最多含一个 * 的 glob 模式，匹配不区分大小写。它作用于 /a2a/<name> 上提供的每一个 JSON-RPC 方法——message/send、message/stream 以及所有任务操作——也作用于 /a2a/<name>/.well-known/agent-card.json 上的 Agent Card 获取。至此，这份转发契约在四个代理面上全部补齐：模型服务提供方凭证、透传路由、MCP Server 和 A2A Agent。默认为空且不转发任何内容，因此现有 Agent 的行为不会改变。

    点名该 Agent auth_type 所填充的凭据槽位——bearer 对应 authorization，api_key 对应 x-api-key——会把调用方自己的凭据替换网关的凭据交给 Agent，而不是同时给出两份；这让原本就按最终用户身份做鉴权的内部 Agent 可以继续这样做。凭据槽位以及 traceparent 和 tracestate 只有在模式精确写出名称时才会转发，* 或 x-* 这类宽泛 glob 永远不会把它们扫进来。转发后会破坏这次交互的请求头，无论模式多宽泛都会被拒绝：host、逐跳请求头、x-aisix-* 命名空间、描述由网关重新序列化的请求体的那些请求头，以及 a2a-version——后者是网关自己对 protocol_version 所固定版本的声明。

    转发 cookie 之前有一个限制值得了解。网关会终结入站的 HTTP/2，并且不做 cookie 重组，因此如果 HTTP/2 调用方的客户端把 cookie 拆成多个请求头字段（这是 HPACK 的一种压缩手段，并非每个客户端都会这么做），只有其中第一个会被转发。A2A Agent、MCP Server 和模型服务提供方凭证都是如此；透传路由则会转发每一个取值。

    该配置可以在控制台的 A2A Agent 创建与编辑表单的"高级"区域中设置，也可以通过 Admin API 设置。如果在保存非空列表时，作用范围内仍有网关运行着不支持该字段的版本，保存会返回一条兼容性告警；这些网关在升级前不会转发任何内容，方向上是失败即拒绝。

改进​

  • 网关可以加载大于 4 MiB 的配置集。 网关会在单次 etcd 范围响应中读取自己的整个前缀，而 4 MiB 的 gRPC 解码上限意味着规模超过该值的环境永远无法加载——触及这条上限的是环境中资源的数量，而不是某个资源本身很大。它也不会自愈：运行中的实例会静默地不再看到配置变更，重启或新调度的实例则根本不会应用任何配置。配置读取路径和 Admin 读取面上的这条上限都已解除。低于旧上限的部署不受影响。

  • 控制面不再限制它写往网关的单个资源的大小。 控制面自身写入路径上的两条消息大小上限——outbox 客户端 2 MiB 的发送上限和内嵌存储 4 MiB 的接收上限——会让某个过大的投影资源在每一轮轮询中都被拒绝，且永远如此。由于按键隔离，队列中其余部分仍在正常排空，所以外部看到的现象是：某一个资源的配置始终没有到达网关，而保存它的人得不到任何提示。这两条上限都不是为这条路径选择的，现已移除。触及其中任何一条都需要异常大的投影值，例如一个授权了数千个模型的 API Key。

  • 等待配置源的网关现在会明确说明。 在第一次配置读取尚未完成期间，网关会在等待开始时记录日志，并每十秒重复一条告警。此前，一个能接受 TCP 连接却不作应答的端点，会让进程既没有端口、也没有任何日志。

  • On-Premises 控制面 Chart 支持为 API 和控制台服务指定固定 NodePort。 api.service.nodePort 和 ui.service.nodePort 加入了已有的 dpm.service.nodePort，各自只在对应 Service 类型为 NodePort 且已设置取值时才渲染；两者默认都为空，因此没有设置它们的安装保持动态分配。这让运维方可以在安装前就把 api.publicBaseURL 设为一个已知的地址。通过 NodePort 访问 API 和控制台走的是明文 HTTP：控制台的 NodePort 并不是一个独立入口，而是一个同源代理的上游，该代理会把 /api/* 路由到 API；除非部署在受信任的私有网络中，否则应由该代理终结 TLS。

修复​

  • etcd 认证 Token 过期或失效后，不再需要重启网关。 etcd 客户端只在连接建立时认证一次、之后不再认证，因此当 Token 在连接空闲期间到期（配置稳定的网关正处于这种状态），或因 etcd 认证存储发生变更而失效时，后续所有调用都会被拒绝，直到进程重启为止。网关现在会丢弃该连接、重新认证并把这次调用重试一次，配置读取路径和 Admin 读取面上都是如此。etcd 确实拒绝的凭据仍会按原样上报，不会被循环重试。

  • 网关在一次更新后不久被停止时，不再丢失最后一份配置快照。 快照缓存的写入此前是分离派发的，没有任何环节等待它完成，因此在应用变更后不久被停止的实例可能在写入尚未完成时就退出，重启后失去最后一份已知良好快照。现在关闭时会排空进行中的写入，上限为五秒。快照写入也按应用顺序提交：较旧修订版本的写入不会再覆盖较新的，因此在一连串更新之后重启的网关，不会回到一份它早已越过的快照上。优雅排空流程、排空窗口和 preStop 行为均保持不变。

  • 始终未被确认的配置 watch 现在能够被发现。 如果 etcd 能应答范围读取、却始终不确认 watch，网关会永远停留在自己的第一份快照上，对之后的每一次变更都视而不见，而 /status/config 仍然报告连接正常。设置了 request_timeout_ms 时，未被确认的 watch 创建会被中止，并按已有的退避策略重试。

  • MCP 访问控制的重投影现在覆盖每一条受影响的记录。 升级时刷新 MCP 访问控制的重投影，其分页方式可能跳过部分记录，让这些记录保留着已被淘汰的投影，兼容性告警也因此一直存在。现在它会显式遍历每一个 API Key 和每一条 MCP 策略。升级控制面时，每个现有 API Key 和每条 MCP 策略会多出一次投影写入。API、配置和资源形状都没有变化，也不需要运维方做任何操作。

  • 配置了外部数据库时，On-Premises 控制面 Chart 不再等待内置的 PostgreSQL。 设置 postgresql.builtin=false 会关闭内置的 PostgreSQL 服务，但 API 和数据面管理器仍会运行一个由 postgresql.image.* 构建的 PostgreSQL 就绪 init 容器，因此在私有网络中，即使外部数据库健康，拉不到 PostgreSQL 镜像也可能阻塞启动。该就绪 init 容器现在只在 postgresql.builtin=true 时渲染。内置部署不受影响，仍然是默认方式。使用外部数据库的运维方需要自行确保它在控制面启动前已经就绪。

API 变化​

OpenAPI 结构对比没有发现破坏性变化。所有新增内容都是可选的，且都集中在 A2A Agent 这一面。

端点变化
  • GET /a2a_agents
  • GET /a2a_agents/{a2a_agent_id}
A2A Agent 表示新增可选字段 forward_client_headers。
  • POST /a2a_agents
  • PATCH /a2a_agents/{a2a_agent_id}
接受可选的 forward_client_headers，取值是一个请求头名称 glob 模式数组；传 [] 会清除已有列表。条目按与其他转发面相同的规则校验——RFC 7230 token 语法、每个条目最多一个 *、最多 64 个条目——如果某个模式只可能点名这一面永远不会转发的请求头，则以 400 拒绝。只携带 forward_client_headers 的 PATCH 是一次有效更新。
  • POST /a2a_agents
  • PATCH /a2a_agents/{a2a_agent_id}
当该 Agent 所暴露环境中的网关运行着不会执行所保存 forward_client_headers 的版本时，保存成功的响应可能包含 warnings。告警形状沿用已有的 CompatibilityWarning；这是 A2A 保存首次可能携带它的版本。

有一处描述在形状不变的前提下收窄了。截至 1.0.0，A2A 的 auth_type 字段声明网关自身的凭据绝不会被转发给调用方、也不会向调用方暴露。这一保证现在只在 forward_client_headers 没有点名 auth_type 所填充的槽位时成立；一旦点名，Agent 收到的就是调用方的凭据而不是网关的。该字段的形状和枚举取值均未改变。

升级说明​

从任何早于 1.1.0 的版本升级时，本节说明都适用，包括那些途中越过 1.1.0 直接升到更新版本的升级。

  • 升级前请检查你的 etcd: 配置块。etcd.dial_timeout_ms 和 etcd.request_timeout_ms 在本版本中首次生效，而上一版本在 config.example.yaml 和 config.managed.yaml 中把这两个键都写成了生效的 5000。因此从其中任一文件复制而来的配置文件，会在配置范围读取上获得一个真实生效的 5 秒上限。如果某个部署的配置集无法在该上限内完成加载，这次读取会失败并重试；而由于网关现在只有在成功应用配置之后才绑定代理监听器，它将无法开始提供服务。除非你确实希望缓慢的 etcd 快速失败，否则请移除 request_timeout_ms；如果保留，请按你自己的配置集规模来设定取值，而不是沿用示例中原有的数字。dial_timeout_ms: 5000 没有可比的风险。现在两个键在自带示例中都处于未启用状态，不设置即表示无上限。
  • 如果你的控制面 Helm values 文件中已经写了 api.service.nodePort 或 ui.service.nodePort，升级前请检查它们。这两个键在本版本之前是被忽略的，现在会被渲染，因此升级 Chart 可能改变一个原本由 Kubernetes 动态分配的端口。想保持动态分配，请删除该键。

1.0.0​

发布日期： 2026 年 9 月 4 日

这个版本让安全护栏的行为在需要调优的地方变得可见、可配置。语义护栏会报告实际测得的相似度，控制台可以在规则挂到生产流量之前对已保存的规则做测试，失败后放行的决定也会在整个网关中得到一致记录。本次发布还为模型路由、MCP 服务器、透传路由和 Realtime 统一了调用方请求头转发契约，完善了不同模型服务提供方协议之间的推理控制，并让路由与配置失败更容易诊断。

行为变化​

  • 模型冷却现在需要显式开启。 直接模型没有 cooldown 配置块，或配置块中省略 enabled 时，请求失败后不再进入冷却。需要保留此前行为的，请设置 cooldown.enabled: true；开启后，默认超时时间与触发条件不变。此前依赖隐式冷却的现有模型会受到这一破坏性行为变化的影响。

  • 安全护栏不再把 Files API 当成一个不透明的整体扫描。 /v1/files 下的上传请求体、上传响应和文件下载现在不做输入或输出护栏评估。此前的整文件扫描既不能逐条评估 JSONL 记录，也无法把掩码后的内容写回 multipart 请求体，还会用替换字符解码二进制文件。/v1/batches 和 /v1/fine_tuning/jobs 的请求信封仍受护栏保护；本版本不包含逐条文件记录筛查。

  • 网关无法扫描的请求体现在遵循实际管辖该方向的护栏策略。 只有至少一条作用域内的护栏会读取这个方向、并且对它采用失败即拒绝时，网关才拒绝不可读内容。不会读取这个方向的护栏不会导致拒绝；所有相关护栏都采用失败后放行时，请求会继续，并记录 unscannable_body。fail_open 现在同样适用于 keyword 和 pii 护栏，而不只适用于远程护栏。已缓冲的流式输出在无法恢复出任何可扫描内容时仍然失败即拒绝，因为放行就意味着释放从未经过护栏评估的字节。

  • 无法解码的音频转写与翻译响应现在遵循输出失败策略。 输出护栏采用失败即拒绝时，这类纯文本转写返回 422 content_filter，错误码为 guardrail_unavailable；采用失败后放行时，原始字节会被转发，并记录这次绕过。能够解码的转写内容仍会接受扫描。

  • 不支持的流式请求会在到达模型服务提供方之前失败。 对 /v1/completions 或 /v1/images/generations 发送 stream: true 现在返回 400 invalid_request_error。这两个端点不转发流式响应；此前请求会被发往上游，可能在重试预算内重复产生可计费工作，最终返回与解码有关的 502。

  • 安全护栏现在按推理内容的提供者确定作用域。 调用方重放的推理内容属于输入，会在 Chat Completions、Responses 和 Anthropic Messages 上接受扫描；模型生成的推理内容不属于输出扫描范围。Anthropic 已签名的 thinking 块会接受拦截动作检查，但不会被掩码动作改写，因为客户端重放时必须保持这些已签名字节不变。

  • 流式错误事件现在采用各端点的原生信封。 /v1/messages 流中的护栏错误使用 Anthropic 的 invalid_request_error 类型；/v1/responses 发出扁平的 Responses API 错误事件，code、message、param 和 sequence_number 位于顶层。HTTP 错误信封不变。

  • 新发布的镜像只使用不可变的完整版本标签。 稳定版本发布 :X.Y.Z、:latest 和 :sha-*；候选版本发布完整 RC 标签与 SHA 标签。此后不再创建新的 :X.Y 和 :X 缩写标签。注册表中已经存在的缩写标签会保留，但本版本及后续版本都不会再推进它们。

新功能​

  • 语义护栏在部署前后都可以测量。 编辑表单新增试运行面板，可以为探测文本生成向量嵌入，并展示拒绝或允许分数、配置阈值、最接近的样例以及最终判定。经过语义护栏评估的请求会在用量事件中新增 guardrail_scores，通过的请求也会记录。日志会显示分数、阈值、方向、最接近样例的索引和向量嵌入模型；用量 API 与 CSV 导出携带同一份记录。持久化用量数据只保存样例索引，不保存样例或被筛查的文本。

  • 调用方请求头转发现在覆盖模型服务提供方凭证、MCP Server、透传路由和 Realtime。 MCP Server 与透传路由新增 forward_client_headers；模型服务提供方凭证已有的配置现在也作用于 Realtime 和所有经过协议翻译的模型服务提供方路径。在 MCP 与标准模型端点上，它是一份允许列表；在透传路由上，它恢复一条原本会被路由剥离的请求头。由于该字段可能传递调用方凭据与链路上下文，包括 AWS SigV4 请求身份头在内的凭据槽位，以及 traceparent / tracestate，都必须精确写出名称，不能由 glob 选中。被精确转发的凭据会替换网关或 default_headers 原本放入该槽位的凭据，不会追加第二个值。Amazon Bedrock 是例外：其签名器拥有 authorization 和 SigV4 请求头，签名前会丢弃调用方提供的这些值。

  • 直接模型可以为上游规范化推理力度。 新增的 effort_mapping 对象会在最终直接目标选定后，执行一次区分大小写的精确字符串映射。没有列出的值或缺失值原样透传；映射不会补充调用方没有提供的值，映射结果也不会再次进入映射。它覆盖 Chat Completions、Responses、Anthropic Messages 与 Token 计数请求，包括原生及跨模型服务提供方路径、流式请求、Bedrock 两种调用方式，以及由路由、语义或 Ensemble 模型选出的直接目标。该配置只允许用于直接模型，并可在控制台编辑。

改进​

  • 语义护栏要求使用为其向量嵌入模型选定的阈值。 非空的 deny_examples 必须同时配置 deny_threshold，非空的 allow_examples 必须同时配置 allow_threshold；没有样例的方向不要求阈值。此前省略阈值的现有数据会填入 0.75，保持原有执行效果。控制台测试面板与每次请求的分数可用于测量并调整替代值。

  • 所有受保护的代理面都能看到失败后放行结果。 成功和失败的用量事件都会携带 guardrail_bypassed_reason，包括在任何单条护栏运行之前发生的绕过。aisix_guardrail_bypasses_total 指标新增 reason="unscannable_body"；aisix_guardrail_blocks_total 也会计入在某条可计时护栏运行前发生的失败即拒绝。A2A、原本不产生用量的 rerank，以及不支持能力的路径，会在需要保留护栏归因时发出零 Token 用量事件。

  • 护栏配置失败现在会作为配置状态上报。 能反序列化、但运行时无法构建的记录会出现在 /status/config、拒绝指标和托管心跳状态中，修复后自动消失。PII、Presidio、关键词和语义护栏配置中，原本可能导致整条护栏被丢弃的 JSON null 现在会被拒绝。升级迁移只会用安全默认值修复已存储的 null 与缺失值，再校验完整投影记录；其他格式错误的记录保持不变。

  • 缓冲式输出护栏覆盖完整 SSE 帧。 Messages 与 Responses 路径现在可以处理 CRLF 分帧、多行 data: 载荷、缺失的最终终止符，以及流式请求返回的非 SSE JSON 响应。无法在保持结构的前提下掩码的内容会被移除或拒绝，而不会未经读取就释放；可以掩码的多行帧会保留完整载荷。

  • 推理控制可以跨协议翻译。 Anthropic 的 output_config.effort 和自适应／禁用 thinking 会映射到相应的 OpenAI reasoning_effort；OpenAI 的 effort 值会映射到 Anthropic 当前使用的 output_config.effort 形式。Anthropic 的结构化输出声明也会转换成带严格 JSON schema 的 OpenAI response_format，而不再被丢弃。

  • 路由和指标会展示网关实际完成的更多工作。 因冷却或后台健康检查而被移除的路由目标会产生一条限频告警，写明目标与原因；失败尝试告警在 Chat Completions、Messages、Token 计数和 Responses 之间保持一致。原生与翻译后的 Responses 流现在都会报告两组 TTFT 指标；Ensemble 请求在配额、用量事件和 Token 指标中使用同一份用量估算。

  • 控制台会保留资源引用，不再要求运营方重新输入。 已有资源字段使用可搜索选择器；允许合法新值的字段继续提供可编辑建议；过期引用仍然可见，不会因一次无关编辑而被静默清空。在日志中，手工输入的请求模型筛选仍然是大小写不敏感的子串搜索；从已知模型中选择则会在数据流与 CSV 导出中执行大小写敏感的精确匹配。

修复​

  • Rerank 与 Realtime 的响应模型名保持一致。 Jina 形状的 /v1/rerank 响应以及 Realtime 的 session.created / session.updated 事件现在报告调用方寻址的网关模型名，而不是模型服务提供方的模型 ID。把完整 Realtime session 对象发回 session.update 时，模型名会再次转换为上游 ID，同时不会改动单独配置的转写模型。

  • 模型服务提供方不支持的能力不再消耗重试预算。 缺失的 completions、embeddings 或图像生成能力会被明确分类，并直接返回已有的 501，不再重试一次不会随尝试变化的 adapter 能力。

  • 通配符模型引用会在失效或扩大访问范围之前得到校验。 当模型被精确名称引用，或重命名会把 API Key 的单模型授权静默扩成命名空间授权时，不允许把该模型重命名成通配符别名。语义护栏不能新选择通配符别名作为 embedding 模型。缓存策略可以选择由通配符别名服务的具体模型名，但不能选择通配符模式本身。已有引用只在其值发生变化时重新校验。

API 变化​

OpenAPI 结构对比没有发现破坏性的形状变化。不过，下列若干校验变化属于语义上的破坏性变化：此前会被接受的请求现在可能返回 400。调用方需要同时检查这些变化和新增字段。

端点变化
  • GET /environments/{env_id}/models
  • GET /environments/{env_id}/models/{model_id}
模型表示新增可选字段 effort_mapping，并注明 cooldown.enabled 默认为 false。
  • POST /environments/{env_id}/models
  • PATCH /environments/{env_id}/models/{model_id}
直接模型接受可选的 effort_mapping，配置后成功响应会返回它；更新时传 null 或 {} 会清除它，非直接模型会拒绝该字段。省略 cooldown 配置块或 enabled 表示关闭冷却。当精确名称引用或 API Key 授权会被破坏时，PATCH 拒绝把模型重命名成通配符别名。
  • POST /environments/{env_id}/guardrails
  • PATCH /environments/{env_id}/guardrails/{guardrail_id}
语义样例列表要求配套阈值；语义向量嵌入模型不能新引用通配符别名；受影响的语义、PII、Presidio 和关键词配置字段拒绝 JSON null。PATCH 完整替换 config 时，必须包含其样例列表要求的每个阈值。
  • POST /environments/{env_id}/cache_policies
  • PATCH /environments/{env_id}/cache_policies/{cache_policy_id}
model:<name> 选择器可以写由通配符别名服务的具体地址，但选择器本身不能是通配符模式。已有值只在发生变更时重新校验。
  • POST /provider_keys
  • PATCH /provider_keys/{provider_key_id}
已有的 request.forward_client_headers 与 request.default_headers 校验现在接受凭据槽位、拒绝会破坏传输的请求头和 x-aisix-* 名称，并应用上文所述的精确匹配与冲突规则。部分此前被接受但不生效的请求头条目，必须先删除才能再次保存完整请求覆盖配置。
  • GET /environments/{env_id}/passthrough_routes
  • POST /environments/{env_id}/passthrough_routes
  • GET /environments/{env_id}/passthrough_routes/{passthrough_route_id}
  • PATCH /environments/{env_id}/passthrough_routes/{passthrough_route_id}
请求与响应新增可选字段 forward_client_headers；更新时传 null 会清除它。
  • GET /mcp_servers
  • POST /mcp_servers
  • GET /mcp_servers/{mcp_server_id}
  • PATCH /mcp_servers/{mcp_server_id}
  • POST /mcp_server_submissions
  • PATCH /mcp_server_submissions/{mcp_server_id}
请求与响应新增可选字段 forward_client_headers。POST /mcp_servers/{mcp_server_id}/approve 与 /reject 返回的 MCP Server 表示中也包含该字段。
  • GET /environments/{env_id}/usage_events
新增可选布尔查询参数 requested_model_exact；响应项可能包含 guardrail_scores。
  • GET /environments/{env_id}/usage_events/export
新增可选布尔查询参数 requested_model_exact；导出项新增 guardrail_scores。

升级说明​

从任何早于 1.0.0 的版本升级时，本节说明都适用，包括那些途中越过 1.0.0 直接升到更新版本的升级。

  • 冷却改为显式开启属于破坏性行为变化。升级前，请为每个需要保留 1.0.0 之前隐式冷却行为的直接模型设置 cooldown.enabled: true。
  • 本版本中 /v1/files 不在安全护栏覆盖范围内。不要依赖上传或下载的整文件关键词、PII 或远程护栏判定。
  • 检查每条护栏的 hook 与失败策略。AISIX 无法扫描、且由相关失败即拒绝护栏管辖的请求体仍会被拒绝；没有相关失败即拒绝护栏时则可能继续。特别是 fail_open: true 现在会对 keyword 和 pii 护栏生效，可能新放行 AISIX 无法扫描的请求或响应。
  • 客户端重放的推理内容现在可能被输入护栏拦截。模型生成的推理内容不再由输出护栏评估，掩码动作也不会改写 Anthropic 已签名的 thinking 块。
  • 当音频转写或翻译响应字节无法解码、且输出护栏采用失败即拒绝时，客户端需要处理 422 content_filter。采用失败后放行时，原始字节现在可能在未经内容评估的情况下被转发。
  • 对 /v1/completions 或 /v1/images/generations 发送 stream: true 现在不会联系模型服务提供方，而是返回 400 invalid_request_error，不再最终返回与解码有关的 502。请更新状态码处理和重试策略。
  • 请更新自定义流解析器以适配原生护栏错误信封：Messages 流使用 Anthropic 的 invalid_request_error，Responses 流把 code、message、param 和 sequence_number 放在顶层。
  • 升级前检查包含 JSON null 的已有护栏。上一版本跳过、且能够安全修复的记录在迁移后可能开始执行；只缺少语义阈值的记录会保持已有的 0.75 行为。
  • 创建或完整替换语义护栏配置的 API 客户端，必须为每个非空样例列表提供对应阈值。即使 OpenAPI 形状没有结构性破坏，阈值与 null 校验仍属于 Cloud Admin API 的语义破坏性变化。
  • 检查重命名模型或写入模型引用的自动化。当精确引用会被破坏或 API Key 授权会扩大时，不允许把模型重命名成通配符别名；语义护栏不能新使用通配符别名作为向量嵌入模型；缓存策略可以写由别名服务的具体模型，但不能写通配符模式本身。
  • 检查 Realtime 使用的模型服务提供方凭证 forward_client_headers 模式：1.0.0 开始在该代理面上执行这份配置。凭据槽位与 traceparent / tracestate 必须精确写名，宽泛 glob 不会选中它们。再次保存完整覆盖配置前，请删除被拒绝的传输头、x-stainless-*、anthropic-version 或 x-aisix-* 条目。在 Bedrock 兼容端点上，转发的调用方值现在会在 x-api-key、api-key、x-goog-api-key、proxy-authorization 和 cookie 槽位中覆盖 default_headers。Bedrock 签名器仍然拥有 authorization 与 AWS SigV4 请求头，并丢弃调用方提供的值。
  • 原本期望新发布的 :X.Y 或 :X 镜像别名继续推进的自动化，需要改用完整版本或 :latest。
  • 如果告警基于 aisix_guardrail_bypasses_total，请考虑新增的 reason="unscannable_body" 序列，以及现在被纳入总数的其他事件。

0.13.0​

发布日期： 2026 年 9 月 1 日

这个版本围绕两件事：把流量区分开，以及按上游自己的方式访问它。模型服务提供方凭证现在可以声明该端点原生提供哪些 API 面、每一个面在哪个地址上，因此一份凭证就能同时访问一个上游的 OpenAI 兼容路径和 Anthropic 兼容路径，不必再建第二份凭证和第二个模型。每条用量记录现在都写明了这次请求要网关做的是什么，图像生成和视频提交在导出器和日志里不再和文本对话混成同一股 OpenAI 流量。被网关限流的调用方，也终于能从响应里读到上限是多少、什么时候可以再来。此外，凡是会返回模型名的端点，响应里现在报的都是调用方寻址时用的网关模型名，而不再是其中一部分端点报服务提供方自己的 ID。

行为变化​

  • 升级后，现有的 DeepSeek 模型服务提供方凭证会直达 DeepSeek 自己的路由，而不再被翻译。 AISIX 现在内置了一份经过实测的声明，写明 DeepSeek 原生提供 /v1/responses 和 Anthropic 兼容的 /anthropic/v1/messages，并在升级时一次性应用到符合条件的凭证上：自身没有任何声明、使用 deepseek 提供方、且 api_base 仍指向 https://api.deepseek.com。这些凭证的 apis_source 会标记为 catalog。对流量的影响是：Responses API 请求会被转发到 DeepSeek 自己的 /v1/responses 而不再翻译成 chat completions，推理输出项因此得以保留；Anthropic 协议的请求会走到 Anthropic 兼容路径，提示缓存断点和思考块因此得以保留。你自己声明过的凭证不会被改动。
  • 客户端从响应里读到的 model 字段，现在是它请求时用的网关模型名。 涉及 /v1/messages、/v1/responses、/v1/completions、/v1/embeddings（流式与非流式同样适用）以及 /v1/videos 的轮询。这几条路径此前返回的是服务提供方自己的模型 ID——一个别名为 gpt4o-mini 的模型会回来 gpt-4o-mini-2024-07-18，而 /v1/chat/completions 早就返回别名了。透传路由不受影响，仍然原样转发服务提供方的响应。
  • 网关自己产生的限流拒绝现在带响应头。 网关拒绝一个请求时，429 会描述拒绝它的那一条上限：x-ratelimit-limit、x-ratelimit-remaining、x-ratelimit-reset、x-ratelimit-scope 和 Retry-After。x-ratelimit-reset 与 Retry-After 都是以秒为单位的相对值。并发维度的拒绝此前完全没有重试提示，现在也有了。这些响应头只在网关自己拒绝时添加；上游返回的 429 仍按上游原样透传。成功响应上原有的 x-ratelimit-limit-requests / -tokens / -concurrent 这组按维度命名的响应头保持不变。
  • 键已经消失的 Prometheus gauge 不再继续上报最后一个值。 aisix_budget_limit_usd / _spent_usd / _remaining_usd / _reset_seconds / _details_present 以及 aisix_ratelimit_remaining_{requests,tokens} 只在请求路径上被写入，因此删掉一个 API Key 会把它的时间序列冻结在最后读到的值上——一条针对预算耗尽的告警，会为一个已经不存在的凭证持续触发。这类序列现在会退休为 NaN，Prometheus 将其视为"没有值"而不是零。比较这些 gauge 的告警不会再匹配到已删除的 Key。如果你的仪表盘面板直接读原始值，Key 删除之后看到的会是一段空缺，而不是一条水平线。

新功能​

  • 模型服务提供方凭证可以声明原生 API 面。 同一个上游账号常常在同一个主机的不同路径上提供多种协议，共用一份凭证——DeepSeek、智谱和 Kimi 都同时提供 OpenAI 兼容路径和 Anthropic 兼容路径。api_base 只能指出其中一个，于是其余请求一律被翻译，丢掉目标协议携带而标准 chat 形状没有的东西。凭证现在支持一个 apis 块，写明每个面以及它所在的 base URL：

    {
      "apis": {
        "responses": {},
        "messages": { "base": "https://api.deepseek.com/anthropic" }
      }
    }

    两个面的判定规则不同，因为它们各自的依据不同。messages 是附加的：adapter 本来就是 anthropic 的凭证，无论这个块怎么写都继续原生提供 /v1/messages，在这里列出它是为了给 adapter 是别的值的凭证补上这条路由。responses 是权威的：一旦这个块存在，/v1/responses 只有被列出才会原生提供——运营方正是用"不列出"来表达"这个端点没有 Responses 路由"，从而让请求被翻译成 chat completions，而不是打到上游收一个 404。完全没有这个块时，两者都回退到此前的推断方式：/v1/messages 依据提供方 ID 或 anthropic adapter，/v1/responses 仅依据提供方 ID。这个块没有涉及的面——embeddings、音频、图像、视频、files、batches、微调、rerank——一律照旧使用 api_base。把它设为 {} 表示该端点除自身 adapter 的面之外不提供任何其他面，设为 null 则清除声明。可在控制台的 Provider Keys 页面配置，也可通过 Cloud Admin API 的 POST 与 PATCH /provider_keys 配置。

  • 用量记录写明了请求要网关做的是什么。 每条用量记录现在都带 operation 字段，取值由请求命中的路由决定、绝不取自调用方文本：chat、completions、messages、count_tokens、responses、embeddings、rerank、realtime、image_generation、image_edit、transcription、translation、speech、video_generation、files、batches、batch_completion、fine_tuning、mcp、a2a、passthrough。inbound_protocol 对每一条 OpenAI 形状的路由都报同一个 openai，因此此前要区分文本对话、图像生成和视频提交，只能对捕获到的 prompt 做正则——而 metadata_only 的导出器根本没有 prompt，零 Token 的视频提交更是无从判断。这个字段会进入你自己的导出器（OTLP、Datadog、SLS），也会进入控制台：Logs 页可以按它筛选，并为每个请求标注——对话类端点（chat、messages、responses、completions）作为常见情形不做标注；GET /usage_events 与 GET /usage_events/export 新增 operation 查询参数，返回的每一项也带这个字段。

改进​

  • 用量记录与预算指标现在写出成员名字，不只是 ID。 aisix_usage_events_emitted_total、aisix_usage_event_drops_total 和五个 aisix_budget_* gauge 现在都在 user_id 旁边带上 user_name，与 aisix_proxy_requests_total 及 aisix_llm_* 系列保持一致。一条用量记录告警或一块预算看板，不必再去 Prometheus 之外查表才能说出它讲的是谁。

修复​

  • aisix_budget_remaining_usd 现在真的会发出来了。 网关只有在控制面的预算决定里写明剩余金额时才能发出这个 gauge，而那份决定从来没带过它——所以指标参考文档里描述的这条时间序列，在 0.12.0 及更早的任何部署里都不存在，基于它做的看板面板或告警匹配不到任何东西。它现在会与 aisix_budget_limit_usd、aisix_budget_spent_usd 一同出现，标签相同、出现时机也相同。只需升级控制面即可，网关不用改、也不用配置。
  • 因来源被拒的登录错误提示不再误述服务端信任的来源，也不再指错要重启的组件。 它此前说服务端只信任它被配置的那一个地址；实际上它同时信任该地址的 localhost／127.0.0.1 对应形式，以及 AISIX_TRUSTED_ORIGINS 中列出的每一个来源，提示现在给出了后一种解法。它此前还让运营方去重启 cp-api，而拒绝这次登录的检查其实运行在控制台里。
  • Helm Chart 的安装后提示不再给出一个它让你执行的 port-forward 并不服务的地址，那段提示里同样存在的、关于可信来源的不准确说法也一并修正。

API 变化​

没有破坏性变化，全部新增项都是可选的。

路由变化
  • POST /provider_keys
新增可选请求属性 apis。当作用范围内有数据面运行的网关版本过旧、无法执行所声明的某个面时，201 响应会带上 warnings
  • PATCH /provider_keys/{provider_key_id}
新增可选请求属性 apis；null 清除声明，{} 表示该端点除自身 adapter 的面之外不提供任何其他面。响应新增 apis、apis_source 和 warnings
  • GET /provider_keys/{provider_key_id}
响应新增 apis、apis_source（catalog 或 operator）和 warnings
  • GET /environments/{env_id}/usage_events
新增可选查询参数 operation；每一项新增 operation 字段
  • GET /environments/{env_id}/usage_events/export
新增可选查询参数 operation；导出的每一项新增 operation 字段

注意 apis 不会在创建响应中回显，与 api_base 一致——用 GET /provider_keys/{provider_key_id} 读回，其中的 apis_source 会说明这份声明是 AISIX 提供的还是你自己写的。

升级说明​

从任何早于 0.13.0 的版本升级时，本节说明都适用，包括那些途中越过 0.13.0 直接升到更新版本的升级。

  • 控制面会在升级后的第一次启动时，一次性把内置的 API 面声明应用到「行为变化」中描述的那些凭证上。这个动作是尽力而为且幂等的：某次启动没能完成，下一次启动会重试；已经带有声明的凭证永远不会被改动。如果某个端点你不希望被原生访问，自己给它写上 apis。
  • 如果你对 aisix_budget_* 或 aisix_ratelimit_remaining_* 配了告警，升级前请对照上面的 gauge 退休变化检查一遍表达式。
  • 仍运行 0.13.0 之前版本的网关不会记录 operation，因为这个取值是由网关根据匹配到的路由推导的。只要机群中还有这样的网关，按 operation 过滤——无论是在 Logs 中、在 GET /usage_events 上，还是在导出中——都会把它的流量排除在结果之外。这些请求照常被代理和记录，只是 operation 过滤看不到它们。升级该网关后，此后的流量即可正常过滤；已经记录下来、没有 operation 的行仍然在过滤范围之外。

0.12.0​

发布日期： 2026 年 8 月 30 日

这个版本让两份契约开始名副其实。Cloud Admin API 现在覆盖控制台能做的全部操作，每个版本发布一份不可变的文档，并且对它所声明的内容做校验。安全护栏则只在你挂载它的地方生效——"没有挂载就等于处处生效"这条规则，已经从网关、控制台和升级回填三处一并移除，而现有护栏实际拦截的范围不受影响。除此之外，Token 计数改为按调用方自己的协议上报，Gemini 模型的思考 Token 终于被计入，用量记录会指出凭证背后的那个人，还有几处删除操作可能留下悬空引用的路径被堵上了。

行为变化​

  • 安全护栏的作用域现在就是它的挂载关系；没有任何挂载的护栏不筛查任何流量。 此前一条没有挂载记录的护栏会以最低优先级作用于整个环境。以"没有记录"作为判据正是危险所在，因为收窄作用域恰恰是通过删除环境级挂载来表达的：一条只作用于某个模型的护栏，会在该模型被删除的那一刻，悄无声息地扩大到环境里的每一个请求。升级不会改变你现有护栏实际拦截的范围——控制面会在升级过程中，把原来隐含的环境级作用域写成一条显式的环境级挂载，且发生在网关不再认可隐含作用域之前；同时它还会把此前某次启动错误放大到环境级的护栏，恢复成你配置的窄作用域。从此之后有变化的是：新建的护栏在你挂载之前不作用于任何流量。声明一条没有挂载的护栏仍然不算错误：它的作用对象可能只是被删掉了。控制台中这类护栏现在显示为 Not attached——"没有挂载到任何对象，因此不筛查任何流量"，此前显示的是 Global／"作用于所有模型"；网关也会为每条已启用但没有挂载的护栏打一条 WARN。与此相关：在控制台打开一条窄作用域护栏、只改了个无关的地方就点 Save，不会再写出一条环境级挂载——编辑器现在把"没有挂载"表示成一个独立状态，而不是默认回退到环境级。
  • 控制台一直在调用的二十一条控制面路由现在进入了 Admin API 契约，并且会对请求做校验。 这些路由此前用 Admin Token 就能访问，只是没有公开的 schema；现在它们出现在 API 参考中。把一条在线路由纳入契约同时也为它打开了请求校验，因此请求体中携带了 schema 未声明的字段时会返回 400，而不再是被接受后忽略——POST /teams 带一个多余字段，在上个版本返回 201，现在返回 400 additional properties not allowed。如果你有程序在调用用量数据流、用量导出、用量汇总或请求级指标、团队与团队成员、模型价格覆盖、邀请、成员移除或通知投递日志，请确认它只发送已文档化的字段。完整路由清单见「API 变化」。
  • 响应中的 Token 计数现在按调用方自己的协议口径上报。 两种协议只在一件事上有分歧：提示缓存的计数是包含在输入计数之内，还是与之并列。OpenAI 协议下 prompt_tokens 是包含缓存命中在内的完整输入；Anthropic 协议下输入计数不含缓存，cache_creation_input_tokens / cache_read_input_tokens 与之并列。网关此前会把上游报什么形状就原样透传，因此当客户端用的协议与上游的协议不一致时，它拿到的是另一种口径的账：用 OpenAI 协议访问 Anthropic 上游的客户端会看到 prompt_tokens: 40 与 total_tokens: 2104 并存——既对不上账，缓存命中也无处体现。同一个请求现在上报 2088 与 2104，命中部分出现在 prompt_tokens_details.cached_tokens 中。在发生口径转换的情况下，total_tokens 会由投影后的输入与输出计数重新算出，而不是照抄一个按另一种口径算出来的总数；不需要转换时，仍然原样透传上游给出的总数。流式、非流式与 /v1/responses 均已覆盖。记录下来的用量事件不变，因此计费与历史费用不受影响——变的只是回给调用方的计数。
  • OpenAI 协议的响应现在可能带上缓存写入计数。 prompt_tokens_details.cache_creation_tokens（/v1/responses 上是 input_tokens_details 下的同名字段）表示本轮被上游写入缓存的 prompt Token 数。它不是 OpenAI 的字段——OpenAI 没有"缓存写入"这个概念——但如果没有它，Anthropic 或 Bedrock 的一次缓存写入就表现为 prompt_tokens 无缘无故变大、调用方无法据此估价，而写入的单价是高于普通输入的。该字段仅在非零时发出，因此严格拒绝未知字段的客户端需要检查一下。
  • Gemini 模型的思考 Token 现在会被计入，并计费。 Gemini 会上报 thoughtsTokenCount，而网关此前在任何地方都没有解析它——因此思考模型的 completion_tokens 记录值少了思考部分，reasoning_tokens 在所有协议下都读作 0。现在两者都会被携带，reasoning_tokens 表示 completion_tokens 中的那一部分，是否包含则依据上游自己上报的总数来判定，因此在 Gemini 已经把思考计入自己的候选 Token 数的情况下不会被重复计算。费用按推理单价（未设置推理单价时按补全单价）对 reasoning_tokens 计费。如果你在使用会思考的 Gemini 模型，记录的补全 Token 数与费用会上升——上升到与 Google 本来就在向你收取、而网关此前没有记录的那部分一致。与上面那条协议转换不同，这一条确实会改变用量记录。
  • /v1/messages/count_tokens 现在会发出用量记录。 这个路由在任何结果下都不发用量事件，因此一个被入站护栏拒绝的请求，虽然被正确拒绝了，却无法在日志中找到——包括 Guardrail blocks 视图。它仍然不计费：无论是正常返回还是被拒绝，prompt_tokens 与 completion_tokens 都是零。"不计费"和"不记录"此前被当成了同一件事，其实是两件。
  • 会留下悬空引用的删除操作，现在会被拒绝、被修复，或者如实告知。 删除一个被语义护栏用作 embedding 模型的模型会返回 409，而重命名该模型会改写这条护栏，而不是把它变成孤儿。此前的代价很高，因为护栏默认失败即拒绝：在上个版本中这个删除会成功，而该护栏作用域内的每一个请求随后都会收到 422 semantic_embed_unresolved。删除一个被声明映射解析到的 API Key 同样返回 409，与 passthrough 路由的匿名 Key 已有的保护方式一致——悬空的映射虽然是失败即拒绝，但代价并非为零：匹配会取优先级最高的规则且不再向下回落，因此一条坏掉的规则会遮蔽一条本来仍然有效的低优先级规则。删除团队、移除成员现在都会清掉它们留在调用方 Key 上的归属，并把变更同步到网关。 这两列此前是被数据库外键置空的，而外键动作不产生投影事件，于是网关继续读着一份指向已不存在团队的文档——一条挂在被删团队上的限流会一直拦着那些 Key，而控制台上没有任何东西能解释那些 429。删除 MCP Server 也不再顺手删掉引用它的按 Key 限流：此前它会删掉限流却保留工具授权，于是"用同名重新创建"这条被支持的路径会恢复权限、却静默丢掉限流上限。删除 OIDC Provider 仍然会成功——它的两处引用持有的都是名称，重命名本身就是删除加重建，悬空是常态且失败即拒绝、可自愈——但响应现在会报告还有多少个 API Key 和声明映射仍在引用它。

新功能​

  • Cloud Admin API 按版本发布。 每个发布 tag 现在都会发布一份由该 tag 自身源码生成的、不可变的 OpenAPI 文档，API 参考会为每个已发布版本提供一个页面，并自动生成相邻版本之间的变更记录。你可以直接查阅自己这套部署所暴露的 API，并与要升级到的版本进行对比，而不必再去对照一份跟随开发分支变化的文档。
  • 用量记录与日志会归因到组织成员，而不只是凭证。 用量记录此前只写明请求是从哪个 API Key 进来的，却从不写明背后是谁，因此"查这个成员最近 24 小时的错误"意味着枚举他名下的每一个 Key 再手工合并结果——而一个既用 API Key 又用 OIDC 的成员，还会被拆成两个身份，没有任何一个筛选条件能把它们并起来。用量记录现在携带成员信息，日志页也可以按成员筛选。这个归因是在请求被处理时打的快照：重新绑定或删除一个 Key，不会改写它已经产生的历史记录。
  • 日志可以按精确的状态码筛选。 此前只提供按状态码族筛选，因此没有办法只查 429 而不把其他所有 4xx 一起带出来。现在支持精确状态码，也支持 500-599 这样的区间。
  • aisix_usage_events_emitted_total 与 aisix_usage_event_drops_total 带上了成员与精确状态码。 两个计数器都新增了 user_id 标签和一个保存原始响应码的 status 标签，因此"这个成员有多少请求被限流了"和"这个成员有没有丢过用量记录"现在可以直接从指标回答。原有的 status_code 族标签保持不变，基于它的告警不受影响——但如果某个仪表盘在聚合这两个计数器时没有显式写出标签，它会看到新增的维度。

改进​

  • 用量页面在加载过程中不再报零。 在第一个响应返回之前，/usage 会在两张写着"最近 30 天没有用量"的表格下面渲染出 $0.00、0 个请求和 0 个 Token，几秒之后再把它们全部替换成真实数字。在网络较慢时，运营方会被明确告知自己的网关没有任何流量。现在它显示 — 并配一行 Loading…，与概览页保持一致。
  • 离线安装脚本会报告所安装的版本，以及真正对外暴露的端口。 离线部署此前没有办法在安装结束时确认自己刚装的是哪个版本；而当端口来自环境变量而不是默认值时，结束时打印的横幅仍然显示默认端口——于是一套监听在某个端口上的部署，却告诉运营方去打开另一个端口。
  • 参考文档现在写明了自定义 PII 规则中替换文本的行为。 $1 不会被当作捕获组引用展开；而当正则里有捕获组时，只替换第 1 个捕获组而不是整个匹配——所以对 ACCT-([0-9]{4})-([0-9]{4}) 用 replacement: "ACCT-$1-****"，得到的是 ACCT-ACCT-$1-****-5678：看上去像脱敏了，其实原文还在里面。控制台现在会在替换文本里含 $ 时给出提示。

修复​

  • 两个控制面副本同时启动不会再互相搞崩。 Schema 迁移全程都是"先检查再动作"——先探查系统目录，再执行创建或修改——而 PostgreSQL 并不会为此串行化，因此高可用部署可能在启动时让某个 Pod 以多种不同的错误码失败。启动期的 schema 操作现在会串行执行；对着全新数据库同时启动八个副本，现在八个全部起来，此前这一档大约八次里会失败七次。
  • 升级回填不会再把只作用于某个模型的护栏重新放大。 那个为"挂载关系出现之前就已存在"的护栏补一条环境级挂载的回填任务，会在每一次控制面启动时运行，并且用"没有环境级挂载"来判定目标——这个判据是在挂载表刚建立、所有护栏都还没有任何挂载时写下的，那时它只可能意味着"早于挂载机制"。而自从把护栏收窄到某个模型会删除它的环境级挂载之后，每一次重启都会悄悄把它重新放大回整个环境。
  • 删除护栏现在会把它的挂载关系从网关撤回；升级还会清理掉此前删除留下的残留。 挂载记录此前是被数据库级联删除的，而级联不会产生投影事件，因此那些挂载文档会一直留在网关侧，每个数据面在每次重建索引时都会打一条"引用了不存在的护栏"的日志，且永不停止。升级会把这些残留撤回，那条日志会自行消失，无需人工处理。

API 变化​

本次共有二十一条路由进入契约。它们是新增文档，而不是新增接口——每一条此前用 Admin Token 就已经可以访问；变化的是它们现在有了公开的 schema，并且请求会被校验（见「行为变化」）。

路由变化
  • GET /environments/{env_id}/usage_events
新增文档
  • GET /environments/{env_id}/usage_events/export
新增文档
  • GET /environments/{env_id}/usage_metrics
新增文档
  • GET /environments/{env_id}/usage_summary
新增文档
  • GET /invitations
  • POST /invitations
  • DELETE /invitations/{invitation_id}
新增文档
  • DELETE /members/{user_id}
新增文档
  • GET /model_pricing
  • PUT /model_pricing
  • DELETE /model_pricing/{id}
新增文档
  • GET /notification_deliveries
新增文档
  • GET /teams
  • POST /teams
  • GET /teams/{team_id}
  • PATCH /teams/{team_id}
  • DELETE /teams/{team_id}
新增文档
  • GET /teams/{team_id}/members
  • POST /teams/{team_id}/members
  • PATCH /teams/{team_id}/members/{user_id}
  • DELETE /teams/{team_id}/members/{user_id}
新增文档
  • DELETE /environments/{env_id}/api_keys/{api_key_id}
新增 409——该 Key 被某条声明映射解析到
  • DELETE /environments/{env_id}/oidc_providers/{oidc_provider_id}
200 响应新增可选属性 warnings，报告仍在引用该 Provider 的 API Key 与声明映射数量
  • DELETE /environments/{env_id}/models/{model_id}
409 此前已文档化；现在它还覆盖"该模型被某条语义护栏用作 embedding 模型"这一情形

任何此前已文档化的路由，其请求或响应形状都没有破坏性变化。有四处容易猜错的语义现在被明确写了出来，值得对照检查你的集成：

  • usage_summary 统计的是去重后的请求数，而不是上游尝试次数——一个重试了三次的请求只计一次。
  • 离线部署下 ModelPricing.source 可以是 snapshot，而不只是联网部署会产生的那些取值。
  • 六个用量筛选条件是大小写不敏感的子串匹配；provider_label 和 request_id 是精确匹配。
  • 调用方 API Key 的归属取的是 GET /members 返回的成员关系 ID，而不是该成员的用户 ID——这一条是对旧参考文档说法的订正。传用户 ID 会被拒绝。

升级说明​

从任何早于 0.12.0 的版本升级时，本节说明都适用，包括那些途中越过 0.12.0 直接升到更新版本的升级。

  • 安全护栏无需任何操作。 这次作用域变更不会改变你现有护栏实际拦截的范围：升级会把原来隐含的环境级作用域写成一条显式的环境级挂载，并把此前某次启动错误放大到环境级的护栏恢复成你配置的窄作用域；它还会撤回此前删除操作遗留下来的挂载记录，因此网关那条"引用了不存在的护栏"的日志会自行停止。升级之后新建的护栏，则只作用于你为它挂载的对象。
  • 如果你直接调用控制面 API，请检查这二十一条新纳入契约的路由。 对它们的请求现在会按公开的 schema 校验，因此此前被接受并忽略的未文档化字段，现在会返回 400。
  • 会思考的 Gemini 模型上，记录的费用会上升。 它们的思考 Token 此前完全没有被计入，现在会出现在 completion_tokens 与 reasoning_tokens 中并参与计费。按此前偏低的数字标定的预算和费用告警需要重新评估。其他模型和服务商不受影响。
  • 检查聚合 aisix_usage_events_emitted_total 或 aisix_usage_event_drops_total 的仪表盘。 这两个计数器新增了 user_id 与 status 标签，会改变未显式指定标签的 sum by (...) 的基数。status_code 族标签保持不变。

0.11.0​

发布日期： 2026 年 8 月 28 日

这个版本的主题是安全护栏。筛查新增两种类型——一种按语义而非模式判断，另一种运行你自己写的脚本——同时整个子系统变得可追责：护栏拒绝一个请求时，现在会说清是你的策略命中了，还是这条规则根本没跑起来；每一次强制命中也都会进入日志和用量记录。与此同时，网关滚动更新时不再丢弃流量，Anthropic 协议上的提示缓存用量得到正确计费与度量，还有几处可能让运营方悄无声息丢失数据、或者执行了一次什么都没做的"升级"的路径被堵上了。

行为变化​

  • 入站安全护栏现在会在每一个到达模型服务提供方的请求上运行。 此前只有当请求携带网关已经提取出的文本时，护栏链才会被调用，因此不带文本的请求——没有参数的 MCP 工具调用、没有 prompt 的语音转写、没有 prompt 的图片编辑、对空字符串做 embedding——都会绕过筛查直达上游，而 /v1/messages/count_tokens 与 /a2a/:agent 则从未被筛查过。按路由变化的是提供给护栏链的文本，而不是护栏链是否被调用。如果你依赖某条护栏把守数据外发，那么在这个版本之前，它并没有覆盖上述路径。 另外，当挂有护栏时，Anthropic 解析器无法读懂的请求体现在会被拒绝，而不再转发给上游。
  • 护栏拒绝现在会记录在它所产生的用量事件上。 控制台日志页 Guardrail blocks 视图筛选所依据的那个标记，此前只有十四个可能拒绝请求的接口中的两个会设置，因此在调用方正被拒绝的同时，那个视图可能显示为空——读起来就像网关完全没有记录任何护栏活动。现在所有接口都会设置它。
  • 无法运行的护栏不再声称你的内容被拦截。 当一条筛查规则失败时——上游不可达、脚本返回了不是裁决的东西、超时——这次拒绝现在会如实上报：调用方收到 422，其中 "code": "guardrail_unavailable"，消息指出是哪条护栏以及失败原因（request rejected: guardrail 'x' could not evaluate it (...)），而不再是真正命中时才该出现的 request blocked by content policy。网关会打一条 WARN 日志，aisix_guardrail_latency_seconds 上的 error_type 也会标明原因。HTTP 状态码与 error.type 保持不变，因此基于它们的告警仍然会把两种情况都计入。这适用于所有类型的护栏、所有接口。aisix_guardrail_blocks_total 一如既往地把两者合并计数——它不带任何标签，因此无法区分二者，而且它只在 chat completions 这条路径上记录。要统计策略拦截，请使用 aisix_guardrail_latency_seconds_count{result="blocked", error_type="none"}； 同一序列上 error_type != "none" 的部分就是规则失败。不要只按 error_type 筛选——这个直方图记录的是每一次护栏执行，其中包含被放行的请求。
  • 安全护栏默认改为失败即拒绝（fail closed）。 两个平面上 fail_open 现在都默认为 false：无法连通其服务的规则会拒绝请求，而不是让它未经筛查地通过。需要保持旧行为的，在该护栏上设置 fail_open: true。脚本故障同样遵循这个默认值。
  • 超出服务商长度上限的内容改为分块，而不再截断。 超限的请求体此前会被截断后只筛查一部分，这在一个"本该看到全部内容"的控制上是个静默的漏洞。现在它会被分块并完整筛查——每一个分块都会被提交，且不设分块数量上限，因为一旦给分块数设预算，超出的部分就成了从后门溜走的未筛查内容。
  • mandatory 开关已移除。 它与 fail_open 表达的是同一件事。请从存量配置中删除；"不允许被绕过"的护栏就是 fail_open: false 的护栏。
  • 已移除的 /passthrough/* 隧道现在返回普通的 404。 0.10.0 用显式 passthrough 路由取代了隐式隧道，并保留了一个版本的 410 Gone 迁移指引。那个版本已经发布，因此未被任何路由认领的 /passthrough/* 路径现在走路由器的常规未命中路径，这个命名空间完全交由你用显式路由认领。随之移除的还有对应的 WARN 日志和 provider="unresolved" 指标序列。
  • /v1/messages 现在会上报 OpenAI 兼容上游的提示缓存命中。 当 OpenAI 兼容上游服务一个 Anthropic 协议请求时，命中缓存的前缀不再被计入 input_tokens：客户端收到的 input_tokens 是未缓存部分，cache_read_input_tokens 是命中部分；用量记录则不做这个转换，它沿用 OpenAI 的形状：prompt_tokens 仍是整个 prompt，cached_prompt_tokens 是其中命中缓存的那一部分，而不是需要再加上去的另一笔——正因如此，日志、用量 API、CSV 导出与计费才能把缓存部分按缓存读取的价格计费。流式响应在收尾的 message_delta 中上报。该计数器仅在非零时发出。此前整个 prompt 都按未缓存价格计费。
  • 十二个指标族新增 upstream_protocol 标签。 它标明实际服务该请求的协议——跨协议转换此前会让这一点不可见。聚合类查询不受影响；精确匹配标签的仪表盘、告警和记录规则需要更新。
  • 已停止的网关会显示为离线。 节点存活现在由控制面判定，而不再在浏览器里计算，DpNode 上新增 status 字段（healthy / warning / offline），依据心跳时间推导。已停止的实例不会再一直显示为健康直到刷新页面，数据面列表也会自行更新。
  • 环境没有 MCP 策略时，GET /environments/{env_id}/mcp_policy 返回 200 且策略为 null，不再返回 404。该接口的 404 现在只表示环境不存在。
  • 通知通道的 URL 不会再因为回写而被销毁。 读取响应会对 URL 打码，因为 webhook 的路径本身就是凭证。此前那个打码值会被当作写入值接受，因此任何"读取-修改-写回"都会静默地把真实 webhook 替换掉并返回 200。现在原样回显的打码值是空操作，指向不同主机的打码值会被拒绝，创建通道时使用打码 URL 也会被拒绝。投递错误不再回显远端响应体——它可能包含该 URL。

新功能​

  • 语义安全护栏。 筛查规则现在可以按语义而非模式判断：给出允许和拒绝的示例语句，它会用你指定的 embedding 模型为每条消息打分，两侧可分别设置阈值。它逐条筛查消息，可以只看用户消息，也可以看整段对话。
  • 自定义脚本安全护栏。 对于内置类型无法表达的策略，可以自己写检查逻辑：网关在沙箱中运行你的脚本，超时时间由你设置，密钥按名称注册而不是内联写入。钩子返回 {action: "none"}（或 "allow"）表示放行，{action: "block", reason, reason_code} 表示拒绝，{action: "mask", segments} 表示改写。这四个就是全部词汇——返回其他任何东西都属于脚本故障，并会被如实上报。
  • PII 规则可以只作用于捕获组，并指定替换内容。 自定义规则可以只脱敏匹配中真正敏感的那一部分，并指定替换用的字符串，而不是用固定的记号遮盖整个匹配。
  • 强制生效的护栏命中会进入日志和用量记录。 每个 LLM 接口现在都会记录是哪条护栏作用于该请求，因此被拦截或被脱敏的调用事后可以归因，而不再只表现为一次拒绝。日志页会区分策略拦截与失败即拒绝导致的中断。
  • validate 会报出能加载但跑不起来的护栏。 配置能解析、却构建不出规则的行——非法的正则表达式、无法识别的检测器或动作取值、编译不通过的 kind: custom 脚本——此前只会打一条 WARN 日志后被移出护栏链，它所描述的筛查就这样悄无声息地不存在了。现在这类问题会在校验时暴露，而不是等到第一个请求。该检查在进程内构建配置、不发起任何网络请求，因此它不会告诉你某个服务是否可达；它还会完全跳过 kind: semantic 的行，这类行所指定的 embedding 模型不在检查范围内。
  • 网关开始排空时会退役 HTTP/2 连接。 收到 SIGTERM 后，网关在排空窗口开启时向 HTTP/2 下游发送 GOAWAY，客户端因此会停止在该连接上发送并改连他处，而不是与关闭过程赛跑。HTTP/1.1 此前已经收到 Connection: close。正在排空的网关同时会对健康探针保持存活，因此编排系统不会在排空中途把它杀掉。
  • POST /v1/images/edits。 multipart 图片编辑现在是一个有类型的接口，与代理的其余部分共享同样的认证、安全护栏和用量计量。
  • 提示缓存 Token 计数器与指标上的 upstream_protocol。 缓存读取与缓存写入现在各有自己的 Prometheus 计数器，因此"输入中有多少来自缓存"可以直接从指标回答，而不必再去聚合用量导出。
  • 网关的 trace id 会随每个请求存储，并可通过 trace_ui_url_template 中的 {trace_id} 插值成追踪查看器的链接，因此一条日志可以直接跳到它对应的链路。

改进​

  • 现在可以在控制台里重命名环境、编辑 embedding 模型。
  • 所有列表底部都支持直接跳转到指定页码，而不再只能逐页翻。
  • 邀请现在是新用户真正可以接受的东西：链接会先展示所属组织再让人加入，加入是一个显式动作而不是打开页面的副作用，并且邀请与被邀请的邮箱绑定。
  • 护栏配置的"读取-修改-写回"可以正常往返。描述已存密钥的那些字段原样回显时会被接受、被篡改时会被拒绝，因此脚本和基础设施即代码不必再手工剔除它们。编辑 Bedrock 护栏也不再索要 API 从不返回的 AWS 密钥。
  • 数据卷已存在而 .env 缺失时，离线安装包会拒绝启动并说明将会丢失什么，而不是重新生成密钥然后陷入崩溃循环。
  • AISIX_CLOUD_NOTIFY_ALLOW_PRIVATE_URLS、AISIX_CLOUD_MCP_SPEC_ALLOW_PRIVATE_URLS、AISIX_CLOUD_ALLOW_FRESH_BOOTSTRAP 与 AISIX_CLOUD_PRICESYNC_URL 现在可以在离线安装包的 .env 中设置；此前它们写在文档里却无法生效。
  • 用量按 UTC 自然日分桶，不受会话所在时区影响；请求总数为精确值而非抽样；估算得出的用量会被标注为估算值。
  • 日常使用控制台不会再耗尽自身的认证额度。受限流的 Token 刷新现在显示为"稍后重试"，而不是"你已登出"——此前已登录的用户会被要求重新登录，另有几处流程也把一次失败的会话读取当成了会话丢失。
  • Overview、Logs、Budgets 与 Observability 页面在数据尚未加载完成时，不再渲染不完整或有误导性的数字。
  • 文档所述的 On-Premises 升级流程现在真的会更新版本。AISIX_VERSION 归安装包所有，每次启动时按包内容对齐；此前它固定在 .env 里，因此照着文档操作会让旧镜像继续运行，还报告成功。需要固定版本请改用镜像变量。降级会被拒绝，除非设置 AISIX_ALLOW_DOWNGRADE=1。
  • 控制面启动失败时会指出原因——数据库密码错误、主密钥错误、密钥 id 不匹配、缺少 CA 根——并同时读取 api 与 dpm 两侧的日志，而不再只留下一句"容器不健康"。

修复​

  • /v1/realtime 重新可以对接 OpenAI。 网关此前在每个 realtime 连接上都发送一个 beta 启用请求头；OpenAI 现已转正式版的接口会拒绝它并在客户端发出任何内容之前关闭会话。该请求头现在只在调用方主动要求时才转发，因此遗留客户端仍能得到 beta 形态，其他人则连到正式接口。
  • kind: custom 安全护栏现在可以在控制台里创建。 网关此前没有在能力清单里宣告这个类型，因此控制台把它显示为"不受支持"，尽管两个平面都能运行它。
  • 没有配置 api_base 的 OpenAI 模型服务提供方 Key，现在在所有路由上都会回落到厂商默认地址，而不只是部分路由。
  • 对模型服务提供方 Key 的空操作更新——把已存的内容原样发回——现在会成功，而不再返回内部错误。
  • 所有接受 multipart prompt 字段的接口都会拒绝非 UTF-8 内容。
  • 控制台编辑表单中，逐项设置的 PII 处理方式不会再丢失。
  • 在三层 MCP 规则之前写入的 API Key 配置行仍然可以正常加载。已退休的 mcp_access.mode 选择器按普通的未知字段忽略，因此整行不会加载失败，该 Key 的 mcp_access 块其余部分照常读取——一行被拒绝的 API Key 会失去对它全部流量的认证能力，而不只是 MCP 流量。
  • 从未接线的静态 OTLP 导出配置块不再打印虚假的成功日志。

升级说明​

  • 先升级控制面，再升级网关。 这是受支持的顺序。在这个窗口期内，仍停留在 0.10.0 的网关无法运行新增的护栏类型（semantic、custom）、PII 的 replacement 字段，以及新增的 text_source 取值：它无法解析这样的配置行，会把整行丢弃，因此该规则在那里什么也不筛查。控制面仍然会保存这样的配置——它不会拒绝——并在写入响应中返回一个 warnings 数组，指出是哪个字段、从哪个版本起才能读取它，以及你有多少个网关受影响。请务必查看这些警告： 在所有网关升级完成之前，这条规则在尚未升级的网关上并未生效。
  • 重新核对你的安全护栏此前究竟覆盖了什么。 这个版本中有两处修复改变了答案：入站护栏链现在会在此前被跳过的路径上运行，拒绝也会记录在每一个可能拒绝的接口上。如果某条护栏此前看起来一直很安静，那可能是覆盖缺口，而不是流量少。
  • 重新录入升级前已被破坏的通知通道 webhook URL。 如果你曾经通过 API 读取某个通道再把整个对象写回，那么真实的 webhook URL 已经被它的打码形式替换，并且无法找回——它只存在于服务商那边。升级后，处于这种状态的通道会在投递错误中报告出来；请从 Slack（或你使用的服务商）重新取得该 URL 并填回。只通过控制台编辑过的通道不受影响。
  • 更新精确匹配标签的指标查询。 十二个指标族新增了 upstream_protocol。
  • 把 aisix_guardrail_blocks_total 当作策略命中量的查询，同时也在统计规则失败。 这个计数器不带任何标签，从来就没有区分过两者，而且它只在 chat completions 这条路径上记录（aisix_guardrail_bypasses_total 同理）。由于 fail_open 现在默认为 false，服务不可达的护栏会拒绝请求而不是放行，因此此前会计入 bypasses 计数器的失败，现在改为计入 blocks 计数器。要统计整个网关范围内的策略拦截量，请使用 aisix_guardrail_latency_seconds_count{result="blocked", error_type="none"}。

0.10.0​

发布日期： 2026 年 8 月 20 日

这个版本的主题是 Agent 流量。正向代理流量——把 IDE 或编码 Agent 指向网关——现在由一个显式、可审计的路由资源承载，而不再是那条需要猜测"该借用哪个凭证"的隐式隧道。MCP 支持了协议的 2026-07-28 修订版、面向无凭证客户端的匿名访问、OAuth 2.1 发现，以及一条统一的工具授权规则。模型组新增一致性哈希与优先级层级。网关在关闭前会保持一个排空窗口继续接受连接，不再拒绝负载均衡器尚未停止转发的请求；通过 OTLP 导出的链路追踪也形成了真正的层级结构。

行为变化​

  • 隐式的 passthrough 隧道被显式路由取代。 /passthrough/<provider>/<rest> 不再按模型服务提供方的名字自动解析；未被任何路由认领的 /passthrough/* 路径返回 410 Gone（error.code: endpoint_removed），并为每次命中打一条 WARN 日志指出调用方，便于找出尚未迁移的客户端。迁移方式：创建一条 passthrough 路由，path_prefix 设为 /passthrough/<provider>、target_url 设为原先的 API base、provider_key_id 设为它此前借用的那把 Key——客户端 URL 即可逐字节保持不变。有两处行为与旧隧道不同：路由是单次转发，上游 5xx 与传输层重试不再进行；由于路由不解析任何模型，这类流量也不再交叉标记模型冷却。访问权限是调用方 Key 上的显式授权（allowed_routes），没有授权的 Key 访问不到任何路由。
  • MCP 工具访问改为三层求交的一条规则。 环境策略、调用方所属团队的策略、以及 Key 自身的 mcp_access 块，各自携带 allow 与 deny 列表。allow 取交集、deny 取并集，因此任何一层都无法放宽另一层已经收紧的范围；未设置的层不施加任何约束，而三层都没有的调用方没有任何 MCP 访问权限。策略与 Key 上的 mode 均已移除，Key 上的 allowed_tools 也已移除（Key 这一层就是 mcp_access.allow），遗留 Key 的迁移流程一并删除。如果你配置过 MCP 工具策略，升级后请重新核对：最终生效的授权会按上述规则重新计算，可能与旧配置产生的结果不同。 其中两处变化影响最大：团队策略现在是在环境授权基础上进一步收窄，而不再是替换它，因此它无法再授予环境本身不允许的工具；没有 mcp_access 块的 Key 现在会跟随策略层，而不再游离于策略之外。每一层都必须写出 allow，因此一个只打算做减法的层需要把 allow 侧显式写成 ["*"]。
  • 安全护栏拦截 MCP 工具调用时，改为以工具错误的形式作答。 调用在协议层面返回成功，结果上带 isError: true，消息中指出是哪条安全护栏生效——绝不回显命中的内容——而不再返回 JSON-RPC 的 -32600。调用方 Agent 因此看到的是一段可以据此调整的工具输出，而不是一条中断的传输通道。此前依据 error.code == -32600 判断拦截的客户端，需要改读 result.isError。
  • weighted 路由策略与 sticky 开关已移除。 权重现在是每个目标自身的属性，在所有策略下都可用：round_robin 采用平滑加权轮询，因此权重相等或缺省时与此前的声明顺序轮转完全一致，权重不等时则严格保持比例。会话粘性成为独立策略 consistent_hash。通过 AISIX Cloud 管理的部署会自动迁移。声明式配置需要手工更新：weighted 改为 round_robin 并保留权重，weighted 加 sticky 改为 consistent_hash。仍然写着 weighted 的存量配置会加载失败，而不会被悄悄改变含义。迁移到一致性哈希后，会话与目标的对应关系会重新分布一次，因为它构建哈希环的方式不同。
  • 不受支持的 MCP 协议版本改为在 JSON-RPC 信封内被拒绝。 当请求的 MCP-Protocol-Version 请求头指定了该端点不提供的修订版时，返回 400 并附带一个 JSON-RPC 错误，其中列出受支持的版本，而不再返回游离于所有网关信封之外的裸 text/plain 响应。该端点提供 2025-03-26、2025-06-18、2025-11-25 与 2026-07-28；不再宣告 2024-11-05——它只存在于 HTTP+SSE 传输时代。
  • 通过 OTLP 导出的链路追踪现在形成层级结构。 到达上游的模型请求会产生一个 HTTP SERVER 跨度、一个覆盖全部重试与故障转移的逻辑 CLIENT 跨度，以及每次上游尝试各一个子跨度，取代了此前“每个用量事件一个扁平跨度”的形状。没有上游分发的已导出请求链路只有 SERVER 跨度；不采用逐次尝试追踪的协议包含 SERVER 跨度和一个 CLIENT 跨度。任何以“每个请求一个跨度”为前提的用法——跨度数量告警、按名字计数——都会看到结构性跨度出现。承载完整属性集的是尝试跨度，可用 aisix.attempt_index 识别；结构性跨度携带较少的关联属性，其中包括 aisix.request_id，SERVER 跨度的 Kind 为 2。另外，调用方的 traceparent 与 tracestate 不再转发给模型服务提供方；运营方为可信上游显式配置的 default_headers 条目仍然有效。
  • 文本转语音的延迟改为按首字节计。 /v1/audio/speech 现在边接收边转发合成的音频，而不再整体缓冲，因此播放器可以在首批字节到达时就开始播放，上报的延迟也随之从"到最后一个字节"变为"到第一个字节"。这与此处所有其他流式接口已有的口径一致。

新功能​

  • Passthrough 路由。 一条路由把一个网关入口——路径前缀、入站 Host 白名单，或两者兼有——绑定到一个上游目标，因此可以把 IDE 或编码 Agent 指向网关，在不改动客户端的前提下对其流量进行审计。Host 匹配在路由之前进行，因此携带原始 Host 送达的正向代理流量可以认领网关同样在用的路径；路径匹配则作为路由器的兜底，因此一条路由绝不会遮蔽网关自身的 API。调用方可以用网关 Key 认证、把 Key 放在你指定的请求头里（从而让 Authorization 留给上游凭证），或者以受源 CIDR 白名单约束的绑定主体身份匿名访问。上游凭证要么由模型服务提供方 Key 注入，要么在路由删除网关凭证和固定请求头集合后转发调用方凭证。可选的设备注入身份请求头会被记录为该请求的终端用户身份，用于按员工归因。请求信封按请求识别——chat、Responses、completions 或不透明——并据此驱动安全护栏取文、审计留存与 Token 计量；非 LLM 调用的流量不会产生虚假 Token。SSE 响应逐帧转发。参见 Passthrough 路由和面向 IDE AI 流量的正向代理。
  • 模型组的一致性哈希与优先级层级。 strategy: consistent_hash 通过把请求键哈希到目标环上，将每个会话固定到同一个目标：相同的键始终命中同一个目标，权重决定各目标的份额，而某个目标故障时只有它自己的会话迁移到环上的后继目标，其余键的映射全部保持不变。请求键来自你配置的来源链（hash_on：请求头、Cookie、调用方 API Key 或客户端 IP），默认使用路由键请求头并回退到 API Key。此外，每个目标都可以设置 priority：目标据此划分为若干层，数值越大越优先，只有当某一层内所有目标都失败或被健康状态摘除后，下一层才会收到流量——因此备用池可以在活跃池之后静默待命，而首个发现整层已死的请求也能在层内溢出并成功返回。
  • MCP 2026-07-28。 /mcp 与 /mcp/{server} 提供该规范的最终修订版，包含免握手的发现生命周期与无状态传输。已注册的 MCP 服务器可选配置 protocol_version，用于固定网关开启上游会话时使用的修订版——这是访问"不再响应旧握手"的服务器的唯一方式；不配置时网关按此前方式协商，因此既有配置保持不变。两个方向上都是显式选择：网关既不探测也不静默回退，因此版本不匹配会明确失败，而不会悄悄协商到一个你本想排除的版本。
  • MCP 匿名访问。 环境可以允许不携带任何凭证的 MCP 客户端访问指定入口，并以你指定的一把 API Key 的身份运行——该 Key 的工具授权、限流、预算与用量归因全部适用。它受一份必填的源 CIDR 白名单约束，需要列出所开放的入口，且聚合入口 /mcp 需要显式开启。携带凭证的客户端仍按正常流程认证；凭证无效时会被拒绝，而不会被降级为匿名服务。
  • 面向 /mcp 的 OAuth 2.1 资源服务器发现。 配置了规范资源 URL 并启用了身份提供方后，网关会发布受保护资源元数据，并对未认证的 MCP 请求返回指向该元数据的 WWW-Authenticate 质询，使标准 MCP 客户端能够自行发现到哪里获取 Token。Bearer Token 的 audience 必须包含该 URL。
  • 安全护栏可以限定到单个 MCP 服务器，从而只守护某一个已注册的服务器，而不必守护环境内所有 MCP 流量。安全护栏现在还会扫描工具的结构化输出，而不只是文本块。
  • 关闭时的排空窗口。 收到 SIGTERM 后，网关立即将自身标记为未就绪，随后至少在 shutdown.min_drain_secs（默认 30 秒）内继续接受新连接，然后才关闭监听器，使负载均衡器在其自身检测窗口内转发过来的连接仍能被正常服务。窗口期内 HTTP/1.1 响应会带上 Connection: close，让使用连接池的客户端在使用过程中自然退休这些连接。这个窗口是下限而非期限：只有窗口耗尽且没有请求在途时，监听器才会关闭。
  • 现在会采纳 W3C 链路上下文。 合法的入站 traceparent 会让网关产生的 span 成为调用方链路的子节点；格式错误或重复的请求头会被忽略并改用本地根节点，而不会导致请求失败。span id 与 trace id 每个请求只生成一次，因此投递重试会重发完全相同的 id，而不是新的一组。用量事件中携带 trace id 以便关联。
  • 流式音频转写改为实时转发。 /v1/audio/transcriptions 在 stream=true 时现在边接收边转发帧，而不再从完整读取的响应体作答，同时仍会记录该请求的 Token 用量。带拦截或掩码能力的输出安全护栏仍走缓冲路径，因为它必须在任何内容到达调用方之前看到完整的转写文本。
  • Cloud Admin API 支持角色管理。 自定义角色的增删改查、组织角色分配，以及环境级角色绑定，现在都纳入了公开的 API 契约，并具备生成的绑定代码与请求校验。

改进​

  • 发布镜像现在采用基于性能剖析的优化（PGO）构建，内存分配器会在负载回落后通过后台线程把已释放内存归还给操作系统。
  • 严格校验在拒绝"某个模型类型根本不读取的配置"时，现在会指出具体是哪个配置项，而不再只是报告文档校验失败。
  • Passthrough 流量会记录其识别出的信封所携带的全部用量维度。

修复​

  • 流式音频转写此前一直按零 Token 计费。 网关的 SSE 解码器只在遇到一对换行符时才认为事件结束，而模型服务提供方在转写流中使用回车换行分帧，因此携带 Token 计数的终止事件从未被解码，每一次流式转写都记录为零 Token。事件现在在任意两个连续的行终止符处结束。该解码器被所有流式桥接路径共用，因此任何使用回车换行分帧的上游都受此影响，不限于音频。
  • 在分层规则之前写入 MCP 访问配置的调用方 API Key 现在仍能正常加载，而不会被丢弃。
  • deployment 与 fallback 计数器现在会被正确发射；分发前的失败不再计入其中，失败的请求也会归因到已解析出的调用方。
  • Passthrough 流量在链路追踪与被拒请求事件中的归因已修正，基于请求头的认证返回 401 时会指出它期望的请求头。
  • 按 Host 匹配的正向代理路由现在可以认领网关保留的路径前缀，并镜像完整的请求路径。
  • 音频元数据解析不再对普通上传文件输出告警日志。
  • 控制台方面：创建模型时的选择器不再显示为"不支持"，Dimensions 字段不再被错误标注为可选，页面路由切换有了加载态，MCP 认证设置也移到了 MCP Access 页面，与其余 MCP 配置放在一起。

升级注意事项​

  • 请先升级控制面，再升级网关。 这是受支持的顺序，中间的混合版本窗口可以持续任意长时间。在窗口期内，仍运行 0.9.x 的网关会停止服务此前使用 weighted 加 sticky 的模型组（迁移后的配置使用了该版本不认识的策略名），也不会应用 MCP 工具策略（其存储形状已变化）。调用方 API Key 在整个窗口期内始终可以正常认证——只是在尚未升级的网关上，它们的 MCP 访问处于关闭状态，直到该网关完成升级。这两种情况都可以在控制台的数据面兼容性视图中看到。
  • 通过 AISIX Cloud 管理的部署，会在升级后控制面首次启动时自动迁移存量的路由配置。声明式配置不会被自动迁移，需要按"行为变化"一节所述手工更新。

0.9.0​

发布日期： 2026 年 8 月 13 日

这个版本让网关明显更快，也让 Agent 流量变得可观测。代理层改为按核独立的 worker 模型，吞吐大约翻倍、p99 延迟减半。缓存学会了匹配“意思相同”的请求，而不再只能匹配“写法相同”的请求。A2A 调用现在会记录它推进了哪个任务、消耗了多少；经过验证的 JWT 也可以代替调用方 API Key，由身份提供方的 claim 决定请求以哪个调用方的身份运行。

这个版本同时完成了 0.4.0 中宣布的 Admin API 弃用：网关自带的 Admin API 现在是只读的，资源改为声明式管理或通过 AISIX Cloud 管理。

行为变化​

  • 网关的 Admin API 不再写入资源。 Admin 监听端口保留全部读取能力——各类资源的列表与详情、模型状态、健康检查、OpenAPI 参考和 Playground——但 /admin/v1/<kind> 上的 POST、PUT、DELETE 现在返回 405 并带 Allow: GET，API Key 轮转路由的两种拼写都返回 404。这完成了 0.4.0 中宣布的弃用。请改用资源文件管理资源（用 aisix validate --resources <file> 校验，用 SIGHUP 重载），或直接写入 etcd；连接 AISIX Cloud 的网关从不暴露该监听端口，不受影响。声明式轮转调用方 Key 的方式是：用同一个资源 id 写入新的 key_hash，写入传播后旧密钥立即失效。发布的 Admin API 参考中已不再包含写操作。参见资源文件。
  • 缓存条目默认按调用方 API Key 隔离。 缓存策略新增 scope 字段，默认值为 api_key，因此一个调用方的应答绝不会被回放给另一个调用方。依赖环境内跨 Key 共享的部署需要显式设置 scope: env。无论选择哪种，缓存键的形状都会发生变化，升级后会出现一次性的全量未命中。参见缓存。
  • 首 Token 时间改为在第一个流式帧处停表，不再区分帧的类型。 此前它会一直等到出现携带生成内容的帧，因此对于“先静默思考再作答”的模型，记录到的是思考结束的时刻——这个数值可能超过该请求自身上报的延迟，也无法与前置网关的口径直接比较。思考所花的时间仍可从上游延迟中看到。按旧口径校准过的监控面板和告警阈值需要重新调整。参见指标与日志。
  • 调用方传入的 request id 现在会被网关采用。 网关默认接受 x-aisix-request-id：该值会原样回传、记入访问日志与用量事件，并转发给上游。id 必须是 1–256 个可见 ASCII 字符；不满足的一律忽略并由网关自行生成，因此格式错误的请求头绝不会导致请求失败。若还想遵循 x-request-id 约定，将其加入 proxy.request_id.accept_headers；把该列表置空则恢复此前行为。由于该 id 现在由调用方控制，它既不唯一也不可信，因此不会被用作任何指标的标签。参见指标与日志。
  • 某个模型类型运行时根本不读取的配置，现在会被拒绝，而不再是存下来却被忽略。 模型组上的 retries、auto_prompt_caching、cost，Ensemble 上的通用调用参数，以及语义路由上的 auto_prompt_caching 和 cost，在写入时都会被拒绝并返回 400。携带这类字段的资源文件将加载失败，并指出出问题的条目。已经存下这类字段的模型不受影响：网关会剥离该字段并按“部分兼容”上报，而不会让这个模型停止服务。反方向上，语义路由和 Embedding 模型现在接受 timeout、stream_timeout 和 retries，此前这些是被拒绝的。
  • 若干此前被静默接受的配置现在会被拒绝。 创建模型时携带属于其他类型的配置块、把通配符别名用作 Ensemble 成员或裁判模型、用作语义路由的目标或默认模型、用作缓存策略的作用目标，把被引用的模型改名为通配符，以及让缓存策略指向不存在的模型，现在都返回 400。这些操作此前都会被接受，然后被悄悄忽略。
  • 经过通配符模型的流量按通配符自身的名字上报。 指标、限流计数桶和健康状态现在以配置中的通配符条目为准，而不再以各调用方随手写下的别名为准，因此一个模型就是一个身份，不会因写法不同而分裂成多条序列。按调用方别名过滤的监控面板，会看到对应序列在这个版本处中断。
  • 升级注意事项。 控制面把用量表的 request_id 列从 uuid 加宽为 text，以便保存调用方自己的 id。在大表上这会触发整表重写——大约每 1000 万行 6 分钟——重写期间控制面不对外服务。Helm Chart 的启动探针预算已相应放宽到 30 分钟；如果你使用自己维护的编排清单，请在升级前同步调大。

新功能​

  • 代理层改为按核独立的 worker 模型。 每个 worker 拥有各自的运行时、监听套接字和上游连接池，因此一个请求的接收、派发和应答都在同一个线程上完成，不再需要在线程之间来回移交两次。在 4 核上，吞吐随并发度提升 54%–88%，p99 延迟大约减半，每请求的系统调用次数从 11.9 降到 5.0。Linux 上默认开启。两个启动期生效的配置项：proxy.thread_per_core 和 proxy.workers，后者默认取进程可用的并行度并会跟随 cgroup 的 CPU 限制。当每个 worker 分到的客户端连接不足约 4 条时，内核的连接分配会不均，此模式反而慢于共享运行时；这种低并发场景请设置 proxy.thread_per_core: false。
  • 语义缓存。 缓存策略现在可以按语义匹配：未命中精确匹配的请求会被向量化，并从余弦相似度达到设定阈值的最近条目中返回结果。只有纯文本请求会走这条路径——包含图片、音频或工具调用的请求一律走精确匹配。条目可以存放在各网关自身的内存中，也可以设置 backend: redis，借助 Redis 向量检索在多个副本间共享。共享方式要求 Redis 8 及以上版本或加载 search 模块；网关在启动时探测，若不具备该能力，则继续提供精确匹配并在日志中说明，而不会让流量失败。策略也可以在不删除的前提下整体清空。参见语义缓存。
  • JWT Claim 映射。 新增的资源可以把经过验证的 OIDC claim 解析到一个已存在的调用方 API Key，从而无需为每个用户单独发放 Key，就能由身份提供方决定请求以哪个调用方的身份运行。规则按优先级顺序求值，第一条 claim 条件全部成立的规则选定目标 Key，随后请求完整继承该 Key 的模型与工具访问权限、限流和预算。条件支持对嵌套 claim 路径做精确字符串匹配和数组包含匹配。未命中任何规则的 Token 一律拒绝。用量事件会记录 subject、身份提供方和命中的映射——请注意 subject 属于最终用户标识，会随用量事件流向已配置的可观测性导出目标。参见 Claim 映射。
  • A2A 调用现在具备协议级可观测性。 每次调用都会记录操作类型、任务 id、上下文 id 和最终任务状态，并对两套线上词汇做归一，避免同一个指标被拆成两份。流式调用还会额外记录首个事件的到达时间、事件数量，以及流结束时调用方是否仍在接收，因此中途挂断的调用不再被计为成功。由于该协议本身不携带 usage 字段，网关会依据流经的消息文本估算 Token 并标记为估算值；成本保持为零，因为 Agent 的计费方式不是网关能够知晓的。指标按 Agent 和操作类型切分。参见 Agent 网关。
  • 模型服务提供方返回的响应 id 现在会被记录。 它会出现在访问日志中，也会出现在每次上游尝试各输出一条的专门日志行里——后者覆盖了单条访问日志在结构上无法覆盖的两种情况：流式响应，以及重试或故障转移产生的后续尝试。控制台的日志详情面板也会展示该 id，因此排查上游侧问题时无需再手工跨系统关联记录。
  • 限流策略支持 day 窗口，按 UTC 自然日计数。参见限流策略。
  • 控制台的请求日志按网关面拆分。 LLM、MCP 和 A2A 流量各有独立的标签页，且每个标签页只提供真正能用于筛选它的过滤条件，而不再是一个混合列表配一组只对部分流量有效的过滤器。
  • 控制台的下拉选择框支持搜索。 模型、模型服务提供方 Key、调用方 API Key 等可能变长的选择框，现在都可以边输入边筛选，不必在完整列表中滚动查找。
  • 控制台会提示网关的配置兼容性。 当你保存的某个配置并非环境内所有网关都能理解时，控制台会在保存时和数据面视图中给出提示，指明具体字段和引入该字段的版本，而不是让这个配置在旧版本网关上静默失效。

改进​

  • 除按核 worker 模型之外，每请求路径还做了一系列优化：改用 jemalloc 内存分配器并启用链接期优化、为零配置部署跳过不需要的处理环节、为每个 worker 缓存指标句柄、对下行连接设置 TCP_NODELAY、缓存上游端点 URL，以及每个请求只加载一次配置快照。
  • 限流条件中的模型维度，现在会同时匹配调用方寻址的条目和实际派发到的目标，因此以模型组为条件的策略能够覆盖所有寻址到该组的请求。此前只比较派发目标，这类条件永远不会命中。
  • 语义路由在选路时会遵守成员自身的访问规则，遇到调用方无权使用的成员会转向其他目标，而不是直接派发过去。
  • 按模型的限流现在适用于所有模型类型，控制台也在每种类型上提供限流表单。
  • 缓存策略的作用目标会在创建时校验；被策略引用的模型改名后，引用会同步更新。

修复​

  • 已过期的邀请不再继续占用邮箱地址，同一个人可以被重新邀请。仍在有效期内的邀请依然会阻止重复邀请。
  • 创建资源时把布尔字段显式设为 false，现在会真正存为 false。此前数据库列默认值会替换掉零值，导致创建时设为禁用的 OIDC 身份提供方被存成启用，API 也随之回显为启用。
  • Realtime 端点上认证通过之后发生的拒绝，现在会归属到已解析出的调用方，而不再是没有身份信息的记录。
  • 已停止上报心跳的网关不再计入控制台的配置兼容性提示，避免一个已下线的实例让健康的集群看起来处于部分不兼容状态。
  • 从源码构建且未注入版本号的网关会上报一个占位版本号；该占位值现在被视为“版本未知”，而不再被当作某个真实的旧版本，因此这类集群不会再对其实际可能支持的特性长期告警。

0.8.2​

发布日期： 2026 年 8 月 11 日

这是一个面向 A2A 网关的维护版本。网关现在会向上游声明每台 Agent 所固定的协议版本，能找到发布在路径前缀下的 Agent Card，把 Card 上公布的每一个地址都指向自身，并把 message/stream 按事件到达的节奏实时中继，而不再缓冲整个响应体。此外，Agent 与 MCP 服务器的命名规则和凭据约束现在适用于所有配置路径，而不再只有网关自带的 Admin API。

行为变化​

  • 通过资源文件提供的 A2A Agent 与 MCP 服务器定义，现在会按 Admin API 相同的规则校验：名称格式、各 auth_type 所需的凭据，以及基于 OpenAPI 的 MCP 服务器所需的字段。违反其中任何一条的文件不再加载，网关会指出是哪一条目缺少哪个属性，而不是带着一份无法工作的定义启动——名称中含 / 的 Agent 会把自己的 /a2a/<name> 路由劈成两段，auth_type: bearer 却未设置 secret 则等于用空凭据向上游认证。通过控制面配置的部署不受影响，因为这些规则在创建资源时就已生效；由控制面托管的网关只会拒绝出问题的那一条，其余配置继续服务。发布前可用 aisix validate --resources <file> 先行检查。参见 Agent 网关。

修复​

  • 网关现在会在发往某台 Agent 的每个请求中，用 A2A-Version 头声明该 Agent 所固定的协议版本，包括获取 Agent Card 的请求。此前网关从不发送该头，而 A2A 规范要求 Agent 把该头的缺失读作 0.3 版本——因此固定为 1.0 的 Agent 会回 VersionNotSupportedError，配置的 protocol_version 形同虚设。调用方自行提供的版本不会覆盖注册时固定的版本。
  • 发布在路径前缀下的 A2A Agent 现在能被正确发现。此前网关在源站构造 well-known Card URI，丢弃了注册时给出的路径，因此部署在 ingress 路径之后的 Agent、或按路径前缀区分租户的 Agent 平台，都会被请求一个它并不在该位置提供的 Card，而平台兜底返回的 405 会被当作 Agent 自己的应答。
  • 网关返回的 Agent Card 现在会把公布的每一个地址都指向网关自身。此前只重写顶层 url，supportedInterfaces 中仍是上游的真实地址——而 A2A 1.0 客户端正是从那里选取端点，因此可以绕过网关（连同调用方身份认证和按 Agent 的访问控制）直接访问上游 Agent。
  • message/stream 和 tasks/resubscribe 现在会按事件到达的节奏中继 Agent 的事件流。此前这两个方法走单响应路径，会缓冲整个响应体并按单个 JSON 文档解析；而事件流不是合法的 JSON，因此这两个本就用于观察长任务进展的方法都会失败并返回 502，完全无法使用。事件会跨数据块边界重新组装；遇到格式错误的事件会以错误结束流，而不是跳过它，从而避免被截断的任务被读成已完成的任务。

0.8.1​

发布日期： 2026 年 8 月 7 日

这是一个维护版本。它修正了网关判断上游是否使用 Anthropic 协议的依据，使指向自建 Anthropic 端点的模型可通过整个 /v1/messages 端点族提供服务，并原样转发请求体。此外，认证拒绝日志补充了排查问题所需的上下文，MCP 服务器重命名时工具授权会随之迁移，并修复了控制面上若干缺少可用请求格式或可操作错误提示的准入路径。

行为变化​

  • 启用 auto_prompt_caching 现在要求模型的服务提供方密钥采用 Anthropic 协议，即 provider: anthropic，或适配器为 Anthropic 的 BYO 密钥。该设置通过注入 Anthropic cache_control 标记实现；此前，该设置在其他上游上虽然可以保存，却从不生效，也不会提示运维人员提示词缓存并未开启。现在，在其他上游上启用该设置会返回 400。所有模型服务提供方仍可关闭该设置，因此可以清理本版本之前配置的模型；如果无法确定密钥的适配器，系统仍会允许操作，而不会在无法确认的情况下拒绝。参见 Anthropic 提示词缓存。
  • 配置为 provider: byo 且适配器为 Anthropic 的模型，现在可通过 /v1/messages 提供服务并原样转发请求体，不再通过跨模型服务提供方的桥接重新编码。客户端自行设置的 cache_control 标记会原样到达上游；此前，该标记会被丢弃，或在模型启用 auto_prompt_caching 时被改写为模型配置的 TTL。这也会改变适用的上游缓存写入价格：1 小时写入的价格是基础输入价格的 2 倍，5 分钟写入的价格是 1.25 倍。身份认证行为保持不变。

改进​

  • 认证拒绝日志现在包含排查问题所需的请求上下文：通过可信代理配置解析出的调用方地址、HTTP 方法和路径，以及请求 ID。密钥被禁用或已过期时，拒绝日志还会包含该密钥的 ID。返回 401 的请求会在任何处理程序运行前被拒绝，因此不会进入访问日志；拒绝计数指标此前是唯一的记录，但该指标无法说明调用方是谁、拒绝发生在何时或请求了哪条路由。日志级别保持不变：扫描器流量仍使用 debug 级别，默认日志级别的输出与之前完全相同。参见指标与日志。
  • AISIX Cloud Admin API 参考现在正确描述了模型服务提供方请求头和条件限流的计数器语义。此前，参考文档称修改策略的 conditions 会重置当前窗口；实际上，计数器 Key 由策略 ID 和所选 group_by 维度的值构成。因此，只修改 conditions 或 limits 会保留现有 Key 及其计数，而修改分组维度会使请求使用不同的 Key。

修复​

  • /v1/messages/count_tokens 现在依据适配器而不是模型服务提供方标识来判断上游是否使用 Anthropic 协议。指向 Anthropic 协议端点的 provider: byo 模型此前会在该端点上收到 400，但同族的 /v1/messages 可以正常提供服务。
  • MCP 服务器重命名时，工具授权现在会随之迁移。工具名采用 <server>__<tool> 格式，因此每项授权都通过名称引用服务器。按 API Key 配置的限流条目此前已经会随重命名迁移，但访问控制不会；这会在没有任何提示的情况下撤销对整台服务器的访问，使其工具从 tools/list 中消失。调用方 API Key 的 allowed_tools 和 mcp_access，以及环境级和团队级访问策略，现在都会一并重写。匹配名称模式而非某一台特定服务器的通配符（例如单独的 *）保持不变。参见工具访问控制。
  • Amazon Bedrock 和 Google Vertex 的模型服务提供方密钥现在可以仅通过 config 创建。两者的凭证无法放入单个 api_key 字符串，但 Schema 要求提供 api_key，而处理程序又会拒绝非空值，因此此前唯一可接受的请求必须使用文档中从未说明的空字符串。现在，缺少凭证的请求会指出该模型服务提供方实际接受的字段。参见选择模型服务提供方上游。
  • 用 PATCH 提交 "tls": null 现在会清除模型服务提供方密钥的 TLS 设置，与 rate_limit 等其他可选块的行为一致。此前它返回 400，只能用空对象清除。
  • 用量列表及其 CSV 导出现在包含 audio_duration_seconds。按时长计费的转写此前能看到费用，却无法从 API 读回它的计费基数。不含音频的请求会省略该字段。参见音频。
  • 离线包不再让两份安装变成一份。Compose 项目名此前取自解压出的目录名，因此在其他位置解压第二份安装包并运行 run.sh，会接管正在运行的安装，使用第二份安装的配置重建其容器，同时继续挂载原来的数据卷。项目名现在固定为安装包本身；若另一目录中已存在同名栈，启动会被拒绝，并同时显示两个目录路径和可选处理方式。原地升级不受影响；如需启动第二套独立安装，仍可显式指定 COMPOSE_PROJECT_NAME。参见 On-Premises 快速入门。
  • 离线包中的控制台容器现在拥有可写的 Next.js 缓存目录，与 Helm Chart 保持一致。
  • 可信代理 CIDR 与 User-Agent 客户端类型规则现在可以用环境变量设置。proxy.real_ip.trusted_proxies 和 observability.metrics.client_type_rules 此前只能写在配置文件里，用对应的 AISIX_* 变量设置会导致网关无法启动。因此完全依赖环境变量配置的部署——Helm Chart 与控制台给出的 docker run 片段——无法把自己的负载均衡器声明为可信代理，所有请求看起来都来自它。参见指标与日志。
  • 两处准入错误现在会说明如何修正。在策略不是 weighted 的路由组目标上配置 weight 时，错误会指出相关字段和策略，而不再只报告笼统的字段无效；provider 值无法识别时，错误会指出被拒绝的值，并说明目录路由需要控制台会话，而不是 Admin Token。
  • 控制台现在允许一个 API Key 访问多个模型组。此前，选择一个模型组会禁用其他选项，因此一个 API Key 只能引用一个模型组，尽管 API 始终接受包含多个模型组的列表，编辑对话框也从未实施该限制。两个对话框现在共用同一个选择器，这还修复了模型组、合议模型、向量嵌入模型和语义路由在编辑对话框中显示空箭头的问题。

0.8.0​

发布日期： 2026 年 8 月 6 日

此版本让限流足以表达真实的配额策略。单条策略现在可以通过条件树决定自己作用于哪些流量、按这些流量的任意维度拆分计数器、同时约束七种不同的量，并按周期性时间表自动暂停自身——例如工作日的非高峰时段、整个周末或指定的节假日。MCP 网关新增只服务单个 MCP 服务器的端点，并保留其原始工具名，使针对该服务器编写的客户端无需改动即可接入。Token、支出和请求指标现在覆盖所有上报用量的端点，而不再只有 Chat Completions 和 Messages；音频转写按音频时长计费。

行为变化​

  • 网关现在在所有 OpenAI 系列端点上都把 api_base 当作上游根路径。此前 /v1/chat/completions 会逐字把端点追加到所配置的 Base URL 之后，而 /v1/responses、/v1/rerank、/v1/audio/*、/v1/realtime、/v1/files、/v1/batches 和 /v1/fine_tuning/jobs 会在 Base URL 未以 /v1 结尾时插入一段 /v1，因此上游根路径不是 /v1 的密钥能正常处理聊天，其余端点全部返回 404。现在两条路径以同一方式解读 Base URL。带路径但不含版本段的 Base URL 现在会构造 https://proxy.corp/openai-shim/responses，此前构造的是 .../openai-shim/v1/responses；如果你依赖旧的补全行为，请把 /v1 写进 api_base。仅含主机名的 Base URL 仍会补上 /v1，以 /v1 结尾的 Base URL 行为不变，Anthropic 在所有 Base URL 形态下均不变。参见兼容 OpenAI 的模型服务提供方。
  • 两个指标的直方图桶边界发生变化。aisix_request_ttft_seconds 去掉了 50 毫秒以下的两个边界，因为它度量的是上游首 Token 时间，永远不会落在那里；aisix_request_e2e_latency_seconds 新增 420 秒和 600 秒两个边界，使 histogram_quantile() 能在 300 秒之上插值，而不是被钉在 300 秒。依赖旧边界的仪表盘和记录规则需要更新。两套边界现在都可以在 observability.metrics.buckets 下按指标分别配置。参见指标。
  • 首 Token 时间现在计入推理模型的首个推理增量。此前只有普通内容才会打点，因此先推理再作答的模型上报的首 Token 时间晚于调用方实际观察到的时刻。这类模型上报的数值会相应下降。参见指标与日志。
  • GET /v1/models 现在会连同直连模型、语义路由和合议模型一起列出模型组。模型组此前是唯一被过滤掉的虚拟别名，因此把模型组作为对外入口、并将调用方 API Key 限定到该模型组的部署，拿到的是一个空列表。授权没有任何变化，这些名字本来就可以被这些 Key 调用。只有断言精确模型列表的客户端会受影响。参见模型别名。

新功能​

限流​

  • 限流策略现在可以写成条件式，携带一棵条件树而不是单一作用域。条件可以匹配团队、成员、调用方 API Key、模型、模型名和模型服务提供方，通过显式的 and、or 分组组合，最多嵌套三层，支持取反，并可按相等、列表成员或正则表达式匹配字符串。因此同一个资源可以为不同流量承载不同配额，而不是只有一个固定数值。参见限流策略。
  • 条件式策略通过 group_by 拆分自己的计数器，按团队、成员、调用方 API Key、模型或它们的任意组合分桶。此前需要为每个租户各配一条策略，现在单条策略即可实施按租户的配额。
  • 一条策略可以任意组合约束七种量：每秒、每分钟、每小时、每天的请求数，每分钟、每天的 Token 数，以及并发请求数。
  • 匹配模型属性的策略会在具体模型确定处预留配额，对路由或合议模型的父别名而言即按每个目标预留。超限的目标被视为一次失败的尝试并故障转移到下一个，而不是消耗父别名自身的配额。
  • 限流拒绝现在会标明是哪条策略产生的。429 响应体携带该策略的 ID 和名称，aisix_ratelimit_rejections_total 现在统计所有端点上的拒绝，并带有生效层级和策略标签。在多条策略同时生效时，无归因的拒绝无法追溯成因。
  • 策略可以携带周期性的暂停窗口，窗口期内不予执行。每个窗口按星期或按显式日期选择生效日，起止时间是其自身 IANA 时区下的挂钟时间，结束时间早于或等于开始时间即视为跨越午夜，并归属于其起始日。多个窗口取并集，窗口结束后自动恢复执行，且切换不会重置计数器，因此无法通过在同一个限流窗口内暂停再恢复来清掉已消耗的配额。在 AISIX Cloud 中，控制台以限流策略表单上的时间表列表呈现该能力。参见限流策略。

MCP 网关​

  • 新增按服务器划分的端点 /mcp/{server}，只服务单个已注册的 MCP 服务器，并以工具的原始名称列出其工具，不带聚合端点所加的 <server>__ 前缀。调用工具时同时接受裸名和带前缀两种写法，而工具访问控制始终在带前缀的形式上判定。因此针对某个服务器自身工具名编写的客户端，经由网关也无需改动即可工作。参见MCP 网关概述。

部署​

  • 新增 proxy.url_rewrites 配置，在网关入口处改写请求路径，按正则表达式匹配并支持在替换字符串中引用捕获组。启动时会校验这些模式，对于不携带配置文件的部署也可以通过环境变量提供。这让 Base URL 无法更改的客户端能够访问不同的网关路径。参见 URL 重写。

计费​

  • 音频模型现在可以按音频时长而不是 Token 计价。转写请求会以音频长度作为计费依据，模型价格按每分钟音频表示。在 AISIX Cloud 中，控制台的模型定价表单接受这类费率。参见音频和模型定价。

改进​

  • 详细请求指标以及 Token 和支出指标现在覆盖所有上报用量的端点，包括 Responses、Embeddings、Rerank、音频、图像和 Realtime。此前它们只覆盖 Chat Completions 和 Messages，因此其他端点上的用量虽然记入用量日志，却在指标中缺失。参见指标。
  • 配置读取现在向前兼容。携带了本网关版本不认识的字段的资源文档会正常加载并生效，未知字段被忽略并上报：配置状态端点的 partially_compatible、一条去重后的告警，以及一个新的 gauge 指标。此前任何未知字段都会导致整条文档被拒绝，这使控制面上每一次纯新增的变更，对尚未升级的网关而言都成了破坏性变更——携带新字段的调用方 API Key 会直接失效。写入路径仍然严格，依旧拒绝未知字段。参见配置状态。
  • 被拒绝的配置更新不再让最后一份可用值丢失。网关会在重新同步和重启之后继续提供此前为该键加载到的值，而不是丢弃该条记录。参见配置传播。
  • 模型服务提供方在已经开始的流中上报的错误，现在会带着其自身的状态码和消息呈现出来，覆盖 OpenAI 系列、Anthropic、Gemini 和 Amazon Bedrock 的流。此前 Anthropic 在流中途送达的 error 事件会被丢弃，被截断的流像正常完成一样关闭，客户端无法区分响应是被切断还是已经结束。这类流现在以一个错误帧结束，且不带完成标记。参见流式响应。
  • 因超出请求体大小限制而被拒绝的请求，现在会通过一个专门的指标上报其请求体读取是如何结束的，从而把客户端断开导致的拒绝与请求体被完整读完的拒绝区分开。参见指标与日志。
  • 当网关以明文 http 访问需要凭证的 MCP、OpenAPI 或 A2A 上游时，会告警一次，并按服务器和地址去重，使配置失误可见而不至于灌满日志。参见MCP 上游认证。
  • 发往 /v1/realtime 但并非 WebSocket 升级的请求，现在会被记录并以网关自身的错误格式作答；代理中其他位置的路径拒绝也走与其他早期拒绝相同的路径，因此会出现在访问日志和请求计数中。参见Realtime。
  • AISIX Cloud Admin API 参考现在记录了其公开的所有操作和 Schema，并将 Base URL 从固定的相对路径改为可编辑字段。该参考托管在 API7 文档站点，而不是读者的控制面上。因此，混合云或本地部署的读者可以把 Base URL 设置为自己的控制面，使示例使用正确的端点。

修复​

  • 流式转写现在会记录它上报的用量。此类请求此前记录零 Token，因此不产生费用，而同一个转写以非流式方式发起时会正常计费。参见音频。
  • 离线包的快速入门脚本现在打印可用的控制台地址。此前它打印的是容器内部端口，因此按默认安装路径操作时，照着打印出的 URL 访问会失败。参见On-Premises 快速入门。
  • 控制台的模型定价表单现在接受每分钟低于一美分的音频费率，多数模型服务提供方的音频定价都需要这一精度。
  • 控制台中的预算阈值提示不再暗示硬停止可以任意超出其上限。参见预算。

0.7.1​

发布日期： 2026 年 7 月 31 日

此版本让网关可以部署到此前无法接通的网络中。出站连接新增信任配置，因此证书由私有或企业 CA 签发的模型端点、安全护栏或 MCP 上游，无需进程级的变通手段即可访问，既可以在部署级配置，也可以在声明该端点的模型服务提供方密钥上逐个配置。运行在独立主机上、以 IP 地址寻址的数据面，现在可以完成双向 TLS 握手并接入其控制面。被调用方放弃的请求，以及网关在分发前就拒绝的请求，不再从访问日志和指标中消失。

行为变化​

  • 流式响应在传输中途被调用方放弃，现在记为 499 而不是 200。此前用量事件上报的是一次完整的投递，因此中途关闭连接的调用方与把整个流读完的调用方无法区分。按状态码 200 筛选的报表和仪表盘会看到这些请求转移到 499。参见指标与日志。

新功能​

出站 TLS​

  • 新增 upstream.tls 配置，通过 ca_file、client_cert_file、client_key_file 和 verify 设定网关在每一条出站连接上使用的信任配置。它适用于模型端点、所有安全护栏服务、MCP 和 A2A 上游、透传路由、JWKS 与 OIDC 发现，以及 OpenTelemetry 导出。此前私有 CA 之后的上游只会以一个笼统的连接错误失败，唯一的变通手段是进程级的 SSL_CERT_FILE 环境变量，而若干出站路径并不遵循它。参见TLS 与 mTLS。
  • 模型服务提供方密钥可以携带自己的 tls 块，其中包含内联的 ca_cert 和 verify 开关，因此面对多个私有 CA 的部署可以在声明端点的位置声明信任。证书以内联方式而非文件路径提供，因为配置模型服务提供方密钥的人没有办法把文件放到网关主机上。在 AISIX Cloud 中，控制台将其呈现为模型服务提供方密钥表单上的 Endpoint TLS 区块。
  • rediss:// 的缓存或限流后端可以携带字段相同的 tls 块，因为它通常位于你自己的部署内部，由与模型端点不同的 CA 签发。有两处限制被明确记录而不是静默忽略：Amazon Bedrock 支持 ca_file，但不支持客户端证书，也不支持 verify: false；Redis Sentinel 模式支持 verify，但不支持 ca_file。

改进​

  • 在分发前被拒绝的请求现在会出现在访问日志和 aisix_requests_total 中。请求体超过 request_body_limit_bytes 时会正确返回 413，但除此之外不留任何痕迹，这使得"客户端报告了一次网关毫无记录的拒绝"与"请求根本没有到达"无法区分。Content-Length 头冲突返回的 400 存在同样的缺口。这些拒绝发生在认证之前，因此不携带用量事件，也不会出现在 AISIX Cloud 的日志页上。
  • 在响应头之前就被放弃的请求会被记录，而不是凭空消失。此类请求此前同时缺席于访问日志、用量事件和指标，恰好掩盖了运维最想看到的情况：调用方在漫长的首 Token 等待中放弃。新增计数器 aisix_proxy_client_cancelled_requests_total 按端点统计它们。参见指标与日志。

修复​

  • 位于独立主机、以 IP 地址指向其控制面的数据面，现在可以完成双向 TLS 握手并接入。数据面管理器签发的服务端证书，其 SAN 只来自它的监听地址以及客户端发送的服务器名称，而在容器中这两者都得不到控制面的对外地址：监听器绑定在所有网卡上，因此没有主机名可读，而以 IP 地址发起连接的客户端根本不会发送服务器名称。现在对外公布的地址会传给数据面管理器，由它为该主机签发证书，因此 IP 地址与 DNS 名同样可用。通过 AISIX_CLOUD_DPMGR_BASE_URL 设置，或在 Helm Chart 中使用 api.dpmgrBaseURL。参见On-Premises 部署。

0.7.0​

发布日期： 2026 年 7 月 31 日

此版本让 AISIX 网关能够为 REST API 的 OpenAPI 3.x 文档中所描述的受支持操作生成 MCP 工具，无需另外部署 MCP 服务器。该能力在开源 AISIX 网关和 AISIX Cloud 中均可使用，由网关调用该 API 并注入所配置的凭证。MCP 服务器还新增了限定到单个服务器的按调用方限流。AISIX Cloud 增加了审核流程，可要求服务器在对调用方可见之前先获批准。此外，每个模型现在即使没有配置也会有上游截止时间，用量记录也把上游耗时与调用方实际等待的时间区分开来。

行为变化​

  • 用量事件的延迟字段被重命名以明确其作用范围，并新增一个字段记录调用方侧的等待。latency_ms 改为 upstream_latency_ms，ttft_ms 改为 upstream_ttft_ms，两者仍以单次尝试为范围。upstream_ttft_ms 现在从该次尝试开始处度量，而不是从请求进入处度量，因此可以与它旁边的延迟直接比较。新增的 downstream_latency_ms 以整个请求为范围。在 OpenTelemetry 导出中，span 属性 aisix.ttft_ms 改为 aisix.upstream_ttft_ms，并新增 aisix.downstream_latency_ms，因此任何读取这些名称的仪表盘或告警都需要更新。控制面同时接受新旧两种名称，因此由 AISIX Cloud 托管的网关无需改动。参见指标与日志。
  • 未配置超时的模型不再没有上界。新增部署级的 upstream.timeout_ms，默认 6000000，即 6000 秒，适用于既未设置 timeout 也未设置 stream_timeout 的任何模型。此前这类模型完全没有上游截止时间，因此接受了连接随后不再响应的上游会把请求无限挂住。这个默认值刻意宽松，它是兜底而不是响应性目标。要在部署级恢复此前的行为，设置 upstream.timeout_ms: 0；单个模型可用 timeout: 0 退出。参见配置文件。
  • 模型组上的 timeout 和 stream_timeout 字段此前没有效果，因为成员只会使用自己的取值。它们现在对两者都未设置的成员生效，按成员、模型组、部署默认值的顺序解析。已经携带这些字段的模型组在升级后会开始应用它们。
  • proxy.request_body_limit_bytes 的默认值从 10 MiB 改为 0，即不限制。模型服务提供方能接受的请求大小超过任何固定的网关默认值，因此原本直连模型服务提供方可用的客户端，经由网关反而可能失败。这只在配置文件中缺少该项时生效；文件中显式携带该值的部署保持原值。若要在省略该项的配置上保留限制，设置 request_body_limit_bytes: 10485760。取值 0 此前的含义是"拒绝所有带请求体的请求"，现在的含义是"不限制"。

新功能​

MCP 网关​

  • 开源 AISIX 网关和 AISIX Cloud 都支持以普通 REST API 为后端的 MCP 服务器。把服务器类型设为 openapi 并提供 OpenAPI 3.x 文档，网关就会为每个受支持的操作生成一个 MCP 工具，并把每次工具调用作为一次 HTTP 请求发往该 API。网关持有所配置的凭证，将其注入出站调用，且不会暴露给发起调用的 Agent。参见将 REST API 暴露为 MCP 工具。
  • 生成的工具与来自真实 MCP 上游的工具经过相同的网关控制，包括工具访问策略、限流、安全护栏和用量记录。
  • 在 AISIX Cloud 中，运维可以粘贴 OpenAPI 文档、提供一个由控制面抓取一次的 URL，或通过控制台加载本地文件。每个由 OpenAPI 支撑的服务器都有一个工具页，用于查看生成的工具名和对应操作。
  • AISIX Cloud 可以要求 MCP 服务器在发布前经过审核。已提交的服务器在审核者接受之前对调用方不可见，而对已上线服务器提出的变更在等待审核期间不会影响正在运行的服务器。参见MCP 服务器上线前审核。
  • 在两个产品中，API Key 都可以携带按服务器设置的限流，因此在某个 MCP 服务器上循环的 Agent 不会消耗同一个 Key 在另一个服务器上的额度。限制可按秒、分钟、小时或天表示，另有并发数，且只对工具调用计量，因此某个服务器的额度耗尽后客户端仍可连接并列出工具。Key 自身的限流仍会叠加生效。参见限流与预算。

超时​

  • 新增两项网关配置 upstream.timeout_ms 和 upstream.stream_timeout_ms，为请求截止时间和流式分块之间的最大间隔提供部署级默认值。截止时间按模型、模型组、这些默认值的顺序解析，并适用于所有端点而不只是聊天路径。参见配置文件。
  • 模型组在控制面和控制台中暴露 timeout 和 stream_timeout，模型上显式的 0 现在会被保留而不再被归一化掉，因此模型可以退出部署级默认值。

可观测性​

  • 用量记录现在上报调用方所等待的时间，度量点在网关把字节交给客户端处，而不是上游分块到达处。在会脱敏响应的输出安全护栏之下，流会被扣留到整个响应扫描通过为止，只有调用方侧的数值反映这段等待。控制台的延迟分位数使用该数值，且只统计成功的请求。参见指标与日志。
  • 用调用方侧延迟减去上游首 Token 时间，就能分离出上游未计入的那段等待，从而在不关联两套系统的情况下看到网关侧开销。对于发生过重试的请求，这个差值还包含此前的各次尝试及其之间的间隔。

审计日志​

  • 审计日志支持在事件的操作者、动作和目标上做全文搜索，支持绝对时间范围、逐页浏览，以及导出当前结果集。参见日志与审计。

部署​

  • 数据面页面在基于清单的安装方式之外提供了真正的 Helm 安装页签，因此可以用已发布的 aisix Chart 安装数据面，其中该环境的连接配置已经填好。

改进​

  • 空闲的网关保持在服务中。就绪端点此前会在配置监听超过五分钟没有事件时报告网关未就绪，而资源不再变化的环境经常如此。在 Kubernetes 上所有副本会在同一时刻越过该阈值，于是完全健康的服务失去了全部端点。就绪现在只报告网关是否正在退出以及配置是否已应用。配置的新鲜度仍可通过健康端点、配置状态端点和 aisix_config_* 指标观察。参见配置状态。
  • aisix 数据面 Helm Chart 的就绪探针现在使用代理端口上的该就绪端点。
  • 超过所配置请求体大小限制的请求，在所有接受请求体的路由上返回相同的错误结构。此前若干 JSON 端点和两个原始请求体端点返回纯文本拒绝，multipart 上传报告一个笼统的客户端错误，而 MCP 和 Agent 端点返回裸的 400。这些端点上的畸形 JSON 现在同样返回标准结构。参见请求头与错误码。
  • Amazon Bedrock 模型现在遵守其所配置的截止时间和连接超时。AWS SDK 此前会用自己的默认值构建自己的 HTTP 客户端，因此 Bedrock 模型的超时并未生效。
  • MCP 上游连接遵守网关的 upstream 连接配置，包括连接超时、TCP Keepalive 和连接池规格。
  • Prometheus 指标占用的内存不再无界增长，指标序列句柄只解析一次并缓存，而不是每个请求都查找一遍。
  • 发布的网关二进制保留符号表，因此针对已发布镜像抓取的性能剖析记录无需特殊构建即可解读。
  • 概览页在其 Top 模型列表中显示完整模型名，不再截断。

修复​

  • 成功的那次尝试所记录的延迟以该次尝试为范围。发生故障转移的请求此前上报的是获胜尝试从请求进入处度量的延迟，因此包含此前所有尝试及重试之间的间隔，使一次成功的故障转移看起来像上游很慢。
  • 重命名 MCP 服务器时会带走其按服务器设置的限流，删除该服务器时也会一并删除。此前这些限制留在旧名字下并静默失效。
  • 审核者编辑 MCP 服务器时会发布它，而不是把它下线。
  • 网关原生支持但公共模型目录未收录的模型服务提供方现在可以重新配置，此前它们在校验阶段被拒绝。
  • 按地域的模型服务提供方 Base URL 与目录中的提供方标识匹配，因此地域相关的默认值可以正确解析，不再落空。
  • 客户端在请求中途断开时不再丢失审计记录。控制面会干净回滚、把断开记录一次，并返回一致的响应体。

0.6.0​

发布日期： 2026 年 7 月 29 日

此版本让调用方可以使用自有身份提供方签发的 JWT 认证，而不必使用网关 API Key。它还把按 Key 维护的 MCP 工具白名单，替换为由环境、团队和 Key 逐层解析的访问策略。此外，重试预算移到模型上，上游请求获得请求上下文变量和客户端请求头白名单，视频生成新增两个模型服务提供方。

行为变化​

  • 重试现在默认开启。此前未设置 routing.retries 的模型组完全不会重试。预算现在按模型、模型组、以及新增的部署级 upstream.retries 默认值 2 的顺序解析，因此从未配置过重试的部署在升级后会开始重试。每次重试都会重新发送完整请求体，并叠加在模型服务提供方自身边缘所做的任何重试之上。要保持此前的行为，在网关配置文件中设置 upstream.retries: 0。参见代理错误与重试。

新功能​

认证​

  • 调用方可以使用 OIDC 提供方签发的 JWT 认证，而不必使用网关 API Key。新增的 oidc_providers 资源按环境保存信任条目，固定 issuer、其接受的 audience 以及 JWKS 位置，网关在请求继续之前校验每一项声明。参见JWT 认证。
  • API Key 通过提供方与 subject 组成的一对与外部身份绑定，因此经 JWT 认证的调用方携带该 Key 的预算、限流、模型访问权限和用量归属。subject 只会针对该 Key 上指定的信任提供方解析，因此第二个受信 issuer 无法声明属于另一个提供方的 subject。
  • JWT 认证作用在网关唯一的认证点上，因此所有代理面都接受它，包括聊天、messages、responses、embeddings、rerank、音频、图像、视频生成、files、batches、fine-tuning、MCP 与 Agent 端点、realtime WebSocket 连接以及透传。
  • 校验默认拒绝：只接受非对称签名算法，必须有过期和 audience 声明，issuer 必须匹配一条已启用的信任条目，运维还可以额外要求 scope 或固定任意嵌套声明。

MCP 访问控制​

  • MCP 工具访问现在由分层策略治理，而不是在每个 Key 上维护白名单。环境默认策略适用于所有调用方，团队策略对该团队成员的 Key 取而代之，Key 再进一步收窄结果。参见MCP 访问策略。
  • 策略可以不授予任何工具、授予指定的一组工具，或授予全部工具。授予全部工具涵盖当前和未来的工具，是一个显式选择而不是默认值。
  • 各层的拒绝模式始终做减法，因此环境级的拒绝会穿透团队策略，并且对本版本之前创建的 Key 同样生效。
  • Key 只能收窄它所继承的权限，永远不能放宽。仍在使用此前 allowed_tools 字段的 Key 行为完全不变，因此升级不会静默授予访问权限。

视频生成​

  • 视频生成端点新增两个模型服务提供方：Runway（runwayml，覆盖 Gen 系列和由 Runway 托管的 Veo）以及 OpenAI Sora（openai）。
  • 内容路由现在使用两种方式交付成品视频。对于返回签名下载 URL 的模型服务提供方，内容路由仍返回 302 重定向，文件会直接从服务提供方存储传输到客户端。OpenAI 要求使用其凭证下载文件，因此网关会使用配置的模型服务提供方密钥获取文件并流式返回，不会将完整文件保存在内存中，也不会向调用方暴露服务提供方凭证。
  • 对于 OpenAI Sora，progress 现在会返回真实完成百分比。不提供百分比的模型服务提供方仍会在任务完成前返回 0，完成后返回 100。
  • OpenAI 是唯一具有内置默认 Base URL 的视频模型服务提供方。其他四个服务提供方仍要求在密钥上配置 api_base。

上游请求头​

  • 模型服务提供方密钥上的默认请求头取值可以引用请求上下文，例如 "x-tenant-id": "${request.api_key.team_id}"，网关按请求渲染它们。内部模型服务因此可以把流量归属到发起调用的团队或 Key，而不必为每个租户单独配置一份模型服务提供方凭证。变量词汇表是封闭的且不含任何机密，变量未能全部解析的请求头会被丢弃，而不是以空值发出。参见上游请求头。
  • 模型服务提供方密钥可以通过一份精确名称或单通配符模式的白名单，把指定的入站客户端请求头转发到上游。它默认为空，且即使在通配符之下也会拒绝来自客户端的认证、传输和网关内部请求头。这让调用方可以在标准端点上传递模型服务提供方特有的请求头或传播 trace 上下文，而不必退化到透传。
  • 视频生成以及 files、batches、fine-tuning 端点此前完全不应用默认请求头，现在每个请求都会携带解析后的集合。

重试​

  • 重试预算现在是模型级配置，作用于所有端点而不只是聊天路径。它按模型、模型组、部署级默认值的顺序解析，并可在控制台中按模型配置。参见代理错误与重试。

连接管理​

  • 网关可以限定已接受的客户端连接在请求之间的最长空闲时间，也可以在尚未产生输出的流式响应上发送心跳注释，使前置代理不会把首 Token 较慢的模型当作已放弃的连接。进行中的请求或流永远不会被中断。参见配置文件。

改进​

  • 日志页支持跨请求的模型、Key、错误消息和标识符做全文搜索，可将当前结果集导出为 CSV 或 JSON，并在时间戳列中与时间一同显示日期。
  • 模型页可按模型名、上游模型或模型 ID 筛选。
  • 模型 ID 字段会提示所选模型服务提供方目录中的模型，同时仍为自由文本，因此目录未收录或刚刚发布的模型仍可手动输入。
  • API Key 和模型服务提供方密钥页面改用紧凑表格，配统一搜索、类型筛选和服务端分页，替换此前的卡片布局。
  • 控制台侧边栏显示控制面构建版本，运维无需登录终端即可确认某个环境运行的是哪个发布版本。
  • aisix-cp Helm Chart 为控制面 API 和数据面管理器新增启动探针，因此首次启动较慢或升级时耗时较长的 Schema 迁移不再被存活探针中断。

修复​

  • 输入安全护栏现在扫描消息文本内容与其结构化内容块的并集。这两者在协议上是相互独立的字段，而模型服务提供方桥接层在存在结构化块时会转发它们，因此此前一个文本无害、载荷藏在块中的请求可以通过所有输入安全护栏，而模型仍然收到该载荷。
  • 失败请求的访问日志行现在会说明失败原因，同时携带可用于筛选或告警的稳定错误类别以及底层原因。此前上游错误、域名解析失败、被回收的连接和未获应答的连接尝试都产生完全相同的日志行。参见指标与日志。

0.5.0​

发布日期： 2026 年 7 月 24 日

此版本新增统一视频生成端点、向外部系统发送通知的预算阈值告警，以及 Anthropic 模型的自动提示词缓存；同时修复重试、超时、限流和用量核算未覆盖所有请求路径的多个问题。

新功能​

视频生成​

  • 新增视频生成端点，通过 /v1/videos 接受文生视频任务、轮询状态并返回成品视频，遵循 OpenAI 视频 API 的三阶段形态。当前映射的模型服务提供方包括 Alibaba Cloud Model Studio、Zhipu AI CogVideoX 和 Volcengine Ark Seedance。
  • 视频请求现在会经过与聊天流量相同的网关控制：模型别名、调用方 API Key 访问检查、客户端 IP 白名单、模型级限流和提示词输入安全护栏扫描。此前，视频流量只能通过透传到达模型服务提供方，不会应用这些模型级控制。
  • 网关不存储任务状态。返回的视频 ID 携带路由信息，因此状态和下载调用可由任意网关实例处理。
  • 视频提交以零 Token 记录在用量日志中。此版本尚未应用按时长计费，因此视频流量不会消耗预算。

安全护栏​

  • 新增 Alibaba Cloud AI Guardrails 类型，调用 MultiModalGuard 服务并执行其建议判定。当服务返回脱敏内容时，网关会将脱敏文本写回请求，而不是直接拒绝。
  • 网关记录 aisix_guardrail_latency_seconds，这是按每次执行统计的延迟直方图，可将安全护栏开销与上游模型延迟区分开。参见指标。
  • Alibaba 安全护栏服务的响应会保留其上游请求 ID，网关会将该 ID 与自身请求 ID 关联，便于跨系统排查。

预算和告警​

  • 预算阈值告警会在支出达到预算配置百分比时通知外部系统。通知渠道支持通用 Webhook 和 Slack。
  • 控制台预算页面现在可以在同一位置管理所有作用域的预算，预算也已纳入 AISIX Cloud Admin API 契约。

提示词缓存​

  • 模型可以启用自动提示词缓存，由网关向符合条件的请求插入 Anthropic 缓存断点。调用方无需修改客户端代码即可获得提示词缓存折扣，也可以在控制台中按模型配置此选项。

用量上报​

  • 当上游未返回用量块时，网关现在会在本地估算 Token 数，而不再记录为零。估算记录会在用量上报和控制台日志页面标记，因此可与模型服务提供方报告的用量区分。
  • aisix_llm_tokens_by_client_total 指标新增 model 标签，并开始为 Responses 端点记录。
  • 内置客户端类型检测覆盖更多编程 Agent，运维人员也可为网关无法识别的客户端添加 User-Agent 映射规则。

部署​

  • 新增 aisix export 命令，可从正在运行的 etcd 存储导出 resources.yaml，作为现有部署切换到独立模式时的初始配置。
  • 对于使用声明式配置且不希望暴露写入 API 的部署，可通过 admin.enabled 设置禁用 Admin 监听器。
  • 状态监听器会报告每个模型的运行时健康状况，无需发送模型请求即可检查上游可达性。
  • 网关会在心跳中报告已应用配置的哈希值，控制面公共规范会公开网关节点和被拒绝资源，从而确认哪些网关已经应用配置变更。参见配置传播。

改进​

  • 模型服务提供方密钥的上游凭证现在可以原地轮换，无需重新创建密钥或重新关联使用它的模型。
  • 控制台模型服务提供方选择器支持搜索，并使用正确的显示名称列出服务提供方。
  • 控制台日志页面会显示完整上游错误消息，不再截断；上游筛选器也不再提供不属于上游的模型组。
  • 日志查询窗口会遵循组织的用量保留设置，不再使用固定范围。
  • 控制面会报告请求被拒绝的原因，而不是返回通用失败。
  • Admin API 写入路径已弃用，推荐使用声明式配置。此版本中它仍可使用。请改为在 resources.yaml 文件中声明动态资源，或通过 AISIX Cloud Admin API 管理它们。

修复​

  • retries 设置现在适用于流式聊天请求；此前独立的流式代码路径不会重试。
  • 对 Azure 模型，stream_timeout 现在按文档限制分块间隔，不再限制整个响应，因此耗时较长但健康的流不会被提前截断。
  • 连接失败会报告底层传输原因，而不是通用上游错误；连接层也开始应用显式限制，不再依赖库默认值。
  • 调用方提供的 cache_control 标记在 OpenAI 到 Anthropic 的桥接过程中会保留，因此使用 OpenAI 客户端访问 Anthropic 模型时仍能获得提示词缓存折扣。
  • 合议成员和评审模型子调用会在后端未报告用量时进行估算，避免合议请求少报 Token。
  • 透传隧道会执行请求正文中指定模型的限流。
  • 组分发会应用每个路由目标自身的模型限流和客户端 IP 白名单，而不再只检查组入口。
  • 每次尝试的错误消息不再截断到 256 个字符，使上游故障在日志中保持可读。
  • 将凭证交换为短期 Token 的服务提供方，其已签发 Token 缓存会按完整凭证建立键，因此密钥轮换会立即生效，无需等待旧 Token 过期。
  • 控制台 Pod 会挂载可写缓存目录，修复 Helm 部署中图片请求可能无限挂起的问题。
  • Playground 只接受控制台会话，个人访问 Token 无法再通过它消耗模型服务提供方配额。

0.4.0​

发布日期： 2026 年 7 月 16 日

此版本引入基于角色的访问控制、自定义角色和环境范围内的管理权限，增加基于状态码的路由故障转移，并通过延迟直方图和更丰富的失败诊断扩展可观测性。

新功能​

访问控制​

  • 组织可以定义自定义角色，按资源类型授予细粒度 read 和 write 权限，替代固定的所有者、管理员和成员划分。
  • 环境范围内的访问权限允许成员管理单个环境，而不授予组织范围内的权限。
  • SCIM 组到角色映射会根据身份服务提供方的组成员身份自动分配角色。
  • 控制面对每个 Admin API 请求执行这些权限检查。

路由​

  • fallback_on_statuses 可将选定的上游 HTTP 状态码纳入重试和故障转移，使 408、409 等服务提供方特定的临时状态码尝试其余目标，而不是直接返回调用方。

可观测性​

  • 分桶的首 Token 时间和端到端延迟直方图支持为服务级目标计算 p90、p99 等延迟分位数。详见指标。
  • 网关会在 Chat、Messages 和 Responses 端点的失败请求中采集请求体，并通过保留结构的截断限制大型载荷。
  • 新的 /status/config 端点会报告已加载的可观测性配置，网关也会发出配置指标。

部署​

  • 独立模式可以从 resources.yaml 加载资源，使网关无需控制面或 etcd 即可运行。

改进​

  • AISIX Cloud Admin API 现在暴露缓存策略、可观测性导出器和限流。
  • 控制台可以为定价目录中没有的模型设置价格覆盖项，使其用量仍能计费。
  • API Key 和限流列表支持分页与搜索。
  • 安全护栏配置错误现在会记录服务提供方的错误响应体，便于排查问题。
  • 阿里云内容安全护栏表单会显示 output_fail_open 选项。

修复​

  • 监控模式的输出安全护栏不再延迟或关闭流式响应。
  • aisix_deployment_state 指标现在根据目标的服务状态派生。
  • SCIM POST /Users 会返回持久化后的身份，而不是回显身份服务提供方的载荷。

0.3.1​

发布日期： 2026 年 7 月 9 日

此维护版本增加 SCIM 目录同步，并改进可观测性、核算、On-Premises Playground 访问和控制面可靠性。

新功能​

  • SCIM 2.0 目录同步可以通过新的 /scim/v2 端点，从 Okta、Microsoft Entra ID 等任意 SCIM 2.0 身份服务提供方自动预配和取消预配组织成员。

改进​

  • 网关构建现在会在 Server 响应头、aisix --version 输出和控制台显示的数据面版本中报告发布版本，不再报告静态构建版本。
  • 按客户端统计的 Token 指标现在包含计入缓存的 total 序列。当前指标目录请参见指标。
  • 健康状态变化时会发出部署冷却指标。
  • 安全护栏管理 API 现已加入 AISIX Cloud Admin API 契约。

修复​

  • 每个代理响应现在都包含 x-aisix-request-id 响应头，用于关联日志和用量事件。
  • Anthropic 提示词缓存 Token 现在会计入原生 /v1/messages 和 /v1/responses 端点的 Token 限流。
  • 单个格式错误的遥测事件不再阻止同一用量批次中的其它事件投递。
  • 启用 AISIX_PLAYGROUND_ALLOW_PRIVATE_IPS 后，On-Premises 控制台 Playground 可以访问私有或内部 LLM 端点。
  • 登录现在接受部署自身的 Origin 和对应的回环 Origin，并为限流或不受信任 Origin 的尝试返回更明确的消息。
  • 成员列表分页不再在视图加载后很快跳回第一页。
  • 控制面重启不再产生无害的重复约束错误日志。

0.3.0​

发布日期： 2026 年 7 月 9 日

此版本引入 MCP 网关和 Agent 网关，扩展代理 API 与安全护栏目录，并增加基于指标的路由。

新功能​

MCP 网关​

  • 新的聚合 /mcp 端点使用一个 AISIX 调用方 API Key 代理多个上游 MCP 服务器。
  • 上游 MCP 服务器成为一等资源，支持在控制面和控制台中注册、完整 CRUD、启用或禁用以及配置上游超时。
  • 工具访问控制将每个调用方 API Key 限定到指定 MCP 工具。
  • 上游认证支持 API Key 和 OAuth 2.0 客户端凭证。
  • MCP 工具调用与模型流量使用相同的限流、预算以及输入和输出安全护栏，同时发出用量事件和访问日志。

Agent 网关​

  • 新的 Agent 网关代理由控制面和控制台管理、作用域为组织的 A2A Agent。
  • allowed_agents 字段将每个调用方 API Key 限定到指定 Agent。

API​

安全护栏​

路由​

  • 多目标模型支持最低成本、最低延迟和最低负载目标选择。
  • 条件路由可按标签或元数据选择目标，通配符别名可路由 provider/* 等模型名称。
  • 粘性加权路由支持 A/B 测试和灰度发布。

流量控制与 API Key​

  • 调用方 API Key 生命周期控制可以设置过期时间、禁用 Key，或通过单次操作完成轮换。
  • 集群限流可以使用共享 Redis 存储，并在现有每分钟（rpm）和每天（rpd）限制之外增加每秒（rps）和每小时（rph）请求限制。

可观测性​

  • 请求和响应内容采集现在覆盖 Embeddings、Rerank、Images 和 Audio。

控制台​

  • 可以在控制台中管理 MCP 服务器，并在限流、预算和安全护栏视图中配置 MCP 治理。
  • 可以按组织配置用量日志保留时间。

改进​

  • 容器镜像以非 root 用户运行，并通过 CAP_NET_BIND_SERVICE 文件能力绑定端口 80 和 443。
  • 控制台提供统一、可筛选的模型视图，并在创建模型时使用单一模型类型选择器。
  • 路由目标可通过拖动重新排序，最低成本目标会显示每个目标的成本标记。
  • 成员和团队列表支持分页。

修复​

  • 缓存和限流 Key 按环境划分作用域，共享 Redis 存储不会混合不同环境的状态。
  • 透传端点现在会为成功和失败请求发出用量事件，并归因到调用方 API Key。