OmniRoute 路由器后端Router Backends与内嵌服务架构解读双轴模型、ServiceSupervisor 生命周期与 Bifrost 兜底路由【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute本文以仓库内架构决策记录 docs/architecture/ROUTER_BACKENDS.mdADR版本 3.8.43为骨架展开。OmniRoute 在单一网关进程中既内嵌可被监督的后台子进程9router、cliproxy、bifrost、dario 等又在/api/v1/relay/chat/completions上提供可切换的中继路由后端ts/bifrost/auto。很多开发者容易把内嵌服务与路由后端混为一谈本指南将澄清这两个正交轴并结合src/lib/services/与routingBackend.ts的真实实现讲清注册表契约、进程监督生命周期、状态码语义、回环保护以及如何用环境变量驱动 Bifrost 故障兜底。核心澄清两个正交的架构轴在深入代码之前必须先建立 ADR 反复强调的核心心智模型一个引擎的角色由两个彼此独立的轴共同描述二者被编码进注册表的RouterBackendDefinition中绝不应合并成一个引擎列表来讨论生命周期轴Axis A—— 引擎如何运行in-process运行在 OmniRoute Node 进程内原生 TS 管线supervised由 OmniRoute 通过ServiceSupervisor安装/启动/停止/健康检查的本地子进程之后作为provider 连接被消费externalOmniRoute 仅向其 HTTP 端点转发但不管理的引擎通过环境变量配置 base URLdisabled已注册但不可选。选择轴Axis B—— relay 是否把请求分发给它RelayRoutingBackend ts | bifrost | auto类型定义在 src/app/api/v1/relay/chat/completions/routingBackend.ts。最常见的错误是把内嵌服务与路由后端当成同一张清单。实际上它们不是一个supervised引擎9router / cliproxy是被原生管线消费的 provider 连接而不是另一个 relay 分发后端bifrost恰好相反 —— 它是一个 relay 分发后端历史上仅以external方式存在。这一区分正是嵌入式服务仪表盘管理 sidecar 进程与路由策略面板决定流量走向在架构上彼此解耦的根本原因。引擎注册表单一事实来源ADR 约定domain/routing/routerBackends.ts实现随 PR #5868 合入会一次性声明每个引擎的生命周期、能力、服务标识、默认端口、健康配置与遥测支持消费方通过getRouterBackend(id)、listRouterBackends()、listRouterBackendsByCapability(cap)查找引擎而不再对每个 sidecar 硬编码特判。在 ADR 的快照里五类引擎的契约如下BackendLifecycleService轴 ARelay backend轴 BHealth默认端口tsin-process—tsnative——bifrostexternal¹—¹bifrost/auto/health—cliproxysupervisedcliproxy—provider/v1/models83179routersupervised9router—provider/api/health20130vibeproxyexternal——provider adapter/v1/models—¹ ADR 记录Bifrost 晋升为supervised内嵌服务可经/api/services/bifrost/安装/启动的进展由 PR #5817 跟踪在合入前 Bifrost 只能通过BIFROST_BASE_URL以external方式访问。需要说明的是当前仓库代码树已先于 ADR 快照演进SERVICES[]中已能看到 Bifrost 的监督条目见下文因此该未来工作在较新版本中实际已落地。capabilitieschat、responses、streaming、tools、vision、oauth-backed、dashboard-embed、model-sync、native-hot-path让调用方按引擎实际能做什么过滤而不是按 id 写死分支。仓库中可见其落地雏形src/lib/services/serviceBackends.ts已把 9router、cliproxyapi 映射为对应的受监督工具9router、cliproxy并各自声明了 provider 插件清单模板格式openai、执行器default、modelsUrl: /v1/models、passthroughModels: true等。Axis A 深挖内嵌服务受监督进程进程注册与启动装配受监督进程的注册表在 src/lib/services/bootstrap.ts 的SERVICES[]中声明。ADR 编写时该数组今日只有9router、cliproxy而当前代码树已扩展为五个条目每条声明了tool、port、healthPath、healthIntervalMs多为 5s、stopTimeoutMs多为 15s、logsBufferBytes5_242_880 ≈ 5MB 环形日志缓冲与needsApiKey9router端口与健康路径均从 provider 插件注册表src/lib/services/providerPlugins/registry.ts解析而非内联字面量注释注明这是 #7333 Phase 1 的迁移结果插件缺失会在 bootstrap 时直接抛错cliproxy健康路径/healthz默认端口来自CLIPROXY_DEFAULT_PORT8317mux/healthbifrost/v1/models—— 印证 Bifrost 监督化已实际合入dario/health注释说明其 503 degraded 是未添加 Claude 账号前的预期状态。bootstrapEmbeddedServices()对每个条目做三件事查询 version-manager 行未安装则跳过、按需生成 API Key、构造并注册ServiceSupervisor随后监听stateChange进程进入running时调度模型同步scheduleServiceModelSync进入stopped/error时停止同步并markAllUnavailable若持久化的autoStart为真则自动start()。ServiceSupervisor 生命周期生命周期管理者在 src/lib/services/ServiceSupervisor.ts其ServiceConfig与状态联合类型定义在 src/lib/services/types.ts状态机not_installed | stopped | starting | running | stopping | error外加一个正交的HealthState healthy | unhealthy | unknownstart()通过内部withLock串行化所有操作 → 置starting→ 若开启probeBeforeSpawn先探测端口 →spawn()子进程 → 将 stdout/stderr 逐行灌入 ringBuffer.ts 的环形缓冲 → 启动HealthChecker→ 在waitForHealthy()中轮询健康超时上限为healthIntervalMs * 3stop()先停健康轮询再killChild()—— 先 SIGTERM超时stopTimeoutMs后升级 SIGKILL已停止时为幂等 no-op崩溃识别handleExit以CRASH_FAST_THRESHOLD_MS 5000判定快速崩溃并给出明确错误子进程的error事件如 ENOENT / 不可执行二进制也会把状态从starting拉回error防止健康轮询永远打一个死端口端口采纳#6205probeBeforeSpawn开启时若目标端口已被一个健康实例占用监督者会采纳该进程解析 OS pid置adoptedtrue若端口被占但不健康则直接给出清晰错误而不是 EADDRINUSE 堆栈。被采纳进程因非spawn()产生、没有管道日志面板会保持为空——这是ServiceStatus.adopted字段存在的原因。为什么独立进程而不是进程内 SDKADR 的答案很明确进程隔离让每个 sidecar 的安装/启动/停止/健康/日志可以被独立控制也让 loopback 派生守护spawn-guard得以生效。把 in-proc 适配器建模属于未来工作——未来会通过native-hot-path能力标志表达而不是现在给某个 sidecar 开特例。/api/services/tool/…生命周期路由契约ADR 强调下面的状态码是按状态/动词/路径特定设计的——这是契约本身不是实现不一致调用条件状态码POST .../startservicenot_installed409preconditionPOST .../stop已停止200幂等 no-opGET .../statusOK200live ?? row ?? unknownPOST .../startspawn 失败503transientGET .../status/.../stop未捕获异常500GET /api/services/x/logs未知工具x404Service x not foundGET .../status?revealkey缺少X-Reveal-Confirm: yes403仅 9router任意/api/services/*调用方非 loopback / 私网403 LOCAL_ONLY所有错误体都由createErrorResponse()统一塑形为{ error: { message, type }, requestId }其中type由状态码推导500→server_error、404→not_found、409→conflict其余invalid_request是可供机器处理的关键判别字段消息则经sanitizeErrorMessage()预脱敏对应 Hard Rule #12。loopback 守护是 403 最常见的来源/api/services/被列入LOCAL_ONLY_API_PREFIXES见 src/server/authz/routeGuard.ts管理策略在鉴权之前就拒绝任何非 loopback / 非私网调用方——因为这些路由会派生子进程Hard Rules #15/#17。因此通过公网隧道触达这些端点会得到 403这是设计使然而非缺陷。Axis B中继路由后端分发侧只有 relay 代理路径/api/v1/relay/chat/completions才会选择分发后端主入口/api/v1/chat/completions从不consultingroutingBackend.ts。逻辑全部集中在 src/app/api/v1/relay/chat/completions/routingBackend.ts。选择逻辑与默认值resolveRelayRoutingBackend()第 54–63 行是一个全局环境变量开关读OMNIROUTE_RELAY_BACKEND或RELAY_ROUTING_BACKEND合法集合为{ts, bifrost, auto}未显式设置时若 Bifrost 已配置且启用则默认auto否则默认ts。三种模式的行为差异模式行为bifrost强制Bifrost 失败 → 硬502不兜底auto先试 Bifrost失败/进入冷却后静默落到原生管线ts/ 兜底后原生open-ssetranslator/executor 管线shouldTryBifrost(backend, config)第 65–70 行是总闸仅当config?.enabled backend ! ts时才可能走 Bifrost。冷却按baseUrl维度管理实现在bifrostCooldown.ts每次baseUrl失败即进入冷却。兜底响应头与机器可读原因码自动兜底会通过响应头把事实暴露给调用方第 99–104、106–134 行getRoutingFallbackHeader()当backend auto enabled时置bifrost头稳定原因码集合RoutingFallbackReasonCodebifrost-cooldown、bifrost-error、bifrost-ineligible、bifrost-provider-unknowngetRoutingFallbackReasonHeader()从遗留的X-Routing-Fallback细节字符串中切出前缀 token如剥离 cooldown 的; remainingms后缀作为可机器处理的原因码。从relay 级全有或全无到按请求门控ADR 记录在release/v3.8.43上选择是relay 级全有或全无的——不存在按 provider 或按请求的引擎互换。按请求门控由 sidecar-manifest 工作引入PR #5869 manifest、PR #5870shouldTryBifrostForRequest让auto只把 manifest 中有资格eligible的 provider 经 Bifrost 路由。当前代码树中该函数已经存在第 72–97 行请求体携带字符串model时通过lookupProviderSidecar(model)查询该模型的 provider 是否有资格走 sidecarbackend bifrost强制放行auto下无资格/未知 provider 则返回tryBifrost: false与对应原因。有资格判定由 provider 插件清单的sidecar字段给出——如serviceBackends.ts中 9router/cliproxyapi 的sidecar: { eligible: false, reasons: [runtime provider] }这类运行时 provider 不会被转发给 Bifrost。Bifrost 的监督化从 external-only 到可自启值得单独展开的是 Bifrost 的身份变迁它是 ADR 轴模型的绝佳例证ADR 快照期Bifrost 只是externalrelay 后端只能经BIFROST_BASE_URL访问监督化#5817尚在推进当前代码树bootstrap.ts已含 Bifrost 监督条目端口取自BIFROST_PORT/BIFROST_DEFAULT_PORT健康路径/v1/models并配套 src/lib/services/installers/bifrost.ts路由配置层的自洽getBifrostRoutingConfig()第 27–52 行在BIFROST_BASE_URL未设置时会查询getSupervisor(bifrost)若其状态为running则自动把 base URL 解析为http://127.0.0.1:port。也就是说监督实例一旦起来原生 relay 无需任何额外环境变量就能把流量指向它。该函数同时定义了 Bifrost 路由相关的完整环境变量面环境变量语义默认值BIFROST_BASE_URL外部 base URL设置后跳过监督探测无BIFROST_ENABLED总开关0禁用启用BIFROST_API_KEY/OMNIROUTE_BIFROST_KEY转发用的 API Key无BIFROST_TIMEOUT_MS转发超时须为正整数才生效30000BIFROST_STREAMING_ENABLED流式开关0关闭启用BIFROST_PORT监督实例端口覆盖默认默认端口Dashboard 集成与轮询契约服务仪表盘通过src/app/(dashboard)/dashboard/providers/services/hooks/useServiceStatus.ts每5 秒轮询一次GET /api/services/tool/status返回{ tool, state, pid, port, health, installedVersion, latestVersion, updateAvailable, autoStart, … }。当前没有共享的 availability-context provider——每个组件按工具各自调用该 hook。在!res.ok时 hook 目前只抛出裸HTTP status把响应中的error.type字段映射成人性化说明被登记为一个 UX 改进项而非契约变更。架构后果与治理收益ADR 在文末总结了这条契约对长期演进的意义这三点也是评审新引擎时最实用的检查清单新引擎只需在ROUTER_BACKENDS注册一次消费方通过能力查询自动获得支持无需新增 per-id 分支它是服务还是路由后端由lifecycle字段回答而不是看它的 id 恰好出现在哪张清单里Bifrost 监督化#5817与原生热路径迁移#5670都应建立在这份共享契约上而不是继续对每个 sidecar 做特判。源码指引docs/architecture/ROUTER_BACKENDS.md —— 本文依据的 ADR 原文含 #5670/#5603/#5817/#5868 等上下文编号src/app/api/v1/relay/chat/completions/routingBackend.ts —— Axis B 的全部实现后端解析、按请求门控、兜底原因码src/lib/services/bootstrap.ts —— Axis A 的SERVICES[]注册与启动装配src/lib/services/ServiceSupervisor.ts —— 子进程生命周期、采纳机制、快速崩溃与 SIGTERM→SIGKILL 升级src/lib/services/types.ts ——ServiceState/HealthState/ServiceStatus状态契约src/lib/services/serviceBackends.ts —— provider 插件与受监督工具的映射、manifest 模板src/server/authz/routeGuard.ts ——LOCAL_ONLY_API_PREFIXES/api/services/的 loopback 守护来源src/lib/services/installers/bifrost.ts 等 installers —— 各 sidecar 的 spawn 参数装配src/lib/services/providerPlugins/registry.ts —— 9router 端口/健康/生命周期配置的插件化来源。一句话收束全篇把生命周期怎么跑与分发角色流量归谁分开建模再用一个注册表把两者同时声明出来是 OmniRoute 在不把 sidecar 特判写得到处都是的前提下将原生 TS 管线、受监督子进程与外部引擎统一治理的架构核心。【免费下载链接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 352 providers (150 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 550 contributors项目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考