Motrix 2.0.0-beta.26 深度解读：中断直链下载安全恢复、系统默认应用接管与跨平台分发演进

Motrix 2.0.0-beta.26 是一个以下载可靠性与平台集成为主线的预发布版本：它为中断的 HTTP/FTP 直链下载引入了一套"不含敏感信息"的持久化重放配方与远端资源校验机制，使应用重启后能在安全验证的前提下无缝续传；同时在 Windows 与 Linux 上新增了系统级默认应用控制，让 .torrent 文件与 magnet: 链接的归属一目了然，新安装默认使用操作系统提供的 Downloads 目录。阅读本文后，你将理解这套直链恢复决策链路的内部工作原理（配方 schema、远端验证器、恢复规划器），掌握新版本在三大平台上的默认应用行为边界，并了解本 beta 的产物形态与分发限制。

本文基于 2.0.0-beta.26.zh-CN.md 展开，源码佐证均来自当前仓库，英文原版见 2.0.0-beta.26.md。

版本主线：中断恢复安全性与平台集成

本版本的主要改进集中在四个方面：

1. 中断恢复安全性：中断的 HTTP 与 FTP 下载现在会持久化重放配方和远端资源校验信息，重启后经过多项检查才决定是否续传；
2. 默认应用控制：集成（Integrations）设置页会显示 Windows 与 Linux 上 .torrent 与 magnet: 链接是否已被 Motrix 接管；
3. 下载目录策略：新安装默认使用操作系统提供的 Downloads 目录，不再假设一定是 <home>/Downloads；
4. 设置体验细节：紧凑 selector 按本地化标签自动扩展、内置浏览器 User-Agent preset 更新。

