qinglong/docs/adr/ADR-0424-external-cluster-admin-release-workstation-ceremony.md

ADR-0424：外部工作站 Cluster Admin Release Ceremony

• 状态：Proposed
• 日期：2026-08-16
• 关联 RFC：QL-RFC-0001 D-332、Phase 2
• 扩展：ADR-0420、ADR-0423

背景

ADR-0420 已固定 Cluster Console 只随 signed multi-architecture Admin OCI 分发，ADR-0423 已在真实本地镜像中证明离线 evidence verifier 能在严格资源与 authority 边界内运行。但源码审计、stub release verifier 测试和本地构建镜像都 不能证明一个公开发布 digest 确实由预期 GitHub Actions workflow 生成，也不能 证明签名、provenance、SBOM、OS vulnerability evidence 与最终拉取的镜像是同一 对象。

公开 release 的验证发生在 operator workstation，具有 registry、GitHub attestation service、transparency log、本地 Docker daemon 和短期 GitHub token 等外部条件。它不能伪装成可离线复现的单元测试，也不能把本地执行报告升级为 服务端证明或行动权限。

决策

1. 在 exact reviewed v3.* source tag 提供 ql3-cluster-admin-release-workstation-ceremony.cjs。输入必须精确绑定 ghcr.io/<owner>/qinglong3-cluster-admin@sha256:<digest>、owner/repo、40-hex source revision、完整 refs/tags/v3.* ref，以及 canonical absolute cosign、gh、docker、短期 token file 和新 report path；mutable tag、branch ref、owner 漂移、symlink、group/other-writable executable 或已存在输出均失败关闭。
2. 三个外部工具按绝对路径直接执行，不经 shell 或 ambient PATH。GitHub token 必须来自 current-owner 0600 bounded file，只注入四个 gh attestation verify 子进程；不得进入 argv、cosign/docker 环境、报告或失败输出。工具在执行前后 复验 device/inode/size/SHA-256，降低 ceremony 中途替换风险。
3. ceremony 精确执行一次 keyless signature 验证，以及绑定 release workflow、 source digest、source tag、非 self-hosted runner 和 OCI bundle 的 provenance、 CycloneDX、OS-vulnerability、source-derived release-candidate contract 四类 GitHub attestation 验证。随后拉取同一 digest， 要求本地 image inspection 的 Linux amd64|arm64 RepoDigests 包含精确输入。
4. ceremony 使用固定、非敏感、单条 run_read redacted evidence vector 检验最终 release image 内的第 11 个 evidence-verify 产品命令。该容器使用 non-root UID/GID 10001、read-only root、network none、drop ALL、no-new-privileges、 128 MiB、0.25 CPU 与 32 PIDs，只读挂载 vector；输出必须与独立 verifier 的 exact no-authority result 一致，vector inode/size/mtime/digest 前后不变。
5. 成功只新建一个 current-owner 0600、two-space canonical JSON 报告。报告保留 public release identity、工具 SHA-256/size、八步 argv/stdout/stderr digest 与字节数、 verification/isolation 结果和自身 canonical SHA-256，不保留原始工具输出、token、 executable path 或 workstation identity。它明确声明 reportAttestation=none、actionAuthority=none。
6. 独立 offline audit 使用 no-follow stable read 校验报告 canonical encoding、exact shape、expected release identity、工具与八步 transcript digest、一致的 isolation/ limitation 以及顶层 digest。其结果固定为 externalResults=not_replayed；离线审计 不能证明外部命令确实运行，也不能重放某一历史时点的 registry、GitHub 或 transparency-log 状态。
7. ceremony 与 auditor 保留在根 scripts/，不新拆 workspace package、不加入 Admin image，从而避免“用待验证镜像验证自身”的循环，也不进入 Edge、Standalone、 AI、MCP Local artifact、Kubernetes workload、数据库或常驻服务闭包。

不选择

