bazil.org/fuse 文档工作流：用 seqdiag 与 reflex 自动化维护 FUSE 挂载时序图

导读

FUSE 文件系统开发中，"内核态与用户态如何完成挂载握手"一直是理解难度最高的环节之一，而 bazil.org/fuse 作为 Go 语言生态中久经考验的 FUSE 库，其 文档目录 用一组 seqdiag 时序图把 Linux 与 OS X 上成功/失败两条路径画得清清楚楚。本篇文章以 depends/bazil.org/fuse/doc/writing-docs.md 为骨架，完整讲解这套文档的生成工具链（seqdiag + reflex 自动重建工作流）、SVG/PNG 双格式输出策略，并逐帧解读仓库内四份 .seq 源文件与配套的 挂载时序说明，最后落到 mount_linux.go 等源码上，验证图中每一步在实现中的真实对应关系。读完本文，你将掌握一套可直接复用的"时序图文档自动化"方法，同时彻底搞懂 FUSE 挂载为何在 Linux 与 macOS 上行为迥异。

1. 这套时序图要解决什么问题：FUSE 挂载时序的背景

1.1 为什么挂载时序需要专门画图

depends/bazil.org/fuse/doc/mount-sequence.md 开宗明义地指出：FUSE 挂载是个"有点棘手"（a little bit tricky）的过程。它涉及一个用户态的辅助工具（mount helper，Linux 上是 fusermount，OS X 上是 mount_osxfusefs），该工具负责与内核完成握手，随后立刻"退到一边"（steps out of the way）。而这个 helper 在不同平台上的行为差异，直接逼迫上层 API 变得更复杂：

• Linux 上，Mount 返回时挂载"立即生效"，文件系统访问会一直等到请求被服务；
• OS X 上，挂载要等 InitRequest（甚至更多请求）被处理之后才对外可见。

这种平台差异无法从单一 API 签名中看出，只有时序图能把"谁先谁后、谁在等谁"直观呈现。这正是 bazil.org/fuse 文档体系选择用 seqdiag 维护一组专用时序图的根本原因。

1.2 文档目录结构

仓库中 depends/bazil.org/fuse/doc/ 下的完整文件构成如下：

文件	作用
README.md	文档索引，列出挂载时序与文档编写说明两篇
mount-sequence.md	挂载时序的文字解说（成功/失败两条路径 × Linux/OS X 两个平台）
writing-docs.md	本文主题：时序图的生成与自动维护方法
mount-linux.seq / .png	Linux 成功挂载时序图源文件与渲染图
mount-osx.seq / .png	OS X 成功挂载时序图源文件与渲染图
mount-linux-error-init.seq / .png	Linux 下 InitRequest 返回错误时的时序
mount-osx-error-init.seq / .png	OS X 下 InitRequest 返回错误时的时序

可以看到，文字说明（.md）与图形源文件（.seq）一一对应，图形是这套文档的主体，writing-docs.md 则是维护它们的方法论。

2. 文档生成工具链：seqdiag 与 reflex

depends/bazil.org/fuse/doc/writing-docs.md 全文只有 16 行，却浓缩了整套文档工程化的三个要点：

2.1 图形工具：seqdiag

The sequence diagrams are generated with seqdiag: http://blockdiag.com/en/seqdiag/index.html

时序图由 seqdiag 生成。seqdiag 是 blockdiag 家族的一员，采用 Python 编写，输入是类 DOT 语法的 .seq 文本文件，输出可以是 PNG、SVG 等多种格式。它非常适合"画进版本库、随代码演进"的文档场景：源文件是纯文本，可 diff、可 review，渲染结果可重现。

2.2 自动重建工作流：reflex 监听文件变更

原文档给出的核心方法，是用 cespare/reflex（一个 Go 编写的文件变更监听与命令重启工具）监听 .seq 源文件的改动，自动重新渲染：

reflex -g 'doc/[^.]*.seq' -- seqdiag -T svg -o '{}.svg' '{}' &

reflex -g 'doc/[^.]*.seq' -- seqdiag -T png -o '{}.png' '{}' &

逐项拆解这两条命令：

