部署运维-LiteLLM 网关与多账号池：个人和团队部署

本文档为基于 Debian Linux + Docker + LiteLLM 搭建大模型（OpenAI / Codex / Claude 等）反向代理网关与智能账号池的完整实战指南。涵盖架构设计、极简个人版与企业团队版的选型部署、客户端接入方法以及高频避坑解决方案。

1. 架构选型对比：个人版 vs 团队版

根据实际使用场景与硬件资源，选择适合的部署模式：

维度	个人极简轻量版（方案 A）	团队多租户配额版（方案 B）
底层组件	纯 LiteLLM 容器（无外部数据库）	LiteLLM + PostgreSQL (+ Redis 可选)
内存/CPU 占用	内存 < 40MB，单核 CPU < 0.5%	内存 250MB~500MB，单核 CPU 约 1%~3%
调度与容灾	原生支持账号池轮询、429 自动熔断、故障切号	原生支持账号池轮询、429 自动熔断、故障切号
密钥鉴权方式	统一使用管理员 `master_key` 调用	对外分发各自独立的虚拟 Key（Virtual Key）
预算/配额限制	不支持（所有客户端共享上游真实总配额）	支持（可为每个用户设置月度额度 `max_budget` 与过期时间）
Web UI 与审计	无 Web 页面，无数据库调用明细	提供可视化 Web 管理后台，记录完整日志与花费统计
适用场景	个人编程助手、小型独立 VPS、避免高资源占用	团队共享、组织分发、商业转售、多成员配额隔离

2. 基础系统准备（Debian 11/12）

2.1 解决 Docker 官方源安装问题

Debian 官方默认仓库未收录 docker-compose-plugin，需配置 Docker 官方源以获取最新版 Docker CE 与 Compose V2：

# 1. 更新系统索引并安装基础依赖
sudo apt update && sudo apt install -y ca-certificates curl gnupg lsb-release

# 2. 信任并添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 3. 写入 Docker 官方 APT 仓库源
echo   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 4. 更新源并安装 Docker 套件
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 5. 启动 Docker 并设置开机自启
sudo systemctl enable --now docker

2.2 创建标准工作目录

1	mkdir -p /opt/litellm && cd /opt/litellm

3. 方案 A：个人极简轻量版部署（推荐单人/小内存 VPS）

该方案不引入数据库，所有账号状态与 429 熔断在内存中运行，零资源冗余，彻底杜绝 CPU 占满问题。

3.1 环境变量配置：`.env`

1	nano /opt/litellm/.env

填入上游真实 Key 与网关主 Key（采用 Service Account sk-svcacct-... 更安全）：

OPENAI_KEY_ACCOUNT1=sk-svcacct-account1-xxxxxxxxxxxxxx
OPENAI_KEY_ACCOUNT2=sk-svcacct-account2-xxxxxxxxxxxxxx
OPENAI_KEY_ACCOUNT3=sk-svcacct-account3-xxxxxxxxxxxxxx
LITELLM_MASTER_KEY=sk-litellm-master-secret-key-change-me

3.2 路由与账号池配置：`config.yaml`

1	nano /opt/litellm/config.yaml

注意：同一账号池内的 model_name 必须完全相同。

model_list:
  # 账号 1
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: "os.environ/OPENAI_KEY_ACCOUNT1"

  # 账号 2
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: "os.environ/OPENAI_KEY_ACCOUNT2"

  # 账号 3
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: "os.environ/OPENAI_KEY_ACCOUNT3"

router_settings:
  routing_strategy: "least-busy"       # 调度策略：最小负载优先 (可选 simple-shuffle)
  num_retries: 3                       # 遇到故障/限流自动切号重试最大次数
  retry_after: 1                       # 重试间隔（秒）
  timeout: 30                          # 超时限制（秒）
  cooldown_time: 60                    # 触发 429 后该 Key 自动挂起冷却的时间（秒）
  allowed_fails: 1                     # 连续失败次数达到阈值后进入冷却
  enable_pre_call_checks: false        # 关闭死循环主动健康探测，降低 CPU 消耗

general_settings:
  master_key: "os.environ/LITELLM_MASTER_KEY"

3.3 容器编排：`docker-compose.yml`

1	nano /opt/litellm/docker-compose.yml

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest   # 使用轻量无 DB 镜像
    container_name: litellm-proxy
    restart: always
    ports:
      - "4000:4000"
    env_file:
      - .env
    environment:
      - LITELLM_TELEMETRY=False                 # 关闭遥测，节省资源
      - LITELLM_MODE=PRODUCTION
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml", "--port", "4000", "--num_workers", "1"]

3.4 启动与验证

1 2	docker compose up -d docker compose logs -f litellm

4. 方案 B：团队多租户配额版部署（带数据库与 Web UI）

适用于需要分发虚拟 Key、设置月度限额与审计日志的场景。已集成防 CPU 100% 优化参数。

4.1 配置文件规划

.env 与 config.yaml 内容与方案 A 一致。

4.2 容器编排：`docker-compose.yml`

1	nano /opt/litellm/docker-compose.yml

