Scorpio：基于 FUSE 的 Monorepo 虚拟文件系统

传统方式：git clone (下载全部) → 本地操作 → git push
Scorpio： mount (下载目录树) → 按需加载 → 本地操作 → commit & push

┌─────────────────────────────────────────────────────────────────────────┐
│                           用户空间 (User Space)                        │
│                                                                         │
│   ┌─────────────┐         ┌──────────────────────────────────────┐     │
│   │ Application │         │     FUSE Daemon (用户态文件系统)      │     │
│   │  (ls, cat)  │         │                                      │     │
│   └──────┬──────┘         │  ┌──────────────────────────────┐   │     │
│          │                │  │  实现 read/write/lookup 等    │   │     │
│          │ open/read      │  │  例如: Scorpio, sshfs, rclone │   │     │
│          │                │  └──────────────────────────────┘   │     │
│          │                └──────────────────┬───────────────────┘     │
└──────────│───────────────────────────────────│─────────────────────────┘
           │                                   │
           │ syscall                           │ /dev/fuse
           ▼                                   ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                           内核空间 (Kernel Space)                       │
│                                                                          │
│   ┌─────────────┐      ┌──────────────┐      ┌─────────────────┐        │
│   │     VFS     │ ───► │ FUSE Kernel  │ ───► │   /dev/fuse     │        │
│   │ (虚拟文件   │      │   Module     │      │ (字符设备)       │        │
│   │  系统层)    │      │              │      │                 │        │
│   └─────────────┘      └──────────────┘      └─────────────────┘        │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

1. 应用程序调用 open("/mnt/fuse/file.txt", O_RDONLY)
                    │
                    ▼
2. 系统调用进入内核 VFS 层
                    │
                    ▼
3. VFS 发现挂载点属于 FUSE，转发请求到 FUSE 内核模块
                    │
                    ▼
4. FUSE 内核模块将请求序列化，写入 /dev/fuse
                    │
                    ▼
5. 用户态 FUSE 守护进程从 /dev/fuse 读取请求
                    │
                    ▼
6. 守护进程处理请求（如从网络获取文件内容）
                    │
                    ▼
7. 守护进程将响应写回 /dev/fuse
                    │
                    ▼
8. FUSE 内核模块将响应返回给 VFS
                    │
                    ▼
9. 应用程序收到 open() 的返回值

use rfuse3::raw::{Filesystem, Request};

impl Filesystem for MyFS {
    async fn lookup(&self, req: Request, parent: u64, name: &OsStr) -> Result<ReplyEntry> {
        // 查找 parent 目录下名为 name 的文件
        // 返回文件的 inode 和属性
    }

    async fn read(&self, req: Request, ino: u64, offset: i64, size: u32) -> Result<ReplyData> {
        // 读取 inode 为 ino 的文件，从 offset 开始读取 size 字节
    }

    async fn write(&self, req: Request, ino: u64, offset: i64, data: &[u8]) -> Result<ReplyWrite> {
        // 将 data 写入到 inode 为 ino 的文件的 offset 位置
    }
}

┌─────────────────┐                    ┌─────────────────┐
│   FUSE Kernel   │                    │   FUSE Daemon   │
│     Module      │                    │   (Scorpio)     │
└────────┬────────┘                    └────────┬────────┘
         │                                      │
         │  FUSE_INIT request                   │
         │  ┌─────────────────────────────┐     │
         │  │ major: 7                    │     │
         │  │ minor: 38                   │     │
         │  │ max_readahead: 131072       │     │
         │  │ flags: ASYNC_READ |         │     │
         │  │        WRITEBACK_CACHE |    │     │
         │  │        PARALLEL_DIROPS | ...│     │
         │  └─────────────────────────────┘     │
         │ ─────────────────────────────────────►
         │                                      │
         │  FUSE_INIT reply                     │
         │  ┌─────────────────────────────┐     │
         │  │ major: 7                    │     │
         │  │ minor: 38                   │     │
         │  │ max_write: 1048576          │     │
         │  │ flags: ASYNC_READ |         │     │
         │  │        BIG_WRITES | ...     │     │
         │  └─────────────────────────────┘     │
         │ ◄─────────────────────────────────────
         │                                      │

传统文件系统 (ext4):
  App → syscall → VFS → ext4 → 返回
        └─────────────────────────┘
              1 次上下文切换

