Artifact Keeper 在线数据库迁移:百万制品规模下不停机创建索引的完整指南

原创2026-10-14 11:57:551,394 阅读

Artifact Keeper 在线数据库迁移:百万制品规模下不停机创建索引的完整指南

Artifact Keeper 是一款开源的通用制品库(Universal Artifact Registry),支持 40+ 包格式、安全扫描与边缘复制。当你的仓库里沉淀了百万级制品(artifact)时,任何一次数据库迁移都可能变成一场停机事故。本文将带你了解 Artifact Keeper 的在线数据库迁移方案:如何在不阻塞上传、不中断服务的前提下,完成创建索引、回填数据等高危数据库操作。

为什么百万制品规模下,一条 CREATE INDEX 就是停机事故?

先讲清楚问题的严重性。Artifact Keeper 的制品目录表 artifacts 每上传一个制品、产生一次下载或扫描就会增长一行——在官方验收负载下轻松突破 100 万行。

此时若执行一条普通的 CREATE INDEX,PostgreSQL 会持有 SHARE 锁直到整个索引构建完成。读取可以继续,但所有写入全部排队。对于一个 7×24 小时上传下载的制品库来说,这等于直接切断上传通道。

Artifact Keeper 为"百万制品运行模型"定了一条发布红线(release gate):

部署大型索引或数据回填期间,上传与下载的 SLO 必须保持在基线的 2 倍以内。

而历史上,199 个迁移文件中有 34 个、共 47 条语句会触碰这条红线——27 条非并发索引构建、8 条带校验的约束添加、8 次全表回填、4 次列重写。它们不是写得不小心,而是工具链压根不支持在线做法,后面会讲。

相关规则与豁免清单见 backend/src/migration_safety.rs,完整运维手册见 docs/operations/online-migrations.md。

真正的障碍:sqlx 把每个迁移包在事务里

很多团队知道 CREATE INDEX CONCURRENTLY 可以做到不停机建索引,但 Artifact Keeper 曾面临一个更隐蔽的坑:

  • 项目使用 sqlx::migrate! 执行迁移,默认把每个迁移文件包在一个事务里执行;
  • 而 PostgreSQL 明确规定:CREATE INDEX CONCURRENTLY 不能在事务块内运行。

也就是说,在机制补上之前,"在迁移里在线建索引"这件事根本不存在可行路径。多个历史迁移文件只能在注释里承认这一点,并给运维一份手工操作配方。

关键钥匙:文件首行的 -- no-transaction 魔术头

sqlx 留了一个逃生舱口:如果迁移文件的第一字节起就是 -- no-transaction(无 BOM、前面不能有空行),sqlx 会跳过事务包装。

但请注意一个反直觉的约束:

文件内容 实际效果
1 条语句 ✅ 真正脱离事务
2 条及以上语句 ❌ 多语句 simple query 会被 PostgreSQL 塞进隐式事务块,等于白写

Artifact Keeper 在 postgres:16-alpine 上实测验证了这一点,并把它固化成 CI 规则:-- no-transaction 迁移文件只能包含恰好一条语句。

这意味着在线建索引的标准写法是"两个迁移文件":

  1. 一个普通事务性迁移:DROP INDEX IF EXISTS …,清理上次失败遗留的 INVALID 索引;
  2. 一个 -- no-transaction 迁移:唯一的语句就是 CREATE INDEX CONCURRENTLY IF NOT EXISTS …。

CI 安全门:让违规迁移在构建期就失败

