用 Docker Compose 把 LiteLLM 跑成生产级 AI 网关：虚拟密钥、消费追踪与监控一次配齐

核心洞察

LiteLLM一个统一的AI模型调用接口，支持多种大型语言模型，提供标准化的API和定价信息查询功能。 这个项目解决的是一个很实际的问题：你不想为了接一个新模型就去翻一遍它家的 SDK 文档。这篇教程带你把整套网关跑起来，包括虚拟密钥LiteLLM中用于控制访问和预算的API密钥，可以设置预算限制和跟踪使用情况。、消费追踪和 Prometheus一个开源的系统监控和警报工具包，用于收集LiteLLM网关的指标数据。 监控。配置环节比较多，建议先把 .env 和 config.yaml 两个文件搞明白再动手。

---

LiteLLM 是一个开源 AI 网关，为超过 100 家大模型提供商提供统一的、兼容 OpenAI 的 API 接口。你不需要挨个对接每家 SDK 和认证方式，接一次 LiteLLM 就行。在生产环境里，团队用它来签发带预算限制的虚拟密钥、追踪各提供商的 token 用量和花费、配置集中式访问控制和路由。这篇教程会带你在 Linux 服务器上用 Docker Compose一个用于定义和运行多容器Docker应用程序的工具。在OpenClaw部署中，用于实现环境隔离、数据持久化与快速升级，是生产环境部署的首选方案。 部署 LiteLLM，后端接 PostgreSQL开源的关系型数据库管理系统，在本实现中用于存储嵌入向量和文档结构数据。 做持久化存储，Prometheus 收集指标，Traefik一个现代的反向代理和负载均衡器，用于处理TLS终止和通过Let's Encrypt自动证书配置。 做反向代理处理 HTTPS。做完之后你会得到一个完整可用的、兼容 OpenAI 的 AI 网关，通过自定义域名访问，虚拟密钥管理、消费追踪和提供商路由都已经配好。

开始之前，你需要准备：一台 Linux 服务器，至少 4 核 CPU 和 8GB 内存，用非 root 用户操作但要有 sudo 权限；装好 Docker 和 Docker Compose；一条 DNS A 记录（比如 litellm.example.com）指向服务器 IP；以及至少一家支持的 LLM 提供商的 API key。

---

核心结论

1. LiteLLM 是一个开源 AI 网关，为超过 100 家大模型提供商提供统一的、兼容 OpenAI 的 API 接口，接一次即可对接所有提供商，无需逐个适配各家 SDK 和认证方式。

2. 生产部署采用 Docker Compose 编排四个服务：Traefik 负责反向代理和 Let's Encrypt TLS 终止，LiteLLM 提供网关服务，PostgreSQL 16 持久化虚拟密钥与消费数据，Prometheus 每 15 秒抓取一次指标并保留 15 天数据。

3. 部署前需准备至少 4 核 CPU、8GB 内存的 Linux 服务器，并配置一条指向服务器 IP 的 DNS A 记录（如 litellm.example.com）。

4. LiteLLM 的 Docker 镜像已用 Cosign 签名，部署前可通过固定公钥验证 release tag（如 v1.89.1），确认镜像自发布后未被篡改。

5. 网关提供 /ui 网页管理后台，支持虚拟密钥管理、按模型/密钥/团队拆分的用量与花费追踪，且任何基于 OpenAI SDK 的应用只需将 base_url 指向网关即可直接使用。

1. 创建目录结构、配置文件和环变量

LiteLLM 需要一个配置文件来定义模型提供商和路由规则，一个 Prometheus 配置文件用来抓取指标，还需要环境变量来存密钥和数据库凭证。

1. 创建项目目录，包含持久化数据的子目录：

$ mkdir -p ~/litellm/{letsencrypt,postgres,prometheus}

letsencrypt 存 SSL/TLS 证书，postgres 持久化 PostgreSQL 数据库文件，prometheus 持久化 Prometheus 指标数据。

2. 进入项目目录：

$ cd ~/litellm

3. 给 Prometheus 宿主机目录设置匹配的属主（Prometheus 在容器内以 UID 65534 运行）：

$ sudo chown -R 65534:65534 prometheus

4. 生成 LiteLLM 的 master key 和 salt key。这条命令跑两次，生成两个不同的值：

