ADR-0195：AI-excluded 本机 Application 候选镜像

状态：Accepted（候选镜像 contract、arm64 build 与 fresh live gate 已实现）
日期：2026-07-29
关联 RFC：QL-RFC-0001 D-42、D-156、D-168、D-175、D-183、D-184、 D-185
关联 ADR：ADR-0042、ADR-0088、ADR-0167、ADR-0178、ADR-0185、 ADR-0193、ADR-0194、ADR-0196

背景

D-184 的 Compose 描述符已经拒绝 mutable tag，但仓库此前只有 Cluster control/admin 镜像。直接把 workspace mount 到通用 Node image 可以用于测试，不能作为本机交付物：它包含开发依赖，缺少独立 production lock，也无法证明 AI 没有进入默认 Edge/Standalone runtime。

为 Edge 与 Standalone 各建一个镜像也没有收益。两者使用相同 application 代码和生产依赖，仅由私有配置选择 SQLite journal、页预算和资源 envelope。复制镜像会产生两套 lock、SBOM、签名和漏洞响应。

决策

1. 一个镜像、两个本机 Profile、零新增 package

deploy/containers/ql3-local-application 是部署制品目录，不是 workspace package。镜像运行时精确包含：

runtime-core；
local-sqlite、local-admin、local-profile、 local-adopted-profile；
local-command-file、local-secret、local-process、 local-execution、local-application；
croner@7.0.8 与 semver@7.7.4。

Edge/Standalone 继续由 qinglong/local-application-process@v2 私有配置选择。镜像不包含 @qinglong/ai；ai.deployment 只能为 D-184 生成的 excluded。后续 AI 镜像若成立，必须作为独立 opt-in 制品和预算评审，不能修改默认镜像闭包。

2. Builder authority 不进入 runtime

Dockerfile 的两处 base 都直接固定为同一 Node 24.18.0 Bookworm Slim OCI index digest，不提供 NODE_IMAGE build argument。build dependency root 独立锁定 TypeScript、Node/Semver types 与 Drizzle schema 编译类型；ql3-ai 只在 workspace builder 中满足 application 的静态类型编译。

production dependency root 使用另一份 lock，只安装 croner 与 semver。最终 stage 从 builder 仅复制上述十个内部 package 的 package.json 与 dist；删除 npm 自动生成但 entrypoint 不需要的 .bin 链接，以及 TypeScript .js.map/.d.ts.map 调试映射；不复制 AI、Drizzle、TypeScript、cache、源码或开发类型。所有 npm ci 都禁用 lifecycle scripts。

3. 镜像身份与运行 envelope

镜像默认：

USER 65532:65532；
NODE_ENV=production；
唯一 entrypoint 为 ql3-local-application；
不声明端口或 health listener；
标记 edge,standalone 与 ai=excluded。

镜像自身不内置可写数据层。D-184 Compose 描述符必须继续固定：

由 host deployment owner 覆盖 numeric UID:GID；
read-only root filesystem；
network_mode: none；
drop all capabilities 与 no-new-privileges；
唯一 /var/lib/qinglong3 bind；
16 MiB noexec tmpfs；
Edge 128 MiB/64 PID，Standalone 256 MiB/256 PID。

默认 numeric user 是无 Compose 覆盖时的最小权限兜底，不代表它能读取任意 host volume。

4. 候选证明与 release 证明分开

静态审计复核 base digest、两份 manifest/lock、build/runtime package 闭包、非必要文件删除、禁用 install scripts、默认 user、entrypoint 与 labels，并以 mutation fixture 拒绝 mutable base、AI runtime copy、额外 production dependency、非必要文件回归和 lock 漂移。

真实 live contract 使用 D-184 prepare 分别创建 fresh Edge 与 Standalone volume，再在 read-only、network-none 容器中以各自 128 MiB/64 PID 与 256 MiB/256 PID envelope 启动候选镜像。只有观察到 active、由 docker stop 触发 SIGTERM、stopped、exit 0，并在退出后取得 SQLite integrity_check=ok 才通过。

CI 在原生 amd64 与 arm64 runner 重复 build、identity、CycloneDX inventory、 --help 和 fresh live contract。ADR-0196 又把本机 profile 接入共享 attested OCI 与 release matrix；当前本机 arm64 成功仍不能替代尚未执行的远端双架构结果。

本 ADR 不接受以下 release 声明：

本地 tag 或 Docker image ID 是可分发 digest；
单架构镜像代表双架构 OCI manifest；
lock 文件代表 SBOM；
Dockerfile 存在代表 provenance/signature；
128 MiB Docker 门代表固定物理路由器的闪存、冷启动或断电证据。

当前证据

静态 contract：findings=[]；
mutation audit：6/6（含非必要文件与双 Profile/双架构 CI contract）；
runtime inventory：10 个内部 package、2 个外部 package、AI absent， 611/640 files、4,897,102/5,242,880 bytes、无 symlink/special file；
本机镜像：Linux arm64、默认 65532:65532；
uncompressed image：251,932,346 bytes；
Edge live：128 MiB、0.5 CPU、64 PID、network none、read-only root；
Standalone live：256 MiB、0.5 CPU、256 PID、同一镜像与隔离边界；
两个 application：各 19 个低敏事件，active 后 SIGTERM graceful stop；
SQLite：integrity_check=ok。

后续发布门

原生 amd64/arm64 CI 的实际成功记录；
ADR-0196 已实现但尚未取得成功记录的双架构 OCI index、逐平台 digest、 CycloneDX/SPDX、provenance、keyless signature 与远端 registry 回读；
npm high/critical 与 SPDX license policy 已实现；base/OS vulnerability scanner 仍待完成；
固定低配路由器的存储占用、冷启动、idle RSS、断电、ENOSPC/EROFS；
image upgrade/rollback 与 D-184 service activation controller。

5.5 KiB Raw Blame History Unescape Escape