Beads 混沌测试与恢复演练：用故障注入验证 `bd doctor` 的数据自愈能力

Beads 混沌测试与恢复演练：用故障注入验证bd doctor的数据自愈能力

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

本文基于 Beads 仓库中 PR #752 混沌测试评审文档 展开，系统梳理 Beads 通过故障注入（数据库损坏、磁盘写锁、NFS 类故障）验证bd doctor恢复流程的实践，并结合当前仓库的doctor/fix实现与测试源码，说明测试组织方式、已发现的迁移 Bug、投入产出权衡与决策框架。读完本文，你将掌握 Beads 混沌测试的五大核心场景、构建标签隔离的运行方式、恢复流程的源码级原理，以及一套可复用的"是否值得投入测试"的判断清单。

一、文档背景：一份关于"要不要大规模加测试"的评审记录

engdocs/staged-for-removal/pr-752-chaos-testing-review.md是一份 PR 评审备忘录（Review Memo），记录了社区贡献者 jordanhubbard 提交的 PR #752 的完整评估过程。该 PR 的规模与目标如下：

• 新增 4849 行，删除 511 行；
• 引入混沌测试框架：随机损坏数据、磁盘空间耗尽、NFS 类故障注入；
• 创建侧数据库（side databases，与真实数据隔离的测试库）用于验证恢复场景；
• 增加E2E 测试，追踪文档中描述的用户场景；
• 将整体代码覆盖率提升到约48%。

这份文档之所以被归档到staged-for-removal目录，是因为其价值在于决策记录与测试方法论，而非可长期维护的教程；同时仓库本身已从 SQLite 后端演进为 Dolt 后端，文档中部分文件路径（如internal/storage/sqlite/migrations/021_*.go）已不再存在于当前代码树中。但其中关于"如何验证恢复能力、测试投入是否值得"的分析，对理解 Beads 的可靠性设计仍然有直接参考价值，且其核心场景在当前仓库的 doctor_repair_chaos_test.go 中仍以测试函数形式保留。

二、混沌测试实际覆盖的五大恢复场景

评审文档从 cmd/bd/doctor_repair_chaos_test.go 中归纳出混沌测试真正验证的内容。当前仓库中对应的测试函数仍然存在，逐一对应如下：

此外还包括数据库写锁时导入快速失败（TestDoctorRepair_DatabaseIntegrity_DBWriteLocked_ImportFailsFast）、只读目录权限修复（TestDoctorRepair_CorruptDatabase_ReadOnlyBeadsDir_PermissionsFixMakesWritable）等补充场景。

需要特别说明的现状：当前仓库已切换到 Dolt 后端，上述每个混沌测试函数体内均以t.Skip(...)跳过，并注明理由，例如"SQLite file corruption chaos test; not applicable to Dolt backend (bd-o0u)"、"Dolt uses server connections, not file locks"。也就是说，场景清单与测试骨架被完整保留，但针对 SQLite 的故障注入逻辑在 Dolt 后端下不再执行——这恰恰印证了评审文档中的一句判断："混沌测试框架本身也是需要维护的东西"，当存储后端迁移时，测试必须跟随演进。

测试基础设施的三个共同特征

评审文档总结了每个混沌测试的共同设计，这些在当前测试文件中依然可见：

1. 隔离的临时目录：每个测试在独立的 workspace 中运行，不污染真实数据；
2. 现场构建全新bd二进制：测试通过exec.Command调用新编译的 CLI，而非直接调用内部函数，保证被测对象与真实使用路径一致；
3. 侧数据库：测试数据与真实数据分离，损坏操作只作用于测试副本。

测试文件中还保留了两个可复用的辅助函数：

• startDaemonForChaosTest：以--db <path> daemon --start --foreground --local --interval 10m启动后台守护进程，然后轮询等待.beads/bd.socksocket 出现（8 秒超时），用于"修复时服务器持有锁"这类并发场景；
• runBDWithEnv：封装--db参数与BEADS_DIR环境变量的注入，统一测试子进程的运行环境。

