Motrix 2.0.0-beta.1 发布说明解读：Motrix Turbo v2 的初始 Beta 范围、分发矩阵与源码级验证

Motrix 2.0.0-beta.1 是 Motrix Turbo（v2 重构版）计划中的首个公开 Beta，本文基于仓库中的发布说明 2.0.0-beta.1.md 完整还原其规划范围：host-neutral 下载核心、MDXP 集成、QuickJS 插件沙箱与多架构 Server 容器。读完本篇，你可以掌握该 Beta 的完整能力边界、各平台分发形态，并用当前仓库源码逐项验证文档声明的技术栈与实现事实。

重要提示：beta.1 的两次 tag 触发的发布流水线都在对外分发前中止，因此 beta.1 没有 GitHub Release、R2 更新源、Docker Hub / GHCR 镜像或 Snap Store 修订版，官方引导使用 Motrix 2.0.0-beta.2 代替。本文保留 beta.1 的完整章节内容，作为其"预期 Beta 范围"的历史记录。

一、核心亮点：桌面端重构与共享下载核心

发布说明列出六大亮点，下面逐项给出仓库源码层面的印证。

1. Electron 43 + React 19 + TypeScript 7 的桌面重构

文档声称 beta.1 采用"基于 Electron 43、React 19 与 TypeScript 7 的地面级重构"，包含可自定义的 Dashboard、暗色模式、跨平台应用菜单和更清晰的 task-inspector 反馈。当前 package.json 可确认这套技术栈仍然延续（beta.28 阶段）：

• electron: "43.4.0"（package.json#L98）
• react: "^19.2.8"（package.json#L142）
• typescript: "~7.0.2"（package.json#L105）
• quickjs-emscripten: "^0.32.0"（package.json#L141），即插件沙箱的运行时

打包侧的配置同样印证了桌面端重构的工程细节，见 electron-builder.json：

• macOS 最低系统版本为 12.0（electron-builder.json#L95），与文档中"macOS 12 or later"的发布矩阵完全一致；
• 注册了 motrix / mo 自定义协议与 magnet 协议（electron-builder.json#L79-L88），支撑"浏览器/CLI 一键转存到 Motrix"的 handoff 能力；
• Windows 目标为 NSIS 安装器（.exe）+ ZIP、仅 x64 架构（electron-builder.json#L141-L145），与文档"Windows 只提供 x64"的限制吻合；
• Electron Fuses 启用了 onlyLoadAppFromAsar、禁用 runAsNode 等安全加固（electron-builder.json#L69-L78），这是 beta.1 规划中"重建的发布流水线"的一部分。

2. 桌面端与 Node/Web Server 共享的 host-neutral 下载核心

文档强调"一个 host-neutral 下载核心同时服务桌面应用与新的 Node/Web Server"，并提供 SQLite 会话恢复、tracker 管理、UPnP/NAT-PMP 以及 HTTP、FTP、BitTorrent、magnet 支持。从仓库结构看，核心逻辑全部位于 src/core/，与宿主解耦：

• SQLite 会话持久化：motrix-database.ts 与 session-manager.ts，依赖 better-sqlite3（package.json#L123），对应"SQLite session recovery"；
• Tracker 管理：tracker-manager.ts、tracker-syncer.ts 等一整套模块，对应"tracker management"；
• UPnP/NAT-PMP：settings-nat-provider.ts 从设置读取 enabled、preferredProtocol、mappingTtl、STUN 服务器与端口可达性检查等配置（settings-nat-provider.ts#L15-L27），底层封装于 @motrix/nat 包；
• 下载引擎为 aria2 分支，通过 fetch-engine.mjs 拉取目标平台的 aria2_motrix 二进制。

3. MDXP 集成：官方 CLI 与浏览器 handoff、设备码配对

文档声明通过 MDXP 实现"官方 CLI 与浏览器 handoff，包括安全的本地发现与针对远程 Server 实例的设备码配对"。当前仓库中：

• 依赖 @motrix/mdxp（package.json#L115）；
• WebSocket 桥接服务 web-socket-bridge-server.ts 负责本地发现与配对；
• device-code-service.ts 实现轮询式、无连接的设备码流程（device-code-service.ts#L10-L13），并内置限流保护（RateLimited，device-code-service.ts#L138），对应文档"remote Server instances 的设备码配对"；
• 仓库还带有 Rust 编写的 native-host 包 packages/native-host，用于浏览器原生消息通道。

4. QuickJS 插件沙箱

文档称插件系统为"带能力授权（capability consent）、签名内置插件与应用内插件市场"。源码印证了 QuickJS 沙箱的实现：quick-js-worker.ts 的头部注释完整描述了沙箱生命周期——主线程通过 worker_thread 启动 Worker，Worker 内加载 QuickJS WASM、注入受限全局对象（带配额的 setTimeout 等）、将插件 bundle 中 import { x } from 'motrix:plugin-api' 重写为 globalThis.__motrix_plugin_api__ 后再以 ES module 方式求值。能力调用被分为 effectful 代理（调用前 assertEffectfulAllowed 校验）与本地注册的 hook/command 句柄，正是"capability consent"的落地方式。相关实现位于 src/core/plugin/host/ 与 src/core/plugin/capabilities/，签名验证逻辑在 trusted-extension-registry.ts。

5. 持久化、多架构 Server 容器

