自托管Sentry升级遇Django迁移冲突：table already exists排查与修复

自托管 Sentry 升级跑到一半终端突然甩出一行django.db.utils.OperationalError: table labels_manager_label already exists紧接着就是Sentry is attempting ...的提示。第一次碰到时我也愣了一下明明是新装的环境怎么数据库里已经有表了后来排查下来才发现这根本不是 Sentry 特有的问题而是 Django 迁移里非常典型的“表已存在但迁移记录缺失”状态。这篇文章就围绕这个报错把原理、排查步骤和修复方案完整过一遍适合自托管 Sentry 的维护者也适合遇到类似迁移冲突的 Django 开发者。1. 先还原现场这条报错通常在什么时刻炸出来1.1 两种最容易踩中的触发方式自托管 Sentry 的日常维护里升级操作是重灾区。跑官方安装脚本或者用 docker compose 执行upgrade前面的镜像拉取、配置更新都正常等到数据库迁移阶段突然中断控制台里就剩这行报错。为什么升级时特别容易踩因为每次升级都会引入新的迁移文件Django 要落一批新表只要中途出一次小意外比如容器被反复重启、网络抖动导致数据库连接受断、或者迁移进程执行到一半被外部杀掉就很容易留下半成品状态。这个“半成品”不是数据半写入而是 DDL 建表完成但迁移记账没完成。除了升级初始化新实例或重建数据库也会触发同样的坑。比如你用一个旧的数据库备份来初始化新环境备份里面可能带了labels_manager_label这张表但备份里的django_migrations记录不完整又或者你之前手动用数据库管理工具建过同名表、导入过手工 SQL都可能导致账实不符。还有一类场景是编排平台拉起容器时多个迁移进程同时启动并发竞态也会撞出这个报错。所以在排查时先想清楚自己是在哪个阶段遇到它的能省下不少摸索时间。1.2 报错文本拆解每一段英文究竟在说什么django.db.utils.OperationalError是 Django 在数据库操作层抛出的异常意思是和底层数据库交互时出了问题不是代码层面的逻辑错误。也就是说整个升级流程本身没问题是数据库当前的状态不允许继续往下走。table labels_manager_label already exists是 PostgreSQL 拒绝执行建表语句的返回结果——目标表已经躺在库里再建一次当然不行。最后那句Sentry is attempting ...说明 Sentry 正处于迁移尝试阶段它必须把数据库 schema 改成和当前版本代码匹配才允许服务继续启动。理解这行报错的关键在于“继续尝试”四个字Sentry 在迁移没有完成之前不会放行 Web 服务和后台 worker。因为它不知道代码里的labels_manager_label到底对应哪一种表结构也不敢假设数据一定存在。宁可卡在迁移这一步也不让运行时代码撞上不存在的列或索引。这种保守策略是对的但代价就是你必须手工介入把数据库实际状态和迁移记录对齐。2. Django 迁移为什么会撞上“表已存在”背后的机制2.1 迁移的记账机制django_migrationsDjango 能知道哪些迁移跑过、哪些没跑过靠的是一张叫django_migrations的表。它记录了 app 名、迁移文件名和应用时间。正常流程是这样执行某个迁移前Django 查询这张表发现没有对应记录才执行建表、建索引等 DDL全部执行成功之后再往表里插一条记录。下次再跑它确认记录存在就会跳过。问题恰恰出在“记录还没有来得及写入”的窗口期。如果CREATE TABLE执行成功但接下来写django_migrations记录之前迁移进程突然退出——容器被杀、数据库连接断开、内存不够被系统 OOM 掉——那张表就已经真实存在于数据库里而 Django 的账本上却没有。下次升级再跑到同一张表时Django 看账本觉得没迁移过于是又来一次CREATE TABLEPostgreSQL 直接拒绝报出already exists。打个比方就像去医院做检查检查已经做完了但分诊系统里没登记第二天系统又让你重做一遍做检查的医生说你这单子早就开过于是撞车。Django 迁移的账本和真实表结构必须保持同步否则就会出现这类问题。理解了这一点后面所有的修复思路其实都围绕一件事让账本和真实状态重新对齐。2.2 为什么偏偏是 labels_manager_labellabels_manager是 Sentry 内部的标签管理模块labels_manager_label这张表在版本升级时由代码自动创建。它不是用户日常会手动维护的表所以排查方向应该集中在新版本引入的迁移上。最典型的场景是从旧版本跳到新版本时升级脚本执行到这个新模块的初始迁移恰好赶上一次中断。表建完了记录没写进django_migrations于是变成一个永远对不上账的残留。还有一种情况是环境迁移你把生产库的数据备份恢复到另一台机器备份数据里带了这张表但备份时间点早于这条迁移记录或者恢复过程把django_migrations表的一部分给截掉了。更隐蔽的一种是并发竞态如果你用 docker compose 的方式让多个容器同时执行迁移两个进程可能同时查询账本发现都没有记录于是一起建表后完成的一方就会撞车。这种情况在自动扩容、编排平台重复拉起容器时特别容易出现。不管来源是哪一种处理路径都一致先看表里有没有数据再对照迁移记录决定是删除重建还是补记录。3. 动手排查三分钟定位残留与缺失3.1 第一步确认实体表与数据量先确认这张表是不是真的存在、里面有多少数据避免在错误的假设上操作。如果用的是 docker compose 部署可以进 postgres 容器直接查。命令大概是docker compose exec postgres psql -U postgres -d sentry -c SELECT count(*) FROM labels_manager_label;如果你的容器名、数据库名或密码和默认配置不同按实际部署环境调整数据库名通常叫sentry。执行成功后结果可能有两种0表示这张表是个空壳大于 0 表示表里有历史数据。这条信息几乎决定了后面的修复方向空表可以直接删除重跑有数据的表就得考虑保留数据、伪造迁移记录。注意这里不要用SELECT *去刷这张表数据量大时会把注意力带偏先看 count 就够了。如果连查询都报“relation does not exist”说明表其实不在库里那是另一个方向的问题本文不展开。3.2 第二步对照 django_migrations 迁移记录接着查 Django 的迁移账本看labels_manager这个 app 到底有没有已应用记录SELECT id, app, name, applied FROM django_migrations WHERE app labels_manager ORDER BY id;如果查询结果为空说明账本里根本没有这个 app 的迁移记录和表已存在的情况形成了典型冲突。如果结果只有部分记录例如只有0002_xxx而没有0001_initial同样要做进一步对照。再去 Sentry 安装目录里看看这个 app 实际有哪些迁移文件。通常在容器内可以这样找find / -type d -path *labels_manager*migrations* 2/dev/null找到目录后ls -1看一下文件名把文件列表和账本里的记录做差集就能知道哪些迁移缺失、应该补哪些。这一步虽然多花两分钟但能避免后面补错名字。迁移文件名必须精准匹配Django 是靠这个做判断的。3.3 第三步判断残留来源判断残留来源能帮你避免下次再犯。你可以反问自己三个问题最近跑过upgrade吗如果跑过并且中途失败过那大概率是中断残留。有没有用旧备份恢复过数据库恢复时如果备份时间点和迁移记录之间有间隔就会造成表存在但记录缺失。有没有用多个方式同时触发迁移比如一边跑自动脚本一边手工执行升级命令造成的并发竞态也可能留下同样痕迹。多数情况下答案是第一个升级中断残留。少数情况是备份恢复导致。不管来源如何确认之后进入下一环节选择适合自己的修复方案。关键是不要在没确认数据量之前盲目删表那一步错下去就真的要把数据找回来了。4. 修复方案二选一数据去留决定操作进入修复之前先明确一个判断原则如果表里有数据且这些数据是业务运行产生的优先选择补迁移记录如果表是空壳或者数据可以完整丢弃删除重建更省事。拿不准时走补记录方案更保守因为它不碰数据本身。下面两条路径都给出完整步骤先想清楚自己属于哪一种。4.1 方案A确认残留表是空壳清掉重迁最省事的路径前提是表里确实没数据。直接删表再重新执行升级迁移。删除之前强烈建议先做一次数据库备份哪怕确认是空表备份成本也很低docker compose exec postgres pg_dump -U postgres sentry sentry_backup_$(date %F).sql备份之后执行删除docker compose exec postgres psql -U postgres -d sentry -c DROP TABLE IF EXISTS labels_manager_label;这里有一个容易被忽略的坑如果这张表被其他表以外键的方式引用DROP TABLE会被拒绝。这时候不要随手加CASCADE应该先把引用关系查清楚确认被连带删除的都是无关紧要的表再用。对 Sentry 的正常版本迁移来说这张表多数是独立残留直接删掉就能继续跑。删除后重新执行升级命令docker compose run --rm sentry upgrade --noinput如果顺利跑完说明问题解决。如果又冒出另一张表的already exists说明历史上中断的不止一张表重复同样的步骤处理即可。但每张表都要重新做一次数据量确认不要因为第一张表是空表就想当然地认为后面所有表都是空表。4.2 方案B表里有历史数据必须标记迁移当表里有数据时直接删表风险很高。这些数据可能是旧版本里真实产生的标签记录删除后再重建会变成空表后续功能可能出现查不到历史标签的连锁问题。更好的方式是让 Django 认为这些迁移已经执行过也就是在django_migrations里补上缺失的记录。操作分三步。第一步找到这个 app 缺失的迁移文件名这一步在 3.2 节已经做了。第二步确认当前账本里确实没有对应的 app 和 name。第三步插入记录。可以用下面这段幂等 SQL在有备份的前提下直接执行INSERT INTO django_migrations (app, name, applied) SELECT labels_manager, 0001_initial, now() WHERE NOT EXISTS ( SELECT 1 FROM django_migrations WHERE app labels_manager AND name 0001_initial );如果有多个迁移名缺失把上面语句复制多份换掉name的值逐个执行。这里有三个细节必须注意name必须和迁移文件名字完全一致大小写、扩展名都别搞错Django 靠这个做匹配app必须写成labels_manager不能写表名labels_manager_labelapplied可以写当前时间但不要留空Django 排序迁移时依赖这个字段。如果你用的是标准 Django 项目也可以直接用 MigrationRecorder 完成同样的事下面这段逻辑与 SQL 完全等价from django.db.migrations.recorder import MigrationRecorder from datetime import datetime MigrationRecorder.Migration.objects.get_or_create( applabels_manager, name0001_initial, defaults{applied: datetime.now()} )考虑到 Sentry 容器的管理命令入口在不同版本里略有差异直接在django_migrations表里补记录是最可控、最少依赖环境的方式。补完之后再跑一次 upgrade就能跳过这些已补记的迁移继续执行后面的部分。4.3 修复后验证无论选了哪条路跑完 upgrade 都要做验证。首先重新查询django_migrationsSELECT app, name, applied FROM django_migrations WHERE app labels_manager ORDER BY id;确认缺失记录已经补上或者原来的记录与表状态一致。其次确认 Sentry Web 能正常响应容器日志里不再出现迁移相关报错。最后如果你业务里确实用到标签功能去界面上看历史标签是否正常显示——这一步虽然简单但最能验证方案 B 是否真的保住了数据。完整流程走完这个table already exists的问题才算闭环。5. 这条迁移坑还会不会再见连锁反应与预防5.1 修复一半继续报错的连锁场景这种迁移问题还容易演变成连环坑。你按方案 A 删掉一张表后跑 upgrade结果系统又报下一张表 already exists说明中断时不止留了一张残留。这时候继续用相同思路处理即可但不要为了省事把所有疑似表一次性删掉——你无法确认每张表是不是空壳删错了数据就真的没了。补记录时同样要注意依赖顺序。如果labels_manager后续还有0002_xxx、0003_xxx等迁移补记录时应该从0001_initial开始往后来不要跳过中间的版本直接补靠后的名字。Django 的迁移是按文件顺序执行的中间缺失时直接跳层会留下隐患后续版本升级很可能再次对账失败。最好每补一个迁移就查一次账确认顺序没问题。5.2 自托管升级的操作纪律经历过一次这种折腾后我现在对自托管 Sentry 的升级操作有几条固定纪律。升级之前一定做一次全量备份哪怕只是小版本更新备份的收益远大于成本。升级期间只允许一个迁移实例在跑把 Web、Worker 临时停掉只保留数据库和迁移执行容器避免并发竞态。同时记录当前 Sentry 版本与目标版本排查时对照迁移文件会快很多。还建议在测试环境里先完整跑一遍升级流程确认迁移全部通过后再上生产。这不是什么高深技巧纯粹是避免夜里改到一半对着数据库干瞪眼的土办法但非常有效。如果用的是 docker compose升级命令尽量固定为同一个入口不要一个用脚本、一个用手工命令交叉执行时最容易埋竞态隐患。5.3 Django 迁移红线不要随意 DROP 有条数据最后说一条我觉得值得反复强调的红线不要因为报错是already exists就把目光只盯在“删表”上。Django 项目里django_migrations这张表就是 schema 的账本真实表结构和账本不一致时删表和补账要按实际情况选择。表里有数据优先补账表是空壳才考虑删表重迁。至于 Sentry 这个具体场景标签表往往和 issue 分组等核心元数据有业务关联删错了不会马上在内存里炸给人看等到查历史数据时才会发现少了一块。所以动手前多做一次备份、多查一眼账本这种摩擦成本比深夜补救数据库要便宜得多。