OctaFuse Gateway 2.2.0 发布：让每一层路由都有自己的策略

📝

OctaFuse Gateway 2.2.0 聚焦路由治理：Gemini 流式/非流式收敛为单一 models.generate 配置、Route Pool 每个 priority 层可独立选择路由策略（cache_affinity/weighted_random/fixed_order/weighted_round_robin）、策略 ID 统一为 canonical 名称，并升级 Admin 可视化策略编辑与 Agent Tools Provider 配置入口。

原文：微信公众号《OctaFuse Gateway 2.2.0：让每一层路由都有自己的策略》（作者：DD，2026-08-07）
开源地址：https://github.com/OctaFuse/octafuse-gateway

⚠️ 版本演进（2026-08-07 更新）：本文原为 2.1.0 发布记录，2.2.0 已发布，标题与内容更新为最新口径；2.1 的 Agent Tools 管控内容保留在文末历史章节。

当一个模型同时接入多个账号、多个供应商或多条备用链路时，「先走谁、同层怎么选、失败后往哪里切」不应该是一组藏在代码里的隐含规则。OctaFuse Gateway 2.2.0 把这些决策继续下沉到 Route Pool 的 priority 层，同时统一 Gemini 的流式与非流式路由语义，让配置、执行与日志看到的是同一套结构。

一句话看懂 2.2.0：一套 Gemini 路由，同时服务流式与非流式请求；一个 Route Pool，可以为不同 priority 层选择不同策略。

本次版本还统一了路由策略名称，升级了 Admin 的可视化策略编辑，并重新设计 Agent Tools Provider 的配置入口，让凭证、启用状态与三账本定价更容易核对。

01｜Gemini 路由：从两套配置收敛为一套

过去，Gemini 的 generateContent 与 streamGenerateContent 会以两个 operation 出现在路由配置中。它们在客户端侧确实是两个 action，但从网关治理视角看，通常属于同一个能力、共享同一组上游和故障转移策略。

2.2.0 将公开 Surface 与上游 Target 的配置统一为 models.generate：

非流式请求使用 generateContent
流式请求使用 streamGenerateContent
实际 action 写入 route_trace.gemini.action，排障时依然清晰可见

这意味着路由配置更少、流式与非流式行为更一致，也减少了两套 Pool 长期漂移的风险。客户端 URL 保持不变，现有 Gemini SDK 与调用方式无需调整。

02｜按 priority 层配置策略

Route Pool 原本已经支持 priority 分层：高优先级上游全部失败后，才会进入下一层。但在 2.2.0 之前，一个 Pool 内的所有层共享同一套路由策略。现在，你可以为每个 priority 层分别选择排序方式：

策略	适合场景
`cache_affinity`	稳定命中首选上游，提高 Prompt Cache 命中率
`weighted_random`	按权重随机分配流量，适合灰度与容量分摊
`fixed_order`	严格按固定顺序尝试，适合主备链路
`weighted_round_robin`	按权重轮转，适合更均匀、可预期的流量分配

例如，同一个 Route Pool 可以这样组织：

P0 主力层：使用 weighted_round_robin，在多个稳定账号之间分摊流量
P10 备用层：使用 fixed_order，优先低成本备用，再进入保底上游

如果某一层没有单独设置策略，它会继续继承 Pool、模型或全局配置。你可以只覆盖真正需要差异化的层，不必重复维护整套规则。

03｜策略名称统一，配置即语义

本次版本将策略 ID 统一为更明确的 canonical 名称：

旧 ID	2.2.0 canonical ID
`affinity`	`cache_affinity`
`strict`	`fixed_order`
`round_robin`	`weighted_round_robin`
`weighted_random`	`weighted_random`

2.2.0 不再接受三个旧 ID。 数据库迁移会改写已持久化的配置；如果你有外部自动化直接调用 Admin API 或写入配置，也必须同步使用新名称。

04｜Admin：看得见策略来源，也看得懂 Failover

Routes 页面同步升级了策略编辑体验：

全局、Pool 与 priority 层统一使用可视化策略选择器
每一层都能查看当前生效策略及其来源
Failover 规则可以在配置现场直接查看
Gemini Provider 新配置优先写入单一 models.generate URL 模板
无法安全合并的历史 Gemini 双模板会被保留，并提示人工复核

