# 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 页面金额与升级前一致
- \[ \] 业务侧同事确认网关可用