ADR-0427：完整跨镜像发布集与部署 Digest Lock

状态：Accepted
日期：2026-08-16
关联 RFC：QL-RFC-0001 D-03、D-14、D-333、D-334、D-335

上下文

D-333 已把发布候选拆成 local|cluster|all 三个 deployment-family scope，并让每个镜像在原生 amd64/arm64 build、OS 漏洞扫描、OCI 合并、Cosign 与四类 GitHub attestation 后独立回读验证。但矩阵 publisher 过去会在各自验证完成后立即写 version/source tag。五个仓库之间没有事务，后续镜像失败时，部署者可能看到只覆盖部分候选的同版本标签，也没有一个能同时冻结 scope、source revision 和所有镜像 digest 的部署输入。

决策

每个 publisher 只发布不可变 digest，不再写 version/source tag。完成远端 manifest、Cosign、四类 GitHub attestation 和适用的 Local profile rollout 验证后，生成一个 canonical、no-replace、mode 0600 的 qinglong/release-set-image-record@v1。
image record 必须绑定同一个 source-derived release candidate digest、scope、version、source ref/revision、 lowercase repository owner、repository、双架构、immutable reference 和自身 SHA-256。矩阵 job 只保留同一 run_id/run_attempt 的短期 record artifact。
唯一 release-set job 必须等待整个 publish matrix 成功，重新从 exact tag source 创建并审计 candidate，下载同一次 workflow attempt 的全部 record，并要求 record 集与 candidate image 集精确闭合、无遗漏、无重复、顺序与 candidate 一致。
聚合结果为 qinglong/release-set@v1，按 local 与 cluster deployment family 列出 exact digest reference、 version/source tag、platform 和 image-record digest。local scope 只包含 Local image；cluster scope 包含 control、control-ai、worker、admin；all 同时闭合两族。
只有 release set 独立重算审计成功后才允许统一 promotion。promoter 先回读所有 source digest 和已有 tag： tag 若已指向其他 digest 则失败；缺失 tag 才执行 digest-to-tag copy；每次写入后必须再次解析为 release-set digest。
不宣称 GHCR 跨 repository tag write 具有原子性。恢复模型明确为 verify_exact_digest_then_continue：失败重跑先验证已存在 tag，只有相同 digest 才继续补齐其余 tag。 workflow concurrency 只串行化同一 release ref，外部写入仍由 conflict preflight 失败关闭。
完整 release-set JSON 使用 GitHub file provenance attestation，并作为 90 天、no-overwrite 的 deployment digest-lock artifact 发布。生产部署必须从该文件取 @sha256: reference；version/source tag 只用于发现和人类导航，不能成为 rollout authority。

部署与资源影响

Edge/Standalone 路由设备只下载并解析 local release set，不需要 Cluster 镜像、Kubernetes、数据库或发布工具；运行时 artifact、模块数和常驻资源预算不变。
Cluster 节点使用 cluster release set，同时锁定四个角色镜像；release-set job 只存在于发布 CI，不新增 Pod、controller、listener、timer、watcher、Pool、schema、migration 或 SQL。
all 是维护者同时发布两族的便利 scope，不把 Local 部署依赖于 Cluster 私有证据，也不要求单个设备拉取五个镜像。

被拒绝的替代方案

每个矩阵 job 验证后立即打标签

拒绝。单镜像证据正确不等于 deployment family 完整；部分成功会暴露同版本的混合状态。

假设多个 GHCR repository 的 tag promotion 原子

拒绝。registry 没有本 workflow 可用的跨仓库事务。显式、可重入的 digest preflight 比虚构原子性更可靠。

让部署继续只引用 version tag

拒绝。tag 可变且无法表达同一 source candidate 下的跨镜像闭包。生产 rollout 必须使用 release set 中的 immutable digest。

为 release-set 增加常驻发布协调服务

拒绝。该问题属于低频发布控制面，GitHub Actions 的有界终态 job 足够；常驻服务会给低配用户和集群都增加不必要的新故障域。

验证

contract 覆盖 Local/Cluster/All 聚合、缺失/重复/跨候选 record、owner/digest/report drift、symlink、额外文件、 closed CLI、no-replace 与独立 audit；
workflow 静态门要求 per-image publisher 不再 promotion、record 位于全部验证之后、same-run attempt 下载、 publish matrix 全成功、独立 aggregate/audit、checksum-pinned copier、先全量 preflight 后 promotion、最终 file attestation 和 90 天 artifact；
release-set contract/workflow 定向门 73/73，连同 Admin Console distribution 交叉审计为 77/77；backend 1,264 pass/2 条件 skip/0 fail，18-package clean build/test 退出 0；package boundary 仍为 18 packages、无 single-source/shallow package，dependency、Edge import、Cluster/Worker deployment、image release 与 Local image 审计均 compatible；
14 档 Local artifact 全部 compatible，默认 Edge/Standalone 为 2,589,890/2,589,968 bytes、315 files、 56 modules，application+AI 为 4,493,043/4,493,175 bytes，MCP 为 7,315,930/7,316,038 bytes；Cluster Admin pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked；
本 Gate 不修改 schema、migration、SQL、role、Pool、连接或 HA 拓扑，因此复用 D-331/D-333 PostgreSQL 18.6 arm64 142/142、timeline 1→2 基线，不把未重跑的数据库门冒充本阶段新证据；
本 ADR 接受的是源码、契约和 workflow 门。公开 tag 尚未运行时，不宣称真实 GHCR promotion、Cosign 或 GitHub attestation 已成功；它们必须由实际 release run 取得。

5.7 KiB Raw Permalink Blame History Unescape Escape