mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
feat(ql3): add strong cluster run stop
This commit is contained in:
whyour
@@ -11,6 +11,20 @@
|
||||
|
||||
最新增量证据（2026-08-12）：
|
||||
|
||||
- D-296/ADR-0384（已接受）
|
||||
Cluster Run Management Plane 已在既有内聚领域内增加强认证 `run.stop`，不新增 package、进程、listener、Pool、timer、watcher、cache、
|
||||
sidecar 或部署 overlay。`run.retry | run.stop` 共用 mTLS、purpose-bound OIDC、五分钟内 `multi_factor|hardware` User、固定
|
||||
`/api/v3/runs/management` route 与 `operations/run-management` opt-in workload；默认 Edge、Standalone 和 Cluster base 的资源与
|
||||
依赖闭包不变。服务端生成 canonical `qinglong/run-cancellation@v1` Event identity，并在单个 `SERIALIZABLE` 事务中重验
|
||||
Project/RoleBinding fence、写 durable cancellation intent/Event 和 `run.stop` allowed audit；相同 mutation 精确重放，不同 mutation
|
||||
不覆写，实际终态仍由既有 cancellation dispatch/fencing 收敛。PostgreSQL capability v56 / migration
|
||||
`pg-0057-run-management-stop-boundary` 只向 `ql3_run_manager` 授予 Runs 的
|
||||
`cancel_requested_at_ms/cancel_reason/version/event_sequence` 四列 UPDATE，表级 UPDATE 和 `status` 列 UPDATE 均保持禁止。
|
||||
本阶段坚持由领域内聚、依赖方向和部署生命周期决定 package 粒度，拒绝为 stop 新增浅 package。完整 18-package clean build/test
|
||||
与 backend 1,165 pass/2 conditional skip/0 fail；workspace 保持 18 package/1,071 source/1,053 nested，无 single-source 或 shallow
|
||||
package；14 档 Local Profile artifact 全部 compatible，最小 Edge 仍为 53 loaded modules 且不含 Cluster/PostgreSQL。真实 PostgreSQL
|
||||
18.4 arm64 physical HA 通过 123 gates、timeline `1→2`，覆盖双 Pool exact replay、原子审计复制、cancellation convergence 和同步冗余
|
||||
恢复后的 promotion stop；报告 SHA-256 `2e5759d3b5e62cd571f6c31450aec0d7f611fa8cafd727b7bb25471792e83c29`，离线审计零 finding。
|
||||
- D-295/ADR-0383（已接受）
|
||||
Cluster 手动 `run.retry` 已从“仅有 PostgreSQL authority”推进到独立强认证产品面：能力内聚在既有 `@qinglong/cluster-admin`
|
||||
的 `run-management/` 目录，不新增 workspace package；只有 `QL3_PROFILE=cluster-admin` 且显式启用时才读取 mTLS/CRL、
|
||||
|
||||
@@ -6,6 +6,8 @@
|
||||
- 前置决策：ADR-0039、ADR-0056、ADR-0356、ADR-0364、ADR-0366、ADR-0381、ADR-0382
|
||||
- Supersedes：ADR-0382 中“复用 `ql3_runtime` 且不新增 role/migration”的产品装配决策；ADR-0382 的共享语义与 PostgreSQL 原子事务仍有效
|
||||
|
||||
> 后续说明：ADR-0384 在不改变本 ADR 的进程、认证、部署与 package 边界下增加 `run.stop`，并 supersede 本文“`ql3_run_manager` 不更新既有 Run”的最小权限定义；该角色改为只允许更新取消意图所需的四个列。
|
||||
|
||||
## 上下文
|
||||
|
||||
ADR-0382 已证明 PostgreSQL 手动 Run retry 的原子语义与 HA 收敛，但现有 Cluster Control bearer 只能建立 `single_factor` User，不能承载会再次执行外部副作用的人工恢复操作。直接把 repository 接进通用 Cluster HTTP 会混合普通控制面与强人类认证 authority；继续使用 `ql3_runtime` 又会使常驻 runtime 持有本不需要的人工恢复权限。
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# ADR-0384：强认证的 Cluster Run Stop Management
|
||||
|
||||
- 状态：Accepted
|
||||
- 日期：2026-08-12
|
||||
- 关联 RFC：QL-RFC-0001 D-296
|
||||
- 前置决策：ADR-0005、ADR-0039、ADR-0056、ADR-0372、ADR-0383
|
||||
- Supersedes：ADR-0383 中“`ql3_run_manager` 没有更新既有 Run 权限”的最小权限定义；其余进程、认证、部署与 package 决策保持有效
|
||||
|
||||
## 上下文
|
||||
|
||||
ADR-0383 已建立独立、强认证、显式启用的 Cluster Run Management Plane，但产品面只暴露 `run.retry`。Cluster Control 已有内部 cancellation repository，直接把它接到产品 route 会留下三个缺口：允许审计与取消意图不在同一事务、专用管理角色没有精确写权限、调用方可能绕过 Run Management 的 purpose-bound OIDC 与五分钟强认证。
|
||||
|
||||
QingLong 同时面向低资源路由设备和多节点集群。本能力不能给 Edge/Standalone 增加常驻成本，也不能为单个命令新增浅 package、独立进程、连接池或部署 overlay。
|
||||
|
||||
## 决策
|
||||
|
||||
### 1. 扩展既有内聚领域，不新增 package 或进程
|
||||
|
||||
`run.stop` 与 `run.retry` 复用 `@qinglong/cluster-admin/run-management` 的 service、discriminated transport、HTTPS route、client、OIDC keyset、mTLS listener、PostgreSQL Pool 和 `operations/run-management` 部署。PostgreSQL adapter 继续由 `@qinglong/cluster-postgres/run-manager` 发布。
|
||||
|
||||
默认 Edge、Standalone、Cluster base overlay 均不加载该能力；关闭 Run Management 时仍为零新增进程、listener、Pool、timer、watcher、cache、sidecar 与 Cluster dependency。这里以“领域内聚 + 独立部署生命周期”决定 package 粒度，不以文件数量决定 package 数量。
|
||||
|
||||
### 2. 固定强认证命令与服务端身份
|
||||
|
||||
transport 只接受 `operation=run.stop`、Project/Run identity、UUID mutation identity 和低敏 request/audit identity，不接受 caller 提供 Event ID、时间、取消原因、Run version 或状态。服务端生成 canonical `qinglong/run-cancellation@v1` Event ID，并固定 `cancel_reason=user`。
|
||||
|
||||
操作必须同时满足 mTLS、`run-management` purpose-bound OIDC、五分钟内 `multi_factor|hardware` User 和 `run.stop` Policy。route admission 与 PostgreSQL 事务分别重验身份和 Project/RoleBinding fence；不存在继续遮蔽，终态或 durable fence 漂移稳定映射为 conflict。
|
||||
|
||||
### 3. 取消意图与允许审计原子提交
|
||||
|
||||
PostgreSQL repository 在一个 `SERIALIZABLE` 事务中使用数据库时钟，锁定 Run，重验 `lock_run_management_policy_fence`，写入 `cancel_requested_at_ms`、`cancel_reason`、Run `version`、`event_sequence`，追加 immutable cancellation Event 和 `run.stop` allowed security audit。任一写入失败都整体回滚；拒绝或不可用由 service 写独立 failure audit。
|
||||
|
||||
相同 mutation 的重放必须返回 `already_requested`，并验证已有 Event 与 allowed audit 的精确语义；不同 mutation 不能覆写既有取消意图。terminal Run 不接受新的 stop。该操作只记录 durable intent，实际 Attempt/Run 收敛仍由既有 cancellation dispatch、lease/fencing 与 recovery authority 完成。
|
||||
|
||||
### 4. PostgreSQL 权限按列收窄
|
||||
|
||||
Migration `pg-0057-run-management-stop-boundary` 把 control-core contract 提升到 v56，并添加 `run_management_stop` capability。`ql3_run_manager` 不获得 Runs 表级 UPDATE，只获得以下四列的 column-level UPDATE：
|
||||
|
||||
- `cancel_requested_at_ms`
|
||||
- `cancel_reason`
|
||||
- `version`
|
||||
- `event_sequence`
|
||||
|
||||
readiness 同时证明四列可更新、`status` 不可更新、表级 UPDATE 仍为 false。角色不得改变 Run 状态、Project/RoleBinding、Task、execution revision，且继续没有 DELETE、migration、Worker、AI 或 Approval authority。
|
||||
|
||||
## 验收
|
||||
|
||||
- service/transport/client 测试覆盖 stop、强身份、命令 shape、response drift、原子 allowed audit 与稳定错误映射；
|
||||
- PostgreSQL 测试覆盖 v56 checksum/capability、精确列权限、事务顺序、exact replay、fence 漂移和回滚；
|
||||
- 真实 PostgreSQL 18.4 physical HA 以两个独立 `ql3_run_manager` Pool 证明跨 Pool replay、允许审计同步复制与 promotion 后写入；
|
||||
- 完整 18-package clean build/test、backend、dependency/package/deployment/Profile artifact、GitNexus change scope 全部通过后才允许阶段性提交。
|
||||
|
||||
## 被否决的替代方案
|
||||
|
||||
1. **新增 `@qinglong/run-stop` package**：没有独立依赖、制品或部署生命周期，只会制造浅 package。
|
||||
2. **新增 stop listener/Pool/overlay**：与 retry 共享同一认证和资源边界，会重复常驻成本。
|
||||
3. **授予 Runs 表级 UPDATE**：会允许管理角色修改状态与其他控制字段，超出产品操作所需。
|
||||
4. **先写 allowed audit、再写取消意图**：可能留下“审计显示成功但意图未提交”的错误事实。
|
||||
5. **由调用方提交 Event ID 或 cancel reason**：扩大重放和语义漂移表面。
|
||||
|
||||
## 验收证据（2026-08-12）
|
||||
|
||||
- `@qinglong/cluster-admin`：284 pass、2 个外部集成条件 skip、0 fail；`@qinglong/cluster-postgres`：311 pass、1 个外部数据库条件 skip、0 fail；完整 18-package clean build/test 全部退出 0；
|
||||
- backend 1,167 项中 1,165 pass、2 个环境条件 skip、0 fail；package/dependency/Edge import/Cluster deployment/CloudNativePG/Local image 静态门均 compatible、零 finding；
|
||||
- workspace 保持 18 个 package、1,071 个 source、1,053 个 nested，`singleSourcePackages=[]`、`shallowSourcePackages=[]`；`cluster-postgres` 为 153/152，v56 migration 归入既有 `run-management` 领域，没有新增浅 package；
|
||||
- 14 档 Edge/Standalone Profile artifact 全部 compatible；最小 Edge 仍仅包含 Local SQLite、Runtime Core 与 `semver`，产物 2,459,624 bytes、53 个 loaded module，未引入 Cluster/PostgreSQL；
|
||||
- PostgreSQL 18.4 arm64 physical HA 通过 123 gates、timeline `1→2`，证明列级 UPDATE readiness、双 Run Manager Pool exact replay、allowed audit 同步复制、既有 cancellation convergence、旧主 fencing，以及恢复 `remote_apply` 同步冗余后的 promotion stop；报告 SHA-256 `2e5759d3b5e62cd571f6c31450aec0d7f611fa8cafd727b7bb25471792e83c29`，独立离线审计 `compatible:true`、零 finding。
|
||||
|
||||
## 影响
|
||||
|
||||
- PostgreSQL schema contract 从 v55 升至 v56；启用新版 Run Management 前必须先运行 migration 和 readiness；
|
||||
- Cluster Run Management route 成为 `retry | stop` 的严格判别联合，但既有 retry envelope/response 保持兼容；
|
||||
- 低配设备默认资源与依赖闭包不变；集群只在已选择的 Run Management workload 内增加同一 Pool 上的一类短事务；
|
||||
- UI 后续可以复用同一 transport 展示 durable cancellation intent，但不得直接写 Run 状态或绕过强认证。
|
||||
@@ -387,6 +387,7 @@
|
||||
| [ADR-0381](./ADR-0381-strong-local-manual-run-retry.md) | 强认证的 Local 手动 Run retry | Accepted |
|
||||
| [ADR-0382](./ADR-0382-postgresql-cluster-manual-run-retry-authority.md) | PostgreSQL Cluster 手动 Run retry 原子 Authority | Accepted |
|
||||
| [ADR-0383](./ADR-0383-strong-cluster-run-management-plane.md) | 强认证的 Cluster Run Management Plane 与专用数据库角色 | Accepted |
|
||||
| [ADR-0384](./ADR-0384-strong-cluster-run-stop-management.md) | 强认证的 Cluster Run Stop Management 与列级数据库权限 | Accepted |
|
||||
|
||||
## 规则
|
||||
|
||||
|
||||
Reference in New Issue
Block a user