Beads 的 Dolt 存储后端完全指南嵌入式与服务器双模式、远程同步与数据迁移【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 将 Dolt 为骨架结合 docs/architecture/dolt.md 与仓库源码系统讲解嵌入式Embedded与服务器Server两种运行模式、bd dolt远程仓库管理、SQLite 遗留迁移、故障排查与高级 Dolt 用法读完即可独立完成 Beads 项目的初始化、多代理并发部署与跨机同步配置。为什么 Beads 选择 DoltBeads 的每一项写操作都会产生一个 Dolt 提交因此bd create、bd comment等命令天然具备可审计的历史轨迹。核心能力对比如下能力维度Dolt 实现方式存储形态目录式存储.beads/embeddeddolt/或.beads/dolt/版本控制原生支持单元cell级 diff 与 merge而非行级文本比对分支原生支持独立于 Git 分支体系时间旅行支持AS OF查询与历史 checkout冲突合并SQL 语义的 cell 级 merge多用户并发通过 Server 模式MySQL 协议实现跨机同步原生 push/pull 到 Dolt remotesDoltHub、S3、GCS、Git SSH、本地文件从源码看cmd/bd/dolt.go 明确写有 Beads runs Dolt embedded (in-process) by default默认嵌入式引擎随bd二进制内联无需额外安装 Dolt 客户端。快速开始1. 安装 Dolt仅服务器模式需要嵌入式模式将 Dolt 引擎直接编译进bd二进制版本由 go.mod 固定无需单独安装 Dolt只有运行服务器模式或希望用dolt sql直接操作数据库时才需要独立 CLI。安装时有两条硬性约束务必先读 docs/architecture/dolt.md不要安装releases/latestDolt 2.3.x 存在数据操作缺陷CALL DOLT_RESET(--hard)在约 3% 的新建库上返回Error 1105 (HY000): context canceled会直接破坏bd flatten与bd admin compact。Beads 将版本固定为2.2.0CI 通过scripts/ci/install-dolt.sh安装同一固定版本其中记录着各版本测量数据与提版标准。不要依赖brew install dolt的版本Homebrew formula 指向的版本未固定安装后必须用dolt version核对。# 校验安装到的版本 dolt version2. 初始化项目# 新项目Dolt 是默认后端默认进入嵌入式模式 bd init3. 配置同步模式# .beads/config.yaml sync: mode: dolt-native # 默认值使用 Dolt remotes 做原生同步嵌入式模式默认嵌入式模式将 Dolt 引擎运行在bd进程内部无需独立服务器是所有bd init安装的默认形态——执行bd init即可使用。零配置无服务器、无端口、无 PID 文件单写者同一时刻仅允许一个进程写入由文件锁flock强制执行数据位置.beads/embeddeddolt/与代码同目录存放。与之呼应cmd/bd/dolt.go 中对bd dolt set、bd dolt test、bd dolt start、bd dolt stop均做了嵌入式模式守卫直接返回bd dolt ... is not supported in embedded mode (no Dolt server)。服务器模式按需开启当需要多代理并发写入多个 Agent、orchestrator 编排环境时切换到服务器模式连接一个运行中的dolt sql-server。开启服务器模式# 初始化时指定 bd init --server # 或用环境变量 export BEADS_DOLT_SERVER_MODE1 bd init已存在的嵌入式项目切换方法见下文「嵌入式与服务器模式互迁」一节。此外 docs/architecture/dolt.md 还提供了 Unix 域套接字连接方式--server-socket标志对应环境变量BEADS_DOLT_SERVER_SOCKET可避开端口冲突适用于 Claude Code 等沙箱环境。服务器配置项环境变量默认值说明BEADS_DOLT_SERVER_MODE空设为1开启服务器模式BEADS_DOLT_SERVER_HOST127.0.0.1服务器绑定地址BEADS_DOLT_SERVER_PORT3307服务器端口MySQL 协议避开 3306 的 MySQL 冲突BEADS_DOLT_SERVER_USERrootMySQL 用户名BEADS_DOLT_SERVER_PASS空MySQL 密码BEADS_DOLT_SHARED_SERVER空共享服务器模式1或true开启环境变量在 cmd/bd/bootstrap.go 等文件中直接参与端口与模式的解析优先级高于配置文件。服务器生命周期管理以下命令仅服务器模式可用嵌入式模式会报错退出# 检查服务器状态 bd doctor # 启停与状态 bd dolt start bd dolt stop bd dolt status # 仅服务器可用的配置命令嵌入式模式报错 bd dolt show bd dolt set bd dolt test在 orchestrator 编排场景bd dolt系列命令会自动拉起/停止项目自己的dolt sql-serverbd doctor同时负责校验服务器健康度与端口一致性。共享服务器模式Shared Server Mode多项目机器上每个项目默认会启动自己的 Dolt 服务器。共享服务器模式让所有项目共用一个 Dolt 服务器进程# 通过配置开启 bd dolt set shared-server true # 或通过环境变量机器级生效 export BEADS_DOLT_SHARED_SERVER1共享服务器状态存放于~/.beads/shared-server/默认端口为 3308避开 orchestrator 使用的 3307。每个项目的数据以其项目前缀命名的独立数据库隔离例如~/.beads/shared-server/dolt/myproject/。从 internal/doltserver/doltserver.go 源码可以看到关键实现细节const DefaultSharedServerPort 3308共享模式默认端口定义IsSharedServerMode()同时检查环境变量与dolt.shared-server配置项SharedServerDir()返回~/.beads/shared-server/dolt/作为共享数据目录。重要约束共享服务器上的每个项目必须有唯一前缀数据库名。若两个项目前缀相同导致数据库共用项目身份校验会检测到不一致并拒绝连接防止静默数据损坏。中央 Dolt 服务器macOS若计划在单机上用 orchestrator 管理多个 beads 项目可以运行一个持久化的中央 Dolt 服务器替代每项目一个的嵌入式实例。嵌入式 vs 中央服务器嵌入式默认中央服务器搭建成本零配置——bd init全自动需一次性服务器搭建数据位置每项目.beads/embeddeddolt/中央目录如/opt/homebrew/var/dolt并发能力每项目单写者通过 MySQL 协议多写者适用场景单人开发、单代理orchestrator、多项目、多代理为什么不能用brew services start doltbrew install dolt之后最自然的想法是brew services start dolt但这条命令会静默忽略你的配置文件Homebrew formula 调用dolt sql-server时没有传--config标志而 Dolt不会从工作目录自动发现config.yaml——配置文件必须通过--config file显式传入。因此编辑/opt/homebrew/var/dolt/config.yaml端口、host 等对brew services启动的进程完全不生效。使用自定义 LaunchAgent 搭建1. 安装 Dolt 并初始化数据目录brew install dolt # 初始化 dolt 数据目录若未初始化 cd /opt/homebrew/var/dolt dolt init2. 配置 Dolt 监听 3307 端口# /opt/homebrew/var/dolt/config.yaml log_level: info listener: host: 127.0.0.1 port: 3307 max_connections: 100 behavior: autocommit: true3. 创建 LaunchAgent plistcat ~/Library/LaunchAgents/com.local.dolt-server.plist EOF ?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.local.dolt-server/string keyProgramArguments/key array string/opt/homebrew/opt/dolt/bin/dolt/string stringsql-server/string string--config/string stringconfig.yaml/string /array keyWorkingDirectory/key string/opt/homebrew/var/dolt/string keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/opt/homebrew/var/log/dolt.log/string keyStandardErrorPath/key string/opt/homebrew/var/log/dolt.error.log/string /dict /plist EOF4. 加载服务并验证launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist # 验证已运行 mysql -h 127.0.0.1 -P 3307 -u root -e SELECT 15. 让 beads 指向中央服务器——追加到~/.zshrc或~/.bashrcexport BEADS_DOLT_SERVER_HOST127.0.0.1 export BEADS_DOLT_SERVER_PORT3307 export BEADS_DOLT_SERVER_MODE1此后任意目录执行bd init都会连接中央服务器而不是再拉起一个嵌入式实例。服务管理# 停止 launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist # 重启unload load launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist # 查看日志 tail -f /opt/homebrew/var/log/dolt.log同步模式Beads 仅使用dolt-native同步模式使用 Dolt remotesDoltHub、S3、GCS 等作为传输通道原生数据库级同步带 cell 级 merge支持分支与合并配套工具bd export用于 issue 可移植性bd backup init/bd backup sync/bd backup restore用于 Dolt 原生备份。bd export生成的 JSONL 只包含 issues 表的记录不包含Dolt 分支、完整提交历史、工作集状态或其他表——需要可恢复的数据库备份时必须使用bd backup或手动 Dolt 备份这一点在 docs/architecture/dolt.md 中有明确说明。Dolt 远程仓库Remotes配置远程仓库远程仓库必须通过bd dolt remote add配置该命令同时注册到运行中的 Dolt SQL 服务器的dolt_remotes表与文件系统CLI配置服务器能立即看到新远程。若直接用doltCLI 添加远程只写入文件系统配置服务器需重启才可见。从 cmd/bd/dolt.go 源码看isRemoteNotFoundErr专门识别「仅通过dolt remote add写入文件系统、未注册进 SQLdolt_remotes表」导致的 remote not found 场景这正是双表面注册机制存在的直接原因。# DoltHub公开或私有 bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads # S3 bd dolt remote add origin aws://[bucket]/path/to/repo # GCS bd dolt remote add origin gs://[bucket]/path/to/repo # Git SSHGitHub、GitLab 等 bd dolt remote add origin gitssh://gitgithub.com/org/repo.git # 本地文件系统 bd dolt remote add origin file:///path/to/remote推送与拉取bd dolt push bd dolt pull对于 SSH 远程bd dolt push/bd dolt pull会自动改用doltCLI 传输而非 SQL 服务器以避免传输期间的 MySQL 连接超时若任一表面SQL / CLI已存在同名远程覆盖前会提示确认可与 Git 仓库共享Dolt 数据存放在refs/dolt/data下与标准 Git refsrefs/heads/、refs/tags/隔离因此可以安全地把gitssh://远程指向项目源码所在仓库——代码与 issue 历史共存于一个 Git 仓库。列出与删除远程bd dolt remote list # 同时展示 SQL 服务器与 CLI 两处的远程并标记差异 bd dolt remote remove origin # 从两个表面同时移除远程配置在两个表面出现不一致时用bd doctor --fix修复。从旧版升级的用户若曾用原生dolt remote add添加远程应改用bd dolt remote add name url重新注册使其通过 SQL 可见bd doctor会在 Dolt Remote Migration 项下报告遗留的 CLI-only 或不匹配远程。从 SQLite 迁移遗留注意bd migrate --to-dolt命令已在 v0.58.0 移除。方案一迁移脚本适用于 0.50 之前安装、数据为 JSONL 格式的旧版本scripts/migrate-jsonl-to-dolt.sh迁移会自动创建备份原 SQLite 数据库保留为beads.backup-pre-dolt-*.db。若迁移后遇到连接错误参见 docs/reference/troubleshooting.md 的断路器circuit breaker一节。方案二全新开始# 导出当前状态 bd export -o backup.jsonl # 归档现有 beads mv .beads .beads-sqlite-backup # 从备份初始化全新项目 bd init --from-jsonl故障排查Dolt 数据目录被误提交进 Git更新 gitignorebd doctor --fix从 Git 跟踪移除git rm --cached -r .beads/dolt/嵌入式模式为.beads/embeddeddolt/提交移除git commit -m fix: remove accidentally committed dolt data可选从历史中彻底清除使用 BFG Repo-Cleaner 或git filter-repo服务器无法启动# 检查端口占用 lsof -i :3306 # 查看服务器日志 cat .beads/dolt/sql-server.log # 校验 dolt 安装 dolt version # 尝试手动启动 cd .beads/dolt dolt sql-server --host 127.0.0.1 --port 3306连接问题# 测试连接 mysql -h 127.0.0.1 -P 3306 -u root beads # 检查服务器运行状态 bd doctor # 强制重启 kill $(cat .beads/dolt/sql-server.pid) 2/dev/null bd list # 触发自动启动嵌入式模式出现 database is locked 时意味着单写者文件锁生效若需要并发访问请切换到服务器模式见互迁章节。性能问题运行bd doctor做诊断服务器模式下检查服务器日志中的错误数据库维护可执行dolt gccd .beads/dolt dolt gc高级用法直接操作 Dolt数据目录取决于模式嵌入式为.beads/embeddeddolt/服务器模式为.beads/dolt/。分支cd .beads/dolt # 创建特性分支 dolt checkout -b feature/experiment # 通过 bd 命令写入 bd create experimental issue # 合并回主干 dolt checkout main dolt merge feature/experiment时间旅行cd .beads/dolt # 列出提交 dolt log --oneline # 查询指定提交时的数据 dolt sql -q SELECT * FROM issues AS OF abc123 # 检出历史状态 dolt checkout abc123Diff 与 Blamecd .beads/dolt # 查看上次提交以来的变更 dolt diff # 提交间差异 dolt diff HEAD~5 HEAD -- issues # 逐行溯源谁改了什么 dolt blame issues配置参考完整配置示例# .beads/config.yaml backend: dolt sync: mode: dolt-native auto_dolt_commit: true # 同步后自动提交默认: true auto_dolt_push: false # 同步后自动推送默认: false dolt: server_mode: false # 使用 sql-server默认: false —— 嵌入式模式 server_host: 127.0.0.1 # 仅 server_mode: true 时生效 server_port: 3307 server_user: root server_pass: # 锁设置 lock_retries: 30 lock_retry_delay: 100ms idle_timeout: 30s federation: remote: dolthub://myorg/beads sovereignty: T3 # T1-T4补充实际配置键名以 docs/architecture/dolt.md 中的dolt.auto-commit、dolt.mode、dolt.shared-server为准。嵌入式模式默认自动提交每条写命令产生一个 Dolt 提交服务器模式默认关闭自动提交——服务器自行管理事务生命周期并发负载下每次写后触发DOLT_COMMIT会引发 database is read only 错误。环境变量变量说明BEADS_DOLT_SERVER_MODE服务器模式1或0BEADS_DOLT_SERVER_HOST服务器主机BEADS_DOLT_SERVER_PORT服务器端口共享模式默认 3308BEADS_DOLT_SERVER_USER服务器用户BEADS_DOLT_SERVER_PASS服务器密码BEADS_DOLT_PASSWORD服务器模式密码优先级最高BEADS_CREDENTIALS_FILE凭据文件路径覆盖默认位置BEADS_DOLT_SERVER_SOCKETUnix 域套接字路径替代 TCPBEADS_DOLT_SHARED_SERVER共享服务器模式开关DOLT_REMOTE_USER/DOLT_REMOTE_PASSWORD克隆/推送/拉取的认证凭据BD_DOLT_AUTO_COMMIT覆盖自动提交设置凭据文件多服务器场景多服务器环境可把密码存在 INI 风格凭据文件中按[host:port]段查找每个项目自动匹配其配置服务器对应的密码。密码解析顺序BEADS_DOLT_PASSWORD环境变量最高→ 凭据文件按[host:port]查找使用运行时解析出的实际端口→ 空字符串。默认位置Linux/macOS 为~/.config/beads/credentialsWindows 为%APPDATA%\beads\credentials可用BEADS_CREDENTIALS_FILE覆盖。文件格式与权限# ~/.config/beads/credentials [127.0.0.1:3307] passwordlocalDevPassword [beads.company.com:3307] passwordteamServerPasswordchmod 600 ~/.config/beads/credentials嵌入式与服务器模式互迁使用bd backup在嵌入式与服务器模式之间迁移数据两个方向都完整保留 Dolt 提交历史。bd export不能替代该流程见上文同步模式说明。逐步指引见 docs/architecture/dolt.md 的 Migrating Between Backends 章节。快速参考# 1. 备份源项目 bd backup init /path/to/backup-dir bd backup sync # 2. 创建目标项目并恢复 mkdir target cd target bd init # 或 bd init --server bd backup restore --force /path/to/backup-dir # 3. 验证 bd list关键细节数据位置不同嵌入式为.beads/embeddeddolt/服务器模式为.beads/dolt/恢复到已初始化项目时--force是必需的覆盖数据库restore 会自动注册备份目录供后续bd backup sync使用、更新项目身份metadata.json、回填嵌入式迁移跟踪器schema_migrations嵌入式模式使用文件锁flock——同一时刻只有一个写者替代方案若两个项目共享同一远程可用 Dolt remotes 迁移bd dolt push/bd dolt pull。备份命令参考与 docs/architecture/dolt.md 一致命令说明bd backup init path注册备份目标文件系统或 DoltHub URLbd backup sync推送数据库到备份目标bd backup restore [path]从备份目录恢复--force覆盖bd backup remove注销备份目标bd backup status显示备份配置与最近同步时间参考链接docs/architecture/dolt.mdDolt 后端总览、版本固定标准、federation 与模式细节docs/reference/troubleshooting.md通用故障排查scripts/migrate-jsonl-to-dolt.sh旧版 JSONL 数据迁移脚本cmd/bd/dolt.gobd dolt系列命令实现远程双表面注册、嵌入式守卫internal/doltserver/doltserver.go共享服务器模式实现3308 端口、~/.beads/shared-server/【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beads 的 Dolt 存储后端完全指南：嵌入式与服务器双模式、远程同步与数据迁移
Beads 的 Dolt 存储后端完全指南嵌入式与服务器双模式、远程同步与数据迁移【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 将 Dolt 为骨架结合 docs/architecture/dolt.md 与仓库源码系统讲解嵌入式Embedded与服务器Server两种运行模式、bd dolt远程仓库管理、SQLite 遗留迁移、故障排查与高级 Dolt 用法读完即可独立完成 Beads 项目的初始化、多代理并发部署与跨机同步配置。为什么 Beads 选择 DoltBeads 的每一项写操作都会产生一个 Dolt 提交因此bd create、bd comment等命令天然具备可审计的历史轨迹。核心能力对比如下能力维度Dolt 实现方式存储形态目录式存储.beads/embeddeddolt/或.beads/dolt/版本控制原生支持单元cell级 diff 与 merge而非行级文本比对分支原生支持独立于 Git 分支体系时间旅行支持AS OF查询与历史 checkout冲突合并SQL 语义的 cell 级 merge多用户并发通过 Server 模式MySQL 协议实现跨机同步原生 push/pull 到 Dolt remotesDoltHub、S3、GCS、Git SSH、本地文件从源码看cmd/bd/dolt.go 明确写有 Beads runs Dolt embedded (in-process) by default默认嵌入式引擎随bd二进制内联无需额外安装 Dolt 客户端。快速开始1. 安装 Dolt仅服务器模式需要嵌入式模式将 Dolt 引擎直接编译进bd二进制版本由 go.mod 固定无需单独安装 Dolt只有运行服务器模式或希望用dolt sql直接操作数据库时才需要独立 CLI。安装时有两条硬性约束务必先读 docs/architecture/dolt.md不要安装releases/latestDolt 2.3.x 存在数据操作缺陷CALL DOLT_RESET(--hard)在约 3% 的新建库上返回Error 1105 (HY000): context canceled会直接破坏bd flatten与bd admin compact。Beads 将版本固定为2.2.0CI 通过scripts/ci/install-dolt.sh安装同一固定版本其中记录着各版本测量数据与提版标准。不要依赖brew install dolt的版本Homebrew formula 指向的版本未固定安装后必须用dolt version核对。# 校验安装到的版本 dolt version2. 初始化项目# 新项目Dolt 是默认后端默认进入嵌入式模式 bd init3. 配置同步模式# .beads/config.yaml sync: mode: dolt-native # 默认值使用 Dolt remotes 做原生同步嵌入式模式默认嵌入式模式将 Dolt 引擎运行在bd进程内部无需独立服务器是所有bd init安装的默认形态——执行bd init即可使用。零配置无服务器、无端口、无 PID 文件单写者同一时刻仅允许一个进程写入由文件锁flock强制执行数据位置.beads/embeddeddolt/与代码同目录存放。与之呼应cmd/bd/dolt.go 中对bd dolt set、bd dolt test、bd dolt start、bd dolt stop均做了嵌入式模式守卫直接返回bd dolt ... is not supported in embedded mode (no Dolt server)。服务器模式按需开启当需要多代理并发写入多个 Agent、orchestrator 编排环境时切换到服务器模式连接一个运行中的dolt sql-server。开启服务器模式# 初始化时指定 bd init --server # 或用环境变量 export BEADS_DOLT_SERVER_MODE1 bd init已存在的嵌入式项目切换方法见下文「嵌入式与服务器模式互迁」一节。此外 docs/architecture/dolt.md 还提供了 Unix 域套接字连接方式--server-socket标志对应环境变量BEADS_DOLT_SERVER_SOCKET可避开端口冲突适用于 Claude Code 等沙箱环境。服务器配置项环境变量默认值说明BEADS_DOLT_SERVER_MODE空设为1开启服务器模式BEADS_DOLT_SERVER_HOST127.0.0.1服务器绑定地址BEADS_DOLT_SERVER_PORT3307服务器端口MySQL 协议避开 3306 的 MySQL 冲突BEADS_DOLT_SERVER_USERrootMySQL 用户名BEADS_DOLT_SERVER_PASS空MySQL 密码BEADS_DOLT_SHARED_SERVER空共享服务器模式1或true开启环境变量在 cmd/bd/bootstrap.go 等文件中直接参与端口与模式的解析优先级高于配置文件。服务器生命周期管理以下命令仅服务器模式可用嵌入式模式会报错退出# 检查服务器状态 bd doctor # 启停与状态 bd dolt start bd dolt stop bd dolt status # 仅服务器可用的配置命令嵌入式模式报错 bd dolt show bd dolt set bd dolt test在 orchestrator 编排场景bd dolt系列命令会自动拉起/停止项目自己的dolt sql-serverbd doctor同时负责校验服务器健康度与端口一致性。共享服务器模式Shared Server Mode多项目机器上每个项目默认会启动自己的 Dolt 服务器。共享服务器模式让所有项目共用一个 Dolt 服务器进程# 通过配置开启 bd dolt set shared-server true # 或通过环境变量机器级生效 export BEADS_DOLT_SHARED_SERVER1共享服务器状态存放于~/.beads/shared-server/默认端口为 3308避开 orchestrator 使用的 3307。每个项目的数据以其项目前缀命名的独立数据库隔离例如~/.beads/shared-server/dolt/myproject/。从 internal/doltserver/doltserver.go 源码可以看到关键实现细节const DefaultSharedServerPort 3308共享模式默认端口定义IsSharedServerMode()同时检查环境变量与dolt.shared-server配置项SharedServerDir()返回~/.beads/shared-server/dolt/作为共享数据目录。重要约束共享服务器上的每个项目必须有唯一前缀数据库名。若两个项目前缀相同导致数据库共用项目身份校验会检测到不一致并拒绝连接防止静默数据损坏。中央 Dolt 服务器macOS若计划在单机上用 orchestrator 管理多个 beads 项目可以运行一个持久化的中央 Dolt 服务器替代每项目一个的嵌入式实例。嵌入式 vs 中央服务器嵌入式默认中央服务器搭建成本零配置——bd init全自动需一次性服务器搭建数据位置每项目.beads/embeddeddolt/中央目录如/opt/homebrew/var/dolt并发能力每项目单写者通过 MySQL 协议多写者适用场景单人开发、单代理orchestrator、多项目、多代理为什么不能用brew services start doltbrew install dolt之后最自然的想法是brew services start dolt但这条命令会静默忽略你的配置文件Homebrew formula 调用dolt sql-server时没有传--config标志而 Dolt不会从工作目录自动发现config.yaml——配置文件必须通过--config file显式传入。因此编辑/opt/homebrew/var/dolt/config.yaml端口、host 等对brew services启动的进程完全不生效。使用自定义 LaunchAgent 搭建1. 安装 Dolt 并初始化数据目录brew install dolt # 初始化 dolt 数据目录若未初始化 cd /opt/homebrew/var/dolt dolt init2. 配置 Dolt 监听 3307 端口# /opt/homebrew/var/dolt/config.yaml log_level: info listener: host: 127.0.0.1 port: 3307 max_connections: 100 behavior: autocommit: true3. 创建 LaunchAgent plistcat ~/Library/LaunchAgents/com.local.dolt-server.plist EOF ?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyLabel/key stringcom.local.dolt-server/string keyProgramArguments/key array string/opt/homebrew/opt/dolt/bin/dolt/string stringsql-server/string string--config/string stringconfig.yaml/string /array keyWorkingDirectory/key string/opt/homebrew/var/dolt/string keyRunAtLoad/key true/ keyKeepAlive/key true/ keyStandardOutPath/key string/opt/homebrew/var/log/dolt.log/string keyStandardErrorPath/key string/opt/homebrew/var/log/dolt.error.log/string /dict /plist EOF4. 加载服务并验证launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist # 验证已运行 mysql -h 127.0.0.1 -P 3307 -u root -e SELECT 15. 让 beads 指向中央服务器——追加到~/.zshrc或~/.bashrcexport BEADS_DOLT_SERVER_HOST127.0.0.1 export BEADS_DOLT_SERVER_PORT3307 export BEADS_DOLT_SERVER_MODE1此后任意目录执行bd init都会连接中央服务器而不是再拉起一个嵌入式实例。服务管理# 停止 launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist # 重启unload load launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist # 查看日志 tail -f /opt/homebrew/var/log/dolt.log同步模式Beads 仅使用dolt-native同步模式使用 Dolt remotesDoltHub、S3、GCS 等作为传输通道原生数据库级同步带 cell 级 merge支持分支与合并配套工具bd export用于 issue 可移植性bd backup init/bd backup sync/bd backup restore用于 Dolt 原生备份。bd export生成的 JSONL 只包含 issues 表的记录不包含Dolt 分支、完整提交历史、工作集状态或其他表——需要可恢复的数据库备份时必须使用bd backup或手动 Dolt 备份这一点在 docs/architecture/dolt.md 中有明确说明。Dolt 远程仓库Remotes配置远程仓库远程仓库必须通过bd dolt remote add配置该命令同时注册到运行中的 Dolt SQL 服务器的dolt_remotes表与文件系统CLI配置服务器能立即看到新远程。若直接用doltCLI 添加远程只写入文件系统配置服务器需重启才可见。从 cmd/bd/dolt.go 源码看isRemoteNotFoundErr专门识别「仅通过dolt remote add写入文件系统、未注册进 SQLdolt_remotes表」导致的 remote not found 场景这正是双表面注册机制存在的直接原因。# DoltHub公开或私有 bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads # S3 bd dolt remote add origin aws://[bucket]/path/to/repo # GCS bd dolt remote add origin gs://[bucket]/path/to/repo # Git SSHGitHub、GitLab 等 bd dolt remote add origin gitssh://gitgithub.com/org/repo.git # 本地文件系统 bd dolt remote add origin file:///path/to/remote推送与拉取bd dolt push bd dolt pull对于 SSH 远程bd dolt push/bd dolt pull会自动改用doltCLI 传输而非 SQL 服务器以避免传输期间的 MySQL 连接超时若任一表面SQL / CLI已存在同名远程覆盖前会提示确认可与 Git 仓库共享Dolt 数据存放在refs/dolt/data下与标准 Git refsrefs/heads/、refs/tags/隔离因此可以安全地把gitssh://远程指向项目源码所在仓库——代码与 issue 历史共存于一个 Git 仓库。列出与删除远程bd dolt remote list # 同时展示 SQL 服务器与 CLI 两处的远程并标记差异 bd dolt remote remove origin # 从两个表面同时移除远程配置在两个表面出现不一致时用bd doctor --fix修复。从旧版升级的用户若曾用原生dolt remote add添加远程应改用bd dolt remote add name url重新注册使其通过 SQL 可见bd doctor会在 Dolt Remote Migration 项下报告遗留的 CLI-only 或不匹配远程。从 SQLite 迁移遗留注意bd migrate --to-dolt命令已在 v0.58.0 移除。方案一迁移脚本适用于 0.50 之前安装、数据为 JSONL 格式的旧版本scripts/migrate-jsonl-to-dolt.sh迁移会自动创建备份原 SQLite 数据库保留为beads.backup-pre-dolt-*.db。若迁移后遇到连接错误参见 docs/reference/troubleshooting.md 的断路器circuit breaker一节。方案二全新开始# 导出当前状态 bd export -o backup.jsonl # 归档现有 beads mv .beads .beads-sqlite-backup # 从备份初始化全新项目 bd init --from-jsonl故障排查Dolt 数据目录被误提交进 Git更新 gitignorebd doctor --fix从 Git 跟踪移除git rm --cached -r .beads/dolt/嵌入式模式为.beads/embeddeddolt/提交移除git commit -m fix: remove accidentally committed dolt data可选从历史中彻底清除使用 BFG Repo-Cleaner 或git filter-repo服务器无法启动# 检查端口占用 lsof -i :3306 # 查看服务器日志 cat .beads/dolt/sql-server.log # 校验 dolt 安装 dolt version # 尝试手动启动 cd .beads/dolt dolt sql-server --host 127.0.0.1 --port 3306连接问题# 测试连接 mysql -h 127.0.0.1 -P 3306 -u root beads # 检查服务器运行状态 bd doctor # 强制重启 kill $(cat .beads/dolt/sql-server.pid) 2/dev/null bd list # 触发自动启动嵌入式模式出现 database is locked 时意味着单写者文件锁生效若需要并发访问请切换到服务器模式见互迁章节。性能问题运行bd doctor做诊断服务器模式下检查服务器日志中的错误数据库维护可执行dolt gccd .beads/dolt dolt gc高级用法直接操作 Dolt数据目录取决于模式嵌入式为.beads/embeddeddolt/服务器模式为.beads/dolt/。分支cd .beads/dolt # 创建特性分支 dolt checkout -b feature/experiment # 通过 bd 命令写入 bd create experimental issue # 合并回主干 dolt checkout main dolt merge feature/experiment时间旅行cd .beads/dolt # 列出提交 dolt log --oneline # 查询指定提交时的数据 dolt sql -q SELECT * FROM issues AS OF abc123 # 检出历史状态 dolt checkout abc123Diff 与 Blamecd .beads/dolt # 查看上次提交以来的变更 dolt diff # 提交间差异 dolt diff HEAD~5 HEAD -- issues # 逐行溯源谁改了什么 dolt blame issues配置参考完整配置示例# .beads/config.yaml backend: dolt sync: mode: dolt-native auto_dolt_commit: true # 同步后自动提交默认: true auto_dolt_push: false # 同步后自动推送默认: false dolt: server_mode: false # 使用 sql-server默认: false —— 嵌入式模式 server_host: 127.0.0.1 # 仅 server_mode: true 时生效 server_port: 3307 server_user: root server_pass: # 锁设置 lock_retries: 30 lock_retry_delay: 100ms idle_timeout: 30s federation: remote: dolthub://myorg/beads sovereignty: T3 # T1-T4补充实际配置键名以 docs/architecture/dolt.md 中的dolt.auto-commit、dolt.mode、dolt.shared-server为准。嵌入式模式默认自动提交每条写命令产生一个 Dolt 提交服务器模式默认关闭自动提交——服务器自行管理事务生命周期并发负载下每次写后触发DOLT_COMMIT会引发 database is read only 错误。环境变量变量说明BEADS_DOLT_SERVER_MODE服务器模式1或0BEADS_DOLT_SERVER_HOST服务器主机BEADS_DOLT_SERVER_PORT服务器端口共享模式默认 3308BEADS_DOLT_SERVER_USER服务器用户BEADS_DOLT_SERVER_PASS服务器密码BEADS_DOLT_PASSWORD服务器模式密码优先级最高BEADS_CREDENTIALS_FILE凭据文件路径覆盖默认位置BEADS_DOLT_SERVER_SOCKETUnix 域套接字路径替代 TCPBEADS_DOLT_SHARED_SERVER共享服务器模式开关DOLT_REMOTE_USER/DOLT_REMOTE_PASSWORD克隆/推送/拉取的认证凭据BD_DOLT_AUTO_COMMIT覆盖自动提交设置凭据文件多服务器场景多服务器环境可把密码存在 INI 风格凭据文件中按[host:port]段查找每个项目自动匹配其配置服务器对应的密码。密码解析顺序BEADS_DOLT_PASSWORD环境变量最高→ 凭据文件按[host:port]查找使用运行时解析出的实际端口→ 空字符串。默认位置Linux/macOS 为~/.config/beads/credentialsWindows 为%APPDATA%\beads\credentials可用BEADS_CREDENTIALS_FILE覆盖。文件格式与权限# ~/.config/beads/credentials [127.0.0.1:3307] passwordlocalDevPassword [beads.company.com:3307] passwordteamServerPasswordchmod 600 ~/.config/beads/credentials嵌入式与服务器模式互迁使用bd backup在嵌入式与服务器模式之间迁移数据两个方向都完整保留 Dolt 提交历史。bd export不能替代该流程见上文同步模式说明。逐步指引见 docs/architecture/dolt.md 的 Migrating Between Backends 章节。快速参考# 1. 备份源项目 bd backup init /path/to/backup-dir bd backup sync # 2. 创建目标项目并恢复 mkdir target cd target bd init # 或 bd init --server bd backup restore --force /path/to/backup-dir # 3. 验证 bd list关键细节数据位置不同嵌入式为.beads/embeddeddolt/服务器模式为.beads/dolt/恢复到已初始化项目时--force是必需的覆盖数据库restore 会自动注册备份目录供后续bd backup sync使用、更新项目身份metadata.json、回填嵌入式迁移跟踪器schema_migrations嵌入式模式使用文件锁flock——同一时刻只有一个写者替代方案若两个项目共享同一远程可用 Dolt remotes 迁移bd dolt push/bd dolt pull。备份命令参考与 docs/architecture/dolt.md 一致命令说明bd backup init path注册备份目标文件系统或 DoltHub URLbd backup sync推送数据库到备份目标bd backup restore [path]从备份目录恢复--force覆盖bd backup remove注销备份目标bd backup status显示备份配置与最近同步时间参考链接docs/architecture/dolt.mdDolt 后端总览、版本固定标准、federation 与模式细节docs/reference/troubleshooting.md通用故障排查scripts/migrate-jsonl-to-dolt.sh旧版 JSONL 数据迁移脚本cmd/bd/dolt.gobd dolt系列命令实现远程双表面注册、嵌入式守卫internal/doltserver/doltserver.go共享服务器模式实现3308 端口、~/.beads/shared-server/【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
