OctaFuse Gateway 2.11.0：流式请求优化、用户折扣策略与错误契约升级

OctaFuse Gateway 2.11.0 为文本流式请求补齐首包、流中空闲和记账三档保护，并增加可选的首事件超时故障转移。同时，用户级模型倍率支持新的组合策略，代理错误也有了更稳定的判断方式。

一句话看懂 2.11.0：

长流式请求有了明确的等待边界和故障转移策略，用户折扣更容易运营，客户端也能更准确地判断失败原因。

01｜流式请求更稳

在流式请求中，"还在思考"和"已经卡住"从连接状态上看可能非常相似。如果超时时间太短，推理时间较长的模型会被误判；如果完全不设限制，异常连接又可能一直占用资源。

2.11.0 将文本流式请求拆成三个阶段分别保护：

阶段	默认时间	作用
等待首个非空数据块	2 分钟	给长上下文和静默思考留出首包时间
流式传输中的空闲间隔	30 秒	已经开始输出后，限制两次上游数据之间的等待时间
用量记账绝对兜底	10 分钟	避免用量记录长期无法结束

三个时间都可以通过 Proxy 的部署环境变量调整：

bash 复制代码

STREAM_FIRST_CHUNK_TIMEOUT_MS=180000
STREAM_IDLE_TIMEOUT_MS=45000
USAGE_SAFETY_TIMEOUT_MS=900000

配置值使用毫秒。未配置、配置为空或者不是正整数时，Gateway 会回退到默认值。Node、Docker 和 Cloudflare 部署都支持这组配置。

这套保护覆盖 Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini streamGenerateContent。

请求开始输出后，如果上游超过空闲时间仍没有发送新的数据，Gateway 会主动取消上游连接，并将请求日志标记为 incomplete，避免连接长期悬挂。超时并不等于一定不计费：如果 Gateway 在超时前已经取得有效用量，仍可能按实际用量记录费用。

需要注意的是，10 分钟的用量记账兜底并不是客户端请求的最长执行时间。它用于保证后台用量流程最终能够结束，不会阻塞客户端正常接收流式内容。

首个事件超时后自动换路由

除了默认生效的流式生命周期保护，2.11.0 还提供了一项可选能力：上游已经返回 2xx，但迟迟没有产生第一个有效 SSE 事件时，可以放弃当前上游并继续故障转移。

该能力通过 system_config 配置：

text 复制代码

STREAM_FIRST_EVENT_TIMEOUT_MS = 45000
STREAM_FIRST_EVENT_TIMEOUT_ROUTE_GROUPS = default,free

命中超时后，当前上游尝试会按 524 处理，Gateway 随后继续尝试其他可用路由。这项能力独立于默认启用的流式生命周期保护，并且默认关闭；开启后如果没有指定路由组，只作用于 default，配置为 * 或 all 时才会覆盖全部路由组。

首事件超时适用于上述四类文本流式入口，不作用于图片、音频、实时语音和 Agent Tools。如果业务中存在超长静默思考或检索，应先评估真实响应时间，再决定是否开启以及设置多长的等待时间。

02｜用户折扣更灵活

OctaFuse 已经支持按用户、按模型设置计费倍率。2.11.0 进一步增加了倍率组合模式，用于决定用户倍率如何与路由的 Charged 倍率共同计算。

目前支持两种模式：

模式	计算方式	适合场景
`multiply`	路由倍率 × 用户倍率	在路由价格基础上继续叠加用户折扣
`min`	取路由倍率和用户倍率中的较小值	两种优惠不叠加，直接采用更低的一档

例如，某条路由的 Charged 倍率为 0.8，用户倍率为 0.5：

multiply 的最终倍率为 0.8 × 0.5 = 0.4。
min 的最终倍率为 min(0.8, 0.5) = 0.5。

默认仍使用 multiply，与此前版本的计价结果保持一致。只有管理员主动切换为 min 后，已配置用户倍率的请求才会采用新算法。

这一设置会影响 LLM、图片和音频请求的最终用户费用，但不会改变模型目录标准价、供应成本，也不作用于 Agent Tools。没有为当前模型配置用户倍率时，两种模式都保持原有路由价格。

Proxy 会缓存该设置约 30 秒。计价审计 pricing_audit 也会记录本次请求采用的用户倍率、组合模式和最终倍率，方便排查展示价格与实际扣费是否一致。

向门户提供用户专属折扣

