---
title: "自架 LiteLLM 模型閘道：虛擬金鑰、預算控制，以及與 New API、Magpie 的選型比較"
description: "用 Zenavo 範本一鍵部署附 PostgreSQL 的 LiteLLM 模型代理，透過 /ui 管理後台設定多家大模型、發放有預算上限的虛擬金鑰，並比較 LiteLLM、New API 與 Magpie 三種開源閘道的適用場景。"
date: 2026-11-13
language: zh-TW
url: https://zenavo.app/zh-TW/blog/self-host-litellm
---

# 自架 LiteLLM 模型閘道：虛擬金鑰、預算控制，以及與 New API、Magpie 的選型比較

開發 AI 應用或帶團隊使用大型語言模型時，把上游服務商的主 API Key 直接放進各個用戶端或程式碼儲存庫裡，既無法限制單一專案能花多少錢，換金鑰時還要到處改設定。[LiteLLM](https://github.com/BerriAI/litellm) 是目前 Python 與 AI 工程生態裡最常使用的開源模型代理（LLM Proxy）：它把 100 多家模型服務商統一成標準 OpenAI API，內建 `/ui` 管理後台、虛擬金鑰（Virtual Keys）、預算上限（Budgets）與每次呼叫的費用日誌。

本文用 Zenavo 的 LiteLLM 範本，把 LiteLLM 連同 PostgreSQL 資料庫一起部署到你自己的伺服器上，並比較它與 **New API**、**Magpie** 的選型差異。伺服器、Zenavo 平台與上游模型 API 分別計費。

## 1. 部署 LiteLLM 與 PostgreSQL

先在 Zenavo 中[連接一台 Linux 伺服器](https://docs.zenavo.app/zh-TW/servers/add-a-server)（建議預留 1 GB 以上記憶體），再開啟 [LiteLLM 範本](https://zenavo.app/deploy?template=litellm)，選擇伺服器並部署。

部署後專案裡有兩項服務，透過[專案私有網路](https://docs.zenavo.app/zh-TW/networking/private)自動連通：

| 服務 / 變數 | 值或用途 |
|---|---|
| `litellm` | 映像檔 `ghcr.io/berriai/litellm:v1.109.1`，HTTP 連接埠 `4000` |
| `postgresql` | 映像檔 `postgres:16`，資料庫 `litellm`，持久化磁碟區 `/var/lib/postgresql/data` |
| `LITELLM_MASTER_KEY` | 自動產生的 `sk-...` 主金鑰，用於登入 `/ui` 後台與管理 API |
| `LITELLM_SALT_KEY` | 自動產生的加密鹽值，用於加密存入資料庫的上游服務商 API Key |
| `STORE_MODEL_IN_DB` | `True`，允許直接在網頁後台增刪模型並持久化至 PostgreSQL |

> **切勿修改 `LITELLM_SALT_KEY`**：在你往後台新增任何上游模型憑證之後，絕對不要改動 `LITELLM_SALT_KEY`。LiteLLM 用它加密和解密資料庫裡的 API Key；一旦改動，已儲存的上游金鑰將全部無法解密。部署完請立刻把 `LITELLM_MASTER_KEY` 和 `LITELLM_SALT_KEY` 複製到密碼管理器（如自架的 [Vaultwarden](https://zenavo.app/zh-TW/blog/self-host-vaultwarden)）中備份。

## 2. 綁定網域並登入 `/ui` 管理後台

1. 在 `litellm` 服務的 **網路（Networking）** 頁為 `4000` 連接埠綁定自訂網域，例如 `llm.example.com`，並在 DNS 新增指向伺服器的 `A` 記錄。詳見[網域與 HTTPS](https://docs.zenavo.app/zh-TW/networking/domains)。
2. 在 `litellm` 服務的 **變數（Variable）** 頁查看並複製 `LITELLM_MASTER_KEY`。
3. 造訪 `https://llm.example.com/ui`，使用管理員使用者名稱（預設填 `admin`）和 `LITELLM_MASTER_KEY` 登入管理面板。

`postgresql` 只走專案內網供 `litellm` 存取，不需要開啟公開存取。

## 3. 新增模型與發放虛擬金鑰

### 新增上游模型
範本已開啟 `STORE_MODEL_IN_DB="True"`，無需手動修改 YAML 設定檔：
1. 在 `/ui` 後台開啟 **Models → Add Model**。
2. 選擇服務商（如 OpenAI、Anthropic、DeepSeek、Gemini、Azure、Bedrock 等），填寫對外公開的模型別名（如 `claude-sonnet` 或 `gpt-4o`）與上游 API Key。
3. 儲存後在 **Test Key / Playground** 發送一則測試請求，確認回傳正常。

### 發放有預算上限的虛擬金鑰（Virtual Keys）
日常呼叫不要直接使用 `LITELLM_MASTER_KEY`。開啟 **Virtual Keys → Create New Key**：
- 為每個應用、隊友或工具單獨建一把金鑰（如 `nextjs-prod`、`open-webui`、`claude-code-alex`）；
- 限制這把金鑰允許呼叫的模型清單；
- 設定預算上限（`Max Budget`，例如 `$20`）與重設週期（按日 / 按月），以及速率限制（TPM / RPM）。

## 4. 串接用戶端與程式碼

任何支援自訂 OpenAI Base URL 的 SDK 或工具都能直接連上 LiteLLM：

- **應用程式碼（OpenAI SDK / LangChain / Vercel AI SDK）**：Base URL 填 `https://llm.example.com/v1`，API Key 填虛擬金鑰。如果應用也部署在同一個 Zenavo 專案裡（例如 [Next.js 全端應用](https://zenavo.app/zh-TW/blog/deploy-nextjs-postgresql)），直接走內網 `http://litellm.zenavo.internal:4000/v1`，延遲更低且不走公網。
- **Claude Code 與 Codex CLI**：LiteLLM 同樣支援 `/v1/messages` 與 `/v1/responses` 路由，可依 [New API 教學中的環境變數設定](https://zenavo.app/zh-TW/blog/self-host-new-api)串接；如果想在 Claude Code 裡透過 MCP 管理 Zenavo 服務，可參考[用 Claude Code 部署和除錯 Zenavo 專案](https://zenavo.app/zh-TW/blog/claude-code-deploy-debug)。
- **聊天介面與智慧體**：在自架的 [Open WebUI](https://zenavo.app/zh-TW/blog/self-host-open-webui)、[LobeHub](https://zenavo.app/zh-TW/blog/self-host-lobehub) 或 [OpenClaw](https://zenavo.app/zh-TW/blog/self-host-openclaw) 中，把 OpenAI 代理位址設為 `https://llm.example.com/v1`（同專案內網為 `http://litellm.zenavo.internal:4000/v1`）即可。

## 5. LiteLLM vs New API vs Magpie：三個閘道怎麼選？

Zenavo 範本庫提供了三款定位不同的開源模型閘道，你可以依使用場景挑選最合適的一款（甚至組合使用）：

| 閘道範本 | 核心定位 | 持久層 | 最合適的場景 |
|---|---|---|---|
| **[LiteLLM](https://zenavo.app/zh-TW/blog/self-host-litellm)** | 面向工程與 SDK 的 OpenAI 代理，附虛擬金鑰、預算控制、護欄（Guardrails）與 Langfuse 等可觀測性串接 | PostgreSQL 16 | 自研 AI 應用後端、Python/TypeScript 工程團隊依專案/服務控管預算與呼叫日誌 |
| **[New API](https://zenavo.app/zh-TW/blog/self-host-new-api)** | 多租戶模型分發與記帳中心，內建使用者註冊/登入、令牌管理、渠道權重與額度面板 | 預設 SQLite（`/data`） | 給團隊多位成員依人發放帳號或令牌，統一串接 Open WebUI、LobeHub、Claude Code 與 Codex |
| **[Magpie](https://zenavo.app/zh-TW/blog/self-host-magpie)** | 輕量單容器多協定閘道，支援在 Anthropic Messages、OpenAI Responses/Chat 與 Gemini 之間互轉，支援 API Key 與訂閱帳號故障切換 | `/config` 磁碟區 | 個人開發者或小團隊用 Claude Code、Codex CLI 寫程式，想跨協定呼叫 DeepSeek/Gemini 並提供 `/me` 自助看板 |

## 6. 備份與升級

LiteLLM 的所有模型設定、虛擬金鑰和消費紀錄都保存在 `postgresql` 服務中：

1. 開啟 `postgresql` 服務的 **備份與還原（Backup & Restore）** 頁，建立資料庫備份並下載留存，還可以開啟排程自動備份。詳見[備份與還原文件](https://docs.zenavo.app/zh-TW/operations/backups)。
2. 務必同時保管好 `litellm` 服務變數裡的 `LITELLM_SALT_KEY`——只有備份的資料庫加上原來的 `LITELLM_SALT_KEY`，還原後才能解開裡面儲存的上游 API Key。
3. 升級時先備份 PostgreSQL，再於 `litellm` 服務的 **設定 → 來源** 中把映像檔標籤（預設 `v1.109.1`）更新到新的穩定版本。

## 常見問題

**為什麼剛部署完造訪 `/ui` 回報 502？**
LiteLLM 啟動時需要連線 PostgreSQL 並執行 Prisma 資料庫遷移，範本設定了 40 秒的啟動健康檢查寬限期（`start_period: 40`）。等服務狀態變為 `Running` 後再開啟網頁即可；若啟動異常，可呼出控制台右側的 [Zenavo Agent](https://docs.zenavo.app/zh-TW/zenavo-agent) 一鍵診斷日誌。

**在 `/ui` 裡新增模型時提示無法寫入資料庫？**
確認 `litellm` 服務的環境變數中保留了 `STORE_MODEL_IN_DB="True"`，且 `postgresql` 服務處於 `Running` 狀態。

**虛擬金鑰回報 `BudgetExceededError`？**
代表該虛擬金鑰的累計費用已達到你設定的 `Max Budget`。可以在 `/ui` 的 **Virtual Keys** 頁面調高預算、重設消費額度，或為它設定按月自動重設。

**LiteLLM 可以和 New API 一起用嗎？**
可以。不少團隊用 New API 管理上游渠道池，再把 LiteLLM 放在應用後端前面做依微服務的預算切分與可觀測性追蹤；兩者放在同一個 Zenavo 專案裡走 `.zenavo.internal` 內網呼叫即可。

開啟 [LiteLLM 範本](https://zenavo.app/deploy?template=litellm)，幾分鐘就能在自己的伺服器上架好附 PostgreSQL 的模型代理，把散落在各處的 API Key 收攏到受預算保護的虛擬金鑰後面。