markbase/docs/FUSE_MOUNT_TEST_GUIDE.md

# FUSE Mount 实际测试指南

## 问题诊断结果

### 成功证据（fuse-t.log）

```
time="2026-05-17T11:16:08+08:00" level=info msg=starting...
time="2026-05-17T11:16:08+08:00" level=info msg="comm socket: 9"
time="2026-05-17T11:16:08+08:00" level=info msg="montor socket: 11"
time="2026-05-17T11:16:08+08:00" level=info msg="Server version 1.2.6 running at 127.0.0.1:52100"
time="2026-05-17T11:16:08+08:00" level=info msg="Mounting: /private/tmp/MarkBase_warren"
time="2026-05-17T11:16:08+08:00" level=info msg="mount [-o port=52100,mountport=52100,vers=4,nobrowse -t nfs fuse-t:/MarkBase-warren /private/tmp/MarkBase_warren]"
```

**结论：Mount 成功启动了！**

### 失败原因

**Mount 进程立即退出 → go-nfsv4 也终止 → 自动卸载**

---

## 正确的测试流程

### Step 1: 启动 Mount（阻塞式）

**打开 Terminal 1，运行：**

```bash
/tmp/mount_warren.sh
```

**或直接运行：**

```bash
cd /Users/accusys/markbase
mkdir -p /tmp/MarkBase_warren
cargo run -- fuse mount --user warren --dir /tmp/MarkBase_warren
```

**⚠️ 重要：保持这个 Terminal 开启！不要关闭！**

**预期输出：**

```
=== Mounting MarkBase FUSE ===
User: warren
Mount path: /tmp/MarkBase_warren
Database: data/users/warren.sqlite
Backend: fskit
macOS version: 26.4.1
[INFO] Mounting MarkBase FUSE for user: warren
[INFO] FUSE session mounted successfully
[INFO] Starting FUSE request handler thread
[INFO] Mount completed for user: warren, waiting for requests...

(进程阻塞在这里，等待 FUSE requests)
```

### Step 2: 验证 Mount（另一个 Terminal）

**打开 Terminal 2，运行：**

```bash
# 检查 mount 状态
mount | grep MarkBase_warren

# 预期输出：
# fuse-t:/MarkBase-warren on /private/tmp/MarkBase_warren (nfs, nobrowse)

# 检查进程
ps aux | grep go-nfsv4

# 预期输出：
# /Library/Application Support/fuse-t/bin/go-nfsv4-1.2.6 ...

# 测试文件访问
ls -la /tmp/MarkBase_warren/

# 统计文件数量
find /tmp/MarkBase_warren -type f | wc -l   # Expected: 11857 files
find /tmp/MarkBase_warren -type d | wc -l   # Expected: 802 folders
```

### Step 3: 测试文件操作

```bash
# 查看根目录
ls -la /tmp/MarkBase_warren/Home/

# 读取文件（测试 read() operation）
cat /tmp/MarkBase_warren/Home/.../test_file.txt

# 检查文件属性（测试 getattr() operation）
stat /tmp/MarkBase_warren/Home/.../file.mp4

# 测试 write() operation（创建测试文件）
echo "test write" > /tmp/MarkBase_warren/test_write.txt
cat /tmp/MarkBase_warren/test_write.txt
```

### Step 4: Unmount

**在 Terminal 1 按 Ctrl+C 停止进程**

**或在 Terminal 2 运行：**

```bash
umount /tmp/MarkBase_warren
# 或
cargo run -- fuse unmount --dir /tmp/MarkBase_warren
```

---

## Mount 流程详解

### fuse_t_session.rs 实现流程

```
1. socketpair() → 创建 Unix socket pairs
   - (fd0, fd1) - FUSE communication channel
   - (mon_fd0, mon_fd1) - Mount status monitor

2. fork() → 分裂成两个进程
   ├─ Parent Process:
   │  ├─ 关闭 fd0, mon_fd0
   │  ├─ 保持 fd1 → File object (FUSE channel)
   │  ├─ 保持 mon_fd1 → File object (monitor)
   │  └─ 返回 session.file, session.monitor_file
   │
   └─ Child Process:
   ├─ 关闭 fd1, mon_fd1
   ├─ 设置环境变量:
   │  ├─ _FUSE_DAEMON_PATH - daemon executable path
   │  ├─ _FUSE_CALL_BY_LIB - "1" (标记为 library call)
   │  ├─ _FUSE_COMMFD - fd0 (socket fd)
   │  ├─ _FUSE_MONFD - mon_fd0 (monitor fd)
   │  └─ _FUSE_COMMVERS - "2" (protocol version)
   ├─ Exec go-nfsv4:
   │  ├─ --noatime=true
   │  ├─ --dontbrowse=true
   │  ├─ --volname MarkBase-warren
   │  └─ /tmp/MarkBase_warren
   └─ Panic (should never reach here)

3. go-nfsv4 启动:
   ├─ 从环境变量获取 socket fds
   ├─ 启动 NFS server (127.0.0.1:52100)
   ├─ 执行 mount_nfs 命令:
   │  mount -o port=52100,mountport=52100,vers=4,nobrowse \
   │        -t nfs fuse-t:/MarkBase-warren /tmp/MarkBase_warren
   └─ 等待 FUSE requests (via socket fd0)

4. send_mount_command():
   ├─ 启动独立 thread
   ├─ 发送 "mount" message 到 mon_fd1
   └─ 等待 go-nfsv4 返回 status

5. FUSE request handler thread:
   ├─ loop:
   │  ├─ channel.get_request() → (reader, writer)
   │  ├─ server.handle_message(reader, writer)
   │  └─ Continue until ENODEV or error
   └─ Exit on unmount

6. wait_mount():
   └─ 等待 send_mount_command() thread 完成
```

### 关键点

1. **环境变量传递** - go-nfsv4 必须通过 `_FUSE_COMMFD` 环境变量获取 socket fd
2. **Fork + Exec** - Child process 执行 go-nfsv4，Parent 保持 socket channel
3. **阻塞式运行** - Handler thread 必须持续运行处理 requests
4. **进程生命周期绑定** - Parent process 退出 → go-nfsv4 也终止

---

## 已修复的问题

### mount_manager.rs 修改

**之前：**
```rust
thread::spawn(move || {
    // Handler thread
});

handle.session.wait_mount()?;  // 等待 mount status
// 焋退出 ← 导致 go-nfsv4 也退出
```

**修复后：**
```rust
let handler_thread = thread::spawn(move || {
    // Handler thread
});

handler_thread.join()?;  // 阻塞等待 handler thread
// 保持进程运行 ← go-nfsv4 持续运行
```

---

## 下一步测试

**立即测试（推荐）：**

1. 打开 Terminal 1: `/tmp/mount_warren.sh`
2. 打开 Terminal 2: `mount | grep MarkBase`
3. 如果看到 mount，继续文件访问测试

**预期结果：**
- ✓ Mount 成功建立
- ✓ 12659 nodes 可见（802 folders + 11857 files）
- ✓ read() operation 正常工作
- ✓ write() operation 正常工作（Phase 4 partial）

---

**文档更新：2026-05-17 11:20**
**状态：Mount 流程已修复，等待实际测试**