跳至主要內容

多區域部署

在同一家雲端提供者的多個區域中執行 LiteLLM proxy 執行個體，全部連接到同一個共享的 PostgreSQL 資料庫。用戶端會被路由到最近的區域以降低延遲，而金鑰、團隊、使用者與花費追蹤則會因為只有單一事實來源而在各處保持一致。

本頁涵蓋支援的拓撲、跨區域授權的運作方式，以及逐步設定方式。若要在每個區域部署 proxy 本身，請參閱生產環境部署。

架構​

用戶端，路由至最近的區域
依延遲或地理位置進行 DNS 路由
Route 53依延遲路由
us-east-1主要
LiteLLM 執行個體區域負載平衡器與 Pod
區域 Redis速率限制、路由器狀態、快取
PostgreSQL（主要）單一共用資料庫
eu-west-1次要
LiteLLM 執行個體區域負載平衡器與 Pod
區域 Redis速率限制、路由器狀態、快取
從選用複本讀取，寫入主要執行個體
讀取複本（選用）DATABASE_URL_READ_REPLICA
一份 Enterprise 授權涵蓋所有區域。每個執行個體都會驗證相同的 LITELLM_LICENSE，並由單一共用資料庫統計使用者與團隊限制。所有執行個體也必須共用相同的 LITELLM_MASTER_KEY 與 LITELLM_SALT_KEY。

此拓撲有三項規則：

  1. 一個資料庫。 每個區域的 proxy 執行個體都指向 DATABASE_URL 同一個 PostgreSQL 資料庫，該資料庫託管在您的主要區域。這就是讓某個區域建立的金鑰能在所有區域運作的原因，也是讓預算與花費追蹤在全域保持一致的原因。
  2. 每個區域一個 Redis。 Redis 處理某個區域內各執行個體之間的速率限制、路由器狀態與回應快取。請保持在同區域內；將單一 Redis 放在跨區域連線後方，會讓每次速率限制檢查都多一次網路往返。
  3. 一個雲端提供者。 在同一家雲端提供者中執行所有區域。

相同的拓撲可採 active-active（DNS 將每個用戶端路由到最近的區域；目標是延遲）或 active-passive（所有流量都在一個區域上，第二個區域已部署但在 DNS 故障轉移記錄後方閒置；目標是災難復原）運作。設定完全相同；只有 DNS 政策不同。

跨區域授權​

只要所有區域共用一個資料庫，單一 LiteLLM Enterprise 授權即可涵蓋所有區域。

每個 proxy 執行個體都會獨立驗證其接收到的 LITELLM_LICENSE 金鑰（離線對已簽署的負載，或對授權伺服器），而授權檢查中不會計算執行個體或區域數量。授權所帶有的數量限制，也就是最大使用者數與最大團隊數，會從資料庫計算。當每個區域共用同一個資料庫時，這些計數只存在一份，因此授權也只會在全域強制一次。

推論很簡單：每個區域各自一個資料庫就是各自獨立的部署，而每個部署都需要自己的授權。兩個資料庫就代表兩組使用者與團隊計數、兩組金鑰，以及兩份授權。

拓撲資料庫所需授權
多區域，共用資料庫（本頁）11
每個區域獨立部署每個區域 1 個每個區域 1 個
Global Control Plane每個 worker 1 個每個 worker 1 個

如果您想要每個區域都有完全獨立的部署（自己的資料庫、Redis、master key 和授權），並由單一 UI 管理，請使用 Global Control Plane（Enterprise），而不是本頁。它以全域一致性換取爆炸半徑隔離：某一區域的資料庫中斷不會影響其他區域，但 keys 和預算不會跨區域共享。

需求​

每個區域中的每個 proxy 執行個體都必須共用下列項目。若這些項目在區域之間有任何差異，部署就會以難以除錯的方式出錯（無法解密已儲存憑證的執行個體、某個區域中驗證失敗的金鑰、座位限制在各處強制不一致）。

