OctaFuse Gateway 2.9.0：用户限流控制、自定义转发头与管理后台升级

当一个用户同时通过网站、Agent 和自动化任务访问 OctaFuse 时，网关不仅要统一转发请求，还要控制用户与不同应用的调用频率、满足供应商对请求头的要求，并让管理员更快看清流量和异常情况。

OctaFuse Gateway 2.9.0 围绕这些日常治理场景，增加用户与 Key 双层限流、自定义上游请求头、Key 级分析和入口 Host 记录，并升级仪表盘、用量分析与操作反馈。已有应用不需要修改请求地址或鉴权方式。

一句话看懂 2.9.0：

既能分别限制用户和单把 Key 的调用频率，也能按路由补充上游请求头，并在管理后台更快定位流量与异常。

01｜用户与 Key 双层限流

一个用户往往不止有一把 API Key。只限制单把 Key，无法控制这个用户的总请求量；只限制用户，又可能让某个异常应用占满全部流量。

2.9.0 增加两层独立的 RPM 限流：

• 用户合计 RPM：限制该用户所有 API Key 在过去 60 秒内的请求总数。
• 单 Key RPM：只限制当前这把 API Key 在过去 60 秒内的请求数。

例如，可以把用户合计上限设为 120 RPM，再把网页应用和自动化任务的 Key 分别设为 80 RPM、30 RPM。任何一把 Key 都不能超过自己的上限，所有 Key 的总量也不能超过用户的共享上限。

两层限制分别配置：留空表示不限，0 表示拒绝所有计次请求，其他值必须是非负整数。窗口按当前时刻向前滚动 60 秒，不会在自然分钟切换时清零。

超限后，Gateway 返回：

429 gateway.rate_limited
Retry-After: <等待秒数>

客户端可以根据 Retry-After 决定何时重试。GET /v1/me 不参与两层计数，因此超限后仍能查询额度状态。

管理员可在用户（Users）详情页设置用户合计 RPM，并在下方查看各 Key 的限流状态；用户列表会直接显示用户限流，密钥（API Keys）页面用于设置单 Key 上限。管理界面和 Admin API 都会拒绝负数与小数。

限流解决的是“可以调用多少”，用量分析解决的是“请求来自哪里”。当某个用户的费用或请求量突然增加时，只看用户汇总通常不够。2.9.0 新增按 API Key 汇总的管理接口：

GET /api/admin/analytics/keys
  ?user_id=<USER_ID>
  &start_date=<START>
  &end_date=<END>

接口会按时间范围返回每把 Key 的请求数、Token 用量、用户计费、供应成本、成功率、模型数量和最后活跃时间。门户或运营系统可以据此把用户总量继续拆到网站、Agent、自动化任务等具体应用。模型分析接口还支持 api_key_id，用于查看单把 Key 在不同模型上的用量和费用。

除了汇总数据，管理后台还可以通过 api_key_id 筛选请求日志。日志同时记录入口 Host（Ingress Host），用于标明请求实际访问的域名；当同一套 Proxy 同时提供正式、测试或多个业务入口时，可以据此判断某把 Key 的请求从哪个入口进入。入口 Host 只用于观测，不是域名白名单，也不参与访问控制。

每次成功写入用量时，Gateway 还会同步更新 Key 的 last_used_at，方便识别长期未使用的密钥。

02｜自定义转发请求头

有些第三方供应商除了 API Key，还要求请求携带固定的 HTTP Header。例如，OpenRouter 等平台可能使用 HTTP-Referer 标识来源网站，并用 X-Title 显示应用名称。

2.9.0 可以为每条路由单独配置这类转发请求头。在路由（Routes）编辑器中添加 Header 名称和值后，Gateway 会将它们随请求发送给上游。

路由的自定义参数分为两部分：左侧 Header 作为 HTTP 请求头发送，右侧参数合并到上游 JSON 请求体，两者不会相互混入。

如果通过 Admin API 管理路由，这些值保存在 custom_params.headers 中。它们只作为 HTTP Header 发送，不会混入 JSON 请求体。

鉴权和传输相关的 Header 仍由 Gateway 控制。Authorization、X-API-Key、X-Goog-API-Key、Host、Content-Type、Content-Length、Cookie 以及连接管理类 Header 均不能通过路由覆盖，避免破坏供应商鉴权或请求转发。

