前言

ai-gateway 是一个基于 Cloudflare Workers + Hono 框架构建的 AI 提供商 API 聚合网关，实现「一个 API 调用所有模型」的聚合能力。它支持多密钥轮询、健康检测、自动故障转移、密钥自动恢复等高级特性，并内置 OpenCode 免费模型，默认开箱即用。整个项目采用 TypeScript 开发，前端使用 Hono 服务端渲染，管理后台为卡片式 UI，支持移动端。

• 项目地址：https://github.com/yutian81/ai-gateway
• 开源协议：Apache 2.0
• Stars：44+

功能特点

技术栈

• 兼容日期：2025-07-01
• 兼容标志：["nodejs_compat"]

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

ai-gateway/
├── src/
│   ├── index.ts               # 入口文件，路由注册
│   ├── types.ts               # TypeScript 类型定义
│   ├── config.ts              # 默认配置
│   ├── storage.ts             # KV 存储层
│   ├── auth.ts                # 认证系统（Session + Bearer Token）
│   ├── proxy.ts               # API 转发核心（密钥轮询 + 健康检测 + 自动恢复）
│   ├── opencode.ts            # OpenCode 官方 API + 公共镜像回退
│   ├── admin.ts               # 管理 API
│   ├── pages.ts               # 前端页面模板（HTML/CSS 服务端渲染）
│   ├── pages.css.ts           # 样式（38KB）
│   └── shared.js.ts           # 前端共享 JS 工具函数
├── worker-proxy/              # 独立代理脚本
│   ├── agentrouter.js         # Agent 路由代理
│   ├── cline.js               # Cline 代理
│   ├── cline-auth.py          # Cline 认证辅助（Python）
│   └── opencode.js            # OpenCode 代理
├── .github/
│   └── workflows/
│       └── deploy.yml         # GitHub Actions 自动部署
├── package.json
├── wrangler.toml
├── tsconfig.json
├── README.md
├── API.md                     # API 完整文档
├── design.md                  # 设计系统规范
├── opencode-cdn.md            # 多 CDN 代理部署指南
└── LICENSE

部署方式一：GitHub Actions 自动部署

这是推荐的部署方式，推送到 main 分支后自动构建部署。

1. Fork 项目仓库

访问 ai-gateway 项目，先给项目点个 ⭐，然后点击右上角 Fork，将仓库克隆到你的 GitHub 账号下。

2. 创建 KV 命名空间

1. 登录 Cloudflare Dashboard
2. 进入 Workers 和 Pages → KV → 创建命名空间
3. 输入名称，例如 AI_GATEWAY_KV，点击创建
4. 记下 KV namespace ID，备用

3. 配置 GitHub Secrets 和 Variables

在 Fork 的仓库中，进入 Settings → Secrets and variables → Actions：

Secrets（密钥）：

Variables（变量）：

如何获取 CF_ACCOUNT_ID： 登录 Cloudflare Dashboard，右上角头像下拉菜单中可见，或从 URL 提取：https://dash.cloudflare.com/ACCOUNT_ID/...

4. 触发部署

在仓库 Actions 页面，找到 Deploy to Cloudflare Workers，点击 Run workflow → Run workflow。

部署流程会自动：

1. 检出代码并安装依赖
2. 生成包含 KV 绑定和管理员凭据的 wrangler.toml
3. 执行 npm run build 构建
4. 通过 Wrangler Action 部署到 Cloudflare Workers

部署成功后，访问 Worker 生成的默认域名（如 ai-gateway.你的用户名.workers.dev），或绑定自定义域名。

部署方式二：Cloudflare Dashboard 手动部署

如果你不习惯用 GitHub Actions，也可以直接在 Cloudflare Dashboard 中手动部署。

1. 创建 Worker

1. 登录 Cloudflare Dashboard
2. 进入 Workers 和 Pages → 创建 → Workers
3. 选择 连接到 Git，授权 GitHub，选择 Fork 的仓库
4. 使用默认构建设置，点击 保存并部署

2. 配置环境变量

部署完成后，进入 Worker → 设置 → 变量和机密，添加以下变量：

OPENCODE_MIRRORS_URL 默认值：

1
2
3

https://opencode.ai.cmliussss.net/zen/v1
https://opencode.fastly.cmliussss.net/zen/v1
https://opencode.gcore.cmliussss.net/zen/v1

[!NOTE]
三个默认镜像 URL 在部署 workflow 中已内置，手动部署时建议一并配置。

3. 绑定 KV

Cloudflare Dashboard 会自动创建 KV 命名空间。进入 Worker → 设置 → KV 命名空间，确认绑定名称为 KV。如果是手动创建的 KV，需要手动添加绑定。

4. 绑定自定义域名

在 Cloudflare Dashboard 中，为 Worker 添加自定义域名（如 ai.你的域名），然后在 DNS 设置中添加相应的 CNAME 记录。

API 接口

公开接口

管理后台接口（Session Cookie 鉴权）

API 转发接口（Bearer Token 鉴权）

模型 ID 格式：providerId/modelId（例如 opencode/deepseek-v4-flash-free）

请求示例：

1
2
3
4
5
6
7
8
9
10
11
12

# 获取模型列表
curl -H "Authorization: Bearer sk_cf_xxxxxxxxxxxxx" \
  https://你的域名/v1/models

