OctaFuse Gateway 2.3.0：供应商粘性绑定，让缓存命中更稳定

OctaFuse Gateway 2.3.0 正式发布。

一次请求通过故障转移（Failover）找到可用上游后，后续请求能否继续访问同一家供应商（Provider），会直接影响缓存命中率、会话连续性以及供应商侧状态的稳定性。

2.3.0 为路由池（Route Pool）新增了供应商粘性（Provider sticky）：网关会记住用户上次请求成功的供应商，并在绑定有效期内优先复用。管理后台（Admin）还提供绑定分布查看、单个用户解绑和整个路由池失效等运维能力。

一句话看懂 2.3.0：

路由策略负责首次选路，供应商粘性记住上次成功的结果，让后续请求持续命中同一上游，从而提高缓存命中率。

01｜供应商粘性：记住上次成功的上游

供应商粘性是一项默认关闭的路由池能力。它的关键在于：粘性绑定的判断先于四种路由策略 。只要为路由池开启粘性，无论配置的是 hash_affinity、weighted_random、weight_priority 还是 weighted_round_robin，绑定有效期间，用户请求都会优先访问上一次分配且请求成功的供应商。只有尚未建立绑定，或原有绑定失效后需要重新选路时，层内策略才会介入。这样一来，整个路由分组就能获得更稳定的缓存命中表现。

运行规则：

没有有效绑定时，仍按优先级（priority）和层内策略选路。
请求成功后，将本次成功的上游目标（Upstream Target）与用户、模型、路由组和协议建立绑定。
绑定有效时，先于常规优先级分层和层内策略尝试该目标。
每次请求成功都会延长绑定有效期；默认空闲有效期为 3600 秒。
429、401 / 403、5xx、524 或网络错误会解绑并继续故障转移。

绑定数据存储在 D1、Postgres 或 MySQL 中，可以在不同的 Cloudflare Worker 隔离实例和多个 Node.js 实例之间共享。如果存储出现异常，网关会自动回退到常规路由，不会因为粘性功能不可用而阻断推理请求。

02｜它与 `hash_affinity` 有什么区别

hash_affinity 是默认的无状态层内策略：对于相同的用户、模型、路由组和协议，它会稳定地计算出一个首选供应商。

供应商粘性记录的则是上一次真正请求成功的上游目标：

可以跨越优先级层级，优先尝试已绑定的目标。
可以在空闲有效期结束后自动过期。
可以在供应商发生故障时自动解绑。
可以通过 sticky_epoch 让整个路由池的旧绑定统一失效。

两者并不冲突。没有有效绑定时，网关仍会使用 hash_affinity，或该层配置的其他策略完成选路。

03｜拓扑视图提供完整的绑定运维能力

路由数量较少时，可以用摘要视图（Summary）快速浏览；当一个模型接入多个供应商，并按不同优先级拆成多层时，切换到拓扑视图（Topology）会更清楚地展示请求入口、路由组、优先级层和故障转移顺序。

在拓扑视图（Topology）的路由组或路由池节点中，点击供应商粘性状态芯片（关闭时显示 Sticky · Off）打开设置后，可以：

启用或关闭供应商粘性，并设置空闲有效期。
查看当前有效绑定数，并对比各上游目标的绑定占比与路由权重（weight）。
按用户邮箱或用户 ID 查找绑定。
只解绑一个用户，让其下一次请求重新选路。
一键使整个路由池的绑定失效，让所有用户在下一次请求时重新选路。

拓扑视图还增强了策略来源和优先级层级的展示，便于在一张图中核对配置、实际尝试顺序和故障转移规则。

04｜`route_trace.sticky`：知道绑定为何命中或失效

请求日志（Request Logs）现在可以记录：

json 复制代码

{
  "sticky": {
    "lookup": "hit",
    "attempted_target": "route-target-id",
    "result": "kept"
  }
}

lookup 描述绑定读取结果，例如 hit、miss、expired、invalid_epoch 或 invalid_circuit。
attempted_target 表示本次优先尝试的上游目标。
result 描述绑定被保持、清除、新建或重绑，也可能记录存储错误。

运维时，可以把这些字段与缓存读取令牌数、上游故障转移次数结合起来观察，判断供应商粘性是否真正提升了提示词缓存的连续命中效果。

05｜路由策略 ID 与界面名称正式对齐

2.3.0 将两个策略 ID 改为与管理后台的展示名称一致：

2.2.0 ID	2.3.0 ID
`cache_affinity`	`hash_affinity`
`fixed_order`	`weight_priority`

另外两个 ID 保持不变：weighted_random、weighted_round_robin。

旧 ID 没有兼容别名。 外部自动化、ROUTE_STRATEGY、模型 route_policy、路由池和优先级层配置都必须使用新名称；写入旧 ID 会返回 400。

写在最后

Octafuse Gateway 2.3.0 这次升级主要针对缓存命中高要求的场景加入了粘性绑定的优先路由规则，用户可以利用粘性 + 其他任何一个路由分配策略都能让用户在粘性时间窗内保持对单一供应商的访问，以实现高缓存命中，大大降低 Token 的消耗！

开源地址：github.com/OctaFuse/oc...

欢迎 Star 支持，您的支持是持续更新迭代的动力！