LiteLLM Docker 部署：config.yaml、Master Key 和 Postgres 配置

这次记录 LiteLLM 的 Docker 部署思路。目标不是单纯把服务跑起来，而是把团队多个 AI 应用的模型调用入口收成一层网关：统一 OpenAI 兼容接口、虚拟 Key、预算、限流、路由、fallback、日志和健康检查。

先说明镜像口径：官方 quickstart 使用 docker.litellm.ai/berriai/litellm，这个官方自有 registry 不要强行替换。本文只在 GHCR release tag 和 Docker Hub 组件镜像预检时使用毫秒镜像前缀：

bash 复制代码

docker pull ghcr.1ms.run/berriai/litellm:<release-tag>
docker pull docker.1ms.run/postgres:17
docker pull docker.1ms.run/redis:7

镜像能拉下来以后，再看 config.yaml、.env、Postgres、Redis 和健康检查。

1. 部署目标

目标	说明
统一入口	业务应用统一访问 LiteLLM Proxy
内部模型名	业务侧不直接写供应商模型名
虚拟 Key	按应用或团队拆 Key
路由和 fallback	失败时切换到备用模型
持久化	Postgres 保存配置、Key 和预算
高流量缓冲	Redis 降低数据库压力

2. `config.yaml` 示例

yaml 复制代码

model_list:
  - model_name: team-chat
    litellm_params:
      model: openai/gpt-4o-mini
      api_key: os.environ/OPENAI_API_KEY

  - model_name: team-fallback
    litellm_params:
      model: anthropic/claude-3-5-haiku
      api_key: os.environ/ANTHROPIC_API_KEY

router_settings:
  fallbacks:
    - team-chat:
        - team-fallback

这里的重点是内部模型名。业务应用调用 team-chat，供应商模型和备用模型放在网关层维护。

3. `.env` 示例

env 复制代码

LITELLM_MASTER_KEY=sk-change-this-master-key
LITELLM_SALT_KEY=change-this-salt-key
DATABASE_URL=postgresql://litellm:password@postgres:5432/litellm
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx

注意两点：

LITELLM_MASTER_KEY 是管理入口的关键凭据，要用强随机值。
LITELLM_SALT_KEY 用于加解密 LLM API Key 凭据，添加模型后不要随意改。

4. Postgres 和 Redis

组件	作用	常见排查
Postgres	保存配置、Key、团队和预算	连接数、备份、迁移
Redis	高流量缓冲、降低 DB 压力	内存、可用性、连接
LiteLLM Proxy	统一模型调用入口	Key、路由、fallback
Prometheus	指标采集	端口、抓取配置

小规模验证可以先跑最小栈，准备上线时再把 Postgres 备份、Redis 可用性、指标采集和健康检查补齐。

5. 验证请求

示例请求：

bash 复制代码

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "team-chat",
    "messages": [
      { "role": "user", "content": "hello" }
    ]
  }'

如果请求失败，按下面顺序排：

现象	排查方向
401	Master Key 或虚拟 Key
模型不存在	`config.yaml` 的 `model_name`
上游报错	供应商 API Key、模型名、额度
fallback 不生效	`router_settings` 配置
DB 报错	Postgres URL、连接数、迁移状态
高流量卡顿	Redis、数据库连接、资源限制

6. 版本固定

生产环境不要长期依赖浮动标签。建议：

固定 release tag 或 digest。
发布记录里写清 LiteLLM 版本、配置版本和数据库迁移时间。
升级前备份 Postgres。
回滚时同时检查配置文件和数据库状态。

总结

LiteLLM Docker 部署不只是把 Proxy 跑起来。真正要做的是把模型调用入口、Key、预算、路由、fallback、数据库和健康检查放进一套可维护的流程。

毫秒镜像在这里解决的是镜像预检这一层：GHCR release tag 和 Docker Hub 组件先排掉拉取入口问题。后面仍然要继续排配置、数据库和上游模型。