ReinaManager分段续传下载引擎解析:4MiB分片与控制文件背后的断点续传设计

原创2026-11-01 15:30:22245 阅读

ReinaManager分段续传下载引擎解析:4MiB分片与控制文件背后的断点续传设计

ReinaManager 是一款轻量级的 Galgame/视觉小说管理器(Tauri 2 + React + Rust 架构)。它内置的 reina-download 分段续传下载引擎,用 4MiB 分片和旁路控制文件(.reina-dl)解决了"大体积游戏包下载中断后不必从头再来"的经典难题。本文带你快速看懂这套断点续传设计的核心机制。

ReinaManager 游戏管理器主界面,展示继续游戏与游戏库入口

一、下载引擎在系统中的位置

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]
}

围绕它有三条铁律:

  1. 存在即未完成:控制文件存在表示下载还没结束;下载成功的最后一步就是删掉它。
  2. 原子写入:每次提交都先写 .tmp 临时文件并落盘,再 rename 覆盖(fsx.rs),崩溃不会留下半写的控制文件。
  3. 只会低估、不会高估:提交器严格按"快照分片计数 → 目标文件 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),双重保险。

下载完成后,游戏包会被解包、扫描可执行文件并导入游戏库,成为你游戏库里的一张新卡片:

ReinaManager 游戏库页面,下载安装完成的游戏以卡片网格展示

九、一张表看懂关键参数

参数 默认值 作用
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 小文件,共同撑起了"随便暂停,随时续传"的体验。

登录后查看全文
ReinaManager