OctaFuse Gateway 2.18.0 重点改进了 MCP 客户端接入和供应商粘性绑定管理。
配合已完成对接的 OAuth 授权服务器，用户可以在支持 OAuth 的 MCP 客户端中登录并授权，无需手动填写 API Key。管理员可以按用户或应用查看、撤销授权，并从请求日志追踪调用来源。
路由后台现在可以直接查看供应商的绑定分布和用户明细，支持调整绑定有效期、逐条解绑或批量清除。流式请求也改进了超时判断，避免上游持续发送心跳却没有实际内容时长时间等待。
01｜MCP 接入：登录授权，按应用管理访问
将 MCP 服务接入外部 Agent 时，现在可以通过 OAuth 完成登录授权。用户在客户端发起连接后，前往业务账户系统登录并同意授权，再由客户端使用独立的访问令牌调用 MCP 服务。
这些令牌与用户的 API Key 分开管理：只允许访问 MCP，不能用于聊天、模型列表等其他接口；调用费用计入令牌所属的网关用户。管理员可以在「OAuth 访问令牌」中按应用或用户查看、撤销授权，用户详情页也能查看对应记录。请求日志会标明调用来自哪个 OAuth 应用，便于追踪用量和排查问题。
如何启用
入口在 MCP 服务 → 客户端接入与授权。打开「OAuth 2.0 授权登录（可选）」，填写授权服务器地址并保存。地址须使用 HTTPS，本机开发允许 HTTP localhost。同一页的「接入指南」提供 API Key 和 OAuth 两种方式，以及 ChatGPT 连接器、Cursor、VS Code、Claude Code 和 Codex 的接入步骤。
启用前，需要准备已与网关完成对接的 OAuth 授权服务器。 OctaFuse Gateway 负责 MCP 服务访问与令牌校验，不提供登录和授权服务器。业务账户系统需要通过网关的 Admin API 签发、轮换访问令牌，不能仅填写一个登录页地址。对接边界见 MCP OAuth 架构说明。
在 MCP 服务页配置授权服务器，向客户端提供 OAuth 接入指引。
访问令牌默认 1 小时有效。过期后，客户端可通过授权服务器刷新令牌；是否需要重新登录，取决于客户端和授权服务器的处理。关闭上述设置会关闭 OAuth 授权发现；如需使已签发的令牌失效，应在「OAuth 访问令牌」中撤销。
02｜供应商粘性绑定：看清分布，直接调整
供应商粘性让同一用户在同一模型、路由组和协议下，优先复用上次成功的供应商，有助于保持缓存连续性。这一版补上了绑定的可视化管理：从路由页打开「Provider 粘性」，即可查看分布、定位用户并处理绑定。
调整绑定有效期
在「配置」中启用粘性，并选择 1 小时（默认）、2 小时、6 小时或自定义有效期。设置以路由池为单位生效，覆盖该池关联的所有入口。
按路由池配置粘性开关和绑定有效期。
查看供应商分布
「分布」按优先级展示各供应商的权重、有效绑定数和全池占比，方便确认用户当前分配在哪些供应商上。点击绑定数，可以直接进入该供应商的绑定明细。
查看各供应商的绑定数与占比，并跳转到对应明细。绑定数代表绑定记录数，不等于请求量或独立用户数。
定位用户并解绑
「明细」展示用户、供应商和剩余有效时间，支持按供应商筛选，以及按邮箱或用户 ID 精确查询。需要让某个用户重新选路时，可以直接解绑对应记录；需要整体重新分配时，可以在「其他」中批量清除本路由池的有效绑定。
从绑定明细定位用户，查看剩余有效时间并手动解绑。
解绑后，用户的下一次请求会按现有路由策略重新选择供应商，仍可能选回原来的供应商。批量清除也不会修改粘性开关或有效期配置。
03｜流式请求：心跳不再延长内容等待
部分上游会持续发送 SSE 注释心跳，却迟迟没有实际内容。现在，首包、空闲和首事件超时只认可带内容的 SSE 事件，注释心跳与空行不再延长等待。
默认情况下，等待首个有效事件超过 60 秒，且仍有未熔断的候选上游时，网关会尝试下一个候选。最后一个可用候选由首包超时兜底，保留更长的等待机会。等待响应头也有独立的超时处理，避免请求一直停留在没有响应的上游。
故障转移日志同时补充了候选上游、失败原因和熔断状态等信息，便于判断请求在哪一步失败、是否继续尝试了其他上游。
04｜请求详情可视化
请求日志详情改为「请求入站 → 路由与转换 → 上游尝试 → 响应结果 → 用量与记账」的流程展示，并用时间线呈现各次上游尝试及故障转移。点击阶段或某次尝试，可查看请求参数变化、上游状态、失败原因和记账信息，排障时更容易定位问题。
改造前，请求信息、耗时和原始数据平铺展示，追踪故障转移需要在 JSON 中查找各次尝试。
改造前：数据分散在多个面板，请求经过了哪些步骤不够直观。
改造后，请求流程、耗时分布和记账摘要集中展示。发生故障转移时，还能直接看到哪次尝试失败、何时切换，以及后续上游的处理结果，再按需展开对应阶段的详情。
改造后：从请求入站到用量与记账一目了然。时间线展示第一次尝试返回 429 后，网关切换到另一个上游并成功的过程。点击图片可查看原图。
05｜其他更新
- Gemini 签名兼容：Gemini 原生入口遇到历史思考签名无效的特定 400 错误时，会清洗可处理的签名，并向同一上游重试一次。
- MCP 调用校验：拒绝 JSON-RPC 批量数组请求，避免绕过按次限流。上游返回空响应或不符合 MCP 结构的工具结果时，按失败处理且不扣费；补充资源模板列表查询，当前返回空列表。
- 路由列表布局：按可用宽度调整分区，分开展示状态、权重、粘性和参数，方便查看配置。
- 模型与供应商目录：新增以下预设，导入后仍需配置对应供应商和路由。
升级须知
从 2.17.0 升级到 2.18.0，需先执行数据库迁移 0034 和 0035，再更新服务。 从更早版本升级时，应按编号执行全部尚未应用的迁移。
- 备份数据库。
- 使用 v2.18.0 的 migrate 镜像应用待执行迁移；手动执行时，先执行 0034，再执行 0035。
- 滚动更新同版本的 Proxy 和 Admin。
0034 支持粘性绑定的用户明细，0035 支持独立的 OAuth 访问令牌及请求日志关联。缺少 0034 会导致新版粘性绑定写入失败，缺少 0035 会导致新版请求日志写入失败。D1、Postgres 和 MySQL 均需执行对应迁移，具体操作见 0034 迁移说明 和 0035 迁移说明。
完整变更见 GitHub Release v2.18.0 和 更新记录。
如果 OctaFuse 对你的项目有帮助，欢迎在 GitHub 上点一个 Star 支持，也欢迎提交 PR。我们也在寻找对项目感兴趣的兼职或全职伙伴。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
OctaFuse Gateway 2.18.0 focused on improving MCP client access and supplier sticky binding management.
In conjunction with the OAuth authorized server that has completed the docking, the user can log in and authorize the MCP client that supports OAuth without having to manually fill in API Key. Administrators can view, revoke and trace the call source from the request log by user or application.
The route backstage now has direct access to the supplier's binding distribution and user details to support the adjustment of the binding period, article by article, or batch removal. Fluid requests also improved the judgement of timeout to avoid long waiting periods for sustained heart beats upstream without actual content.
01 |MCP Access: Access authorization, application management access
The login authorization can now be completed by OAuth when the MCP service is connected to the outside Agent. After the client initiates the connection, the user goes to the OPS to log in and agrees to authorize the client to call the MCP service using an independent access token.
These tokens are managed separately from the user 's API Key: access is allowed only to MCP and cannot be used for other interfaces, such as chats, model lists, etc.; call costs are charged to the user of the gateway to which the token belongs. The administrator can view and revoke the authorization by application or user in OAuth Access Cards, and the corresponding records can also be viewed on the user details page. The request log will indicate which OAuth application to call to facilitate tracking of usage and routing.
How to Enable
Access to MCP service access and authorization. Opens "OAuth 2.0 Authorization Login (optional)" to fill in the authorized server address and save it. The address must be HTTPS, which is allowed to develop HTTP localhost. The "access guide" on the same page provides both API Key and OAuth access steps for ChatGPT connectors, Cursor, VS Code, Claude Code and Codex.
Before enabled, you need to prepare the OAuth authorized server that has been connected to the gateway. OctaFuse Gateway is responsible for MCP service access and token verification and does not provide login and authorization servers. The OP system needs to issue and rotate access tokens through Admin API at the gateway, and cannot fill in only one login address. A description of the MCP OAuth structure for the interface.
Configure authorized servers on the MCP service page to provide OAuth access guidance to clients.
Access to token is valid by default for 1 hour. Upon expiry, the client can refresh the token through the authorized server; re-entry is required depending on the client and the processing of the authorized server. Closing the above-mentioned settings closes the OAuth authorization to discover; if the issued token is to be invalidated, it should be removed from the "OAuth access token".
02 | vendor viscosity binding: clear distribution, direct adjustment
cache continuity is facilitated by the supplier ' s viscosity, which gives the same user priority to the previous successful supplier under the same model, route group and agreement. This version is supplemented by bound visualization management: Open "Provider sticker" from the route page to view distribution, locate users and process bindings.
Adjust the binding period
Enables viscosity in Configure and selects one hour (default), two hours, six hours or custom validity. Sets are effective in the form of a route pool, covering all entry points associated with the pool.
Configure a sticky switch and binding period by route pool.
View vendor distribution
The distribution presents the weights of suppliers, valid binding numbers and pool-wide ratios by priority, facilitating the identification of suppliers for which users are currently assigned. Clicking on a fixed number allows direct access to the supplier ' s bind details.
See the ratio of binding figures to the respective suppliers and jump to the corresponding breakdown. The binding number represents the binding number of records and is not equal to the number of requests or independent users.
Position users and untie them
"Specific" displays users, suppliers and remaining valid times, supports vendor-by-supplier screening, and accurate queries by mailbox or user ID. When it is necessary for a user to reroute, the corresponding records can be removed directly; when it is necessary to redistribute the entire body, the effective binding of this route pool can be removed in " other " lots.
The user is located in detail from the binding to see the remaining valid time and to untie it manually.
Once untied, the next user ' s request will re-select the supplier in accordance with the existing route strategy and may still be re-selected. Batch removal does not modify a sticky switch or validity configuration.
03 Fluent Request: Heart beat without extension waiting
Part of the upstream will continue to send SSE note heartbeats, but the actual content is delayed. Only SSE events with content are now accepted by the package, free time and event timeout, and no longer is the note heartbeat or empty line waiting.
By default, the gateway will try the next candidate when the first valid event exceeds 60 seconds and there are still unmelted candidates upstream. The last available candidate is covered by the first package of timeout, with longer waiting opportunities. An independent timeout is also handled at the waiting point to avoid requests staying upstream without response.
The failure logs complement information on upstream candidate, cause of failure and melting state to determine where the request fails and whether other upstream attempts continue.
04 Details of Request Visible
The details of the request log are shown in the "Request to enter the station route and convert the upstream attempt to respond to the results of the response volume and recording" process, and the time line is used to display the various upstream attempts and failure shifts. Clicking at a stage or at a time to see changes in the requested parameters, upstream status, reasons for failure and accountancy information, making location easier when you are handicapped.
Before retrofitting, requests for information, time-consuming and raw data parlour are displayed, and tracking down down failure movements requires searching for attempts in JSON.
Pre-adaptation: Data are spread over multiple panels and what steps are requested that are not intuitive.
Following the modifications, the request process, time-consuming distribution and accounting summary were centrally displayed. When a failure is transferred, it is also possible to see directly which attempt failed, when to switch, and subsequent upstream treatments, with details of the corresponding phase as needed.
Remodified: from the request for entry to the amount to be recorded. The timeline shows another upstream and successful process after the first attempt to return 429. Click the picture to see the original picture.
05 Other updates
- Gemini Signs Compatibility: When the Geneni Native entrance encounters a specific 400 error in the invalidity of a historical thought signature, it washes a handleable signature once to the same upstream retry.
- MCP Call Validation: Refusal of JSON-RPC batch array requests and avoidance of circumvention of sub-rate limit. If you return an empty response upstream or a tool result that does not conform to the MCP structure, it is processed unsuccessfully and free of charge; the list of supplementary resource templates is queryed and the current empty list is returned.
- Route list layout: adjust the partition to the width available, show the status, weight, viscosity and parameters separately, and facilitate the viewing of the configuration.
- Models and supplier catalogues: The following presets have been added and will still require matching suppliers and routers after import.
Information on promotion
The upgrade from 2.17.0 to 2.18.0 requires database migrations 0034 and 0035 before services are updated. When an earlier version is upgraded, all unapplied migrations should be numbered.
- Backup database.
- Migrate mirror application using v2.18.0 is to be moved; when manually executed, do 0034 and then do 0035.
- Scroll up the same version of Proxy and Admin.
0034 User Details for sticky binding, 0035 for independent OAuth access tokens and request log connections. The absence of 0034 leads to the failure of writing of the new sticky binding and the absence of 0035 leads to the failure of writing of the new request log. D1, Postgres and MySQL are required to perform a corresponding migration, as described in the 0034 and 0035 migration instructions.
Complete changes can be found in GitHub Release v2.18.0 and update records.
If OctaFuse helps your project, please click a Star support on GitHub and submit a PR. We are also looking for part-time or full-time partners interested in the project.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.