ReinaManager分段续传下载引擎解析:4MiB分片与控制文件背后的断点续传设计
ReinaManager分段续传下载引擎解析:4MiB分片与控制文件背后的断点续传设计
ReinaManager 是一款轻量级的 Galgame/视觉小说管理器(Tauri 2 + React + Rust 架构)。它内置的 reina-download 分段续传下载引擎,用 4MiB 分片和旁路控制文件(.reina-dl)解决了"大体积游戏包下载中断后不必从头再来"的经典难题。本文带你快速看懂这套断点续传设计的核心机制。
一、下载引擎在系统中的位置
ReinaManager 的整体架构是:React 前端负责界面,Rust 后端负责文件、安装任务和持久化(参见 docs/architecture/README.md)。下载引擎是一个独立 crate,位于 src-tauri/reina-download/:
| 模块 | 职责 |
|---|---|
| engine.rs | 下载编排:探测、分片调度、单流回退、提交器、收尾 |
| control.rs | 磁盘控制文件:分片进度记录与原子写入 |
| types.rs | 默认 4MiB 分片大小、DownloadOptions 全部可调参数 |
| limiter.rs | 跨任务连接预算(Gate)与自适应连接数(Adaptive) |
| fsx.rs | 定位写、稀疏预分配、原子替换 |
| progress.rs | 阶段枚举 Phase 与进度快照推送 |
真正调用它的是游戏安装流水线中的 src-tauri/src/install/download.rs。
二、4MiB 分片:中断损失"以秒计"
引擎把所有文件切成固定大小的分片,默认值定义在 types.rs:
/// 默认分片大小:足够小让中断损失以秒计,又不会让大文件产生过多请求。
pub const DEFAULT_PIECE_SIZE: u64 = 4 * 1024 * 1024;
这是一个精心权衡的数值:
- 太小(如 64KB):几十 GB 的文件会产生上万条请求,探测和调度开销巨大;
- 太大(如 256MB):一个分片刚下载了一半就断网,损失的上界也跟着变大。
4MiB 让"单个分片最多损失 4MiB 的传输进度",在常见带宽下只是零点几秒的事;同时 4GiB 的游戏包也只被切成 1024 个分片,请求数完全可控。
分片下载时,每个 worker 用 Range: bytes=起始-结束 精确请求自己负责的字节区间,并以定位写(write_at/seek_write)把数据直接写到目标文件的正确偏移处,见 fsx.rs。多个连接写同一个文件互不干扰,因为它们的范围绝不重叠。
三、控制文件 .reina-dl:断点的唯一事实源
断点信息不放在数据库,而是放在目标文件旁边的一个 JSON 控制文件,后缀常量为 .reina-dl(control.rs):
game.zip ← 目标文件
game.zip.reina-dl ← 控制文件(下载成功时删除)
控制文件里记录了文件总大小、分片大小、内容标识(如 sha256:…)、ETag / Last-Modified,以及每个分片从起点开始连续已写入的字节数。例如:
{
"version": 1,
"size": 4294967296,
"piece_size": 4194304,
"identity": "sha256:9f2a...",
"pieces": [4194304, 4194304, 2097152, 0, 0]
}
围绕它有三条铁律:
- 存在即未完成:控制文件存在表示下载还没结束;下载成功的最后一步就是删掉它。
- 原子写入:每次提交都先写
.tmp临时文件并落盘,再rename覆盖(fsx.rs),崩溃不会留下半写的控制文件。 - 只会低估、不会高估:提交器严格按"快照分片计数 → 目标文件
fdatasync→ 写控制文件"的顺序执行(engine.rs)。宁可让控制文件记录得保守一点,续传时多下几个字节,也绝不复用一个实际没写好的位置。
引擎还会做几何校验:控制文件里的分片数、每个分片声称的长度与文件大小不符时,直接判定失效、重新开始(control.rs)。
四、续传身份判断:换直链也能续
签名直链过几小时就失效,重下时往往是一个新 URL。引擎的续传身份与 URL 无关(engine.rs 的 reconcile 逻辑):
- 首选
expected_size+ 内容校验和(identity,如sha256:…):两者一致就放心续传,CDN 各节点 ETag 漂移也能容忍; - 没有校验和时,退回比对 ETag / Last-Modified,不一致则丢弃旧断点;
- 服务器报告的文件大小与期望不一致时,直接报
SizeMismatch拒绝继续。
此外还有两条防御:目标文件存在但没有控制文件且大小正好匹配,直接视为已完成秒返;目标文件缺失或长度不对,说明旧分片字节已不可证明,全部归零重来(engine.rs)。
五、探测与单流回退:Range 不灵也不卡死
下载前先发一个 Range: bytes=0-0 探测请求(最多重试 5 次),按响应分三种走法:
| 响应 | 含义 | 引擎行为 |
|---|---|---|
206 |
服务器支持 Range | 进入多连接分段下载 |
200 |
服务器忽略了 Range | 回退单流下载,后台每 10 秒复探一次,一旦拿到 206 立即无缝升级为分段模式 |
416 |
范围不可满足 | 从 Content-Range 中解析出总大小,仍按分段处理 |
还有个细节:部分 CDN 只在首个请求上忽略 Range。引擎会等待 1.5 秒后复测一次,避免误入单流模式(engine.rs)。单流模式下进度依然按分片粒度记账,升级后零损失衔接。
六、自适应连接与限流:对 CDN 有礼貌
默认参数(types.rs)为:最少 1 / 初始 4 / 最多 8 条连接,由 Adaptive 调节:
- 连续 8 个分片成功 → 连接数 +1,向 8 爬升;
- 收到
429限流 → 目标减半(同一窗口内只减一次),并按服务器Retry-After做全局暂停(上限 60 秒,防止恶意值让下载停摆)。
单连接 20 秒收不到字节即判"停滞",断开重排;失败按指数退避重试(500ms 起步,30 秒封顶,带抖动),连续可重试失败超过 20 次才整体失败。
更上层还有一道全局预算:所有并行安装任务共享 24 条在飞连接上限(download.rs),避免多任务把同一 CDN 打爆。
七、暂停/取消不是错误:先落盘,再返回
这是整个设计里最值得记住的一条约定:取消(暂停与取消对核心等价)先把进度持久化到控制文件,再返回 Outcome::Cancelled,它不算错误(lib.rs)。
运行中的提交器每 2 秒做一次"快照 + fdatasync + 写控制文件";收到取消信号后还会强制执行一次最终提交再退出。也就是说,你最多只损失不到 2 秒里还留在页缓存、未落盘的字节——关掉 App、断网、断电同理。下次启动恢复任务时,读一次控制文件就能精确续传。
进度推送则完全与传输解耦:后台 emitter 每 250ms 推一个含阶段(探测/分段下载/单流/收尾)、已提交字节、平滑速度的快照;安装层每 500ms 把已提交水位写入任务表并广播给前端进度条,UI 刷新永远不会拖慢下载(progress.rs、download.rs)。
八、收尾与校验:删控制文件才算完成
全部分片到齐后,引擎做最终 sync_all 落盘、删除控制文件,才返回 Completed(engine.rs)。核心的职责边界非常克制——它只保证"字节落位",最终内容校验由调用方完成:安装流水线随后按任务携带的校验和做 sha256 / blake3 全文件比对(download.rs),双重保险。
下载完成后,游戏包会被解包、扫描可执行文件并导入游戏库,成为你游戏库里的一张新卡片:
九、一张表看懂关键参数
| 参数 | 默认值 | 作用 |
|---|---|---|
piece_size |
4 MiB | 分片大小,决定中断损失上界 |
min/initial/max_connections |
1 / 4 / 8 | 单任务连接数自适应区间 |
stall_timeout |
20 s | 单连接停滞判定 |
commit_interval |
2 s | 控制文件落盘间隔 |
progress_interval |
250 ms | 进度快照推送间隔 |
grow_after_successes |
8 | 连续成功多少个分片后连接 +1 |
max_consecutive_failures |
20 | 连续可重试失败上限 |
upgrade_probe_interval |
10 s | 单流模式重探 Range 的间隔 |
| 全局连接预算 | 24 | 所有并行任务共享的在飞连接上限 |
小结:ReinaManager 的断点续传 = 固定分片定位写(快且损失小)+ 旁路控制文件原子记账(崩溃安全、只会低估)+ 与 URL 解耦的身份校验(换直链可续)+ 单流回退与自适应限流(对服务器友好)+ 取消即落盘(暂停/断电零尴尬)。四个 MiB 的小数字和一个 .reina-dl 小文件,共同撑起了"随便暂停,随时续传"的体验。

