markbase/docs/fskit-research/ZFS_MVP_DESIGN.md

ZFS MVP（最小可用版本）设计 ⭐⭐⭐⭐⭐

功能拆解策略

用户要求：不需要实现所有ZFS功能，先将ZFS拆解

MVP原则：最小功能集，验证可行性

---

ZFS功能拆解分析

Core Features（核心功能）

Level 1: 基础挂载 ⭐⭐⭐⭐⭐ (MVP)

• Pool import（导入现有pool）
• Dataset mount（挂载dataset）
• File read（读取文件）
• Directory listing（目录列举）
• 工作量：约200-300行

Level 2: 基础写入 ⭐⭐⭐⭐⭐

• File write（写入文件）
• File create（创建文件）
• Directory create（创建目录）
• 工作量：约100-150行

Level 3: 基础属性 ⭐⭐⭐⭐

• Get attributes（获取属性）
• Set attributes（设置属性）
• Extended attributes（xattr）
• 工作量：约100-150行

---

Advanced Features（高级功能）- 暂不实现

Level 4: Pool管理 ⭐⭐⭐⭐ (延后)

• Pool create（创建pool）
• Pool destroy（删除pool）
• Vdev management（设备管理）
• 工作量：约500+行

Level 5: Snapshot ⭐⭐⭐⭐ (延后)

• Snapshot create（创建快照）
• Snapshot rollback（回滚快照）
• Snapshot list（快照列表）
• 工作量：约300+行

Level 6: Compression ⭐⭐⭐⭐ (延后)

• Compression on/off
• Compression algorithm选择
• 工作量：约200+行

Level 7: Send/Receive ⭐⭐⭐⭐ (延后)

• ZFS send（发送流）
• ZFS receive（接收流）
• 工作量：约500+行

---

MVP必需FSKit Operations

必需实现（最小集）

FSVolume.Operations 必需方法（约10个）：

// Level 1: 基础挂载和读取
func activate(options: FSTaskOptions) async throws -> FSItem
func lookupItem(named: FSFileName, inDirectory: FSItem) async throws -> (FSItem, FSFileName)
func enumerateDirectory(...) async throws -> FSDirectoryVerifier

// Level 2: 基础写入
func createItem(named: FSFileName, type: FSItem.ItemType, ...) async throws -> (FSItem, FSFileName)
func removeItem(...) async throws

// Level 3: 属性
func attributes(_ item: FSItem) async throws -> FSItem.Attributes

// 必需辅助方法（约5个）
func deactivate(options: FSDeactivateOptions) async throws
func synchronize(flags: FSSynchronizeFlags) async throws
func reclaimItem(_ item: FSItem) async throws

可选延后（约8个）：

// 高级功能，MVP不实现
func readSymbolicLink(...) async throws -> FSFileName
func createSymbolicLink(...) async throws -> (FSItem, FSFileName)
func createLink(...) async throws -> FSFileName
func renameItem(...) async throws -> FSFileName
func getXattr(...) async throws -> Data
func setXattr(...) async throws
func listXattrs(...) async throws -> [String]
func removeXattr(...) async throws

---

MVP实现策略 ⭐⭐⭐⭐⭐

Phase 1: Level 1基础挂载（约200行）

核心功能：

• Pool import（读取现有ZFS pool metadata）
• Dataset mount（创建FSVolume）
• File read（通过libzfs user-space）
• Directory listing（列举dataset文件）

FSKit实现：

• activate: 返回root item
• lookupItem: 查找文件/目录
• enumerateDirectory: 列举目录内容
• attributes: 基础属性

预计工作量：约200行 Swift + 100行 C（libzfs wrapper）

---

Phase 2: Level 2基础写入（约100行）

核心功能：

• File write（写入数据）
• File create（创建新文件）
• Directory create（创建目录）

FSKit实现：

• createItem: 创建文件/目录
• removeItem: 删除文件/目录
• OpenClose + IO operations

