markbase/MarkBaseFS/docs/FSKIT_MODULE_USER_GUIDE.md

FSKit Module安装操作指南

日期：2026-05-26

版本：1.0

---

概述

本指南将帮助您完成MarkBaseFS FSKit Module的系统级安装

预计操作时间：10-15分钟

---

准备工作检查

必要文件确认

请确认以下文件存在：

# 检查FSKit Module Bundle
ls -la "/Users/accusys/markbase/MarkBaseFS/build/Debug/MarkBaseFS FSKit Module.bundle"

# 检查测试脚本
ls -la /Users/accusys/markbase/MarkBaseFS/tests/*.sh

预期结果：

• ✅ MarkBaseFS FSKit Module.bundle 存在
• ✅ fskit_module_test.sh 存在
• ✅ install_fskit_module.sh 存在
• ✅ verify_fskit_module.sh 存在

---

操作步骤

步骤1：安装FSKit Module Bundle

打开终端，执行以下命令：

# 1. 创建filesystems目录
sudo mkdir -p /Library/Filesystems

# 2. 复制FSKit Module bundle
sudo cp -R '/Users/accusys/markbase/MarkBaseFS/build/Debug/MarkBaseFS FSKit Module.bundle' /Library/Filesystems/

# 3. 设置权限
sudo chmod 755 '/Library/Filesystems/MarkBaseFS FSKit Module.bundle'
sudo chown root:wheel '/Library/Filesystems/MarkBaseFS FSKit Module.bundle'

注意：

• 需要输入sudo密码
• 每个命令需要单独执行
• 如果命令失败，请检查路径是否正确

---

步骤2：验证安装

执行验证脚本：

# 设置执行权限
chmod +x /Users/accusys/markbase/MarkBaseFS/tests/verify_fskit_module.sh

# 运行验证脚本
/Users/accusys/markbase/MarkBaseFS/tests/verify_fskit_module.sh

预期结果：

• ✅ Bundle exists in system directory
• ✅ Bundle has executable permissions
• ✅ Bundle has correct ownership (root:wheel)

---

步骤3：重启macOS（重要）

FSKit Module需要重启才能加载

重启方式：

方法1：正常重启

sudo shutdown -r now

方法2：使用Apple Menu重启

• 点击Apple Menu ()
• 选择 "Restart..."
• 等待系统重启

注意：

• 重启前请保存所有工作
• 重启需要约1-2分钟

---

步骤4：重启后验证Module加载

重启完成后，打开终端执行：

# 检查Bundle是否存在
ls -la "/Library/Filesystems/MarkBaseFS FSKit Module.bundle"

# 检查Bundle ID
cat "/Library/Filesystems/MarkBaseFS FSKit Module.bundle/Contents/Info.plist" | grep CFBundleIdentifier

预期结果：

• ✅ Bundle still exists after reboot
• ✅ Bundle ID: com.accusys.markbase.fskitmodule

---

步骤5：测试Module加载（可选）

使用FSClient API测试：

需要创建Swift测试程序：

import Foundation
import FSKit

let client = FSClient.shared
client.fetchInstalledExtensions { modules, error in
    if let modules = modules {
        print("Installed FSKit Modules:")
        for module in modules {
            print("  - Bundle ID: \(module.bundleIdentifier)")
            print("    URL: \(module.url)")
            print("    Enabled: \(module.enabled)")
        }
    } else if let error = error {
        print("Error fetching modules: \(error)")
    }
}

---

常见问题

问题1：sudo命令失败

原因：

• 密码输入错误
• 权限不足

解决：

• 重新输入密码
• 确认用户有管理员权限

---

问题2：Bundle复制失败

原因：

• 路径错误
• Bundle不存在

解决：

• 检查Bundle路径是否正确
• 重新构建Bundle：

cd /Users/accusys/markbase/MarkBaseFS
xcodebuild -project MarkBaseFS.xcodeproj \
    -target MarkBaseFSFSKitModule \
    -configuration Debug \
    build

---

问题3：重启后Bundle消失

原因：

• macOS安全机制清理未授权的Bundle

解决：

• 需要通过System Extension API安装
• 需要Apple Developer签名

---

验证成功标志

成功标志

如果安装成功，您应该看到：

1. ✅ Bundle存在于 /Library/Filesystems/
2. ✅ Bundle权限正确 (755)
3. ✅ Bundle所有权正确 (root:wheel)
4. ✅ 重启后Bundle仍然存在

---

下一步操作

安装成功后

下一步：

1. 测试mount功能

   • 使用Disk Utility测试
   • 或使用终端命令测试

2. 验证Frame Index Table

   • 检查数据库是否正确连接
   • 检查Frame count是否正确

3. 测试File Operations

   • 测试文件读取
   • 测试文件写入

---

相关文档

参考文档

文档	位置	说明
FSKIT_MODULE_INSTALLATION.md	/Users/accusys/markbase/MarkBaseFS/docs/	安装技术文档
FSKIT_MODULE_USER_GUIDE.md	/Users/accusys/markbase/MarkBaseFS/docs/	用户操作指南（本文件）
fskit_module_test.sh	/Users/accusys/markbase/MarkBaseFS/tests/	测试脚本
verify_fskit_module.sh	/Users/accusys/markbase/MarkBaseFS/tests/	验证脚本

---

操作时间估算

时间估算

步骤	预计时间	说明
步骤1：安装Bundle	2-3分钟	sudo命令执行
步骤2：验证安装	1分钟	脚本验证
步骤3：重启macOS	2-5分钟	系统重启
步骤4：重启后验证	1分钟	Bundle检查
步骤5：测试加载	1-2分钟	FSClient测试
总计	7-12分钟	完整流程

---

重要提醒

重要提醒

⚠️ 重要提醒：

1. 重启是必要的

   • FSKit Module需要重启才能加载
   • 请保存所有工作后再重启

2. sudo密码需要手动输入

   • 无法自动输入sudo密码
   • 请在终端手动输入

3. Bundle可能被安全机制清理

   • macOS可能清理未授权的Bundle
   • 如果重启后Bundle消失，需要使用System Extension API

---

最后更新：2026-05-26