Flea 文件管理器架构全景:Rust 后端与 Quickshell 前端如何靠 JSON 行协议高效协作

原创2026-10-26 16:53:201,632 阅读

Flea 文件管理器架构全景:Rust 后端与 Quickshell 前端如何靠 JSON 行协议高效协作

Flea 是一个面向 Linux 的极速文件管理器,为 Omarchy 桌面而生,主打键盘优先的操作体验。它的界面由 Quickshell(基于 Qt/QML)绘制,而所有文件读写、缩略图与传输都交给独立的 Rust 后端进程完成,两者之间只通过一种极简的 JSON 行协议通信——一行一个 JSON 对象。本文带你从架构全景看懂这套前后端分工、协议细节,以及它如何让十万个文件的大目录依然流畅。

一、为什么文件管理器要"前后端分离"

GUI 程序最常见的卡顿原因:界面线程顺手做了磁盘 IO。目录一多、网络一慢,窗口就开始掉帧。

Flea 的答案很直接:进程级隔离。

  • Rust 后端:负责一切重活——目录扫描、stat、排序、搜索、缩略图、拷贝/移动/删除、撤销日志
  • Quickshell 前端:只负责渲染和输入——列表、网格、列视图、标签页,以及把按键翻译成语义化请求
  • 两者之间没有共享内存、没有复杂 IPC,只有 stdin/stdout 上的文本行

整个 Flea 是同一个 Rust 二进制里的不同运行模式:flea --gui 启动图形界面(内部直接 exec Quickshell),flea --backend 进入后端主循环,flea --thumb-worker 则是沙箱里的缩略图工人。入口分发表在 src/main.rs,Quickshell 的启动逻辑在 src/gui.rs。

二、架构全景:一个二进制,多种角色

组件 技术 主要位置
启动器 / 模式分发 Rust src/main.rs
前端界面 QML + JS ui/ 目录,200+ 个 QML 与 150+ 个 JS 文件
前后端桥 QML ui/Backend.qml
后端主循环 Rust src/backend/ 目录,280 个 Rust 源文件
协议解析 Rust src/backend/proto.rs + src/json.rs

Flea 文件管理器列视图

上图是 Flea 的列视图(Columns):点击一个文件夹,右侧列通过一条 peek 请求多拉一列数据,而不必重新加载整个窗口。

三、JSON 行协议:一行一个 JSON 对象

协议的全部规则可以浓缩成一句话(引自 docs/protocol.md):

一行一个 JSON 对象,换行分隔,走 flea --backend 子进程的 stdin 与 stdout。没有批量、没有长度前缀。

前端用 Quickshell 的 Process 拉起后端,并用 SplitParser 按 \n 切分 stdout,见 ui/Backend.qml;后端用 src/backend/proto.rs 中的 parse_request 逐行解析请求,由 src/backend/run.rs 分发到各功能模块。

一次"打开目录"的完整往返长这样:

前端 → 后端(请求)

{"c":"list","path":"/home/gm","first":350,"hidden":false}

后端 → 前端(响应,两行)

{"t":"listed","n":100000,"read":26.400,"sort":2.500,"v":56,"w":true,"path":"/home/gm"}
{"t":"rows","start":0,"rows":[{"n":"photos","d":true,"s":4096,"i":"folder","t":false,"k":1}],"listing":1}
  • c 字段是命令,t 字段是响应类型,一行就是一条消息
  • listed 行报告总量与耗时,rows 行给出当前窗口内的文件行
  • 失败不走退出码,而是回一行 {"t":"error","where":"...","msg":"..."}——进程永远活到收到 quit 为止

协议的四条不变量

docs/protocol.md 开头列了四条必须记住的规则,读源码之前值得先看:

  1. list 成功必跟 rows:即使结果为空也会回一行空数组,前端永远不必猜
  2. 错误是消息,不是退出码:--backend 只会在读到 quit 或 stdin 关闭时退出,且退出码恒为 0
  3. 只有一条"主动"消息:changed(目录被别的程序改动)。它可能插在任意请求与响应之间,所以客户端必须读 t 字段而不是按行数计数
  4. 行号只在它所在的 listing 里有效:每次重新扫描都分配递增的 listing 编号,携带旧编号的 trash、transfer 等请求会在解析任何索引之前就被拒绝——这是防竞态的关键设计

四、两阶段加载 + 窗口化:大目录为什么快

Flea 打开十万文件的目录时,不会把全部元数据拉回前端。协议把这件事拆成三步:

  1. Phase 1:只读名字。list 只做 readdir,拿到文件名和"是不是目录",立刻回 listed + 首窗口 rows
  2. 窗口化取详情:前端滚动到哪里,就发 {"c":"window","start":1200,"count":350} 要那一小段的 stat 信息(大小、时间、图标),越界请求只会被夹取、不会出错
  3. 一切按需:缩略图只有 thumb 点名才会生成,目录大小只有 dirsize 点名才会递归统计——"没人点名的行永远不会被看一眼"

Flea 文件管理器网格视图与缩略图

缩略图的前端状态机在 ui/js/Thumbs.js:滚动停止 120ms 后才发一次 thumb,只点名当前可见、且行上标了 t:true 的行;滚出视口的行立刻 thumbcancel。这就是"甩动列表零请求、停下才加载"的来源。

五、前端视角:Backend.qml 如何驱动后端

ui/Backend.qml 是整条协议在前端的唯一化身,只干两件事:

协议的每一种响应行都对应一个 QML 信号:signal rows(...)、signal thumbed(...)、signal transferProgress(...)……界面组件只订阅信号,完全不知道"行"的存在——协议在前端被翻译成了事件流。

长任务也有交代:远端挂载上的写入超过时限,后端先回一行 slow 告诉前端"它还在后台跑,别干等",事件循环继续服务所有其他请求。拷贝/移动则通过 transferstarted → transferprogress(每 150ms 节流一次)→ transferitem → transferdone 四段式消息驱动进度卡片。

Flea 文件管理器快速预览 PDF

预览列与 Quick Look(空格键)的图片尺寸、媒体时长、PDF 信息,同样走这条协议:meta 请求按需取单行的元信息,绝不做全量扫描。

六、性能数字:协议设计换来的结果

README 中的实测(0.3.10,btrfs,100,000 个可见条目,完整方法见 docs/benchmarks.md):

文件管理器 首窗出现 完全稳定 窗口内存 (PSS)
Flea 505 ms 1.00 s 80.7 MiB
Dolphin 752 ms 5.07 s 202.6 MiB
Nautilus 921 ms 6.59 s 321.4 MiB
Nemo 857 ms 21.78 s 472.8 MiB
Thunar 518 ms 19.45 s 358.5 MiB

Flea 文件管理器 Shelf 文件架

这些数字背后正是前文的设计:首窗只等名字扫描、stat 窗口化、缩略图与目录大小全按需、重活全在后台线程,事件循环从不被阻塞。

七、源码导读:想深入从哪里开始

八、总结

Flea 给"文件管理器"这个老题目提供了一个清爽的架构答案:Quickshell 前端只画界面,Rust 后端只管磁盘,中间是一条换行分隔的 JSON 文本流。协议简单到可以直接用终端手敲调试,规则却严丝合缝——错误是消息、行号带编号、主动通知只有一条。正是这种克制,让它把十万文件的目录做成了 1 秒内稳定的流畅体验。如果你想给自己的 Linux 桌面写一个快而稳的文件管理器,这套"进程隔离 + 行协议 + 按需加载"的组合非常值得参考。

登录后查看全文
flea