FUSE 文件系统:
  App → syscall → VFS → FUSE kernel → /dev/fuse
                                          │
        ┌─────────────────────────────────┘
        │
        ▼
  FUSE daemon (用户态处理) → /dev/fuse → FUSE kernel → 返回
        └─────────────────────────────────────────────────┘
                        4 次上下文切换

普通 FUSE 读取:
  read() → kernel → /dev/fuse → daemon → 读取后端 → 返回

Passthrough 模式:
  read() → kernel → 直接读取后端文件 → 返回
                    (绕过 daemon)

// rfuse3 未来可能的 io_uring 集成方向
// (当前仍使用 epoll/kqueue)
let ring = IoUring::new(256)?;
ring.submitter().register_files(&[fuse_fd])?;

┌─────────────────┐     ┌─────────────────┐
│   Guest VM      │     │      Host       │
│                 │     │                 │
│  ┌───────────┐  │     │  ┌───────────┐  │
│  │ virtiofs  │──┼─────┼─►│ virtiofsd │  │
│  │  (kernel) │  │     │  │           │  │
│  └───────────┘  │     │  └───────────┘  │
│                 │     │        │        │
│  共享内存直通   │     │        ▼        │
│  (DAX window)   │◄────┼──── Host FS     │
└─────────────────┘     └─────────────────┘

// rfuse3 的 MountOptions 配置示例
let mut options = MountOptions::default();
options
    .force_readdir_plus(true)      // 启用 READDIRPLUS
    .uid(getuid())
    .gid(getgid());

// libfuse (C) - 同步回调
static int my_read(const char *path, char *buf, size_t size,
                   off_t offset, struct fuse_file_info *fi) {
    // 同步读取，阻塞当前线程
    return pread(fi->fh, buf, size, offset);
}

// rfuse3 (Rust) - 异步回调
async fn read(
    &self,
    _req: Request,
    inode: u64,
    fh: u64,
    offset: u64,
    size: u32,
) -> Result<ReplyData> {
    // 异步读取，不阻塞 executor
    let data = self.backend.read(inode, offset, size).await?;
    Ok(ReplyData { data })
}

┌─────────────────────────────────────────────────────────────────────────┐
│                              应用层                                    │
│                                                                         │
│   开发者工具 (IDE, 编译器, 脚本)                                         │
│         │                                                               │
│         ▼                                                               │
│   /workspace/src/main.rs  (挂载点)                                      │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                            FUSE 接口层                                 │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                         MegaFuse                               │   │
│   │                                                                │   │
│   │   职责:                                                        │   │
│   │   - 实现 FUSE Filesystem trait                                 │   │
│   │   - 管理多个 OverlayFs 实例                                     │   │
│   │   - Inode 分配和映射                                            │   │
│   │   - 将请求路由到对应的文件系统层                                 │   │
│   └─────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                           联合文件系统层                                │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                        OverlayFs                               │   │
│   │                                                                │   │
│   │   ┌───────────────────────────────────────────────────────┐     │   │
│   │   │  Upper Layer (读写层)                                  │     │   │
│   │   │  - Passthrough 到本地目录                              │     │   │
│   │   │  - 所有写操作都在这里                                   │     │   │
│   │   │  - Copy-on-Write 语义                                  │     │   │
│   │   ├───────────────────────────────────────────────────────┤     │   │
│   │   │  CL Layer (可选，变更列表层)                            │     │   │
│   │   │  - 用于 CI/CD 场景的增量变更                            │     │   │
│   │   ├───────────────────────────────────────────────────────┤     │   │
│   │   │  Lower Layer (只读层)                                  │     │   │
│   │   │  - Dicfuse 虚拟文件系统                                 │     │   │
│   │   │  - 从 Mega 服务器按需拉取                               │     │   │
│   │   └───────────────────────────────────────────────────────┘     │   │
│   └─────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                            数据存储层                                  │
│                                                                         │
│   ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐     │
│   │   Tree Store     │  │  Content Store   │  │   Local Store    │     │
│   │                  │  │                  │  │                  │     │
│   │  目录树元数据     │  │  文件内容缓存    │  │  本地修改数据     │     │
│   │  (sled DB)       │  │  (内存+磁盘)     │  │  (passthrough)   │     │
│   └──────────────────┘  └──────────────────┘  └──────────────────┘     │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
┌───────────────────────────────────▼─────────────────────────────────────┐
│                            网络层                                      │
│                                                                         │
│   ┌─────────────────────────────────────────────────────────────────┐   │
│   │                      Mega Server API                           │   │
│   │                                                                │   │
│   │  GET /api/v1/tree/{commit_id}     获取目录树                    │   │
│   │  GET /api/v1/blob/{blob_id}       获取文件内容                  │   │
│   │  POST /api/v1/commit              提交变更                      │   │
│   └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘

