mergerfs 快速入门:从安装到 fstab 与 systemd 的完整挂载配置指南
mergerfs 快速入门:从安装到 fstab 与 systemd 的完整挂载配置指南
本文基于 mergerfs 官方 Quick Start 文档,系统讲解这个多盘位联合文件系统(union filesystem)从安装、推荐配置到实际挂载的全过程。读完本文,你将掌握:如何根据 Linux 内核版本与 mmap 需求选择 cache.files、category.create、func.getattr、dropcacheonclose 四个关键选项组合;如何通过命令行、/etc/fstab、配置文件加符号链接、systemd 服务等多种方式完成持久化挂载;以及 mergerfs 源码中这些选项的实际作用机制。
一、安装准备
快速上手的第一步是确保安装了最新版 mergerfs。由于非滚动发布的发行版(如 Debian、Ubuntu)官方源中的版本往往较旧,官方建议从发布渠道安装对应发行版的预构建包(deb/RPM)、静态二进制或容器镜像。详细的各发行版安装方式(ArchLinux、CentOS/Rocky、Debian/Ubuntu、Fedora、SUSE、FreeBSD、NixOS 等)见 安装文档。
# Debian / Ubuntu 示例
sudo apt install -y mergerfs
# 或从 releases 页下载预构建 .deb 包安装
提示:在报告问题或 Bug 之前,请先升级到最新 release 版本确认问题依然存在。
二、配置理念:没有"最快"的配置,只有改变行为的选项
mergerfs 拥有大量 配置选项,而它们几乎全部是功能性(functional)选项——这一点是理解 mergerfs 配置哲学的关键:
- 不存在"最优"或"最快"的配置组合;
- 不存在单纯的"加速"选项;
- 每个选项改变的都是行为,某些行为改变才会附带影响性能。
因此,除非你明确知道自己有特殊的性能或兼容性需求,官方建议直接使用下面两套经过验证、覆盖常见使用场景的选项组合。
Linux 6.6 及以上内核(auto mmap 可用)
cache.files=off
category.create=pfrd
func.getattr=newest
dropcacheonclose=false
适用前提:cache.files=off 在此内核版本下依然能支持 mmap,因为自 Linux 6.6 起 FUSE 可以在应用请求 mmap 时透明地自动启用 page caching(即"auto mmap"特性)。相应地,mergerfs 侧的 "auto mmap" 支持要求 mergerfs v2.41.0 及以上版本,旧版本请参照下方旧内核配置。
关于 Linux 内核版本、mergerfs 版本与 mmap 之间关系的完整细节,见 已知问题:使用 mmap 的软件。
Linux 6.5 及以下内核
旧内核的 FUSE 支持 mmap 必须以启用 page caching 为前提,即 cache.files 不能设为 off。此时需按是否需要 mmap 二选一:
需要 mmap 支持(如 sqlite3、Plex/Jellyfin/Emby 配置库、qbittorrent 等)
cache.files=auto-full
category.create=pfrd
func.getattr=newest
dropcacheonclose=true
cache.files=auto-full 表示跨 open 缓存文件页,但若文件的 mtime 或 size 发生变化则丢弃缓存;dropcacheonclose=true 则在关闭文件时丢弃缓存,配合使用以控制内存占用与一致性。
不需要 mmap 支持
cache.files=off
category.create=pfrd
func.getattr=newest
dropcacheonclose=false
四个选项在源码中的落点
从源码结构看,这四个选项的作用位置各有不同,理解了它们可以更好地区分参数语义:
cache.files:page caching 模式的枚举选项,实现在 config_cachefiles.hpp / config_cachefiles.cpp,取值包括off、partial、full、auto-full、per-process,详见 caching 文档。注意:启用 page cache 通常会使同一份数据被缓存两次(底层文件系统一次 + mergerfs 一次),因此官方明确指出"启用 page cache 一般损害性能",它存在的意义主要是支撑mmap。另外若启用了passthrough.io,mergerfs 会自动将cache.files设为auto-full,且此时不存在双重缓存。dropcacheonclose:布尔选项,默认false,在 config.cpp 中定义默认值、在 config.cpp 注册选项名;真正生效的位置在文件释放路径 fuse_release.cpp —— 当该值为true时,release回调中会调用缓存丢弃逻辑。category.create=pfrd:create类别(新文件/目录创建)使用的策略为pfrd(path preserving,最满盘优先),实现见 policy_pfrd.hpp。它是推荐组合的一部分,保证新建内容优先落在空间最满的分支上,便于后续统一腾挪。func.getattr=newest:getattr使用newest策略,实现见 policy_newest.hpp。因为getattr的默认策略是ff(first found),当目录的 mtime 在某个分支上更新时,ff返回的可能是其他分支的旧信息;newest保证返回 mtime 最新的分支的元数据(代价是需要扫描所有分支)。这一点与 已知问题中的 directory mtime 一节 相互印证。
三、分支(branches)设置
在挂载之前先了解分支组织方式。branches 文档 给出了分支目录的命名与布局建议(如按 hdd/ssd/nvme/remote 分类、以容量-序列号命名挂载点),并支持在分支路径上用 = 附加模式(RW/RO/NC)与 minfreespace 值,例如 /mnt/hdd/disk0=RW,1234。
分支路径支持 glob 通配(如 /mnt/hdd/*:/mnt/ssd/*),但通过 shell 使用时必须转义 glob 字符,否则 shell 会先行展开。glob 只在挂载时(或经运行时接口更新 branches 时)解析一次,之后新增的目录不会自动纳入。
四、使用方式一:命令行挂载
mergerfs 支持三种等价的位置参数写法:
# 写法 1:两个位置参数 —— `:` 冒号分隔的分支列表 + 挂载点
mergerfs -o opt[,opt...] /mnt/hdd/disk0:/mnt/hdd/disk1:/mnt/hdd/disk2 /media
# 写法 2:一组位置参数 —— 最后一个是挂载点
mergerfs -o opt[,opt...] /mnt/hdd/disk0 /mnt/hdd/disk1 /mnt/hdd/disk2 /media
# 写法 3:用 -o mountpoint 指定挂载点
mergerfs -o mountpoint=/media /mnt/hdd/disk0 /mnt/hdd/disk1 /mnt/hdd/disk2
结合上文推荐配置(以 Linux 6.6+ 为例)的完整命令行:
mergerfs -o cache.files=off,category.create=pfrd,func.getattr=newest,dropcacheonclose=false /mnt/hdd/disk0:/mnt/hdd/disk1:/mnt/hdd/disk2 /media
分支与挂载点的解析最终汇入 mergerfs.cpp 的启动流程,其中挂载点会经过等待挂载与校验(确保目标目录本身不与分支文件冲突)。
五、使用方式二:/etc/fstab 持久化
在 /etc/fstab 中直接写入一行即可实现开机自动挂载:
/mnt/hdd/disk0:/mnt/hdd/disk1:/mnt/hdd/disk2 /media mergerfs cache.files=off,category.create=pfrd,func.getattr=newest,dropcacheonclose=false 0 0
systemd 挂载依赖(推荐)
在 systemd 系统上,只要分支文件系统与 mergerfs 都配置在 /etc/fstab 中,就不需要自定义 service 或启动脚本。做法是在 mergerfs 这一行的挂载选项中,为每个分支挂载目标各追加一次 x-systemd.requires-mounts-for=:
LABEL=disk0 /mnt/hdd/disk0 ext4 defaults 0 2
LABEL=disk1 /mnt/hdd/disk1 ext4 defaults 0 2
LABEL=disk2 /mnt/hdd/disk2 ext4 defaults 0 2
/mnt/hdd/disk0:/mnt/hdd/disk1:/mnt/hdd/disk2 /media mergerfs cache.files=off,category.create=pfrd,func.getattr=newest,dropcacheonclose=false,x-systemd.requires-mounts-for=/mnt/hdd/disk0,x-systemd.requires-mounts-for=/mnt/hdd/disk1,x-systemd.requires-mounts-for=/mnt/hdd/disk2 0 0
实际使用时请把示例中的 LABEL 与文件系统类型替换为你系统真实的值。systemd 会据此从 mergerfs 的 mount 单元生成对 mnt-hdd-disk0.mount、mnt-hdd-disk1.mount、mnt-hdd-disk2.mount 的 Requires= 与 After= 依赖:先启动这些挂载,若任一必需挂载失败则不启动 mergerfs 挂载。注意它检查的是 mount 单元,而不仅仅是 /mnt/hdd/diskN 目录是否存在。
编辑 /etc/fstab 后重新加载生成的单元:
sudo systemctl daemon-reload
依赖关系在下次挂载 /media 时以及后续每次开机时生效。
如果使用 systemd service(见下文)而非 fstab 条目,则在 service 的 [Unit] 段中加入等价指令即可:
RequiresMountsFor=/mnt/hdd/disk0 /mnt/hdd/disk1 /mnt/hdd/disk2
RequiresMountsFor= 同时提供要求(requirement)与顺序(ordering)依赖,无需再为这些挂载单独写 Requires= 和 After=。
Web UI 管理
除了命令行与 fstab,mergerfs-webui 提供了基于浏览器的挂载创建与管理方式,可编辑开机配置,也可检查和修改运行中挂载的选项。注意:仅通过运行时接口做的修改在重新挂载后不会保留,需要写入启动配置才能持久化。
六、使用方式三:/etc/fstab 配合独立配置文件
对于更复杂的部署,把配置从 fstab 中分离出来更清晰。
/etc/fstab
/etc/mergerfs/branches/media/* /media mergerfs config=/etc/mergerfs/config/media.ini
/etc/mergerfs/config/media.ini
cache.files=off
category.create=pfrd
func.getattr=newest
dropcacheonclose=false
# comments and empty lines are supported
/etc/mergerfs/branches/media/ 符号链接分支列表
在 media/ 目录下为每个分支创建一个符号链接即可,mergerfs 会解析符号链接并使用真实路径(符号链接的目标路径也会经过 branches 文档 中描述的 glob 展开 + realpath 规范化流程):
ls -lh /etc/mergerfs/branches/media/*
lrwxrwxrwx 1 root root 14 Aug 4 2023 disk0 -> /mnt/hdd/disk0
lrwxrwxrwx 1 root root 14 Aug 4 2023 disk1 -> /mnt/hdd/disk1
lrwxrwxrwx 1 root root 14 Aug 4 2023 disk2 -> /mnt/hdd/disk2
这种"符号链接 + glob"组合是官方推荐的便捷分支配置手法,新增/移除分支只需增删一个符号链接。
七、使用方式四:systemd service
简单版 service
/etc/systemd/system/mergerfs-media.service:
[Unit]
Description=mergerfs /media service
RequiresMountsFor=/mnt/hdd/disk0 /mnt/hdd/disk1 /mnt/hdd/disk2
After=local-fs.target network.target
[Service]
Type=simple
KillMode=none
ExecStart=/usr/bin/mergerfs \
-f \
-o cache.files=off \
-o category.create=pfrd \
-o func.getattr=newest \
-o dropcacheonclose=false \
/mnt/hdd/disk0 \
/mnt/hdd/disk1 \
/mnt/hdd/disk2 \
/media
ExecStop=/usr/bin/umount /media
# Or if you need fusermount
# ExecStop=/usr/bin/mergerfs-fusermount -u /media
Restart=on-failure
[Install]
WantedBy=default.target
要点说明:
-f前台运行,配合 systemd 的Type=simple作为主进程管理;KillMode=none避免 systemd 在停止时误杀导致挂载点残留(mergerfs 正常退出前会处理自身卸载,必要时 mergerfs.cpp 中还有lazy_umount_mountpoint的 lazy umount 兜底);ExecStop显式umount /media;无 root 权限场景可改用mergerfs-fusermount -u。
带前置 setup 脚本的 service
如果你需要在挂载 mergerfs 之前执行一些准备工作(例如等待网络存储就绪),官方给出了一个少有人写但很有参考价值的 notify 模式示例。
/usr/local/bin/setup-for-mergerfs
#!/usr/bin/env sh
# Perform setup
/bin/sleep 10
# Report back to systemd that things are ready
/bin/systemd-notify --ready
/etc/systemd/system/setup-for-mergerfs.service
[Unit]
Description=mergerfs setup service
[Service]
Type=notify
RemainAfterExit=yes
ExecStart=/usr/local/bin/setup-for-mergerfs
[Install]
WantedBy=default.target
/etc/systemd/system/mergerfs-media.service
[Unit]
Description=mergerfs /media service
RequiresMountsFor=/mnt/hdd/disk0 /mnt/hdd/disk1 /mnt/hdd/disk2
Requires=setup-for-mergerfs.service
After=local-fs.target network.target setup-for-mergerfs.service
[Service]
Type=simple
KillMode=none
ExecStart=/usr/bin/mergerfs \
-f \
-o cache.files=off \
-o category.create=pfrd \
-o func.getattr=newest \
-o dropcacheonclose=false \
/mnt/hdd/disk0 \
/mnt/hdd/disk1 \
/mnt/hdd/disk2 \
/media
ExecStop=/usr/bin/umount /media
# Or if you need fusermount
# ExecStop=/usr/bin/mergerfs-fusermount -u /media
Restart=on-failure
[Install]
WantedBy=default.target
机制上:setup 服务以 Type=notify 启动,脚本执行完成后调用 systemd-notify --ready 通知 systemd 准备就绪;RemainAfterExit=yes 使其退出后仍保持 active 状态;mergerfs-media.service 通过 Requires= + After= 保证在 setup 完成后才启动。
八、快速自查清单
- [ ] 确认 mergerfs 为最新版本(安装文档),并核对 Linux 内核版本以选择正确的
cache.files组合; - [ ] 确认所用软件(sqlite3 系、qbittorrent 等)是否需要
mmap,必要时按旧内核"需要 mmap"组合配置; - [ ] fstab 条目中已为每个分支添加
x-systemd.requires-mounts-for=,或 service 中已写RequiresMountsFor=; - [ ] 修改 fstab 后已执行
sudo systemctl daemon-reload; - [ ] 运行时修改过的选项已知晓不会跨重挂载保留,需同步写入启动配置。
更多选项语义(minfreespace、moveonenospc、passthrough.io、statfs 等)可继续在 config 目录 下按主题文档深入阅读。