設定必須為原因
DATABASE_URL每個區域使用相同的資料庫金鑰、團隊、使用者、花費與授權座位數的單一事實來源
LITELLM_MASTER_KEY每個區域都相同金鑰會對共享資料庫進行驗證；master key 在各處都必須一致
LITELLM_SALT_KEY每個區域都相同，且設定完成後不得變更加密與解密儲存在資料庫中的 LLM 憑證。使用不同 salt key 的執行個體無法讀取已儲存的模型憑證
LITELLM_LICENSE每個區域使用相同的授權金鑰每個執行個體都會獨立驗證授權；一把金鑰可啟用所有執行個體
DISABLE_SCHEMA_UPDATE所有 proxy 執行個體上的 trueSchema migration 必須且只能執行一次（作為一個 job），不能被每個區域中的每個執行個體競態執行

每個區域另外還要執行一個 Redis 執行個體，並在該區域的 proxy 設定中將其設定好（router_settings 與快取設定）。Redis 狀態是區域性的：速率限制與已快取回應都只屬於處理該請求的區域。

資訊

速率限制（key、team 和 user 的 TPM/RPM）是透過 Redis 強制執行。每個區域一個 Redis 時，100 RPM 的限制代表每個區域 100 RPM，而不是全域 100 RPM。若您需要嚴格的全域速率限制，所有執行個體都必須共用一個 Redis，這會讓遠端區域的請求路徑多一次跨區域往返。多數部署會接受每個區域各自強制執行。

設定​

以下步驟假設您已經可以部署單一區域的生產環境 proxy（load balancer、proxy 執行個體、Postgres、Redis）。如果還不行，請先從 生產環境部署指南 和 生產檢查清單 開始。

1. 佈建共享資料庫​

在您的主要區域建立一個 PostgreSQL 資料庫，並使用 Helm charts 或 Terraform modules 中的 migration job，對其執行一次 schema migration。所有區域都會使用這個資料庫的連線字串。

2. 連接各區域的網路​

次要區域中的 proxy 執行個體必須透過私有、已路由的連線連到主要區域的資料庫：AWS 上使用 VPC peering 或 Transit Gateway，GCP 上使用 VPC Network Peering（具有區域子網路的全球 VPC 也可以），Azure 上使用 VNet peering。在資料庫的 security group 或 firewall 中，從每個次要區域的 proxy 子網路開放資料庫埠（5432），並要求連線使用 TLS（sslmode=require）；這些流量會跨越區域邊界。每一次來自次要區域的未快取資料庫讀取，都會支付跨區域往返成本，這也是第 4 步新增區域內讀複本的原因。

3. 在每個區域部署 proxy 執行個體​

在每個區域部署 proxy 的方式與單一區域完全相同，只有兩個差異：將 DATABASE_URL 指向主要區域的資料庫，而不是區域內的資料庫；並且只在主要區域執行 schema migrations job（次要區域的 Helm values 中設為 migrationJob.enabled: false），如此一來某個區域的 rollout 就不會與另一個區域對共享 schema 的 migration 競態。請從同一個事實來源部署每個區域（單一 Helm values 檔案或 Terraform 設定，只依區域參數化），以避免各區域在版本或設定上漂移。

DATABASE_URL="postgresql://litellm:<password>@db.us-east-1.internal:5432/litellm?sslmode=require"
LITELLM_MASTER_KEY="sk-<same-everywhere>"
LITELLM_SALT_KEY="sk-<same-everywhere-never-rotate>"
LITELLM_LICENSE="<same-everywhere>"
DISABLE_SCHEMA_UPDATE="true"
REDIS_HOST="redis.us-east-1.internal"
REDIS_PORT="6379"
REDIS_PASSWORD="<regional>"

4. 選用：新增區域內讀複本​

每個請求都會先向資料庫驗證其金鑰（並搭配記憶體快取，因此穩態流量不會在每次呼叫時都碰到資料庫）。次要區域仍可透過在區域內執行 PostgreSQL 讀複本，並設定 DATABASE_URL_READ_REPLICA，來降低資料庫讀取延遲。LiteLLM 會將唯讀查詢路由到該複本，而所有寫入則送往主資料庫。請參閱 資料庫讀複本 了解哪些路由到哪裡，以及如何處理 replication lag。

寫入（建立金鑰、設定變更、花費更新）一律送往主要區域的資料庫。花費更新會批次處理，因此跨區域寫入延遲不會落在請求路徑中。

