Beads Federation 实战指南基于 Dolt Remotes 的多工作区对等同步【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 的 Federation联邦机制利用 Dolt 的分布式版本控制能力让多个工作区各自维护独立的 beads 数据库同时通过配置的 peer对等节点双向同步 issue 数据。本指南以 docs/multi-agent/federation.md 为主线结合bd federation命令族与存储层源码完整讲解联邦的配置、peer 管理、同步策略、主权分级与跨副本租约治理读完即可在独立团队或跨地域站点之间搭建一套无需中央服务器的 issue 同步网络。概览为什么需要 FederationFederation 解决的是多个独立团队或站点之间共享 issue 数据的问题。与文件导出、导入不同它直接复用 Dolt 的分布式版本控制能力每个工作区保留自己的数据库只把工作项增量同步给已配置的 peer。其核心收益包括Peer-to-peer对等网络无需中央服务器每个站点文档中称 town自治运行数据库原生版本化同步基于 Dolt 的版本控制而非文件导出基础设施灵活远端可选用 DoltHub、S3、GCS、本地路径或 SSH数据主权分级提供可配置的主权分级T1–T4满足 GDPR 等合规要求。如果你只需要两台机器通过一个自己拥有的对象存储桶共享同一个数据库可以参考 Bucket Federation Quickstart 的端到端路径——它覆盖建桶、种子推送、第二副本诞生、同步节奏与故障模式并给出了实测耗时。前置条件Dolt 存储后端联邦功能只支持 Dolt 后端这是唯一受支持的存储后端。命令行的 Long 描述也明确写着Requires the Dolt storage backend见 cmd/bd/federation.go。此外联邦命令要求对数据库的直接访问权限——proxied-server代理服务器模式下会直接拒绝执行federation sync is not supported in proxied-server mode。配置联邦兼容的同步编辑项目内的.beads/config.yaml或用户全局的~/.config/bd/config.yamlfederation: remote: dolthub://myorg/beads # Primary remote (可选) sovereignty: T2 # 数据主权分级也可以使用环境变量export BD_FEDERATION_REMOTEdolthub://myorg/beads export BD_FEDERATION_SOVEREIGNTYT2在 docs/reference/configuration.md 的 Sync and Federation 一节中这两个配置项被进一步细化federation.remoteDolt 远端 URL支持dolthub://org/beads、gs://bucket/beads、s3://bucket/beads、az://account.blob.core.windows.net/container/beads、file://...等 schemefederation.sovereignty数据主权分级 T1–T4含义见下表federation.allowed-remote-patterns用于限制允许的远端 URL 的 glob 模式列表默认[]federation.exclude_types从联邦推送中排除的 issue 类型默认[wisp]。bd config validate会校验远端 URL 格式、主权分级、federation.allowed-remote-patterns以及routing.mode。在 CLI 端add-peer也支持--sovereignty标志合法值为 T1、T2、T3、T4输入会自动转为大写再校验非法值直接报错。数据主权分级Sovereignty Tiers分级描述适用场景T1无限制Full sovereignty数据不离开受控基础设施公开数据T2组织级Regional sovereignty数据留在区域/司法管辖区区域/公司合规T3假名化Provider sovereignty数据托管于可信云厂商移除标识符T4匿名No restrictions数据可位于任何地方最大隐私添加联邦 Peer使用bd federation add-peer注册远端 peerbd federation add-peer name endpointPeer 命名规则必须以字母开头仅允许字母数字、连字符-和下划线_最大长度 64 字符。支持的 Endpoint 格式格式示例描述DoltHubdolthub://org/repoDoltHub 托管的仓库Google Cloudgs://bucket/pathGoogle Cloud StorageAmazon S3s3://bucket/pathAmazon S3本地file:///path/to/backup本地文件系统HTTPShttps://host/pathHTTPS 远端SSHssh://host/pathSSH 远端Git SSHgithost:pathGit SSH 简写注意add-peer的 Long 帮助中还支持一种直接连接 dolt sql-server的形式——host:port/database如192.168.1.100:3306/beads用于直连模式。示例# 在 DoltHub 上添加一个 staging 环境 bd federation add-peer staging dolthub://myorg/staging-beads # 添加云端备份 bd federation add-peer backup gs://mybucket/beads-backup bd federation add-peer backup-s3 s3://mybucket/beads-backup # 添加本地备份 bd federation add-peer local file:///home/user/beads-backup # 添加合作伙伴组织 bd federation add-peer partner-town dolthub://partner-org/beads从源码看cmd/bd/federation.go 的runFederationAddPeeradd-peer实际有两条注册路径带凭证提供--user时构造storage.FederationPeer含 Name、RemoteURL、Username、Password、Sovereignty调用store.AddFederationPeer凭证会落入加密存储见下文凭证管理不带凭证仅调用store.AddRemote(ctx, name, url)等价于git remote add。凭证管理以--user可配合--password否则交互式提示输入配置的 peer其 SQL 凭证会以AES-256 加密后存储在本地。同步时自动使用已存储的凭证bd federation add-peer town-gamma 192.168.1.100:3306/beads --user sync-bot凭证加密的实现在 internal/storage/dolt/credentials.go 中数据库旁会生成一个随机 32 字节的加密密钥即 AES-256存于federation_peers表的password_encrypted列中。该文件还包含migrateCredentialKeys迁移逻辑——将旧的、由数据库路径推导出的可预测密钥加密的密码重新用随机密钥加密一遍说明凭证体系经历了从可推导密钥到随机密钥的安全加固。加密密钥文件federation credential key会被bd init写入的.beads/.gitignore排除在版本控制之外。JSON 输出脚本化使用--json标志bd --json federation add-peer staging dolthub://myorg/staging-beads # {added:staging,url:dolthub://myorg/staging-beads,has_auth:false,sovereignty:}输出字段包括addedpeer 名、url、has_auth是否带凭证、sovereignty分级。federation sync、federation status、federation list-peers、federation remove-peer均支持--json便于在定时任务或 CI 中做机器可解析的状态判断。验证配置列出已配置的 peerbd federation list-peers与 Peer 同步使用bd federation sync从 peer 拉取并向 peer 推送bd federation status在不传输数据的前提下检查同步状态# 与所有 peer 同步 bd federation sync # 与指定 peer 同步 bd federation sync --peer town-beta # 处理冲突 bd federation sync --strategy theirs # 或 ours # 检查状态ahead/behind、可达性、冲突 bd federation status bd federation status --peer town-beta关键语义均有源码佐证不带--peer时sync会列出所有远端并把origin排除在外if r.Name ! origin对其余每个 peer 逐一执行同步status则包含全部远端--strategy只接受ours或theirs其他值直接报错invalid strategy不带--strategy遇到合并冲突时同步会暂停并报告冲突表交由人工解决绝不自动解析status会执行一次轻量 fetch来探测可达性并刷新 ahead/behind 数据ds.Fetch失败即标记Unreachable同时展示LocalAhead/LocalBehind提交数、LastSync时间与HasConflicts状态还会提示本地的 pending changes 数量。冲突处理的底层调用链以 internal/storage/dolt/federation.go 的Sync实现为例一次同步的完整流程是提交前自动提交commitBeforePull同步开始前先把未提交的变更含 config其中kv.memory.*持久化记忆行位于其中提交掉否则 DOLT_MERGE 会以 cannot merge with uncommitted changes 失败——这是add-peer写入配置元数据后最容易踩的坑Fetch从 peer 拉取远端分支Merge合并peer/branch分支得到冲突列表冲突处理无策略时返回错误提示人工介入有策略时对每个冲突字段调用ResolveConflicts随后CommitMergeResolution提交解决结果同样包含 config并重算is_blocked——因为冲突的合并会跳过自动的 is_blocked 重算必须在解决提交后补齐整个 mergeresolution 窗口推送合并成功后把本地提交推回 peer。拓扑模式Topologies模式描述适用场景Hub-spoke星型中心 hub卫星节点同步到 hub需要中央协调的团队Mesh网状所有 peer 两两互相同步去中心化协作Hierarchical层级由多个 hub 组成的树多团队组织架构原理工作原理每个工作区拥有自己的 Dolt 数据库add-peer注册一个 Dolt 远端类似git remote addbd federation sync在 peer 之间推送和拉取提交冲突解决遵循配置的策略。针对 Dolt SQL server 部署时联邦使用两个端口MySQL3306提供多写者 SQL 访问remotesapi8080用于 peer 间的 push/pull┌─────────────────┐ ┌─────────────────┐ │ Workspace A │◄───────►│ Workspace B │ │ dolt sql-server│ sync │ dolt sql-server│ │ :3306 (sql) │ │ :3306 (sql) │ │ :8080 (remote) │ │ :8080 (remote) │ └─────────────────┘ └─────────────────┘多仓库支持Multi-RepoIssue 通过其SourceSystem字段标识由哪个联邦系统创建从而在跨组织场景下建立正确的归属与信任链该字段在 internal/storage/issueops/public_create.go 的克隆创建路径中随 issue 一并复制。连通性远端连通性在首次 push/pull 操作时验证而非添加 peer 时。因此你可以在基础设施就绪之前就完成 peer 配置——文档明确指出Remote connectivity is validated on first push/pull operation, not when adding the peer。存储接口层联邦能力通过internal/storage/versioned.go暴露的版本化存储接口与FederationStore接口见 internal/storage/federation.go含AddFederationPeer/GetFederationPeer/ListFederationPeers/RemoveFederationPeer实现Dolt 的具体实现位于 internal/storage/dolt/store.go 与 internal/storage/dolt/federation.go。租约按副本生效Leases are per-replica这是联邦部署中最容易出事故、也最需要理解透彻的部分。一次认领租约bd ready --claimbd heartbeat由bd reclaim收割只在授予它的那个副本上有意义。leases表是克隆本地的从不复制跨桥传输的只有 claim 的可见性——issue 行上的status/assignee——而它在其他副本上的可见性最多滞后一个同步周期。联邦部署必须同时满足两条规则宽限窗口 同步周期且租约 TTL 同步周期。若 TTL 或bd reclaim --older-than的宽限小于副本交换状态的节奏跨桥判断就是无意义的远端视图天生落后一个完整周期那边的收割者会用比租约本身还旧的数据判断存活。bd reclaim默认宽限为租约 TTL 的 2 倍请把 TTL或宽限提高到同步周期之上永远不要为了迁就它们而缩短同步周期。收割权属于授予副本。每个租约记录授予它的副本bd reclaim会跳过其他副本授予的租约并在 stderr 上点名报告。在雇佣了工人的那台机器上收割死掉的 worker。守卫是 opt-in 的为副本命名守卫只在给副本命名后才生效export BEADS_NODE_IDmini # 每台机器或 bd config set node_id mininode_id配置键由 cmd/bd/config.go 声明为replica identity for the lease guard (read from yaml/env, never the DB)。关于命名两条规则都是承重的node_id命名的是 STORE存储不是主机。每个 beads数据库一个值。作为同一个dolt sql-serverBEADS_DOLT_SERVER_HOST、systemd/Docker 服务器、Hosted Dolt、VPS的客户端的多个主机无论多少台机器都是一个副本——给它们同一个值或保持未设置。若给了不同 id就会重建下述 fail-closed 回归supervisor 匹配不到任何 worker 的租约永远收割 0 个。只有存在真实的同步周期时才为某个副本命名。node_id是逐机器的因此绝不能提交入库。项目内的.beads/config.yaml是 git跟踪的文件。一旦把node_id提交进去一台机器的身份就会传播给所有克隆它的副本然后所有比较都匹配守卫完全武装却又完全惰性laptop会像收割本地租约一样收割mini的租约——这正是该特性要关闭的隐患却在你以为受保护时发生。这比完全不设置更糟。因此bd config set node_id写入用户全局的~/.config/bd/config.yaml与其它逐机器状态sync-state.json、push-state.json、redirect并列。请使用环境变量或该命令永远不要手工把node_id加进.beads/config.yaml。刻意没有主机名回退主机名回答的是错误的问题——它命名的是客户端进程的机器而非存储。在那些最需要自动收割的拓扑里猜主机名必然出错共享或远程 dolt sql-serverBEADS_DOLT_SERVER_HOST、Hosted Dolt、VPS下多个主机是一个存储的客户端、彼此之间没有同步周期按主机名分配身份会让 supervisor 收割不到任何 worker 的租约容器里主机名是每次运行的容器 IDmacOS 的瞬态主机名跟随网络变化。这些都会在一个根本没有联邦的部署上把工作困死——比守卫要防止的失败更糟。所以未设置身份时行为降级为旧行为每个租约都视为本地而不是 fail-closed升级以及任何单存储部署永远不会困死收割者以前能恢复的租约。该特性落地前授予的租约同样不带副本标记会一直保持可收割状态直到某次 heartbeat 用已配置的 node 重新盖戳。解除守卫bd reclaim --any-replicabd reclaim --any-replica解除守卫。它适用于永久消失的副本或已被重命名、现在把自身旧租约视为外来的节点——这不是常规设置因为只有授予机器才对持有者是否存活有第一手视角。bd reclaim会把它拒绝的租约在 stderr 上一行总结配合bd -v可展开到前 20 条租约明细。heartbeat 证明存活但不移动租约普通 heartbeat 只在授予副本仍为空时回填它——不会覆盖一条明确命名了归属方的行。所以租约通常终身保留其授予副本以下状态会困死一条正被本地 heartbeat 维持的租约被重命名的副本mini→mini2持续 heartbeat 自己的租约而这些租约从此永远显示为外来通过 JSONL 互操作流入的外来租约其持有者名在本地也存在于是在这里被 heartbeat但仍带着远端节点标签导入落到一条已过期的本地租约行上时会连同授予副本一起整行采用快照——于是本节点自己的陈旧租约可能带着远端标签回归。唯一能让租约反向移动的路径是heartbeat 的持有者是租约行持有者的不同拼写——它会通过 upsert 重新武装盖上新节点戳。当确认授予副本不再收割后可用bd reclaim --any-replica恢复被困租约。确认授予副本不再收割正是该守卫的全部意义因此优先使用窄形式对单个 issue 用bd reclaim --any-replica --id id或bd unclaim --force id裸的全局形式会回退所有外来陈旧租约包括活着的 peer。bd reclaim会在 stderr 上点名它拒绝的内容——每次运行一条摘要bd -v展开到前 20 条租约明细。在 cmd/bd/reclaim.go 的帮助文本中上述两条不变式grace window sync interval且 lease TTL sync interval被明确标注为守卫无法替你强制执行的前提并再次强调bd reclaim --any-replica是override覆盖开关不是 scope作用域它会加宽处理集合越过每个副本的默认边界。计划中的功能以下操作已有基础设施支持但尚未以命令形式暴露bd federation push peer/bd federation pull peer—— 与单个 peer 的单向同步。bd federation sync已覆盖双向场景。故障排查requires direct database access联邦命令需要 Dolt 后端并提供直接数据库访问。请确保为联邦操作配置了 Dolt 后端proxied-server 模式下联邦子命令会直接返回不支持。peer already exists同名 peer 已存在。换一个名字或先用bd federation list-peers查看现有 peer。无效的 endpoint 格式确保 endpoint 匹配上文列出的某种受支持格式。scheme 必须是dolthub://、gs://、s3://、file://、https://、ssh://或 git SSH 格式githost:pathadd-peer还支持直连形式host:port/database。一般健康检查bd doctor --deep参考全部联邦配置项参见 Configuration 参考federation.remote、federation.sovereignty、federation.allowed-remote-patterns、federation.exclude_types及环境变量覆盖BD_FEDERATION_REMOTE/BD_FEDERATION_SOVEREIGNTY命令实现cmd/bd/federation.goadd-peer/remove-peer/list-peers/sync/status五个子命令含--peer、--strategy、--user/--password、--sovereignty、--json标志存储接口internal/storage/versioned.go版本化存储与Sync/SyncStatus/SyncResult与internal/storage/federation.goFederationStore接口Dolt 实现internal/storage/dolt/store.go、internal/storage/dolt/federation.goSync 完整流程、internal/storage/dolt/credentials.goAES-256 凭证加密与密钥迁移租约守卫cmd/bd/reclaim.go--any-replica、--older-than、--id与 stderr 报告语义桶联邦快速入门见 Bucket Federation Quickstartbd sync与bd federation sync的适用场景对比、退出码约定与实测成本。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Beads Federation 实战指南：基于 Dolt Remotes 的多工作区对等同步
Beads Federation 实战指南基于 Dolt Remotes 的多工作区对等同步【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeads 的 Federation联邦机制利用 Dolt 的分布式版本控制能力让多个工作区各自维护独立的 beads 数据库同时通过配置的 peer对等节点双向同步 issue 数据。本指南以 docs/multi-agent/federation.md 为主线结合bd federation命令族与存储层源码完整讲解联邦的配置、peer 管理、同步策略、主权分级与跨副本租约治理读完即可在独立团队或跨地域站点之间搭建一套无需中央服务器的 issue 同步网络。概览为什么需要 FederationFederation 解决的是多个独立团队或站点之间共享 issue 数据的问题。与文件导出、导入不同它直接复用 Dolt 的分布式版本控制能力每个工作区保留自己的数据库只把工作项增量同步给已配置的 peer。其核心收益包括Peer-to-peer对等网络无需中央服务器每个站点文档中称 town自治运行数据库原生版本化同步基于 Dolt 的版本控制而非文件导出基础设施灵活远端可选用 DoltHub、S3、GCS、本地路径或 SSH数据主权分级提供可配置的主权分级T1–T4满足 GDPR 等合规要求。如果你只需要两台机器通过一个自己拥有的对象存储桶共享同一个数据库可以参考 Bucket Federation Quickstart 的端到端路径——它覆盖建桶、种子推送、第二副本诞生、同步节奏与故障模式并给出了实测耗时。前置条件Dolt 存储后端联邦功能只支持 Dolt 后端这是唯一受支持的存储后端。命令行的 Long 描述也明确写着Requires the Dolt storage backend见 cmd/bd/federation.go。此外联邦命令要求对数据库的直接访问权限——proxied-server代理服务器模式下会直接拒绝执行federation sync is not supported in proxied-server mode。配置联邦兼容的同步编辑项目内的.beads/config.yaml或用户全局的~/.config/bd/config.yamlfederation: remote: dolthub://myorg/beads # Primary remote (可选) sovereignty: T2 # 数据主权分级也可以使用环境变量export BD_FEDERATION_REMOTEdolthub://myorg/beads export BD_FEDERATION_SOVEREIGNTYT2在 docs/reference/configuration.md 的 Sync and Federation 一节中这两个配置项被进一步细化federation.remoteDolt 远端 URL支持dolthub://org/beads、gs://bucket/beads、s3://bucket/beads、az://account.blob.core.windows.net/container/beads、file://...等 schemefederation.sovereignty数据主权分级 T1–T4含义见下表federation.allowed-remote-patterns用于限制允许的远端 URL 的 glob 模式列表默认[]federation.exclude_types从联邦推送中排除的 issue 类型默认[wisp]。bd config validate会校验远端 URL 格式、主权分级、federation.allowed-remote-patterns以及routing.mode。在 CLI 端add-peer也支持--sovereignty标志合法值为 T1、T2、T3、T4输入会自动转为大写再校验非法值直接报错。数据主权分级Sovereignty Tiers分级描述适用场景T1无限制Full sovereignty数据不离开受控基础设施公开数据T2组织级Regional sovereignty数据留在区域/司法管辖区区域/公司合规T3假名化Provider sovereignty数据托管于可信云厂商移除标识符T4匿名No restrictions数据可位于任何地方最大隐私添加联邦 Peer使用bd federation add-peer注册远端 peerbd federation add-peer name endpointPeer 命名规则必须以字母开头仅允许字母数字、连字符-和下划线_最大长度 64 字符。支持的 Endpoint 格式格式示例描述DoltHubdolthub://org/repoDoltHub 托管的仓库Google Cloudgs://bucket/pathGoogle Cloud StorageAmazon S3s3://bucket/pathAmazon S3本地file:///path/to/backup本地文件系统HTTPShttps://host/pathHTTPS 远端SSHssh://host/pathSSH 远端Git SSHgithost:pathGit SSH 简写注意add-peer的 Long 帮助中还支持一种直接连接 dolt sql-server的形式——host:port/database如192.168.1.100:3306/beads用于直连模式。示例# 在 DoltHub 上添加一个 staging 环境 bd federation add-peer staging dolthub://myorg/staging-beads # 添加云端备份 bd federation add-peer backup gs://mybucket/beads-backup bd federation add-peer backup-s3 s3://mybucket/beads-backup # 添加本地备份 bd federation add-peer local file:///home/user/beads-backup # 添加合作伙伴组织 bd federation add-peer partner-town dolthub://partner-org/beads从源码看cmd/bd/federation.go 的runFederationAddPeeradd-peer实际有两条注册路径带凭证提供--user时构造storage.FederationPeer含 Name、RemoteURL、Username、Password、Sovereignty调用store.AddFederationPeer凭证会落入加密存储见下文凭证管理不带凭证仅调用store.AddRemote(ctx, name, url)等价于git remote add。凭证管理以--user可配合--password否则交互式提示输入配置的 peer其 SQL 凭证会以AES-256 加密后存储在本地。同步时自动使用已存储的凭证bd federation add-peer town-gamma 192.168.1.100:3306/beads --user sync-bot凭证加密的实现在 internal/storage/dolt/credentials.go 中数据库旁会生成一个随机 32 字节的加密密钥即 AES-256存于federation_peers表的password_encrypted列中。该文件还包含migrateCredentialKeys迁移逻辑——将旧的、由数据库路径推导出的可预测密钥加密的密码重新用随机密钥加密一遍说明凭证体系经历了从可推导密钥到随机密钥的安全加固。加密密钥文件federation credential key会被bd init写入的.beads/.gitignore排除在版本控制之外。JSON 输出脚本化使用--json标志bd --json federation add-peer staging dolthub://myorg/staging-beads # {added:staging,url:dolthub://myorg/staging-beads,has_auth:false,sovereignty:}输出字段包括addedpeer 名、url、has_auth是否带凭证、sovereignty分级。federation sync、federation status、federation list-peers、federation remove-peer均支持--json便于在定时任务或 CI 中做机器可解析的状态判断。验证配置列出已配置的 peerbd federation list-peers与 Peer 同步使用bd federation sync从 peer 拉取并向 peer 推送bd federation status在不传输数据的前提下检查同步状态# 与所有 peer 同步 bd federation sync # 与指定 peer 同步 bd federation sync --peer town-beta # 处理冲突 bd federation sync --strategy theirs # 或 ours # 检查状态ahead/behind、可达性、冲突 bd federation status bd federation status --peer town-beta关键语义均有源码佐证不带--peer时sync会列出所有远端并把origin排除在外if r.Name ! origin对其余每个 peer 逐一执行同步status则包含全部远端--strategy只接受ours或theirs其他值直接报错invalid strategy不带--strategy遇到合并冲突时同步会暂停并报告冲突表交由人工解决绝不自动解析status会执行一次轻量 fetch来探测可达性并刷新 ahead/behind 数据ds.Fetch失败即标记Unreachable同时展示LocalAhead/LocalBehind提交数、LastSync时间与HasConflicts状态还会提示本地的 pending changes 数量。冲突处理的底层调用链以 internal/storage/dolt/federation.go 的Sync实现为例一次同步的完整流程是提交前自动提交commitBeforePull同步开始前先把未提交的变更含 config其中kv.memory.*持久化记忆行位于其中提交掉否则 DOLT_MERGE 会以 cannot merge with uncommitted changes 失败——这是add-peer写入配置元数据后最容易踩的坑Fetch从 peer 拉取远端分支Merge合并peer/branch分支得到冲突列表冲突处理无策略时返回错误提示人工介入有策略时对每个冲突字段调用ResolveConflicts随后CommitMergeResolution提交解决结果同样包含 config并重算is_blocked——因为冲突的合并会跳过自动的 is_blocked 重算必须在解决提交后补齐整个 mergeresolution 窗口推送合并成功后把本地提交推回 peer。拓扑模式Topologies模式描述适用场景Hub-spoke星型中心 hub卫星节点同步到 hub需要中央协调的团队Mesh网状所有 peer 两两互相同步去中心化协作Hierarchical层级由多个 hub 组成的树多团队组织架构原理工作原理每个工作区拥有自己的 Dolt 数据库add-peer注册一个 Dolt 远端类似git remote addbd federation sync在 peer 之间推送和拉取提交冲突解决遵循配置的策略。针对 Dolt SQL server 部署时联邦使用两个端口MySQL3306提供多写者 SQL 访问remotesapi8080用于 peer 间的 push/pull┌─────────────────┐ ┌─────────────────┐ │ Workspace A │◄───────►│ Workspace B │ │ dolt sql-server│ sync │ dolt sql-server│ │ :3306 (sql) │ │ :3306 (sql) │ │ :8080 (remote) │ │ :8080 (remote) │ └─────────────────┘ └─────────────────┘多仓库支持Multi-RepoIssue 通过其SourceSystem字段标识由哪个联邦系统创建从而在跨组织场景下建立正确的归属与信任链该字段在 internal/storage/issueops/public_create.go 的克隆创建路径中随 issue 一并复制。连通性远端连通性在首次 push/pull 操作时验证而非添加 peer 时。因此你可以在基础设施就绪之前就完成 peer 配置——文档明确指出Remote connectivity is validated on first push/pull operation, not when adding the peer。存储接口层联邦能力通过internal/storage/versioned.go暴露的版本化存储接口与FederationStore接口见 internal/storage/federation.go含AddFederationPeer/GetFederationPeer/ListFederationPeers/RemoveFederationPeer实现Dolt 的具体实现位于 internal/storage/dolt/store.go 与 internal/storage/dolt/federation.go。租约按副本生效Leases are per-replica这是联邦部署中最容易出事故、也最需要理解透彻的部分。一次认领租约bd ready --claimbd heartbeat由bd reclaim收割只在授予它的那个副本上有意义。leases表是克隆本地的从不复制跨桥传输的只有 claim 的可见性——issue 行上的status/assignee——而它在其他副本上的可见性最多滞后一个同步周期。联邦部署必须同时满足两条规则宽限窗口 同步周期且租约 TTL 同步周期。若 TTL 或bd reclaim --older-than的宽限小于副本交换状态的节奏跨桥判断就是无意义的远端视图天生落后一个完整周期那边的收割者会用比租约本身还旧的数据判断存活。bd reclaim默认宽限为租约 TTL 的 2 倍请把 TTL或宽限提高到同步周期之上永远不要为了迁就它们而缩短同步周期。收割权属于授予副本。每个租约记录授予它的副本bd reclaim会跳过其他副本授予的租约并在 stderr 上点名报告。在雇佣了工人的那台机器上收割死掉的 worker。守卫是 opt-in 的为副本命名守卫只在给副本命名后才生效export BEADS_NODE_IDmini # 每台机器或 bd config set node_id mininode_id配置键由 cmd/bd/config.go 声明为replica identity for the lease guard (read from yaml/env, never the DB)。关于命名两条规则都是承重的node_id命名的是 STORE存储不是主机。每个 beads数据库一个值。作为同一个dolt sql-serverBEADS_DOLT_SERVER_HOST、systemd/Docker 服务器、Hosted Dolt、VPS的客户端的多个主机无论多少台机器都是一个副本——给它们同一个值或保持未设置。若给了不同 id就会重建下述 fail-closed 回归supervisor 匹配不到任何 worker 的租约永远收割 0 个。只有存在真实的同步周期时才为某个副本命名。node_id是逐机器的因此绝不能提交入库。项目内的.beads/config.yaml是 git跟踪的文件。一旦把node_id提交进去一台机器的身份就会传播给所有克隆它的副本然后所有比较都匹配守卫完全武装却又完全惰性laptop会像收割本地租约一样收割mini的租约——这正是该特性要关闭的隐患却在你以为受保护时发生。这比完全不设置更糟。因此bd config set node_id写入用户全局的~/.config/bd/config.yaml与其它逐机器状态sync-state.json、push-state.json、redirect并列。请使用环境变量或该命令永远不要手工把node_id加进.beads/config.yaml。刻意没有主机名回退主机名回答的是错误的问题——它命名的是客户端进程的机器而非存储。在那些最需要自动收割的拓扑里猜主机名必然出错共享或远程 dolt sql-serverBEADS_DOLT_SERVER_HOST、Hosted Dolt、VPS下多个主机是一个存储的客户端、彼此之间没有同步周期按主机名分配身份会让 supervisor 收割不到任何 worker 的租约容器里主机名是每次运行的容器 IDmacOS 的瞬态主机名跟随网络变化。这些都会在一个根本没有联邦的部署上把工作困死——比守卫要防止的失败更糟。所以未设置身份时行为降级为旧行为每个租约都视为本地而不是 fail-closed升级以及任何单存储部署永远不会困死收割者以前能恢复的租约。该特性落地前授予的租约同样不带副本标记会一直保持可收割状态直到某次 heartbeat 用已配置的 node 重新盖戳。解除守卫bd reclaim --any-replicabd reclaim --any-replica解除守卫。它适用于永久消失的副本或已被重命名、现在把自身旧租约视为外来的节点——这不是常规设置因为只有授予机器才对持有者是否存活有第一手视角。bd reclaim会把它拒绝的租约在 stderr 上一行总结配合bd -v可展开到前 20 条租约明细。heartbeat 证明存活但不移动租约普通 heartbeat 只在授予副本仍为空时回填它——不会覆盖一条明确命名了归属方的行。所以租约通常终身保留其授予副本以下状态会困死一条正被本地 heartbeat 维持的租约被重命名的副本mini→mini2持续 heartbeat 自己的租约而这些租约从此永远显示为外来通过 JSONL 互操作流入的外来租约其持有者名在本地也存在于是在这里被 heartbeat但仍带着远端节点标签导入落到一条已过期的本地租约行上时会连同授予副本一起整行采用快照——于是本节点自己的陈旧租约可能带着远端标签回归。唯一能让租约反向移动的路径是heartbeat 的持有者是租约行持有者的不同拼写——它会通过 upsert 重新武装盖上新节点戳。当确认授予副本不再收割后可用bd reclaim --any-replica恢复被困租约。确认授予副本不再收割正是该守卫的全部意义因此优先使用窄形式对单个 issue 用bd reclaim --any-replica --id id或bd unclaim --force id裸的全局形式会回退所有外来陈旧租约包括活着的 peer。bd reclaim会在 stderr 上点名它拒绝的内容——每次运行一条摘要bd -v展开到前 20 条租约明细。在 cmd/bd/reclaim.go 的帮助文本中上述两条不变式grace window sync interval且 lease TTL sync interval被明确标注为守卫无法替你强制执行的前提并再次强调bd reclaim --any-replica是override覆盖开关不是 scope作用域它会加宽处理集合越过每个副本的默认边界。计划中的功能以下操作已有基础设施支持但尚未以命令形式暴露bd federation push peer/bd federation pull peer—— 与单个 peer 的单向同步。bd federation sync已覆盖双向场景。故障排查requires direct database access联邦命令需要 Dolt 后端并提供直接数据库访问。请确保为联邦操作配置了 Dolt 后端proxied-server 模式下联邦子命令会直接返回不支持。peer already exists同名 peer 已存在。换一个名字或先用bd federation list-peers查看现有 peer。无效的 endpoint 格式确保 endpoint 匹配上文列出的某种受支持格式。scheme 必须是dolthub://、gs://、s3://、file://、https://、ssh://或 git SSH 格式githost:pathadd-peer还支持直连形式host:port/database。一般健康检查bd doctor --deep参考全部联邦配置项参见 Configuration 参考federation.remote、federation.sovereignty、federation.allowed-remote-patterns、federation.exclude_types及环境变量覆盖BD_FEDERATION_REMOTE/BD_FEDERATION_SOVEREIGNTY命令实现cmd/bd/federation.goadd-peer/remove-peer/list-peers/sync/status五个子命令含--peer、--strategy、--user/--password、--sovereignty、--json标志存储接口internal/storage/versioned.go版本化存储与Sync/SyncStatus/SyncResult与internal/storage/federation.goFederationStore接口Dolt 实现internal/storage/dolt/store.go、internal/storage/dolt/federation.goSync 完整流程、internal/storage/dolt/credentials.goAES-256 凭证加密与密钥迁移租约守卫cmd/bd/reclaim.go--any-replica、--older-than、--id与 stderr 报告语义桶联邦快速入门见 Bucket Federation Quickstartbd sync与bd federation sync的适用场景对比、退出码约定与实测成本。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