目标是让运维人员在修改前就能回答：这层现在按什么顺序走？配置从哪里继承？失败后会切到哪里？

05｜Agent Tools Provider：凭证、价格与启用状态放在一起

2.2.0 重新设计了 Agent Tools Provider 卡片，通过卡片与右侧抽屉集中维护 Web Search、Web Fetch、Deep Search 与 AI Detection 的：

Provider 凭证
Standard / Charged / Metered 三账本单价
「仅保存配置」或「保存并启用」
未保存、缺少凭证、服务不可用与亏损定价提示

对于按调用量计费的 Agent 能力，配置是否完整、售价是否覆盖成本、当前 Provider 是否真正启用，都可以在同一处完成核对。

升级前必读

如果此前的路由策略全部继承自全局配置，可以平滑升级到 2.2.0。
如果存在模型、Pool 或 priority 层的独立策略配置，升级期间可能短暂出现因新旧数据不一致导致的请求错误。建议在同一维护窗口内完成数据库迁移，并同步升级 Proxy 与 Admin。

获取 2.2.0：GitHub Release v2.2.0 · 完整 Changelog · 2.2.0 迁移索引

📜 历史章节：2.1.0 Agent Tools 统一管控（2026-08-03 发布）

以下为 2.1.0 发布记录，保留作为版本演进历史。

2.1 的核心：把模型之外的 AI 能力也纳入网关统一管控

过去 AI 网关的更新大多聚焦在模型调用上：如何统一接入 OpenAI、Anthropic、Gemini 等协议，如何在多个 Provider 之间路由和故障转移，如何管理 API Key、预算、Token、成本与调用日志。

但当 Agent 真正进入业务，模型调用只是链路的一部分——它还会搜索网页、抓取正文、做深度检索，甚至调用 AI 率检测等垂直能力。如果这些工具各自维护密钥、价格、账单和日志，系统很快又会回到「每接一个能力，就多一套烟囱」的状态。

新增 AI 率检测工具

2.1.0 新增常用工具 AI 率检测，实现端点：

1	POST /v1/tools/ai-detection

调用方只需提交待检测文本，Gateway 会完成：用户 API Key 鉴权 → 预算预检 → 长文本自动分段 → 调用当前启用的检测引擎 → 汇总整体评分与分段结果 → 成功后记录费用并扣减预算 → 写入统一请求日志。当前已实现腾讯云 TMS 引擎，计费按字符单元计算。

四类 Agent Tools 共用一套运营体系

Web Search：联网搜索
Web Fetch：网页正文抓取
Web Deep Search：搜索与正文读取一体化
AI Detection：AI 生成概率检测

它们统一使用 /v1/tools/* 对外提供服务，并共享用户鉴权、预算、计费、日志与审计能力。客户端只需要一把 Octafuse 用户 Key，不必再直接持有一组搜索服务密钥、一组抓取服务密钥和一组检测服务密钥。

三账本计费

统一为 standard（目录标准价）/ metered（供应侧实际成本）/ charged（用户实际计费），只有 charged 会累加到用户的 budget_spent。运营人员可以清楚看到：上游实际成本是多少？对外目录价是多少？用户最终扣了多少？单次调用留下多少利润空间？

定价预查接口

GET /v1/tools/pricing 只读返回计费币种、工具计费方式、字符计费粒度、供应成本/目录价/用户价。不返回引擎密钥，也不暴露当前 Active 引擎名称。

工程结构

2.1.0 新增共享包 @octafuse/tool-engines，Web Search、Web Fetch、Web Deep Search、AI Detection 的引擎客户端由 Proxy 和 Admin Playground 共同复用。Docker 构建也已纳入该包，并增加 docker-compose smoke workflow。

🔍 GitHub 数据验证（API 实测）

项目	08-03 记录	API 实测（08-07）	判定
Stars	188	234	✅ 4 天 +24%，持续增长
语言	TypeScript	TypeScript	✅
License	AGPL-3.0	AGPL-3.0	✅
创建时间	2026-05-11	2026-05-11（约 3 个月）	✅
最近更新	—	2026-08-06（当日有 push）	✅ 活跃

⚠️ 项目较新（创建约 3 个月，234⭐），版本迭代快（两周内 2.1 → 2.2.0），生产环境接入前建议先看仓库 Issue 与最新 Release。