OctaFuse 2.15.0 实操：MCP 聚合、向量接口与目录同步怎么配

如果你正在用 OctaFuse Gateway 做 AI 网关，2.15.0 是一个偏「基建整合」的版本。这篇教程把更新说明里最值得动手的三件事拆开讲：怎么把多个 MCP 服务收拢成一个网关入口、怎么让向量 Embeddings 走现有的路由和记账体系，以及怎么手动对照官方目录同步模型参数。适合已经部署过 OctaFuse、希望统一管理 Agent 工具与向量接口的读者。

一、先弄懂：为什么要把 MCP 聚合到网关

MCP（Model Context Protocol）服务的问题在于「一个服务一个地址、一套鉴权头」。Agent 想同时用三个工具源，就得写三份配置；上游换个地址，所有 Agent 都得跟着改。2.15.0 的思路是让网关当「工具前置代理」：管理员在后台接入多个远程 MCP 服务，Agent 侧只需要一个网关地址加一个用户 API Key。

几个设计细节值得注意：

• 协议用的是无会话的 Streamable HTTP，鉴权直接复用用户 API Key，Agent 拿不到上游真实地址和鉴权头。
• 工具名会变成 {slug}__{原名} 的形式，避免来自不同服务的同名工具打架；提示词和资源也从同一入口读取。
• Agent 看到的目录是「管理员审核过的快照」，不是上游实时清单——上游新增了工具，Agent 那边不会立刻冒出来，必须先经过审核。

这种「先审核、后暴露」的策略，适合不想让 Agent 被上游未预期变更「投喂」的团队。代价是管理员需要定期手动同步。

二、MCP 接入与审核：具体操作步骤

接入一个新的远程 MCP 服务，流程如下：

• 第 1 步：填写地址。在后台「MCP 服务」页点添加，填远程地址和静态请求头；也可以直接粘贴常见客户端的 MCP 配置，系统会自动解析出地址和请求头。注意：本地进程、旧版 SSE 和 OAuth 这三种方式不会被导入。
• 第 2 步：同步目录。系统会拉取上游的工具、提示词和资源，并与当前快照对比出新增、变更和移除。
• 第 3 步：逐条审核。新增条目默认是停用状态，需要逐条或批量启用；已有条目的说明一旦变更，也要重新审核。同步失败的服务会在列表标红，上游地址和请求头默认脱敏显示，避免在界面泄露密钥。

给 Agent 配置时不用手写文档：MCP 服务页提供「接入指南（Connection guide）」，填好 Proxy 地址、选择全部服务或单个服务后，可以直接复制 Cursor、VS Code、Claude Code、Codex 的配置或 curl 验证命令，内容里只含 <YOUR_API_KEY> 占位符。

想确认 Agent「实际看到什么」，用「对外目录测试（Test exposed catalog）」：填 Proxy 地址和用户 API Key，页面会真实请求 /mcp 或 /mcp/{slug}，支持原始 JSON 和按服务分组两种视图。这个测试只查询目录和协议能力，不会真的执行工具，可以放心在上线前跑。

三、MCP 计费与日志：按成功调用计 1 个单元

MCP 走的是「按调用计费」，规则设在网关侧，而不是上游怎么扣就怎么转：

• 只有 tools/call 会计费，每次成功调用固定计 1 个请求单元；调用前会检查余额。
• 向用户收费用标准价 × 用户倍率；供应成本按标准价 × 供应倍率。用户倍率设为 0 即免费，但供应成本仍会记录，方便内部核算。
• 服务可设默认单价，单个工具可以覆盖；上游调用失败不扣费。

日志方面，MCP 调用以 provider_id=octafuse-mcp 写入请求日志，可以按 MCP 调用筛选。对外 GET /v1/tools/pricing 接口新增了 mcp 段，包含已启用 MCP 工具的计费单元和单价，前端门户可以直接读取展示，不用自己维护价格表。

四、向量 Embeddings：两条协议共用一套基础设施

2.15.0 之前，向量请求没有统一入口。现在两类协议都能走网关已有的路由池、故障转移、限流和记账：

请求体原样透传，Gemini 批量请求仅改写每个 requests[].model。计费只按输入 token，上游没返回用量就不计费。识别向量模型的方式是 output_modalities 含 embedding 标识；GET /v1/models 默认不返回向量模型，需要时加 kind=embedding。

后台也做了配套：模型、路由、供应商新增 embedding 类型，模型表单只保留输入价；OpenAI、Azure OpenAI、ZenMux 的全能力 Base 和 Gemini Base 模板会自动派生向量端点。目录预设包括 text-embedding-3-small/large、text-embedding-ada-002、gemini-embedding-2，以及阿里云的 qwen3.7-text-embedding、text-embedding-v4。调试台与路由快速测试提供 OpenAI、Gemini 两种向量请求模板，会显示向量个数、维度和用量，方便验证路由是否通。

