部署前的环境检查

  • 1 台 Linux 服务器（Ubuntu 22.04+，2 vCPU + 4GB RAM 推荐）
  • 一个域名（如 llm.yourdomain.com，A 记录指向服务器）
  • 至少 1 个 LLM provider 的 key（Anthropic / OpenAI / 中转任选）
  • Docker + Docker Compose 已装好

部署步骤

Step 1：项目结构

~/litellm/
├── docker-compose.yml
├── config.yaml
├── .env
└── Caddyfile

Step 2：docker-compose.yml

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:4000:4000"
    env_file:
      - .env
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: litellm
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data

Step 3：.env

LITELLM_MASTER_KEY=sk-master-xxx-rotate-monthly
LITELLM_SALT_KEY=随机 32 字节字符串
UI_USERNAME=admin
UI_PASSWORD=换成强密码
DATABASE_URL=postgresql://litellm:你的密码@postgres:5432/litellm
POSTGRES_PASSWORD=你的密码

ANTHROPIC_API_KEY=sk-ant-xxx
OPENAI_API_KEY=sk-xxx

Step 4：config.yaml

model_list:
  - model_name: chat-main
    litellm_params:
      model: anthropic/claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: chat-main
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: chat-fast
    litellm_params:
      model: anthropic/claude-3-5-haiku-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  routing_strategy: simple-shuffle
  num_retries: 2
  fallbacks:
    - chat-main: ["chat-fast"]

general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  database_url: os.environ/DATABASE_URL

Step 5：Caddyfile

llm.yourdomain.com {
    reverse_proxy 127.0.0.1:4000
    encode gzip
}

Step 6：启动

cd ~/litellm
docker compose up -d
docker compose logs -f litellm

5-10 秒后访问 https://llm.yourdomain.com/ui 看到登录页即成功。

安全加固

1. UI 启用 SSO（可选）

config.yaml 加：

general_settings:
  ui_access_mode: admin_only
  microsoft_client_id: ...   # 如果用 Azure AD SSO

2. 速率限制

Caddyfile 加：

llm.yourdomain.com {
    rate_limit {
        zone llm {
            key {remote_host}
            events 100
            window 1m
        }
    }
    reverse_proxy 127.0.0.1:4000
}

3. 备份脚本

backup.sh，每日 cron：

#!/bin/bash
docker compose exec -T postgres pg_dump -U litellm litellm | gzip > /backups/litellm-$(date +%F).sql.gz
# 保留最近 30 天
find /backups -name 'litellm-*.sql.gz' -mtime +30 -delete

4. 监控

config.yaml 加：

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]

设置 LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY 环境变量。

或直接用内置 Prometheus：

litellm_settings:
  callbacks: ["prometheus"]

访问 https://llm.yourdomain.com/metrics 抓 Prometheus metrics。

常见失败原因

  • 启动报「Database connection failed」：检查 DATABASE_URL 用户密码
  • UI 进不去：检查 UI_USERNAME / UI_PASSWORD 是否在 .env
  • 调用报 401：用的不是 master key 或者子 key 过期
  • /metrics 404：忘了配 callbacks [“prometheus”]

跨地区访问

LiteLLM Proxy 部署在境外服务器（Hetzner / DigitalOcean）的话，从国内调用域名需要稳定网络。可以把 LiteLLM Proxy 本身作为一个 channel 套进中转方，国内用户走中转转发到你的 LiteLLM 实例，既保留子 key 管理能力又解决国内访问问题。

运维备忘

一个人管 LiteLLM 实例建议建一张简单的运维记录表：负责人是谁、后台入口在哪里、证书什么时候过期、谁在付服务器费用、出问题时回滚到哪个版本。换服务器或迁数据库的时候，没有这张表很容易漏掉关键资料。

LiteLLM Proxy 自托管的准备材料

一个人运营时可以用表格压住复杂度：负责人、后台入口、到期日、费用来源和回滚动作各占一列，避免换服务商时才发现资料缺口。

涉及 Stripe、公司注册、税表或签证的内容，只能作为操作参考。当前页面没有覆盖你所在司法辖区的特殊规定时，不应把它当成法律或税务意见。

LiteLLM Proxy 自托管最怕把法律主体、收款工具和产品代码混成一个问题。动手前看清失败提示、回滚动作和费用影响，金额较大或涉及税务时应交给专业顾问处理。

项目看什么不宜继续的信号
失败提示当前后台、日志或设置页里能直接看到的字段页面提示和手头资料对不上
回滚动作费用、权限、地区或设备造成的实际影响已经影响付款、审核、生产环境或家庭使用
费用影响回退入口、旧配置、官方支持材料找不到回滚方式，或责任人无法确认

相关阅读