Gemini Balance 部署筆記：API 代理、金鑰輪詢與版本邊界

如果一個客戶端只會連一個 Gemini API endpoint，所有請求、認證與金鑰失效都會擠在同一個地方。Gemini Balance 的價值，是在客戶端與 Google Gemini API 中間放一層可管理的代理：由它保存多個 upstream key，處理輪詢、存取 token 與狀態觀察，再把較一致的 API 介面提供給 Cherry Studio 或其他客戶端。

本文記錄 2025 年 7 月的一次部署體驗。它的讀者合約是理解代理層與部署決策，不是保證今天照著每一張截圖就能完成部署。Gemini Balance、ClawCloud、客戶端和 Gemini API 都會更新；文末的版本檢查清單是這篇文章不可省略的一部分。

代理層到底替客戶端做了什麼？

客戶端送出請求時，先帶著代理 token 到 Gemini Balance。代理再從自己的 key pool 選擇一把可用的 Google Gemini API key，轉送請求並記錄結果。這讓客戶端不必保存每一把 upstream key，也可以在代理端集中管理模型清單、失敗重試與 key 狀態。

目前上游 README 將 Gemini Balance 描述為以 Python FastAPI 建立的 Gemini API proxy/load balancer，並列出 Gemini 與 OpenAI 相容路徑、key rotation、authentication、model filtering 與 status monitoring。這些是專案功能宣告，不等同於我在本次部署中逐項驗證過的結果。

為什麼金鑰輪詢不等於無限配額？

原始文章是因為遇到 Gemini API 的配額錯誤，才開始研究多 key 代理。把請求分散到多個 key，可能改變每個 key 的請求分布，但它不能保證突破 provider 的 quota、billing、rate limit 或服務條款，也不能把失敗請求變成成功請求。

因此，正確的心智模型是「增加一個可觀測與可控的代理層」，而不是「免費擴充 API 配額」。正式使用前，應閱讀 Google Gemini API rate limits，確認帳號、模型與應用情境允許的用量；也要避免把不屬於自己的 key 放進代理。

2025 年的 ClawCloud 路徑留下了什麼？

原始嘗試以 ClawCloud 執行容器，並用管理頁設定 upstream keys 與 allowed tokens，再以 Cherry Studio 和 VS Code Cline 連線測試。這三個介面截圖能回答一個具體問題：代理 token、公開 base URL 與客戶端 provider 設定是否接得起來。

但「部署成功」在這裡只表示當時能完成一次連線測試。它沒有證明免費額度會一直存在、外部 URL 永久可用、SQLite 適合所有流量，也沒有證明多 key 代理可以安全地承擔團隊或商業服務。

為什麼今天不能直接複製舊的 SQLite 教學？

截至 2026-09-22，我核對到的 Gemini Balance 上游 README 將 Docker Compose 列為推薦方式，範例要求設定 DATABASE_TYPE=mysql 與 MYSQL_* 連線資訊；同一份 README 仍列出 sqlite 作為可選的 DATABASE_TYPE，但這不代表原文章所引用的 ClawCloud SQLite 指南仍是最佳或完整路徑。

部署前至少要重新確認：

1. 上游 repository 的 branch、release 或 image tag；不要把 latest 當成固定版本。
2. .env.example 的必要欄位、ALLOWED_TOKENS、AUTH_TOKEN 與資料庫設定。
3. 代理實際提供的是 Gemini API 格式、OpenAI 相容格式，還是某個 client 特有的 base path。
4. 公開部署的 secret、TLS、資料持久化、管理頁認證、log 內容與備份策略。
5. 目前使用的模型是否仍存在，以及 key health check、retry 和 disable 行為是否與你的期待相同。

可以先從上游目前的 Docker image 與 Compose 入口開始：

docker pull ghcr.io/snailyp/gemini-balance:latest
docker compose up -d

這段只表達目前 README 的入口，不是完整安全部署命令；.env 和資料庫設定必須依當前版本填寫，不能把 API keys 寫進文章、shell history 或公開 repository。

這次部署真正證明了什麼？

這次經驗證明了代理層可以把「多個 upstream key、統一的 client 入口、狀態觀察」放在一個服務中，也證明了 Docker 與第三方託管平台能讓個人快速做一次端到端連線試驗。它沒有證明成本一定較低、配額一定增加、服務一定高可用，或客戶端未來版本一定相容。

這也是這篇文章現在仍值得保留的原因：部署的難點不只在按下 Deploy，而在於辨認哪些行為是代理本身的功能、哪些是 Google API 或客戶端的外部條件，以及哪些只是某一天的服務介面。當版本變動時，先回到上游 README、環境變數與實際 health check，再決定是否沿用舊設定。

參考資料

• Gemini Balance 官方 repository
• Gemini Balance README（目前的 Docker 與設定說明）
• Google Gemini API rate limits
• 原文章引用的 ClawCloud SQLite 指南（歷史參考，執行前請重新核對）