One Balance: 如何使用 Cloudflare 构建一个智能的 API 密钥负载均衡器

你好！如果你正在处理多个 AI API 密钥，特别是那些有配额限制的，比如 Google AI Studio 的密钥，你可能会遇到一个常见问题：如何高效地轮询这些密钥来最大化利用资源，而不让其中一个密钥过早耗尽配额？今天，我想和你聊聊 One Balance 这个工具。它是一个基于 Cloudflare 的 API 密钥负载均衡器，能帮助你智能管理这些密钥。让我们一步步来了解它是怎么回事，为什么它有用，以及如何上手。

想象一下，你有几个 API 密钥，每个都有自己的使用限制。如果你手动切换它们，很容易出错，或者浪费时间。One Balance 就是来解决这个的。它利用 Cloudflare AI Gateway 的路由能力，在此基础上添加了轮询和健康检查功能。这样，你可以让系统自动选择可用的密钥发送请求，避免单一密钥被过度使用。

One Balance 还支持赞助，如果你赞助项目，可以领取 Gemini Key。这是一个不错的激励方式，支持项目的持续发展。

如果你感兴趣，可以访问赞助项目来支持发展。

One Balance 的主要特性是什么？

我们先来谈谈 One Balance 能做什么。我会用列表形式列出来，便于你快速浏览。

降低封禁风险：通过 Cloudflare AI Gateway 路由请求，这能有效减少 API 密钥被封禁的概率，尤其是针对 Gemini 这样的密钥。
智能的错误处理：系统处理错误的逻辑很细致，能识别不同类型的错误，并相应调整。例如，它有模型级限流，能精准屏蔽达到速率限制的特定模型。对于 Google AI Studio，它还能区分分钟级和天级配额，进行不同的冷却处理，比如触发天级配额后冷却 24 小时。
自动熔断：如果密钥被提供商封禁（比如返回 403 错误），系统会永久禁用它，避免无效的重试。
免费且简单：基于 Cloudflare Workers，一键部署。你可以充分利用 Cloudflare 的免费额度，包括在处理大规模密钥时优化 CPU 时间。
广泛的兼容性：支持 Cloudflare AI Gateway 兼容的所有 API 提供商。这包括轮询 Gemini TTS，这可能是独有的功能，已经应用在像 Zenfeed.xyz 这样的服务中，用于实时生成新闻播客。

这些特性让 One Balance 不仅仅是一个简单的负载均衡器，而是一个能智能适应的工具。举个例子，如果你有多个 Gemini 密钥，系统会轮询它们，确保每个密钥的配额都被均匀利用。

如何部署 One Balance？

部署过程其实很简单，我会一步步指导你，就像我们在聊天一样。如果你问：“我需要什么准备？” 答案是：安装 Node.js 和 pnpm，还有一个 Cloudflare 账户。这些都是基础环境。

步骤 0: 准备环境

下载并安装 Node.js。
安装 pnpm，这是一个包管理器，能帮助你高效管理依赖。

有了这些，你就ready了。

步骤 1: 创建 AI Gateway

登录你的 Cloudflare 仪表板。导航到 AI 部分，然后选择 AI Gateway。创建一个新的 Gateway，并命名为 “one-balance”。这个名字很重要，因为它会和后面的配置匹配。

为什么需要这个 Gateway？因为 One Balance 会通过它路由请求到实际的 AI 提供商。

步骤 2: 部署到 Cloudflare

现在，克隆仓库并部署。使用终端运行以下命令：

git clone https://github.com/glidea/one-balance.git
cd one-balance
pnpm install

然后，根据你的操作系统设置 AUTH_KEY 并部署：

对于 Mac 或 Linux：

AUTH_KEY=your-super-secret-auth-key pnpm run deploycf

对于 Windows (PowerShell)：

$env:AUTH_KEY = "your-super-secret-auth-key"; pnpm run deploycf

脚本会引导你登录 wrangler（Cloudflare 的 CLI 工具），如果还没登录的话。它还会自动创建所需的 D1 数据库，并部署 Worker。完成后，你会得到一个 Worker URL，比如 https://one-balance-backend.<your-subdomain>.workers.dev。

部署成功后，你可能会想：“如果我在中国大陆访问有问题怎么办？” 建议使用代理工具来访问管理界面，因为有些地区可能有访问限制。

如何使用 One Balance？

部署好了，现在来聊聊怎么用。使用分两部分：配置密钥和访问 API。

配置待轮询的密钥

访问你的 Worker URL，比如 https://<your-worker-url>。在这里，你可以添加和管理要轮询的密钥。

一个最佳实践：尽量不要和他人共享密钥。因为如果共享，系统无法感知全局调用信息，可能会增加 429 错误（限流）的概率。保持密钥私有，能让负载均衡更有效。

访问 API

