Spacedrive 无领导Leaderless库同步协议设计解析从架构决策到 HLC 与混合同步实现【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrive本文基于仓库任务文档 LSYNC-001-design-library-sync-protocol.md 展开。该文档记录了 Spacedrive 库同步Library Sync协议的完整设计过程从早期的领导者/跟随者模型演进为基于数据所有权分析的无领导对等leaderless peer-to-peer混合模型。读者读完本文后将掌握无领导同步的架构动机与决策要点、设备自有数据state-based与共享资源HLC log-based两类数据的同步策略差异、以及 HLC 时钟、PeerLog、批量传输等核心组件在 core/src/infra/sync 中的实际实现。背景为什么需要重新设计同步协议Spacedrive 是一个用 Rust 编写的跨平台文件管理器其核心是一个虚拟分布式文件系统VDFS。库Library是 Spacedrive 中的元数据聚合单元包含位置、文件条目、标签、相册等数据。为了让用户的多个设备桌面、移动端、服务器看到一致的库视图需要一套元数据同步机制。原始设计采用领导者模型leader-based model由一台设备充当 leader为所有变更分配全局序列号sequence numberfollower 设备的所有写入都必须经过 leader。这种模型存在三个致命问题单点瓶颈所有设备的每次写入都要经过 leaderleader 成为性能与可用性的单点离线不可用leader 离线时其他设备无法提交任何变更复杂度高需要实现选举election、心跳heartbeat等协调机制。2025 年 10 月的架构更新中设计团队基于数据所有权分析data ownership analysis得出了一个关键洞察设备所有权消除了约 90% 的冲突——位置、文件条目、卷等数据天然由某台设备拥有即该设备是这些数据的权威来源只有标签、相册这类会被多台设备共同编辑的共享资源才真正需要有序日志。因此设计从 leader-based 转向 peer-to-peer见 LSYNC-001 与父任务 LSYNC-000-library-sync.md。新协议的架构决策修订后的架构决策Architecture Decisions如下无领导对等不进行 leader 选举所有设备地位平等混合同步策略Hybrid设备自有数据locations、entries 等采用**基于状态state-based**同步共享资源tags、albums 等采用基于日志log-based HLC同步批量优化以批量状态传输batched state transfer提升效率冲突解决HLC 排序 并集合并union merge无中央协调器每台设备直接向对等设备广播变更。新旧设计对比原任务文档给出了一张清晰的对比表这是理解本次重构的核心AspectOld DesignNew DesignArchitectureLeader/followerPeer-to-peerOrderingCentral sequencesHLC timestampsSync logOne central logPer-device for shared changes onlyDevice-owned dataGoes through leaderDirect state broadcastComplexityHigh (election, heartbeats)Low (simpler)其中两个最显著的变化排序机制从中央序列号改为HLC 时间戳。中央序列需要 leader 在线而 HLC 由每台设备独立生成天然支持离线操作同步日志从一条中央日志改为每设备一条、只记录共享变更的小日志。设备自有数据的变更直接广播状态不再进入日志。从实现角度看这一改动让整个同步系统减少了约 800 行代码见 LSYNC-000并取消了sync_leadership字段、LeadershipManager结构体与所有is_leader()检查见 LSYNC-009 的迁移清单。两类数据的同步策略设备自有数据基于状态的直接广播设备自有数据包括Locations、Entries、Volumes、Devices四类模型。它们的特征是每条记录都有一个明确的属主设备属主是权威来源。同步方式为属主设备将自身的状态变化直接广播给所有对等设备对端直接应用。由于只有属主会修改这些数据不存在并发写冲突因此不需要日志和全局排序只需基于时间戳timestamp-based的增量同步即可。这种方式效率最高成本也最低。共享资源基于日志 HLC共享资源包括Tags、Collections、ContentIdentity、UserMetadata四类模型。它们的特征是任何设备都可能修改同一条记录例如两台设备同时编辑同一个标签因此需要全局一致的排序来确定谁先谁后。同步方式为每台设备维护一条自己的shared_changes日志将自己的共享资源变更按 HLC 顺序写入广播时携带 HLC 时间戳用于排序对端确认ACK后本地即可激进地修剪prune日志条目保证日志始终保持在极小规模。这套广播 → ACK → 修剪的机制在源码 peer_log.rs 中有完整实现每台设备每个库维护一个独立的sync.db位于库目录下其中shared_changes表以 HLC 为主键// core/src/infra/sync/peer_log.rs CREATE TABLE IF NOT EXISTS shared_changes ( hlc TEXT PRIMARY KEY, model_type TEXT NOT NULL, record_uuid TEXT NOT NULL, change_type TEXT NOT NULL, data TEXT NOT NULL, created_at TEXT NOT NULL )该表只存储本设备对共享资源的变更一旦所有对等设备 ACK即可删除对应条目因此每个设备的sync.db始终很小。8 个模型的同步归属总览从 LSYNC-000 的实现总结可以看到完整清单4 个设备自有模型state-basedDevice、Location、Entry、Volume4 个共享模型HLC log-basedTag、Collection、ContentIdentity、UserMetadata。其中 ContentIdentity 采用确定性 UUIDdeterministic UUID生成相同的文件内容会在不同设备上产生相同的 UUID从而实现天然的跨设备去重。HLC无领导环境下的全局排序基石为什么需要 HLC无领导模型下没有中央序列号但共享资源的冲突解决仍然需要全局可比较的排序。HLCHybrid Logical Clock混合逻辑时钟是这一问题的标准解法其论文出处为 Kulkarni 等人的Logical Physical Clocks and Consistent Snapshots同类实现可参考 CockroachDB、TiDB见 LSYNC-009。HLC 的关键性质全序Total ordering任意两个 HLC 都可比较因果追踪Causality tracking若事件 A 因果先于 B则HLC(A) HLC(B)分布式生成Distributed generation每台设备独立生成无需协调紧凑共 16 字节timestamp counter device_id携带与存储成本极低。HLC 的源码实现HLC结构体定义在 hlc.rs// core/src/infra/sync/hlc.rs pub struct HLC { /// Physical time component (milliseconds since Unix epoch) pub timestamp: u64, /// Logical counter for events within the same millisecond pub counter: u64, /// Device that generated this HLC (for deterministic ordering) pub device_id: Uuid, }三个字段各司其职timestamp物理时间自 Unix 纪元起的毫秒数提供与真实时间的近似对齐counter同一毫秒内事件的逻辑计数器解决同毫秒并发device_id生成该时钟的设备 ID用于确定性打破平局——即使两个设备恰好在同一毫秒产生相同计数器值device_id 也能给出确定的比较结果从而保证全序。生成与更新的核心逻辑如下/// Generate next HLC based on previous HLC pub fn generate(last: OptionHLC, device_id: Uuid, time_source: dyn TimeSource) - Self { let now time_source.current_time_ms(); match last { Some(last) if last.timestamp now { // Same millisecond, increment counter Self { timestamp: now, counter: last.counter 1, device_id } } _ { // New millisecond or no previous HLC Self { timestamp: now, counter: 0, device_id } } } } /// Update this HLC based on received HLC (causality tracking) pub fn update(mut self, received: HLC, time_source: dyn TimeSource) { let now time_source.current_time_ms(); // Take max of all three: local, received, and physical time let max_timestamp self.timestamp.max(received.timestamp).max(now); // ... }注意两个细节generate在同毫秒时递增 counter否则重置为 0——这是 HLC 保持全序的基础update在收到对端 HLC 时取local、received、物理时间三者的最大值实现因果追踪一旦收到未来的时间戳本地时钟立即追赶确保后续生成的事件在因果上晚于已接收事件。这正是 HLC 与纯 Lamport 时钟的区别——物理时间参与其中使时钟值更贴近真实时间同时逻辑部分保证排序正确性。时间源通过TimeSourcetrait 抽象time_source.rs生产环境使用SystemTimeSource测试环境使用FakeTimeSource使得 HLC 的行为可以在测试中精确控制。HLC 的四个集成点LSYNC-009 明确了 HLC 在同步系统中的接入位置SharedChangesDbshared_changes表用 HLC 取代序列号存储对应 peer_log.rs 中以 HLC 为主键的表结构TransactionManager为共享变更生成 HLC不再有 leader 检查SyncProtocolHandler在SharedChange消息中携带 HLC冲突解决按 HLC 排序确定应用顺序后写者胜LWW。冲突解决采用HLC 排序 LWWLast-Write-Wins后写者胜对同一记录的多个并发变更按 HLC 排序后HLC 最大的那个即最后写入者胜出。HLC 的 device_id 字段保证即使时间戳与计数器完全相同时也有确定性的胜负判定避免不同设备对同一记录的最终状态产生分歧。传输抽象同步层与网络层的解耦无领导模型要求每台设备直接向所有对等设备广播。为了让同步层不依赖具体网络实现Iroh P2P 栈transport.rs 定义了NetworkTransporttrait// core/src/infra/sync/transport.rs #[async_trait::async_trait] pub trait NetworkTransport: Send Sync { async fn send_sync_message(self, target_device: Uuid, message: SyncMessage) - Result(); }该 trait 的设计要点打破循环依赖依赖关系为Library → SyncService → NetworkTransport ← NetworkingService同步层只依赖 trait网络层实现 trait两边互不反向依赖设备 UUID → NodeId 映射实现者NetworkingService通过DeviceRegistry将目标设备的 UUID 映射为网络层 NodeId再经 Iroh endpoint 发送endpoint.send_message(node_id, sync, bytes)优雅降级设备可能随时离线发送失败时应记录警告而不是让整个广播失败——这正体现了无领导模型尽力而为广播的设计哲学。从注释中的示例可以看到 PeerSync 的广播模式先获取所有同步伙伴sync partners然后遍历调用send_sync_messageNetworkTransport内部完成 UUID→NodeId 映射与序列化。批量优化与统一配置三种批量场景无领导模型下为了在网络传输中提升效率config.rs 将同步消息分为三种批量粒度配置项默认值用途backfill_batch_size10,000回填请求StateRequest / SharedChangeRequest每次拉取的记录数state_broadcast_batch_size1,000设备自有数据的 StateBatch 广播shared_broadcast_batch_size100共享资源 SharedChangeBatch 广播max_snapshot_size100,000SharedChangeResponse 当前状态快照上限realtime_batch_max_entries100实时事件监听器的批内最大条目数realtime_batch_flush_interval_ms50实时事件批量刷新的时间间隔毫秒批量不仅减少网络往返次数也让广播 → ACK → 修剪的日志维护按批进行进一步控制sync.db的体积。三种内置配置模板SyncConfig提供了三套开箱即用的配置模板config.rs覆盖典型部署场景aggressive()面向快速局域网与常在线设备。同步间隔 2 秒、消息超时 15 秒、回填批 5,000、日志保留 3 天、PruningStrategy::AcknowledgmentBased收到 ACK 即修剪conservative()面向不稳定网络与频繁离线设备。同步间隔 10 秒、消息超时 60 秒、回填批 25,000、日志保留 30 天、PruningStrategy::Conservative { min_retention_days: 7 }保留至少 7 天mobile()面向移动设备以电池与带宽为先。同步间隔 30 秒、PruningStrategy::TimeBased { retention_days: 14 }、关闭指标采集enable_metrics: false。三套模板在 retention保留策略、network网络时序、monitoring监控三个维度上分别取不同的权衡值统一通过SyncConfig管理这正是 LSYNC-021-unified-sync-config 中统一同步配置思路的落地。消息与协议流程基于 mod.rs 的模块布局transport、peer_log、hlc、watermarks、checkpoints、event_log等可以勾勒出无领导同步的典型工作流设备自有数据状态广播属主设备上的写入操作完成如索引器发现了新条目变更被批量封装为StateBatchstate_broadcast_batch_size条/批通过NetworkTransport广播给所有启用了同步的对等设备对端按记录 UUID 直接应用幂等天然无冲突。共享资源日志广播TransactionManager 为共享变更生成 HLC变更写入本设备sync.db的shared_changes表批量封装为SharedChangeBatchshared_broadcast_batch_size条/批并携带 HLC 广播对端按 HLC 排序后应用冲突时 LWW 决出胜者对端 ACK 后本设备修剪已确认的日志条目日志保持极小。新设备加入回填 backfill新设备通过StateRequest/SharedChangeRequest批量拉取存量数据backfill_batch_size条/批配合watermarks水位线实现增量断点续传checkpoints用于回填的可恢复性。这些机制在 LSYNC-012-entry-sync-bulk-optimization 与 LSYNC-023-rebuild-closure-tables-on-sync 等子任务中有更细化的设计。验收标准与落地状态LSYNC-001 的验收标准全部勾选完成创建了详细的协议设计文档定义了混合策略state log明确了 HLC 排序机制设计了对等广播协议更新了实现任务清单。从 LSYNC-000 可以看到后续落地进度Phase 1Iroh P2P 栈、设备配对、同步设置、Phase 2TransactionManager、Syncable trait、HLC 实现、混合协议处理器与 Phase 3对等同步服务、冲突解决、元数据同步、8 个模型实现均已完成配套基础设施包括 Syncable trait 与 FK 映射、PeerLog、HLC、冲突解决LWW、动态派发注册表以及 10 个通过的集成测试。剩余的 Phase 4 工作聚焦于 8 个模型的增强集成测试、新设备加入时的回填优化、失败同步的重试队列以及性能监控。相关文档导航若要深入该主题建议按以下顺序阅读仓库中的关联材料父任务总览LSYNC-000-library-sync.md —— 混合模型完整动机与各阶段状态HLC 实现任务LSYNC-009-hlc-implementation.md —— 时钟原理与迁移清单同步服务与冲突解决LSYNC-010、LSYNC-011同位于 .tasks/core 目录核心源码目录core/src/infra/sync —— 包含 hlc.rs、peer_log.rs、transport.rs、config.rs 等全部实现正式文档docs/core/library-sync.mdx 与 docs/core/sync-event-log.mdx网络与配对基础NET-001Iroh P2P 栈、NET-002设备配对任务文档以及 docs/core/networking.mdx、docs/core/pairing.mdx。小结Spacedrive 的库同步协议设计LSYNC-001展示了一次典型的分布式系统架构收敛通过数据所有权分析发现大部分数据不存在并发写冲突从而把全局有序的中央日志降级为设备自有数据直传 共享资源按需排序的混合模型。HLC 以 16 字节的成本提供了无领导环境下的全序与因果追踪PeerLog 通过 ACK 修剪保持日志极小批量配置与三套模板则让同步行为可以针对 LAN、弱网、移动设备分别调优。这套设计在消除 leader 瓶颈的同时实现了完全离线可用并显著降低了系统复杂度——从源码结构与任务状态来看它已在仓库中完整落地并通过了集成测试验证。【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrive创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考