自动发布敢放手,全靠「坏了能回滚」。可回滚只换代码、不换数据库,所以一次 DROP COLUMN 就能在发布那一刻让回滚失效,而所有测试照样是绿的。这篇讲 MaxClaw 怎么把 expand/contract 从约定写成落地闸上的一条机械检查。

1. 回滚到底回滚了什么⌗

MaxClaw 的发布链路大致是这样:

分支 ──► 落地通道(lane) ──► main ──► release 目录(按 git tree 不可变)
                                         │
                       current ─────────►│ 新版本,进入试用期
                       known-good ──────►│ 上一个通过试用期的版本
                                         ▼
                 guardian:试用期内启动失败 / 崩溃 → 自动切回 known-good

guardian 回滚的时候切换的是代码目录,数据库还是原来那个。新版本启动时已经跑过的迁移不会撤销,MaxClaw 也没有 down migration;旧版本的迁移运行器碰到账本里自己不认识的行,会容忍、照常启动(pg-migrate.ts 把它们归进 unknownApplied,不报错)。

所以「能回滚」这个不变量的真实含义是:

known-good 的代码,必须能在 current 的 schema 上正常运行。

加表、加列、放宽 CHECK 都不会破坏它,旧代码根本看不到新东西。会破坏它的只有删减,也就是删表、删列、删视图、删函数,以及把 CHECK 的取值列表收窄(事件类型、状态枚举在这里通常就是一个 kind = ANY (ARRAY[...]))。

2. 为什么测试抓不到⌗

设想一个很自然的分支:某个列已经没用了,于是在同一个分支里删掉所有读它的代码,再加一条 ALTER TABLE ... DROP COLUMN。

检查看的是什么结果
单元 / 集成测试新代码 + 新 schema绿:新代码已经不读这个列了
schema 漂移门迁移文件 vs expected-schema.json绿:快照已重新生成
生产预演新代码在生产数据克隆上启动绿
回滚路径旧代码 + 新 schema没有人跑

每一项检查都在验证「新版本能不能跑」,没有一项问「如果新版本跑不起来,退回去的那个版本还能不能跑」。回滚路径只有在出事的时候才会被走到,而且偏偏是在最需要它的时候才第一次被执行。

这不是假想。MaxClaw 自己的历史里就有一次:迁移 0626 在删掉所有读者的同一个 release 里 DROP 了 messages.reactions。那一版碰巧没有触发回滚,否则 guardian 会把系统切回一个 SELECT ... reactions 的版本,而这个列已经不存在了。等于自动回滚和自动发布联手把系统锁死在一个两边都起不来的状态。

3. 常见做法为什么不够⌗

业界对这个问题的标准答案是 expand/contract(也叫 parallel change):先发一版停止使用旧对象,等这版稳定了,再发一版删掉它。道理大家都懂,问题出在怎么执行:

做法问题
写进团队规范、靠 code review审的人得记得去看「上一个已发布版本」的代码,而不是 diff 里的代码。diff 里恰恰看起来最干净
写 down migration列删了数据就没了,down 只能把空列建回来;而且 down 本身也是一段只在出事时才跑的代码
允许删,出事再人工修在无人值守的自动回滚下,「出事」意味着 guardian 已经在两个都起不来的版本之间打转
加一个豁免注释豁免很快变成默认写法

MaxClaw 的分支大多由 agent 写、由落地通道无人值守地合进去,一天可能落十几次。这种节奏下「记得分两次」不是靠得住的东西。规则必须是机器能判定的。

4. 机制:快照做差,到每棵回滚树里 grep⌗

检查放在落地通道的 migration-numbers 步骤里。这一步本来就会在测试机上用真实迁移重新生成 expected-schema.json,现在多做一件事(src/landing/rollback-compat.ts,175 行):

expected-schema.json @ 合并基点 ─┐
                                ├─ schemaRemovals() ─► 删减清单
expected-schema.json @ 合并后  ─┘                       │
                                                        ▼
回滚目标 = { 合并基点, known-good, current, 试用期前任 },按 git tree id 去重
                                                        │
                    对每个 (目标, 删减):git grep <treeish> -- <运行代码路径>
                                                        │
                              有引用 ─► 落地失败(candidate),附 文件:行 + 出路
                              无引用 ─► 记一行 "N removed schema object(s) unused by ..."

4.1 删减:五种⌗

schemaRemovals(before, after) 只看减少,不看增加:

kind判定
table表在 before 里,不在 after 里
column表还在,列名没了
view视图没了
function函数名没了。只改签名(加参数)不算删
check-value同名约束前后都是 = ANY (ARRAY[...]) 形式,某个字面量没了

测试把边界钉得很清楚:before 有 quiet_turn(text),after 换成 quiet_turn(text, integer),不报;messages_bump_rev() 改了函数体,也不报;新增的列和表都不出现在结果里。改名也会被当成「删旧 + 加新」,这正是想要的结果,因为旧代码读的是旧名字。

4.2 回滚目标:不只是合并基点⌗

最容易想到的目标是「合并基点」,也就是这次落地之前的 main。但 guardian 真正会退回的是 release 指针指向的那几棵树,而它们可能比 main 落后好几次落地。productionRollbackTargets() 从 release 目录读出三个:

  • known-good release
  • current release
  • 正在试用期那一版的前任(probation.previous)

这些 release 本来就是以 git tree id 命名的,所以可以直接拿来当 git grep 的 treeish,不用另外存档。几个目标如果指向同一棵树(很常见:known-good 等于 current),先 rev-parse ^{tree} 去重,只搜一次。指向的树在仓库里找不到就直接抛错,不会悄悄跳过。