API 的访问路径是 https://<your-worker-url>/api/<ai-gateway-path>。

例如，如果你的 Worker URL 是 https://one-balance-backend.workers.dev，想向 Google Gemini 2.5 Pro 发送请求，URL 就是 https://one-balance-backend.workers.dev/api/google-ai-studio/v1beta/models/gemini-2.5-pro:generateContent。

认证方式

你需要用部署时设置的 AUTH_KEY 进行认证。不同提供商的 Header 不同：

对于 OpenAI：使用 Authorization: Bearer <AUTH_KEY>。
对于 Google、Anthropic、Elevenlabs、Azure OpenAI、Cartesia：使用对应的自定义 Header，比如 x-goog-api-key: <AUTH_KEY>。

这确保只有授权的用户能访问你的负载均衡器。

使用示例

让我们看一些实际的 curl 示例。这些能帮助你快速测试。

直接使用 Gemini 格式请求 Google Gemini（支持流式）

curl "https://<your-worker-url>/api/google-ai-studio/v1/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
 -H 'content-type: application/json' \
 -H 'x-goog-api-key: your-super-secret-auth-key' \
 -d '{
      "contents": [
          {
            "role":"user",
            "parts": [
              {"text":"你是谁?"}
            ]
          }
        ]
      }'

这个示例支持流式响应，适合实时交互。

使用 OpenAI 兼容格式请求 Google Gemini（不支持流式，中文可能乱码）

curl "https://<your-worker-url>/api/compat/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-super-secret-auth-key" \
  -d '{
    "model": "google-ai-studio/gemini-2.5-pro",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

这里，模型格式是 $provider/$model，参考 Cloudflare 的文档。注意，它不支持流式，且中文可能有编码问题。

请求 OpenAI

curl https://<your-worker-url>/api/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-super-secret-auth-key" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

其他提供商的格式类似，参考 Cloudflare AI Gateway 的提供商文档。

在 Cherry Studio 中，你可以看到类似的使用界面。

One Balance 的未来计划是什么？

One Balance 还有一些待开发的特性，我列在下面。这些是 Roadmap 中的计划，能让你看到项目的方向。

支持 key 动态转发。
支持自定义渠道。
支持虚拟 Model，聚合多个渠道。
支持分发用户 Key。

这些功能如果实现，会让工具更灵活。

One Balance 是如何工作的？

现在，我们深入一点，聊聊背后的机制。这部分适合那些想了解细节的人。我们会用架构图、生命周期图和一些解释来拆解。

架构概述

One Balance 作为一个中间层，接收 API 请求，并智能转发到 Cloudflare AI Gateway。以下是高层架构：

graph TD
    subgraph "用户"
        User["👨‍💻<br>客户端"]
    end

    subgraph "Cloudflare 环境"
        OneBalance["<b>One Balance Worker</b>"]
        D1["🗄️ D1 数据库"]
        AIGW["Cloudflare AI Gateway"]

        OneBalance -- "获取/更新密钥状态" <--> D1
        OneBalance -- "转发请求" --> AIGW
    end

    subgraph "第三方服务"
        Provider["🤖<br>AI 提供商<br>(Google, OpenAI...)"]
    end

    User -- "1. API 请求 (含服务 AUTH_KEY)" --> OneBalance
    AIGW -- "2. 代理请求 (含提供商密钥)" --> Provider
    Provider -- "3. API 响应" --> AIGW
    AIGW -- "4. 响应" --> OneBalance
    OneBalance -- "5. 最终响应" --> User

为什么用 D1 数据库而不是 Cloudflare KV？因为 KV 的免费额度有限，而 D1 更适合存储密钥状态。

密钥的生命周期

密钥不是静态的，它们有状态变化。以下是生命周期图：

graph TD
    NonExistent("<b>(不存在)</b>")

    subgraph "生命周期"
        direction LR
        Active("Active / 可用")
        CoolingDown("Cooling Down / 冷却中<br><i>(针对特定模型)</i>")
        Blocked("Blocked / 已封禁")
    end

    NonExistent -- "1. 创建 (管理员添加)" --> Active

    Active -- "2a. 使用: 成功 (2xx)" --> Active
    Active -- "2b. 使用: 被限流 (429)" --> CoolingDown
    Active -- "2c. 使用: 无效 (401, 403)" --> Blocked

    CoolingDown -- "冷却时间结束" --> Active

    Active -- "3. 删除" --> NonExistent
    Blocked -- "3. 删除" --> NonExistent
    CoolingDown -- "3. 删除" --> NonExistent

这个流程确保系统只用健康的密钥。

可靠性、可扩展性和可观测性

可靠性

系统通过几点来保障可靠：

