James LIN

Posted on Sep 25

Hardening freellmapi in Production: Atomic Quotas, Key Isolation, and Retry Tiering

#devops #go #sqlite #ai

基於 freellmapi 構建團隊級 AI 網關：配額管控與密鑰隔離的生產強化實踐

作者: James LIN

適用場景: 5~20 人工程團隊與遠程工作室的 API 密鑰治理、子 Token 額度熔斷、防止天價帳單與調用歸屬審計

凌晨三點的警報：共享根密鑰的災難半徑

凌晨三點半，PagerDuty 刺耳的警報把我就地拽醒：團隊共享的 OpenAI 組織帳號在兩小時內被抽乾了整整 2,500 美元月度預算。溯源排查後發現，一位剛入職實習生的壓測腳本陷入了無終止的死循環，而代碼庫的 .env 裡躺著全組通用的 Master API Key。在缺乏調用端隔離的架構下，一把根密鑰的洩漏或濫用，直接等同於全團隊生產服務的連帶休克。

傳統企業級中繼方案（如 Azure OpenAI Service 或 GCP Vertex AI）配置繁瑣、多層審批鏈條冗長，對敏捷小團隊而言運營摩擦過大。開源項目 freellmapi 提供了一套極為簡潔的自託管中繼骨架，但在真實生產負載下，其原生版本缺乏併發級配額扣減、持久化速率限制以及精細化的重試決策。本文記錄我作為外部工程團隊技術負責人，基於 tashfeenahmed/freellmapi 進行系統級生產加固的具體工程路徑。

核心架構：中繼代理 + 子 Token 隔離 + SQLite 原子 CAS

加固後的核心思想非常明確：Master Key 永遠只存於網關內部，下游成員與各環境僅分配獨立子 Token，所有扣額與流控下沉至網關原子執行。

[團隊成員 A/B/C] → 各持獨立子 Token
          ↓
    [freellmapi Gateway]
      - Token → User 映射 (SQLite)
      - CAS 原子扣額 (BEGIN IMMEDIATE)
      - 429/503 指數退避 vs 5xx 快速失敗
          ↓
  [上游 API: OpenAI / Anthropic]

1. 請求重試分級策略：終結盲目重試風暴

原始 freellmapi 採用了單純的「遇 5xx 統一重試 3 次」邏輯。在速率限制（429）或網關瞬時抖動（503）時，退避重試是合理的自癒手段；但若上游直接返回模型不存在或帳號封禁，機械重試只會白白堆疊延遲，並將網關 Worker 徹底耗盡。生產強化後實施嚴格的狀態碼分級決策：

switch resp.StatusCode {
case 429, 503:
    // 指數退避: 1s → 2s → 4s,最多 3 次
    time.Sleep(time.Duration(1<<attempt) * time.Second)
    continue
case 500, 502:
    // 檢查 body 是否含 "渠道不存在" / "模型下架"
    if strings.Contains(body, "渠道不存在") {
        return fmt.Errorf("upstream model unavailable: %s", body)
    }
    // 其他 5xx 快速失敗,避免連鎖阻塞
    return fmt.Errorf("upstream error: %d", resp.StatusCode)
case 401, 403:
    // 立即失敗,記錄洩密風險
    log.Error("auth_failure", "token", tokenHash, "upstream", provider)
    return ErrUnauthorized
default:
    return nil
}

併發連線池防護：

配置底層 http.Client 的 Transport.MaxIdleConnsPerHost=10 與 IdleConnTimeout=90s，徹底防範高併發下 Keep-Alive 連線洩漏與 FD 耗盡；網關內部計數指標統一採用 atomic.AddInt64 取代粗粒度互斥鎖 mu.Lock()，顯著降低 Goroutine 鎖競爭。

2. SQLite 配額原子扣減：CAS 樂觀鎖與防穿透

多位團隊成員同時執行並行腳本時，最常出現的併發 Bug 就是 TOCTOU（Time-of-Check to Time-of-Use）窗口：兩個請求同時判定額度剩餘 $0.05，隨後雙雙扣費，造成嚴重透支。我們將原本分散的 SELECT → 判斷 → UPDATE 徹底重構為帶條件校驗的 CAS（Compare-And-Swap）單一事務：

BEGIN IMMEDIATE;
UPDATE tokens
SET remaining_quota = remaining_quota - ?1
WHERE token = ?2
  AND remaining_quota >= ?1
  AND (reset_at IS NULL OR reset_at > datetime('now'));
