LiteLLM 閘道架設：以自己的 API Key 建立統一入口

LiteLLM 閘道架設的目的，是把你已經從各家模型服務商取得的 API Key 集中到一個與 OpenAI 相容的端點後面，並且只讓你自己的應用程式連接。閘道以 Docker Compose 在固定版本上運作，每個應用程式獲發一把設有獨立預算的虛擬密鑰，閘道本身則不暴露在互聯網上。

關鍵要點：

• 只使用你自己的官方服務商 API Key，不轉售、不向他人分享閘道存取權。
• 把映像固定到發行標籤，密鑰放在受保護的 .env 檔案內。
• 虛擬密鑰、預算及按密鑰限流都依賴 Postgres 資料庫。
• 端口只在 127.0.0.1 發布，經 SSH 或附 TLS 的反向代理連接。
• .env 要與資料庫一併備份，遺失 salt 密鑰會令已儲存的憑證無法讀取。

LiteLLM 閘道可以做甚麼、不可以做甚麼？

LiteLLM 閘道提供與 OpenAI 相容的 API，任何 OpenAI SDK 都可直接指向它。虛擬密鑰用來取代原始服務商密鑰交給應用程式，每把密鑰都可設定自己的預算、請求限額和可用模型。［1］ 本文依據下列官方來源整理，未完成完整端到端實測。本文以 LiteLLM v1.105.1 為準，其發行說明列出的映像為 ghcr.io/berriai/litellm:v1.105.1。［2］

閘道無法憑空產生你沒有的服務商權限，也不能解除服務商的限額或更改其條款。它亦不是在受限網絡使用 AI 工具的方法：如 Cursor 或 Copilot 完全連不上，請先找出連線失敗的原因，不要再多加一層。

把範圍收窄。只使用經各服務商官方開發者平台簽發給你本人的 API Key，供你自己或所屬機構的應用程式使用。不要轉售存取權，不要把虛擬密鑰交給外人，也不要把面向消費者的網頁聊天工作階段轉換成 API；經閘道發出的請求，仍屬你在各服務商政策下的使用，例如 OpenAI 的使用政策。［3］

LiteLLM 閘道架設在哪部機器較合適？

你維護的伺服器始終是伺服器，自行架設服務的維護取捨同樣適用；租用的 VPS 也不等於 VPN 服務，租用 VPS 與訂閱 VPN 的分別對此有所說明。

位置	適合	主要風險
你自己的工作電腦	單一開發者、本機工具	電腦休眠時閘道隨之停止
區域網絡內的家用伺服器	你自己的多部裝置	端口轉發設定出錯會把它暴露出去
VPS	需要長期運作的自家應用程式	有公共 IP：切勿公開 4000 端口

步驟 1：準備主機及受保護的密鑰

安裝 Docker Engine 和 Compose 插件，然後建立工作目錄。官方快速入門以 openssl rand -hex 32 產生主密鑰和 salt 密鑰；以下寫法另外產生一個資料庫密碼：［1］

mkdir -p ~/litellm && cd ~/litellm
umask 077
printf 'LITELLM_MASTER_KEY=sk-%s\nLITELLM_SALT_KEY=sk-%s\nPOSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" "$(openssl rand -hex 24)" > .env
ls -l .env

以編輯器開啟 .env，加入 OPENAI_API_KEY= 和 ANTHROPIC_API_KEY= 兩行並填上你自己的密鑰；在編輯器輸入可避免密鑰留在 shell 歷史紀錄。主密鑰是閘道的根憑證，可授權所有管理呼叫及 Admin UI 登入，必須當作 root 密碼看待。［1］ 正式部署指南要求它以 sk- 開頭。［4］

步驟 2：編寫固定版本的 LiteLLM Docker Compose 部署檔

快速入門提供的 compose 檔使用浮動標籤，而且在沒有另行設定時會把 4000 端口發布到所有網絡介面；它亦建議在本機評估以外固定發行標籤。［1］ 把以下內容儲存為 compose.yaml：

