Motrix 2.0.0-beta.17 发布工程解析：容器发布门禁恢复与双 Registry 原生发布工作流

Motrix 2.0.0-beta.17（Motrix Turbo 系列）的核心看点并不在新增功能，而是一次对容器发布管线的治理级修复：它终结了 beta.16 因 Docker Hub 仓库描述修改请求返回 HTTP 403 而导致的"最终公开 runtime 校验矩阵未运行"的遗留问题，并沉淀出一套"原生架构构建 → 按内容寻址 digest 暂存 → 跨 Registry 一致性核验 → 签名 → 原生 runtime smoke → 最后推进浮动别名"的完整发布纪律。本文以官方发布说明为骨架，结合仓库中的 .github/workflows/release.yml、容器发布相关脚本与 Docker Server 部署指南 源码证据，逐段拆解这次发布到底改了什么、发布门禁如何 fail-closed、镜像 tag 语义如何设计，以及测试者应当注意的边界与限制。

beta.17 的由来：beta.16 遗留的"非 artifact 失败"

理解 beta.17，首先要回到它的前身。仓库保留了完整的 beta.16 发布记录（含 简体中文版），其中明确记载：beta.16 的桌面五平台构建、三个 Finalize 任务、assembling、GitHub 预发布版与 R2 更新数据源均已成功，两个原生平台容器 linux/amd64 与 linux/arm64 也已在各自原生 runner 上完成构建并通过双 Registry 的匿名拉取 smoke。

真正的断裂点发生在最后的 finalize 阶段：一个更新 Docker Hub 仓库描述（repository description）的非 artifact 请求返回了 HTTP 403。由于该请求仍属于 finalize job 的一部分，job 整体失败，导致两个本应在原生 runner 上、针对两个 Registry 中的最终已签名 digest 运行的 linux/amd64 / linux/arm64 最终公开 runtime 矩阵任务被跳过。

值得注意的是，beta.16 的容器 index 事实上是"公开且已签名"的，但它不完整——并非所有最终容器门禁都通过，因此官方记录明确要求不得将其描述为 fully verified。同时，不可变的 v2.0.0-beta.16 tag 不会被移动、复用或回填。

beta.17 的定位正是"对 beta.16 已发布并签名了两个 Registry 容器 index 之后才出现的非 artifact 失败进行修复"，且同样不移动、不复用不可变的 v2.0.0-beta.16 tag。从当前 package.json 看，仓库主版本线已演进到更高的 2.0.0-beta.28，说明这组发布门禁机制在此后一直作为稳定基线被沿用。

发布门禁恢复：四项具体变更

针对上述故障根因，beta.17 在发布权威（release authority）层面做了四项收紧，全部可以在 release.yml 中得到印证：

1. 移除 Docker Hub 仓库描述修改。发布说明给出的理由是：仓库的 description 与 overview 属于"发布者元数据（publisher metadata）"，并非带版本号的 OCI artifact，其管理边界（administrative access boundary）与镜像发布相互独立，不应混入以镜像发布为目的的 finalize 权限上下文中。翻阅 release.yml 的 publish-container job，其步骤仅包含镜像登录（docker/login-action）、Buildx、下载平台元数据、核验、创建/修复不可变 index、签名与验证，确实不存在对 Docker Hub HTTP API 的仓库描述写入调用。

2. 将匿名签名验证置为唯一容器 finalize job 的最后一步。这样一来，finalize 一旦成功，其"已验证的 digest"可以直接交接给原生公开 runtime 矩阵，中间不再夹杂任何其他可能失败的、与 artifact 无关的管理类请求。这正是对 beta.16 故障点（描述更新请求与签名共处于同一 job）的结构性消除。

3. 新增 workflow contract。如果被移除的 Docker Hub 登录路径、仓库描述 payload 或描述步骤再次出现在安全关键的发布路径上，检查会直接拒绝（reject），防止历史故障模式被意外"回填"进发布流。

4. 保持失败可见并 fail-closed。本次改动不使用 continue-on-error，不削弱 artifact、签名、provenance、SBOM、platform、匿名拉取或 runtime 任一检查，也不扩大发布访问范围。在实现层面，release.yml 各关键 job 大量使用 set -euo pipefail 与显式 [[ ... ]] 断言，任何一步异常都会让 job 直接失败而非吞掉错误。

原生容器发布流水线：从暂存 digest 到签名 index 的全链路门禁

beta.17 发布说明中篇幅最大、也最能体现工程约束的，是"原生容器发布（Native container publication）"一节。它对应的实际实现是 release.yml 中一串严格串行、互为前置的 job。以下按真实执行顺序展开，每一条说明都能在 workflow 中找到对应 step。

第一步：检查发布状态（plan-container-publication）

