LiteLLM 升级操作手册：1.87.0 -> 1.98.0
- 目标服务器：`192.168.4.19`（容器 `litellm`，安装目录 `/opt/litellm`）
- 计划时间：中午业务低峰执行，预计停机 20-40 秒
- 手册生成：2026-09-01
- 状态：**预检已通过，尚未执行升级**（生产仍运行 1.87.0）
---
## 一、现状与版本核实
| 项目 | 值 |
|---|---|
| 当前镜像 | `ghcr.io/berriai/litellm:1.87.0`（2026-05-23 发布） |
| 目标版本 | `v1.98.0`（2026-08-22，官方 Latest Release） |
| 更新版本情况 | `1.99.0-rc.2`、`1.100.0-rc.1` 均为 RC，生产不使用 |
| 部署方式 | docker-compose v5.3.1，`/opt/litellm/docker-compose.yml` |
| 数据库 | `postgres:16`，bind mount `/opt/litellm/postgres`，库名 `litellm` |
| 配置挂载 | `./config.yaml` -> `/app/config.yaml` |
| 关键开关 | `STORE_MODEL_IN_DB=True`、`restart: always` |
| 模型数 | 11 个 |
| 资源 | 磁盘剩 1.8T，内存 15G，DB 体积 386MB |
**为什么该升**：官方只维护最近 4 个稳定小版本（当前 1.95-1.98），1.87.0 已停止接收修复。
---
## 二、预检结论（2026-09-01 已实测，生产未受影响）
1. 镜像可用性
- `ghcr.io` 直连会卡死（11/21 层后无进展），**必须用镜像源**
- `ghcr.nju.edu.cn/berriai/litellm:1.98.0` 约 30 秒拉取完成，已在本地
- `docker.litellm.ai/berriai/litellm:1.98.0` 亦验证可拉
2. 备份可用性
- 已生成 `/opt/litellm/backup_litellm_db_20260901-020955.dump`（20MB，`pg_dump -Fc`）
- 已成功 restore 到临时库，备份有效
3. 数据库迁移
- 用克隆库实跑 1.98.0：**28 个迁移自动应用成功**
- 日志链路：`prisma migrate deploy` -> `Migration diff applied` -> `Post-migration sanity check completed`，无报错
4. 功能一致性
- 11 个模型全部注册，`/model/info` 入/出/缓存单价与 1.87 **逐项一致，0 差异**
- 真实调用通过：`qwen3.7-plus`、`deepseek-v4-flash-vision-exp` 均正常返回
5. 兼容性风险
- 1.88-1.98 release notes **无 Breaking Changes 段落**
- 已知高危 issue #33650（1.90.0 起全新库迁移静默失败）已在 **v1.90.6 修复**，且只影响全新库；本次是增量升级，不受影响
- 预检日志中无 unknown / invalid / deprecated 配置项告警
---
## 三、升级步骤
### 步骤 0：升级前再备份一次（务必，捕获当天用量数据）
```bash
cd /opt/litellm
cp config.yaml config.yaml.bak.$(date +%Y%m%d-%H%M)
cp docker-compose.yml docker-compose.yml.bak.$(date +%Y%m%d-%H%M)
docker exec litellm-postgres pg_dump -U litellm -d litellm -Fc -f /tmp/pre.dump
docker cp litellm-postgres:/tmp/pre.dump /opt/litellm/backup_before_1.98_$(date +%Y%m%d-%H%M).dump
docker exec litellm-postgres rm -f /tmp/pre.dump
ls -lh /opt/litellm/backup_before_1.98_*.dump
```
### 步骤 1：改镜像 tag
```bash
cd /opt/litellm
sed -i 's#image: ghcr.io/berriai/litellm:1.87.0#image: ghcr.nju.edu.cn/berriai/litellm:1.98.0#' docker-compose.yml
grep -n "image:" docker-compose.yml
```
### 步骤 2：重建容器（只动 litellm，postgres 不重启）
```bash
cd /opt/litellm
docker compose up -d litellm
```
### 步骤 3：盯日志确认迁移与模型加载
```bash
docker logs -f litellm
```
成功标志（顺序出现）：
- `Applying migration ...`（28 条）
- `Migration diff applied successfully` + `Post-migration sanity check completed`
- `LiteLLM: Proxy initialized with Config, Set models:` 后列出 11 个模型
- 无 `Traceback` / `ERROR`
`Ctrl+C` 退出日志跟踪。
### 步骤 4：验证
```bash
# 健康检查
curl -s http://127.0.0.1:4000/health/readiness
# 期望 {"status":"healthy","db":"connected"}
# 模型数量应为 11
curl -s http://127.0.0.1:4000/v1/models -H "Authorization: Bearer sk-xxxxxxxxxxxx" | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d['data'])); [print(' -',m['id']) for m in d['data']]"
# 实际调用一次最便宜的模型
curl -s http://127.0.0.1:4000/v1/chat/completions -H "Authorization: Bearer sk-xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"qwen3.7-plus","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'
# 确认版本
docker exec litellm litellm --version
docker inspect litellm --format "{{.Config.Image}}"
```
界面侧还要确认：
- Costs 页面 11 个模型金额正常（单位仍显示 `$`，数值为人民币口径不变）
- Usage / 预算 / Key 列表能正常打开
- Admin UI 这版从 antd/Tremor 改为 shadcn，**外观会变**，属预期
---
## 四、回滚方案
### 方案 A（首选，轻量）：改回旧镜像
1.98 新增的都是新表/新列，1.87 的 Prisma 只查询已知列，通常可直接回退：
```bash
cd /opt/litellm
sed -i 's#image: ghcr.nju.edu.cn/berriai/litellm:1.98.0#image: ghcr.io/berriai/litellm:1.87.0#' docker-compose.yml
docker compose up -d litellm
docker logs -f litellm
```
若 1.87 启动报迁移相关错误（`relation does not exist` / `migration state mismatch`），删除 1.98 新增的迁移记录后重启：
```bash
docker exec litellm-postgres psql -U litellm -d litellm -c \
"DELETE FROM \"_prisma_migrations\" WHERE migration_name > '20260514120000_add_blocked_to_proxy_model_table';"
docker compose restart litellm
```
### 方案 B（彻底）：用备份重建库
```bash
cd /opt/litellm
docker compose stop litellm
docker exec litellm-postgres psql -U litellm -d postgres -c "DROP DATABASE litellm;"
docker exec litellm-postgres psql -U litellm -d postgres -c "CREATE DATABASE litellm OWNER litellm;"
docker cp backup_before_1.98_<时间戳>.dump litellm-postgres:/tmp/r.dump
docker exec litellm-postgres pg_restore -U litellm -d litellm /tmp/r.dump --no-owner
docker exec litellm-postgres rm -f /tmp/r.dump
# 同时把 docker-compose.yml 的 image 改回 1.87.0
docker compose up -d
```
> 注意：方案 B 会丢弃备份点之后的所有用量与 Key 数据，属最后手段。
---
## 五、1.98.0 相对 1.87.0 新增的 28 个迁移（回滚清理时对照用）
```
20260520120000_add_mcp_env_vars
20260526120000_add_oauth_passthrough_to_mcp_servers
20260604120000_add_oauth2_flow_to_mcp_servers
20260605182307_add_timeout_to_mcp_server_table
20260626120000_add_mcp_tool_search_enabled
20260629000000_add_max_concurrent_requests_to_mcp_server_table
20260630120000_add_token_exchange_to_mcp_servers
20260630190000_add_budget_fallbacks_to_litellm_verification_token
20260703120000_add_token_exchange_profile_to_mcp_servers
20260710000000_add_dcr_bridge_to_mcp_server_table
20260713010000_add_ptu_columns_to_daily_team_spend
20260713230852_add_key_type_to_litellm_verification_token
20260715000000_add_issuer_to_mcp_server_table
20260717000000_add_compression_saved_tokens
20260717000000_add_mcp_server_oauth_client_table
20260718000000_add_savings_spend
20260721000000_add_sso_identity_assertion
20260724000000_add_spend_log_tool_index_start_time_idx
20260725000000_add_daily_tool_spend
20260729000000_add_reload_tracking_to_litellm_config
20260730000000_add_api_key_and_request_tags_to_managed_object_table
20260731000000_add_autorouter_savings_spend
20260803000000_add_daily_gateway_requests
20260805000000_add_autorouter_session_rollup
20260807000000_add_autorouter_session_tier_turns
20260810000000_add_verificationtoken_settings_updated_at
20260811172448_add_shadow_eval
20260813180408_add_shadow_eval_direction
```
升级前库内迁移头（回滚判定基线）：`20260514120000_add_blocked_to_proxy_model_table`
---
## 六、注意事项
- **迁移只前进不后退**：不要只改回 tag 就认为万事大吉，报迁移错时按方案 A 清理 `_prisma_migrations`
- **不要改 `LITELLM_MASTER_KEY`**：当前未在 compose 显式设置 `LITELLM_SALT_KEY`，LiteLLM 用 master key 派生加密盐，改 master key 会导致库内已存的 LLM API Key 无法解密
- **保留 1.87.0 镜像**：升级后近期不要 `docker image prune`，它是快速回滚的保险
- **1.98 会多一条启动 warning**：`register_model: model=... not in built-in cost map ... cache cost fields will default to 0`。只影响“缓存写入（cache creation）”成本统计，现有 `cache_read_input_token_cost` 照常生效（已实测单价一致）。如要消除，可在各 `model_info` 补 `cache_creation_input_token_cost`
- **1.98.0 主要新特性**（与本项目相关）：PTU 按部署计费、可调用的 routing groups、6 个 `x-litellm-response-cost-*` 响应头拆分成本、Admin UI 大改版
- 升级当天留意 SMTP 告警邮件是否正常发出（`alerting: ["email"]` 依赖 compose 中的 SMTP 变量）
---
## 七、执行确认清单
- [ ] 步骤 0 当天新备份已生成并确认文件大小
- [ ] 步骤 1 image 行已改为 `ghcr.nju.edu.cn/berriai/litellm:1.98.0`
- [ ] 步骤 3 日志出现 28 条 Applying migration 且无 ERROR
- [ ] 步骤 4 健康检查 healthy + db connected
- [ ] 步骤 4 `/v1/models` 返回 11 个模型
- [ ] 步骤 4 实际调用返回 200
- [ ] Costs 页面金额与升级前一致
- [ ] 业务侧同事确认网关可用