services:
  litellm:
    image: ghcr.io/berriai/litellm:v1.105.1
    command: ["--config", "/app/config.yaml"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    environment:
      LITELLM_MASTER_KEY: ${LITELLM_MASTER_KEY:?set in .env}
      LITELLM_SALT_KEY: ${LITELLM_SALT_KEY:?set in .env}
      DATABASE_URL: postgresql://litellm:${POSTGRES_PASSWORD:?set in .env}@db:5432/litellm
      OPENAI_API_KEY: ${OPENAI_API_KEY:?set in .env}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:?set in .env}
      LITELLM_MODE: PRODUCTION
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
      POSTGRES_DB: litellm
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U litellm"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data:

Docker 提醒，已發布的端口預設可從主機外部連入；加上 127.0.0.1 後，只有 Docker 主機本身可以連接該端口。［5］ 把 LITELLM_MODE 設為 PRODUCTION，可阻止 LiteLLM 自行載入本機 .env。［4］ 不使用的服務商那一行可以刪除。

步驟 3：在 config.yaml 列出模型

在 config.yaml 中，model_name 是應用程式送出的名稱，litellm_params.model 則是閘道實際呼叫的服務商模型。［6］ 把佔位符換成服務商現行文件中的模型 ID：

model_list:
  - model_name: openai-main
    litellm_params:
      model: openai/<openai-model-id>
      api_key: os.environ/OPENAI_API_KEY
  - model_name: claude-main
    litellm_params:
      model: anthropic/<anthropic-model-id>
      api_key: os.environ/ANTHROPIC_API_KEY
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  trusted_proxy_ranges: []

os.environ/ 寫法會從容器環境變數讀取密鑰，Anthropic 模型使用 anthropic/ 前綴。［6］［7］ 沒有開啟 store_model_in_db 時，這個檔案就是唯一的設定依據。［6］ 客戶端直接連接時，trusted_proxy_ranges 留空即可；日後加入反向代理，再填上代理所在網段。［4］

docker compose up -d
docker compose ps
docker compose logs --tail 50 litellm

步驟 4：發出設有限額的 LiteLLM 虛擬密鑰

虛擬密鑰依賴資料庫，須以主密鑰呼叫 /key/generate 建立。［8］ 先把主密鑰讀入變數，輸入時不顯示：

read -rs LITELLM_ADMIN && export LITELLM_ADMIN
curl -s http://127.0.0.1:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_ADMIN" \
  -H 'Content-Type: application/json' \
  -d '{"models": ["openai-main"], "max_budget": 5, "budget_duration": "30d", "rpm_limit": 20}'

密鑰超出 max_budget 後請求會失敗，budget_duration 會在每個周期完結時重設花費；每分鐘請求數亦可按密鑰設限。［9］ 預算只在連接資料庫時才會執行，所以也要在各服務商自己的控制台設定消費上限。［1］ 把傳回的密鑰存入應用程式的密鑰管理工具，每個應用程式各用一把。

步驟 5：驗證正常呼叫及拒絕情況

read -rs APP_KEY && export APP_KEY
curl -s http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer $APP_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model": "openai-main", "messages": [{"role": "user", "content": "Say hello in five words."}]}'

下表說明應檢查甚麼，並非測試結果紀錄。

檢查方法	預期現象	失敗時處理
以虛擬密鑰呼叫 openai-main	傳回對話結果	在日誌中檢查服務商密鑰和模型 ID
改用隨意編造的密鑰再呼叫	傳回認證錯誤，沒有結果	確認已設定 master_key，而且密鑰沒有被重用
以這把密鑰呼叫 claude-main	被拒：模型不在該密鑰清單內	重新建立密鑰並明確填寫 models 清單
超出該密鑰的每分鐘請求限額	時段結束前傳回錯誤	檢查資料庫是否已連接
從另一部裝置 curl 4000 端口	連線被拒	修正 ports 一行，保留 127.0.0.1

密鑰外洩時，如想先停用而不刪除，可用主密鑰把它提交到 /key/block；/key/unblock 可以恢復。［8］

步驟 6：從其他裝置連接閘道

保持綁定本機位址。在手提電腦上以 SSH 本機轉發，把請求送到伺服器的回送端口：ssh -L 4000:127.0.0.1:4000 user@server。如不清楚 SSH 轉發與 VPN 隧道有何分別，可比較 SSH 隧道與 VPN。

