feat(ql3): close cross-profile alpha stage index

This commit is contained in:
whyour
2026-08-28 01:07:04 +08:00
parent 07d1dd97c1
commit 82d74cf56f
9 changed files with 1167 additions and 2 deletions
+5
View File
@@ -13,6 +13,8 @@
`Local Alpha Trial Kit + Local milestone index` 是本阶段的用户可试运行产物;`Cluster Integration Candidate + Cluster milestone index` 是集群部署者可下载、可离线验真的集成产物。单个 headless runtime、单个 Cluster archive 或没有 milestone index 的部分矩阵产物都只是工程中间件。Cluster milestone 仍不满足正式 Kubernetes deployment-lock 的 GHCR immutable digest 与 catalog provenance。
当维护者显式选择 `alpha_artifact_scope=all` 时,还会生成 `Alpha stage index`。它把同一次 run 的 Local/Cluster milestone 交叉绑定,并为 Edge、Standalone、Cluster 给出目标架构的最小 artifact 选择;这是阶段交付导航,不是正式 release catalog。只生成 Local 或 Cluster 时,各自 milestone 仍可独立成立,不制造一个不完整的总索引。
## 当前阶段实物(2026-08-27
提交 `4239464af6937d56528a0a2c573d12329bc7ca55` 已形成最新 owner-private arm64 工程候选:
@@ -36,6 +38,7 @@ ADR-0506 现要求 `qinglong/alpha-local-trial-kit@v2` 额外包含 `verificatio
- `ql3-alpha-<commit>-local-milestone`
- `ql3-alpha-<commit>-control-<arch>``control-ai-<arch>``admin-<arch>``worker-<arch>`
- `ql3-alpha-<commit>-cluster-milestone`
-`alpha_artifact_scope=all``ql3-alpha-<commit>-stage-index`
Local artifact 含:
@@ -47,6 +50,8 @@ Local artifact 含:
Cluster artifact 是每角色/架构一个六文件闭包:native Docker archive、精确 CycloneDX SBOM、workflow-bound verification evidence、README、`qinglong/alpha-cluster-image@v1` manifest 和覆盖全部内容文件的 `SHA256SUMS`。完整 CI 成功后,八个 bundle 由 `qinglong/alpha-cluster-milestone@v1` 小型索引闭合;索引本身不重复存放大 archive。
Stage index 是 `qinglong/alpha-stage-index@v1` 三文件闭包。它重新审计两个 milestone,要求 version/source/workflow SHA/ref/run/attempt 一致,并把路由/NAS 的单 Local Trial Kit 与 Cluster 的 control/admin/worker 最小集、可选 control-ai 写为机器可读选择;它不重复存放任何镜像 archive。
任何 required job 失败时不上传对应产物。artifact 名和 archive 内的 `ci-*` tag 都表示 commit-bound candidate,不能改名后冒充 `v3.x` release。
## 下载后验证与最小 smoke
+41
View File
@@ -0,0 +1,41 @@
# QingLong 3.0 Alpha 阶段交付索引
本目录是一次 `alpha_artifact_scope=all` 运行的最外层交付入口。它把同一源码、同一 GitHub Actions run/attempt 的 Local Alpha milestone 与 Cluster Alpha milestone 绑定起来,并为 Edge、Standalone 与 Cluster 部署者给出机器可读的最小下载选择。它不是正式 release catalog,也不包含 Docker archive。
## 先判断设备类型
| 设备或环境 | 选择 | 稳态组件 | 需要下载 |
| --- | --- | --- | --- |
| 低配路由器、NAS、单机 | `deploymentSelections.local` | 仅 Local ApplicationOperator 只在 setup/upgrade/recovery 短暂运行 | 目标架构的一个 Local Trial Kit |
| 临时 K3s/Kubernetes 集群 | `deploymentSelections.cluster` | control、admin、workerAI 按需增加 control-ai | 目标架构的三个 required artifact;需要 AI 时再下载 optional artifact |
不得把四个 Cluster 角色部署到低配路由器,也不需要为一台 amd64 主机下载 arm64 归档。索引固定列出十个可选择 artifact,但每个部署者只下载目标 Profile、架构和角色所需的子集。
## 验证
1. 在本目录运行 `sha256sum --check SHA256SUMS`
2. 检查 `manifest.json`
- schema 为 `qinglong/alpha-stage-index@v1`
- maturity 为 `alpha_stage_delivery_not_public_release`
- source revision、run ID/attempt 是准备验证的显式 workflow run
- `milestones.local``milestones.cluster` 分别指向同一提交的 milestone artifact。
3. 下载两个 milestone 小索引,比较各自 `manifest.json` 的长度与 SHA-256 是否等于本索引的记录。
4.`deploymentSelections` 下载目标大归档,再按对应 milestone 和 bundle README 逐层执行 checksum 与离线审计。
持有同一版本源码与 Node.js 24 时,可以一次复审三层索引:
```sh
node scripts/ql3-alpha-stage-index.cjs \
--mode=audit \
--stage=/absolute/path/to/stage-index \
--local-milestone=/absolute/path/to/local-milestone \
--cluster-milestone=/absolute/path/to/cluster-milestone
```
该命令拒绝跨 source、version、run/attempt 混用,重新执行两个 milestone auditor,并核对 milestone manifest digest 与部署选择。它不访问 Docker 或网络,也不会重新执行漏洞扫描、真实用户旅程或 Kubernetes live gate。
## 成熟度和回退边界
本索引只证明一次显式 Alpha 运行同时形成了两个部署档位的闭合候选物。Local 仅供 fresh、隔离、非生产目录试用;Cluster 仅供隔离 registry、临时命名空间和可删除数据库集成。它不提供受保护 tag、公开 GHCR immutable digest、签名、attestation、生产 deployment lock、HA、升级或长期支持承诺。
Local 回退是停止并删除 Alpha 容器和 fresh 测试目录;Cluster 回退是删除临时 workload、测试数据和 credential,并恢复原 deployment lock。任何 2.x 数据迁移或生产写入仍必须走正式 cutover/reconciliation/rollback ceremony。