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

做 AI 应用或带团队用大模型时，把上游服务商的主 API Key 直接塞进各个客户端或代码仓库里，既没法限制单个项目能花多少钱，换密钥时还要到处改配置。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 服务器（建议预留 1 GB 以上内存），再打开 LiteLLM 模板，选择服务器并部署。

部署后项目里有两项服务，通过项目私有网络自动连通：

服务 / 变量	值或用途
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）中备份。

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

1. 在 litellm 服务的 网络（Networking） 页为 4000 端口绑定自定义域名，例如 llm.example.com，并在 DNS 添加指向服务器的 A 记录。详见域名与 HTTPS。
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 全栈应用），直接走内网 http://litellm.zenavo.internal:4000/v1，延迟更低且不走公网。
• Claude Code 与 Codex CLI：LiteLLM 同样支持 /v1/messages 与 /v1/responses 路由，可按 New API 教程中的环境变量配置接入；如果想在 Claude Code 里用 MCP 管理 Zenavo 服务，可参考用 Claude Code 部署和调试 Zenavo 项目。
• 聊天界面与智能体：在自建的 Open WebUI、LobeHub 或 OpenClaw 中，把 OpenAI 代理地址设为 https://llm.example.com/v1（同项目内网为 http://litellm.zenavo.internal:4000/v1）即可。

5. LiteLLM vs New API vs Magpie：三个网关怎么选？

Zenavo 模板库提供了三款定位不同的开源模型网关，你可以按使用场景挑最合适的一款（甚至组合使用）：

网关模板	核心定位	持久层	最适合的场景
LiteLLM	面向工程与 SDK 的 OpenAI 代理，带虚拟密钥、预算控制、護栏（Guardrails）与 Langfuse 等可观测性对接	PostgreSQL 16	自研 AI 应用后端、Python/TypeScript 工程团队按项目/服务管控预算与调用日志
New API	多租户模型分发与记账中心，自带用户注册/登录、令牌管理、渠道权重与额度面板	默认 SQLite（/data）	给团队多位成员按人发放账号或令牌，统一接入 Open WebUI、LobeHub、Claude Code 与 Codex
Magpie	轻量单容器多协议网关，支持在 Anthropic Messages、OpenAI Responses/Chat 与 Gemini 之间互转，支持 API Key 与订阅账号故障切换	/config 数据卷	个人开发者或小团队用 Claude Code、Codex CLI 写代码，想跨协议调 DeepSeek/Gemini 并提供 /me 自助看板

6. 备份与升级

LiteLLM 的所有模型配置、虚拟密钥和消费记录都保存在 postgresql 服务中：

1. 打开 postgresql 服务的 备份与恢复（Backup & Restore） 页，创建数据库备份并下载留存，还可以开启定时自动备份。详见备份与恢复文档。
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 一键诊断日志。

在 /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 模板，几分钟就能在自己的服务器上搭好带 PostgreSQL 的模型代理，把散落在各处的 API Key 收拢到受预算保护的虚拟密钥后面。