Motrix 2.0.0-beta.21 发版解析：Linux 可信 HTTPS、64 连接性能预置档与结构化日志脱敏

Motrix 2.0.0-beta.21 是 v2 系列在一系列内部 beta 校验后推出的一个高质量候选版本，它同时修复了 Linux 发行版上因静态引擎 OpenSSL 路径缺失而导致的 HTTPS 下载失败问题、引入全新的下载性能预置档（最高单服务器 64 连接）、强化了设置持久化与引擎恢复的可靠性，并为应用与插件日志建立了统一的脱敏边界。本文以 2.0.0-beta.21 发布说明 为核心，结合仓库源码逐项还原这些能力的实现原理、配置取值与运行前提，帮助下载器开发者和进阶用户在测试与集成该版本时快速定位相关模块、理解行为边界。

版本定位与发布策略

beta.21 并非针对 beta.20 功能层面的增量：二者面向用户的变化完全一致，beta.20 之所以未能公开发布，是因为发布装配阶段发现 electron-builder 生成的「AppImage 优先」的 Linux 更新元数据未通过校验。beta.21 在保留同样功能的前提下，将兼容性字段归一化到 DEB 更新资产上，再进入最终验证与发布流程（见发布说明）。

该版本仍属于预发布软件，发布说明给出了明确的测试前提：

• 安装前必须备份现有 Motrix 应用数据与下载任务；
• 从 Motrix v1 数据的迁移尚未得到验证，不要用唯一的 v1 数据副本参与测试；
• 条件允许时，建议在独立的 OS 账号、机器或 Docker 数据目录中并行测试 v2；
• 该 beta 仅在全部受保护的发布门禁（protected release gate）通过后才面向公开分发。

也就是说，正式产出（DMG/ZIP、NSIS、AppImage/DEB/RPM、容器镜像等）以发布流水线门禁通过为前提，读者在自行构建或等待官方产物时应关注这一流程约束。

关键能力亮点速览

本版本的高亮能力可归纳为六条主线：

1. Linux 可信 HTTPS 修复：每次启动时由系统信任库组装一份全新 CA bundle 交给 aria2，必要时回退到内置根证书——而不是简单关闭证书校验。
2. 统一 aria2 fork 基线：桌面、Server、Docker、Flatpak 包统一使用 Motrix 维护的 1.37.0-motrix.6；Server 与 Docker 直接内置经校验的 Motrix 二进制，不再依赖发行版提供的 aria2。
3. 下载性能预置档：Automatic / Balanced / High speed / Maximum / Custom 五档，协同管理连接数、分段数、最小分段大小与磁盘缓存。
4. 设置持久化先行：先保存、再请求引擎重启；可热应用的设置即时下发，需要重启的项保留持久化提示。
5. 结构化日志脱敏：应用与插件日志共用脱敏边界，密钥、凭据、Cookie、请求体、存储值、敏感路径与 URL query 均被清除。
6. AppImage 桌面集成回归：可选启用桌面项、图标以及 motrix:、magnet:、.torrent 协议处理器，全部局限在用户自己的 XDG 数据目录。

其余改进覆盖 tracker 状态恢复、NAT 映射重试、下载计数语义对齐，以及 Windows/Linux 标题栏控制按钮与安全区的统一。下文逐一展开源码级细节。

修复 Linux 发行版上的可信 HTTPS 下载

核心问题：静态构建的 aria2 在运行时使用的 OpenSSL 编译期路径，在很多 Linux 发行版上并不存在，导致合法的 HTTPS 下载失败。

修复方案不是禁用证书校验，而是在每次启动时从系统信任库动态组装一份 CA bundle：

• Linux 启动路径会调用 Aria2TrustStore.prepareEnvironment()（见 aria2-trust-store.ts），通过 Node 的 getCACertificates() 读取系统 CA 证书，去重、去空白后原子写入用户配置目录下的 aria2-ca-bundle.pem（文件权限 0o600），再通过 SSL_CERT_FILE 环境变量传递给 aria2 子进程；
• 若系统信任库为空，则回退到内置根证书（日志记录 bundled-fallback）；两级都为空时才抛出 No CA certificates are available for aria2 HTTPS；
• 若调用方已显式设置 SSL_CERT_FILE / SSL_CERT_DIR，则直接沿用调用方提供的信任库，不做覆盖（见 aria2-trust-store.ts）。

值得强调的是，该实现还顺带做了两项环境净化，属于容易被忽略但关键的细节：

• 剥离代理环境变量：http_proxy、https_proxy、ftp_proxy、all_proxy、no_proxy 全部被移除（代码位置），确保 Motrix 的代理策略是 aria2 路由的唯一来源，避免 aria2 自行导入协议级代理变量覆盖 all-proxy 与元数据客户端的路由；
• Windows 剔除 OpenSSL 覆盖：openssl_conf、openssl_engines 等机器级 OpenSSL 覆盖不会进入子进程环境，防止它们替换静态链接引擎的 provider 路径与 CPU 分发配置——这些变量甚至会影响 WebSocket SHA-1 与 RPC-secret HMAC，造成本地 RPC 失效。

