# FSKit Module安装操作指南

## 日期：2026-05-26
## 版本：1.0

---

## 概述

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

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

---

## 准备工作检查

### 必要文件确认

**请确认以下文件存在：**

```bash
# 检查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

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

```bash
# 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：验证安装

**执行验证脚本：**

```bash
# 设置执行权限
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：正常重启**
```bash
sudo shutdown -r now
```

**方法2：使用Apple Menu重启**
- 点击Apple Menu ()
- 选择 "Restart..."
- 等待系统重启

**注意：**
- 重启前请保存所有工作
- 重启需要约1-2分钟

---

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

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

```bash
# 检查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测试程序：**

```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：
```bash
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**