plan-container-publication job 使用 docker buildx imagetools inspect 分别检查 Docker Hub 与 GHCR 上对应版本不可变 tag 的当前状态，再交给 container-publication-state.mjs 判定本次应该执行的 publication_action。这一步是整条管线的"决策入口"，决定了后续是全新构建（build）、从已验证 index 修复缺失 Registry（copy），还是接受完全一致的已有结果（resume）。这个设计直接支撑了发布说明中的可恢复性声明："一次全新发布会创建两个 index；续跑可以接受完全一致的已有结果，或从已验证的现有 index 修复缺失 registry"。

第二步：原生架构构建（build-container-platform，双平台并行）

build-container-platform job 是一个双平台矩阵：

matrix 平台	runner	备注
linux/amd64	ubuntu-22.04（GitHub-hosted，X64）	原生架构构建
linux/arm64	ubuntu-22.04-arm（GitHub-hosted，ARM64）	原生架构构建

发布说明强调"每个 job 都会在 Buildx 启动前证明 GitHub-hosted Linux runner 及其原生架构；容器发布路径不安装或调用 QEMU"。这一条在 workflow 里有硬编码校验 step（Require native GitHub-hosted Linux runner），逐一断言 runner.environment == 'github-hosted'、runner.os == 'Linux'、runner.arch 等于矩阵期望值，任何一项不满足都会在 Buildx 之前失败。

随后 docker/build-push-action 的关键参数是：

• target: runtime，对应 Dockerfile 中的 FROM node:24-alpine AS runtime 多阶段目标；
• outputs: type=image,...,push-by-digest=true,name-canonical=true,push=true，即只按无 tag、内容寻址的 OCI digest 推送，这正是"单一架构永远不会获得公开版本 tag、不能独立成为正式发布版本"的实现基础；
• provenance: mode=max 与 sbom: true，生成 max-level provenance 与 SBOM；
• 通过 build-args 注入 OCI_REVISION（当前 commit SHA）与 OCI_VERSION（容器版本）。

构建后紧接着是一个格式断言：digest 必须严格匹配 ^sha256:[0-9a-f]{64}$。随后为 Docker Hub 与 GHCR 各自抓取 inspect 快照与 raw index 快照，并用匿名的空 auths Docker config 对两个 Registry 上的精确暂存 digest 依次执行 smoke-server-image.mjs（180 秒超时，包含 HTTP fixture 下载、.moext 插件加载、torrent 数据等完整 Server runtime 冒烟内容）。只有两个 Registry 的 smoke 都成功后，才调用 container-platform-metadata.mjs 的 create 子命令写入平台元数据。

也就是说，"只有两个 registry smoke 都成功后才生成平台元数据"与"平台记录绑定精确版本、commit、workflow run 与 attempt、原生 runner 身份、原始 OCI index 哈希、image manifest、attestation manifest、max-level provenance 和非空 SPDX SBOM"这两条发布说明描述，均可以在该 job 的输入参数（--version/--revision/--builder-run-id/--builder-attempt/--runner-arch/--runner-environment/--runner-os 以及两组 --docker-hub-inspect/--docker-hub-index/--ghcr-inspect/--ghcr-index 快照文件）中被逐一验证。

第三步：单一 finalize job（publish-container）

publish-container job 是整个容器发布的"唯一收口点"，其 needs 声明同时包含 plan-container-publication 与 build-container-platform，且通过 always() + 逐项 needs.xxx.result == 'success' 的组合条件，保证只有完整 amd64/arm64 集合成功后才会执行。该 job 的流水线依次完成：

1. 核验完整平台构建集合：下载两份平台元数据后运行 container-platform-metadata.mjs verify-set。发布说明中"缺失、重复、意外、架构串线、共用、歧义、冲突或未来 attempt 数据会在创建任一版本 tag 前 fail-closed"即对应此步——任何不符合"本 run 的 amd64 + arm64 恰好各一份"的数据形态都会中止。

2. Finalize 前重新检查两个不可变 tag：再次 imagetools inspect 两个 Registry 的版本 tag，重新解析 finalization state。根据上一步的判定，分三种路径执行：

   • 全新发布：docker buildx imagetools create --tag <repo>:<version> <repo>@<amd64-digest> <repo>@<arm64-digest>，在两个 Registry 各创建一个多平台 index；
   • 修复缺失 Registry（copy）：在创建版本 tag 前，先用 verify-container-publication.mjs 对源 digest 的 inspect、index、SBOM、provenance 与平台元数据做一致性核验，再从已验证的现有 index 复制到缺失的 Registry；
   • 续跑（resume）：接受完全一致的已有结果。

3. 强制收敛断言：重新 inspect 两个 tag 后再次运行 publication-state 解析，随后有一个名为 Refuse a non-resumable immutable result 的 step，只有解析结果严格等于 resume 才算收敛，否则直接失败。这从机制上保证了不可变 tag 不会被"部分创建后含混通过"。