特别提醒两点：

• 官方确认支持 OpenAI 兼容 embeddings 的平台（火山方舟、阿里云百炼、腾讯混元、百度千帆、智谱 GLM、Mistral、OpenRouter、SiliconFlow 等）已在供应商模板补上端点；未核实的需要自己在供应商里填 embeddings 或 models.embed 端点。
• 除阿里云外，预设里的人民币价是「美元 × 7」的占位换算，不是官方人民币刊例。如果你的成本按人民币结算，上线前一定要核对实际费率。

五、模型类型拆分与官方目录同步

此前的「音频」类型把 ASR（语音识别）和 TTS（语音合成）混在一起，2.15.0 起拆为两个独立类型，新建模型时直接选，不再有二级「音频能力」开关。GET /v1/models 的 kind 新增 asr 和 tts，旧的 kind=audio 保留为兼容别名，后台旧链接会落到 ASR。保存模型时如果计费模式和模态矛盾（比如 TTS 但输出不含 audio），会被拒绝，Admin 与 Proxy 共用同一套判定规则。

更有用的是「检查官方更新」按钮，位于模型页和供应商页右上角。它只在你点击时运行，不会后台自动同步——已导入的数据永远不会被自动改动，这点对线上稳定性很重要。

同步面板（Sync with official catalog）按厂商分组，逐项并排对比名称、上下文窗口、最大输出、介绍、发布日期、模态和价格，每一项可选「采用官方」或「保留当前」。三条边界要记住：

• 价格默认保留：价格直接影响计费，默认选「保留当前」，应用前会提示涉及的启用路由数。
• 不清空字段：官方目录没给出的字段保持原值。
• 不动其他配置：标签、元数据、路由及价格覆盖都不会被修改。

供应商同步逻辑类似，额外的保护是：已替换成实际值的部署占位符（如 Vertex 的 YOUR_PROJECT_ID、Azure OpenAI 的 YOUR_RESOURCE_NAME）不再提示更新；采用官方时保留已填的项目、资源名和区域；API Key、启用状态和供应商名称绝不被改。官方模板改名或下线后遗留的旧类型会单独列出，可迁移到新类型。

六、配套改动与升级清单

这个版本还有一些影响日常操作的改动：

• Tools 导航重构：原「配置」改为「REST 服务」，MCP 服务紧随其后；调用记录同时包含两类，可按来源和服务筛选。
• 请求追踪：聊天、消息和 Responses 的响应都会返回 X-OctaFuse-Request-Id，与请求日志主键一致，成功失败都带；日志另记录消息结构摘要（按角色汇总字段名和内容类型），不记录消息正文。
• Azure OpenAI 模板：官方 Base 改为带 /openai/v1 的路径，仍用旧地址会提示更新。
• 新增 gemini-4-argon 预设：价格按 2026-12-01 起的 Standard 刊例，输入 4、输出 20 / 每百万 Token，缓存读取 $0.20，只支持隐式缓存。

升级到 2.15.0 需要执行数据库迁移 0030，新增 mcp_servers 和 mcp_server_items 两张表（D1、Postgres、MySQL 脚本语义一致）。建议顺序：备份数据库 → 用 v2.15.0 的 migrate 镜像执行 0030 → 滚动更新 Proxy 和 Admin。新 Proxy 在表缺失时不会报错，只是 /v1/tools/pricing 的 mcp 字段返回空数组；需要回退时这两张表可以保留。

升级后建议做三项检查：在 MCP 服务页接入上游、同步目录、逐条启用，再用对外目录测试验证 /mcp；抽查 POST /v1/embeddings，并在模型页和供应商页点「检查官方更新」，确认价格仍处于「保留当前」后再决定是否同步；最后对既有主要路由做一轮冒烟测试。

小结

2.15.0 的核心思路是「把散落的入口收进网关」：MCP 从「N 个地址 N 套鉴权」变成「一个网关地址 + 一份审核过的工具快照」，向量 Embeddings 纳入统一路由与记账，官方目录同步则把「要不要跟上官方参数」的决定权留给管理员。对使用者来说，最需要建立的习惯有两个：一是 MCP 上游同步后记得审核，别让默认停用的新工具堵住流程；二是同步官方目录时先看价格项，默认「保留当前」是最安全的选择。把这两点融入日常运维，这套网关能省下不少逐机配置的时间。

本文基于 rss-juejin《OctaFuse Gateway 2.15.0：MCP 聚合、向量 Embeddings 与官方目录同步》深度重写，事实与观点归原作者所有。建议阅读原文。原作者：程序猿DD。发布于 2026-10-15。