services:
  litellm:
    image: ghcr.io/berriai/litellm-database:main-latest
    container_name: litellm-proxy
    restart: always
    ports:
      - "4000:4000"
    env_file:
      - .env
    environment:
      - DATABASE_URL=postgresql://postgres:litellmpassword@postgres:5432/litellm
      - STORE_MODEL_IN_DB=False                # 关键：避免模型库高频轮询打满 CPU
      - DISABLE_PRISMA_SCHEMA_UPDATE=True      # 关闭启动时重复重构数据表
      - LITELLM_TELEMETRY=False                # 关闭后台遥测
      - LITELLM_MODE=PRODUCTION
    volumes:
      - ./config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml", "--port", "4000", "--num_workers", "1"]
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    container_name: litellm-postgres
    restart: always
    environment:
      POSTGRES_DB: litellm
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: litellmpassword
    volumes:
      - postgres_data:/var/lib/postgresql/data
    deploy:
      resources:
        limits:
          memory: 150M                         # 限制数据库内存

volumes:
  postgres_data:

4.3 生成与管理虚拟 Key（Virtual Key）

服务启动后，使用 master_key 为团队成员分发独立令牌：

API 生成带有 50 美元限额的虚拟 Key：

curl -X POST "http://localhost:4000/key/generate"     -H "Authorization: Bearer sk-litellm-master-secret-key-change-me"     -H "Content-Type: application/json"     -d '{
    "models": ["gpt-4o"],
    "max_budget": 50,
    "duration": "30d",
    "metadata": {"user": "team-member-alice"}
  }'

Web UI 管理后台：在浏览器访问 http://<服务器公网IP>:4000/ui，使用 LITELLM_MASTER_KEY 登录，可在图形化界面直观分配 Key、查看各 Key 已用额度与图表。

5. 客户端接入指南

无论是个人版（使用 master_key）还是团队版（使用生成的虚拟 Key），接入方式完全一致：

5.1 接入三要素

Base URL：http://<服务器IP>:4000/v1（必须以 /v1 结尾）
API Key：个人版填 LITELLM_MASTER_KEY，团队版填生成的 sk-... 虚拟 Key。
Model：gpt-4o（必须与 config.yaml 中的 model_name 一致）。

5.2 接入方式示例

VS Code 插件（Continue：~/.continue/config.json）：

{
  "models": [
    {
      "title": "LiteLLM-Relay",
      "provider": "openai",
      "model": "gpt-4o",
      "apiBase": "http://<服务器IP>:4000/v1",
      "apiKey": "sk-your-virtual-or-master-key"
    }
  ]
}

终端全局环境变量（Linux / macOS）：

1 2	export OPENAI_BASE_URL="http://<服务器IP>:4000/v1" export OPENAI_API_KEY="sk-your-virtual-or-master-key"

Python SDK：

from openai import OpenAI

client = OpenAI(
    base_url="http://<服务器IP>:4000/v1",
    api_key="sk-your-virtual-or-master-key"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Ping"}],
    stream=True
)
for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

6. 实战避坑指南（核心经验）

坑 1：中转站一开，单核 CPU 占用 100%，服务器/SSH 卡死

根因：
1. Docker 容器启动了多 Worker（如 --num_workers 4），在单核 VPS 上引发严重的 CPU 上下文切换。
2. 启用了 STORE_MODEL_IN_DB=True，后台高频轮询数据库造成 busy-wait。
3. config.yaml 开启了 enable_pre_call_checks: true 死循环健康检查。
解法：
1. command 中显式指定 --num_workers 1。
2. 环境变量设置 STORE_MODEL_IN_DB=False 和 LITELLM_TELEMETRY=False。
3. config.yaml 设置 enable_pre_call_checks: false。

坑 2：账号池未生效，请求没有轮询且不会切号

根因：在 config.yaml 中为每个账号起了不同的 model_name（如 gpt-4o-1、gpt-4o-2）。
解法：账号池聚合的依据就是 完全相同的 model_name。所有同类上游账号必须统一命名为 gpt-4o。

坑 3：Docker 与服务器 VPN / 节点代理冲突

现象 A（Docker 网桥冲突）：宿主机运行 VPN/Clash TUN 模式后，Docker 无法出网或 VPN 掉线。
- 解法：在 docker-compose.yml 中使用 network_mode: "host"，直接复用宿主机网络栈，规避 Docker 虚拟网桥与 iptables 冲突。
现象 B（容器内无法走宿主机代理）：VPS 在受限网络下，容器请求上游超时。
- 解法：在 docker-compose.yml 的 environment 中注入代理：
  1
  2
  - HTTP_PROXY=http://127.0.0.1:7890
  - HTTPS_PROXY=http://127.0.0.1:7890
现象 C（本地客户端连不上 VPS）：本地开了 TUN 模式导致访问 VPS 走代理环回。
- 解法：在本地代理客户端分流规则中，将 VPS 公网 IP 设为 DIRECT 直连。

坑 4：代码生成卡顿、迟钝或一次性吐出（SSE 流式失效）

根因：在 LiteLLM 前面套了 Nginx 反向代理，但默认开启了响应缓冲（proxy_buffering）。

解法：在 Nginx 对应 location / 配置中显式加入：

proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding on;
proxy_read_timeout 600s;

坑 5：OpenAI Key 类型选择与权限安全

选型：在 OpenAI 控制台创建 Key 时务必选择 Service Account（服务账号），生成 sk-svcacct-... 开头的密钥。
优势：权限严格限定在当前 Project 内部，与组织财务、成员管理完全物理隔离，即便泄露也不会危及整个组织。