4. 签名前匿名校验：在签名之前，用匿名的 DOCKER_CONFIG 对两个 Registry 上最终 digest 的 inspect、raw index、SBOM、Provenance 全部抓取快照，交给 verify-container-publication.mjs 校验——要求 Docker Hub 与 GHCR 暴露相同的最终 index digest、platform manifest、attestation manifest、provenance 与 SBOM 集合。

5. 签名与匿名验签：使用 cosign sign 以 GitHub OIDC 身份对两个 Registry 的同一最终 digest 签名，随后 cosign verify 用 --certificate-identity（绑定 release.yml@refs/tags/<tag>）与 OIDC issuer https://token.actions.githubusercontent.com 在匿名环境下验签，并内置 18 次、每次间隔 10 秒的可见性重试。

到这里，"把匿名签名验证作为唯一容器 finalize job 的最后一步"就有了完整闭环：签名验证是 finalize 的最后一个动作，成功后 digest 直接交接给下一步的原生公开 runtime 矩阵。

第四步：最终公开 runtime 校验矩阵（verify-container-runtime）

verify-container-runtime job 再次回到双平台矩阵（linux/amd64 on ubuntu-22.04、linux/arm64 on ubuntu-22.04-arm），同样先断言原生 GitHub-hosted runner 架构，然后以匿名 config 对两个 Registry 中精确的已签名 digest（PUBLISHED_DIGEST 来自 finalize job 输出）分别运行完整的 smoke-server-image.mjs。这就是 beta.16 未能完成、beta.17 得以恢复的"最终公开 Server runtime smoke"。

第五步：稳定浮动别名推进（promote-container-aliases，仅稳定版）

promote-container-aliases job 是整条链上最后一个 job，且带有一个决定性条件：needs.preflight.outputs.container_prerelease != 'true'。也就是说，只有非预发布（stable）版本才会走到这里。