自动熔断与重试：如果密钥返回 401 或 403，更新为 blocked，并用下一个密钥重试。
模型级智能限流：对于 429 错误，不禁用整个密钥，只为特定模型设置冷却。对于 Google AI Studio，区分分钟级（冷却 1 分钟）和天级（冷却 24 小时）。
依赖 Cloudflare 生态：Workers、D1 和 AI Gateway 提供高可用性。

可扩展性

无服务器架构：Cloudflare Workers 自动扩展，无需管理服务器。
状态分离：Worker 无状态，数据在 D1 中，便于水平扩展。
易于扩展：添加新密钥通过界面；新提供商只需配置认证头。

可观测性

核心事件日志：通过 console.log 输出密钥封禁、冷却等事件，在 Cloudflare 仪表盘查看。
Cloudflare AI Gateway 分析：查看请求数、错误率、延迟、成本。
管理界面：查看密钥状态和冷却详情。

这些机制让 One Balance 易于维护。

FAQ: 常见问题解答

我预测你可能有一些问题，这里直接回答，就像我们在对话。

One Balance 能处理哪些 AI 提供商？
它支持 Cloudflare AI Gateway 兼容的所有提供商，包括 Google、OpenAI 等。特别支持 Gemini TTS 的轮询。

如果我的密钥被封禁了，会怎么样？
系统会自动检测 403 错误，将其标记为 blocked，并从池中移除，避免进一步使用。

冷却机制是怎么工作的？
对于限流 (429)，它是模型级的。对于 Google AI Studio，分钟级限流冷却 1 分钟，天级冷却 24 小时。

部署后，如何管理密钥？
通过 Worker URL 的管理界面添加、查看和删除密钥。记住，避免共享以减少 429 风险。

One Balance 免费吗？
是的，基于 Cloudflare 的免费额度。一键部署，优化 CPU 时间，尤其适合大规模密钥。

支持流式响应吗？
是的，在直接使用 Gemini 格式时支持。但在 OpenAI 兼容格式中不支持，且中文可能乱码。

为什么用 Cloudflare AI Gateway？
它路由请求，降低封禁风险，并兼容多种提供商。

如何调试问题？
查看 Cloudflare 仪表盘的日志和 AI Gateway 分析面板。管理界面也能显示状态。

未来会添加什么功能？
计划包括 key 动态转发、自定义渠道、虚拟 Model 和用户 Key 分发。

HowTo: 一步步构建你的第一个请求

如果你是新手，这里是一个 HowTo 指南，帮助你从零开始发送请求。

部署工具：按照上面部署指南完成，获取 Worker URL。
添加密钥：访问 Worker URL，添加你的 API 密钥。
选择提供商：决定用哪个，比如 Google Gemini。
构建 URL：如 https://<your-worker-url>/api/google-ai-studio/v1beta/models/gemini-2.5-pro:generateContent。
添加认证：用 Header 如 x-goog-api-key: <AUTH_KEY>。
发送请求：用 curl 或其他工具。参考示例。
检查响应：如果错误，查看日志调整。

通过这个过程，你能快速上手。

为什么 One Balance 适合你？

如果你是开发者或研究者，处理多个有配额的 API 密钥，One Balance 能节省时间。它智能轮询、处理错误，让你专注核心工作，而不是管理密钥。

举个场景：你正在构建一个应用，需要调用 Gemini 生成内容。有多个密钥，但手动切换麻烦。One Balance 自动处理，确保平稳运行。

它还支持像 TTS 这样的独特功能，已在实际服务中使用。

深入探讨负载均衡的逻辑

负载均衡的核心是轮询：系统从可用池中选择密钥。结合健康检查，如果密钥失败，根据错误类型调整。

例如，成功响应 (2xx) 保持 active。限流 (429) 进入 cooling down。无效 (401, 403) 变为 blocked。

这基于简单的状态机，但很有效。

对于 Google AI Studio，区分限流类型是关键洞见：分钟级是短期，天级是长期。

管理界面的使用技巧

管理界面是 Web-based 的。添加密钥时，确保格式正确。查看状态：active 表示可用，cooling down 有模型特定冷却，blocked 是永久禁用。

定期检查，能保持系统健康。

与其他工具的比较

虽然文件没提其他工具，但基于特性，One Balance 的优势在免费部署、智能错误处理和 Cloudflare 集成。

如果你用过简单轮询脚本，One Balance 更高级，因为有数据库持久化和自动熔断。

潜在挑战及解决方案

挑战：访问限制。解决方案：用代理访问界面。

挑战：中文乱码。解决方案：用原生格式而非兼容模式。

挑战：密钥共享。解决方案：保持私有。

这些基于实际使用经验。

结语：开始你的 One Balance 之旅

One Balance 是一个实用工具，能让 API 密钥管理更轻松。部署简单，使用灵活，特性强大。如果你有多个密钥，不妨试试。

如果有问题，参考 FAQ 或日志。享受构建吧！

API密钥负载均衡器实战：基于Cloudflare的智能配额管理方案