區域網絡內有多部裝置時，在閘道前加設使用有效 TLS 證書的反向代理，並以防火牆限制存取；切勿把發布一行改成所有網絡介面。SDK 指向轉發或代理後的位址，並使用各應用程式自己的虛擬密鑰。

步驟 7：升級、備份及停止

先細閱下一個版本的發行說明，更改映像標籤，再執行 docker compose pull 和 docker compose up -d。發行說明附有以 cosign 核實映像簽署的指令。［2］

.env 和資料庫要一併備份，因為日後更換 LITELLM_SALT_KEY 會令已儲存的憑證無法讀取：［1］

docker compose exec -T db pg_dump -U litellm litellm > litellm-backup.sql
chmod 600 litellm-backup.sql

docker compose down 會停止整套服務並保留資料庫卷；docker compose down -v 還會刪除該卷，而且無法復原。停用閘道時，亦要到各服務商控制台撤銷相應密鑰。

總結

• 閘道只用於你自己的官方 API Key 和自家應用程式。
• 固定映像版本，保護好 .env，把 4000 端口綁定到本機位址。
• 在 config.yaml 把易記的模型名稱對應到服務商模型。
• 為每個應用程式發出限定模型、預算和請求限額的虛擬密鑰。
• 升級或停用前，把密鑰檔案和資料庫一併備份。

常見問題

自行架設 LiteLLM 需要付費嗎？

開源閘道採用 MIT 授權，可免費運行；不過你的密鑰所產生的 API 用量，仍然要按各服務商的規定付費。

簡單部署也一定要用 Postgres 嗎？

只有不需要虛擬密鑰和預算時才可省略。沒有資料庫時主密鑰是唯一憑證，而且預算不會被執行。

可以把閘道分享給朋友使用嗎？

不建議這樣做。把服務商密鑰的存取權分給他人可能違反服務商條款，你亦要為他人的使用行為負責。

主密鑰為何要以 sk- 開頭？

LiteLLM 的虛擬密鑰及正式部署指南都要求主密鑰帶 sk- 前綴，按這個格式產生可避免啟動時出現問題。

閘道能繞過 AI 服務的地區限制嗎？

不能。閘道只是轉發你自己的 API 請求，不會改變服務商的可用地區、帳戶資格，也不會改變適用於你的條款。

遺失 LITELLM_SALT_KEY 會怎樣？

資料庫內儲存的憑證會無法讀取，只能重新輸入；請把原本的 .env 檔案與備份放在一起妥善保存。

應否在 VPS 開放 4000 端口？

不應該。端口保持在 127.0.0.1，經 SSH 轉發或只容許你自己裝置連接的 TLS 反向代理來存取。

免責聲明：本文依據官方文件整理，只提供一般技術資訊，不構成法律意見，亦非已完成測試的紀錄。請遵守你所使用 API Key 相應服務商的條款。

來源:

1. LiteLLM Docker Quickstart — https://docs.litellm.ai/docs/proxy/docker_quick_start
2. LiteLLM v1.105.1 release — https://github.com/BerriAI/litellm/releases/tag/v1.105.1
3. OpenAI Usage Policies — https://openai.com/policies/usage-policies/
4. LiteLLM Production Best Practices — https://docs.litellm.ai/docs/proxy/prod
5. Docker Port Publishing and Mapping — https://docs.docker.com/engine/network/port-publishing/
6. LiteLLM Proxy Config.yaml — https://docs.litellm.ai/docs/proxy/configs
7. LiteLLM Anthropic Provider — https://docs.litellm.ai/docs/providers/anthropic
8. LiteLLM Virtual Keys — https://docs.litellm.ai/docs/proxy/virtual_keys
9. LiteLLM Budgets and Rate Limits — https://docs.litellm.ai/docs/proxy/users

Sources checked 2026 年 10 月 14 日。

---

延伸閱讀：

• 排查 AI 編程工具無法連線的原因
• 在租用 VPS 與使用 VPN 之間作選擇
• 比較 SSH 隧道與 VPN