Flea 文件管理器架构全景:Rust 后端与 Quickshell 前端如何靠 JSON 行协议高效协作
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 的列视图(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 开头列了四条必须记住的规则,读源码之前值得先看:
list成功必跟rows:即使结果为空也会回一行空数组,前端永远不必猜- 错误是消息,不是退出码:
--backend只会在读到quit或 stdin 关闭时退出,且退出码恒为 0 - 只有一条"主动"消息:
changed(目录被别的程序改动)。它可能插在任意请求与响应之间,所以客户端必须读t字段而不是按行数计数 - 行号只在它所在的 listing 里有效:每次重新扫描都分配递增的
listing编号,携带旧编号的trash、transfer等请求会在解析任何索引之前就被拒绝——这是防竞态的关键设计
四、两阶段加载 + 窗口化:大目录为什么快
Flea 打开十万文件的目录时,不会把全部元数据拉回前端。协议把这件事拆成三步:
- Phase 1:只读名字。
list只做readdir,拿到文件名和"是不是目录",立刻回listed+ 首窗口rows - 窗口化取详情:前端滚动到哪里,就发
{"c":"window","start":1200,"count":350}要那一小段的 stat 信息(大小、时间、图标),越界请求只会被夹取、不会出错 - 一切按需:缩略图只有
thumb点名才会生成,目录大小只有dirsize点名才会递归统计——"没人点名的行永远不会被看一眼"
缩略图的前端状态机在 ui/js/Thumbs.js:滚动停止 120ms 后才发一次 thumb,只点名当前可见、且行上标了 t:true 的行;滚出视口的行立刻 thumbcancel。这就是"甩动列表零请求、停下才加载"的来源。
五、前端视角:Backend.qml 如何驱动后端
ui/Backend.qml 是整条协议在前端的唯一化身,只干两件事:
send(object):把请求对象JSON.stringify成一行写入后端 stdin,子进程还没起来时先排队(ui/Backend.qml#L203-L219)receive(line):解析 stdout 的每一行,交给 ui/js/Messages.js 的route分发到对应 QML 信号(ui/Backend.qml#L508-L520)
协议的每一种响应行都对应一个 QML 信号:signal rows(...)、signal thumbed(...)、signal transferProgress(...)……界面组件只订阅信号,完全不知道"行"的存在——协议在前端被翻译成了事件流。
长任务也有交代:远端挂载上的写入超过时限,后端先回一行 slow 告诉前端"它还在后台跑,别干等",事件循环继续服务所有其他请求。拷贝/移动则通过 transferstarted → transferprogress(每 150ms 节流一次)→ transferitem → transferdone 四段式消息驱动进度卡片。
预览列与 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 |
这些数字背后正是前文的设计:首窗只等名字扫描、stat 窗口化、缩略图与目录大小全按需、重活全在后台线程,事件循环从不被阻塞。
七、源码导读:想深入从哪里开始
- 协议全文(最权威的文档):docs/protocol.md
- 请求解析与响应行构造:src/backend/proto.rs
- 后端事件循环与分发:src/backend/run.rs
- 手写 JSON 字段扫描器(热路径不依赖 JSON 库):src/json.rs
- 前端桥与信号定义:ui/Backend.qml
- 响应路由:ui/js/Messages.js
- 缩略图状态机:ui/js/Thumbs.js
- 测试套件:tests/,开发约定:AGENTS.md
八、总结
Flea 给"文件管理器"这个老题目提供了一个清爽的架构答案:Quickshell 前端只画界面,Rust 后端只管磁盘,中间是一条换行分隔的 JSON 文本流。协议简单到可以直接用终端手敲调试,规则却严丝合缝——错误是消息、行号带编号、主动通知只有一条。正是这种克制,让它把十万文件的目录做成了 1 秒内稳定的流畅体验。如果你想给自己的 Linux 桌面写一个快而稳的文件管理器,这套"进程隔离 + 行协议 + 按需加载"的组合非常值得参考。



