qinglong/docs/adr/ADR-0259-purpose-bound-cluster-automation-management-process.md

ADR-0259：用途隔离的 Cluster Automation Management 进程

• 状态：Accepted
• 日期：2026-08-01
• 关联：D-207、D-208、D-239、D-241、D-242、ADR-0104、ADR-0105、ADR-0244、ADR-0258

上下文

Fresh Edge/Standalone 已有短生命周期 ql3-task 与 ql3-trigger，但 Cluster 仍没有受支持的 Task/Trigger 写入口。把 PostgreSQL administration repository 暴露给通用 cluster-admin 根组合、 复用 ql3_admin，或让 runtime 直接写 Task/Trigger，都会让常驻调度/执行进程获得人类管理权限。 另建只含少量文件的 workspace package 又会增加发布、SBOM、依赖审计和低配设备 importer 成本。

部署跨度也不能被一个默认值掩盖：低配路由器应保持零管理 listener、零 PostgreSQL Pool；生产集群 需要可滚动升级的双副本、持久身份防回滚与独立数据库角色。开发单节点可以选择非 HA 形态，但不能 把它声明成生产基线。

决策

1. Cluster Task/Trigger 管理由独立 ql3-automation-manage 进程持有。实现作为既有 @qinglong/cluster-admin 与 @qinglong/cluster-postgres 子入口交付，不新增 workspace package； 通用 bootstrapClusterAdmin 不再持有原始 Task/Trigger repository port。
2. PostgreSQL 新增唯一 ql3_automation_manager 登录角色。它只取得 Project Policy、Task/Trigger administration、低敏 security audit 与 automation-management 身份账本所需的精确权限； ql3_admin、runtime、Package manager 和 Worker manager 均不能读写该管理面。
3. task.publish 与 trigger.publish 只接受 strong User（multi_factor|hardware），分别要求 Project Policy 的 task.create|task.update 与 trigger.create|trigger.update，并在 PostgreSQL SERIALIZABLE 事务中原子写 immutable revision、current head、allowed audit 与 exact replay。 Trigger 必须固定 current enabled Task；scheduler 候选与最终 Run admission 继续重验 current fence。
4. 网络边界固定为 TLS 1.3 + 双向 TLS + 用途绑定的 OIDC 断言。断言必须同时使用 aud=qinglong3-automation-management、typ=ql3-automation-management+jwt、 ql3_purpose=automation-management；Plugin Package/Worker 管理断言即使共享 issuer/key 也拒绝。
5. public keyset 仍使用共享的 management identity ledger 存储结构，但 authority 行严格分为 plugin-package-management、worker-credential-management、automation-management。 PostgreSQL contract v51 允许 automation manager 精确维护自己的行，并拒绝 generation 回滚、 同代改写、隐式删除 key 与跨用途读取。
6. Kubernetes operation 默认显式 opt-in，使用两个副本、required pod anti-affinity、PDB=1、 无 ServiceAccount token、non-root/read-only rootfs、ClusterIP 8445。base 仅允许 DNS egress； CloudNativePG overlay 仅增加 cnpg.io/cluster=ql3-postgres TCP 5432，并绑定独立数据库 Secret、 operator CA 与 fail-closed Admin image digest。
7. Operator 产品调用复用共享 authenticated management client 的私有文件、TLS 1.3、mTLS、响应上限 与低敏错误实现，但使用 automation 专属 path/command/result validator。ql3-automation-client 对 返回的 Project、Task/Trigger ID、Task revision/content digest 重新绑定原请求；Kubernetes automation-management-client 是 backoffLimit=0、无 RBAC/token 的 caller-driven Job。Task body 可能敏感，因此 request 使用 immutable Secret，而不是 Worker client 的 ConfigMap 模式。
8. 资源分层不能通过自动探测硬件后静默改变安全语义：

   形态	Automation 管理入口	常驻管理成本	支持边界
   Edge 路由器	ql3-task/ql3-trigger 私有 command file	0 listener、0 Pool	SQLite、本机 Owner、短生命周期
   Standalone	同 Edge，可由 UI 调同一 local service	0 独立管理 daemon	不安装 Cluster authority
   单节点开发集群	私有 overlay 可设 1 Pod、Pool 1	非 HA	只用于开发/恢复演练
   Cluster HA	2 Pod、每 Pod Pool 2、32 connections/16 concurrent requests	requests 合计 200m CPU/256Mi	当前生产基线
   更大集群	显式 overlay 横向扩展并同步评审 DB role connectionLimit/限流	有界配置	不提供无界 autoscale 默认值

