架构决策记录: 同步模块分离

日期: 2026-01-14 状态: 已接受；模块清单已过时（2026-10-10：未使用的 mDNS 发现、带宽限制、块同步和 S3Sync 复制入口已删除；同步统一走 VaultSyncEngine + ObjectStore） 作者: CipherFS 团队

背景

在此次重构之前，cipherfs-core crate 同时包含核心存储/加密功能和同步（P2P、S3）代码。这导致了以下问题：

编译时间长: 网络依赖（tokio、reqwest、rust-s3）使核心 crate 的编译时间增加了 60-70%
二进制文件大: 即使不需要同步功能，也会包含同步代码
边界不清晰: 核心功能和同步功能紧密耦合
功能臃肿: Core crate 职责过多

决策

我们将同步功能分离到独立的 cipherfs-sync crate：

重构前

cipherfs-core (单体)
├── storage
├── crypto
├── version
├── sync (P2P, S3, mDNS)
└── vault

重构后

cipherfs-core (专注)
├── storage
├── crypto
├── version
└── vault

cipherfs-sync (独立)
├── discovery (mDNS)
├── p2p
├── s3
├── manager
└── bandwidth

影响

正面影响

编译速度: Core crate 编译时间 ~16秒（从 ~60秒）- 提升 73%
二进制大小: Core 二进制大小减少约 65%
职责分离: Core = 纯存储/加密，Sync = 网络操作
灵活的特性标志: 可以选择性排除同步功能: --no-default-features
依赖灵活性: 下游 crate 可以选择包含哪些功能

中性影响

更多 crate: 需要维护 2 个 crate 而不是 1 个（但职责更清晰）
导入路径变更: cipherfs_sync:: 替代 cipherfs_core::sync::

缓解策略

文档更新: 更新 README 和架构文档以反映新结构
类型重导出: 常用类型从 cipherfs-sync::sync_types 重导出
特性标志: 为所有依赖 crate 添加 sync 特性
迁移指南: 测试文件从 cipherfs-core/tests/ 移至 cipherfs-sync/tests/

实现细节

新 Crate: cipherfs-sync

位置: crates/cipherfs-sync/

依赖:

cipherfs-core (storage, crypto features)
tokio (异步运行时)
reqwest (HTTP 客户端)
rust-s3 (S3 客户端，可选)
mdns-sd (mDNS 发现)
redb (操作日志)

导出:

pub use discovery::Discovery;
pub use manager::{SyncConfig, SyncManager, SyncMode, SyncResult, SyncStatus};
pub use sync_types::{Conflict, ConflictType, ConflictResolution, VectorClock, ...};
pub use p2p::{P2PConfig, P2PServer, P2PClient};
pub use s3::{S3Config, S3Sync};

Core Crate 变更

移除:

所有 sync 相关模块（移至 cipherfs-sync）
网络依赖（tokio、reqwest、rust-s3 等）
sync 特性标志

更新:

Cargo.toml - 移除网络依赖
src/lib.rs - 移除 sync 模块导出
测试文件 - 移至 cipherfs-sync

新功能: mDNS 发现

文件: cipherfs-sync/src/discovery.rs

使用 mDNS/Bonjour 实现本地网络自动 peer 发现：

const SERVICE_TYPE: &str = "_cipherfs._tcp.local.";

pub struct Discovery {
    daemon: ServiceDaemon,
    peers: Arc<RwLock<HashSet<SocketAddr>>>,
    instance_name: String,
}

impl Discovery {
    pub fn new(instance_name: &str) -> Result<Self>;
    pub fn register(&self, port: u16) -> Result<()>;
    pub fn start_discovery(&self) -> Result<()>;
    pub fn get_peers(&self) -> Vec<SocketAddr>;
}

集成: 当 p2p_config.enable_discovery = true 时在 SyncManager 中自动启用

迁移指南

对于用户

之前:

cargo build --release  # core 包含 sync

之后:

# 不含 sync（最小、最快）
cargo build --release --no-default-features

# 含 sync（完整功能）
cargo build --release --features sync

# 指定功能
cargo build --release --features "sync,fuse"

对于开发者