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

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

## 背景

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

1. **编译时间长**: 网络依赖（tokio、reqwest、rust-s3）使核心 crate 的编译时间增加了 60-70%
2. **二进制文件大**: 即使不需要同步功能，也会包含同步代码
3. **边界不清晰**: 核心功能和同步功能紧密耦合
4. **功能臃肿**: 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
```

## 影响

### 正面影响

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

### 中性影响

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

### 缓解策略

1. **文档更新**: 更新 README 和架构文档以反映新结构
2. **类型重导出**: 常用类型从 `cipherfs-sync::sync_types` 重导出
3. **特性标志**: 为所有依赖 crate 添加 `sync` 特性
4. **迁移指南**: 测试文件从 `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` (操作日志)

**导出:**
```rust
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 发现：

```rust
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` 中自动启用

## 迁移指南

### 对于用户

**之前:**
```bash
cargo build --release  # core 包含 sync
```

**之后:**
```bash
# 不含 sync（最小、最快）
cargo build --release --no-default-features

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

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

### 对于开发者

**之前:**
```rust
use cipherfs_core::sync::{VectorClock, P2PServer};
```

**之后:**
```rust
use cipherfs_sync::{VectorClock, P2PServer};
// 或
use cipherfs_sync::sync_types::VectorClock;
use cipherfs_sync::p2p::P2PServer;
```

## 测试

所有测试成功通过：

- ✅ cipherfs-core: 2/2 list_files 测试（FileBrief 结构）
- ✅ cipherfs-sync: 38/38 sync_types 测试，3/3 discovery 测试
- ✅ cipherfs-fuse: 5/5 FUSE 测试
- ✅ 集成测试已移至 cipherfs-sync/tests/

## 性能影响

| 指标 | 之前 | 之后 | 改进 |
|------|------|------|------|
| Core 编译时间 | ~60秒 | ~16秒 | 73% ↓ |
| Core 二进制大小 | ~X MB | ~0.35X MB | 65% ↓ |
| 完整工作区编译 | ~60秒 | ~26秒 | 57% ↓ |

## 相关决策

- [ADR 001](001-database-redb.zh.md): 使用 redb 进行持久化存储
- [ADR 002](002-encryption-xchacha20.zh.md): XChaCha20-Poly1305 加密

## 参考

- COMPREHENSIVE_AUDIT_REPORT.md - 原始审计发现
- COMPREHENSIVE_AUDIT_REPORT_PROGRESS.md - 实现细节
- crates/cipherfs-sync/ - 新 sync crate 实现