mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
feat(ql3): rehearse exact local upgrade cutover
This commit is contained in:
whyour
@@ -110,7 +110,7 @@ ADR-0506 的 `qinglong/alpha-local-trial-kit@v2` 首次增加 source-bound verif
|
||||
Local artifact 含：
|
||||
|
||||
- 一个包含所选 Application 与短生命周期 operator 的 archive；headless 为 `qinglong3-local-trial-kit-<arch>.docker.tar`，Console 为 `qinglong3-local-console-trial-kit-<arch>.docker.tar`，共享 Node 基础层在 archive 中去重；
|
||||
- schema 为 `qinglong/alpha-local-trial-kit@v7` 的 `manifest.json`，通过 `variant/archive/images/sboms/quickstart/upgradeReadiness/upgradeRehearsal/readme/verification` 绑定版本、完整 source commit、架构、两个 image tag/image ID 与文件长度/SHA-256；
|
||||
- schema 为 `qinglong/alpha-local-trial-kit@v8` 的 `manifest.json`，通过 `variant/archive/images/sboms/quickstart/upgradeReadiness/upgradeRehearsal/upgradeCutoverRehearsal/readme/verification` 绑定版本、完整 source commit、架构、两个 image tag/image ID 与文件长度/SHA-256；
|
||||
- canonical `quickstart.sh`，在目标 Linux 设备上只依赖 POSIX shell、`sha256sum` 和 Docker，完成 checksum、load、identity、fresh Owner 与 Profile-bound Application active；
|
||||
- canonical `upgrade-readiness.sh`，把 2.x data root 只读挂载给 128 MiB/无网络 Operator，生成 SQLite 与完整目录两个私有 inspect 计划，不获得 stage/cutover authority；
|
||||
- `verification-evidence.json` 绑定 `workflow_dispatch` 的 workflow ref/SHA、run ID/attempt、同架构两个 exact image ID 和完整 gate 集；下载者仍须到 GitHub 交叉检查 run，它不替代正式签名；
|
||||
@@ -119,7 +119,7 @@ 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。
|
||||
|
||||
Local milestone 是 `qinglong/alpha-local-milestone@v4` 三文件闭包，绑定一个 variant 的双架构 Trial Kit，并直接记录两个架构的 `upgradeReadinessSha256` 与 `upgradeRehearsalSha256`。Stage index 是 `qinglong/alpha-stage-index@v2` 三文件闭包；它重新审计两个 milestone，要求 version/source/workflow SHA/ref/run/attempt 一致，并把 Local variant/Profile 与 Cluster 的 control/admin/worker 最小集、可选 control-ai 写为机器可读选择；它不重复存放任何镜像 archive。
|
||||
Local milestone 是 `qinglong/alpha-local-milestone@v5` 三文件闭包，绑定一个 variant 的双架构 Trial Kit，并直接记录两个架构的 `upgradeReadinessSha256`、`upgradeRehearsalSha256` 与 `upgradeCutoverRehearsalSha256`。Stage index 是 `qinglong/alpha-stage-index@v2` 三文件闭包；它重新审计两个 milestone，要求 version/source/workflow SHA/ref/run/attempt 一致，并把 Local variant/Profile 与 Cluster 的 control/admin/worker 最小集、可选 control-ai 写为机器可读选择；它不重复存放任何镜像 archive。
|
||||
|
||||
任何 required job 失败时不上传对应产物。artifact 名和 archive 内的 `ci-*` tag 都表示 commit-bound candidate，不能改名后冒充 `v3.x` release。
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@
|
||||
```
|
||||
|
||||
2. 打开 `manifest.json`，确认：
|
||||
- `schema` 为 `qinglong/alpha-local-milestone@v4`；
|
||||
- `schema` 为 `qinglong/alpha-local-milestone@v5`；
|
||||
- `variant` 为 `headless` 或 `console`，且两个架构记录都使用同一变体；
|
||||
- `sourceRevision` 是准备试用的完整 40 位提交；
|
||||
- `workflow.event` 为 `workflow_dispatch`，`workflow.job` 为 `local-alpha-milestone`；
|
||||
@@ -28,7 +28,7 @@
|
||||
- `artifacts` 恰好包含 `amd64` 与 `arm64`。
|
||||
3. 根据主机架构下载 `artifacts.<architecture>.artifactName` 指向的 Trial Kit。
|
||||
4. 对 Trial Kit 先执行其 `SHA256SUMS`，再确认其中 `manifest.json` 的 SHA-256 与 milestone 的 `bundleManifest.sha256` 完全一致。
|
||||
5. 确认 milestone 的 `upgradeReadinessSha256`、`upgradeRehearsalSha256` 与 Trial Kit manifest 中同名入口摘要一致，再按 Trial Kit 自带 `README.md` 完成 fresh smoke、只读 2.x 升级就绪盘点或受审核计划的 side-by-side 暂存。
|
||||
5. 确认 milestone 的 `upgradeReadinessSha256`、`upgradeRehearsalSha256`、`upgradeCutoverRehearsalSha256` 与 Trial Kit manifest 中同名入口摘要一致，再按 Trial Kit 自带 `README.md` 完成 fresh smoke、只读 2.x 升级就绪盘点、受审核计划的 side-by-side 暂存或隔离切换链演练。
|
||||
|
||||
若持有同一版本源码与 Node.js 24，可额外审计 milestone 索引：
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ sha256sum --check SHA256SUMS
|
||||
|
||||
`manifest.json` 必须满足：
|
||||
|
||||
- `schema` 为 `qinglong/alpha-local-trial-kit@v7`；
|
||||
- `schema` 为 `qinglong/alpha-local-trial-kit@v8`；
|
||||
- `variant` 为 `headless` 或 `console`，并与 milestone、application SBOM 和 artifact 名一致；
|
||||
- `sourceRevision` 是你准备试用的完整 40 位 commit；
|
||||
- `architecture` 与主机相同；
|
||||
@@ -116,7 +116,7 @@ artifact job 必须在原生 amd64/arm64 上使用生产形态 2.x fixture 运
|
||||
|
||||
## 受审核计划的 Side-by-side 暂存
|
||||
|
||||
审核上一节两个完整结果后，把其中 exact `evidence.planDigest` 作为显式参数交给 v7 bundle 的 canonical `upgrade-rehearsal.sh`：
|
||||
审核上一节两个完整结果后，把其中 exact `evidence.planDigest` 作为显式参数交给 v8 bundle 的 canonical `upgrade-rehearsal.sh`：
|
||||
|
||||
```sh
|
||||
sh upgrade-rehearsal.sh \
|
||||
@@ -135,6 +135,27 @@ staging manifest。summary 必须是 `status=verified`、`legacySource=read_only
|
||||
复用或当作生产数据根；后续 adopted start 必须精确消费这里的 evidence，并走独立的 D-426b 门。artifact job 必须对将要上传的 exact 脚本使用同一个
|
||||
生产形态 fixture 实跑，并记录 `verification-evidence.json.gates.legacyUpgradeStage=passed`。
|
||||
|
||||
## 隔离的真实切换链演练
|
||||
|
||||
v8 headless bundle 进一步提供 `upgrade-cutover-rehearsal.sh`。它只面向 Linux Docker 测试主机，在新的 rehearsal root 和两个专用合成容器上消费上一阶段已审核的两个 plan digest：
|
||||
|
||||
```sh
|
||||
sh upgrade-cutover-rehearsal.sh \
|
||||
edge \
|
||||
/opt/qinglong/data \
|
||||
/opt/qinglong3-alpha-upgrade-cutover \
|
||||
<reviewed-sqlite-plan-digest> \
|
||||
<reviewed-data-directory-plan-digest> \
|
||||
ql3-alpha-upgrade-legacy \
|
||||
ql3-alpha-upgrade-target
|
||||
```
|
||||
|
||||
脚本先重跑 canonical stage/verify，再完成 fresh Owner 建立、data-directory transform/apply、真实 Docker socket 上的合成 Legacy 停机和 3.0 target 启停。Operator 镜像仅增加固定版本 Docker CLI，仍不携带 daemon、Compose，也不常驻。Legacy root 在所有容器中均以只读方式挂载；脚本对演练前后的 `db/database.sqlite` 做 SHA-256 闭合校验。
|
||||
|
||||
成功时 `cutover-summary.json` 必须同时为 `status=rollback_candidate`、`legacySource=unchanged`、`target=stopped`。两个合成容器会保持停止状态供审查，随后按脚本输出显式 `docker rm`；失败时脚本自动清理。该结果证明打包产物能够走通控制器链和 Docker 证据闭环，但不会停止用户真实 2.x 容器、执行 Legacy restart/rollback 或授权生产升级。
|
||||
|
||||
原生 amd64/arm64 headless artifact job 必须从将要上传的目录执行 exact `upgrade-cutover-rehearsal.sh`，检查 summary 和旧 SQLite 未变，并删除合成容器后才能上传；对应 gate 为 `verification-evidence.json.gates.legacyUpgradeCutover=passed`。Console artifact 继续实跑 canonical stage，但该 gate 固定为 `not_applicable`；在 adopted target 证据正式支持 Local API 入口前，不得把 Console fresh journey 冒充升级切换验证。
|
||||
|
||||
## 手工加载与最小 smoke
|
||||
|
||||
从 `manifest.json.archive.file` 找到 archive 后加载：
|
||||
@@ -162,7 +183,7 @@ docker run --rm --read-only --network none --cap-drop ALL \
|
||||
|
||||
## Fresh 试运行边界
|
||||
|
||||
完整 fresh setup、首 Owner ceremony、Owner presentation 安装、Application active、SIGTERM drain、SQLite integrity 和原生 cancellation 必须在 `verification-evidence.json` 指向的同架构 milestone job 中验证。Console 还必须证明首页返回 200、未认证 API 返回 401，并用真实 Owner credential 完成 Task read、fenced start、`succeeded` 终态与 bounded log marker。v7 artifact job 必须从将要上传的目录实际执行 `quickstart.sh`、read-only `upgrade-readiness.sh` 和 reviewed-plan `upgrade-rehearsal.sh`，并完成 graceful stop。实际部署时仍必须使用独立目录，并让 operator 以最终数据文件 POSIX owner 的 UID/GID 运行；operator 默认无网络且每次只执行一个命令后退出，不应作为 sidecar 或 daemon 常驻。
|
||||
完整 fresh setup、首 Owner ceremony、Owner presentation 安装、Application active、SIGTERM drain、SQLite integrity 和原生 cancellation 必须在 `verification-evidence.json` 指向的同架构 milestone job 中验证。Console 还必须证明首页返回 200、未认证 API 返回 401，并用真实 Owner credential 完成 Task read、fenced start、`succeeded` 终态与 bounded log marker。v8 artifact job 必须从将要上传的目录实际执行 `quickstart.sh`、read-only `upgrade-readiness.sh` 和 isolated `upgrade-cutover-rehearsal.sh`，并完成 graceful stop、rollback-candidate 检查与合成容器清理。实际部署时仍必须使用独立目录，并让 operator 以最终数据文件 POSIX owner 的 UID/GID 运行；operator 默认无网络且每次只执行一个命令后退出，不应作为 sidecar 或 daemon 常驻。
|
||||
|
||||
Edge 的验证上限为 Application 128 MiB、0.5 CPU、64 PID；Standalone 为 256 MiB、0.5 CPU、256 PID；operator 为 128 MiB、0.5 CPU、32 PID。这里的数值是试运行门，不是所有 workload 的容量承诺。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user