• 只保留 verify-release.sh 的布尔输出：适合人工快速检查，但缺少工具固定、 最终 pull/inspect、镜像内 verifier smoke 与可独立审计的 digest-level transcript。
• 保存完整 cosign/gh 输出：会不必要地扩大身份、registry metadata 和未来 输出格式的泄漏面，也让报告兼容性依赖外部工具展示层。
• 把 token 交给全部子进程或继承完整环境：扩大 credential 与 ambient authority 暴露，且降低 ceremony 可解释性。
• 把 runner 烘焙进 Admin image：产生自验证循环，并迫使运行容器获得 Docker daemon 与 registry authority。
• 把本地报告签成 QingLong authority：工作站报告只记录一次观察，不是 release workflow attestation、Cluster durable audit 或 action approval。

验收

1. stub ceremony 必须证明精确 1 次 signature、3 次 attestation、1 次 immutable pull、1 次 digest inspection、1 次隔离 verifier；token 只出现在 gh 环境，报告 为 0600、不泄漏 token 且不覆盖现有文件。
2. mutable image、branch ref、source revision/owner drift、tool failure、executable drift、非私有 token/report、verifier 输出漂移或 vector mutation 必须失败关闭， 失败输出不得包含路径、输入或外部工具 transcript。
3. offline audit 必须接受真实 canonical report，并拒绝 tamper、即使重新计算顶层 digest 的 claim/isolation/shape 扩宽、expected release swapping、noncanonical JSON、 symlink 与权限漂移。
4. Console distribution audit、Cluster Admin、18-package、backend、npm pack、依赖/ deployment/release 以及 14 档 Local artifact 门必须通过；package 总数与低配设备 默认 Edge/Standalone artifact 必须保持不变。
5. 必须从公开 v3.* release 获取真实 immutable Admin digest，并在装有真实 cosign、authenticated gh 和 Docker 的外部工作站完成 ceremony 与独立 audit， 才能把本 ADR 从 Proposed 改为 Accepted。

当前状态

截至 2026-08-16，本地仓库没有 v3.* tag，开发工作站未安装 gh 与 cosign， 且项目公开 GitHub Releases 尚无可供输入的 3.0 release digest。因此本门只可完成 runner、auditor、negative contract、资源与 artifact 回归；不得用 stub 或本地 d332-local 镜像伪造第 5 条外部验收。发布 digest 可用后，按本 ADR 记录真实 report digest、工具 digest 与外部审计结果，再独立接受本决策。

实现门结果

2026-08-16，D-332 已完成可在发布后直接执行的实现门，但没有改变本 ADR 的 Proposed 状态：

• runner/stub tools、独立 offline auditor、原 release verifier 与 Console distribution 定向门全部通过；覆盖精确 signature/attestation/pull/inspect/run argv、token 仅注入 gh、tool drift、权限扩宽、no-replace、结构重签与 expected identity swapping 等正负路径。
• backend 全量为 1,233 pass、2 条件 skip、0 fail；Cluster Admin 为 387 pass、 3 条件 skip、0 fail；18-package clean build/test 退出 0。沙箱内 loopback listener 的 EPERM 已通过同命令非沙箱重跑消除，不记作产品失败。
• workspace 继续为 18 packages，singleSourcePackages=[]、 shallowSourcePackages=[]；Cluster dependency、Edge import、Cluster deployment、 image release、OS vulnerability、Console 与 distribution 审计均 compatible。
• Cluster Admin npm pack 保持 250 files、271,238-byte tarball、1,690,196-byte unpacked；D-332 的根脚本和 ADR 没有进入 npm/OCI 产品内容。
• 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。
• 本门没有 schema、migration、SQL、role、Pool 或连接拓扑变化，因此不重复冒充 PostgreSQL HA 执行；继续复用紧邻 D-331 已通过的 PostgreSQL 18.6 arm64 142/142、timeline 1→2 物理 HA 基线。唯一未满足项仍是第 5 条真实公开 release digest 外部 ceremony。