• -g 'doc/[^.]*.seq'：reflex 的 glob 过滤规则。[^.]* 表示"不以点开头的任意文件名"，即排除了 mount-linux.seq.png 这类已渲染产物与隐藏文件，只匹配 doc/ 目录下的 .seq 源文件（仓库中即 mount-linux.seq、mount-osx.seq、mount-linux-error-init.seq、mount-osx-error-init.seq 四个）；
• -- 之后是文件变更时实际执行的命令：seqdiag -T svg -o '{}.svg' '{}'；
• '{}' 是 reflex 的占位符，会被替换为发生变更的具体文件名，例如 doc/mount-linux.seq，于是命令展开为 seqdiag -T svg -o doc/mount-linux.seq.svg doc/mount-linux.seq；
• 两条命令分别处理 SVG 与 PNG 两种输出格式，并行以后台方式（&）常驻。开发者在编辑器中保存一次 .seq，两套图即自动更新，完全无需手动跑渲染命令。

这条工作流的精髓在于：把"画图"从一次性劳动变成文档维护闭环——改源文件 → 自动重渲染 → 提交双格式产物。

2.3 为什么 markdown 里引用 PNG 而不是 SVG

The markdown files refer to PNG images because of Github limitations, but the SVG is generally more pleasant to view.

原文档特别说明了双格式策略：markdown 正文引用 PNG，原因是 GitHub 渲染 markdown 时对图片格式的支持限制；而 SVG 观感更佳（矢量、可缩放、在本地浏览器打开更清晰），因此保留一份供本地查看。仓库中实际渲染的 PNG 图片均以 .seq.png 命名存在于 doc 目录 下，与 .seq 源文件成对出现，正是上述两条 reflex 命令的输出结果。

3. 仓库内四份 .seq 源文件逐帧解析

为了让读者真正掌握这套文档的写法，下面直接解读仓库中的时序图源文件（它们就是 seqdiag 的输入样例）。

3.1 参与者与基础语法

以 mount-linux.seq 为例，源文件结构如下：

seqdiag {
  app;                        // 参与者：调用方应用
  fuse [label="bazil.org/fuse"];   // 参与者：库本身，可自定义标签
  fusermount;                 // 参与者：用户态挂载辅助工具
  kernel;                     // 参与者：内核
  mounts;                     // 参与者：挂载表

  app -> fuse [label="Mount"];                 // 同步调用箭头
  fuse -> kernel [label="write /dev/fuse fd"]; // 带标签的箭头
  ... repeat ...                               // 循环省略写法
}

seqdiag 语法要点：

• 顶部先声明所有参与者（actor），可用 [label="..."] 重命名显示名，例如把包名 fuse 显示为 bazil.org/fuse；
• A -> B [label="..."] 表示从 A 到 B 的调用，label 标注消息内容；
• A <-- B 表示返回路径，A ->> B 是异步/非阻塞消息（图中用于表示"挂载对内核可见"这个异步事件）；
• [diagonal] 控制箭头的斜线样式，[note="..."]、[leftnote="..."]、[rightnote="..."] 在箭头旁附加说明框；
• [color=red] 标注出错路径；
• ... repeat ... 表示循环重复的消息段。

3.2 Linux 成功挂载：mount-linux.seq

该图完整描述了一次成功的 Linux 挂载生命周期：

