Beads 意外发布 v1.2.1 事故复盘与恢复指南schema 游标回滚修复 v53/v65 版本错位【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读本文是一份针对 Beads 意外发布 v1.2.1 导致的本地数据库 schema 迁移事故的完整恢复手册。2026-08-11Beads 未经发布测试意外发布了 v1.2.0/v1.2.1任何一次bd命令执行哪怕是只读的bd list都会把本地数据库 schema 从 v53 迁移到 v65随后发布的 v1.2.2 实际上是经过测试的 v1.1.2 代码、只是换用了更高版本号因此它只认识 v53 schema遇到 v65 数据库会直接拒绝运行。阅读本文后你将掌握如何判断自己是否受影响、如何用一条 Dolt SQL 把 schema 游标回滚到 v53 完成两分钟恢复、如何使用BD_IGNORE_SCHEMA_SKEW1应急兜底、以及如何彻底回滚 Dolt 历史。文中所有命令均直接可复制执行并辅以仓库源码级证据说明其底层原理。事故背景v1.2.0/v1.2.1 为何会被意外发布根据 CHANGELOG.md 的记录v1.2.0 与 v1.2.1 于 2026-08-11 在未经过发布测试的情况下被意外发布v1.2.0 的 tag 在发布前即被烧毁实际只有 v1.2.1 到达用户。由于 Homebrew、npm、安装脚本、go install等所有安装渠道都会向前推进到更高版本号用户机器会自动升级到这些未经测试的二进制。随后的 v1.2.2 通过重新发布经过测试的 1.1 系列来取代它们——它本质上就是 v1.1.2 的代码只是版本号更高因此所有安装渠道都会前进到经过测试的代码上。这也意味着v1.2.x 独有特性不在v1.2.2 中work leases工作租约、events journal事件日志、sync federation同步联邦、HTTP API server、provenance events溯源事件等将在经过完整测试的后续版本中回归。问题本质一次命令触发 v53 → v65 的 12 步迁移核心事故机制是即使只运行一次bd二进制任何命令包括只读的bd list也会把本地数据库 schema 从 v53 迁移到 v65。而 v1.2.2 二进制只认识 schema v53因此打开这类数据库时会立即报错schema version mismatch: database is at v65, binary knows up to v53 (12 migrations ahead)这段错误文案来自仓库中的真实实现。在 internal/storage/schema/schema.go 中SchemaSkewError精确地构造了这条消息——它读取数据库的当前版本DBVersion与二进制的已知版本BinaryVersion比较并自动处理 1 migration 与 N migrations 的单复数差异。幸运的是v1.2.x 的 schema 变更严格是加法式strictly additive的——1.1 系列读取或写入的每一个对象都没有被删除、重命名或收窄。因此恢复是一个两分钟的元数据修复而不是数据迁移。v65 相对 v53 的 12 个迁移是什么从仓库的 internal/storage/schema/migrations/ 目录可以精确看到这 12 个迁移0054–0065它们正是 v1.2.x 新增特性的 schema 载体迁移内容对应 v1.2.x 特性0054_add_lease_columns为issues/wisps增加lease_expires_at、heartbeat_at、row_lock列及idx_issues_lease索引work leases0055_move_leases_to_table将租约数据迁移到独立表work leases0056_add_comments_keyset_index评论表增加 keyset 索引—0057_events_value_columns_idempotent_longtext事件表 value 列改为幂等 LONGTEXT—0058_heal_wisp_dependencies_split_constraints修复 wisp 依赖拆分约束—0059_recompute_null_gate_is_blocked重算空 gate 的 is_blocked—0060_add_storage_class为issues/wisps增加storage_class VARCHAR(16)标记列storage-class 协议0061_content_derived_aux_ids内容派生 aux id—0062_events_dolt_ignore将events审计表移出版本化平面provenance/审计0063_create_provenance_events新建provenance_events表provenance events0064_create_events_journal新建events_journal表events journal0065_widen_wisp_comments_text加宽 wisp 评论 TEXT 列—其中0062_events_dolt_ignore.up.sql值得特别说明它通过删除已跟踪的events表并单独提交删除 → 注册dolt_ignore模式 → 在未版本化平面上重建表 → 恢复行数据四个阶段把审计表从 Dolt 的版本化历史中剥离使事件不再产生历史提交该文件注释解释了events表占约 80% 的 dolt 提交是历史无限增长的主要驱动者见 0062_events_dolt_ignore.up.sql。这正是恢复指南可选恢复审计事件版本化一节所针对的迁移。我是否受影响只有同时满足以下两个条件才受影响至少运行过一次 v1.2.1 二进制且用 v1.2.2或任何 1.1.x 二进制打开数据库时看到上述 schema-mismatch 错误。以下两类用户通常不受影响升级了 v1.2.1 但从未运行过bd的用户迁移发生在首次执行时而不是安装时工作区配置了 Dolt remote 的用户——远程迁移门控remote-migrate gate阻止了静默迁移。关于第二点仓库源码中有充分佐证internal/storage/schema/remote_migrate_gate.go、internal/storage/schema/smart_remote_migrate_gate.go以及internal/storage/embeddeddolt/remote_migrate_gate_test.go共同构成了这道防护测试文件 remote_migrate_gate_test.go 还验证了即便在门控打开的状态下BD_IGNORE_SCHEMA_SKEW1仍保留逃生通道。推荐修复回滚 schema 游标两分钟恢复v1.2.x 的迁移被特意写成游标回滚后可重放replay-safe因此本操作完全可逆——之后安装经过测试的 1.2.x 升级会正常工作。恢复前准备在动手前先理解恢复依赖的机制Beads 通过schema_migrations表记录已应用的迁移版本游标。在 internal/storage/schema/schema.go 中CurrentVersion通过mainSource.currentVersion(ctx, db)从该表读取当前版本CheckBehindDrift 的实现展示了它的查询形式SELECT COALESCE(MAX(version), 0) FROM schema_migrations。回滚游标本质上就是删除这些多余的版本行——不触碰任何实际数据。恢复步骤1. 先把所有机器和 clone 升级到 v1.2.2。残留的 v1.2.1 二进制只要碰一次数据库就会静默地重新迁移它因此必须确保环境里没有旧二进制。2. 停止所有使用数据库的进程。关闭正在运行的bd进程服务器模式下还需执行bd dolt stop。3. 备份工作区数据库。cp -a .beads .beads.backup-pre-recovery4. 用 Dolt CLI 回滚游标。任意较新的dolt版本均可无需dolt config配置命令自带 author。数据库目录取决于运行模式嵌入模式默认.beads/embeddeddolt/db服务器模式.beads/dolt/dbcd .beads/embeddeddolt/db dolt sql -q DELETE FROM schema_migrations WHERE version 53; CALL DOLT_ADD(schema_migrations); CALL DOLT_COMMIT(-m, recovery: roll schema cursor back to v53 (accidental v1.2.1), --author, bd recovery recoverybeads.invalid)这条命令做了三件事删除版本大于 53 的游标记录、暂存schema_migrations表的变更、以显式 author 提交。如果返回没有可提交内容nothing to commit说明该步骤已完成可安全继续。5. 从工作区运行任意bd命令验证。应当无警告地正常工作无需BD_IGNORE_SCHEMA_SKEW1。适用范围与协作注意本方法同样适用于由 v1.2.1 创建而非仅升级的数据库v65 schema 是 1.1 系列所需一切的超集。如果与队友 push/pull issue 数据请注意迁移后的游标会复制要么恢复每一个 clone要么先恢复一个并 push然后让其他人 pull。可选恢复审计事件版本化0062 号迁移把events审计表移出了 Dolt 的版本化平面。游标回滚后1.1 系列会继续写入审计事件但不再进行版本化或同步其他一切都正常同步。如果你依赖版本化的审计轨迹需要在同一数据库目录下重新跟踪该表dolt sql -q DELETE FROM dolt_ignore WHERE pattern events; CALL DOLT_ADD(-f, events); CALL DOLT_COMMIT(-m, recovery: re-track events table, --author, bd recovery recoverybeads.invalid)这条命令从dolt_ignore中移除events模式、强制暂存events表-f是因为 dolt_ignore 过的表普通DOLT_ADD是静默 no-op这与 0062 迁移中DOLT_ADD(-f, events)的用法一致见 0062_events_dolt_ignore.up.sql然后提交。注意该命令的-f标志是必需的否则删除dolt_ignore模式后对仍在 ignore 状态下的表执行普通 add 不会生效。停工期应急恢复前的临时兜底如果当下就要用bdskew 守卫提供了逃生舱口BD_IGNORE_SCHEMA_SKEW1 bd command其实现原理在 internal/storage/schema/schema.go 的checkSchemaSkew中当环境变量BD_IGNORE_SCHEMA_SKEW等于1时前向 drift 检查不再返回SchemaSkewError而是向 stderr 打印警告后放行。命令行也提供等价开关在 cmd/bd/main.go 中--ignore-schema-skew标志会在PersistentPreRun阶段设置BD_IGNORE_SCHEMA_SKEW1因此以下写法完全等价bd --ignore-schema-skew command这一逃生通道已针对 v53 二进制 / v65 数据库这一确切组合验证过读操作结果一致、写操作正常因为 v1.2.x 的 schema 新增内容对 1.1 系列不可见。相关验证可以在 internal/storage/schema/schema_skew_test.go、internal/storage/dolt/schema_skew_test.go 以及 cmd/bd/protocol/versioning_contract_test.go 中看到。但请注意审计事件版本化在兜底期间是暂停的见上文直到你完成游标回滚。把它当作应急手段而不是最终方案。恢复后会留下什么意外发布期间写入 1.2.x 独有结构中的数据仍留在数据库中但 1.1 系列不会使用它们遗留数据说明work-lease 状态临时性的5 分钟 horizon会被自然回收events-journal 行该功能默认关闭正常情况下没有数据provenance 行只有显式的新命令才会写入storage_class标记纯标记列不改变行为这些遗留数据不会阻塞未来的 1.2.x 升级——届时升级会直接恢复使用它们。从源码看storage_class被设计为纯类标记class marker列0060 迁移的注释明确写道 The column is a class MARKER only: this migration changes no behavior见 0060_add_storage_class.up.sql。备选方案通过 Dolt 历史彻底回滚如果你希望把数据库历史本身恢复到迁移前状态游标回滚会保留迁移提交在历史中可以使用此方案。v1.2.1 的迁移器为每个迁移做了一个带标签的 Dolt 提交schema: apply migration 0054_...到0065_...因此迁移前的提交很容易定位。安全操作序列如下用 v1.2.1 二进制导出bd export --all -o backup.jsonl停止一切并复制.beads到别处作为额外保险在数据库目录中执行dolt reset --hard pre-migration-commit安装 v1.2.2执行bd import backup.jsonl恢复数据已知注意事项升级后删除的 issue 会复活import 无法重新删除在 v1.2.1 期间记录的审计事件会丢失。因此大多数用户应优先选择游标回滚只有确实需要还原历史时才采用本方案。预防性理解Beads 的 schema 版本守卫机制本次事故能快速止血很大程度上得益于 Beads 内置的 schema 版本守卫Schema Version Guard。正如 README.md 所描述的bd在打开数据库时检查 schema 版本如果数据库已被更新版本的二进制迁移、而当前二进制试图打开它bd会带着可操作的错误信息退出而不是发出会以晦涩 SQL 错误失败如 column X could not be found in any table in scope的查询。守卫只会因为前向 drift数据库 schema 领先于二进制触发正常的升级路径二进制把数据库向前迁移不受影响。正是这道守卫让 v1.2.2 在碰到 v65 数据库时立即报错而非静默破坏数据为本文的恢复流程创造了前提。而BD_IGNORE_SCHEMA_SKEW1逃生通道之所以被设计为可用也正是因为它假设前向迁移是加法式的、对你的工作负载安全——本次事故恰好满足这一前提。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考