• 系统编程
• 存储
• 内核驱动

Hybrid Mount（meta-hybrid_mount）是一款面向 KernelSU 与 APatch 的混合挂载元模块，它内置了OverlayFS、Magic Mount、VFS 三种挂载后端，允许你在同一套模块中按模块、按路径自由混用。本文用通俗的语言对比三种后端的工作原理、优缺点和适用场景，帮你快速做出最适合自己的后端选型。

一、先认识一下 Hybrid Mount 📌

启动时，Hybrid Mount 会只读扫描模块目录，生成一棵"共享节点树"，再按路径规则 > 模块默认值 > 全局默认值的优先级，为每个文件或目录指派去向：overlay、magic、vfs或ignore（忽略）。整条启动流水线见 docs/ARCHITECTURE.md。

两个重要前提：

• 模块源目录始终是只读输入，/data/adb/modules/<id>/system/下的原文件不会被移动或删除；
• 修改配置后需要重启才能生效。

三种后端各有"脾气"：一个是内核原生的多层合并挂载，一个是文件级精准替换，另一个则干脆不是挂载。下面逐个拆解。

二、三种后端逐个拆解 ⚙️

1. OverlayFS：内核原生的"多层合并挂载"

这是默认后端，直接借用内核自带的 overlayfs：

• 多个模块的内容作为 lowerdir 层叠在一起，同一路径下优先级高的层遮住低的层；
• 一次挂载最多接受 64 层，超出的部分会自动折叠成中间层（src/overlayfs/overlayfs.rs）；
• 存储模式二选一：overlay_mode = "tmpfs"（内存）或"ext4"（loop 镜像，默认），镜像位于/data/adb/hybrid-mount/modules.img。

✅适合：模块文件量大、整棵目录树要合并、多个模块叠加在同一分区上的常规场景。

2. Magic Mount：文件级"精准替换"

同样是真实挂载，但策略完全不同（src/magic_mount/exec.rs）：

• 文件：直接 bind 到目标路径并只读重挂载；
• 目录：先搭一个 tmpfs "骨架"、镜像保留真实目录的其余条目，再整体挪到目标位置；
• 符号链接：克隆进 staging 区；
• 支持.replace（整目录替换）与 whiteout（隐藏文件）语义，所有写入都发生在私有随机 tmpfs 中，不占 ext4 镜像。

✅适合：只改少量文件、需要隐藏某个系统文件、追求低开销和快速启动的场景。

3. VFS：内核级的"隐身注入" 🕶️

VFS 与前两者有本质区别——它不是真实挂载：

• 由 HM 自有的hybridmount内核模块劫持内核路径查找，把虚拟路径重定向到真实文件（module/vfs/README.md）；
• 规则通过内核 keyring 下发（hm1协议），支持按 UID 限定规则、whiteout 隐藏、opaque 目录（src/vfs/mod.rs）；
• 注入点不会出现在mountinfo中，也不参与卸载列表，对依赖挂载表检测的手段更"隐形"；
• 依赖内核支持：发布包为每个受支持的 Android/GKI 目标都带了预编译.ko（module/vfs/binaries/），内核未内建时启动流程会自动尝试加载；仍不可用时按vfs_strict决定降级为ignore或直接启动失败；
• 它是独立实现，不与 NoMount 互操作，也不与 NoMount 的内核树兼容。

✅适合：不想暴露挂载点、需要按应用 UID 精细控制可见性、或以"隐藏"为主的场景。

三、一张表看懂核心区别 📊

四、按场景选型的完整指南 🎯

场景 1：大多数用户的默认答案 —— OverlayFS

首次安装可用音量键选择默认后端，config.toml中default_mode = "overlay"即为全局默认。内核原生、兼容性最好、多模块叠加语义清晰，没有特殊需求就选它。

场景 2：只改几个文件、要藏个别配置 —— Magic Mount

无需 ext4 镜像、启动开销小，单文件替换和 whiteout 最顺手，适合轻量模块组合。

场景 3：需要"隐形"或按应用隔离 —— VFS

先确认内核有匹配的支持（可用hybrid-mount vfs-doctor只读诊断，不会触发加载）。满足条件时，VFS 能让你在不产生任何挂载点的情况下完成文件替换与隐藏，并可指定哪些 UID 看到原生文件系统（vfs_isolate_uids）。

场景 4：进阶 —— 同一套规则里混用

路径规则 > 模块默认 > 全局默认，三者可以任意搭配。默认配置示例见 module/config.toml：

default_mode = "overlay" # 全局默认 [rules.my_module] default_mode = "magic" # 该模块默认走 magic [rules.my_module.paths] "system/etc/hosts" = "overlay" # 路径规则优先级最高 "system/app/SomeApp" = "ignore" # 模块级/路径级可用 ignore

⚠️ 两条硬约束：

1. 同一文件路径不能同时进入多个后端；
2. VFS 目标与 OverlayFS / Magic Mount 的挂载点不能互为祖先，否则规划阶段直接报PlanConflict。

五、VFS 后端常见疑问 ❓

Q1：内核没有匹配的预编译 .ko，VFS 还能用吗？不能。启动流程会先探测、再尝试加载匹配的随附模块；仍不可用时所有vfs规则降级为ignore（配置vfs_strict = true则启动失败）。你也可以把 module/vfs/ 源码内建进自己的内核，跳过 insmod。

Q2：改了后端配置为什么不生效？配置修改重启后才生效；设备上的配置文件位于/data/adb/hybrid-mount/config.toml。

Q3：两个后端想抢同一个文件会怎样？文件、类型或.replace冲突会在启动规划阶段直接报错，而不是靠"后挂载的遮住先挂载的"来碰运气，避免产生难以排查的静默错误。

Q4：怎么排查 VFS 到底有没有工作？在 root shell 执行/data/adb/modules/hybrid_mount/hybrid-mount vfs doctor，它会报告 Provider 存在方式、协议版本、规则与隔离 UID；命令全表见 docs/VFS_CLI.md。

六、延伸阅读 📚

• 完整中文文档：docs/README_ZH.md
• 启动流水线与代码分层：docs/ARCHITECTURE.md
• 规则优先级与冲突检测实现：src/plan/
• 三后端共享的节点树：src/mount_tree.rs
• VFS 内核子系统细节与运行时 CLI：module/vfs/README.md

一句话总结：求稳选 OverlayFS，轻量精准选 Magic Mount，需要隐形或按 UID 隔离再上 VFS——而 Hybrid Mount 的魅力，恰恰是这三者可以按模块、按路径自由组合。

• 系统编程
• 存储
• 内核驱动