admin/markbase
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
1300a4e22318a3f761836ebe831d5a1e40693149
markbase/docs/FSKit_INSTALLATION_RESEARCH.md
Warren 1300a4e223
Some checks failed
Test / test (push) Has been cancelled
Details
Test / build (push) Has been cancelled
Details
MarkBase架构升级：Multi-Volume Virtual Tree + Dual-View Management + Git Remote修正 
核心功能：
- ✅ Categories/Series双视图管理（category_view.rs + import_markdown.rs）
- ✅ FUSE Multi-Volume支持（tree_type参数）
- ✅ SSH/SFTP/SCP/rsync协议完整实现（4042行）
- ✅ NFS/SMB Module Phase 1-3完成
- ✅ Archive Module Phase 1-4完成（2916行）
- ✅ Download Center API完整实现
- ✅ S3兼容API实现（560行）

Git配置修正：
- ✅ 删除错误origin（gitea.momentry.ddns.net）
- ✅ 删除m5max128（指向机器名）
- ✅ 设置origin = m5max128gitea.momentry.ddns.net/admin/markbase
- ✅ 设置m4minigitea = m4minigitea.momentry.ddns.net/warren/markbase

数据清理：
- ✅ 删除38个临时SQLite（保留accusys.sqlite、demo.sqlite）
- ✅ 删除.bak、test_*.bin、调试脚本等临时文件
- ✅ 删除临时目录（build/、download files/、raid_test/等）
- ✅ 更新.gitignore排除临时文件

架构优化：
- 52个文件修改，2434行新增，4739行删除
- Workspace成员整合（16个crate）
- 数据库状态：accusys.sqlite保留（主demo测试）

远程同步：
- ✅ 准备推送到m5max128gitea（远程Gitea）
- ✅ 准备推送到m4minigitea（本地Gitea）
2026-06-12 12:59:54 +08:00

