AI Gateway

2周前发布 41 00

ai-gateway 是一款运行在 Cloudflare Workers 上的私有 AI API 网关。它将分散在不同供应商、API 密钥、额度与模型别名上的计算容量,聚合为一个统一的、兼容 OpenAI 或 Anthropic 协议的请求入口。

所在地:
fongap-labs
收录时间:
2026-10-31
AI GatewayAI Gateway

ai-gateway 是一款运行在 Cloudflare Workers 上的私有 AI API 网关。它将分散在不同供应商、API 密钥、额度与模型别名上的计算容量,聚合为一个统一的、兼容 OpenAI 或 Anthropic 协议的请求入口。

AI Gateway

这里的“私有”指自托管模式,仅供个人或可信的小团队使用。客户端只需配置一个网关地址和一把网关密钥,即可屏蔽上游复杂的配置细节。

核心机制:容量分层与自动切换

网关通过三层容量架构(Tier)来管理请求路由,确保日常调用的韧性与成本可控。请求会严格按照 Tier 1 到 Tier 3 的顺序尝试,前一层耗尽或不可用时,才会流向下一层。

  • Tier 1(日常主力):免费或近似免费的 API 容量。系统会重点保障其持续可用性。
  • Tier 2(次级容量):订阅权益(如 Claude Pro/Max、ChatGPT/Codex 等,通常经 OAuth 接入)。它作为补充,而非第二个通用的密钥池。
  • Tier 3(最终兜底):按量计费的付费 API 容量。仅在前两层均不可用或额度耗尽时才会触发,确保用量可预测。

当某一路径遇到限流(如 HTTP 429 状态码)时,网关会暂时冷却该节点,并自动将请求转交至下一层级的可用节点。冷却期结束后,系统会进行单次探测以尝试恢复。在响应流开始输出前,客户端不会感知到上游的切换过程。

安全边界:密钥隔离与分组授权

为了防止上游凭证泄露并实现精细的权限控制,ai-gateway 设计了严格的安全机制。

  • 密钥隔离:客户端仅持有网关分发的访问密钥。所有上游的真实 API Key 均加密保存在 Cloudflare Secrets 中,不会暴露给终端应用。
  • 分组授权:网关支持多个访问分组(如 AIR、PRO、MAX、ULTRA、AGENT)。每把网关密钥在创建时,必须绑定一个允许调用的逻辑模型列表(通过 AIG_ACCESS_MODELS_* 变量配置)。
  • 互不继承:五个访问分组相互独立。若某个分组的模型列表为空,该密钥将无法调用任何模型。

适用场景与能力边界

明确工具的使用边界有助于避免架构设计上的误用。

适合的场景:

  • 个人或小团队拥有多个免费额度或多把 API Key,希望统一调用入口。
  • 需要同时兼容 OpenAI 与 Anthropic 协议客户端的自托管环境。
  • 希望在本地控制 API 调用成本与系统稳定性。

不适合的场景:

  • 面向公众的 SaaS 服务或对外售卖 API 的商业平台。
  • 需要复杂的计费、转售或按独立用户计量的多租户系统。
  • 需要企业级组织管理或基于角色的访问控制(RBAC)。

部署与验证流程

部署过程依赖 Node.js 环境,需确保版本 ≥ 22.18.0。整个过程通过命令行工具链完成,主要步骤如下:

  1. 环境准备:在 Cloudflare 控制台创建一个 KV 命名空间,并记录其 32 位十六进制 ID。准备好上游的节点配置 JSON 和凭据 JSON。
  2. 获取代码:克隆仓库并安装依赖。
    git clone https://github.com/fongap-labs/ai-gateway.git
    cd ai-gateway
    npm ci
    npm run cf:login
    
  3. 配置校验:在部署前校验节点配置,确保格式正确。
    npm run config:check -- --tier1 <tier1.json> --secrets <secrets.json>
    
  4. 执行部署:将网关推送到 Cloudflare Workers。
    npm run deploy
    

部署完成后,可通过以下命令验证服务状态:

  • 检查健康状态:curl https://<你的网关>/health -H "Authorization: Bearer <YOUR_MAX_OR_ULTRA_KEY>"。返回 200 且 nodes_usable 大于 0 表示配置有效。
  • 检查模型列表:curl https://<你的网关>/v1/models -H "Authorization: Bearer <YOUR_GATEWAY_KEY>"。返回非空列表说明分组授权配置正确。

客户端接入方式

接入时,只需将客户端的 base URL 指向网关,并将 API Key 替换为网关访问密钥。模型名称需使用网关定义的“逻辑模型名”(如 code-pro),而非上游的真实模型名。

  • OpenAI 协议(Chat Completions / Responses):
    设置 OPENAI_BASE_URL=https://<你的网关>/v1,OPENAI_API_KEY=<YOUR_GATEWAY_KEY>。
  • Anthropic 协议(Messages):
    设置 ANTHROPIC_BASE_URL=https://<你的网关>,ANTHROPIC_AUTH_TOKEN=<YOUR_GATEWAY_KEY>。

进阶配置与协议兼容性

网关的核心行为由四类环境变量控制,它们分别存放在普通变量或 Secret 中:

  • 节点定义(AIG_TIER{1,2,3}_NODES_01..10):定义 provider、地址与模型映射。
  • 上游凭据(AIG_TIER{1,2,3}_CREDENTIALS_01..10):按节点 ID 绑定的真实 Key,仅保存在本机,严禁提交至 Git。
  • 网关访问密钥(AIG_ACCESS_KEY_*):分发给客户端的鉴权凭证。
  • 逻辑模型列表(AIG_ACCESS_MODELS_*):该分组允许调用的模型名称集合(CSV 格式)。

在协议支持方面,网关原生支持 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages。系统通过规范化中间表示(IR)矩阵,实现了这三种协议之间的两两互转。

所有重试与回退操作共享同一套时间预算,max_attempts 为请求级的硬性上限。一旦流式输出开始,网关将锁定当前上游节点,不再进行切换,以保证数据流的完整性。

常见故障排查

  • Node 版本报错:运行 node -v 检查,确保版本 ≥ 22.18.0。
  • KV 命名空间 ID 被拒:确认输入的 ID 为严格的 32 位十六进制字符串。
  • /v1/models 返回空列表:检查当前使用的网关密钥对应的 AIG_ACCESS_MODELS_* 环境变量是否已正确配置且不为空。
  • 鉴权失败:确认请求头格式严格为 Authorization: Bearer <密钥>,且密钥字符串与安装时生成的完全一致。

相关导航