pub struct Dicfuse {
    readable: bool,
    pub store: Arc<DictionaryStore>,  // 元数据存储
}

impl Dicfuse {
    /// 按需加载文件内容
    async fn load_one_file(&self, parent: u64, name: &OsStr) -> std::io::Result<()> {
        // 1. 查找父目录的 Tree 对象
        let parent_item = self.store.find_path(parent).await?;
        let tree = fetch_tree(&parent_item).await?;

        // 2. 在 Tree 中找到目标文件
        for item in tree.tree_items {
            if item.name == name && item.mode == Blob {
                // 3. 从服务器拉取 Blob 内容
                let url = format!("{}/{}", blob_endpoint, item.id);
                let content = client.get(url).send().await?.bytes().await?;

                // 4. 缓存到本地
                self.store.save_file(inode, content.to_vec());
            }
        }
        Ok(())
    }
}

                     首次访问 /workspace/src/main.rs
                                    │
                                    ▼
              ┌─────────────────────────────────────────┐
              │  Dicfuse.lookup("src", "main.rs")       │
              │                                         │
              │  1. 检查本地缓存 → 未命中               │
              │  2. 查询 Tree Store 获取元数据          │
              │     → 找到: inode=42, size=1024        │
              │  3. 返回文件属性（不加载内容）          │
              └─────────────────────────────────────────┘
                                    │
                                    ▼
              ┌─────────────────────────────────────────┐
              │  Dicfuse.read(inode=42, offset=0)       │
              │                                         │
              │  1. 检查 Content Store → 未命中         │
              │  2. 从 Mega 服务器拉取 Blob             │
              │     GET /api/v1/blob/{sha1}            │
              │  3. 存入 Content Store                  │
              │  4. 返回文件内容                        │
              └─────────────────────────────────────────┘

                    用户视角（合并视图）
                    /workspace/
                    ├── src/
                    │   ├── main.rs      (来自 Upper，已修改)
                    │   └── lib.rs       (来自 Lower，只读)
                    └── Cargo.toml       (来自 Lower，只读)

         ═══════════════════════════════════════════════════
                              │
            ┌─────────────────┼─────────────────┐
            ▼                 ▼                 ▼
     ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
     │ Upper Layer │  │  CL Layer   │  │ Lower Layer │
     │  (读写)     │  │  (可选)     │  │  (只读)     │
     ├─────────────┤  ├─────────────┤  ├─────────────┤
     │ src/        │  │             │  │ src/        │
     │   main.rs ✏ │  │             │  │   main.rs   │
     │             │  │             │  │   lib.rs    │
     │             │  │             │  │ Cargo.toml  │
     └─────────────┘  └─────────────┘  └─────────────┘

impl MegaFuse {
    /// 挂载一个 overlay 文件系统
    pub async fn overlay_mount(
        &self,
        inode: u64,
        store_path: &Path,
        need_cl: bool,
        cl_link: Option<&str>,
    ) -> std::io::Result<()> {
        // 构建层结构
        let lower = store_path.join("lower");   // Dicfuse 映射
        let upper = store_path.join("upper");   // 本地写入层

        let mut lower_layers = vec![];

        // 可选的 CL 层
        if need_cl {
            let cl_path = store_path.join("cl").join(cl_link);
            lower_layers.push(new_passthroughfs_layer(cl_path));
        }

        // 添加只读下层
        lower_layers.push(new_passthroughfs_layer(lower));

        // 创建读写上层
        let upper_layer = new_passthroughfs_layer(upper);

        // 组装 OverlayFs
        let overlayfs = OverlayFs::new(
            Some(upper_layer),  // 读写层
            lower_layers,       // 只读层列表
            config,
            inode,
        )?;

        self.overlayfs.lock().await.insert(inode, Arc::new(overlayfs));
        Ok(())
    }
}