预计工作量：约100行 Swift

---

Phase 3: Level 3基础属性（约100行）

核心功能：

• Get/set attributes
• Extended attributes（ZFS properties）

FSKit实现：

• attributes: 完整属性
• XattrOperations（可选）

预计工作量：约100行 Swift

---

MVP总工作量评估 ⭐⭐⭐⭐⭐

重新评估：

方面	MVP工作量	评估
FSKit Volume	约400-500行	⭐⭐⭐⭐ 大幅降低
libzfs wrapper	约200行	⭐⭐⭐⭐
测试和文档	约100行	⭐⭐⭐⭐
总工作量	约700-800行	⭐⭐⭐⭐⭐
开发时间	约2-3 weeks	⭐⭐⭐⭐⭐

对比：

• 完整ZFS：15-20 months → MVP：2-3 weeks
• 从 ⭐⭐⭐ → ⭐⭐⭐⭐⭐

---

MVP架构设计 ⭐⭐⭐⭐⭐

ZFS MVP (Level 1-3)
│
├── FSKit Layer (Swift)
│   ├── HelloFS (FSUnaryFileSystem)
│   │   ├── probeResource (接受ZFS pool)
│   │   ├── loadResource (加载dataset)
│   │   └── unloadResource
│   │
│   ├── ZFSVolume (FSVolume + 必需protocols)
│   │   ├── activate (返回root)
│   │   ├── lookupItem (查找文件)
│   │   ├── enumerateDirectory (列举目录)
│   │   ├── createItem (创建文件)
│   │   ├── removeItem (删除文件)
│   │   ├── attributes (获取属性)
│   │   └── deactivate
│   │
│   └── ZFSItem (FSItem)
│       ├── name, id, attributes
│       └── content (Data)
│
├── libzfs Wrapper (C + Swift FFI)
│   ├── zpool_import (导入pool)
│   ├── zfs_open (打开dataset)
│   ├── zfs_read (读取数据)
│   ├── zfs_write (写入数据)
│   └── zfs_list (列举文件)
│
└── ZFS User-Space Core (C)
    ├── SPA (Storage Pool Allocator)
    ├── DMU (Data Management Unit)
    ├── DSL (Dataset Layer)
    └── ZPL (ZFS POSIX Layer)

---

MVP优先级 ⭐⭐⭐⭐⭐

立即实现（Level 1）：

1. ✅ Pool import（读取现有pool）
2. ✅ Dataset mount（创建FSVolume）
3. ✅ File read（读取文件）
4. ✅ Directory listing

次要实现（Level 2）： 5. ⏸️ File write 6. ⏸️ File create/delete

延后实现（Level 3+）： 7. ⏸️ Advanced attributes 8. ⏸️ Snapshot operations 9. ⏸️ Compression 10. ⏸️ Send/receive

---

MVP验证目标 ⭐⭐⭐⭐⭐

验证目标：

• ✅ 能导入现有ZFS pool
• ✅ 能挂载ZFS dataset
• ✅ 能读取ZFS文件
• ✅ 能列举ZFS目录
• ✅ 基础功能可用

不验证（延后）：

• ❌ Pool创建
• ❌ Snapshot操作
• ❌ 高级压缩
• ❌ Send/receive

---

MVP vs 完整ZFS对比

功能	MVP	完整ZFS	差距
Pool管理	Import only	Create/Destroy/Vdev	90%减少
Dataset	Mount only	Create/Destroy/Snapshot	80%减少
File Ops	Read/Write/Create	Full POSIX	50%减少
Attributes	Basic	Full + xattr	60%减少
Snapshot	❌ None	✅ Full	100%减少
Compression	❌ None	✅ lz4/zstd	100%减少
Send/Receive	❌ None	✅ Full	100%减少
工作量	700行	135,000行	99%减少
时间	2-3 weeks	15-20 months	95%减少

---