# 调用聊天补全
curl -X POST https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk_cf_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "opencode/deepseek-v4-flash-free",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

密钥健康系统

ai-gateway 内置了一套完善的密钥健康管理系统：

失败判定规则：

密钥恢复机制：
已降级的 Key 在 5 分钟冷却期后会获得一次重试机会：

• 重试成功 → 恢复权重，回到健康队列
• 重试失败 → 再次进入冷却

OpenCode 自动回退

OpenCode 提供商有特殊的智能回退逻辑：

1. 配置了 API Key → 优先尝试官方 API（https://opencode.ai/zen/v1）+ 用户 Key
2. 官方 API 失败 → 尝试公共镜像（随机起点，每个最多一次）
3. 未配置 API Key → 跳过官方 API，直接尝试公共镜像（使用 Bearer public）
4. 全部失败 → 返回官方 API 的存储错误响应

模型过滤：OpenCode 仅展示以 -free 结尾的免费模型和 big-pickle 模型。

配置说明

环境变量

默认配置（src/config.ts）

1
2
3
4
5

const PROXY_KEY_PREFIX = 'sk_cf_'       // 代理密钥前缀
const OPENCODE_DEFAULT_URL = 'https://opencode.ai/zen/v1'
const KEY_HEALTH_COOLDOWN_MS = 5 * 60 * 1000  // 5 分钟冷却
const KEY_HEALTH_MAX_FAILURES = 5              // 连续失败降级次数
const SESSION_TTL = 7 * 24 * 60 * 60          // Session 有效期 7 天

默认提供商（自动初始化）

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "id": "opencode",
  "name": "OpenCode",
  "baseUrl": "https://opencode.ai/zen/v1",
  "apiType": "openai",
  "apiKeys": [],
  "models": [
    {"id": "deepseek-v4-flash-free", "enabled": true},
    {"id": "mimo-v2.5-free", "enabled": true},
    {"id": "nemotron-3-ultra-free", "enabled": true},
    {"id": "hy3-free", "enabled": true}
  ],
  "enabled": true
}

KV 存储键

管理后台

管理后台访问路径为 https://你的域名/admin，登录后可以：

提供商管理

• 查看所有提供商（OpenCode、自定义 OpenAI/Anthropic 兼容提供商）
• 添加新提供商（填写 ID、名称、API 地址、API 类型）
• 编辑提供商配置（API Key、模型列表、启用/禁用）
• 删除不再使用的提供商

代理密钥管理

• 生成新的 sk_cf_* 格式 API 密钥
• 查看密钥列表（密钥值脱敏展示）
• 启用/禁用特定密钥
• 删除密钥

模型测试

• 测试某个 API Key 是否可以连接
• 测试某个模型是否可以正常调用
• 所有测试通过服务端代理完成，避免跨域问题

本地开发

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 克隆仓库
git clone https://github.com/your-username/ai-gateway
cd ai-gateway

# 安装依赖
npm install

# 创建 .dev.vars 文件（已 gitignore）
echo "ADMIN_USERNAME=admin" >> .dev.vars
echo "ADMIN_PASSWORD=your-password" >> .dev.vars
echo "OPENCODE_MIRRORS_URL=https://opencode.ai.cmliussss.net/zen/v1" >> .dev.vars

# 启动本地开发
npm run dev

# 部署
npm run deploy

npm 脚本：

设计系统

项目使用 Hono 服务端渲染，设计系统遵循：

错误响应格式

1
2
3
4
5
6

{
  "error": {
    "message": "错误描述信息",
    "type": "错误类型"
  }
}

错误类型：authentication_error、invalid_request_error、provider_disabled、model_disabled、configuration_error、key_exhausted、proxy_error、server_error、not_found

常见问题

部署后首页空白或报错？

检查 KV 命名空间是否正确绑定。进入 Cloudflare Worker → 设置 → KV 命名空间，确认绑定名称为 KV。

管理后台无法登录？

确认环境变量 ADMIN_USERNAME 和 ADMIN_PASSWORD 已正确设置。密码使用 SHA-256 比较，确保密码没有多余空格。

OpenCode 模型无法调用？

1. 检查 OPENCODE_MIRRORS_URL 环境变量是否配置
2. 确认 Cloudflare 网络可以访问镜像地址
3. 检查模型是否处于启用状态

自定义提供商模型 ID 格式？

模型 ID 格式为 providerId/modelId。例如添加了名为 my-api 的提供商，模型 ID 为 gpt-4o，则调用时使用 my-api/gpt-4o。

代理密钥 sk_cf_* 忘记了怎么办？

代理密钥在创建时只显示一次。如果忘记了，可以在管理后台的「代理密钥」页面重新生成一个新的。

不支持哪些部署平台？

不推荐部署到：

• Vercel — SSE 连接会超时
• Netlify — 不支持 SSE 透传
• Render — 冷启动延迟 5-10 秒

如何添加自定义 OpenCode 镜像？

在 GitHub Actions 的 OPENCODE_MIRRORS_URL 变量中追加你的镜像 URL，或使用 Dashboard 手动配置环境变量。

参考

• ai-gateway GitHub 仓库
• Hono 框架官网
• Cloudflare Workers 文档
• Cloudflare KV 文档
• Wrangler CLI 文档

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客