pub struct InodeAlloc {
    // 每个 overlay 分配一个 inode 区间
    // 避免不同 overlay 的 inode 冲突
    allocations: Mutex<HashMap<u64, InodeBatch>>,
}

struct InodeBatch {
    start: u64,
    end: u64,
    next: u64,
}

impl InodeAlloc {
    /// 为新的 overlay 分配 inode 批次
    pub async fn alloc_inode(&self, overlay_inode: u64) -> InodeBatch {
        let mut alloc = self.allocations.lock().await;

        // 计算新的区间
        let batch_size = 0x1000_0000;  // 每个 overlay 分配 256M 个 inode
        let start = overlay_inode * batch_size;
        let end = start + batch_size - 1;

        let batch = InodeBatch { start, end, next: start + 1 };
        alloc.insert(overlay_inode, batch);
        batch
    }
}

┌──────────────────────────────────────────────────────────────┐
│                       CI/CD Pipeline                        │
│                                                              │
│  Job 1 ─────► Antares Mount ─────► /mnt/job1/                │
│               (独立工作空间)        ├── src/ (Dicfuse)        │
│                                    └── build/ (Upper)        │
│                                                              │
│  Job 2 ─────► Antares Mount ─────► /mnt/job2/                │
│               (独立工作空间)        ├── src/ (Dicfuse)        │
│                                    └── build/ (Upper)        │
│                                                              │
│  共享只读层：Dicfuse（单例，节省内存）                        │
└──────────────────────────────────────────────────────────────┘

pub struct AntaresFuse {
    pub mountpoint: PathBuf,
    pub upper_dir: PathBuf,           // 独立的写入层
    pub dic: Arc<Dicfuse>,            // 共享的只读层
    pub cl_dir: Option<PathBuf>,      // 可选的 CL 层
    fuse_task: Option<JoinHandle<()>>,
}

impl AntaresFuse {
    /// 构建 overlay 并挂载
    pub async fn mount(&mut self) -> std::io::Result<()> {
        let overlay = self.build_overlay().await?;

        // 启动 FUSE 会话
        let handle = mount_filesystem(overlay, &self.mountpoint).await;

        self.fuse_task = Some(tokio::spawn(async move {
            let _ = handle.await;
        }));

        Ok(())
    }

    /// 卸载
    pub async fn unmount(&mut self) -> std::io::Result<()> {
        // 调用 fusermount -u 卸载
        Command::new("fusermount")
            .arg("-u")
            .arg(&self.mountpoint)
            .output()
            .await?;
        Ok(())
    }
}

#[tokio::main]
async fn main() {
    // 1. 加载配置
    config::init_config("scorpio.toml")?;

    // 2. 初始化 ScorpioManager，检查工作目录状态
    let mut manager = ScorpioManager::from_toml(config_file)?;
    manager.check().await;  // 同步目录树元数据

    // 3. 创建 MegaFuse，挂载工作目录
    let fuse = MegaFuse::new_from_manager(&manager).await;

    // 4. 启动 FUSE 会话
    let mount_handle = mount_filesystem(fuse, mountpoint).await;

    // 5. 启动 HTTP daemon
    tokio::spawn(daemon_main(Arc::new(fuse), manager));

    // 6. 等待退出信号
    tokio::select! {
        _ = mount_handle => {},
        _ = signal::ctrl_c() => {
            mount_handle.unmount().await?;
        }
    }
}

用户执行: cat /workspace/src/main.rs
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  1. VFS → FUSE 内核模块 → /dev/fuse                     │
│     FUSE_LOOKUP: parent=1, name="src"                   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  2. MegaFuse.lookup(parent=1, name="src")               │
│     → 查找 overlay 映射                                  │
│     → 委托给 OverlayFs.lookup()                          │
│     → 返回 inode=2, attr={dir, mode=0755}               │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  3. MegaFuse.lookup(parent=2, name="main.rs")           │
│     → OverlayFs 按优先级查找：                           │
│       a. Upper 层：不存在                                │
│       b. Lower 层 (Dicfuse)：存在元数据                  │
│     → 返回 inode=42, attr={file, size=1024}             │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  4. MegaFuse.open(inode=42, flags=O_RDONLY)             │
│     → 返回 file handle                                   │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  5. MegaFuse.read(inode=42, offset=0, size=4096)        │
│     → OverlayFs.read() → Dicfuse.read()                 │
│     → 检查 Content Store：未命中                         │
│     → HTTP GET /api/v1/blob/{sha1}                      │
│     → 缓存内容到 Content Store                           │
│     → 返回文件数据                                       │
└─────────────────────────────────────────────────────────┘