文档规划"用于 NAS 与家庭服务器部署的持久化多架构容器，计划发布到 Docker Hub 与 GHCR"。当前仓库的 Dockerfile 展示了该 Server 的构建方式：基于锁定摘要的 node:24-alpine 镜像，按 TARGETARCH 选择 amd64/arm64 拉取对应引擎并执行 pnpm run build:server，随后经 stage-server-app.mjs 与 verify-server-package.mjs 完成打包与校验（Dockerfile#L37-L52）。部署细节（存储挂载 /data 与 /downloads、网络发布模式、tag 策略）详见 docs/docker-server.md，其中也明确镜像同时发布到 docker.io/motrixapp/motrix-server 与 ghcr.io/agalwood/motrix-server 两个注册表——正是 beta.1 文档中"intended"的两个镜像名。

6. 重建的发布流水线

文档列出的流水线能力——隔离的 macOS 签名、可选的 Windows Authenticode 签名、包校验、第三方声明与 SPDX SBOM——在当前仓库脚本中均有对应物：

• 第三方声明与 SBOM 生成：generate-third-party-notices.mjs，electron-builder.json#L46-L68 将 sbom.spdx.json 与 THIRD_PARTY_LICENSES 目录打进 extraResources；
• 包校验：before-pack-verify.mjs、verify-electron-package.mjs、verify-server-package.mjs；
• 容器发布校验：verify-container-publication.mjs、verify-update-artifacts.mjs；
• 仓库根目录的 THIRD_PARTY_LICENSES 目录与 THIRD_PARTY_NOTICES.md 即为该流程产物。

二、测试前须知（Before testing）

这是发布说明中面向测试者的关键安全提示，原文完整保留：

• 这是预发布软件。安装前请备份现有的 Motrix 应用数据与下载内容。由于从 Motrix v1 数据的迁移尚未验证，不要用唯一的 v1 数据副本直接跑这个 Beta；
• 条件允许时，请用独立的 OS 账号、独立机器或独立 Docker 数据目录并行测试 v2；
• 不要把这个 Beta 当作重要下载的唯一副本。

三、测试范围（What to test）

官方给出的测试清单，也是理解 beta.1 能力边界的最好索引：

1. HTTP、FTP、BitTorrent、magnet 下载，包括暂停/恢复与会话恢复；
2. 桌面集成、通过 MDXP 的浏览器与 CLI handoff、沙箱化插件；
3. Headless Server 部署、持久化存储与远程配对。

四、计划中的下载渠道（Intended downloads，实际未发布）

以下为文档原文的完整分发矩阵：

分发渠道	架构	计划产物
macOS 12 或更高	arm64（Apple Silicon）、x64（Intel）	DMG 和 ZIP
Windows	x64	NSIS 安装器（.exe）和 ZIP
Linux	x64、arm64	DEB 和 RPM
Docker Hub / GHCR	linux/amd64、linux/arm64	两个注册表中的不可变 2.0.0-beta.1 tag
Snap Store	amd64、arm64	latest/edge

计划中的容器镜像名为 docker.io/motrixapp/motrix-server:2.0.0-beta.1 与 ghcr.io/agalwood/motrix-server:2.0.0-beta.1，均未发布。存储、网络与升级方面的部署指导请见 Docker Server 部署指南。

五、已知的分发限制（Known distribution limits）

文档明确列出的限制，逐条与仓库配置相互印证：

• AppImage 不随本 Beta 发布。注意 electron-builder.json#L197-L201 中 Linux target 目前包含 AppImage，说明该限制是 beta.1 当时的流水线决策而非打包配置缺失；
• Flatpak 独立验证，不由 release tag 发布（相关脚本见 prepare-flatpak-project.mjs 与 verify-flatpak-packaging.mjs）；
• 无 Windows arm64 与任何 32 位包——与 electron-builder.json#L141-L145 中 NSIS/ZIP 均只列 x64 一致；
• Windows 包计划不做 Authenticode 签名，可能触发 SmartScreen 警告；且 beta.1 的 Windows 包实际未发布（签名能力对应 electron-builder.signing.json）；
• Beta 容器 tag 不可变，不会推进 latest、stable 或其他稳定的浮动 tag——docs/docker-server.md 中的 tag 语义表（不可变 x.y.z、浮动 x.y/x/stable/latest，预发布绝不更新浮动 tag）延续了这一策略。

六、问题反馈

发布说明要求通过 GitHub Issues 报告可复现的问题，并附操作系统、架构、包类型与复现步骤。在当前仓库内，可直接定位问题归属的方式是：

• 桌面端 UI 问题看 src/renderer（组件、hooks、路由）；
• 下载核心问题看 src/core（task、session、bridge、tracker、nat 等子模块均有同名 *.test.ts 单元测试）；
• Server 端问题看 src/server；
• 端到端行为有 Playwright 用例覆盖（playwright.config.ts 与 e2e 目录，如 e2e/pair-and-submit.spec.ts 覆盖 MDXP 配对提交流程）。

七、小结

beta.1 虽然未走到对外分发，但这份发布说明完整定义了 Motrix Turbo 的初始 Beta 范围：一个同时服务桌面与 Server 的共享下载核心、MDXP 驱动的 CLI/浏览器集成、QuickJS 能力授权式插件沙箱，以及多架构 Server 容器与重建的签名/SBOM 发布流水线。上述每一项声明都可以从当前仓库的 package.json、electron-builder.json、Dockerfile、src/core 与 scripts 中找到对应的实现证据；如需实际安装与部署，请以 Motrix 2.0.0-beta.2 及后续版本的发布说明为准。