排查 Prisma 迁移错误

在使用 LiteLLM 代理版本升级或降级时遇到的常见 Prisma 迁移问题及其修复方法。

关于安全回退 LiteLLM 版本的完整指南，请参阅 安全回退指南。

Prisma 迁移在 LiteLLM 中是如何工作的

• LiteLLM 使用 Prisma 来管理其 PostgreSQL 数据库架构。
• 迁移历史记录在数据库的 _prisma_migrations 表中。
• 当 LiteLLM 启动时，它会运行 prisma migrate deploy 来应用任何新的迁移。
• 升级 LiteLLM 会应用自上次应用版本以来添加的所有迁移。

常见错误

1. relation "X" does not exist (关系“X”不存在)

错误示例

ERROR: relation "LiteLLM_DeletedTeamTable" does not exist
Migration: 20260116142756_update_deleted_keys_teams_table_routing_settings

原因：这通常发生在版本回退之后。_prisma_migrations 表仍将来自较新版本的迁移记录为“已应用”，但底层的数据库表已被修改、删除或从未完全创建。

如何修复

第一步 — 删除失败的迁移条目并重启

从历史记录中删除有问题的迁移，以便可以重新应用它

-- View recent migrations
SELECT migration_name, finished_at, rolled_back_at, logs
FROM "_prisma_migrations"
ORDER BY started_at DESC
LIMIT 10;

-- Delete the failed migration entry
DELETE FROM "_prisma_migrations"
WHERE migration_name = '<failed_migration_name>';

删除条目后，重启 LiteLLM — 它会在启动时重新应用该迁移。

第二步 — 如果无效，请使用 prisma db push

如果删除迁移条目并重启无法解决问题，请直接同步架构

警告：如果 Prisma 架构删除了数据库中现有的列或表，prisma db push 可能会导致数据丢失。仅在万不得已时使用，并确保先备份数据库。

DATABASE_URL="<your_database_url>" prisma db push

这会绕过迁移历史记录，并强制数据库架构与 Prisma 架构匹配。

---

2. New migrations cannot be applied before the error is recovered from (在从错误中恢复之前无法应用新迁移)

原因：之前的迁移失败（在 _prisma_migrations 中记录了错误），在解决该故障之前，Prisma 拒绝应用任何新迁移。

如何修复

1. 找到失败的迁移

SELECT migration_name, finished_at, rolled_back_at, logs
FROM "_prisma_migrations"
WHERE finished_at IS NULL OR rolled_back_at IS NOT NULL
ORDER BY started_at DESC;

2. 删除失败的条目并重启 LiteLLM

DELETE FROM "_prisma_migrations"
WHERE migration_name = '<failed_migration_name>';

3. 如果无效，请使用 prisma db push（参见上面的警告 — 请先备份数据库）

DATABASE_URL="<your_database_url>" prisma db push

---

3. 版本回退后的迁移状态不匹配

原因：您升级到了 X 版本（应用了新迁移），回退到了 Y 版本，然后再次升级。_prisma_migrations 表中存在部分应用或对应于不再存在的架构状态的过期迁移条目。

修复方法

1. 检查迁移表以查找有问题的条目

SELECT migration_name, started_at, finished_at, rolled_back_at, logs
FROM "_prisma_migrations"
ORDER BY started_at DESC
LIMIT 20;

2. 对于每个不应该存在的迁移（即来自您回退的那个版本），删除该条目

   DELETE FROM "_prisma_migrations" WHERE migration_name = '<migration_name>';

3. 重启 LiteLLM 以重新运行迁移。

4. 如果无效，请使用 prisma db push（参见上面的警告 — 请先备份数据库）

DATABASE_URL="<your_database_url>" prisma db push