5.0 KiB
ADR-0525：Console Adopted Target 入口证据
- 状态：Accepted（源码与 CI 门禁已实现；exact Console 双架构阶段实物待生成）
- 日期：2026-09-01
- 决策：D-426b2c
- 关联：ADR-0512、ADR-0513、ADR-0522、ADR-0523、ADR-0524
上下文
ADR-0524 已用 headless Trial Kit 的只读 Application cutover probe 闭合 clean rollback 证据，但 Console 镜像的生产入口是 ql3-local-api。普通 Local API 启动会同时启动 Application、loopback listener、认证操作面、recovery、scheduler 与 execution admission；直接把它用于切换探针可能改变 adopted SQLite，既不适合低性能路由设备，也不能证明“target 尚未接收业务写入”。
把 Console artifact 继续标记为 legacyUpgradeCutover=not_applicable 又会留下另一类缺口：fresh Console journey 只能证明面板可用，不能证明下载到的 Console 镜像可由 adopted target controller 以 exact 生产入口启动。
决策
ql3-local-api增加显式--cutover-probe --config <local-api.json>模式。它严格解析 Local API 配置，随后调用既有 Application 只读 cutover probe；不绑定 listener、不读取 credential 或 pepper、不启动 recovery、scheduler、execution、plugin recovery 或产品管理面，也不持有可写数据库。- Target run command 增加可选
targetApi入口绑定：宿主 Local API 配置路径和容器内 exact 入口配置路径。省略该字段时，既有 headless command、journal digest 与证据 shape 保持不变。 - Console target evidence 同时绑定外层 Local API 配置与内层 Application 配置：
- 外层 schema、配置摘要、loopback host/port、deployment root、严格位于 root 内的 Owner pepper 目录；
- 外层
applicationConfigFilePath必须指向 exact 内层 Application target path；两个配置 target path 必须不同； - 两份只读配置 mount、deployment root mount、数据库与既有 activation/recovery/manifest/legacy mounts；
- 容器命令必须精确为
['--cutover-probe','--config',expectedLocalApiPath]。
- Trial Kit 的 canonical
upgrade-cutover-rehearsal.sh同时支持headless|console。Console rehearsal 生成私有外层配置，运行同一 reviewed stage、Owner 强认证 apply、真实 synthetic Legacy stop、Console image probe start/stop 与 clean rollback classifier；成功 summary 升级为qinglong/local-alpha-upgrade-cutover-summary@v2，并绑定 variant 与 target entrypoint。 - 原生 amd64/arm64 artifact workflow 对两个变体都要求
legacyUpgradeCutover=passed，并在上传前删除 synthetic target/legacy 容器。fresh Console journey 仍单独证明真实 listener、HTTP、credential 与自动化能力，不能由无 listener probe 替代。
Profile 与资源边界
- Edge/路由设备：默认仍选择 headless；若显式选择 Console，cutover probe 只增加一次性配置读取与只读 SQLite readiness，不新增 listener、daemon、timer、watcher、连接池或稳态 RSS。
- Standalone：与 Edge 使用同一证据模型，只保留现有 Profile 资源上限差异。
- Cluster：不复用 Local SQLite、POSIX owner、loopback Console 或 Docker target proof；Cluster control/admin/worker 部署链不变。
被拒绝的方案
- 用普通
ql3-local-api --config做 probe：会激活写能力，破坏 clean rollback 语义。 - 只校验 Application 内层配置：不能证明下载镜像的真实 Console entrypoint 与 mount authority。
- 为 Console 增加独立 probe daemon/sidecar：扩大低配设备常驻面，且制造第二套生命周期。
- 把 fresh Console HTTP journey 当作 upgrade cutover：两者验证的权限、数据状态与失败恢复语义不同。
验证与交付状态
- Local API：80/80；cutover probe 单测覆盖成功、配置漂移与不启动 listener；
- Local Owner CLI：314 total / 307 pass / 7 conditional skip / 0 fail（新增双配置正向、内层指向漂移、路径别名与 Owner 目录边界）；
- Trial Kit bundle：12/12；Console gate 从
not_applicable改为passed，summary v2 绑定variant=console与targetEntrypoint=local-api； - Local Application：56 total / 51 pass / 5 conditional skip / 0 fail；
- package boundary、Cluster dependency、Edge import 与 Local image/operator image audit 均为 compatible；workspace package 仍为 18 个，未新增依赖、package 或常驻进程。
本机 exact Console image build 尚未形成阶段实物：Docker 配置的镜像镜像源 register.liberx.info 在解析固定 Node base image 时连续 EOF，构建未进入源码层。因此本 ADR 当前只声明“源码与 CI 门禁已实现”；只有同源原生 amd64/arm64 Console artifact、milestone 与离线 auditor 在成功终态 workflow 中闭合后，才能升级为“阶段实物已交付”。
后续
D-426c 继续处理 target 接收写入后的 capture、review、reconciliation 与恢复；Public Release 仍需受保护 tag、immutable multi-arch digest、签名/attestation、deployment lock 与生产回退门。