为什么一定要把 release 树也算进来?测试里有一个专门的场景:main 上的代码已经不读某张表了,可 known-good 那一版还在 SELECT id FROM main_bubbles。如果只看合并基点,这次 DROP TABLE 会被放行,回滚依然会挂。加上 release 树之后,失败信息是:

table main_bubbles is still used by known-good release <tree前12位> (src/bubbles.ts:1 ...)

4.3 什么算「引用」⌗

这部分是纯文本的启发式,规则写得很克制:

  • 路径:只搜会在生产上跑的代码(.ts/.tsx/.js/.mjs/.sql/.py/.sh),排除 *.test.ts、迁移目录本身、ui/(只走 API,不直连数据库)、bench/、docs/、node_modules、vendor。
  • 注释行不算:以 //、/*、*、--、# 开头的行跳过。
  • 按词边界匹配,reactions 不会命中 reactions_count。
  • 列:同一个文件里必须同时出现表名,命中的是提到列名的那些行。所以 SELECT reactions FROM posts 不会挡住 messages.reactions 的删除。
  • CHECK 值:同一个文件里要出现表名,并且这个值是以带引号的字面量出现的。光有一个 'ignored' 字符串、文件里却没有那张表,不算。

失败时最多列 3 处引用,多出来的写 +N more,后面跟着固定的出路:

in this landing only stop reading and writing it (remove the code; keep the object, no DROP / narrowing in the migration); put the DROP in a later landing, queued once the release carrying this one is known-good.

失败原因标成 candidate,意思是分支自身的问题,不算基础设施故障,也不会进重试。设计文档里专门写了一句:没有豁免标记。

5. 规格:一次拒绝,两次通过⌗

lane.test.ts 里的主测试就是 expand/contract 的完整剧本:

main:  expected-schema = messages(id, reactions)
       src/session-store.ts: 'SELECT id, reactions FROM messages'

① feat/drop-now   删读者 + 9001_drop_reactions.sql
   → failed / candidate
   → "column messages.reactions is still used by main before this landing"
   → "src/session-store.ts:1 `export const q = 'SELECT id, reactions FROM messages'`"
   → p.verified 长度为 0(还没进 verify 就被挡下了)

② feat/stop-reading   只删读者,不动 schema
   → landed

③ feat/drop-later     只有 DROP;known-good = ② 之后的 main tree
   → landed
   → "rollback compatibility: 1 removed schema object(s) unused by main before this landing, ..."

有两处值得注意:

  1. 检查放在 verify 之前。 改不改 schema 是从快照差里确定性算出来的,用不着先在测试机上把全量测试跑完再告诉你不行。被拒的分支一个测试槽位都没占。
  2. 第三步依赖 release 状态,不只是 main。 「下一个落地」严格说应该是「等到携带第二步的那一版成为 known-good 之后」。如果第二步刚上 main 还没发布,known-good 仍然是读 reactions 的旧树,第三步会继续被挡。这正是预期的行为,时间顺序由 release 指针来裁定,不靠人记。

全部改动 7 个文件,+409 / -5;新增测试 8 个(rollback-compat.test.ts 6 个,lane.test.ts 2 个)。按提交说明,拿这条检查重放 main 的历史,0626 那次删列会被拦下。

6. 为什么说它比约定好⌗

维度规范 + review这条检查
看的是哪份代码diff(新代码)每一个可能回滚到的已发布树
「上一个版本」是谁人去推断从 release 指针读出来的 tree id
什么时候判定review 时,靠人记得每次落地都判,在 verify 之前
出错时给什么「记得分两次发」文件:行 + 两步走的具体出路
例外一个注释就能绕过没有豁免标记

更根本的一点是问题的提法变了。以往问的是「这次迁移安不安全」,这个问题脱离部署状态是没法回答的。现在问的是「这次删掉的每一个对象,在 guardian 此刻可能退回的每一棵代码树里,是否已经没人用」。后一个问题有确定的输入(两份 schema 快照、几个 tree id),也有确定的输出。

它也顺带把 expand/contract 的节奏交给了 release 系统:contract 能不能落地,取决于 expand 那一版是否已经成为 known-good,而这正是「回滚窗口已经越过旧读者」的精确定义。

7. 它挡不住什么⌗

这是文本 grep,不是数据流分析。我清楚它的边界在哪:

  • 假阴性:
    • 表名和列名分散在不同文件里,比如表名做成常量从别处 import,列名写在 query builder 里。按「同文件须有表名」的规则,这种引用不会被算上。
    • 动态拼出来的标识符,比如 `${prefix}_items`。
    • 只覆盖五种删减。改列类型、加 NOT NULL、收紧非值列表形式的 CHECK、改函数返回类型,都可能让旧代码挂掉,这条检查都看不到。
    • 以注释开头、但后面跟着真代码的行(如 /* x */ SELECT ...)会被整行跳过。
  • 假阳性:同一个文件里恰好既有这张表名,又在别的语境里用了同名的词。这种情况会多拦一次。拦错的代价是多走一次两步落地,放错的代价是回滚失效,两者不对称,所以宁可多拦。
  • 数据层面的不兼容:schema 没变,但新版本写进去的数据旧代码读不懂(比如新的 JSON 字段形状),这完全不在检查范围内。

前两类可以靠 schema 访问收口来逐步缩小,所有 SQL 都走少数几个模块,grep 的命中率自然就高。最后一类需要的是另一条不变量,不是这条检查再加几个正则能解决的。

8. 一句话⌗

自动发布的前提是自动回滚能用,而自动回滚能用这件事,必须每次落地都由机器验证一遍。expand/contract 本身不是新东西,这次做的只是把「上一个版本」从人脑里的概念换成 release 指针里实实在在的 tree id,再拿 git grep 去问它一句。