这与 container-release-metadata.mjs 的版本语义完全一致：该脚本对预发布版本（prerelease）返回空的 floatingTags，只保留 immutableTag: version；对稳定版本则生成 [major.minor, major, 'stable', 'latest'] 四枚浮动 tag（乘以 Docker Hub 与 GHCR 两个 Registry，正好对应 workflow 中 (( ${#dockerhub_tags[@]} == 8 ))、(( ${#ghcr_tags[@]} == 8 )) 的断言）。因此发布说明中"稳定版浮动 alias 只由最后一个可恢复 job 推进，且必须等全部构建、index、签名、provenance、SBOM、匿名拉取和 runtime 门禁通过；beta 只发布不可变版本 tag，beta.17 不更新 latest、stable"的表述，可以从脚本与 workflow 双重得到印证。

推广到一般 tag 语义，Docker Server 部署指南 中的表格给出了完整参考：

Reference	Behavior	Recommended use
:2.3.4	不可变发布 tag	生产与回滚
:2.3	2.3 线最新稳定补丁	自动补丁升级
:2	大版本 2 内最新稳定	自动 minor/patch 升级
:stable	最新稳定版	明确使用稳定通道的用户
:latest	与 stable 相同 digest	NAS UI 默认
:2.3.4-beta.2	不可变预发布 tag	仅评估用途

预发布版本永远不会推进 2.3、2、stable 或 latest；两个 Registry 收到同一不可变 manifest digest 后，浮动 tag 才可能被推进。

各发布渠道：独立门禁，不宣称跨渠道原子性

需要特别说明的是，上述容器管线只是 Motrix 发布矩阵的一个渠道。GitHub 预发布版、R2 更新数据源（见 release.yml 的 publish-feed job）、容器 Registry 与 Snap Store 是各自独立门禁的发布渠道，每个渠道都有自己的安全检查与恢复规则。发布说明明确：beta.17 不宣称跨渠道原子性。这也解释了为什么 beta.16 虽然容器 index 已签名公开，但整体发布仍不被视为完整——渠道之间没有"要么全成、要么全不动"的原子承诺。

Snap beta 策略：预发布 run 止步于源码校验

Snap 不属于 beta.17 的分发范围。发布说明给出的策略是：受保护的预发布 Snap run 会在 source validation 后停止，因此不会构建 Snap artifact、上传 Store revision 或修改 latest/edge。

这与仓库中 .github/workflows/snap.yml 的结构吻合：该 workflow 的 preflight job 名为 Validate Snap source，负责校验 release 元数据（通过 release-metadata.mjs 解析 package.json 的 SemVer）并确认 tag commit 在 main 上；而发布到 Store 的权限与 job 受到更严格的触发条件约束。从设计意图看（见该文件头部注释），Snap 发布走的是"受保护 tag 发布双架构构建集到 latest/edge、显式受保护 main 手动 run 可恢复 edge 发布、candidate 与 stable 通过 snap-promote.yml 承接"的独立通道，预发布 beta 被显式排除在构建与上传之外。

软件背景：beta.17 装载了什么

虽然 beta.17 发布说明的重心在发布治理，但它同时概述了 Motrix Turbo 这条产品线的软件形态，作为了解"容器里到底跑什么"的必要背景（也为想测试的读者框定范围）：

• 桌面端全面重建：基于 Electron 43、React 19 与 TypeScript 7 从零构建（release.yml 中可见 pnpm 11、Node.js 24、electron-builder 26.x、macOS 部署目标 12.0 等运行时约束），提供可自定义 Dashboard、深色模式、跨平台应用菜单与更清晰的任务检查器反馈。
• 宿主无关的统一下载内核：桌面应用与 Node/Web Server 共享同一套下载内核（对应仓库中的 src/core/engine、src/core/session、src/core/tracker、src/core/nat 等模块），支持 SQLite session 恢复、Tracker 管理、UPnP/NAT-PMP，以及 HTTP、FTP、BitTorrent 和磁力链接下载。
• MDXP 集成：官方 CLI 与浏览器任务交接统一走 MDXP 桥接协议，支持本地发现与远程 Server 实例的 device-code 配对（对应 src/core/bridge 与 src/main/bridge）。
• QuickJS 插件沙箱：带能力授权（capability consent）、内置 builtin 插件与应用内插件市场（对应 src/core/plugin 下的 capabilities、grants、host、install 等子模块）。
• 面向 NAS 与家庭服务器的持久化多平台 Server 容器：即上文整条发布管线要交付的产物——由 Dockerfile 的 runtime 多阶段目标构建，采用非 root 运行、内置带校验和的 motrixapp/aria2 fork 以承载 SQLite 持久化契约，详见 Docker Server 部署指南。

测试前须知

这是预发布软件。安装前请备份现有 Motrix 应用数据和下载文件：

• Motrix v1 数据的迁移路径尚未经过验证，请勿让本 beta 使用你唯一一份 v1 数据；
• 条件允许时，建议通过独立系统账户、独立设备或独立 Docker 数据目录，与现有环境并行测试 v2；
• 不要让本 beta 成为你重要下载文件的唯一存储位置。

测试者应在容器门禁通过后按官方发布渠道获取产物，并理解镜像 tag 不可变、不推进稳定别名这一前提。

发布门禁通过后的计划下载

beta.17 计划的分发矩阵（来源：发布说明原表，镜像引用与 tag 语义经 docs/docker-server.md 佐证）：

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

全部容器门禁通过后，带版本的镜像引用将是：

docker.io/motrixapp/motrix-server:2.0.0-beta.17
ghcr.io/agalwood/motrix-server:2.0.0-beta.17

其中 Docker Hub 与 GHCR 两个仓库名（motrixapp/motrix-server、agalwood/motrix-server）以及"同一个 index digest 双 Registry 一致"的契约，硬编码在 container-release-metadata.mjs 的 CONTAINER_REPOSITORIES 常量中。关于数据持久化、存储、网络与升级方法，请阅读 Docker Server 部署指南（另有 简体中文版）。

已知发布限制

beta.17 的已知分发限制（完整继承自发布说明，未做增删）：

• 本 beta 不发布 AppImage；
• Flatpak 会单独验证，不会随版本 tag 发布；GitHub 预发布版只包含其 Native Host 配套程序压缩包；
• 不提供 Windows arm64 和任何 32 位安装包；
• Windows 安装包未签名，可能触发 Windows SmartScreen 警告，应仅在正式发布后从官方预发布渠道下载；
• Beta 容器 tag 不可变，不会更新 latest、stable 或其他稳定浮动 tag；
• Snap 不随本 beta 发布，预发布 Snap run 在 source validation 后停止，不构建也不发布 Snap artifact。

小结

Motrix 2.0.0-beta.17 的发布说明，本质上是一份"发布管线如何自我纠错"的工程文档。通过移除发布者元数据写入、把匿名验签固化为 finalize 的最后一步、以 workflow contract 封死故障路径的回流，它让容器发布管线收敛为一条纯粹的、可由原生产物驱动的链：原生构建 → digest 暂存 → 双 Registry 匿名 smoke → 平台元数据 → 集合核验 → 不可变 index 创建/修复 → 跨 Registry 一致性校验 → 签名与匿名验签 → 原生 runtime 校验 →（仅稳定版）最后推进浮动别名。整条链在设计上显式选择了 fail-closed 与"不宣称跨渠道原子性"，而这种克制本身，正是它最值得借鉴的部分。