5. 將用戶端路由到最近的區域​

在各區域負載平衡器前放置以延遲為基礎或地理位置的 DNS：AWS 上使用 Route 53 latency-based routing，GCP 上使用 Cloud DNS geolocation routing policies，Azure 上使用 Traffic Manager 或 Front Door。用戶端使用單一主機名稱，並進入其最近的區域。

對每個區域針對 /health/liveliness 進行健康檢查，而不是 /health/readiness。Readiness 只要資料庫無法連線就會回傳 503，而且資料庫是共用的：一次故障會同時觸發所有區域的 readiness 檢查，並將所有區域一併從 DNS 轉送中移除；而就在那個時候，allow_requests_on_db_unavailable 本可讓它們繼續服務快取流量。Liveliness 則回報該區域的 proxy 是否正常運作，這正是 DNS 故障轉移決策所需要的資訊。

6. 驗證​

  1. 開啟主區域的 Admin UI（https://llm.example.com/ui），前往 Virtual Keys，並建立一個金鑰。

  2. 直接開啟次區域的 UI（https://eu.llm.example.com/ui），前往 Test Key playground，貼上您剛建立的金鑰，然後送出請求。這會成功，因為兩個區域都使用同一個資料庫驗證金鑰。

  3. 回到 Virtual Keys，確認該 key 顯示您透過次要區域發出的請求所產生的支出。UI 流程本身已在 Quickstart 中以截圖說明。

選用：專用管理實例​

預設情況下，每個實例同時提供 LLM 流量與管理流量（UI 與管理 API）。在多區域部署中，您可以將某個實例指定為僅供管理使用，並從各區域實例中移除管理介面。這可讓管理存取只經由單一主機名稱，並降低提供 LLM 流量之實例的攻擊面。

企業版功能

此功能需要 LiteLLM 企業版授權。立即開始 30 天免費試用或預約展示。 查看企業版完整功能。

DISABLE_ADMIN_ENDPOINTS 和 DISABLE_LLM_API_ENDPOINTS 是 Enterprise 功能。

# Serves the UI and management APIs, refuses LLM traffic
DISABLE_LLM_API_ENDPOINTS="true"
DATABASE_URL="postgresql://...@db.us-east-1.internal:5432/litellm"
LITELLM_MASTER_KEY="sk-<same-everywhere>"
變數預設值當 true 時的影響
DISABLE_ADMIN_UIfalse/ui 的網頁 UI 會無法使用
DISABLE_ADMIN_ENDPOINTSfalse管理端點（/key/*、/user/*、/team/*、/model/*）會回傳錯誤；LLM 端點、/health，以及 /metrics 會繼續運作
DISABLE_LLM_API_ENDPOINTSfalseLLM 端點（/chat/completions、/v1/*、provider pass-through routes）會回傳錯誤；管理端點會繼續運作，且 /models 仍可使用，因此 UI 可以列出模型

常見問題​

我真的需要多區域嗎？ 通常不需要。單區域部署搭配多 AZ 資料庫與 Redis，已足以在可用區故障時維持運作；請參閱 Production Best Practices。當您需要為遠端使用者降低延遲，或需要跨區域災難復原時，再新增區域。

多區域需要 Enterprise 授權嗎？ 共用資料庫拓樸本身可在開源 proxy 上執行。Enterprise 功能在各區域之間由同一份授權涵蓋，詳見 Licensing across regions。

如果主區域的資料庫當機會發生什麼事？ 所有區域都會失去資料庫存取：key 驗證會回退到快取，而管理操作會失敗，直到資料庫恢復為止。在這種架構中，資料庫是唯一的耦合點。請設定 general_settings.allow_requests_on_db_unavailable: true，讓 proxies 在故障期間仍能為已快取的 keys 繼續提供流量（請參閱 優雅處理資料庫無法使用），以自動故障移轉方式在多個 AZ 上執行資料庫；如果這樣仍不足以提供隔離，請改用 Global Control Plane。

我可以在不同區域執行不同版本的 LiteLLM 嗎？ 可以，但僅限於 rolling upgrade 期間。請勿在穩定狀態下執行混合版本；共用資料庫 schema 會遵循最新版本，而 migration 應在每次升級時只執行一次。

LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →