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）
This commit is contained in:
Warren
274
MarkBaseFS/docs/FSKIT_MODULE_USER_GUIDE.md
Normal file
274
MarkBaseFS/docs/FSKIT_MODULE_USER_GUIDE.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 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**
|
||||
Reference in New Issue
Block a user