mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
43 lines
4.8 KiB
Markdown
43 lines
4.8 KiB
Markdown
# ADR-0531：现有面板到规范 Run 日志的有界桥接
|
||
|
||
- 状态：Accepted（D-429 exact Console 双架构阶段实物已交付）
|
||
- 日期：2026-09-04
|
||
- 关联 RFC：QL-RFC-0001 D-429、D-428、D-415
|
||
|
||
## 背景
|
||
|
||
ADR-0530 已把现有 2.x 面板作为受限静态客户端装入 Local Console，并只开放 Cron 列表。用户仍无法从该页面观察一次定时执行的日志。恢复旧 `/api/crons/:id/log`、文件系统日志目录或 2 秒轮询，会复制已经存在的 3.0 Run/Attempt/Artifact 权威，并给 Edge 路由设备增加持续请求。
|
||
|
||
Run 聚合已经持久化可选 `triggerId`，规范 Local API 已提供有界 Run list、Run detail 与 Attempt log range read。缺口不是新的日志后端，而是安全地把这条规范链交给受限旧页面。
|
||
|
||
## 决策
|
||
|
||
- `BoundedRunListItem` 增加可选 `triggerId`。只有值存在且满足 128 字节无控制字符边界时才投影；其余 Run 私有字段仍不跨越 projection。
|
||
- 旧面板不新增 `/api/crons/:id/log` 兼容路由。用户点击某个 Cron 的“日志”后，页面按 capability budget 分页读取 `/api/v3/projects/:project/runs`，以 `triggerId + taskId` 精确选择最新 Run，再读取 Run detail 的 latest Attempt 和该 Attempt 的首个日志片段。
|
||
- 每次日志片段仍经过既有 Bearer authentication、`artifact.read` Policy、durable audit、credential reconfirm 与 Artifact retention 检查。页面不接触文件路径、Artifact id 或 Secret。
|
||
- Edge 最多扫描 64 条 Run、读取 16 KiB；Standalone 最多扫描 256 条 Run、读取 32 KiB。每页最大 64 条。未找到、尚未就绪、已清理、运行中无 Artifact 和截断状态必须显式呈现。
|
||
- QL3 模式下 Cron 列表不再运行旧页面的 10 秒轮询，日志也不运行旧页面的 2 秒轮询。初始列表只读一次，后续列表由分页/页面动作触发；日志只由点击和“刷新”按钮触发。
|
||
- QL3 的 Action 列只保留“日志”。运行、停止、更多、创建、批量操作和写 Modal 继续隐藏；2.x 模式保持原行为。
|
||
|
||
## 部署与架构边界
|
||
|
||
- 不新增 workspace package、production dependency、migration、schema、数据库连接、listener、timer、watcher 或后台进程。
|
||
- 默认 headless 产物不含旧面板，资源占用不变。Console 仍使用同一个 loopback Local API 和同一个受限静态闭包。
|
||
- Cluster 不复用 Local 面板 shell；`triggerId` 是 profile-neutral 的 Run 低敏感关联字段，因此规范 Run projection 可被 Local/Cluster 消费，但本 ADR 不新增 Cluster UI。
|
||
- 这是一条迁移期客户端桥接，不把 2.x 页面定义为 QingLong 3.0 的领域模型或长期管理面。新的 3.0 能力优先进入原生 `/console`。
|
||
|
||
## 验证与剩余门禁
|
||
|
||
本地已完成 runtime-core 594/594、Local API 93/93、18-package clean build/test、后端 1685 项（1683 pass / 2 environment skip / 0 fail）、兼容闭包回归 4/4、Node 20 production panel build，以及 package boundary、Edge import、Cluster dependency 和 240 files / 11,965,017 bytes 离线闭包审计。真实 Chromium mock journey 验证了 QL3 credential 登录、只读 Action 列、Run list → Run detail → Attempt log 三个规范请求和 Base64/UTF-8 日志展示；页面稳定 15 秒只有一次 Cron list，日志打开后稳定 5 秒没有自动重读。
|
||
|
||
运行时代码提交 `09ef1745226c05521a9a44accb9d9ef95dd46c85` 的主 CI [run 33787481413](https://github.com/whyour/qinglong/actions/runs/33787481413) 为 42 success / 3 expected condition skip / 0 fail；独立 Kubernetes deployment live [run 33787481415](https://github.com/whyour/qinglong/actions/runs/33787481415) 与 Security Administration live [run 33787481443](https://github.com/whyour/qinglong/actions/runs/33787481443) 均成功。显式 Console artifact [run 33789576578](https://github.com/whyour/qinglong/actions/runs/33789576578) 为 43 success / 2 expected skip / 0 fail，交付 amd64/arm64/milestone artifact `9907367021`/`9907250404`/`9907412968`，大小 `239029707`/`234429387`/`6797` bytes，保留至 2026-10-03。下载后的 `SHA256SUMS` 与 `qinglong/alpha-local-milestone-audit@v7` 均通过，source revision、Console variant、workflow run 和双架构身份完全一致，`compatible=true`。D-429 因此闭合为可直接试运行的阶段页面产物。
|
||
|
||
后续仍需把旧面板外部装饰资产本地化，并按独立 ADR 评审原生 `/console` 的任务详情、日志续读和明确写操作；不得用兼容面一次性恢复 2.x 全部管理权限。
|
||
|
||
## 不做的方案
|
||
|
||
- 不恢复旧文件日志 API 或任意路径读取；
|
||
- 不把日志轮询速度做成配置项；低端设备默认仍会付出持续成本；
|
||
- 不在本切片开放 Run start/stop、Cron mutation 或完整 `/log` 页面；
|
||
- 不为复用旧页面而把 Local SQLite/POSIX authority 带入 Cluster。
|