OctaFuse Gateway 2.11.0 为文本流式请求补齐首包、流中空闲和记账三档保护，并增加可选的首事件超时故障转移。同时，用户级模型倍率支持新的组合策略，代理错误也有了更稳定的判断方式。
一句话看懂 2.11.0：
长流式请求有了明确的等待边界和故障转移策略，用户折扣更容易运营，客户端也能更准确地判断失败原因。
01｜流式请求更稳
在流式请求中，“还在思考”和“已经卡住”从连接状态上看可能非常相似。如果超时时间太短，推理时间较长的模型会被误判；如果完全不设限制，异常连接又可能一直占用资源。
2.11.0 将文本流式请求拆成三个阶段分别保护：
| 阶段 | 默认时间 | 作用 |
|---|---|---|
| 等待首个非空数据块 | 2 分钟 | 给长上下文和静默思考留出首包时间 |
| 流式传输中的空闲间隔 | 30 秒 | 已经开始输出后，限制两次上游数据之间的等待时间 |
| 用量记账绝对兜底 | 10 分钟 | 避免用量记录长期无法结束 |
三个时间都可以通过 Proxy 的部署环境变量调整：
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 配置：
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 新增管理接口：
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 统一使用响应头标记代理错误类型：
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。你的关注和反馈，会帮助我们继续完善路由治理、计价能力与自托管体验。