qinglong/docs/operations/ql3-release-set-deployment.md

QingLong 3.0 release-set 部署准入

生产部署的镜像 authority 是成功 ql3-image-release.yml 运行产生的 ql3-release-set-<version>-<scope> artifact，不是可变 version/source tag。下载后先验证该 JSON 的 GitHub file provenance，确认 repository、source tag、source revision 与目标发布一致，再从 images[].reference 读取完整 ghcr.io/<owner>/<repository>@sha256:<digest>。

选择 scope

部署类型	release scope	必须出现的镜像
低配路由器、Edge、Standalone	local	local
Kubernetes/Cluster	cluster	control、control-ai、worker、admin
同时发布两族	all	上述五个镜像

Local 用户不需要下载 Cluster 镜像，也不依赖 CloudNativePG 或 Worker 私有发布证据。Cluster 运维者不能拿 Local image 的证明替代任一角色镜像；尤其 Worker 与短生命周期 Admin 必须有各自 digest。

准入检查

1. 只接受来自成功、未重跑替换的同一 release workflow attempt 的 artifact，并验证 release-set 文件 provenance。
2. schema 必须为 qinglong/release-set@v1；release.version、release.sourceRef、 release.sourceRevision、release.scope 必须与变更单一致。
3. 镜像集合必须与上表精确相等；每个 reference 必须是 digest reference，且 owner/repository 与部署目标一致。
4. Kubernetes overlay 用 newName 加 digest 或等价的 immutable image reference；不得把生产 placeholder 改成 newTag。Local compose/rollout 同样固定 @sha256:。
5. rollout 前再次向 registry 解析 version/source tag。它们可以用于发现，但只有解析到 release set 的同一 digest 才算一致；部署仍以 digest 为准。

发布失败与恢复

GHCR 不提供跨 repository tag 事务，release set 明确记录 crossRepositoryAtomicity=false。如果 promotion 中途 失败，不删除已经正确的 tag，也不重新构建镜像。使用原 source tag/revision 重跑 release workflow：它会先验证 每个 source digest 和既有 tag；既有 tag 指向同一 digest 时继续，指向其他 digest 时立即失败。只有最终 release-set artifact 和 provenance 都生成后，才能宣布该 deployment family 可部署。

workflow artifact 当前保留 90 天，因此长期归档属于 release owner 的外部职责。进入稳定 GA 前，应把经验证的 release-set 同步到不可变、保留期满足组织策略的发布档案；同步过程不得改写 JSON。