ADR-0458：最小权限 CancellationDispatch 诊断与人工 Rearm

状态：Accepted
日期：2026-08-19
关联 RFC：QL-RFC-0001 D-365、PR-5、PR-7
关联 ADR：ADR-0005、ADR-0383、ADR-0456、ADR-0457
Amends：ADR-0005 的 blocked 人工处置边界、ADR-0456 的 PostgreSQL Run manager authority

上下文

ADR-0456/0457 已让 Cluster Run cancellation 具备数据库计时、跨副本 fencing 和真实 Worker 交付，但 identity_mismatch、pid_mismatch、unsupported、invalid 会有意进入 blocked，禁止自动重试。没有受权诊断与人工 rearm 时，operator 只能直接查询或修改数据库；这既容易泄露 lease capability，也绕过 Project Policy、强认证、RunEvent 和安全审计。

QingLong 同时面向低配路由器与集群。该能力只属于 Cluster operator plane，不能扩大 Local Profile 闭包，也不应为了两个 operation 新建微包、HTTP 服务、扫描 timer 或数据库连接池。

决策

复用既有隔离 cluster-admin Run management HTTPS/mTLS process、固定 /api/v3/runs/management 路径、OIDC assertion、速率限制、连接池和 shutdown lifecycle。新增 operation 为 run.cancellation.inspect 与 run.cancellation.rearm，不新增服务或部署对象。
inspect 只接受强认证 User，授权使用既有 run.read。因此 viewer 可诊断，agent、弱认证、过期认证和 authorization fence drift 均失败关闭。
diagnostic 只投影 Project/Run 状态、取消意图、Attempt ID、dispatch status/version/count、受限时间戳、固定 last result 与 none|wait|rearm 建议。lease owner、raw token、token digest、PID、handle、命令、环境、Secret 和错误原文永不进入 SQL projection、transport schema 或客户端结果。
rearm 继续使用 run.stop，不新建更宽 permission。请求必须精确匹配 blocked、expected dispatch version 和 expected blocking result，并提供 1 秒至 24 小时的 retry delay；服务端生成 RunEvent ID，调用方不能塑造 event identity。
Repository 使用 SERIALIZABLE 短事务和 PostgreSQL transaction_timestamp()。它重新锁定 Project Policy fence 与 Run，验证非终态 Run、既有 cancellation、同 Run active Attempt 和精确 dispatch CAS；绝对 next_attempt_at_ms 只能由数据库计算。
成功 rearm 在同一事务中推进 Run version/event sequence，把 dispatch 切换为 retry_wait 并递增 version，追加 run.cancel_dispatch_rearmed 和 allowed security audit。事件 payload 只包含 mutation、前后 version、固定 blocking result、delay、due time 与 Run version。
mutation replay 先读取 immutable RunEvent，只有 actor、mutation、version、result、delay 和 receipt 全部相同时返回原 receipt；任何漂移返回 conflict，不重复更新 dispatch。
rearm 保留原 blocking last_result 作为历史，因此 canonical/SQL 状态约束允许 leased|retry_wait 携带 blocking 或 retryable history；新 claim/result 仍按当前 status 与精确 fence 决定，不把历史结果当作新的 controller verdict。
pg-0067-cancellation-dispatch-management 把 capability 提升至 v66。ql3_run_manager 只新增 dispatch SELECT 与四列 UPDATE：status、version、next_attempt_at_ms、updated_at_ms；没有 INSERT、DELETE、TRUNCATE、lease 字段 UPDATE 或 schema authority。
Attempt active check 在已有 SERIALIZABLE 事务与 Run 行锁后执行普通 SELECT。PostgreSQL 的 FOR KEY SHARE 也隐含要求至少一列 UPDATE 权限；为行锁扩大 Run manager 的 Attempt UPDATE authority 被拒绝。并发终态变化由 Run 锁与 serializable ordering 收敛。
新 repository 留在现有 cluster-postgres/run-management 子域，协议留在现有 cluster-admin/run-management 子域。新增两个文件不会成为拆分 package 的理由；workspace 继续精确为 18 包。

被拒绝的替代方案

直接暴露数据库记录

拒绝。原始表包含 lease owner/token digest 等 capability-adjacent 字段，也没有逐请求 Policy、强认证、审计和响应 shape 验证。

blocked 自动重试

拒绝。身份、PID 或协议不匹配不是瞬时可用性问题；自动循环可能向错误执行实例重复交付停止。

新建 cancellation-admin 服务或 package

拒绝。既有 Run management plane 已拥有完全相同的用户身份、Project Policy、mTLS、连接和生命周期边界。另建服务会增加低价值微包、端口、Secret 和部署成本。

给 Run manager 增加 RunAttempt UPDATE 权限

拒绝。该权限只为满足 PostgreSQL 行锁语法，而不是业务 mutation。SERIALIZABLE + Run lock + 普通读取足以表达合法顺序，不能为了实现细节扩大 authority。

资源、安全与部署影响

Edge/Standalone package closure 不包含 cluster-admin、cluster-postgres 或 pg；14 个 Local Profile 预算不变化。
Cluster 复用既有 caller-driven management request，没有扫描 timer、后台队列、缓存、额外连接或空闲写入。
每次 inspect/rearm 最多一个 5 秒 statement timeout 的 SERIALIZABLE 短事务；rearm 只在人工明确操作时写一条 RunEvent 和一条 audit。
response 与客户端都做 exact-shape 验证；未知字段、目标漂移、version/result/delay 漂移和 lease capability 泄漏失败关闭。

验证

Repository 聚焦测试 5/5，service 6/6，transport/client 12/12；覆盖低敏 inspect、viewer/read 与 operator/stop 分权、exact replay、stale fence、失败审计和 secret-field tampering。
cluster-postgres 完整包 339 pass / 0 fail / 3 conditional skip；cluster-admin 完整包 394 pass / 0 fail / 3 conditional skip。
完整 backend 1,487 pass / 0 fail / 2 conditional skip；18-package clean build/test 退出 0。
package boundary、cluster dependency、Edge import、cluster deployment 四项审计零 finding；workspace 仍为 18 包，Cluster PostgreSQL 为 172 source/171 nested，根入口计数不变。
14/14 Local artifact audit 通过：基础 Edge/Standalone 2,589,998 / 2,590,076 bytes，Application+AI 4,493,151 / 4,493,283 bytes，均不包含 PostgreSQL closure。
PostgreSQL 18.6 arm64 HA 144/144：真实 ql3_run_manager 执行 blocked→inspect→rearm，验证 retry not-due、最终 production dispatch、同步 WAL、主库隔离与 standby promotion；timeline 1→2，报告 SHA-256 58f43327f426c286aaa1764aa6dd9f5963a462304716e09b933f326991442b8a。

后续

ADR-0459 已用既有管理面完成数据库事实驱动的 Project 级 blocked/availability 汇总；ADR-0460 已增加一次性产品状态卡、稳定 JSON 与告警退出码。有界 blocked drill-down 和 Console 可选接入仍待实现。CloudNativePG live failover、多副本容量压力、固定 Linux x64/arm64 与物理 Edge 资源证据继续作为发布最终化门，不由单机 Docker HA 结果替代。

6.9 KiB Raw Blame History Unescape Escape