-- 若 changes() == 0 則額度不足或已過期
COMMIT;

事務鎖與生命週期管理：

BEGIN IMMEDIATE：在事務開頭直接獲取保留鎖（Reserved Lock），從根源杜絕讀寫時序差引起的幻讀與死鎖。
WAL 與熱備份：全域開啟 PRAGMA journal_mode=WAL 保障高併發讀寫互不阻塞；每日由定時任務調用 sqlite3 quota.db ".backup /backup/quota_$(date +%F).db" 執行非阻塞增量熱備，嚴格保留 7 天歷史快照。

3. 速率限制持久化：滑動窗口 Token Bucket

單純的進程內 In-Memory Token Bucket 存在致命死穴：網關一旦重啟或部署滾動升級，內存狀態全部歸零，瞬時突發流量會直接繞過限制擊穿上游。 我們引入 Redis Sorted Set 構建秒級精度的滑動窗口限流器：

func AllowRequest(token string, burstSize int) bool {
    now := time.Now().Unix()
    key := "ratelimit:" + token
    // 清理過期令牌
    redis.ZRemRangeByScore(ctx, key, "-inf", now-60)
    // 檢查當前窗口令牌數
    count := redis.ZCard(ctx, key).Val()
    if count >= int64(burstSize) {
        return false
    }
    // 添加新令牌
    redis.ZAdd(ctx, key, &redis.Z{Score: float64(now), Member: uuid.New().String()})
    redis.Expire(ctx, key, 61*time.Second)
    return true
}

防護邊界：

參數 burstSize=20 嚴格限制單成員每分鐘突發上限為 20 req/min。一旦超過即時拒絕，配合客戶端的退避重試，既保障了正常開發展現，又徹底封死了惡意死循環對上游帳戶造成的打擊。

生產部署與可觀測性加固

容器沙箱與資源邊界約束

# docker-compose.yml
services:
  gateway:
    image: freellmapi:prod
    cpus: "2.0"
    mem_limit: 1g
    ulimits:
      nofile: 8192
    environment:
      DB_PATH: /data/quota.db
      REDIS_URL: redis://redis:6379/0
    volumes:
      - ./data:/data
    restart: unless-stopped

硬性限制 mem_limit=1g 防止高延遲慢速客戶端攻擊引發記憶體洩漏與 OOM；調整 ulimits.nofile=8192 確保高負載下長連線穩定維持。

結構化可觀測性鏈條

網關全面收斂為結構化日誌輸出，嚴格脫敏所有請求主體，僅記錄審計指紋：

log.Info("request_completed",
    "token_hash", sha256(token)[:8],
    "model", model,
    "latency_ms", latency.Milliseconds(),
    "quota_remaining", remaining,
)

網關向 Prometheus 暴露核心維運指標：

gateway_requests_total{token, model, status}
gateway_quota_remaining{token}
gateway_upstream_latency_seconds{provider}

結合 Grafana 監控面板，設置告警規則 quota_remaining < 1000，在任何子帳戶額度告罄前提前 7 天發送釘釘/Slack 警報，徹底終結突發停機。

架構權衡與運營反思

回顧整套改造，輕量網關的設計本質上是一場極簡維運與架構擴展性之間的零和博弈：

單機 SQLite 的極限：目前採用 WAL 模式的單機 SQLite 足以應付千萬級月度請求，但水平擴展時必須重構為 PostgreSQL + 分佈式 Advisory Lock。
審計留存與隱私邊界：若業務要求落盤完整 Prompt 審計日誌，必須在邊緣實施端到端非對稱加密並嚴格定期輪轉 KEK。
被動重試 vs 主動健康檢查：純被動狀態碼重試始終會對 P99 延遲造成數百毫秒的毛刺，引入基於 Circuit Breaker 的主動探針是下階段的必經之路。

你們團隊目前是如何管控內部 AI API 消耗與密鑰分發的？是在 Envoy/Kong 等重型網關上加掛 Wasm 插件，還是依賴這類自託管的輕量級 Go 中繼層？在高併發與成本審計的平衡上踩過哪些坑？歡迎在評論區分享你的實戰經驗！

技術披露:

作者任職於 B-Lost.com AI 網關,本文所述強化實踐已在生產環境服務 15+ 小型技術團隊。B-Lost 提供開箱即用的多租戶中繼服務,但核心配額管控與請求分級策略與上述 freellmapi 改進路徑保持一致。

DEV Community