路由中的“请求体”是另一项配置，用于提供 temperature 等 JSON 默认参数。客户端显式传入同名参数时，以客户端值为准，因此请求体默认值不能用来强制限制参数上限。

保存路由后，可以在调试台（Playground）的“实际上游请求”中检查最终请求头和请求体。自定义 Header 会单独标记，API Key 等敏感内容会自动脱敏。

调试台会标记来自 custom_params 的自定义 Header，并同时展示脱敏后的鉴权信息和最终上游请求体。

03｜管理后台升级

新版仪表盘（Dashboard）把请求量、成功率、平均响应时间、用户计费金额、趋势、热门模型、活跃用户、近期请求和错误信息集中到同一页面。运营人员可以先从总览判断流量是否正常，再进入模型、供应商、用户或可靠性分析继续排查。

新版仪表盘集中展示核心运行指标和流量趋势，并支持按常用或自定义时间范围分析。

模型、供应商和用户用量页面现在可以同时展开多条明细，横向比较不同对象的数据，不必反复收起和切换。多处保存、删除及异常反馈也统一改为页面通知和确认对话框，减少浏览器弹窗对操作流程的打断。

04｜其他更新

除上述重点功能外，2.9.0 还包含以下目录、部署和兼容性更新：

场景	本次变化
供应商接入	新增 SiliconFlow 国际站模板，明确区分国内站和国际站账号、端点；导入和编辑界面增加平台主页或 API Key 页面入口。
模型目录	新增 gemini-3.8-flash；为 DeepSeek V4 Pro、DeepSeek V4 Flash 补齐工作日官方高峰时段；修正 23 个阿里云百炼模型的 USD 与 CNY 预设价格。
价格展示	多条路由优先级、权重相同时，目录选择当前综合倍率更低的路由展示折扣；实际请求的选路策略不变。
Cloudflare 部署	PROXY_CUSTOM_DOMAIN、ADMIN_CUSTOM_DOMAIN 支持逗号分隔多个域名；空白项会忽略，重复项会去重，原有单域名写法继续有效。
Node / Docker 部署	修复管理后台位于反向代理之后时，创建或修改集成密钥可能被同源校验误判为 403 的问题；真正的跨站写操作仍会被拒绝。
计费日志	Chat、Responses、Anthropic Messages 和 Gemini 采用同一套结构化计费记录流程，用量、错误和上游请求 ID 的整理方式保持一致；现有计费口径不变。
图片编辑（Images Edits）	转发单张参考图时使用 image，多张参考图时使用 image[]，提升对不同 OpenAI 兼容上游的适配性。

已经导入数据库的模型和供应商不会被静态目录自动覆盖。需要使用新模型、国际站模板或更新后的价格时，请先核对现有配置，再重新导入或手动调整。

升级到 2.9.0

本版本包含数据库迁移 0028，为用户和 API Key 增加限流配置，为请求日志增加入口 Host，并创建对应索引。D1、PostgreSQL 和 MySQL 使用相同字段语义。

建议按以下顺序升级：

1. 备份目标数据库。
2. 运行 2.9.0 的 migrate 镜像或对应命令，应用迁移 0028。
3. 将 Proxy 和 Admin 滚动升级至 2.9.0。
4. 验证用户合计 RPM、单 Key RPM、Retry-After 和 /v1/me 豁免。
5. 核对入口 Host、Key 最近使用时间和按 Key 筛选结果。
6. 通过调试台验证自定义请求头，再回归 Chat、Responses、Messages、Gemini、Images 和 Audio 路由。

迁移新增字段都允许为空，未配置 rate_limit 的存量用户和 Key 会继续保持不限流。回退旧版本时可以保留新增列。

限流窗口默认保存在每个 Proxy 进程或 Cloudflare isolate 的内存中，不写入数据库。Node 单进程下接近精确；多进程、多副本或 Cloudflare 多 isolate 环境中，各实例不会共享窗口，因此属于软上限。进程重启后，当前窗口也会重新计数。需要跨实例严格一致的全局限流时，仍需增加集中式限流能力。

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

小结

2.9.0 让共享网关的流量治理和日常管理更加完整：双层 RPM 分别约束用户总量和单把 Key，自定义转发请求头满足不同供应商的接入要求，Key 级分析、入口 Host 和新版仪表盘则让流量与异常更容易定位。升级时需要应用迁移 0028，并根据业务为用户和 Key 设置合适的请求频率；已有应用不需要改变调用方式。

• OctaFuse 官网
• GitHub 仓库

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