# FSKit API 详细文档 ⭐⭐⭐⭐⭐ ## 1. FSKit Framework 结构 **Framework位置**：`/System/Library/Frameworks/FSKit.framework` **核心组件**： - UnaryFilesystemExtension - FSUnaryFileSystem - FSVolume - FSItem - FSBlockDevice --- ## 2. UnaryFilesystemExtension（入口点） **定义**：文件系统扩展入口点，相当于 kernel module init **Swift API**： ```swift import FSKit class UnaryFilesystemExtension { // 系统调用，启动文件系统 func start() -> Bool // 系统调用，停止文件系统 func stop() // 返回文件系统实现 func filesystem() -> FSUnaryFileSystem } ``` **生命周期**： ``` 1. 用户激活 Extension (System Settings) 2. macOS 调用 start() 3. 文件系统初始化 4. 返回 FSUnaryFileSystem 实例 5. macOS 调用 stop() (deactivate) ``` --- ## 3. FSUnaryFileSystem（文件系统） **定义**：文件系统核心类，管理卷和文件系统操作 **Swift API**： ```swift class FSUnaryFileSystem { // 文件系统名称 var name: String // 文件系统版本 var version: String // 初始化文件系统 func initialize() -> Bool // 清理文件系统 func cleanup() // 创建卷（相当于 dataset） func createVolume(name: String, device: FSBlockDevice?) -> FSVolume // 删除卷 func deleteVolume(volume: FSVolume) // 查询卷 func queryVolumes() -> [FSVolume] } ``` **协议 FSUnaryFileSystemOperations**： ```swift protocol FSUnaryFileSystemOperations { // 启动文件系统 func start() -> Bool // 停止文件系统 func stop() // 处理挂载请求 func handleMountRequest(request: FSMountRequest) -> FSVolume? // 处理卸载请求 func handleUnmountRequest(volume: FSVolume) } ``` --- ## 4. FSVolume（卷管理） **定义**：卷实例，相当于 ZFS dataset 或传统文件系统分区 **Swift API**： ```swift class FSVolume { // 卷名称 var name: String // 卷 ID var id: UUID // 所属文件系统 var filesystem: FSUnaryFileSystem // 卷状态 var state: FSVolumeState // 块设备（可选） var blockDevice: FSBlockDevice? // 根目录项 var rootItem: FSItem } ``` **协议 FSVolume.Operations**： ```swift protocol FSVolumeOperations { // 文件操作 func lookup(path: String) -> FSItem? func create(path: String, type: FSItemType) -> FSItem? func remove(item: FSItem) -> Bool func rename(item: FSItem, newPath: String) -> Bool // 读写操作 func read(item: FSItem, offset: Int, size: Int) -> Data? func write(item: FSItem, offset: Int, data: Data) -> Int // 目录操作 func readdir(directory: FSItem) -> [FSItem] func mkdir(path: String) -> FSItem? func rmdir(directory: FSItem) -> Bool // 属性操作 func getattr(item: FSItem) -> FSItemAttributes func setattr(item: FSItem, attributes: FSItemAttributes) -> Bool // 扩展属性 func getxattr(item: FSItem, name: String) -> Data? func setxattr(item: FSItem, name: String, value: Data) -> Bool func listxattr(item: FSItem) -> [String] func removexattr(item: FSItem, name: String) -> Bool // 锁定操作 func lock(item: FSItem, operation: FSLockOperation) -> Bool func unlock(item: FSItem) -> Bool // 符号链接和硬链接 func symlink(path: String, target: String) -> FSItem? func link(item: FSItem, newPath: String) -> FSItem? func readlink(item: FSItem) -> String? } ``` --- ## 5. FSItem（文件/目录项） **定义**：文件系统项（文件、目录、符号链接等） **Swift API**： ```swift class FSItem { // 项 ID var id: UUID // 项名称 var name: String // 项类型 var type: FSItemType // 所属卷 var volume: FSVolume // 父目录 var parent: FSItem? // 文件大小 var size: Int // 属性 var attributes: FSItemAttributes } enum FSItemType { case file // 文件 case directory // 目录 case symlink // 符号链接 case hardlink // 硬链接 case special // 特殊文件 } ``` --- ## 6. FSBlockDevice（块设备） **定义**：块设备访问接口，对 ZFS 极重要 **Swift API**： ```swift class FSBlockDevice { // 设备路径 var path: String // 设备大小 var size: Int // 设备 ID var id: UUID // 块大小 var blockSize: Int // 读取块 func readBlock(offset: Int, size: Int) -> Data? // 写入块 func writeBlock(offset: Int, data: Data) -> Bool // 刷新缓存 func flush() // 设备信息 func getInfo() -> FSBlockDeviceInfo } ``` **关键特性**： - ✅ **直接块设备访问**（pread/pwrite） - ✅ **设备路径**: /dev/disk18, /dev/disk19, etc - ✅ **支持多个设备**（RAID-Z, mirror） - ✅ **异步 I/O**（可选） - ✅ **Direct I/O**（可选） --- ## 7. FSItemAttributes（属性） **定义**：文件/目录属性 **Swift API**： ```swift struct FSItemAttributes { // 标准 POSIX 属性 var mode: Int // 权限模式 var uid: Int // 用户 ID var gid: Int // 组 ID var size: Int // 文件大小 var nlink: Int // 链接数 var atime: Date // 访问时间 var mtime: Date // 修改时间 var ctime: Date // 创建时间 var flags: Int // 标志位 // macOS 特定属性 var finderInfo: Data // Finder 信息 var extendedFlags: Int // 扩展标志 } ``` --- ## 8. FSMountRequest（挂载请求） **定义**：用户挂载请求处理 **Swift API**： ```swift class FSMountRequest { // 挂载路径 var mountPath: String // 设备路径 var devicePath: String? // 挂载选项 var options: FSMountOptions // 用户 ID var uid: Int // 进程 ID var pid: Int } struct FSMountOptions { var readOnly: Bool var noExec: Bool var noSuid: Bool var noDev: Bool var synchronous: Bool var noBrowse: Bool } ``` --- ## 9. FSKit 挂载流程 **完整流程**： ``` 1. 用户挂载命令: mount -F -t MyFS disk18 /mnt/test 2. macOS 处理: - 解析挂载参数 - 创建 FSMountRequest - 调用 FSUnaryFileSystemOperations.handleMountRequest() 3. 文件系统处理: - 解析 FSMountRequest - 访问块设备（disk18） - 创建 FSVolume 实例 - 返回 FSVolume 4. macOS 完成: - 注册 FSVolume - 创建挂载点 - 激活卷操作 5. 用户操作: - read/write/readdir 等操作 - macOS → FSVolume.Operations 6. 卸载: umount /mnt/test - macOS → FSUnaryFileSystemOperations.handleUnmountRequest() ``` --- ## 10. FSKit Extension 激活 **用户激活流程**： ``` 1. System Settings → General → Login Items & Extensions 2. 找到文件系统扩展（MyFS Extension） 3. 启用扩展 4. macOS 加载 Extension 5. 调用 UnaryFilesystemExtension.start() 6. Extension 返回 FSUnaryFileSystem 7. 文件系统可用 ``` **权限要求**： - 需要 root 或管理员权限激活 - Apple Developer 证书签名（生产） - 沙箱化运行（安全） --- ## 11. FSKit vs Kernel VFS 对比 | FSKit API | Kernel VFS | 功能 | |-----------|-----------|------| | UnaryFilesystemExtension | kernel module init | 入口点 | | FSUnaryFileSystem | filesystem type | 文件系统类型 | | FSVolume | superblock | 卷管理 | | FSVolume.Operations | file_operations | 文件操作 | | FSItem | dentry/inode | 文件项 | | FSBlockDevice | block_device | 块设备 | | FSItemAttributes | inode attributes | 属性 | --- ## 12. FSKit 限制和特性 **支持**： - ✅ 文件/目录操作 - ✅ 扩展属性（xattr） - ✅ 符号链接/硬链接 - ✅ 文件锁定 - ✅ 块设备访问 - ✅ 异步 I/O - ✅ Direct I/O - ✅ Unicode 文件名 - ✅ 大文件支持 **不支持**： - ❌ IOCTL（不通过 FSKit） - ❌ BMAP（不通过 FSKit） - ❌ 设备文件（字符/块设备） - ❌ 网络文件系统特性（某些） --- ## 13. FSKit 最佳实践 **1. 用户态设计**： - 所有代码运行在用户态 - 无 kernel code - 使用 Swift/C 用户态库 **2. 块设备访问**： - FSBlockDevice API - pread/pwrite 用户态 I/O - Direct I/O 优化性能 **3. 性能优化**： - 用户态缓存（类似 ARC） - 批量操作 - Async I/O **4. 安全考虑**： - Apple sandbox 模型 - 权限检查 - 用户态崩溃隔离 ---