$ openssl rand -hex 32

把两个值都记下来，下一步要填到 LITELLM_MASTER_KEY 和 LITELLM_SALT_KEY 字段里。

5. 创建 .env 文件，存放凭证和密钥：

$ nano .env

6. 填入以下内容：

DOMAIN=litellm.example.com
LETSENCRYPT_EMAIL=admin@example.com
LITELLM_MASTER_KEY=sk-YOUR_MASTER_KEY
LITELLM_SALT_KEY=sk-YOUR_SALT_KEY
LLM_PROVIDER_API_KEY=YOUR_LLM_PROVIDER_API_KEY
POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD
DATABASE_URL=postgresql://llmproxy:${POSTGRES_PASSWORD}@db:5432/litellm
UI_USERNAME=admin
UI_PASSWORD=YOUR_UI_PASSWORD

把占位符换成你自己的值。litellm.example.com 是指向服务器 IP 的域名；admin@example.com 是 Let's Encrypt 通知用的邮箱；sk-YOUR_MASTER_KEY 是管理 LiteLLM API 的管理员密钥（把 YOUR_MASTER_KEY 换成第一次生成的值，sk- 前缀保留）；sk-YOUR_SALT_KEY 用来加密存在 PostgreSQL 里的提供商凭证，第一个模型添加之后就不能再改了；YOUR_LLM_PROVIDER_API_KEY 是 config.yaml 里配置的提供商的 API key；STRONG_DATABASE_PASSWORD 是 PostgreSQL 密码，数据库容器和连接字符串都用这个；admin/YOUR_UI_PASSWORD 是 LiteLLM 面板的登录凭证。

7. 创建 LiteLLM 配置文件：

$ nano config.yaml

8. 填入以下内容：

model_list:
  - model_name: my-model
    litellm_params:
      model: provider/model
      api_key: os.environ/LLM_PROVIDER_API_KEY

litellm_settings:
  callbacks:
    - prometheus
  require_auth_for_metrics_endpoint: true

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY

my-model 换成你想在 LiteLLM 里标识这个模型的名字，provider/model 换成 LiteLLM 提供商前缀加模型标识（比如 anthropic/claude-haiku-4-5）。os.environ/ 前缀告诉 LiteLLM 运行时从环境变量读取值，而不是硬编码在文件里。litellm_settings 块通过 callbacks 字段启用 Prometheus 指标，require_auth_for_metrics_endpoint: true 把 /metrics 端点限制为需要认证的请求，这样只有 Prometheus（把 master key 作为 Bearer token 发送）才能成功抓取指标。general_settings 块定义了 LiteLLM 用来认证管理 API 请求和虚拟密钥管理操作的 master key。

9. 创建 Prometheus 配置文件：

$ nano prometheus.yml

10. 填入以下内容：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

把 sk-YOUR_MASTER_KEY 换成 .env 文件里 LITELLM_MASTER_KEY 的值。Prometheus 靠这个 token 去访问受保护的 /metrics 端点，没它抓不到数据。

2. 用 Docker Compose 部署

整套部署栈把 LiteLLM 放在 Traefik 后面，TLS 终止和 Let's Encrypt 证书签发都交给 Traefik 处理。PostgreSQL 负责持久化虚拟密钥、消费数据和用量日志。Prometheus 每 15 秒通过内部 Docker 网络抓一次 LiteLLM 的 /metrics 端点。

1. 把当前用户加进 Docker 组：

$ sudo usermod -aG docker $USER

2. 让新的组成员身份生效：

$ newgrp docker

3. 创建 Docker Compose 清单文件：

$ nano docker-compose.yaml

4. 填入以下内容：