450 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# FSKit Module Installation Research Report
## Research Date: 2026-05-28
## Researcher: MarkBase Team
---
## 1. Apple Official Documentation
### 1.1 FSKit API Documentation
**Status**: ✅ Partially Available
**Sources**:
- **FSKit Framework**: macOS 15+ (Sequoia) introduction
- **fskitd man page**: Available via `man fskitd`
- **Apple Developer Documentation**: https://developer.apple.com/documentation/fskit (requires JavaScript)
**Key Documentation**:
#### fskitd Man Page
```
NAME
fskitd – FSKit mount manager and mount support
DESCRIPTION
fskitd is the FSKit mount management and mount support daemon. It manages
the FSKit mount life cycle and coordinating with other daemons. It also
translates requests from the kernel LIFS file system to the user space
file system servers backing volumes.
fskitd is invoked by launchd(8) when volume creation is requested
or when previously-created volumes are detected.
FILES
/System/Library/LaunchAgents/com.apple.fskitd.plist
```
### 1.2 ExtensionKit Installation Guides
**Status**: ❌ Limited Public Documentation
**Key Findings**:
- ExtensionKit is the underlying framework for FSKit Modules
- FSKit Modules are **App Extensions** (`.appex`)
- Extension Point: `com.apple.fskit.fsmodule`
### 1.3 App Extension vs System Extension Differences
| Feature | App Extension | System Extension |
|---------|---------------|------------------|
| **Location** | `/System/Library/ExtensionKit/Extensions/` (Apple) <br> `/Library/Filesystems/` (Third-party) | `/Library/SystemExtensions/` |
| **Installation** | Automatic discovery | Requires user approval via System Preferences |
| **API** | ExtensionKit | System Extension API |
| **Restart Required** | ❌ No | ❌ No (but may require logout) |
| **Entitlements** | `com.apple.developer.fskit.fsmodule` | `com.apple.system-extension` |
| **Sandbox** | ✅ Required | ✅ Required |
| **User Approval** | ❌ Not required (for local filesystems) | ✅ Required |
**Critical Finding**: FSKit Modules are **App Extensions**, NOT System Extensions!
---
## 2. Third-Party Implementations
### 2.1 rclone FSKit Implementation
**Status**: ❌ Not Implemented
**Evidence**:
- rclone documentation shows FUSE mount support
- No FSKit-specific documentation found
- rclone uses macFUSE/FUSE-T, not native FSKit
**Conclusion**: rclone does not have FSKit Module implementation.
### 2.2 Google Drive FSKit Implementation
**Status**: ❌ Not Publicly Available
**Evidence**:
- Google Drive File Stream uses kernel extensions (deprecated)
- No FSKit Module implementation found
- Likely waiting for broader macOS adoption
### 2.3 Other Third-Party FSKit Modules
**Status**: ❌ None Found
**Search Results**:
- GitHub search: "FSKit module macOS" → 0 repositories
- GitHub search: "fskit fsmodule" → No public code
- Stack Overflow: No FSKit tag
**Conclusion**: MarkBaseFS is **one of the first third-party FSKit Modules** publicly documented.
---
## 3. Installation Mechanism
### 3.1 How macOS Discover FSKit Modules?
**Discovery Mechanism**:
1. **ExtensionKit Framework**:
- ExtensionKit daemon scans `/System/Library/ExtensionKit/Extensions/`
- FSKit Modules are discovered by `EXExtensionPointIdentifier` = `com.apple.fskit.fsmodule`
2. **Local Filesystems**:
- `/Library/Filesystems/` is scanned by fskitd
- `.appex` bundles with correct Info.plist are registered
3. **Discovery Process**:
```
fskitd (daemon) → ExtensionKit → .appex bundles → Info.plist → EXExtensionPointIdentifier
```
### 3.2 Does FSKit Daemon Automatically Discover New Modules?
**Answer**: ✅ YES (for `/Library/Filesystems/`)
**Evidence**:
- fskitd man page: "invoked by launchd when volume creation is requested"
- MarkBaseFS Module at `/Library/Filesystems/MarkBaseFS FSKit Module.appex` was discovered
- No manual registration required
**Process**:
1. Copy `.appex` to `/Library/Filesystems/`
2. fskitd automatically discovers it
3. Module becomes available for mounting
### 3.3 Does it Require macOS Restart?
**Answer**: ❌ NO
**Evidence**:
- fskitd is launched by launchd on demand
- fskit_agent is running as Background/Aqua session type
- ExtensionKit framework supports dynamic discovery
- Test: MarkBaseFS Module was discovered without restart
**Launchd Services Running**:
```
PID: 99535 - /usr/libexec/fskitd
Launch Agent: com.apple.fskit.fskit_agent (PID: -9, background)
```
---
## 4. System Extension API
### 4.1 Is System Extension API Applicable to FSKit Modules?
**Answer**: ❌ NO
**Reason**:
- FSKit Modules are **App Extensions**, not System Extensions
- System Extension API is for:
- DriverKit drivers
- Network Extensions
- Endpoint Security
**Evidence**:
- MarkBaseFS Module Info.plist: `CFBundlePackageType = XPC!` (App Extension)
- Apple FSKit Modules: Same `XPC!` package type
- Extension Point: `com.apple.fskit.fsmodule` (App Extension point)
### 4.2 System Extension API Use Cases
| Type | Extension Point | API |
|------|----------------|-----|
| **DriverKit** | `com.apple.driverkit` | System Extension API |
| **Network Extension** | `com.apple.network-extension` | System Extension API |
| **Endpoint Security** | `com.apple.endpoint-security` | System Extension API |
| **FSKit Module** | `com.apple.fskit.fsmodule` | ExtensionKit API |
---
## 5. Correct Installation Location
### 5.1 Apple FSKit Modules Location
**Location**: `/System/Library/ExtensionKit/Extensions/`
**Examples**:
```
/System/Library/ExtensionKit/Extensions/
├── com.apple.fskit.exfat.appex
├── com.apple.fskit.ftp.appex
├── com.apple.fskit.msdos.appex
└── FSKitModuleManagement.appex
```
### 5.2 Third-Party FSKit Modules Location
**Primary Location**: `/Library/Filesystems/`
**Evidence**:
- MarkBaseFS Module currently at `/Library/Filesystems/MarkBaseFS FSKit Module.appex`
- Historical precedent: NetFSPlugins at `/Library/Filesystems/NetFSPlugins/`
- This location is scanned by fskitd
**Alternative Locations** (NOT recommended):
- ❌ `/System/Library/ExtensionKit/Extensions/` → Reserved for Apple
- ❌ `/Library/Application Support/com.apple.fskit/` → Does not exist
- ❌ `/Library/SystemExtensions/` → Reserved for System Extensions
### 5.3 Location Comparison
| Type | Location | Discovery | Permission Required |
|------|----------|-----------|---------------------|
| **Apple Modules** | `/System/Library/ExtensionKit/Extensions/` | ExtensionKit | Root (system) |
| **Third-Party Modules** | `/Library/Filesystems/` | fskitd | Root (sudo) |
---
## 6. Entitlements Required
### 6.1 Apple FSKit Module Entitlements
**Source**: `/System/Library/ExtensionKit/Extensions/com.apple.fskit.exfat.appex`
**Entitlements**:
```xml
<key>com.apple.application-identifier</key>
<string>com.apple.fskit.exfat</string>
<key>com.apple.developer.fskit.fsmodule</key>
<true/>
<key>com.apple.security.app-sandbox</key>
<true/>
```
### 6.2 MarkBaseFS Module Entitlements
**Source**: `/Library/Filesystems/MarkBaseFS FSKit Module.appex`
**Entitlements**:
```xml
<key>com.apple.application-identifier</key>
<string>com.accusys.markbase.fskitmodule</string>
<key>com.apple.developer.fskit.fsmodule</key>
<true/>
<key>com.apple.security.app-sandbox</key>
<true/>
```
### 6.3 Entitlements Comparison
| Entitlement | Apple FSKit | MarkBaseFS | Required |
|-------------|-------------|------------|----------|
| `com.apple.application-identifier` | ✅ Yes | ✅ Yes | ✅ Yes |
| `com.apple.developer.fskit.fsmodule` | ✅ Yes | ✅ Yes | ✅ Yes (critical) |
| `com.apple.security.app-sandbox` | ✅ Yes | ✅ Yes | ✅ Yes |
### 6.4 Code Signing Comparison
| Feature | Apple FSKit | MarkBaseFS |
|---------|-------------|------------|
| **Certificate Authority** | Software Signing | Developer ID Application: Accusys,Inc (K3TDMD9Y6B) |
| **Notarization** | Apple internal | ✅ Stapled ticket |
| **Team Identifier** | not set | K3TDMD9Y6B |
| **Runtime Version** | N/A | 26.5.0 |
---
## 7. Key Findings Summary
### 7.1 Architecture
```
FSKit Architecture:
┌─────────────────────────────────────────────────┐
│ macOS Kernel (LIFS file system) │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ fskitd (mount manager daemon) │
│ - PID: 99535 │
│ - Manages mount lifecycle │
│ - Coordinates with other daemons │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ fskit_agent (agent daemon) │
│ - Mach service: com.apple.fskit.fskit_agent │
│ - Background/Aqua session type │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ ExtensionKit Framework │
│ - Discovery mechanism │
│ - Extension Point: com.apple.fskit.fsmodule │
└─────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────┐
│ FSKit Modules (.appex) │
│ - /System/Library/ExtensionKit/Extensions/ │
│ - /Library/Filesystems/ │
└─────────────────────────────────────────────────┘
```
### 7.2 Installation Process
**Step-by-Step**:
1. **Build FSKit Module**:
- Create `.appex` bundle with correct Info.plist
- Set `EXExtensionPointIdentifier = com.apple.fskit.fsmodule`
- Add entitlements: `com.apple.developer.fskit.fsmodule = true`
2. **Code Signing**:
- Sign with Developer ID Application certificate
- Enable Hardened Runtime (options runtime)
- Submit for notarization
- Staple ticket
3. **Installation**:
```bash
sudo cp "MarkBaseFS FSKit Module.appex" /Library/Filesystems/
sudo chown root:wheel /Library/Filesystems/MarkBaseFS FSKit Module.appex
```
4. **Discovery**:
- fskitd automatically discovers module
- No restart required
- Module becomes available for mounting
### 7.3 Critical Requirements
| Requirement | Status |
|-------------|--------|
| ✅ Correct Extension Point | `com.apple.fskit.fsmodule` |
| ✅ Correct Entitlements | `com.apple.developer.fskit.fsmodule = true` |
| ✅ App Sandbox | `com.apple.security.app-sandbox = true` |
| ✅ Code Signing | Developer ID Application |
| ✅ Notarization | Stapled ticket |
| ✅ Correct Location | `/Library/Filesystems/` |
| ✅ Root Ownership | `root:wheel` |
---
## 8. Recommendations for MarkBaseFS
### 8.1 Current Status
✅ MarkBaseFS Module is correctly installed at `/Library/Filesystems/MarkBaseFS FSKit Module.appex`
✅ Entitlements match Apple FSKit Modules
✅ Code signed with Developer ID Application
✅ Notarization ticket stapled
✅ Automatically discovered by fskitd
### 8.2 Installation Script Recommendation
```bash
#!/bin/bash
# MarkBaseFS FSKit Module Installation Script
# 1. Build FSKit Module (already done)
# xcodebuild -project MarkBaseFS.xcodeproj -scheme MarkBaseFS
# 2. Code Sign (already done)
# codesign --sign "Developer ID Application: Accusys,Inc (K3TDMD9Y6B)" \
# --deep --force --verify --verbose --options runtime \
# "MarkBaseFS FSKit Module.appex"
# 3. Notarize (already done)
# xcrun notarytool submit ...
# xcrun stapler staple ...
# 4. Install to correct location
sudo cp -R "MarkBaseFS FSKit Module.appex" /Library/Filesystems/
sudo chown -R root:wheel "/Library/Filesystems/MarkBaseFS FSKit Module.appex"
# 5. Verify installation
ls -la /Library/Filesystems/
codesign -dvvv "/Library/Filesystems/MarkBaseFS FSKit Module.appex"
# 6. Trigger discovery (optional, automatic)
# killall fskitd # fskitd will restart and discover
echo "MarkBaseFS FSKit Module installed successfully"
```
### 8.3 Next Steps
1. ✅ Current installation is correct
2. Test mounting via Finder or `diskutil`
3. Performance validation (target: 600 MB/s)
4. Document mounting procedures for end users
---
## 9. Sources and Citations
### 9.1 System Sources
- **fskitd man page**: `man fskitd`
- **Apple FSKit Modules**: `/System/Library/ExtensionKit/Extensions/`
- **MarkBaseFS Module**: `/Library/Filesystems/MarkBaseFS FSKit Module.appex`
- **Launch Agent**: `/System/Library/LaunchAgents/com.apple.fskit.fskit_agent.plist`
### 9.2 Code Signing Evidence
- **Apple FSKit**: `codesign -dvvv /System/Library/ExtensionKit/Extensions/com.apple.fskit.exfat.appex`
- **MarkBaseFS**: `codesign -dvvv /Library/Filesystems/MarkBaseFS FSKit Module.appex`
### 9.3 Process Evidence
- **fskitd**: `ps aux | grep fskit` → PID 99535
- **fskit_agent**: `launchctl list | grep fskit` → com.apple.fskit.fskit_agent
### 9.4 Documentation Sources
- **Apple Developer**: https://developer.apple.com/documentation/fskit
- **rclone Documentation**: https://rclone.org/docs/
- **MarkBaseFS README**: `/Users/accusys/markbase/MarkBaseFS/README.md`
- **FSKit Backend Test**: `/Users/accusys/markbase/docs/fuse_poc/FSKit_BACKEND_TEST.md`
---
## 10. Conclusion
**FSKit Module Installation is straightforward**:
1. ✅ Build `.appex` with correct Info.plist and entitlements
2. ✅ Code sign with Developer ID Application
3. ✅ Notarize and staple
4. ✅ Install to `/Library/Filesystems/`
5. ✅ fskitd automatically discovers module
6. ✅ No restart required
**MarkBaseFS is correctly installed and should be functional**.
**No System Extension API or approval process is required**.
---
**Report Version**: 1.0
**Date**: 2026-05-28
**Status**: Research Complete ✅
Reference in New Issue View Git Blame Copy Permalink