三、测试组织方式：构建标签隔离，不拖慢日常开发

评审文档明确了测试的组织原则——按Go build tag划分层级：

//go:build chaos // 混沌/损坏类测试（单独运行） //go:build e2e // 端到端 CLI 测试 // 普通单元测试 // 无需任何构建标签

对应的运行命令：

go test ./... # 仅运行普通测试 go test -tags=chaos ./... # 加入混沌测试 go test -tags=e2e ./... # 加入 E2E 测试

这意味着混沌测试只在显式请求时才运行，不会拖慢每一次go test。当前仓库的 doctor_repair_chaos_test.go 文件头部仍保留//go:build chaos标签，验证了这一约定在代码库中的实际落地。这是评审文档中"构建标签隔离能最小化对开发节奏的影响"这一论点的直接源码证据。

四、混沌测试的实战价值：已经抓到过迁移 Bug

评审文档指出，PR #752 在测试过程中已经发现了真实的生产级 Bug：

• 迁移 021/022：pinned与is_template两列在迁移过程中会被意外覆盖（clobbered）；
• 修复方式是提交迁移修复并增加回归测试，防止复发。

这类问题正是那种"平时不触发、一旦触发就导致数据丢失"的隐蔽缺陷。虽然当前仓库已不再包含internal/storage/sqlite/migrations/021_*.go与022_*.go（SQLite 存储已被 Dolt 取代），但这一事实本身证明了混沌测试的两个核心价值：

1. Bug 发现价值：故障注入能暴露正常测试路径永远走不到的损坏分支；
2. 回归防护价值：一旦某个损坏场景被修复并固化为测试，未来任何改动破坏该路径都会被 CI 拦截。

这正是评审文档中"如果混沌测试能通过，说明 Beads 比担心的更健壮"这一判断的经验来源。

五、源码佐证：当前仓库的恢复流程是如何实现的

评审文档讨论的"SQLite + JSONL + git backstop"三层兜底设计，在当前仓库中已演进为 Dolt 后端下的"备份 + 重建"恢复流程，核心实现位于 cmd/bd/doctor/fix/database_integrity.go：

恢复主流程（doltIntegrityRecovery）：

1. 先经 serverModeIntegrityRecoveryGuard 检查：若仓库处于 Dolt 服务器模式，拒绝自动恢复，因为可能替换错误的 Dolt root，必须人工核对配置的数据库后再重建；
2. 将损坏的 Dolt 目录以时间戳命名备份：<doltPath>.<UTC 时间戳>.corrupt.backup；
3. 执行bd init --force -q --skip-hooks重建（若配置了sync.remote会从远端克隆）；
4. 重建失败时回滚：删除新建目录并恢复备份，保证失败不扩大损失；
5. 成功后保留损坏库副本供人工取证。

故障注入友好性：cmd/bd/doctor/fix/fs.go 将文件操作抽象为可替换的包级变量（renameFile / removeFile / openFileRO / openFileRW），并实现跨设备移动（moveFile）与 EXDEV 检测（isEXDEV）——这种"变量间接层"正是为了测试中注入磁盘故障（如跨文件系统 rename 失败）而设计的，与评审文档中"NFS 类故障注入"的目标一致。

Git 卫生检查：cmd/bd/doctor/git.go 中定义了 30 秒 git 子进程超时（gitCmdTimeout），并检查 pre-commit / post-merge / pre-push 推荐钩子是否安装——这是"git backstop"兜底设计的日常体检项。此外仓库还保留了 cli_coverage_show_test.go 等覆盖率相关测试文件，印证评审文档中"覆盖率提升到约 48%"的工作确实落地到了测试代码。

六、成本与收益的完整权衡

评审文档用一张清晰的对照表分析了引入大规模测试的代价：

成本（Costs）