services:
  traefik:
    image: traefik:v3.6
    container_name: traefik
    restart: always
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
      - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
      - "--certificatesresolvers.le.acme.httpchallenge=true"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt

  litellm:
    image: docker.litellm.ai/berriai/litellm:v1.89.1
    container_name: litellm
    restart: always
    volumes:
      - ./config.yaml:/app/config.yaml
    command:
      - "--config=/app/config.yaml"
    environment:
      DATABASE_URL: ${DATABASE_URL}
      STORE_MODEL_IN_DB: "True"
    env_file:
      - .env
    expose:
      - "4000"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test:
        - CMD-SHELL
        - python3 -c "import urllib.request; urllib.request.urlopen('http://localhost:4000/health/liveliness')"
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.litellm.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.litellm.entrypoints=websecure"
      - "traefik.http.routers.litellm.tls=true"
      - "traefik.http.routers.litellm.tls.certresolver=le"
      - "traefik.http.services.litellm.loadbalancer.server.port=4000"

  db:
    image: postgres:16
    container_name: litellm_db
    restart: always
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: llmproxy
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres:/var/lib/postgresql/data
    expose:
      - "5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d litellm -U llmproxy"]
      interval: 1s
      timeout: 5s
      retries: 10

  prometheus:
    image: prom/prometheus
    container_name: litellm_prometheus
    restart: always
    volumes:
      - ./prometheus:/prometheus
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    expose:
      - "9090"
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
      - "--storage.tsdb.path=/prometheus"
      - "--storage.tsdb.retention.time=15d"

这份配置在单个 HTTPS 端点后面跑了四个服务。traefik 做反向代理和 TLS 终止，把 HTTP 请求重定向到 HTTPS，证书走 Let's Encrypt。litellm 用的是固定版本号的镜像，挂载 config.yaml，启动前会等 PostgreSQL 健康检查通过。db 跑 PostgreSQL 16，持久化虚拟密钥、消费数据和用量日志。prometheus 每 15 秒抓一次 LiteLLM 的指标，数据保留 15 天。db 和 prometheus 都用了命名卷，容器删了重建数据也不会丢。

用 Cosign 验证 Docker 镜像

LiteLLM 的 Docker 镜像用 Cosign 签过名。部署前验证一下镜像签名，能确认镜像从 LiteLLM 团队发布之后没被人动过手脚。

1. 下载并安装 Cosign 二进制文件：

$ curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64"

2. 把二进制文件移到系统路径里：

$ sudo mv cosign-linux-amd64 /usr/local/bin/cosign

3. 给二进制文件加上可执行权限：

$ sudo chmod +x /usr/local/bin/cosign

4. 验证安装：

$ cosign version

5. 用固定的公钥验证 LiteLLM 镜像签名。这一步校验的是 Docker Compose 文件里部署的那个 release tag。LiteLLM 只为 ghcr.io 仓库发布签名，所以这里确认的是 v1.89.1 这个 release 本身，而不是 docker.litellm.ai 镜像的逐字节一致性。

$ cosign verify \
    --key https://raw.githubusercontent.com/BerriAI/litellm/0112e53046018d726492c814b3644b7d376029d0/cosign.pub \
    ghcr.io/berriai/litellm:v1.89.1

验证通过的话会输出一段 JSON，确认这个镜像确实是用 LiteLLM 公钥签过的。

启动整套服务

1. 启动所有服务：

$ docker compose up -d

2. 确认所有容器都在运行：

$ docker compose ps

四个容器都应该是 Up 状态，其中 litellm 和 db 后面带 (healthy)，traefik 的 PORTS 列里能看到 80 和 443。

3. 访问并配置 LiteLLM

LiteLLM 在配置好的域名下 /ui 路径提供了一个网页管理后台，可以查看模型配置、虚拟密钥、用量和花费追踪。

1. 浏览器打开 https://litellm.example.com/ui，把 litellm.example.com 换成你自己的域名。
2. 用 .env 文件里的凭据登录，Username 填 UI_USERNAME 的值，Password 填 UI_PASSWORD 的值，然后点 Login。确认仪表盘正常加载，主面板都能显示出来。
3. 点左侧边栏的 Models + Endpoints，检查配置好的模型提供商。config.yaml 里定义的模型会出现在列表里，带上别名和底层提供商模型。左侧边栏还能进 Virtual Keys 管理限定范围的访问凭据，Usage 看每个模型和每个密钥的请求量，Logs 看按模型、密钥、团队拆分的花费明细。

4. 测试网关并创建虚拟密钥

LiteLLM 暴露的是 OpenAI 兼容 API，任何基于 OpenAI SDK 的应用，只要把 base_url 指向网关就能直接用。虚拟密钥提供限定范围的、凭据隔离的访问方式，不用把主密钥LiteLLM的管理员密钥，用于认证管理API请求和虚拟密钥管理操作。暴露出去。