公开模型目录 GET /catalog/models 展示的是平台公共价格。如果门户需要在用户登录后显示专属折扣，还需要叠加该用户配置的模型倍率。

2.11.0 新增管理接口：

text 复制代码

GET /api/admin/users/:id/display-discounts

接口需要 users.read 权限，只返回该用户已经配置倍率且当前存在可用路由的模型，也可以通过 route_groups 限定路由组。

门户可先通过 GET /catalog/models 获取公共模型目录，再用该接口返回的结果覆盖对应模型的用户专属折扣。该接口使用管理端身份，不占用用户或 API Key 的 RPM；门户无需持有用户 API Key，也不必为了展示价格去调用面向 Agent 的 GET /v1/models。

03｜错误判断更明确

仅靠 HTTP 状态码，很难准确判断代理请求失败在哪一层。

2.11.0 统一使用响应头标记代理错误类型：

text 复制代码

X-OctaFuse-Error-Code: gateway.no_route

客户端应优先读取 X-OctaFuse-Error-Code，再结合 HTTP 状态码和错误文案处理。错误文案适合展示和记录日志，不建议作为程序分支的固定依据。

几个容易混淆的错误现在可以明确区分：

错误码	HTTP	含义	处理建议
`gateway.model_not_found`	404	请求的模型 ID 不在 Gateway 模型目录中	检查客户端使用的模型 ID
`gateway.no_route`	404	模型存在，但当前协议、操作或路由组没有可用上游	检查请求入口、路由组和活跃上游目标
`upstream.not_found`	404	请求已经到达上游，但上游模型或资源不存在	检查路由中的 `provider_model_name` 和供应商配置

其中，gateway.no_route 在 2.11.0 中由原来的 502 调整为 404，错误文案统一为 No available route。

如果客户端、监控告警或重试规则依赖原来的状态码，需要同步调整，并改为优先按错误码处理。

这套错误契约主要覆盖用户侧的 /v1/* 和 /v1beta/* 代理接口。Admin API 不使用这套响应格式；Agent Tools 的鉴权、额度和限流错误会带统一错误码，但工具自身返回的业务错误目前不一定包含该响应头。

04｜其他更新

2.11.0 同步更新了模型和价格目录：

场景	本次变化
新增图片模型	新增 `gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 预设
新增文本模型	新增 `glm-5.3-flashx` 预设
价格更新	调整 `claude-sonnet-5`、`gpt-5.6-terra` 和 `gpt-5.6-luna` 的 USD / CNY 目录价格

模型目录导入不会覆盖数据库中已经存在的同 ID 模型。需要使用新增模型时，应按需导入并配置路由；已有模型如需采用新的目录价格，应先核对实际供应商价格，再由管理员手动更新。

升级到 2.11.0

本版本没有新增数据库迁移，已完成现有迁移的环境可以直接升级 Proxy 和 Admin。

为了避免新旧 Proxy 使用不同的用户倍率算法，建议按以下顺序滚动升级：

先将所有 Proxy 升级至 2.11.0。
确认旧版 Proxy 已全部退出流量。
再升级 Admin。
全部实例升级完成后，再决定是否将用户倍率模式切换为 min。

默认的 multiply 模式与此前版本一致，不主动修改配置时，用户计费方式不会发生变化。

三档流式保护在升级后会按默认值生效。对于超长静默思考或检索类请求，建议在部署前评估响应时间，必要时调整前文三个环境变量。首事件超时故障转移仍默认关闭，不配置 STREAM_FIRST_EVENT_TIMEOUT_MS 就不会改变现有行为。

升级后建议重点验证：

长流式请求能够正常完成；流式输出中断后，上游连接会被取消，请求日志标记为 incomplete。
如果启用了首事件超时，命中条件的请求能够继续尝试其他路由。
无可用路由时返回 404，并包含 X-OctaFuse-Error-Code: gateway.no_route。
两种倍率模式的展示价格和实际扣费一致，用户专属折扣接口的权限及返回结果符合预期。

升级前可查看 GitHub Release v2.11.0 和完整更新记录。

小结

2.11.0 进一步明确了网关的运行边界：流式请求可以及时收口或切换上游，用户折扣拥有更灵活的组合方式，客户端也能通过统一错误码准确定位问题。这些变化不会改变 OctaFuse 的基本接入方式，但能让长请求、计价运营和故障处理更加可控。

如果 OctaFuse 对你的项目有帮助，欢迎在 GitHub 上点一个 Star。你的关注和反馈，会帮助我们继续完善路由治理、计价能力与自托管体验。