Beads 数据库损坏恢复实战指南基于 bd doctor 的 Dolt 数据修复与预防【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文是 Beads 项目的数据库损坏恢复 runbook对应仓库 docs/recovery/database-corruption.md。Beads 将编码 Agent 的 Issue、依赖关系与记忆存储在基于 Dolt 的数据库中一旦数据库损坏bd命令会报错、数据凭空消失或状态不一致。读完本文你将掌握从症状识别、bd doctor诊断、bd dolt show排查到备份、bd doctor --fix重建、验证与重启 Dolt 服务的完整恢复流程并了解如何在日常使用中预防损坏。背景Beads 的数据存储形态Beads 默认将工作区数据放在仓库根目录的.beads/目录中其中包含metadata.json记录数据库后端选择bd_version、repo_id、clone_id、dolt_database等字段的配置文件dolt/Dolt 数据目录默认位置可通过bd dolt set># 检查 Beads 安装与数据库健康核心诊断入口 bd doctor # 检查 Dolt 服务器健康状态 bd dolt show在此基础上建议按下面的顺序扩展诊断# 查看整体状态recovery 目录总览推荐先执行 bd status # Dolt 引擎状态embedded 显示 in-process 与数据目录server 模式显示连接信息 bd dolt statusbd doctor是诊断的核心。从源码看它以只读方式运行通过skipStoreAnnotation注释跳过了打开存储的前置步骤见 cmd/bd/doctor.go在打开数据库之前就会检查.beads/是否存在、metadata.json是否存在并可解析、Dolt 格式是否兼容旧 noms 格式会导致服务器 panic。随后它会打开一个共享 storeGH#2636避免每个检查各自开关 store 导致 Dolt 服务器无限重启循环依次执行数十项检查按类别分组输出检查类别典型检查项与损坏相关的信号Core核心安装目录、Fresh Clone、Metadata Config、Dolt Format、Database Version、Schema Compatibility、Repo Fingerprint、Database Integrity、ID FormatDatabase Integrity 报 Error 即说明基本查询失败Data数据Database Config、Project Identity、Stale Lock Files、Corrupt Manifest、is_blocked 一致性、标签空白损伤Corrupt Manifest 报 Error 表示 Dolt manifest 已损坏GH#3290Metadata元数据Dependency Cycles、Dependency Keys、Deletions Manifest、版本追踪依赖环 / 悬挂依赖引用Dolt / FederationDolt 连接、Dolt Schema、Remote URL 冲突、同步陈旧度、冲突检测服务器模式下的连接与同步问题其中与数据库损坏直接对应的是Database Integrity检查它以只读方式打开 Dolt store尝试读取bd_version元数据与统计数据任一失败即判定为损坏见 cmd/bd/doctor/database.go 的checkDatabaseIntegrityWithStore。输出格式上默认只显示 warning/error可用--verbose查看全部检查--json输出机器可读结果--agent输出面向 AI Agent 的结构化诊断包含 Observed state、Expected state、Commands、Severity 等字段--output diagnostics.json可将诊断导出为带时间戳与平台信息的报告便于追踪间歇性问题。解决方案六步恢复流程原 runbook 给出了完整的六步恢复流程下面逐一步骤展开并说明每一步背后的源码行为确保你可以安全地照做。Step 1停止 Dolt 服务器bd dolt stop适用前提仅在服务器模式下需要此步。Beads 默认是 embedded 模式进程内运行 Dolt没有独立服务器此命令会提示不支持。在服务器模式下必须先停掉服务器再操作数据目录否则文件处于使用中修复与恢复可能互相干扰。嵌入式模式的用户在修改.beads/前应确保没有其他bd进程正在运行。Step 2备份当前状态cp -r .beads .beads.backup这一步不要跳过。虽然bd doctor --fix的数据库完整性修复本身也会自动备份损坏目录见 Step 4但在修复前手工复制一份完整快照可以让你在任意一步出错时都能回滚到原始状态。若你更倾向使用内置命令仓库提供了bd backup命令见 cmd/bd/backup.go可以按项目自身的备份机制生成快照。Step 3预览 doctor 将要修复的内容bd doctor --dry-run--dry-run会先完整跑一遍诊断然后只列出可修复项而不做任何改动。从 cmd/bd/doctor_fix.go 的previewFixes实现可以看到它会收集所有状态为 warning/error 且带Fix建议的检查项逐条打印问题名称、状态、说明与修复方案最后输出[DRY-RUN] Would attempt to fix N issue(s)与提示命令。这一步让你在真正动手前评估修复的影响面——尤其是确认Database Integrity是否在待修复列表中。Step 4重建数据库bd doctor --fix--fix会以依赖感知的顺序执行所有可自动修复项先修 gitignore、权限、锁文件、配置等前置项再执行 Database Integrity、Schema Compatibility 等数据库级修复最后重算is_blocked状态见 cmd/bd/doctor_fix.go 的orderDoctorFixes其中 Blocked State 被固定为最后执行确保基于修复后的图结构重算。针对数据库损坏bd doctor --fix调用的实际修复逻辑是fix.DatabaseIntegrity见 cmd/bd/doctor/fix/database_integrity.go其行为是将损坏的 Dolt 目录重命名为带时间戳的备份dolt 目录.UTC时间戳.corrupt.backup调用bd init --force -q --skip-hooks重新初始化数据库若配置了sync.remoteinit 会从远端 clone 数据回来若重建失败自动恢复回滚损坏目录避免二次破坏成功后保留.corrupt.backup备份并输出恢复信息。常用变体bd doctor --fix --yes # 跳过交互确认适合 CI/自动化非交互 stdin 下无 --yes 会直接跳过修复 bd doctor --fix -i # 逐项确认y/n/a/q 交互模式 bd doctor --fix --force # 数据库无法打开时也强制执行修复 bd doctor --fix --sourcejsonl # 从 JSONL 导出重建数据库 bd doctor --checkvalidate --fix # 只跑数据完整性检查并自动修复重复项、孤儿依赖、测试污染、git 冲突服务器模式的重要限制如果工作区配置为 Dolt 服务器模式自动完整性恢复会被禁用serverModeIntegrityRecoveryGuard因为重建可能替换错误的 Dolt root 或错误的数据库默认库名beads。此时需要手工保留 Dolt root核对配置的数据库名后再决定是否重新初始化详见 cmd/bd/doctor/database.go 的serverModeIntegrityManualRecoveryDetail。Step 5验证恢复结果bd doctor bd listbd doctor用于确认所有检查项恢复为绿色无 errorbd list用于从业务侧验证 Issue 数据完整可见。也可以加跑bd doctor --deep做全图完整性校验检查父子依赖、依赖引用、epic 完备性、Agent bead 状态、邮件线程、molecule 结构等或bd doctor --server做服务器模式健康检查连通性、Dolt 版本、数据库存在性、schema 兼容、连接池。Step 6重启 Dolt 服务器dolt sql-server仅服务器模式需要。注意原 runbook 中的重启命令是 Dolt 原生命令若你使用 Beads 管理服务器生命周期等价操作是bd dolt start。重启后建议再跑一次bd doctor确认连接健康。预防让损坏不再发生原 runbook 给出了三条预防准则这里结合源码补充其具体含义让 Dolt 服务器处理同步不要手工复制/修改运行中的 Dolt 数据目录也不要绕过 Beads 直接操作数据库文件。并发写入与复制正在使用的数据目录是损坏的头号来源。系统关机前先执行bd dolt stop服务器模式下非正常关机可能留下陈旧锁文件与未提交事务bd doctor专门检查的 Lock Files、Circuit Breaker、Dolt Locks 大多源于此类异常退出。定期运行bd doctor尽早发现问题可将bd doctor --json加入 CI 或定时任务非交互输出会自动跳过网络检查保持确定性并配合--output diagnostics.json留存历史基线便于对比间歇性问题。此外遇到损坏相关症状时还可参考 docs/recovery/index.md 中的其他 runbook合并冲突、同步失败、历史膨胀等并利用bd doctor --agent --json生成面向 Agent 的结构化诊断将观察到什么、应该是什么、如何修复完整交给下游工具处理。关键源码索引诊断命令主入口与全部检查项编排cmd/bd/doctor.go修复执行逻辑含--dry-run、--fix、交互确认cmd/bd/doctor_fix.go数据库完整性检查实现cmd/bd/doctor/database.go数据库损坏的实际恢复流程备份 重初始化cmd/bd/doctor/fix/database_integrity.goDolt 服务器生命周期与配置命令cmd/bd/dolt.go恢复手册总览docs/recovery/index.md【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads 数据库损坏恢复实战指南：基于 bd doctor 的 Dolt 数据修复与预防
Beads 数据库损坏恢复实战指南基于 bd doctor 的 Dolt 数据修复与预防【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads本文是 Beads 项目的数据库损坏恢复 runbook对应仓库 docs/recovery/database-corruption.md。Beads 将编码 Agent 的 Issue、依赖关系与记忆存储在基于 Dolt 的数据库中一旦数据库损坏bd命令会报错、数据凭空消失或状态不一致。读完本文你将掌握从症状识别、bd doctor诊断、bd dolt show排查到备份、bd doctor --fix重建、验证与重启 Dolt 服务的完整恢复流程并了解如何在日常使用中预防损坏。背景Beads 的数据存储形态Beads 默认将工作区数据放在仓库根目录的.beads/目录中其中包含metadata.json记录数据库后端选择bd_version、repo_id、clone_id、dolt_database等字段的配置文件dolt/Dolt 数据目录默认位置可通过bd dolt set># 检查 Beads 安装与数据库健康核心诊断入口 bd doctor # 检查 Dolt 服务器健康状态 bd dolt show在此基础上建议按下面的顺序扩展诊断# 查看整体状态recovery 目录总览推荐先执行 bd status # Dolt 引擎状态embedded 显示 in-process 与数据目录server 模式显示连接信息 bd dolt statusbd doctor是诊断的核心。从源码看它以只读方式运行通过skipStoreAnnotation注释跳过了打开存储的前置步骤见 cmd/bd/doctor.go在打开数据库之前就会检查.beads/是否存在、metadata.json是否存在并可解析、Dolt 格式是否兼容旧 noms 格式会导致服务器 panic。随后它会打开一个共享 storeGH#2636避免每个检查各自开关 store 导致 Dolt 服务器无限重启循环依次执行数十项检查按类别分组输出检查类别典型检查项与损坏相关的信号Core核心安装目录、Fresh Clone、Metadata Config、Dolt Format、Database Version、Schema Compatibility、Repo Fingerprint、Database Integrity、ID FormatDatabase Integrity 报 Error 即说明基本查询失败Data数据Database Config、Project Identity、Stale Lock Files、Corrupt Manifest、is_blocked 一致性、标签空白损伤Corrupt Manifest 报 Error 表示 Dolt manifest 已损坏GH#3290Metadata元数据Dependency Cycles、Dependency Keys、Deletions Manifest、版本追踪依赖环 / 悬挂依赖引用Dolt / FederationDolt 连接、Dolt Schema、Remote URL 冲突、同步陈旧度、冲突检测服务器模式下的连接与同步问题其中与数据库损坏直接对应的是Database Integrity检查它以只读方式打开 Dolt store尝试读取bd_version元数据与统计数据任一失败即判定为损坏见 cmd/bd/doctor/database.go 的checkDatabaseIntegrityWithStore。输出格式上默认只显示 warning/error可用--verbose查看全部检查--json输出机器可读结果--agent输出面向 AI Agent 的结构化诊断包含 Observed state、Expected state、Commands、Severity 等字段--output diagnostics.json可将诊断导出为带时间戳与平台信息的报告便于追踪间歇性问题。解决方案六步恢复流程原 runbook 给出了完整的六步恢复流程下面逐一步骤展开并说明每一步背后的源码行为确保你可以安全地照做。Step 1停止 Dolt 服务器bd dolt stop适用前提仅在服务器模式下需要此步。Beads 默认是 embedded 模式进程内运行 Dolt没有独立服务器此命令会提示不支持。在服务器模式下必须先停掉服务器再操作数据目录否则文件处于使用中修复与恢复可能互相干扰。嵌入式模式的用户在修改.beads/前应确保没有其他bd进程正在运行。Step 2备份当前状态cp -r .beads .beads.backup这一步不要跳过。虽然bd doctor --fix的数据库完整性修复本身也会自动备份损坏目录见 Step 4但在修复前手工复制一份完整快照可以让你在任意一步出错时都能回滚到原始状态。若你更倾向使用内置命令仓库提供了bd backup命令见 cmd/bd/backup.go可以按项目自身的备份机制生成快照。Step 3预览 doctor 将要修复的内容bd doctor --dry-run--dry-run会先完整跑一遍诊断然后只列出可修复项而不做任何改动。从 cmd/bd/doctor_fix.go 的previewFixes实现可以看到它会收集所有状态为 warning/error 且带Fix建议的检查项逐条打印问题名称、状态、说明与修复方案最后输出[DRY-RUN] Would attempt to fix N issue(s)与提示命令。这一步让你在真正动手前评估修复的影响面——尤其是确认Database Integrity是否在待修复列表中。Step 4重建数据库bd doctor --fix--fix会以依赖感知的顺序执行所有可自动修复项先修 gitignore、权限、锁文件、配置等前置项再执行 Database Integrity、Schema Compatibility 等数据库级修复最后重算is_blocked状态见 cmd/bd/doctor_fix.go 的orderDoctorFixes其中 Blocked State 被固定为最后执行确保基于修复后的图结构重算。针对数据库损坏bd doctor --fix调用的实际修复逻辑是fix.DatabaseIntegrity见 cmd/bd/doctor/fix/database_integrity.go其行为是将损坏的 Dolt 目录重命名为带时间戳的备份dolt 目录.UTC时间戳.corrupt.backup调用bd init --force -q --skip-hooks重新初始化数据库若配置了sync.remoteinit 会从远端 clone 数据回来若重建失败自动恢复回滚损坏目录避免二次破坏成功后保留.corrupt.backup备份并输出恢复信息。常用变体bd doctor --fix --yes # 跳过交互确认适合 CI/自动化非交互 stdin 下无 --yes 会直接跳过修复 bd doctor --fix -i # 逐项确认y/n/a/q 交互模式 bd doctor --fix --force # 数据库无法打开时也强制执行修复 bd doctor --fix --sourcejsonl # 从 JSONL 导出重建数据库 bd doctor --checkvalidate --fix # 只跑数据完整性检查并自动修复重复项、孤儿依赖、测试污染、git 冲突服务器模式的重要限制如果工作区配置为 Dolt 服务器模式自动完整性恢复会被禁用serverModeIntegrityRecoveryGuard因为重建可能替换错误的 Dolt root 或错误的数据库默认库名beads。此时需要手工保留 Dolt root核对配置的数据库名后再决定是否重新初始化详见 cmd/bd/doctor/database.go 的serverModeIntegrityManualRecoveryDetail。Step 5验证恢复结果bd doctor bd listbd doctor用于确认所有检查项恢复为绿色无 errorbd list用于从业务侧验证 Issue 数据完整可见。也可以加跑bd doctor --deep做全图完整性校验检查父子依赖、依赖引用、epic 完备性、Agent bead 状态、邮件线程、molecule 结构等或bd doctor --server做服务器模式健康检查连通性、Dolt 版本、数据库存在性、schema 兼容、连接池。Step 6重启 Dolt 服务器dolt sql-server仅服务器模式需要。注意原 runbook 中的重启命令是 Dolt 原生命令若你使用 Beads 管理服务器生命周期等价操作是bd dolt start。重启后建议再跑一次bd doctor确认连接健康。预防让损坏不再发生原 runbook 给出了三条预防准则这里结合源码补充其具体含义让 Dolt 服务器处理同步不要手工复制/修改运行中的 Dolt 数据目录也不要绕过 Beads 直接操作数据库文件。并发写入与复制正在使用的数据目录是损坏的头号来源。系统关机前先执行bd dolt stop服务器模式下非正常关机可能留下陈旧锁文件与未提交事务bd doctor专门检查的 Lock Files、Circuit Breaker、Dolt Locks 大多源于此类异常退出。定期运行bd doctor尽早发现问题可将bd doctor --json加入 CI 或定时任务非交互输出会自动跳过网络检查保持确定性并配合--output diagnostics.json留存历史基线便于对比间歇性问题。此外遇到损坏相关症状时还可参考 docs/recovery/index.md 中的其他 runbook合并冲突、同步失败、历史膨胀等并利用bd doctor --agent --json生成面向 Agent 的结构化诊断将观察到什么、应该是什么、如何修复完整交给下游工具处理。关键源码索引诊断命令主入口与全部检查项编排cmd/bd/doctor.go修复执行逻辑含--dry-run、--fix、交互确认cmd/bd/doctor_fix.go数据库完整性检查实现cmd/bd/doctor/database.go数据库损坏的实际恢复流程备份 重初始化cmd/bd/doctor/fix/database_integrity.goDolt 服务器生命周期与配置命令cmd/bd/dolt.go恢复手册总览docs/recovery/index.md【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考