open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2026-09-20 16:07:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(ql3): ship selectable local console trial kit

Browse Source
This commit is contained in:
whyour
2026-08-28 06:50:37 +08:00
parent 84d1a61372
commit c60ab7e48a
31 changed files with 1339 additions and 192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/QINGLONG_3_0_ARCHITECTURE_RFC.md
+3 -1
View File
@@ -11,7 +11,9 @@
最新增量证据（2026-08-28）：
- D-417/ADR-0512（已实现，Console Trial Kit 交付待后续切片）：开发约二十天后的阶段产物从“可直接启动的 headless runtime”继续推进到首个可操作 Web 产品面。既有可选 `@qinglong/local-api` 现在内置 `/`、`/console.css`、`/console.js` 三文件离线 Console，总计 43,252 bytes，无前端框架、CDN、网络字体、遥测或 Web Storage；它复用同一 Node 进程、loopback listener、SQLite authority、Bearer/Project Policy/durable audit/re-confirm 链，不新增 package、sidecar、数据库连接、timer、watcher 或 cache。部署者可以按 Project 查看 Task revision/content fence、显式确认启动，查看 durable Run、Workflow Step 数与 Event sequence，并对未终止 Run 提交显式 cancellation request；取消请求不会伪装成停止终态。Credential 只在当前页面内存，服务端固定 CSP/COOP/CORP/Permissions Policy/no-referrer/nosniff/DENY/no-store，远程设备只能由操作者建立 SSH tunnel，不开放 LAN/public listener。默认 Edge/Standalone 与 D-416 Trial Kit 继续 headless、零增量；Console 只进入 opt-in `edge-application-api|standalone-application-api`，两档 artifact 为 `3,953,346 / 3,953,490 bytes`、467 files、12 packages、90 loaded modules，低于 6 MiB/640-file 门。Local API 48/48、pruner 11/11、完整 backend `1,637 total / 1,635 pass / 2 conditional skip / 0 fail`、18-package clean build/test 退出 0；package boundary 保持 18 packages 且无 single-source/shallow package，Cluster dependency、122-module Edge import 与全部 14 档 Local artifact audit 均 compatible。桌面 1440×960 与手机 390×844 已检查 Task、Run/Event spine 和显式确认工作态。该切片形成可构建、可运行的 source/application-api 阶段制品，但当前 v3 Trial Kit 尚未携带 Console；把 Console image/quickstart 变成路由/NAS 可下载物、固定低性能物理 Edge 容量数据和 public release 仍是后续门。
- D-418/ADR-0513（已实现，首份真实双架构产物待授权）：二十天研发形成的 headless 用户旅程与 opt-in Console 已闭合为部署者可选择的 Local Alpha 交付链。手动门新增默认 `headless` 的 `local_alpha_variant=headless|console`；一次授权 run 只生成所选变体，不把两套 Application 塞入同一 archive。默认 Docker/runtime 与路由/NAS 继续使用原 8 个内部 package、无 listener 的 headless 镜像；独立 `runtime-console` target 增加 Local API/Console，固定 12-package、6 MiB/640-file、AI-excluded 闭包。Console quickstart 仅支持 Linux Docker host，使用 host network 让容器内仍严格绑定 `127.0.0.1:5700` 的服务可由宿主访问，远程只能显式 SSH tunnel，不放宽为 `0.0.0.0` 或 public ingress。Trial Kit、verification、Local milestone 与 stage index 分别升级为 `qinglong/alpha-local-trial-kit@v4`、`qinglong/alpha-local-trial-kit-verification@v2`、`qinglong/alpha-local-milestone@v2`、`qinglong/alpha-stage-index@v2`，variant 贯穿 archive/SBOM/evidence/artifact name/deployment selection，拒绝跨变体与跨架构混用。普通双架构 CI 同时构建、Trivy 扫描、库存/SBOM 对账和实跑两种镜像；Console 必须完成 fresh Owner、loopback 首页 200、未认证 API 401 与 graceful stop。实际大 archive 仍只由维护者显式 `produce_alpha_artifacts=true` 生成；没有同 run/attempt 的双架构 milestone 时，单个 archive 仍只是工程中间物，不冒充 public release、生产 HA、签名或 LTS。
- D-417/ADR-0512（已实现，部署交付由 D-418 闭合）：开发约二十天后的阶段产物从“可直接启动的 headless runtime”继续推进到首个可操作 Web 产品面。既有可选 `@qinglong/local-api` 现在内置 `/`、`/console.css`、`/console.js` 三文件离线 Console，总计 43,252 bytes，无前端框架、CDN、网络字体、遥测或 Web Storage；它复用同一 Node 进程、loopback listener、SQLite authority、Bearer/Project Policy/durable audit/re-confirm 链，不新增 package、sidecar、数据库连接、timer、watcher 或 cache。部署者可以按 Project 查看 Task revision/content fence、显式确认启动，查看 durable Run、Workflow Step 数与 Event sequence，并对未终止 Run 提交显式 cancellation request；取消请求不会伪装成停止终态。Credential 只在当前页面内存，服务端固定 CSP/COOP/CORP/Permissions Policy/no-referrer/nosniff/DENY/no-store，远程设备只能由操作者建立 SSH tunnel，不开放 LAN/public listener。默认 Edge/Standalone 与 D-416 Trial Kit 继续 headless、零增量；Console 只进入 opt-in `edge-application-api|standalone-application-api`，两档 artifact 为 `3,953,346 / 3,953,490 bytes`、467 files、12 packages、90 loaded modules，低于 6 MiB/640-file 门。Local API 48/48、pruner 11/11、完整 backend `1,637 total / 1,635 pass / 2 conditional skip / 0 fail`、18-package clean build/test 退出 0；package boundary 保持 18 packages 且无 single-source/shallow package，Cluster dependency、122-module Edge import 与全部 14 档 Local artifact audit 均 compatible。桌面 1440×960 与手机 390×844 已检查 Task、Run/Event spine 和显式确认工作态。D-417 当时只形成 source/application-api 制品；其 Console image/quickstart 下载交付已由 D-418 完成，固定低性能物理 Edge 容量数据和 public release 仍是后续门。
- D-416/ADR-0511（已实现，首份真实 v3 Trial Kit 待授权）：阶段产物的判定从“可下载、可验真”推进到“部署者可直接试运行”。Local Trial Kit schema 升为 `qinglong/alpha-local-trial-kit@v3`，每个 amd64/arm64 bundle 新增由唯一模板生成并绑定 archive、两个 exact image ID、source 和 architecture 的 `quickstart.sh`；离线 auditor 会重新渲染 canonical journey，拒绝即使重算 manifest/checksum 的本地脚本改写。目标路由/NAS 或单节点只需 POSIX shell、`sha256sum` 和 Docker，即可在一个尚不存在的隔离目录完成全包 checksum、镜像 load/identity 复核、128 MiB 短生命周期 operator fresh setup、首 Owner 建立，并按 Edge `128 MiB/64 PID` 或 Standalone `256 MiB/256 PID` 启动 Application、等待 `active` 后输出 logs/stop/remove 指令。显式 artifact job 在 upload 前必须执行将要上传的 exact quickstart、检查 SQLite/Owner delivery 并 graceful stop；普通 push 不生成大 archive。聚焦 materializer/milestone/stage/workflow 回归为 `26/26`，完整 backend 为 `1636 total / 1634 pass / 2 conditional skip / 0 fail`，18-package clean build/test 退出 0；package boundary 保持 `18 packages / singleSourcePackages=[] / shallowSourcePackages=[]`，Cluster dependency、122-module Edge import、镜像/版本与 14 档 Local artifact 均 compatible，基础 Edge/Standalone 仍为 `2,669,390 / 2,669,468 bytes`、325 files、58 modules。历史同源 arm64 镜像对已本地物化为 v3 八文件开发 bundle，184,648,192-byte archive 完成 checksum、canonical audit、load 与 exact identity；Docker Desktop 在 Owner directory ownership 处按既有 POSIX 不等价失败关闭，未冒充原生 Linux 成功，正式 native exact-script 证据由手动 artifact job 产生。该切片不安装宿主 Node.js，不把 Operator 变成 daemon，不增加镜像 layer、workspace package、端口或稳态 RSS，也不触碰 2.x/migration。当前产物是无外部 listener、AI-excluded 的 headless Alpha runtime，不冒充 2.x Web UI、公开 release、生产 HA 或 LTS；首份真实双架构 v3 下载物仍需维护者授权 `produce_alpha_artifacts=true`。
docs/adr/ADR-0512-bounded-offline-local-web-console.md
+1 -1
View File
@@ -66,7 +66,7 @@ D-416 的 Local Trial Kit 和基础 `edge|standalone` Application 仍保持 head
- `application-api` Edge/Standalone 制品当前为 3,953,346 / 3,953,490 bytes、467 files、12 packages，远低于 6 MiB/640-file budget；加载闭包为 90 modules，实测 import RSS delta 约 14.0 MiB；
- 基础 headless Edge/Standalone、D-416 Trial Kit、Cluster Profile 和 AI/MCP Profile 不因本切片新增 Console 进程或端口；
- Console 视觉和交互已在 1440×960 与 390×844 视口验证，工作态覆盖 Task detail、运行确认、Run evidence/Event sequence 和取消入口；
- 当前仍缺少面向部署用户的 Console Docker image/Trial Kit 选择、真实低性能物理 Edge 容量数据，以及受保护 public release。
- 本 ADR 当时缺少的 Console Docker image/Trial Kit 选择已由 ADR-0513 闭合；真实低性能物理 Edge 容量数据和受保护 public release 仍未完成。
## 验证
docs/adr/ADR-0513-selectable-local-console-trial-kit.md
+83
View File
@@ -0,0 +1,83 @@
# ADR-0513：可选择的 Local Console Trial Kit
- 状态：Accepted
- 日期：2026-08-28
- 决策：D-418
- 关联：ADR-0503、ADR-0506、ADR-0508、ADR-0510、ADR-0511、ADR-0512
## 背景
D-416 已形成可执行的 headless Local Alpha Trial Kit，D-417 已形成有界、离线、loopback-only 的 Local Web Console，但部署用户仍不能下载一套同时包含 Console、短生命周期管理 authority 和 canonical quickstart 的闭合产物。开发约二十天后，阶段成果必须能够由 amd64/arm64 的路由器、NAS 或单节点用户下载、验真、启动和回退，而不能只停留在源码包或单元测试。
同时，Console 不应增加默认低配设备的镜像体积、listener 或稳态资源成本；也不能为了容器访问而把 Local API 从 `127.0.0.1` 放宽为 LAN/public listener。
## 决策
### 1. Local Trial Kit 提供两个互斥变体
显式 artifact run 新增 `local_alpha_variant=headless|console`，默认 `headless`。一次授权运行只生成所选变体的 amd64/arm64 Trial Kit 和对应 Local milestone，不把两套 Application 镜像塞入同一个 archive：
- `headless`：沿用最小 Local Application，稳态无 listener，适合低配路由器/NAS；
- `console`：使用独立 `runtime-console` image target，携带 `@qinglong/local-api` 与 `@qinglong/local-owner-console`，适合需要浏览器操作面的 Linux 单节点。
两者共享同一个短生命周期 Local operator。默认 Docker build 仍落在 headless runtime，Console 不进入 2.x、Cluster 或基础 Edge/Standalone 闭包。
### 2. Console 保持 loopback-only
Console quickstart 只允许 Linux Docker host，Application 使用 host network，但进程配置仍严格绑定 `127.0.0.1:5700`。这样宿主浏览器可访问 loopback，同时没有把 API 改为 `0.0.0.0`。远程设备必须由操作者建立 SSH tunnel，不得直接向 LAN 或公网暴露端口。
### 3. 产物协议显式升级并绑定变体
- Trial Kit：`qinglong/alpha-local-trial-kit@v4`，manifest schemaVersion 5；
- verification evidence：`qinglong/alpha-local-trial-kit-verification@v2`；
- Local milestone：`qinglong/alpha-local-milestone@v2`；
- Alpha stage index：`qinglong/alpha-stage-index@v2`。
manifest、verification、SBOM、archive 名、artifact 名、milestone 和 stage deployment selection 都必须记录同一个 `variant`。Headless archive 保留兼容文件名；Console 使用 `qinglong3-local-console-trial-kit-<arch>.docker.tar`。跨变体复制、混合双架构或用 headless SBOM 冒充 Console 一律失败关闭。
### 4. 阶段可用必须有真实运行证据
普通 push/PR 构建并扫描两个 image target，复核 exact package inventory/SBOM，并在原生 amd64/arm64 Linux 上执行：
- headless Edge 与 Standalone fresh setup、首 Owner、active、SIGTERM drain；
- Console Edge fresh setup、首 Owner、loopback 首页 HTTP 200、未认证 API HTTP 401、SIGTERM drain；
- 128 MiB/64 PID Edge 入口约束和 AI-excluded closure。
只有显式 `produce_alpha_artifacts=true` 的 workflow 才能生成大 archive；上传前必须从即将上传的目录运行 exact `quickstart.sh`。没有同 run/attempt 的双架构 Local milestone 时，单个 archive 仍只是中间产物。
## 被拒绝的替代方案
### 一个 archive 同时携带 headless 与 Console
拒绝。低配用户会为未选择的 UI 支付下载和存储成本，部署选择也难以从 SBOM 和 image identity 中可靠判定。
### Console 取代默认 Local Application
拒绝。它会让所有路由设备承担额外 package、静态资产和 listener，违背按能力付费与默认最小运行时原则。
### 将 Local API 改为 `0.0.0.0`
拒绝。Alpha 尚未关闭 TLS、可信代理、CSRF 和远程会话门；容器便利性不能扩大网络 authority。
### 每个变体一次生成两套 artifact
拒绝。单次显式授权只产生被维护者选择的变体，避免大 archive 存储翻倍，并保持 milestone 语义单一。
## 影响
- 低配设备默认仍下载和运行 headless Application，Console 对其为零成本；
- Console image 有独立 12-package、6 MiB/640-file 上限、SBOM、OS vulnerability policy 与双架构 live gate；
- Local milestone 和 stage index 升级 schema，旧 v1/v3 索引不会被新 auditor 静默接受；
- 该决策提供 Alpha/Linux 试运行产物，不等于 public release、生产 ingress、HA、签名或 LTS；
- 首份真实可下载双架构产物仍需维护者显式授权 workflow，普通 CI 成功只证明产物链可生成。
## 验证
- Trial Kit materializer/auditor 覆盖 headless 与 Console 的 archive、SBOM、quickstart 和 mutation 拒绝；
- Local milestone 与 stage index 覆盖变体绑定、双架构隔离和 Console deployment selection；
- Dockerfile audit 固定 headless/Console 两套精确 package closure、Console asset 保留与 loopback label；
- 原生 Linux CI 对两个架构运行 Console HTTP 200/401 和生命周期门；
- 本地聚焦门为 `70/70`，完整 backend 为 `1646 total / 1644 pass / 2 conditional skip / 0 fail`，18-package clean build/test 退出 0，14 档 Local artifact audit 全部 `compatible=true`；
- 本机实际镜像库存为 headless `10 packages / 425 files / 3,638,399 bytes`、Console `12 packages / 455 files / 3,831,208 bytes`，两者均在 128 MiB/64 PID entrypoint 门内且排除 AI；
- macOS Docker Desktop 的 bind mount 不能提供与原生 Linux 等价的 POSIX Owner UID/mode 证据，Console fresh lifecycle 因此在 owner-private directory 门失败关闭；不得把该宿主限制冒充应用通过，最终双架构证据由推送后的原生 Linux CI 关闭；
- GitNexus 变更审计、镜像静态门和 Docker 实物门在提交前执行。
docs/adr/README.md
+2 -1
View File
@@ -515,7 +515,8 @@
| [ADR-0509](./ADR-0509-cluster-alpha-bundle-and-milestone-closure.md) | Cluster Alpha Bundle 与跨架构里程碑闭合 | Accepted（首份实际 Cluster milestone artifact 待维护者授权） |
| [ADR-0510](./ADR-0510-cross-profile-alpha-stage-delivery-index.md) | 跨 Profile Alpha 阶段交付索引 | Accepted（首份实际 stage index 待维护者授权） |
| [ADR-0511](./ADR-0511-runnable-local-alpha-quickstart.md) | 可直接试运行的 Local Alpha Quickstart | Accepted（首份实际 v3 Trial Kit 待维护者授权） |
| [ADR-0512](./ADR-0512-bounded-offline-local-web-console.md) | 有界、离线的 Local Web Console | Accepted（Console Trial Kit 交付待后续切片） |
| [ADR-0512](./ADR-0512-bounded-offline-local-web-console.md) | 有界、离线的 Local Web Console | Accepted（Trial Kit 交付已由 ADR-0513 闭合） |
| [ADR-0513](./ADR-0513-selectable-local-console-trial-kit.md) | 可选择的 Local Console Trial Kit | Accepted（首份实际双架构产物待维护者授权） |
## 规则
docs/operations/ql3-alpha-candidate.md
+14 -14
View File
@@ -15,16 +15,16 @@
当维护者显式选择 `alpha_artifact_scope=all` 时，还会生成 `Alpha stage index`。它把同一次 run 的 Local/Cluster milestone 交叉绑定，并为 Edge、Standalone、Cluster 给出目标架构的最小 artifact 选择；这是阶段交付导航，不是正式 release catalog。只生成 Local 或 Cluster 时，各自 milestone 仍可独立成立，不制造一个不完整的总索引。
## 当前阶段实物（2026-08-27）
## 当前阶段实物（2026-08-28）
在下面保留的历史 exact-image 证据之外，2026-08-28 的源码阶段已经形成两条可独立验收的产品线：
在下面保留的历史 exact-image 证据之外，2026-08-28 的源码阶段已把 headless 用户旅程与 opt-in Console 合并为一条可选择的交付链：
| 阶段产物 | 当前可用能力 | 仍缺少 |
| --- | --- | --- |
| D-416 Local Alpha Trial Kit v3 | POSIX shell + Docker 一条命令完成 checksum、load、fresh setup、首 Owner、headless Application active/stop | 首份远端双架构实际 artifact 仍需维护者授权 `produce_alpha_artifacts=true` |
| D-417 opt-in Local Web Console | `application-api` 制品可在同进程/同 SQLite/loopback listener 上查看 Task/Run/Event 并显式运行或取消；Edge/Standalone 制品审计通过 | 尚未进入 Trial Kit Docker image/quickstart，不能冒充当前路由/NAS 下载物 |
| D-418 headless Trial Kit v4 | 默认低配变体；POSIX shell + Docker 一条命令完成 checksum、load、fresh setup、首 Owner、Application active/stop；无 listener | 首份远端双架构实际 artifact 仍需维护者授权 `produce_alpha_artifacts=true` |
| D-418 Console Trial Kit v4 | 显式 Linux-only 变体；同一 quickstart 关闭 Owner ceremony 后启动 loopback Console，支持 Task/Run/Event、显式运行与取消；CI 验证首页 200、未认证 API 401 | 仍是 Alpha、无 public ingress/TLS/签名；首份实际 archive 同样需维护者授权 |
这两个边界共同防止把“20 天代码和测试”冒充“用户已经能下载并完整操作”：D-416 已关闭 fresh headless 用户旅程，D-417 已关闭 source/application-api 操作界面，但两者尚未合并成实际可下载的 Console Trial Kit。操作说明见 [Local Web Console](./ql3-local-web-console.md)。
D-418 防止把“20 天代码和测试”冒充“用户已经能下载并完整操作”：源码与普通 CI 已具备生成、审计和实跑两种 Trial Kit 的能力，但只有显式 artifact run 生成且被同 run 的双架构 milestone 收录后，才是可下载阶段产物。操作说明见 [Local Alpha Trial Kit](./ql3-local-alpha-trial-kit.md) 与 [Local Web Console](./ql3-local-web-console.md)。
提交 `4239464af6937d56528a0a2c573d12329bc7ca55` 已形成最新 owner-private arm64 工程候选：
@@ -35,24 +35,24 @@
该本地 archive 不是新的 v2 Local Alpha Trial Kit。它在 ADR-0506 前生成，manifest v1 会无条件写入 `passed`，且 macOS Docker Desktop 因 bind-mount UID 映射无法对 exact 本地 archive 完成 Owner pepper 旅程；原生 CI 证明同源码实现，不自动证明另一个 archive 的 exact image bytes。它因此保留为工程候选，不冒充已获 workflow evidence 的用户 Alpha。
ADR-0506 的 `qinglong/alpha-local-trial-kit@v2` 首次增加了 source-bound `verification-evidence.json`；ADR-0511 进一步把当前格式升级为 `@v3`，新增不依赖宿主 Node.js 的 canonical `quickstart.sh`，把可验证镜像闭合为可执行的 fresh 用户旅程。旧 `e3c05862` runtime-only archive、`2620be05` v1 Trial Kit、`4239464a` v1 archive 与未携带 quickstart 的 v2 均为历史工程证据，不能通过 v3 auditor。下一项外部里程碑仍是维护者授权 `produce_alpha_artifacts=true`，由同一次原生 milestone job 生成并实际执行 exact-image 双架构可下载 archive。
ADR-0506 的 `qinglong/alpha-local-trial-kit@v2` 首次增加 source-bound verification，ADR-0511 的 `@v3` 增加 canonical quickstart，ADR-0513 的 `@v4` 再把 `headless|console` 变体绑定到 image、SBOM、verification、milestone 和 stage index。旧 runtime-only、v1/v2/v3 bundle 均为历史工程证据，不能通过 v4 auditor。下一项外部里程碑仍是维护者授权 `produce_alpha_artifacts=true`，由同一次原生 milestone job 生成并实际执行所选变体的双架构可下载 archive。
## 生成
在 GitHub Actions 手动运行 `QingLong 3.0 CI`，选择目标 `next` 提交，设置 `produce_alpha_artifacts=true`，并明确选择 `alpha_artifact_scope=local|cluster|all`。普通 push/PR 不上传大镜像，避免每次开发提交都制造伪里程碑和额外存储成本。
在 GitHub Actions 手动运行 `QingLong 3.0 CI`，选择目标 `next` 提交，设置 `produce_alpha_artifacts=true`，明确选择 `alpha_artifact_scope=local|cluster|all`，并为 Local 选择 `local_alpha_variant=headless|console`（默认 headless）。普通 push/PR 不上传大镜像，避免每次开发提交都制造伪里程碑和额外存储成本。
成功后同一次 run 生成、保留 30 天：
- `ql3-alpha-<commit>-local-amd64` 与 `ql3-alpha-<commit>-local-arm64`；
- `ql3-alpha-<commit>-local-milestone`；
- `ql3-alpha-<commit>-local-<variant>-amd64` 与 `ql3-alpha-<commit>-local-<variant>-arm64`；
- `ql3-alpha-<commit>-local-<variant>-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 含：
- 一个包含 Application 与短生命周期 operator 的 `qinglong3-local-trial-kit-<arch>.docker.tar`；共享 Node 基础层在 archive 中去重；
- schema 为 `qinglong/alpha-local-trial-kit@v3` 的 `manifest.json`，通过 `archive/images/sboms/quickstart/readme/verification` 绑定版本、完整 source commit、架构、两个 image tag/image ID 与文件长度/SHA-256；
- 一个包含所选 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@v4` 的 `manifest.json`，通过 `variant/archive/images/sboms/quickstart/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；
- `verification-evidence.json` 绑定 `workflow_dispatch` 的 workflow ref/SHA、run ID/attempt、同架构两个 exact image ID 和完整 gate 集；下载者仍须到 GitHub 交叉检查 run，它不替代正式签名；
- 与实际只读镜像 inventory 对账过的 CycloneDX SBOM；
@@ -60,7 +60,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。
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。
Local milestone 是 `qinglong/alpha-local-milestone@v2` 三文件闭包，绑定一个 variant 的双架构 Trial Kit。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。
@@ -75,8 +75,8 @@ sh quickstart.sh edge /opt/qinglong3-alpha-data
也可以选择 `standalone` 和自定义容器名。quickstart 会先执行 `SHA256SUMS`，再核对 exact
镜像身份并完成 fresh setup、首 Owner 与 Application active；成功后输出 logs、stop 和
remove 命令。当前是无外部 listener、AI-excluded 的 headless runtime 阶段成果，不是
2.x Web UI 的替代品。
remove 命令。Headless 不开放 listener；Console 只在 Linux host 的 `127.0.0.1:5700`
提供 Alpha 操作面，远程访问必须经 SSH tunnel。两者都不是 2.x Web UI 的生产替代品。
## 手工验证与最小 smoke
docs/operations/ql3-alpha-stage-index.md
+3 -2
View File
@@ -6,7 +6,7 @@
| 设备或环境 | 选择 | 稳态组件 | 需要下载 |
| --- | --- | --- | --- |
| 低配路由器、NAS、单机 | `deploymentSelections.local` | 仅 Local Application；Operator 只在 setup/upgrade/recovery 短暂运行 | 目标架构的一个 Local Trial Kit |
| 低配路由器、NAS、单机 | `deploymentSelections.local`；默认选择 `headless`，需要浏览器操作面时显式选择 `console` | 仅 Local Application；Operator 只在 setup/upgrade/recovery 短暂运行 | 目标架构、目标 variant 的一个 Local Trial Kit |
| 临时 K3s/Kubernetes 集群 | `deploymentSelections.cluster` | control、admin、worker；AI 按需增加 control-ai | 目标架构的三个 required artifact；需要 AI 时再下载 optional artifact |
不得把四个 Cluster 角色部署到低配路由器，也不需要为一台 amd64 主机下载 arm64 归档。索引固定列出十个可选择 artifact，但每个部署者只下载目标 Profile、架构和角色所需的子集。
@@ -15,7 +15,8 @@
1. 在本目录运行 `sha256sum --check SHA256SUMS`。
2. 检查 `manifest.json`：
- schema 为 `qinglong/alpha-stage-index@v1`；
- schema 为 `qinglong/alpha-stage-index@v2`；
- `deploymentSelections.local.variant` 与 Local milestone、artifact 名和 Profile 一致；
- maturity 为 `alpha_stage_delivery_not_public_release`；
- source revision、run ID/attempt 是准备验证的显式 workflow run；
- `milestones.local` 与 `milestones.cluster` 分别指向同一提交的 milestone artifact。
docs/operations/ql3-local-alpha-milestone.md
+3 -2
View File
@@ -9,7 +9,7 @@
- 不提供公开 GHCR tag、Cosign 签名、GitHub attestation、catalog、生产升级或长期支持承诺；
- Cluster/Kubernetes 仍按独立 Integration Candidate 与 Public Release Set 门验收。
单个架构 artifact 提前上传并不代表 milestone 成功。没有 `ql3-alpha-<sourceRevision>-local-milestone` 索引、索引 workflow 不是成功终态、run/attempt 不一致或索引审计失败时，已有的大归档只能作为失败运行的中间文件，不得交付用户。
单个架构 artifact 提前上传并不代表 milestone 成功。没有 `ql3-alpha-<sourceRevision>-local-<variant>-milestone` 索引、索引 workflow 不是成功终态、run/attempt/variant 不一致或索引审计失败时，已有的大归档只能作为失败运行的中间文件，不得交付用户。
## 选择并验证下载物
@@ -20,7 +20,8 @@
```
2. 打开 `manifest.json`，确认：
- `schema` 为 `qinglong/alpha-local-milestone@v1`；
- `schema` 为 `qinglong/alpha-local-milestone@v2`；
- `variant` 为 `headless` 或 `console`，且两个架构记录都使用同一变体；
- `sourceRevision` 是准备试用的完整 40 位提交；
- `workflow.event` 为 `workflow_dispatch`，`workflow.job` 为 `local-alpha-milestone`；
- GitHub Actions 中对应 `runId/runAttempt` 的整条 `QingLong 3.0 CI` 为成功终态；
docs/operations/ql3-local-alpha-trial-kit.md
+14 -9
View File
@@ -2,7 +2,7 @@
本目录是绑定一个 QingLong 3.0 源码提交、一个 Linux 架构和一次显式 GitHub milestone run 的阶段试运行套件，不是公开 release 或生产升级承诺。它同时包含常驻 Application 镜像和短生命周期 operator 镜像；两者共享的 OCI layer 只在同一个 Docker archive 中保存一次。
一套 Trial Kit 只有被同一 run 的 `ql3-alpha-<sourceRevision>-local-milestone` 跨架构索引收录后才是可交付阶段产物。单个矩阵 job 提前上传、另一架构或完整 CI 随后失败时留下的 artifact 只是中间文件。先按 milestone `manifest.json` 选择本机架构并核对本 bundle manifest digest，再执行下述离线验收。
一套 Trial Kit 只有被同一 run 的 `ql3-alpha-<sourceRevision>-local-<variant>-milestone` 跨架构索引收录后才是可交付阶段产物。单个矩阵 job 提前上传、另一架构或完整 CI 随后失败时留下的 artifact 只是中间文件。先按 milestone `manifest.json` 选择 `variant` 和本机架构并核对本 bundle manifest digest，再执行下述离线验收。
## 适用范围
@@ -11,6 +11,8 @@
- fresh、隔离的测试数据目录；
- 离线导入、设备兼容验证和 3.0 Alpha 用户旅程验证。
`headless` 是默认且最小的低配设备变体，不打开端口。`console` 是显式选择的 Linux-only 变体，携带离线 Web Console，并仅通过宿主 `127.0.0.1:5700` 提供操作面。二者是独立 archive，不应同时下载；远程 Console 只允许经 SSH tunnel 访问，不得暴露到 LAN 或公网。
不要把它直接用于生产数据、2.x 唯一数据目录或生产 Secret。Cluster/Kubernetes 节点应使用 Cluster Integration Candidate；本套件不包含 PostgreSQL HA、Worker 或 Cluster Admin。
## 离线验收
@@ -23,7 +25,8 @@ sha256sum --check SHA256SUMS
`manifest.json` 必须满足：
- `schema` 为 `qinglong/alpha-local-trial-kit@v3`；
- `schema` 为 `qinglong/alpha-local-trial-kit@v4`；
- `variant` 为 `headless` 或 `console`，并与 milestone、application SBOM 和 artifact 名一致；
- `sourceRevision` 是你准备试用的完整 40 位 commit；
- `architecture` 与主机相同；
- `maturity` 为 `alpha_candidate_not_public_release`。
@@ -42,7 +45,7 @@ node scripts/ql3-local-alpha-trial-kit-bundle.cjs \
## 一条命令完成 Fresh 试运行
v3 bundle 内的 `quickstart.sh` 不依赖宿主 Node.js、jq 或 Compose，只需要 POSIX
v4 bundle 内的 `quickstart.sh` 不依赖宿主 Node.js、jq 或 Compose，只需要 POSIX
shell、`sha256sum` 和已启动的 Docker。必须选择一个尚不存在、与 2.x/生产数据完全
隔离的绝对路径：
@@ -66,11 +69,12 @@ Owner delivery 保留在新数据目录的 `owner-delivery/`，operator command
删除数据目录；确认不再需要诊断后由操作者显式删除该 fresh 测试目录。脚本拒绝既有目录，
不能用于升级、迁移或接管 2.x。
当前 Application 是无外部 listener、AI-excluded 的 headless Alpha runtime。该试运行可
验证 3.0 SQLite、Owner authority、调度/插件基础与生命周期，但还不是 2.x Web UI 的
可替代版本。D-417 已在 opt-in `application-api` Profile 提供首个 Local Web Console，
但本 v3 Trial Kit 尚未携带该 Profile；不要期待 quickstart 启动后出现 Web 端口。Console
当前使用方式与边界见 [Local Web Console](./ql3-local-web-console.md)。
Headless Application 是无外部 listener、AI-excluded 的最小 Alpha runtime。Console 变体同样
AI-excluded，但 quickstart 会在 Linux 上使用 host network，让容器内仍严格绑定
`127.0.0.1:5700` 的 Local API 可由宿主浏览器访问。成功后打开
`http://127.0.0.1:5700/`；远程主机必须建立 SSH tunnel。两种变体都只用于 fresh Alpha，
不是 2.x Web UI 的生产替代版本。Console 能力和凭据边界见
[Local Web Console](./ql3-local-web-console.md)。
## 手工加载与最小 smoke
@@ -78,6 +82,7 @@ Owner delivery 保留在新数据目录的 `owner-delivery/`，operator command
```sh
docker load --input qinglong3-local-trial-kit-<arch>.docker.tar
# Console 变体使用 qinglong3-local-console-trial-kit-<arch>.docker.tar
```
以 manifest 中 `images.application.reference` 和 `images.operator.reference` 为准，分别核对 `docker image inspect` 返回的 image ID。然后执行无网络、只读 smoke：
@@ -98,7 +103,7 @@ docker run --rm --read-only --network none --cap-drop ALL \
## Fresh 试运行边界
完整 fresh setup、首 Owner ceremony、Application active、SIGTERM drain、SQLite integrity 和原生 cancellation 必须在 `verification-evidence.json` 指向的同架构 milestone job 中验证。v3 artifact job 还必须从将要上传的目录实际执行 `quickstart.sh` 并完成 graceful stop。实际部署时仍必须使用独立目录，并让 operator 以最终数据文件 POSIX owner 的 UID/GID 运行；operator 默认无网络且每次只执行一个命令后退出，不应作为 sidecar 或 daemon 常驻。
完整 fresh setup、首 Owner ceremony、Application active、SIGTERM drain、SQLite integrity 和原生 cancellation 必须在 `verification-evidence.json` 指向的同架构 milestone job 中验证。Console 还必须证明首页返回 200、未认证 API 返回 401。v4 artifact job 必须从将要上传的目录实际执行 `quickstart.sh` 并完成 graceful stop。实际部署时仍必须使用独立目录，并让 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 的容量承诺。