1. 安装 Python 虚拟环境包：

$ sudo apt install -y python3-venv

2. 创建 Python 虚拟环境：

$ python3 -m venv litellm-env

3. 激活虚拟环境：

$ source litellm-env/bin/activate

4. 安装 OpenAI Python SDK：

$ pip install openai

5. 把主密钥导出为环境变量，把 sk-YOUR_MASTER_KEY 换成 .env 文件里 LITELLM_MASTER_KEY 的值：

$ export LITELLM_MASTER_KEY="sk-YOUR_MASTER_KEY"

6. 把网关域名导出为环境变量，把 litellm.example.com 换成你配置的域名：

$ export LITELLM_DOMAIN="litellm.example.com"

7. 创建测试脚本：

$ nano test_litellm.py

8. 填入以下内容，把 my-model 换成你在 config.yaml 里设置的模型名：

import os
from openai import OpenAI

脚本会返回配置好的 LLM 提供商的响应，说明网关的路由工作正常。

10. 用 LiteLLM API 创建一个虚拟密钥，把 my-model 换成你在 config.yaml 里设置的模型名：

$ curl -X POST "https://${LITELLM_DOMAIN}/key/generate" \
    -H "Authorization: Bearer ${LITELLM_MASTER_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"key_alias": "test-app-key", "models": ["my-model"], "max_budget": 5.00}' \
    | python3 -c "import sys, json; print(json.load(sys.stdin)['key'])"

命令会打印生成的虚拟密钥，格式类似 sk-M9M0_aUDLi7AuhXtOAw6uw。每个密钥可以单独配置模型访问列表、预算上限和速率限制。

11. 导出上一步返回的虚拟密钥，把 sk-your-virtual-key 换成实际打印出来的完整密钥字符串：

$ export LITELLM_VIRTUAL_KEY="sk-your-virtual-key"

12. 用虚拟密钥发送请求，把 my-model 换成你在 config.yaml 里设置的模型名：

$ curl -X POST "https://${LITELLM_DOMAIN}/v1/chat/completions" \
    -H "Authorization: Bearer ${LITELLM_VIRTUAL_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "my-model",
      "messages": [{"role": "user", "content": "Hello from a virtual key!"}]
    }'

网关验证虚拟密钥，把请求路由到配置的提供商，然后返回模型响应。

13. 回到 https://litellm.example.com/ui 面板，点击左侧边栏的 Logs。 每条记录会显示模型别名、密钥别名、token 数量和预估费用，通过主密钥和虚拟密钥发送的请求都能看到。

后续步骤

• 往 config.yaml 里添加更多模型，为不同团队或应用签发独立的虚拟密钥，各自设置不同的预算上限。
• 基于 Prometheus 指标搭建 Grafana 面板，做网关可观测性。
• 对预算阈值和提供商请求失败设置告警。
• 定期轮换主密钥和盐密钥用于加密存储在PostgreSQL中的提供商凭证的密钥，首次添加模型后不可更改。，每次升级时重新验证 Docker 镜像签名。

完整指南和更多技巧，请访问 Vultr Docs 上的原文。

常见问题（FAQ）

LiteLLM 能解决什么问题？

LiteLLM 是开源 AI 网关，为超过 100 家大模型提供商提供统一的、兼容 OpenAI 的 API 接口。你不需要挨个对接每家 SDK 和认证方式，接一次 LiteLLM 就行，还能签发带预算限制的虚拟密钥、追踪 token 用量和花费。

部署 LiteLLM 需要准备哪些环境？

需要一台 Linux 服务器，至少 4 核 CPU 和 8GB 内存，用非 root 用户操作但要有 sudo 权限；装好 Docker 和 Docker Compose；一条 DNS A 记录指向服务器 IP；以及至少一家支持的 LLM 提供商的 API key。

LiteLLM 的 master key 和 salt key 怎么生成？

用 openssl rand -hex 32 命令跑两次，生成两个不同的值，分别填入 .env 文件的 LITELLM_MASTER_KEY 和 LITELLM_SALT_KEY 字段。salt key 用来加密存在 PostgreSQL 里的提供商凭证，第一个模型添加之后就不能再改了。