app -> fuse [label="Mount"];
fuse -> fusermount [label="spawn, pass socketpair fd"];
fusermount -> kernel [label="open /dev/fuse"];
fusermount -> kernel [label="mount(2)"];
kernel ->> mounts [label="mount is visible"];
fusermount <-- kernel [label="mount(2) returns"];
fuse <<-- fusermount [diagonal, label="exit, receive /dev/fuse fd",
  leftnote="on Linux, successful exit here means the mount has happened,
            though InitRequest might not have yet"];
app <-- fuse [label="Mount returns\nConn.Ready is already closed",
  rightnote="InitRequest and StatfsRequest may or may not be seen
             before Conn.Ready, depending on platform"];

关键语义：

1. Mount 调用启动后，库 spawn 出 fusermount 子进程，并通过 socketpair 传递文件描述符（源码验证见 mount_linux.go，其中 syscall.Socketpair(syscall.AF_FILE, syscall.SOCK_STREAM, 0) 创建通信对，_FUSE_COMMFD=3 环境变量把写端 fd 传给子进程）；
2. fusermount 打开 /dev/fuse、发起 mount(2) 系统调用，挂载对内核（挂载表）立即可见；
3. fusermount 通过 socket 把 /dev/fuse 的文件描述符传回父进程（ReceiveSocketControlMessage，源码中 ReadMsgUnix + ParseSocketControlMessage + ParseUnixRights 三步，见 mount_linux.go）后退出；
4. 图中的 leftnote 点明 Linux 的关键特性：fusermount 成功退出即代表挂载已完成，尽管此时 InitRequest 可能尚未处理；
5. Mount 返回时 Conn.Ready 通道已经关闭，但 InitRequest/StatfsRequest 是否在 Conn.Ready 之前被看到，因平台而异——这是 bazil.org/fuse 面向调用方给出的确定性契约。

随后进入服务阶段：app -> fuse [label="fs.Serve"] 后，库从 /dev/fuse 读请求（从 InitRequest 开始），回调应用实现的 FS/Node/Handle 方法，再把响应写回内核，如此循环（... repeat ...）。

3.3 Linux 错误路径：mount-linux-error-init.seq

该图演示 InitRequest 返回错误时的情况：

app -> fuse [label="fs.Serve"];
fuse => kernel [label="read /dev/fuse fd", note="starts with InitRequest"];
fuse -> app [label="Init"];
fuse <-- app [color=red];
fuse -> kernel [label="write /dev/fuse fd", color=red];
kernel -> kernel [label="set connection state to error", color=red];
... conn.MountError == nil, so it is still mounted ...
... call conn.Close to clean up ...

要点：在 Linux 上，InitRequest 出错并不会导致挂载消失——挂载点依然存在，只是此后所有操作都会失败；conn.MountError 为 nil，说明连接仍处于挂载状态，需要调用方主动 conn.Close 清理。这印证了 mount-sequence.md 的结论："On Linux, the mountpoint is there but all operations will fail"。

3.4 OS X 成功与失败路径：mount-osx.seq 与 mount-osx-error-init.seq

OS X 的实现与 Linux 截然不同，mount-osx.seq 揭示了两个关键差异：

app -> fuse [label="Mount"];
fuse -> kernel [label="open /dev/osxfuseN"];
fuse -> mount_osxfusefs [label="spawn, pass fd"];
fuse -> wait [label="goroutine", note="blocks on cmd.Wait"];
app <-- fuse [label="Mount returns"];
mount_osxfusefs -> kernel [label="mount(2)"];
... kernel ->> mounts [label="mount is visible"] ...
mount_osxfusefs <-- kernel [label="mount(2) returns"];
wait <<-- mount_osxfusefs [diagonal, label="exit",
  leftnote="on OS X, successful exit here means we finally know the mount
            has happened (can't trust InitRequest, kernel might have timed out
            waiting for InitResponse)"];
app <<-- wait [diagonal, label="mount is ready, close Conn.Ready",
  rightnote="InitRequest and StatfsRequest may or may not be seen
             before Conn.Ready, depending on platform"];

• 设备节点不同：打开的是 /dev/osxfuseN（N 为实例号）而非 /dev/fuse；
• 挂载点出现时机不同：mount(2) 返回后，挂载才在 mounts 中可见；而在 Mount 返回之后、InitRequest 服务期间，内核还会先发出两次 StatfsRequest（图注 "also seen before mount exits: two StatfsRequest calls"）；
• "挂载已就绪"的判定标准：不能信任 InitRequest 的响应——因为内核可能因等待 InitResponse 而超时，必须等 mount_osxfusefs 进程成功退出，才由后台 wait goroutine（阻塞在 cmd.Wait 上）关闭 Conn.Ready。这也是 mount-sequence.md 所说"OS X 挂载在 InitRequest 被服务后才可见"的底层原因。

mount-osx-error-init.seq 则展示：OS X 上 InitRequest 出错时，mount(2) 返回失败、helper 退出、wait goroutine 以失败状态关闭 Conn.Ready，此时 conn.MountError != nil，挂载从未发生（"the mount never happened"）。

4. 源码佐证：时序图背后的真实实现

时序图不是凭空画的，bazil.org/fuse 的实现与图一一对应。以下关键证据可以帮助读者把图"翻译"回代码：

4.1 Linux：socketpair + fusermount 子进程（mount_linux.go）

• mount() 函数第一行即 close(ready)——对应图中"Mount returns, Conn.Ready is already closed"以及注释 "linux mount is never delayed"（mount_linux.go），从源码层面确认了 Linux 挂载不被延迟的特性；
• syscall.Socketpair 创建匿名 socketpair，写端作为 ExtraFiles 传给 fusermount，读端用于接收回传的 /dev/fuse fd——对应图中 spawn, pass socketpair fd → exit, receive /dev/fuse fd 两段；
• 对 fusermount stderr 的解析（handleFusermountStderr）把常见的 fusermount: failed to access mountpoint ...: No such file or directory 转换为类型化的 MountpointDoesNotExistError，并把 Permission denied 这类噪音静默——说明挂载失败时的错误信息也走时序图之外的"错误处理"逻辑。

4.2 统一的错误与卸载入口

• mount.go 定义了 ErrOSXFUSENotFound（OS X 上未检测到 OSXFUSE 安装时返回）以及 lineLogger（把 helper 的 stdout/stderr 逐行写入日志）；
• unmount.go 与 unmount_linux.go 对应图中"关闭阶段"：Linux 走 fusermount -u，OS X 走 umount(2)，随后库读到 /dev/fuse 的 EOF，fs.Serve 返回，调用方 conn.Close 关闭 fd。

4.3 测试与示例印证

仓库还提供了可运行的验证材料：

• fs/serve_test.go 与 fs/serve_darwin_test.go 分别覆盖两个平台的服务端行为；
• fs/fstestutil/mounted.go 提供测试用挂载辅助设施，fs/fstestutil/mountinfo_linux.go 用于核对挂载表信息——正是时序图中 mounts 参与者的测试对应物；
• 最直观的入门示例是 examples/hellofs/hello.go：实现 fs.FS/fs.Node 接口后即可体验"Mount → fs.Serve → 内核请求回调"的完整生命周期。

5. 实战指南：把这套工作流迁移到你的项目

5.1 落地步骤

1. 安装工具：pip install seqdiag（Python 环境）；安装 reflex（Go 环境：go install github.com/cespare/reflex@latest 或从 release 下载二进制）；
2. 建立 doc/*.seq 源文件：参照 mount-linux.seq 的语法声明参与者、消息与注释；
3. 启动自动渲染：在仓库根目录运行原文档中的两条 reflex 命令（注意 glob 模式要匹配你的目录结构，如 doc/[^.]*.seq）；
4. 提交双格式产物：mount-linux.seq 与 mount-linux.seq.png（以及可选的 .svg）一并纳入版本控制；
5. 在 markdown 中引用 PNG：如 mount-sequence.md 所示，用 描述性 alt 文本 插入，避免依赖外部图片托管。

5.2 写时序图时的关键纪律（来自仓库实践的提炼）

• 给每个异步边界加 note：Linux 的 leftnote（helper 退出=挂载完成）与 OS X 的 leftnote（不能信任 InitRequest）这类说明，是读者理解平台差异的核心，务必写进图里而不是只写在正文里；
• 错误路径单独成图：仓库将 *-error-init.seq 独立成文件，便于聚焦"InitRequest 出错后连接状态如何变化"（MountError 是否非 nil、挂载是否保留）；
• 用 ... repeat ... 表示服务循环，保持图面简洁，聚焦握手阶段；
• 把"何时知道挂载成功"画成显式事件：这是整套图最有价值的信息——Linux 靠 helper 退出，OS X 靠 helper 退出 + Conn.Ready 关闭，两条路径对比一目了然。

6. 总结

depends/bazil.org/fuse/doc/writing-docs.md 用 16 行文字定义了一套完整的"时序图文档自动化"工作流：seqdiag 负责把 .seq 文本渲染成图，reflex 负责监听变更自动重建，PNG 供 GitHub 渲染、SVG 供本地细看。而它服务的 挂载时序说明 与四份 .seq 源文件，则把 FUSE 挂载中最容易踩坑的"平台差异"讲得明明白白：Linux 挂载即时生效、InitRequest 失败也不卸载；OS X 挂载延迟可见、成败以 helper 退出为准。配合 mount_linux.go 中 close(ready)、socketpair、ReadMsgUnix 等实现细节，图与代码互相印证，既是一份高质量的 FUSE 原理资料，也是一套可以原样迁移到任何需要"图片级文档"项目的工程实践。