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