主进程在启动阶段即实例化信任库，用户数据目录直接来自平台层：const trustStore = new Aria2TrustStore(platform.userDataDir)（见 src/main/index.ts）。

统一到 Motrix aria2 fork 1.37.0-motrix.6

本版本将所有分发形态（Desktop / Server / Docker / Flatpak）统一到自维护的 fork 基线 1.37.0-motrix.6。这与仓库中的特性探测逻辑一致：

• feature-report.ts 通过 --version 报告的 ^\d+\.\d+\.\d+-motrix\.\d+$ 正则识别 fork 血统，BT 特性开关的最低基线为 1.37.0；
• fork 契约在 1.37.0-motrix.3 后调整了 gid 解析语义，因此 hasDurableRemoveSemantics() 要求 base 版本不低于 1.37.0 且 fork patch 不小于 3，1.37.0-motrix.6 自然满足这一要求；
• Server 与 Docker 不再依赖系统自带的 aria2 可执行文件，而是内置经过校验的 Motrix 二进制，从而保证桌面与无头部署下行为一致。

下载性能预置档：从 Auto 到 64 连接

设置页新增 Automatic、Balanced、High speed、Maximum、Custom 五档性能预置。其真实取值集中在 engine-performance-profiles.ts，统一管理四个维度：单服务器最大连接数（maxConnectionPerServer）、分段数（split）、最小分段大小（minSplitSize）、磁盘缓存（diskCache）。

预置档	maxConnectionPerServer	split	minSplitSize	diskCache
auto	64（MAX_CONNECTIONS_PER_SERVER）	16	4 MB	32 MB
balanced	16	16	10 MB	32 MB
high	32	32	4 MB	64 MB
maximum	64	64	1 MB	64 MB
custom	由用户自定义	—	—	—

源码层面的要点：

• 常量 MAX_CONNECTIONS_PER_SERVER = 64 是所有档位的硬上限（engine-performance-profiles.ts）；
• ENGINE_PERFORMANCE_PROFILE_IDS 以 as const 收敛可选值，非法档位在类型层即被拦截；
• applyEnginePerformanceProfile() 会把非 custom 档位对应的四个键直接合并进设置对象，custom 则保留用户原始值（实现见这里）。

Automatic 档位的特殊之处在于启动时进行磁盘感知调优：入口 get-tuning-recommendation.ts 先对下载目录执行 probePrecise() 精确磁盘探测，再把下载路径、总大小、协议、是否多文件等上下文交给 aria2 侧的 recommend() 生成建议值。这使 auto 档在不同存储介质（HDD/SSD/网络盘）上得到差异化的缓存与分段建议，而不是套用一个固定参数。

设置先保存、再重启：重启语义与热应用边界

v2 的设置写入遵循「设置总是先保存，shell 再决定是否提示重启」的顺序：SettingsManager.update() 先持久化，再通过结果中的 requiresAppRestart 上报给命令处理层（见 settings-manager.ts 与 UpdateResult 定义）。需要引擎级重启的键集中在 restart-keys.ts：

'performanceProfile', 'rpcPort', 'rpcSecret', 'listenPort', 'dhtListenPort',
'dhtEnabled', 'fileAllocation', 'diskCache', 'sqlite3Persistence',
'sqlite3DbPath', 'sqlite3HistoryLimit', 'sessionSaveInterval'

其余 EngineSettings 键走热应用路径（经 SpeedLimitController / proxy / tracker 的 changeGlobalOption 直接下发）。连接数、文件分配（allocation）与缓存选择因此可以在保存并重新启动后保持前后一致，不会出现「改了没生效」或「重启后回退」的状态漂移。目前 APP_RESTART_REQUIRED_KEYS 为空集——如 launchAtStartup 通过 syncAutoLaunch() 热应用、browserBridgeEnabled 通过 BridgeManager.setEnabled() 热应用，只有确无运行时应用手段的键才应加入该集合（注释说明）。

应用与插件日志的统一结构化脱敏边界

日志安全是本版本的重头戏，核心实现在 log-redact.ts，应用日志与插件日志共用同一条脱敏边界。脱敏目标明确：密钥、凭据、Cookie、请求体、存储值、敏感路径与 URL query 数据一律清除，同时保留可用的诊断上下文。

实现层面的手段包括：

