Artifact Keeper 在线数据库迁移:百万制品规模下不停机创建索引的完整指南
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 迁移文件只能包含恰好一条语句。
这意味着在线建索引的标准写法是"两个迁移文件":
- 一个普通事务性迁移:
DROP INDEX IF EXISTS …,清理上次失败遗留的 INVALID 索引; - 一个
-- 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 锁逐行校验,阻塞一切读写。改写为两个独立迁移:
ADD CONSTRAINT … NOT VALID——只登记约束、立即校验新写入的行;- 后续迁移执行
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 检查到启动自愈的完整闭环。
如果你想动手验证,建议按顺序阅读:
- docs/operations/online-migrations.md —— 完整 runbook 与锁对照表;
- backend/src/migration_safety.rs —— CI 安全门的判定逻辑与 allowlist;
- backend/src/migration_repair.rs —— 启动期 INVALID 索引修复;
- 挑几个
-- no-transaction开头的迁移文件,对照 docs/operations/rollback.md 看失败与回滚路径。