feat(ql3): gate console capacity evidence

This commit is contained in:
whyour
2026-08-20 10:04:21 +08:00
parent 0a5f1448f1
commit 3979707f6d
7 changed files with 2289 additions and 1 deletions
+17
View File
@@ -11,6 +11,23 @@
最新增量证据(2026-08-20):
- D-370/ADR-0463(实现与本地协议门已接受;首份原生 CI 双架构报告待实际 workflow 产生):为显式按需的 Cluster Admin
Copilot Console 增加固定 Linux x64/arm64 容量与 assertion 生命周期发布证据。两个原生 Admin image matrix job 分别在
`192 MiB / swap 0 / 0.25 CPU / 32 PIDs`、只读 root、非 root、cap-drop ALL、no-new-privileges、默认 seccomp、8 MiB tmpfs 与
loopback-only publication 下执行四次用户驱动读取,并从 Console 自身 cgroup v2 采集 memory max/peak/events、swap、CPU 与 PID;要求至少
32 MiB headroom 且 `max/oom/oom_kill/oom_group_kill` 不增加。隔离 synthetic TLS 1.3/mTLS management verifier 验证
`initial accepted → atomic rotated accepted → expired rejected → rotated recovered`,Console 全程不重启、不轮询、不重试、不缓存、不 mutation,过期
assertion 只投影为 502/`assertion_expired` 低敏事实。每架构报告绑定 repository/revision/workflow/run ID/attempt 和独立 image ID,使用 nofollow
bounded input、`wx/0600` output 与 domain-separated canonical SHA-256;独立只读 job 以 commit-pinned artifact actions 精确下载、合并并离线重审。
实现保持在单一 CI 脚本和既有 image release audit 中,没有新增 package、dependency、binary、服务、端口、数据库对象或部署 workload,避免制造单文件微包;
Edge/Standalone closure 不含 Console。D-370 聚焦证据与发布审计为 `108/108`,连同 image SBOM 的原生 job 聚焦集合为 `120/120`18-package
clean build/逐包测试退出 0,完整 backend 工作区门为 `1,503 total / 1,501 pass / 2 conditional skip / 0 fail`(含一条不会提交的既有用户测试;D-370
提交范围为 `1,502 total / 1,500 pass / 2 skip`),六项架构审计和 14 档 Local artifact
audit 全部 compatible。基础 Edge/Standalone 仍为 `2,589,998 / 2,590,076` bytesApplication+AI 为 `4,493,151 / 4,493,283` bytesMCP 为
`7,315,930 / 7,316,038` bytes。本机只能验证协议、Docker inspect 契约和 workflow 装配,尚无本提交的原生
GitHub x64/arm64 memory peak、artifact digest 或 run URL,因此不能把实现状态写成最终现场证据。192 MiB 只回答 workstation Console 的有界空载读取,
不是物理路由器最低配置,也不是 Cluster 节点吞吐、故障恢复或容量规划。
- D-369/ADR-0462(已接受):在既有 operator-workstation Copilot Console 内完成显式可选、默认关闭的 Run management 只读纵切,新增固定
`run_cancellation_status``run_cancellation_blocked_list``run_cancellation_inspect` 三种 browser/BFF operation。只有同时提供独立
`--run-management-config` 与 owner-private `--run-management-assertion` 才启用,Project API credential、浏览器 session 与 Run 专用 TLS 1.3/mTLS/OIDC
@@ -0,0 +1,107 @@
# ADR-0463:原生双架构 Console 容量与 Assertion 生命周期证据
- 状态:Accepted(证据协议、原生采集与 CI 聚合门已实现;首份 GitHub Actions 双架构报告待实际运行产生)
- 日期:2026-08-20
- 关联 RFCQL-RFC-0001 D-370、PR-5、PR-7
- 关联 ADRADR-0088、ADR-0281、ADR-0322、ADR-0329、ADR-0462
- AmendsADR-0462 中尚未取得的 compact Console Linux x64/arm64 实测边界
## 上下文
D-369 已把 Run cancellation status、blocked page 与 inspect 作为显式可选、用户驱动的只读纵切接入
Cluster Copilot Console,并继续声明 compact workstation 容器预算为 `192 MiB / 0.25 CPU / 32 PIDs`
静态 limit、macOS Docker Desktop 或单架构开发机都不能证明生产镜像在原生 Linux x64 与 arm64 上确实满足该
envelope,也不能证明 Console 在不重启时会为每次点击重新读取轮换后的短期 assertion,并低敏拒绝过期凭据。
部署用户跨度很大:Edge/Standalone 可能运行在小型路由设备,而 Cluster operator workstation 与集群节点有
完全不同的资源和可用性要求。因此本门只能回答“按需启动的 Cluster Admin Console 是否在固定 CI 容器预算内
完成四次有界管理读取”,不能把结果外推为物理 Edge 最低配置、Cluster 节点吞吐或多节点容量规划。
## 决策
1. 新增单一 CI/审核脚本 `scripts/ql3-cluster-copilot-console-capacity-evidence.cjs`,提供 `capture``merge`
`audit` 三种模式。它不新增 workspace package、生产 dependency、binary、服务、数据库对象或部署 workload;
证据职责不足以成立独立 package,避免再次制造只有一个文件的微包。
2. `capture` 只允许 Node `v24.18.0` 的原生 Linux `x64``arm64`,并要求显式
`QL3_CLUSTER_COPILOT_CONSOLE_CAPACITY_LIVE=1`。镜像必须是当前 matrix 刚构建的独立 Admin image
architecture、content ID、size 和 `10001:10001` runtime user 均从 Docker inspect 取得。
3. Console 使用精确 compact envelope`192 MiB` memory、memory-swap 与 memory 相同从而使 cgroup v2
`memory.swap.max=0``0.25 CPU``32 PIDs`、只读 root、cap-drop ALL、no-new-privileges、默认 seccomp、
`8 MiB` noexec/nosuid/nodev tmpfs、非 root user 和仅 `127.0.0.1` 发布端口。authority volume 只读挂载,
management fixture 只存在于隔离 Docker network 且不发布宿主端口。
4. 在四次请求前后从 Console 自身 cgroup v2 读取 `memory.max``memory.peak``memory.swap.max`
`memory.events``cpu.max``pids.max/current`,并从 `/proc/self/status` 读取 NoNewPrivs/seccomp。peak 必须至少
保留 `32 MiB` headroom`max/oom/oom_kill/oom_group_kill` 不能增加。container start identity 前后相同,
因而不能通过重启掩盖累积峰值或 assertion reload 缺陷。
5. synthetic management verifier 只接受 TLS 1.3 和受信 client certificate,固定 service SAN 与
`/api/v3/runs/management`,且只记录 label、TLS、method、path、operation、mutation 等低敏事实。它不是外部
IdP 或生产 authorization attestation。
6. 用户驱动序列固定为 `initial_accepted → rotated_accepted → expired_rejected → rotated_recovered`。Assertion
通过同一只读 volume 内的 `write wx → chown → atomic rename` 原位轮换;Console 每次 POST 重新读取文件,
不能重启、轮询、重试、缓存或触发 mutation。过期 assertion 必须由上游 401 被 BFF 投影为 502 和
`assertion_expired`,响应与日志不能泄露 assertion、authority path 或 service identity。
7. 每个原生 matrix job 生成 exact-shape、source-bound 架构报告,绑定 repository、40 位 revision、workflow、
run ID 与 run attempt。输入为有大小上限、nofollow 的普通 JSON;输出只以 `wx/0600` 新建。内容使用固定
domain separator 的 canonical SHA-256,未知字段、非有限数字、过深或过多节点均失败关闭。
8. Artifact 名精确包含 run ID、attempt 与 architectureupload/download action 固定到完整 commit,禁止
overwrite。独立只读 job 必须等待完整 `cluster-image` matrix,分别下载 x64/arm64,不使用 pattern 或
merge-multiplemerge 重验同源与不同 image ID,随后在同一 job 离线 audit 合并报告。
9. 合并报告显式保留四条 limitation192 MiB workstation envelope 不是 Cluster 吞吐/容量规划;native CI
不是物理 Edge 最低配置、断电、闪存、热环境或 soak 证明;synthetic mTLS verifier 不是外部 IdP 证明;
workflow source binding 不是密码学硬件 attestation。
## 被拒绝的替代方案
### 在 macOS arm64 上用 QEMU 生成双架构结果
拒绝。标签与模拟执行不能代替两个原生 Linux runner;本地只能验证协议、负向门禁和工作流装配。
### 把容量采集拆成多个 workspace package
拒绝。capture、merge、audit 只服务一个 CI evidence contract,没有独立生产依赖、版本、入口或运行时生命周期。
拆分会扩大 package 数和维护面,并重现 `packages/*/src` 只有一个平铺文件的问题。
### 把 192 MiB 写成路由设备最低配置
拒绝。Console 是显式按需的 Cluster operator workstation 工具,Edge/Standalone artifact closure 不包含它;
固定路由器仍需明确硬件、内核、文件系统、断电、闪存、热环境和长时间 soak 证据。
### 把空载 Console 峰值写成 Cluster 容量
拒绝。该门只有四次串行读,没有副本、数据库延迟、并发 operator、Worker、queue、failover 或恢复负载。
Cluster 容量规划必须由独立多节点负载与故障恢复门完成。
### 为 assertion 轮换加入 watcher、polling 或重启
拒绝。既有 server 的每次点击读取已经提供最小、可审计的 reload 语义;watcher/timer 会增加 idle 成本,重启会
破坏 session 并掩盖实际 reload 行为。
## 验证与当前证据状态
- D-370 证据协议与 CI 发布审计聚焦门为 `108/108`;原生 `cluster-image` 聚焦集合连同 SBOM 为 `120/120`。覆盖双架构正向 merge/audit、headroom、swap、OOM、PID、
schema widening、assertion sequence/TLS/mTLS/mutation、digest 篡改、跨 run、重复 image、symlink、overwrite、
live opt-in,以及 capture、matrix dependency、offline audit 的负向 workflow drift。
- 本机 Docker inspect 探针确认 SecurityOpt 为 `no-new-privileges`tmpfs 保留精确 `size=8m` 表示;探针容器已
删除。该探针只用于修正静态 inspect 契约,不冒充 native Linux x64/arm64 容量证据。
- CI 脚本与 workflow 已实现,但当前提交尚未在 GitHub Actions 产生同一 run 的两个原生 architecture artifact。
因此本 ADR 接受的是实现和门禁设计,不能宣称已经取得最终 memory peak、image ID、artifact digest 或 run URL。
- 该变化不改 package/dependency tree、Edge/Standalone runtime closure、PostgreSQL schema/role/Pool 或 HA 拓扑,
不重新占有数据库 HA 证据。
- 18-package clean build 与逐包测试在允许 loopback listener 的宿主环境退出 0Worker Runtime 独立复核为
`133/133`。当前完整 backend 工作区门为 `1,503 total / 1,501 pass / 2 conditional skip / 0 fail`;其中包含一项
与本切片无关、保持未跟踪且不会提交的用户测试,因此 D-370 提交范围对应 `1,502 total / 1,500 pass / 2 skip`。package boundary、dependency、Edge import、Cluster deployment、
Console 与 Console distribution 六项审计均 compatible、零 findingworkspace 仍为 18 packages、无 single/shallow
packageCluster Admin 为 `125 source / 124 nested`
- 14 档 Local artifact audit 全部 compatible;基础 Edge/Standalone 精确为 `2,589,998 / 2,590,076` bytes
Application+AI 为 `4,493,151 / 4,493,283` bytesMCP 为 `7,315,930 / 7,316,038` bytes,证明 CI-only evidence
没有进入低配部署闭包。
## 后续边界
- 推送后记录首个成功 workflow run、x64/arm64 bundle digest、cross-architecture release digest、各架构 image ID/
size/memory peak/headroom 与 artifact retention;若任何架构超过 envelope,必须修实现或调整经过 RFC 评审的
budget,不能放宽 validator 伪造成功。
- 物理 Edge 支持下限继续由 ADR-0088 类型的固定设备矩阵证明;Cluster 节点容量继续由多节点数据库、Worker、
queue、failover 与恢复负载证明。
- 后续若 Console 引入新的 read operation 或生产 dependency,必须重新采集双架构报告并证明仍无 mutation、
polling、authority leak 和 Edge closure 变化。