发布说明

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

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

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 访问不到任何路由。参见 Passthrough 路由与面向 IDE AI 流量的正向代理。
• 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 侧显式写成 ["*"]。
• Guardrail 拦截 MCP 工具调用时，改为以工具错误的形式作答。 调用在协议层面返回成功，结果上带 isError: true，消息中指出是哪条 Guardrail 生效——绝不回显命中的内容——而不再返回 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 span、一个覆盖全部重试与故障转移的逻辑 client span，以及每次上游尝试各一个子 span，取代了此前"每个用量事件一个扁平 span"的形状。任何以"每个请求一个 span"为前提的用法——span 数量告警、按名字计数——都会看到结构性 span 出现。承载完整属性集的是 attempt span，可用 aisix.attempt_index 识别；结构性 span 只携带 aisix.request_id，SERVER span 的 kind 为 2。另外，调用方的 traceparent 与 tracestate 不再转发给模型服务提供方；运营方为可信上游显式配置的 default_headers 条目仍然有效。
• 文本转语音的延迟改为按首字节计。 /v1/audio/speech 现在边接收边转发合成的音频，而不再整体缓冲，因此播放器可以在首批字节到达时就开始播放，上报的延迟也随之从"到最后一个字节"变为"到第一个字节"。这与此处所有其他流式接口已有的口径一致。

新功能

• Passthrough 路由。 一条路由把一个网关入口——路径前缀、入站 Host 白名单，或两者兼有——绑定到一个上游目标，因此可以把 IDE 或编码 Agent 指向网关，在不改动客户端的前提下对其流量进行审计。Host 匹配在路由之前进行，因此携带原始 Host 送达的正向代理流量可以认领网关同样在用的路径；路径匹配则作为路由器的兜底，因此一条路由绝不会遮蔽网关自身的 API。调用方可以用网关 Key 认证、把 Key 放在你指定的请求头里（从而让 Authorization 留给上游凭证），或者以受源 CIDR 白名单约束的绑定主体身份匿名访问。上游凭证要么由模型服务提供方 Key 注入，要么原样转发调用方自己的凭证——后者下网关自身的凭证绝不会泄漏到上游。可选的设备注入身份请求头会被记录为该请求的终端用户身份，用于按员工归因。请求信封按请求识别——chat、Responses、completions 或不透明——并据此驱动 Guardrail 取文、审计留存与 Token 计量；非 LLM 调用的流量不会产生虚假 Token。SSE 响应逐帧转发。
• 模型组的一致性哈希与优先级层级。 strategy: consistent_hash 通过把请求键哈希到目标环上，将每个会话固定到同一个目标：相同的键始终命中同一个目标，权重决定各目标的份额，而某个目标故障时只有它自己的会话迁移到环上的后继目标，其余键的映射全部保持不变。请求键来自你配置的来源链（hash_on：请求头、Cookie、调用方 API Key 或客户端 IP），默认使用路由键请求头并回退到 API Key。此外，每个目标都可以设置 priority：目标据此划分为若干层，数值越大越优先，只有当某一层内所有目标都失败或被健康状态摘除后，下一层才会收到流量——因此备用池可以在活跃池之后静默待命，而首个发现整层已死的请求也能在层内溢出并成功返回。
• MCP 2026-07-28。 /mcp 与 /mcp/{server} 提供该规范的最终修订版，包含免握手的发现生命周期与无状态传输。已注册的 MCP Server 可选配置 protocol_version，用于固定网关开启上游会话时使用的修订版——这是访问"不再响应旧握手"的 Server 的唯一方式；不配置时网关按此前方式协商，因此既有配置保持不变。两个方向上都是显式选择：网关既不探测也不静默回退，因此版本不匹配会明确失败，而不会悄悄协商到一个你本想排除的版本。
• MCP 匿名访问。 环境可以允许不携带任何凭证的 MCP 客户端访问指定入口，并以你指定的一把 API Key 的身份运行——该 Key 的工具授权、限流、预算与用量归因全部适用。它受一份必填的源 CIDR 白名单约束，需要列出所开放的入口，且聚合入口 /mcp 需要显式开启。携带凭证的客户端仍按正常流程认证；凭证无效时会被拒绝，而不会被降级为匿名服务。
• 面向 /mcp 的 OAuth 2.1 资源服务器发现。 配置了规范资源 URL 并启用了身份提供方后，网关会发布受保护资源元数据，并对未认证的 MCP 请求返回指向该元数据的 WWW-Authenticate 质询，使标准 MCP 客户端能够自行发现到哪里获取 Token。Bearer Token 的 audience 必须包含该 URL。
• Guardrail 可以限定到单个 MCP Server，从而只守护某一个已注册的 Server，而不必守护环境内所有 MCP 流量。Guardrail 现在还会扫描工具的结构化输出，而不只是文本块。
• 关闭时的排空窗口。 收到 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 用量。带拦截或掩码能力的输出 Guardrail 仍走缓冲路径，因为它必须在任何内容到达调用方之前看到完整的转写文本。
• 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 秒。依赖旧边界的仪表盘和 recording rule 需要更新。两套边界现在都可以在 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 指标占用的内存不再无界增长，指标序列句柄只解析一次并缓存，而不是每个请求都查找一遍。
• 发布的网关二进制保留符号表，因此针对已发布镜像抓取的 profile 无需特殊构建即可解读。
• 概览页在其 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 监听器。
• 状态监听器会报告每个模型的运行时健康状况，无需发送模型请求即可检查上游可达性。
• 网关会在心跳中报告已应用配置的哈希值，控制面公共规范会公开网关节点和被拒绝资源，从而确认哪些网关已经应用配置变更。参见配置传播。

改进

• 模型服务提供方密钥的上游 Secret 现在可以原地轮换，无需重新创建密钥或重新关联使用它的模型。
• 控制台模型服务提供方选择器支持搜索，并使用正确的显示名称列出服务提供方。
• 控制台日志页面会显示完整上游错误消息，不再截断；上游筛选器也不再提供不属于上游的模型组。
• 日志查询窗口会遵循组织的用量保留设置，不再使用固定范围。
• 控制面会报告请求被拒绝的原因，而不是返回通用失败。
• 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

• /v1/realtime WebSocket 中继支持 OpenAI 系列和 Azure 服务提供方、浏览器子协议认证以及每会话用量核算。
• 新的 /v1/files、/v1/batches 和 /v1/fine_tuning 端点支持 OpenAI 系列和 Azure 服务提供方，并可归因批处理任务成本。
• Embeddings支持原生 Vertex AI、Gemini、Bedrock Titan 和 Cohere 请求。
• Anthropic Messages支持跨服务提供方的图片、工具使用、工具结果和文档内容块。

安全护栏

• 新增 Lakera Guard、Presidio和 OpenAI Moderation集成。
• PII 检测与脱敏可以在请求和响应体中掩码或阻断敏感数据，包括流式响应和非 Chat 端点。
• 监控模式下的安全护栏匹配会出现在用量事件和控制台 Logs 视图中。

路由

• 多目标模型支持最低成本、最低延迟和最低负载目标选择。
• 条件路由可按标签或元数据选择目标，通配符别名可路由 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。