---
title: "自建 LiteLLM 模型网关：虚拟密钥、预算控制，以及与 New API、Magpie 的选型对比"
description: "用 Zenavo 模板一键部署带 PostgreSQL 的 LiteLLM 模型代理，通过 /ui 管理后台配置多家大模型、发放带预算上限的虚拟密钥，并对比 LiteLLM、New API 与 Magpie 三种开源网关的适用场景。"
date: 2026-11-13
language: zh-CN
url: https://zenavo.app/zh-CN/blog/self-host-litellm
---

# 自建 LiteLLM 模型网关：虚拟密钥、预算控制，以及与 New API、Magpie 的选型对比

做 AI 应用或带团队用大模型时，把上游服务商的主 API Key 直接塞进各个客户端或代码仓库里，既没法限制单个项目能花多少钱，换密钥时还要到处改配置。[LiteLLM](https://github.com/BerriAI/litellm) 是目前 Python 与 AI 工程生态里最常用的开源模型代理（LLM Proxy）：它把 100 多家模型服务商统一成标准 OpenAI 接口，自带 `/ui` 管理后台、虚拟密钥（Virtual Keys）、预算上限（Budgets）和每次调用的费用日志。

这篇文章用 Zenavo 的 LiteLLM 模板，把 LiteLLM 连同 PostgreSQL 数据库一起部署到你自己的服务器上，并对比它与 **New API**、**Magpie** 的选型差异。服务器、Zenavo 平台和上游模型 API 分别计费。

## 1. 部署 LiteLLM 与 PostgreSQL

先在 Zenavo 中[连接一台 Linux 服务器](https://docs.zenavo.app/zh-CN/servers/add-a-server)（建议预留 1 GB 以上内存），再打开 [LiteLLM 模板](https://zenavo.app/deploy?template=litellm)，选择服务器并部署。

部署后项目里有两项服务，通过[项目私有网络](https://docs.zenavo.app/zh-CN/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` 后台和管理接口 |
| `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-CN/blog/self-host-vaultwarden)）中备份。

## 2. 绑定域名并登录 `/ui` 管理后台

1. 在 `litellm` 服务的 **网络（Networking）** 页为 `4000` 端口绑定自定义域名，例如 `llm.example.com`，并在 DNS 添加指向服务器的 `A` 记录。详见[域名与 HTTPS](https://docs.zenavo.app/zh-CN/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-CN/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-CN/blog/self-host-new-api)接入；如果想在 Claude Code 里用 MCP 管理 Zenavo 服务，可参考[用 Claude Code 部署和调试 Zenavo 项目](https://zenavo.app/zh-CN/blog/claude-code-deploy-debug)。
- **聊天界面与智能体**：在自建的 [Open WebUI](https://zenavo.app/zh-CN/blog/self-host-open-webui)、[LobeHub](https://zenavo.app/zh-CN/blog/self-host-lobehub) 或 [OpenClaw](https://zenavo.app/zh-CN/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-CN/blog/self-host-litellm)** | 面向工程与 SDK 的 OpenAI 代理，带虚拟密钥、预算控制、護栏（Guardrails）与 Langfuse 等可观测性对接 | PostgreSQL 16 | 自研 AI 应用后端、Python/TypeScript 工程团队按项目/服务管控预算与调用日志 |
| **[New API](https://zenavo.app/zh-CN/blog/self-host-new-api)** | 多租户模型分发与记账中心，自带用户注册/登录、令牌管理、渠道权重与额度面板 | 默认 SQLite（`/data`） | 给团队多位成员按人发放账号或令牌，统一接入 Open WebUI、LobeHub、Claude Code 与 Codex |
| **[Magpie](https://zenavo.app/zh-CN/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-CN/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-CN/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 收拢到受预算保护的虚拟密钥后面。