被拒绝的方案

1. 新建 ql3-automation-management workspace package：没有独立依赖或发布价值，且现有两个 Cluster 包已经是部署/权限 owner；子入口足够。
2. 复用 ql3_admin 或通用 Admin 进程：会把临时运维 authority 和持续人类管理 authority 合并。
3. 让 Cluster runtime 直接发布 Task/Trigger：执行面一旦被利用即可修改未来调度定义。
4. 让路由器也启动 HTTPS manager：增加空闲 RSS、端口、证书轮换与连接池，且本机已有更小入口。
5. 只靠内存记住 OIDC generation：全副本重启会接受旧投影；必须由 PostgreSQL ledger 固定历史。
6. 按 CPU/RAM 自动选择安全 Profile：资源探测可能漂移，部署者必须显式选择并留下配置证据。

验证

• cluster-admin automation service/transport/HTTPS/process/client 定向测试通过；完整包为 196 pass、 2 条真实 PostgreSQL/Kubernetes 条件 skip、0 fail；独立进程验证 disabled 不开 authority、Cluster Profile gate、 Pool/HTTP 上限、TLS 私钥清理和 HTTP→DB 关闭顺序。
• cluster-postgres contract v51 完整包为 271 pass、1 条真库条件 skip、0 fail；migration checksum、 readiness、角色权限、Task/Trigger current-head repository 与三用途 identity ledger 隔离均通过。
• PostgreSQL 18.4 arm64 HA 重跑通过：remote_apply、timeline 1→2、旧主 fencing、pg_rewind 只读同步重入；automation ledger 两实例竞争至 generation 3，并拒绝回滚/同代改写/隐式删除， COMMIT 响应丢失后收敛，提升后事实不变，总 gate 为 true。
• Kubernetes manager base/CloudNativePG 与一次性 client Kustomize 均成功渲染；Cluster/CloudNativePG 部署正负向审计 41/41，固定角色集合为 9 个。尚未取得真实 Kubernetes CNI、双 Pod 滚动轮换与 故障注入证据， 因此静态部署通过不能替代生产 release ceremony。
• ql3-automation-client 的真实本地 TLS 1.3+mTLS 产品链 3/3；一次性 Kubernetes Job Kustomize 渲染与生命周期、Secret、网络、digest/default-disable 负向门通过。它证明客户端/清单契约，不等价于 真实 Kubernetes CNI/双 Pod/CloudNativePG 运行证据。
• 真实 PostgreSQL 18 上启动两个独立 TLS 1.3+mTLS automation-manager，并由产品 client 并发提交 同一 Task：结果精确为 created + existing。第三实例在 Task v2 COMMIT 后模拟响应丢失，另一个实例 以相同请求重放收敛为 existing；随后 Trigger 固定 v2、Task 更新 v3、operator 显式 repin v3，最终 数据库精确为 Task 3 revisions、Trigger 2 revisions、5 条 allowed audit 且无 replay duplicate（1/1）。 该证据使用测试 identity adapter，不能替代生产 OIDC issuer/keyset ceremony。

后续约束

• UI/API gateway 必须调用同一 transport，不得复制 Policy、current-head、audit 或 replay 逻辑。
• 增加 inspect/list 时必须使用独立只读 repository 与 keyset pagination，不能顺带扩大 mutation authority。
• 单节点/大集群 overlay 必须显式提交资源、连接、限流与故障域证据；不得修改 HA base 迎合开发环境。
• 共享 identity ledger 的历史表名可在 3.0 alpha 后续 migration 中泛化，但不能用破坏性 rename 丢失审计历史。