1. 维护负担：必须将覆盖率维持在 48%（或设定的阈值）之上；
2. CI 噪音：测试失败会阻塞合并，且 CI 反馈"非常吵"（评审原文：very spammy if your tests don't pass）；
3. 速度税（Velocity tax）：每次行为变更都要同步更新测试；
4. 复杂度：混沌测试框架自身（侧数据库、构建标签、测试辅助函数）也需要维护。

收益（Benefits）

1. 鲁棒性验证：证明 Beads 能从损坏中恢复；
2. Bug 发现：已经发现了 021/022 迁移问题；
3. 信心：混沌测试通过意味着 Beads 比担心的更健壮；
4. 文档价值：E2E 测试是用户场景的可执行文档——当 AI Agent 询问"发生 X 时应该怎样"，测试给出了可运行的标准答案；
5. 回归防护：未来的变更在发布前就被拦截。

投入产出（ROI）计算

评审文档给出了一个务实的量化框架：

• 不测试的代价：Agent 丢失上下文（恢复需 30-60 分钟）+ 人工排障（15-60 分钟）+ 难以量化的信任损耗；
• 测试的代价：评审该 PR（一次性 1-2 小时）+ 行为变更时更新测试（每次 5-15 分钟）+ 修复偶发 flaky 测试（不定）。

结论是：若损坏每月才发生一次，测试 ROI 勉强；若损坏每周发生（或每个新功能都引入损坏），测试成本就物超所值。这一判断与 Beads 的处境直接相关——当多个 Agent 并发工作、真实数据损坏的代价放大 10 倍时，测试投入的回报也随之放大。

七、决策框架：四个问题判断"现在是否该投入"

评审文档最终给出MERGE WITH MODIFICATIONS（有条件合并）的结论，理由包括：实现质量高、已发现的 Bug 证明了投入价值、构建标签隔离降低了开发节奏影响、Beads 已越过原型阶段。

同时附带了三条修改建议：

1. CI 中不设硬性覆盖率门槛——价值在于混沌测试能抓住损坏，而非达标某个百分比，允许覆盖率随优先级自然浮动；
2. 混沌测试可选运行——在 release 分支运行而非每个 PR，减少活跃开发期的 CI 噪音；
3. 明确测试归属（ownership）——贡献者应文档化如何新增混沌场景，让后续贡献者知道何时该加测试、何时该跳过。

对读者（尤其是 Beads 用户与贡献者）最有实操价值的是文末的决策清单——以下问题如果回答 YES 达到 2 个及以上，就应该合并这类测试投入：

• 你是否正在用 Beads 处理真实工作（dogfooding）？
• 过去一个月内，数据损坏是否导致你损失过时间？
• 你是否预期多个 Agent 会并发使用 Beads？
• Beads 是否正接近 "v1.0" 里程碑？

如果全部回答 NO，则可以推迟测试投入，直到项目稳定。

八、结论与延伸阅读

评审文档的核心洞察可以浓缩为一句话：测试的价值不取决于覆盖率数字，而取决于它能否在真实损坏发生之前抓住那些"平时不触发、触发即数据丢失"的缺陷。Beads 的bd doctor恢复链路（备份损坏库 → 重建 → 失败回滚）之所以值得信赖，正是因为有一组围绕"损坏后能否自愈"设计的混沌场景在持续校验它——即使存储后端从 SQLite 迁移到 Dolt 导致具体注入逻辑停用，场景骨架与恢复设计的源码证据依然保留在仓库中，供后续后端演进时重新激活。

如需进一步深入，可继续阅读：

• 评审原文：engdocs/staged-for-removal/pr-752-chaos-testing-review.md
• 混沌测试骨架：cmd/bd/doctor_repair_chaos_test.go
• Dolt 后端恢复实现：cmd/bd/doctor/fix/database_integrity.go
• 故障注入友好文件层：cmd/bd/doctor/fix/fs.go
• Git 卫生检查：cmd/bd/doctor/git.go
• 覆盖率测试：cmd/bd/cli_coverage_show_test.go

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads