mergerfs 故障排查与支持指南：从 collect-info、strace 到 gdb 的高质量 Bug 报告实践

• 存储

文件系统与上层应用的交互极其复杂，union 文件系统（如 mergerfs）的故障排查更是如此。本文围绕 mergerfs 官方支持文档 mkdocs/docs/support.md 的核心要求，完整讲解如何收集诊断信息、如何使用mergerfs.collect-info等内置工具、如何用strace与gdb定位卡死与阻塞问题，并给出结合运行时接口自查配置的完整流程。读完本文，你将掌握一套可复制的标准支持诊断流程，能够产出让维护者一眼看懂的高质量 Bug 报告，显著提升问题被修复的概率。

为什么文件系统问题难以排查

文件系统是操作系统与存储硬件之间的桥梁，任何一层（内核、驱动、文件系统实现、上层应用、网络、容器）出现问题都可能表现为"mergerfs 出问题了"。同时，文件系统层面的操作高频且微小，日志往往无法覆盖全部细节。因此，mergerfs 官方在提交问题时明确要求：请尽可能多地包含下列信息，否则问题将难以甚至无法诊断；同时务必先阅读 mkdocs/docs/faq/why_isnt_it_working.md 与 mkdocs/docs/error_handling_and_logging.md，大量此前遇到过的疑问与已知问题都已有解答。

第一步：确保使用的是最新版本

诊断的起点不是收集信息，而是确认版本。mergerfs 官方特别强调：

• 请使用 最新发布版本（或至少与最新版本对比验证），发行版（如 Debian、Ubuntu）自带的 mergerfs 往往是旧版本，永远不会再被更新，你遇到的问题可能早已在后续版本中修复；
• 报告问题时，请同时提供mergerfs --version的输出（该信息也会被mergerfs.collect-info自动收集）。

从源码结构看，src/mergerfs_collect_info.cpp 会调用mergerfs --version并把结果写入收集文件，这正是为了让维护者第一时间核对版本。

Bug 报告中必须包含的信息清单

官方支持文档要求报告者至少提供以下信息，每一项都有其明确目的。

1. 问题的更广泛背景与已尝试的解决方案

• 描述更广泛的问题场景，而不仅仅是表面症状，以及你尝试过的解决思路；
• 列出已经排除掉的方案及其排除原因，避免维护者重复你已经走过的弯路。

2. mergerfs.collect-info 的输出（关键）

这是收集系统与配置细节的官方工具，随近期版本的 mergerfs 一同发布，专门用于辅助 support。用法如下：

$ mergerfs.collect-info * Please have mergerfs mounted before running this tool. * Upload the following file to your GitHub ticket or put on https://pastebin.com when requesting support. * /tmp/mergerfs.info.txt

要点：

• 必须先挂载 mergerfs 再运行该工具——它依赖挂载点上的运行时接口来读取配置；
• 输出统一写入/tmp/mergerfs.info.txt，将该文件随 Bug 报告一起提交即可。

从 src/mergerfs_collect_info.cpp 的源码可以看到它实际收集了哪些数据，每一段都对应一个诊断维度：

该工具的实现方式是逐个调用系统命令并把输出附加到收集文件（src/mergerfs_collect_info.cpp），同时通过 mergerfs 运行时接口的allpaths获取每个挂载点对应的全部分支路径并逐一stat（src/mergerfs_collect_info.cpp）。因此该文件已经覆盖了"分支根"级别的权限信息，但分支内部文件/目录的权限仍需自行补充。

3. 相关路径与文件的全部信息

工具只收集分支根级别的信息，因此你还需手工补充所有相关路径与文件的细节：

• 权限（mode）、属主（uid/gid）、类型（目录/文件/符号链接）；
• 可通过ls -l、stat、getfacl等命令获取；
• 若怀疑权限问题，可先用 fsck.mergerfs 自查（见下文）。

4. 发起请求的应用信息

• 应用的版本号，以及它以哪个uid/gid运行；
• 尽量先用系统核心工具（ln、mv、cp、ls、dd等）复现，排除应用自身因素。

5. 用最简单的方式最小化复现

官方建议用最简配置复现问题，例如：

• 只用单个分支、且该分支使用受良好支持的文件系统；
• 必要时降为单线程（-o threads=1，对应 config/options.md 中的read-thread-count）；
• 使用标准程序逐步复现，缩小排查范围。

这种"最小化复现"思路也体现在测试套件中——仓库的 tests/ 下大量测试（如TEST_posix_open_read_write、TEST_posix_xattr）正是针对单一操作语义的最小验证。

6. 运行环境说明

• mergerfs 本身是否运行在容器中？
• 使用 mergerfs 的客户端应用是否运行在容器中（如 Docker/Podman）？
• 容器场景下，rename 与 link 无法跨设备工作，这是高频误报点。

7. 对出问题应用的 strace

捕获应用发起的每一次系统调用，定位是哪个调用、返回了什么错误：

strace -fvTtt -s 256 -o /tmp/app.strace.txt <cmd>

参数含义：-f跟踪子进程、-v输出完整信息、-T显示每次调用的耗时、-t打印时间戳、-s 256扩大字符串输出长度、-o指定输出文件。

8. 对 mergerfs 的 strace（关键）

分别在问题发生前和问题发生时两个阶段抓取 mergerfs 进程的调用：

strace -fvTtt -s 256 -p <mergerfsPID> -o /tmp/mergerfs.strace.txt

-p <mergerfsPID>表示 attach 到已运行的 mergerfs 进程。这份跟踪可以揭示 mergerfs 在哪些底层调用上等待、返回了什么错误，是区分"内核层问题"与"mergerfs 自身问题"的最直接证据。

9. 阻塞 / 卡死时的 gdb 堆栈

如果 mergerfs 出现阻塞或疑似卡死，用 gdb 抓取全线程堆栈：

gdb -q --batch -ex "set pagination off" -ex "thread apply all bt full" -ex quit --pid <mergerfsPID> > /tmp/mergerfs.stacktrace.txt

参数含义：--batch非交互执行、-ex "set pagination off"关闭分页避免截断、-ex "thread apply all bt full"对所有线程执行完整回溯（含局部变量）、-ex quit抓取后立即退出，输出重定向到文件。堆栈能直接显示 mergerfs 阻塞在哪个系统调用或锁上。

10. 精确的逐步复现步骤

最后，附上精确到每一步的复现步骤，不要省略任何细节——包括目录结构、挂载参数、执行的每条命令。

借助运行时接口先自查配置

很多"Bug"其实是配置与预期不符。在提交报告前，先用运行时接口确认当前生效的配置，能省去大量来回沟通。mergerfs 通过挂载点下的伪文件/.mergerfs暴露运行时 xattr 接口，详见 runtime_interface.md。

查看全部配置键：

$ getfattr -d /mnt/mergerfs/.mergerfs user.mergerfs.branches="/mnt/hdd/disk0=RW:/mnt/hdd/disk1=RW" user.mergerfs.minfreespace="4294967295" user.mergerfs.moveonenospc="false" ...

检查 create 策略是否符合预期：

$ sudo getfattr -n user.mergerfs.category.create /mnt/mergerfs/.mergerfs user.mergerfs.category.create="mfs"

查询文件实际落在哪个分支：

$ sudo touch /mnt/mergerfs/new-file $ sudo getfattr -n user.mergerfs.allpaths /mnt/mergerfs/new-file user.mergerfs.allpaths="/mnt/hdd/disk0/new-file"

这套自查方法在官方 FAQ 中也被推荐（why_isnt_it_working.md）：先确认策略配置，再用touch创建文件并查询allpaths，即可判断文件落点是否符合策略预期。例如"所有文件都堆在同一个盘"通常并非 Bug，而是ep*（existing path）策略的预期行为——该类策略在设计上就倾向于保持目录布局（why_isnt_it_working.md）。

日志与调试模式：抓取 FUSE 消息踪迹

syslog 常规日志

即使不开调试模式，mergerfs 也会通过 syslog 记录部分关键事件。在 systemd 系统上可用：

journalctl -t mergerfs

-t mergerfs按 syslog 标识过滤。从源码看，mergerfs 内置的 syslog 封装以"mergerfs"作为openlog标识、LOG_USERfacility，并提供info/debug/notice/warning/error/alert/crit分级接口（vendored/libfuse/include/syslog.hpp）。mergerfs.collect-info也会抓取最近 60 分钟的journalctl -t mergerfs输出附入报告（src/mergerfs_collect_info.cpp）。

调试模式与 log.file

文件系统在高速执行海量小操作，不可能始终记录全部动作。因此 mergerfs 提供可按需开启（甚至运行时切换）的调试模式，核心内容是所有 FUSE 消息的踪迹，写入由log.file选项指定的位置：

• debug：true/false，默认false。开启后记录 FUSE 消息踪迹；
• log.file：踪迹输出文件路径，空字符串表示输出到 stderr，默认 stderr。

两个选项的完整说明见 config/options.md。从源码看，开启 debug 时会确保输出目标已设置：若有log.file则写入该文件，否则回退到 stderr（src/config_debug.cpp）；设置log.file会调用fuse_debug_set_output切换输出目标（src/config_log_file.cpp）。FUSE 消息踪迹的具体输出逻辑位于 vendored/libfuse/lib/debug.cpp，涵盖init、attr、entry、readlink、write、statfs、getxattr、ioctl等各类 FUSE 消息。

权限类问题的自助修复：fsck.mergerfs

如果你"看不到文件/目录"，几乎总是权限问题。与 mhddfs、unionfs-fuse 以 root 身份访问内容不同，mergerfs始终切换到调用者的凭据执行操作，这是唯一安全的权限管理方式——用户无权限访问的文件，mergerfs 同样无法访问。于是各分支权限不一致会导致只能看到部分文件。

此时可使用fsck.mergerfs诊断并修复池中的权限/属主不一致问题（详见 tooling.md）：

$ fsck.mergerfs --help fsck.mergerfs: A tool to help diagnose and solve mergerfs pool issues USAGE: fsck.mergerfs [OPTIONS] path POSITIONALS: path TEXT:DIR REQUIRED mergerfs path OPTIONS: -h, --help Print this help message and exit --fix TEXT:{none,manual,newest,largest} [none] Will attempt to 'fix' the problem by chown+chmod or copying files based on a selected file. * none: Do nothing. Just print details. * manual: User selects source file. * newest: Use file with most recent mtime. * largest: Use file with largest size. --check-size BOOLEAN [false] Considers file size in calculating differences --copy-file BOOLEAN [false] Copy file rather than chown/chmod to fix

各选项含义：

• path：必填的 mergerfs 挂载路径（必须是已存在目录）；
• --fix：修复策略，none仅输出差异详情（默认）、manual由用户选择源文件、newest采用 mtime 最新的文件、largest采用体积最大的文件；
• --check-size：在计算差异时把文件大小也纳入比较；
• --copy-file：以复制文件的方式修复（而非 chown/chmod），仅对普通文件有效。

从 src/mergerfs_fsck.cpp 的源码可以看出它的判定逻辑：逐项对比各副本的st_mode、st_uid、st_gid，并在开启check_size时对普通文件追加st_size比较；类型不一致（如一个是目录一个是文件）时拒绝自动修复并要求人工介入（src/mergerfs_fsck.cpp）。newest与largest分别通过比较 mtime 纳秒精度与文件大小选取源文件（src/mergerfs_fsck.cpp）。另外，从源码看，非 root 运行且指定了非none的修复策略时会输出警告"should be run as root to apply fixes"（src/mergerfs_fsck.cpp），因此修复操作请以 root 执行。

分支消失 / 不可见时的行为与保护措施

"某个分支的文件系统消失/被卸载"在 mergerfs 中不是错误条件。mergerfs 操作的是路径而非挂载点，它不会主动检查分支路径是否仍处于挂载状态，也不会持有会阻止卸载的文件描述符。文件系统消失后，mergerfs 照常工作——就像该路径从未挂载过一样；若分支路径不存在，策略会直接跳过该分支（详见 error_handling_and_logging.md)。

如果希望在底层文件系统消失时阻止该分支路径继续被使用，官方给出的技巧是让目录"难以或无法使用"：

chown root:root /mnt/mountpoint/ chmod 0000 /mnt/mountpoint/ chattr +i /mnt/mountpoint/

注意：chattr +i仅在部分文件系统上有效，主要是ext4。目录仍可被挂载，但任何人都无法向其写入（包括 root）。

提交渠道与顺序

官方支持文档给出的联系 / 提交渠道（按优先级排列）：

1. GitHub Issues（mergerfs 官方仓库的 issues 页面）——报告 Bug 的首选渠道，请附上mergerfs.collect-info生成的/tmp/mergerfs.info.txt内容或文件；
2. Discord社区频道——适合快速问答与交流；
3. Reddit的r/mergerfs社区——适合讨论使用经验与方案。

另外，商业支持或功能需求可直接联系项目作者（官方邮箱见 support.md）。

结语：一份高质量报告应有的样子

综合官方支持文档的全部要求，一份合格的 mergerfs Bug 报告应当包含：最新版本号的确认、mergerfs.collect-info输出（/tmp/mergerfs.info.txt）、相关路径与文件的权限/属主细节、应用版本与 uid/gid、最小化复现步骤、运行环境（容器与否）、应用与 mergerfs 两个层面的strace、阻塞场景下的 gdb 全线程堆栈，以及你已排除的方案。在提交前，建议先用 runtime_interface.md 的自查命令（getfattr -d /.mergerfs、getfattr -n user.mergerfs.allpaths等）确认配置与落点符合预期，再用 fsck.mergerfs 排除权限不一致，最后按官方模板提交。这一流程不仅能大幅提高维护者复现与修复的效率，也能让普通用户在多数场景下自行定位并解决问题。

• 存储