mergerfs 快速入门:从安装到 fstab 与 systemd 的完整挂载配置指南

原创2026-10-09 14:52:361,947 阅读
文章标签:存储

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 目录 下按主题文档深入阅读。

登录后查看全文
mergerfs