• 统一占位符：[redacted]、路径类 [redacted-path]、对象类 [redacted-object]（见代码）；
• redactUrl() 对 URL 做结构化解构，query 等敏感部分被替换并支持超长截断（见代码）；
• 按字段名归一化匹配 LOG_URL_KEYS、存储键、代理对象、Error 的 cause 链等分类做递归脱敏；
• 引擎额外选项 redactExtraEngineOptions() 对可疑的自定义 key 整体脱敏，避免用户传入的意外字段把敏感内容带进日志；
• 对外提供两个入口：redactLogFields() 面向结构化字段，redactApplicationLogArguments() 面向应用日志参数（见代码 与 见代码）。

一旦脱敏过程自身异常，结果统一标记 redactionFailed，遵循「宁可失败也不泄漏」的安全取向。配套测试可参考 log-redact.test.ts。

AppImage 发布回归与用户级桌面集成

本版本恢复 Linux x64 / arm64 的 AppImage 产物，并把桌面集成改成用户可选、范围收敛的模式。首次启动时用户可以选择是否注册桌面项、图标与 motrix:、magnet:、.torrent 处理器，集成数据写入用户自己的 XDG 数据目录，之后可从设置页的 Integration 卡片随时启用、修复或移除——渲染侧对应 appimage-integration-section.tsx 测试中出现的 "Enable/Remove desktop integration" 状态机。

平台的判定逻辑在 appimage-integration-host.ts：只有 Linux 且设置了 process.env.APPIMAGE 才视为 AppImage 运行环境；主进程侧 isAppImage 也以此判断（见 src/main/index.ts）。

需要注意两个边界：

• AppImage 暂不支持浏览器扩展交接：因为其 Native Messaging host 在挂载镜像之外没有稳定路径；
• Flatpak 单独验证，不随 release tag 发布，但 GitHub prerelease 会附带其 Native Host companion 归档。

发布装配：AppImage 优先元数据的兼容归一

针对 beta.20 的发布阻断问题，beta.21 在装配层做了两件事：一是接受 electron-builder 生成的 AppImage 优先（AppImage-first）的 Linux 更新源元数据，对每个被引用的 Linux 资产做校验；二是为更新器额外产出基于 DEB 的兼容字段。最终发布验证依旧保持严格，涉及装配与产物验收的工程化细节可以参考仓库 scripts 下各类 verify-*.mjs 与 assemble-release-artifacts.mjs。

引擎恢复与任务计数语义的可靠性改进

围绕引擎中断后的自愈，本版本还包含一组较小的行为修正，共同服务于「恢复后状态与中断前一致」：

• 引擎中断前缓存的 tracker 状态在恢复后重新应用；
• 对预期中的引擎关闭错误做抑制，不再误报为故障；
• NAT 映射在发现之后自动重试（相关实现见 core/nat 目录的 settings-nat-provider）；
• 下载计数以 Motrix 任务状态为准，避免引擎侧内部状态与 UI 展示脱节（涉及 core/task 下的状态与计数逻辑）。

窗口外观：28px 标题栏控制与安全区

Windows 与 Linux 的标题栏控制按钮统一为 28px 的点击目标，并同侧边栏、面板动作按钮对齐；Toast 与内容区域的安全区（safe area）计算适配了自定义窗口装饰（custom window chrome），避免自定义标题栏遮挡可交互内容。相关实现与窗口管理代码位于 src/main/window 与 src/renderer 的布局与组件层。

计划产物与镜像引用

发布说明同时预告了门禁全部通过后的产物矩阵：

分发目标	架构	计划产物
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.21-linux-<arch>.tar.gz
Docker Hub / GHCR	linux/amd64、linux/arm64	两个 registry 中不可变的 2.0.0-beta.21 tag
Snap Store	—	本 beta 不发布

容器门禁全部通过后，版本化镜像引用将是 docker.io/motrixapp/motrix-server:2.0.0-beta.21 与 ghcr.io/agalwood/motrix-server:2.0.0-beta.21。存储、网络与升级指引可阅读仓库内的 Docker Server 部署指南。

分发注意事项

• AppImage 桌面集成为可选项，仅写入当前用户的 XDG 数据目录；
• Windows arm64 与全部 32 位包不可用；
• Windows 安装包未签名，可能触发 SmartScreen 警告，应仅从官方正式发布的 prerelease 页面下载；
• beta 容器 tag 不可变，不会更新 latest、stable 等浮动 tag；
• Snap 本 beta 不发布，预发布 Snap 流水线在源码验证后即停止，不会构建工件或改动 latest/edge。

反馈与复现建议

遇到可复现的问题时，发布说明建议通过项目 Issues 反馈，并附上操作系统、架构、包类型与最小复现步骤。需要说明的是，本 beta 的一切结论均以仓库当前内容为准：本文涉及的全部代码、常量与测试都可在 src/shared/constants/engine-performance-profiles.ts、src/shared/constants/restart-keys.ts、src/core/engine/aria2/aria2-trust-store.ts 与 src/core/log-redact.ts 中直接核对。