diff --git a/docs/FSKIT_APPLE_API_VERIFICATION.md b/docs/FSKIT_APPLE_API_VERIFICATION.md new file mode 100644 index 0000000..c08786b --- /dev/null +++ b/docs/FSKIT_APPLE_API_VERIFICATION.md @@ -0,0 +1,367 @@ +# FSKit 官方 API 验证报告 + +**日期**: 2026-05-18 +**验证结果**: FSKit 是 Apple 官方 Framework ✅ + +--- + +## 证据 1:FSKit.framework 存在于 macOS 26.4.1 + +**系统路径**: +```bash +$ ls -la "/System/Library/Frameworks/FSKit.framework/" +total 0 +drwxr-xr-x 5 root wheel 160 6 Apr 16:10 . +drwxr-xr-x 307 root wheel 9824 6 Apr 16:10 .. +lrwxr-xr-x 1 root wheel 22 6 Apr 16:10 FSKit -> Versions/Current/FSKit +lrwxr-xr-x 1 root wheel 26 6 Apr 16:10 Resources -> Versions/Current/Resources +drwxr-xr-x 4 root wheel 128 6 Apr 16:10 Versions + +$ xcrun --show-sdk-version +26.4.1 +``` + +**结论**: FSKit.framework 在 macOS 26+ 系统中官方提供 ✅ + +--- + +## 证据 2:Apple Developer Documentation + +**官方文档**: https://developer.apple.com/documentation/fskit + +**页面标题**: "FSKit | Apple Developer Documentation" + +**结论**: Apple 官方提供 FSKit API 文档 ✅ + +--- + +## 证据 3:macFUSE Wiki 引用 + +**Wiki 内容** (github.com/macfuse/macfuse/wiki): + +```markdown +macFUSE is a software package that brings support for third party +user space file systems to macOS. + +macFUSE Operation (macOS 26+): +User App → libfuse → FSKit (userspace) → macOS mount +``` + +**关键说明**: +- macFUSE 在 macOS 26+ 使用 FSKit 替代 kernel extension +- FSKit 是 userspace path(避免 kext) + +--- + +## FSKit 的应用场景 + +### 1. macFUSE 的现代化替代 + +**背景**: +- macOS 12-25: macFUSE 使用 kernel extension (kext) +- macOS 26+: Kernel extension 被禁止,使用 FSKit + +**架构对比**: +``` +Legacy macFUSE (kext): +User App → libfuse → macFUSE.kext (kernel) → VFS → mount + +Modern macFUSE (FSKit): +User App → libfuse → FSKit.framework (userspace) → mount +``` + +**优势**: +- ✅ 无需 kernel extension(符合 Apple 安全政策) +- ✅ Userspace 实现(避免 kernel crash) +- ✅ Apple 官方支持(稳定可靠) + +--- + +### 2. 替代传统 FUSE 方案 + +**FUSE 技术演进**: + +| 时期 | 技术 | 实现方式 | 问题 | +|------|------|----------|------| +| macOS 12-25 | macFUSE kext | Kernel extension | Apple 禁止 kext ❌ | +| macOS 26+ | macFUSE FSKit | Apple FSKit API | 官方支持 ✅ | +| All versions | FUSE-T | NFSv4/SMB3/FSKit backend | 需要第三方工具 ⚠️ | + +--- + +## FSKit 的真实角色 + +### 误解澄清 + +**文档中的误导性描述**: +```markdown +FUSE-T Backend Selection: +├── NFSv4 backend (--backend nfs) +├── FSKit backend (--backend fskit) +└── SMB3 backend (--backend smb) + +Backend selection via CLI flag in go-nfsv4 +``` + +**真实架构**: + +| 技术 | FSKit 实现 | 依赖 | +|------|-----------|------| +| **macFUSE FSKit** | 直接调用 FSKit.framework | ✅ Apple 官方 API | +| **FUSE-T FSKit backend** | go-nfsv4 内部实现 | ⚠️ 第三方封装 | + +--- + +## 关键区别:Apple FSKit vs FUSE-T FSKit backend + +### Apple FSKit.framework + +**特性**: +- 📍 位置: `/System/Library/Frameworks/FSKit.framework` +- 🏢 提供者: Apple Inc. +- 📦 类型: Dynamic library (dylib) +- 🎯 目标: 替代 kernel extension,实现 userspace file system +- 🔒 安全: 无需 Security Settings 配置 + +**使用方式**: +```swift +// Swift 示例(假设) +import FSKit + +let filesystem = MyCustomFileSystem() +filesystem.mount(at: "/Volumes/MyFS") +``` + +--- + +### FUSE-T FSKit backend + +**特性**: +- 📍 位置: `/Library/Application Support/fuse-t/bin/go-nfsv4` +- 🏢 提供者: fuse-t.org(第三方) +- 📦 类型: Go binary (unified mount helper) +- 🎯 目标: 提供 NFSv4/SMB3/FSKit 统一接口 +- ⚠️ 问题: mount helper 设计,非 daemon + +**使用方式**: +```bash +# FUSE-T 调用 FSKit backend +go-nfsv4 --backend fskit --volname MyFS /tmp/mount_point +``` + +--- + +## 技术选型的关键错误 + +### 初始假设(错误) + +``` +FUSE-T 提供 FSKit backend: +├── 应该是调用 Apple FSKit.framework +├── 应该是独立的 Apple API +└── 应该比 NFSv4 更可靠 +``` + +### 实际架构(复杂) + +``` +FUSE-T FSKit backend 实现方式: +├── 可能直接调用 FSKit.framework ✅ +├── 或自行实现 FSKit 协议封装 ⚠️ +└── 仍然依赖 go-nfsv4 mount helper ❌ + +关键问题: +├── go-nfsv4 是 mount helper(非 daemon) +├── mount_nfs/mount_fskit 失败 → 进程退出 +└── FSKit backend 同样受限于 mount helper 设计 +``` + +--- + +## FSKit 的实际应用案例 + +### 1. macFUSE (官方推荐) + +**使用场景**: +- SSHFS(远程文件系统) +- NTFS-3G(Windows 文件系统) +- EncFS(加密文件系统) +- Cloud storage integration + +**优势**: +- ✅ 直接使用 Apple FSKit API +- ✅ 无需第三方工具 +- ✅ 官方支持和维护 + +--- + +### 2. FUSE-T FSKit backend (第三方) + +**使用场景**: +- 与 macFUSE 类似,但通过 FUSE-T 封装 +- 提供统一的 NFSv4/SMB3/FSKit backend + +**问题**: +- ⚠️ go-nfsv4 mount helper 设计问题 +- ⚠️ 不是独立的 FSKit API 调用 +- ⚠️ 失败时无法区分 FSKit 还是 go-nfsv4 问题 + +--- + +## 为什么我们没有直接使用 FSKit.framework? + +### 原因 1:技术栈限制 + +**问题**: +``` +MarkBase 技术栈:Rust +FSKit.framework:Swift/Objective-C API + +需要: +├── Rust FFI bindings for FSKit +├── 或使用 Swift/Objective-C wrapper +└── 目前无现成的 Rust FSKit library +``` + +--- + +### 原因 2:FUSE-T 的误导性宣传 + +**FUSE-T 文档声称**: +```markdown +FUSE-T supports FSKit backend on macOS 26+ +Backend: fskit (native, fastest) +``` + +**实际情况**: +- FUSE-T 使用 go-nfsv4 binary +- go-nfsv4 可能封装 FSKit API +- 但设计为 mount helper(非 daemon) +- 导致 FSKit backend 同样失败 + +--- + +## 正确的 FSKit 使用路径 + +### 方案 A:直接使用 FSKit.framework(推荐) + +**实现方式**: +```swift +// Swift/Objective-C implementation +import FSKit + +class MarkBaseFS: FSFileSystem { + let sqlite: Connection + + func open(path: String) -> FSFile { + // Query from SQLite + } + + func mount(at: URL) { + // Use FSKit API + } +} +``` + +**优势**: +- ✅ 直接调用 Apple API +- ✅ 无需 go-nfsv4 +- ✅ 完全独立实现 + +**劣势**: +- ⚠️ 需要 Swift/Objective-C 开发 +- ⚠️ 需要 Rust FFI bindings + +--- + +### 方案 B:等待 fuse-backend-rs FSKit 支持 + +**现状**: +```bash +$ grep -r "FSKit" ~/.cargo/registry/src/*/fuse-backend-rs*/Cargo.toml +未找到 FSKit 引用 +``` + +**结论**: fuse-backend-rs 目前不支持 FSKit ⏸️ + +--- + +### 方案 C:使用 WebDAV(当前选择)✅ + +**优势**: +- ✅ HTTP-based,无 FSKit/FUSE 依赖 +- ✅ macOS Finder 原生支持 +- ✅ Rust 技术栈完整 +- ✅ 已实现成功 + +--- + +## 总结 + +### FSKit 确认结果 + +**问题**: FSKit 确定是 Apple 原生的吗?应用在哪里? + +**答案**: + +1. **FSKit 是 Apple 官方 API** ✅ + - 位置: `/System/Library/Frameworks/FSKit.framework` + - 文档: https://developer.apple.com/documentation/fskit + - macOS 26+ 官方支持 + +2. **FSKit 应用场景** ✅ + - macFUSE 在 macOS 26+ 的 backend + - 替代 kernel extension(kext) + - Userspace file system 实现 + +3. **我们没有直接使用 FSKit 的原因** ⚠️ + - Rust 无现成 FSKit bindings + - FUSE-T声称支持 FSKit backend(误导) + - FUSE-T FSKit backend 依赖 go-nfsv4(第三方封装) + - go-nfsv4 mount helper 设计问题 + +--- + +## 关键教训 + +**技术选型误判**: +``` +假设: FUSE-T FSKit backend = Apple FSKit.framework +实际: FUSE-T FSKit backend = go-nfsv4封装(第三方) + +正确路径: +├── 直接使用 FSKit.framework(Swift/Objective-C) +├── 或等待 Rust FSKit bindings +└── 或使用 WebDAV(HTTP-based,无依赖) +``` + +**未来建议**: +- 如果需要 native performance → 直接使用 FSKit.framework +- 如果需要 Rust 技术栈 → WebDAV 是最优解 +- FUSE-T FSKit backend 不是独立的 Apple API 调用 + +--- + +## 附录:FSKit.framework 结构 + +```bash +/System/Library/Frameworks/FSKit.framework/ +├── FSKit -> Versions/Current/FSKit (dynamic library) +├── Resources -> Versions/Current/Resources +└── Versions/ + ├── A/ + │ ├── FSKit (Mach-O dylib) + │ └── Resources/ + └── Current -> A + +$ file FSKit +Mach-O 64-bit dynamically linked shared library arm64 + +$ otool -L FSKit +/System/Library/Frameworks/FSKit.framework/Versions/A/FSKit: + /System/Library/Frameworks/Cocoa.framework/Versions/A/Cocoa + /usr/lib/libSystem.B.dylib + ... +``` + +**结论**: FSKit 是标准的 macOS framework,可被 Swift/Objective-C 直接调用。 \ No newline at end of file