靠开发者自觉是不可靠的,Artifact Keeper 的做法是把规则变成强制门:

  • backend/src/migration_safety.rs 对所有 backend/migrations/*.sql 做文本级扫描,检查"热表"(artifacts、download_statistics、audit_log、packages、scan_results 等)上是否出现阻塞式 DDL——包括非并发 CREATE INDEX、不带 NOT VALID 的 ADD CONSTRAINT、ALTER COLUMN … TYPE 等;
  • 新迁移在热表上加一条阻塞语句,构建直接失败;
  • 历史遗留的违规则逐条登记在 ALLOWLIST 中,注明豁免理由;allowlist 条目若不再匹配任何文件同样会报错,防止清单"悄悄腐烂"。

这个设计保证了两件事:违规在开发者的 CI 上就被拦住,而不是在生产库上炸给运维;同时旧账有记录、新账不产生。

失败如何自愈:启动期自动修复 INVALID 索引

在线建索引还有个经典难题:CREATE INDEX CONCURRENTLY 若中途失败(锁超时、Pod 被杀、手动取消),会留下一个 INVALID 状态的残留索引。更糟的是,IF NOT EXISTS 会看到这个残留并"跳过",把迁移标记为成功——而规划器永远不会使用一个 INVALID 索引。

Artifact Keeper 的解法在 backend/src/migration_repair.rs:

  • 每个在线建索引迁移都在 CONCURRENT_INDEX_MIGRATIONS 中按版本号 + 索引名注册;
  • 每次启动(只要不是 SKIP_MIGRATIONS=true)、在执行迁移之前,repair_invalid_concurrent_indexes 会检查已注册但尚未记录的迁移:若对应索引处于 INVALID 状态,先删掉再从头重建;
  • 已记录的迁移与有效索引绝不会被触碰。

配合前面"一个文件只建一个索引"的规则,失败不再是运维事故,而是一次自动重试。

五种高危操作的在线改写方案

backend/migrations/ 目录是这套规范的最佳范例,以下是文档总结的五种改写套路(详见 docs/operations/online-migrations.md):

1️⃣ 索引构建:CONCURRENTLY + 注册自愈

如前所述,一个事务性 reset 文件 + 一个单语句 -- no-transaction 文件 + 一处注册,三件套缺一不可。

2️⃣ CHECK / 外键约束:拆成"先挂上、后校验"两步

ALTER TABLE … ADD CONSTRAINT … VALIDATE 会持有 ACCESS EXCLUSIVE 锁逐行校验,阻塞一切读写。改写为两个独立迁移:

  1. ADD CONSTRAINT … NOT VALID——只登记约束、立即校验新写入的行;
  2. 后续迁移执行 VALIDATE CONSTRAINT——在 SHARE UPDATE EXCLUSIVE 锁下扫描存量数据,不阻塞写入。

⚠️ 注意:两步必须放在不同文件。PostgreSQL 锁持有到事务提交,同一文件里执行的话,校验阶段仍会被前一步的 ACCESS EXCLUSIVE 锁拖住。

3️⃣ 唯一约束:先在线建索引,再"收编"

单独执行 ADD CONSTRAINT … UNIQUE 会以 ACCESS EXCLUSIVE 锁建索引。正确姿势:先用 CREATE UNIQUE INDEX CONCURRENTLY 在线把唯一索引建好,再用 ADD CONSTRAINT … UNIQUE USING INDEX 让约束直接复用已有索引,零额外锁成本。

4️⃣ 全表回填:批处理 + 可断点续跑

绝不用一条 UPDATE 扫全表——它会锁定每一行、经 MVCC 让表堆翻倍、并挤出一个巨大的 WAL 突发。标准做法是 DO 批处理块:

  • 按主键 ORDER BY id LIMIT 5000 分批更新;
  • 每批结束 COMMIT + pg_sleep(0.05),给前台流量让路;
  • 过滤条件用"该修的行"(如 … IS NULL)而不是行数计数器,中断后重跑会从断点继续;
  • 对热表的批处理还必须设置短 lock_timeout(如 5 秒)并捕获 lock_not_available 重试,避免撞上迁移会话的 5 分钟锁超时。

5️⃣ 修改列类型:没有在线捷径,走"双列并行"

PostgreSQL 没有在线 ALTER COLUMN … TYPE。规范是四步走、跨两个版本:新增列 → 分批回填 → 应用切换到新列 → 删除旧列。唯一例外:纯 VARCHAR(n) 扩长且无 USING 子句时,PG 16 只做目录更新,可一步完成。

部署前 / 运行中 / 部署后:操作员检查清单 📋

这套 runbook 的可贵之处是给了操作员具体的命令。核心步骤如下:

部署前(避免踩坑):

  • 统计 artifacts 的存活行数,知道自己要扫多少数据;
  • 用 pg_total_relation_size('artifacts') 确认磁盘够放下"新索引 + 旧表";
  • 检查 pg_stat_activity 中是否有长事务——CREATE INDEX CONCURRENTLY 会等待所有在它之前开启的事务,包括 idle-in-transaction 的"僵尸事务"。

运行中(盯进度):

  • 通过 pg_stat_progress_create_index 查看 tuples_done / tuples_total 进度;
  • 若发现上传停了,用 pg_locks 关联 pg_stat_activity 找出持锁者;
  • SELECT pg_cancel_backend(<pid>) 可以安全取消一次在线建索引——它留下 INVALID 索引,下次启动会被启动修复自动清掉重跑,不会留下"假成功"。

部署后(验收):

  • 查询 pg_index 确认没有遗留的 INVALID 索引(INVALID 索引不被查询使用,却仍会在每次写入时维护,纯浪费);
  • 对迁移头注释里点名的那条查询执行 EXPLAIN (ANALYZE, BUFFERS),确认执行计划真的用上了新索引。

万一要回滚?Artifact Keeper 的受支持路径是给旧版本部署设置 SKIP_MIGRATIONS=true,原理与操作细节见 docs/operations/rollback.md。迁移会话本身的 lock_timeout 与 statement_timeout 则在 backend/src/main.rs 中统一定义为 5 分钟与 30 分钟。

这套方案对普通用户的价值

传统方式 Artifact Keeper 在线迁移
建索引 = 上传暂停若干分钟 上传/下载 SLO 保持在基线 2 倍内
失败靠人工善后 启动期自动识别并清理 INVALID 索引,重试即恢复
全表回填一次提交,WAL 风暴 5000 行一批、限流、可断点续跑
违规靠 code review 自觉 CI 安全门强制拦截,历史违规逐条登记

对于新手来说,理解这套机制最大的收获是一条通用经验:在 PostgreSQL 上做大型数据变更,先想"锁"再想"SQL";而 Artifact Keeper 的贡献,是把这条经验固化成了从迁移文件首行、CI 检查到启动自愈的完整闭环。

如果你想动手验证,建议按顺序阅读:

  1. docs/operations/online-migrations.md —— 完整 runbook 与锁对照表;
  2. backend/src/migration_safety.rs —— CI 安全门的判定逻辑与 allowlist;
  3. backend/src/migration_repair.rs —— 启动期 INVALID 索引修复;
  4. 挑几个 -- no-transaction 开头的迁移文件,对照 docs/operations/rollback.md 看失败与回滚路径。
登录后查看全文
artifact-keeper