此外还有一项重要的发布声明：只有在全部受保护发布门禁通过后，本版本才适合公开分发。这是仓库成熟发布流程的一部分——对应发布脚本 scripts/* 中存在大量如 verify-container-publication.mjs、verify-update-artifacts.mjs 之类的门禁校验工具，与文档"受保护发布门禁"的说法相互印证。

直链恢复的"重放配方"：只记事实，不存凭据

为什么需要配方

一条 HTTP/FTP 直链任务在创建时可能附带自定义 Header、Cookie、代理地址或额外的 aria2 引擎选项。单纯保存 URL，重启后无法复现与首次请求一致的语义；而把 Cookie、Authorization 等凭据明文落库又会带来严重的安全问题。Motrix 的解法是：持久化一份"请求形态描述"，而不是请求本身。

核心实现位于 src/core/task/direct-replay-recipe.ts 的 buildDirectReplayRecipe()：它逐项探测创建参数中是否存在非空的自定义项，并据此生成一个只含枚举标签的 requestModifiers 数组，可能的取值定义在 src/shared/schemas/direct-replay-recipe.ts：

• headers：任务携带了自定义请求头；
• cookies：任务显式携带 Cookie；
• proxy：任务配置了代理；
• extraEngineOptions：任务携带了额外的 aria2 引擎选项；
• engineGlobalOptions：使用了环境级全局引擎请求选项（来自 ambientEngineRequestOptions 参数）。

配方主体的字段约束同样在 schema 文件中明确：

字段	说明	约束
version	配方版本	字面量 1
connections	建议的连接数	可选，整数 1–128
requestModifiers	请求形态标签列表	最多 5 个，不允许重复
replayability	可重放性	uri-only 或 requires-credentials
resourceValidator	远端资源校验器	可选（详见下节）

schema 内置 superRefine 自洽性校验：replayability 必须与 requestModifiers 长度一致——没有任何修饰项时为 uri-only（仅凭 URI 即可等价重放），否则为 requires-credentials（需要请求凭据）。schema 文件 同时提供 parseDirectReplayRecipe()：未知版本、结构损坏、内部自相矛盾的配方一律视为不可重放，而不是部分妥协地使用，保证"恢复安全"这条主线的严格性。

远端资源校验信息：强 ETag 与 Last-Modified

只有 URI 还不足以安全续传——重启后必须确认远端资源没有变化，否则把新资源的数据拼接到旧的部分文件上会造成数据损坏。因此配方还包含一个 resourceValidator，由 src/core/task/direct-resource-validator.ts 中的 DirectResourceValidatorService 在任务创建时通过有界探测捕获，schema 区分两种"强校验器"（见 direct-replay-recipe.ts）：

• strong-etag：必须是带引号且不以 W/ 开头的强 ETag（弱 ETag 不保证字节级一致，会被 schema 直接拒绝），可选记录 contentLength；
• last-modified：必须是可解析的合法 HTTP 日期。

探测过程遵循一套严格的 HTTP 语义：请求使用与 aria2 一致的 GET 方法、redirect: 'manual' 手工跟随、最多 5 次重定向，收到响应头后立即取消响应体（每个探测请求默认 3 秒超时）；跨源重定向时仅保留 accept、range、user-agent 等安全头，携带空值以外的 authorization/cookie 会被拒绝放行。它还会参照 extra/aria2.conf 中开启的 gzip 行为，为探测请求补上 accept-encoding: deflate, gzip 与 want-digest 头，以尽可能复现 aria2 的真实请求指纹。

重启后的多级检查与恢复决策

恢复时的判断逻辑由 src/core/session/direct-recovery-planner.ts 中的 DirectRecoveryPlanner 承担。它会先校验路径合法性与绝对性（拒绝含 NUL 字节、非绝对路径、空文件名等"不可用输入"），随后对磁盘状态做组合判定，产出五种 DirectRecoveryKind：

判定类型	触发条件	含义
invalid	路径含 NUL、非绝对路径、路径指向非文件等	输入非法，放弃自动恢复
finalization-candidate	临时文件不存在但最终文件存在	上次已下载完成，仅需收尾
fresh	临时文件缺失或为空	从头开始
checkpoint	临时文件非空且存在 <file>.aria2 checkpoint	具备续传条件
blocked	最终路径冲突、或临时文件非空但 checkpoint 缺失等	阻断自动续传

可以看到，文档所述的恢复前检查——部分文件是否存在、aria2 checkpoint（即 .aria2 控制文件）是否存在、最终路径是否存在冲突——正是该规划器的输入与输出维度。

校验不通过时的策略：保留部分文件，绝不拼接

真正决定"能否续传"的是重启后对远端的二次验证。Motrix 会带着已持久化的校验器发起一次单字节 Range 探测（Range: bytes=0-0 + If-Range: <validator值>，见 direct-resource-validator.ts），并根据响应返回四种结果：

• unchanged：服务器返回 206 Partial Content，ETag/Last-Modified 与记录一致 → 可安全续传；
• range-unsupported：服务器返回 200（忽略 Range），说明不支持断点续传，但资源身份一致；
• source-changed：校验器值或长度不一致 → 远端资源已变化；
• unverifiable：无法完成校验（超时、代理不可用、缺少校验头等）。

只有在"能安全验证资源身份、且请求凭据可满足"时才会真正续传；一旦无法安全验证资源身份或请求凭据（例如配方是 requires-credentials 而凭据不可重放），Motrix 会保留部分文件，并向用户说明需要手动恢复的原因——而不是把可能不兼容的数据强行拼接，这是本次恢复安全性的核心承诺。相关测试可参考 direct-recovery-planner.test.ts 与 direct-resource-validator.test.ts，它们覆盖了上述各分支与失败路径。

系统默认应用控制：.torrent 与 magnet: 的归属

Windows：只读 UserChoice，跳转 Default Apps 页面

在 Windows 上，.torrent 与 magnet: 的关联由注册表 UserChoice 键保护，应用不应也无权绕过系统直接改写。因此实现位于 src/main/platform/windows-default-apps.ts：

• 应用安装时注册 App Capabilities（Software\Motrix\Capabilities）与两个 ProgID：Motrix.File.Torrent 与 Motrix.Url.Magnet；
• 集成设置页只读取 .torrent/magnet 关联键下的 UserChoice\ProgId（源码中仅列出 UserChoice、UserChoiceLatest、UserChoiceLatest\ProgId 等后缀用于查询，绝不写入），据此显示当前是否由 Motrix 接管；
• 需要变更时，Windows 会打开系统的 Default Apps 设置页（ms-settings:defaultapps），把最终决定权交还给用户。源码还区分了不同 Windows 11 累积更新对"按应用查询默认值"能力的支持差异（见该文件 supportsRegisteredAppDefaultAppsQuery），确保在不支持新 API 的系统上退化为通用默认应用页。

Linux：native 用 xdg-mime，AppImage 保存并恢复旧 handler

Linux 侧的实现在 src/main/platform/linux-default-apps.ts，它首先通过环境变量识别包类型（detectLinuxPackageKind）：

• APPIMAGE → AppImage；
• FLATPAK_ID → Flatpak；
• SNAP/SNAP_NAME/SNAP_INSTANCE_NAME → Snap；
• 否则视为 native（DEB/RPM）。

针对两个 MIME 类型（application/x-bittorrent 与 x-scheme-handler/magnet），该模块沿 XDG 数据目录链查找 Motrix 的 desktop 文件，并用 xdg-mime query default 查询当前默认 handler，比对是否落在 Motrix 的 desktop id 集合内：

• native（DEB/RPM）：canSetTorrentDefault 为 true，可通过 xdg-mime default <desktopId> <mime> 直接设置 .torrent 的默认应用，并以查询结果回读验证是否成功；
• AppImage：集成需要用户主动启用，只写入当前用户的 XDG 数据目录；据 appimage-integration.ts 及其配套测试，AppImage 集成会保存并恢复经过验证的旧 handler，避免在退出/更新时破坏用户原有关联；
• Snap/Flatpak：受限容器只能识别到带实例前缀的导出 desktop id，不会把 host 上无关的 deb/rpm desktop 条目错误归属给自身。

分发方式差异

文档特别指出：由于 Native Messaging host 在挂载镜像之外没有稳定路径，浏览器扩展暂时无法向 AppImage 安装包转交下载任务；AppImage 用户如需浏览器接管，需要改用 native 安装包。这也是集成设置在不同包类型上能力不一的原因。

下载目录：跟随操作系统真实 Downloads 目录

此前版本可能直接假设目录为 <home>/Downloads，但不同语言环境、不同系统（尤其 Windows）的真实下载目录并不总是这个名字。本版本开始：

• 新安装默认使用操作系统提供的 Downloads 目录（通过 Electron app.getPath('downloads') 之类的平台 API 解析真实位置）；
• 已经保存的路径保持不变，升级不改变用户既有配置；
• 受限 Snap 安装包继续使用稳定的 real-home 默认值，这是因为 Snap 沙箱内的 $HOME 与实际宿主 home 存在差异，需要专门的路径策略。

这符合"迁移不破坏存量配置、新用户拿到正确默认值"的工程原则，相关下载路径与迁移逻辑可在 src/core/session/migrations 与设置默认值相关源码中进一步确认。

设置细节与体验更新

• 紧凑 selector 自动扩展：设置界面中的紧凑下拉 selector 现在会根据本地化标签长度自动扩展，避免较长译文（例如德语、法语等长单词语言）被截断显示不全。
• User-Agent preset 更新：内置的 Chrome、Firefox、Safari 与 Transmission 四组浏览器/客户端 User-Agent 预设已更新，使伪装 UA 下载时保持与新版浏览器的请求指纹一致（相关请求头默认逻辑可参见 direct-resource-validator.ts 的探测头构造）。

预发布测试须知与建议场景

beta 版本存在数据风险，文档给出的测试纪律值得逐条执行：

1. 安装前备份现有 Motrix 应用数据与下载文件；
2. 不要用本 beta 处理唯一一份 v1 数据——v1 → v2 数据迁移路径尚未验证；
3. 条件允许时，用独立的操作系统账号、设备或 Docker 数据目录并行测试 v2，不要把唯一重要下载内容托付给本 beta。

针对本次新功能的定向测试建议：

• 在 HTTP/FTP 下载已写入部分文件与 aria2 checkpoint 后中断任务，再重启 Motrix，确认任务能继续下载且不丢失进度；
• 主动构造远端资源已变化或 checkpoint 缺失的场景，确认 Motrix 会保留部分文件而不是拼接不兼容的数据；
• Windows 与 Linux 用户在集成设置中检查默认应用状态，验证 .torrent 与 magnet: 的转交（接管）行为是否符合预期。

发布门禁与分发形态

计划产物矩阵

门禁通过后计划提供如下产物：

分发方式	架构	计划产物
macOS 12 或更高版本	arm64（Apple Silicon）、x64（Intel）	DMG 和 ZIP
Windows	x64	未签名 NSIS 安装程序（.exe）和 ZIP
Linux	x64、arm64	AppImage、DEB 和 RPM
Flatpak Native Host companion	linux/x64、linux/arm64	Motrix-Native-Host-2.0.0-beta.26-linux-<arch>.tar.gz
Docker Hub / GHCR	linux/amd64、linux/arm64	两个仓库中的不可变 2.0.0-beta.26 标签
Snap Store	—	本 beta 不发布

容器门禁通过后可使用带版本镜像：docker.io/motrixapp/motrix-server:2.0.0-beta.26 与 ghcr.io/agalwood/motrix-server:2.0.0-beta.26；存储、网络与升级相关说明见 Docker Server 部署指南。

分发边界说明

• AppImage：桌面集成需用户主动启用且只写当前用户 XDG 数据目录；浏览器扩展无法向 AppImage 转交下载（Native Messaging host 无稳定路径）；
• Flatpak：单独验证、不由 release tag 发布；GitHub 预发布版会附带其 Native Host companion 压缩包；
• 不提供 Windows arm64 与所有 32 位安装包；
• Windows 安装包未签名，可能触发 SmartScreen 警告，请仅从官方预发布渠道下载并核对来源；
• Beta 容器标签不可变，不会更新 latest、stable 或其他稳定通道浮动标签；
• Snap：本 beta 不发布；预发布 Snap 流程在 source validation 后即停止，不构建/上传产物，也不改动 latest/edge。

反馈方式

遇到可复现的问题时，请通过官方 GitHub Issues 反馈，并附上操作系统、架构、安装包类型与完整复现步骤四要素——这四类信息足以定位绝大多数平台相关问题。

小结

Motrix 2.0.0-beta.26 是一次典型的"可靠性 + 平台集成"预发布迭代：恢复功能从"凭部分文件硬续传"进化为"配方 + 校验器 + 恢复规划器"的多级安全决策，数据安全优先于下载便利；默认应用管理在 Windows/Linux 上尊重系统语义（UserChoice 只读、xdg-mime 协作、AppImage handler 存档恢复）；下载目录默认值回归操作系统真实路径。对于使用直链下载且关心中断恢复一致性的用户而言，理解这套"不存凭据、不拼错数据"的设计，比等待正式版更有实际价值。