用户执行: echo "new content" >> /workspace/src/main.rs
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  1. MegaFuse.open(inode=42, flags=O_WRONLY|O_APPEND)    │
│     → OverlayFs 检测到写操作                             │
│     → 触发 Copy-on-Write                                │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  2. Copy-on-Write 过程：                                │
│     a. 从 Lower 层读取原始内容                           │
│     b. 在 Upper 层创建同名文件                           │
│     c. 将原始内容复制到 Upper 层                         │
│     d. 标记 Upper 层文件为"覆盖"                         │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  3. MegaFuse.write(inode=42, data="new content\n")      │
│     → 写入 Upper 层文件                                  │
│     → Lower 层原始文件保持不变                           │
└─────────────────────────────────────────────────────────┘

写入后的层结构：
┌─────────────┐
│ Upper Layer │  src/main.rs  ← 包含新内容
├─────────────┤
│ Lower Layer │  src/main.rs  ← 原始内容（被遮盖）
└─────────────┘

用户执行: scorpio commit -m "update main.rs"
              │
              ▼
┌─────────────────────────────────────────────────────────┐
│  1. 扫描 Upper 层变更                                    │
│     → 遍历 upper/ 目录                                   │
│     → 收集所有修改/新增/删除的文件                        │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  2. 构建 Git 对象                                        │
│     a. 为每个修改的文件创建 Blob 对象                    │
│     b. 构建新的 Tree 对象（合并变更）                    │
│     c. 创建 Commit 对象                                  │
│        - parent: 上一个 commit                          │
│        - tree: 新的根 tree                              │
│        - message: "update main.rs"                      │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  3. 推送到服务器                                         │
│     POST /api/v1/commit                                 │
│     Body: { objects: [...], commit: {...} }             │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  4. 更新本地状态                                         │
│     → 清空 Upper 层                                      │
│     → 更新 Tree Store 到新 commit                        │
└─────────────────────────────────────────────────────────┘

impl Dicfuse {
    /// 批量预取目录内容
    pub async fn prefetch_directory(&self, inode: u64) {
        let tree = fetch_tree(inode).await;

        // 将所有子项元数据存入 Tree Store
        for item in tree.items {
            self.store.insert_metadata(item);
        }
    }
}

┌─────────────────────────────────────────────────────────┐
│                    缓存层次                              │
│                                                         │
│  L1: 内存缓存 (LRU，限制大小)                           │
│       ↓ miss                                            │
│  L2: 本地磁盘缓存 (Content Store)                       │
│       ↓ miss                                            │
│  L3: Mega 服务器                                        │
└─────────────────────────────────────────────────────────┘

pub struct DictionaryStore {
    tree_cache: RwLock<HashMap<u64, TreeNode>>,
    content_cache: RwLock<HashMap<u64, Vec<u8>>>,
}

// 读操作使用读锁，允许并发
async fn get_metadata(&self, inode: u64) -> Option<TreeNode> {
    self.tree_cache.read().await.get(&inode).cloned()
}

// 写操作使用写锁
async fn insert_metadata(&self, inode: u64, node: TreeNode) {
    self.tree_cache.write().await.insert(inode, node);
}

# 启动 Scorpio
./scorpio -c scorpio.toml

# 查看挂载的工作空间
ls /workspace
# src/  Cargo.toml  README.md

# 像普通仓库一样使用
cd /workspace
cargo build
vim src/main.rs

# 提交变更
curl -X POST http://localhost:8000/api/commit \
  -H "Content-Type: application/json" \
  -d '{"message": "fix bug"}'

# 启动 Antares daemon
./antares serve --bind 0.0.0.0:2726

# 创建构建环境
curl -X POST http://localhost:2726/mounts \
  -H "Content-Type: application/json" \
  -d '{
    "mountpoint": "/mnt/job1",
    "upper_dir": "/var/antares/upper/job1",
    "labels": ["ci", "build"],
    "readonly": false
  }'

# 在隔离环境中构建
cd /mnt/job1
./build.sh

# 清理
curl -X DELETE http://localhost:2726/mounts/{mount_id}