markbase/docs/FSKIT_APPLE_API_VERIFICATION.md

FSKit 官方 API 验证报告

日期: 2026-05-18
验证结果: FSKit 是 Apple 官方 Framework ✅

---

证据 1：FSKit.framework 存在于 macOS 26.4.1

系统路径:

$ 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):

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 的真实角色

误解澄清

文档中的误导性描述:

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 示例（假设）
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

使用方式:

# 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 文档声称:

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/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 支持

现状:

$ 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 结构

/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 直接调用。