mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-23 03:18:09 +08:00
145 lines
7.5 KiB
Markdown
145 lines
7.5 KiB
Markdown
# ADR-0495：无敏感内容的 Cluster Legacy Env 迁移计划账本
|
||
|
||
- 状态：Accepted
|
||
- 日期：2026-08-24
|
||
- 决策：D-400
|
||
- 关联：ADR-0104、ADR-0233、ADR-0259、ADR-0491、ADR-0494
|
||
|
||
> 2026-08-24：ADR-0497/D-402 已完成本 ADR 所列的下一切片：在同一 Automation Manager
|
||
> SERIALIZABLE transaction 中复验并迁移 Task/Trigger，重置 schedule fence，并写入逐项
|
||
> content-free receipt。本 ADR 的 plan ledger 决策保持不变。
|
||
|
||
## 背景
|
||
|
||
ADR-0491 已完成 Local SQLite 上的 Legacy Env 检查、人工裁决、Secret application、
|
||
Task/Trigger revision mutation、回滚和 completion；ADR-0494 又证明了 Cluster
|
||
`mounted-files` provider 的在线轮换。Cluster 仍缺少一个独立于 Local SQLite/POSIX
|
||
authority 的持久计划边界，无法在真正写 Secret、Task 或 Trigger 之前冻结源证据、目标
|
||
revision 集合和幂等 mutation 身份。
|
||
|
||
该边界不能把 2.x `Envs` 的名称、值、行内容搬进 PostgreSQL，也不能为了“先跑起来”
|
||
让 runtime、admin 或通用 root export 取得迁移写权限。小型路由设备不应安装或加载本
|
||
Cluster 能力；集群侧也必须有明确的行数、Task、Trigger 和有效载荷预算。
|
||
|
||
## 决策
|
||
|
||
### 1. 账本只保存不可逆摘要、计数和目标引用
|
||
|
||
新增 profile-neutral `qinglong/cluster-legacy-env-migration-plan@v1`。计划只包含：
|
||
|
||
- plan、mutation、Project 身份；
|
||
- reconciliation bundle、reviewed decision、candidate set 三个 SHA-256 摘要；
|
||
- source/active/disabled/effective binding 计数；
|
||
- 同 Project、精确固定 version 的 canonical `SecretRef`；
|
||
- Task 与 Trigger revision set 摘要和计数；
|
||
- effective Secret 总字节数、数据库计划时间和 plan digest。
|
||
|
||
它不得包含源 Env 名称/值、row body、目标 plaintext/ciphertext、key ID、credential、
|
||
Task spec、Trigger spec 或迁移日志。`SecretRef` 是既有目标路由引用，不是源 Env 名称；
|
||
其 payload 仍受 canonical encoding、同 Project 和固定 version 校验。
|
||
|
||
硬上限为 100,000 个源行、100,000 个 Task、500,000 个 Trigger、64 KiB effective
|
||
Secret 和 8 KiB plan JSON。active/disabled/source 计数必须守恒，至少存在一个 active
|
||
行、effective binding 和 Task。
|
||
|
||
### 2. PostgreSQL 只提供 append-only v69 计划表
|
||
|
||
`pg-0070-cluster-legacy-env-migration-plans` 将 control contract 推进到 v69，并新增
|
||
`cluster_legacy_env_migration_plans`：
|
||
|
||
- `plan_id` 为主键，`mutation_id` 与 `plan_digest` 各自唯一；
|
||
- Project 外键使用 `ON DELETE/UPDATE RESTRICT`；
|
||
- identity、digest、source、target、time、JSON 六组 named constraints；
|
||
- `plan_json` 必须与列值构造出的完整 canonical JSONB **精确相等**，不是包含关系，
|
||
因而任何额外 Env 字段也会被数据库拒绝；
|
||
- 不提供 UPDATE、DELETE、TRUNCATE 或后台 GC。
|
||
|
||
迁移能力值新增 `cluster_legacy_env_migration_plan: 1`。Drizzle schema、readiness
|
||
contract、固定 migration checksum 和实际 SQL stream 必须保持同锁步。
|
||
|
||
### 3. 只有 Automation Manager 可以读取和追加
|
||
|
||
新表从 PUBLIC 撤销全部权限，只向 `ql3_automation_manager` 授予 `SELECT, INSERT`。
|
||
runtime、admin、Worker ingress、Approval/Run/Package/Worker Credential 等其他角色均为
|
||
零权限；migration owner 只用于 schema 管理与集成验证。
|
||
|
||
具体 repository 只由
|
||
`@qinglong/cluster-postgres/cluster-legacy-env-migration-plan` 显式子路径发布，不进入
|
||
package root、runtime 或 admin entrypoint。runtime-core 也只通过
|
||
`@qinglong/runtime-core/cluster-legacy-env-migration-plan` 发布数据契约。
|
||
|
||
### 4. 发布使用数据库时间、SERIALIZABLE 和精确重放
|
||
|
||
repository 每次使用一个短 `SERIALIZABLE` transaction，设置 statement、lock 和 idle
|
||
transaction timeout；先按 `mutation_id` 查 exact replay，再验证 Project 在该可序列化
|
||
快照中为 active，使用 `transaction_timestamp()` 生成 `plannedAtMs`，最后追加计划。
|
||
|
||
相同 mutation 与相同 intent 返回 durable `existing`；mutation drift、plan identity
|
||
占用、inactive Project 和 named constraint 冲突失败关闭。`40001`、`40P01`、`55P03`
|
||
最多重试三次。可选 transaction hook 只用于后续在**同一 Automation Manager 事务**中
|
||
追加 Task/Trigger revision mutation；本 ADR 不调用它来声称那些 mutation 已实现。
|
||
|
||
Project 检查使用普通 SERIALIZABLE read，而不是 `FOR SHARE`。后者在 PostgreSQL 中还
|
||
要求 UPDATE privilege，会错误扩大 Automation Manager 权限；可序列化顺序与外键已足以
|
||
表达“计划发生在并发归档之前”的合法历史。
|
||
|
||
### 5. 不扩大 Edge/Standalone 闭包
|
||
|
||
实现复用既有 `runtime-core` 与 `cluster-postgres` package，不新增 workspace package、
|
||
生产依赖、daemon、timer、watcher、controller 或缓存全集。Edge/Standalone 不导入
|
||
PostgreSQL repository 或 migration；计数上限是 Cluster 计划输入预算，不是把集群表或
|
||
Task 集合加载进小型设备。
|
||
|
||
## 被拒绝的替代方案
|
||
|
||
### 在 PostgreSQL 保存 Env 名称、值、密文或 key ID
|
||
|
||
拒绝。密文仍会扩大 custody、rotation、backup 和 HA 泄漏面；计划账本只需要摘要和目标
|
||
引用即可证明后续 mutation 的输入身份。
|
||
|
||
### 在同一切片直接改写全部 Task/Trigger head
|
||
|
||
拒绝。计划发布和实际 DML 是两个可独立审计的 authority 阶段。没有 current-head
|
||
revalidation、逐项 mutation receipt 与完整 response-loss 测试前，不得把 plan 冒充迁移。
|
||
|
||
### 复用 Local SQLite 或 Plugin Package Secret Binding 表
|
||
|
||
拒绝。Local authority 不属于 Cluster；Plugin Package binding 的 installation/generation
|
||
身份也不能表达 Legacy Env reconciliation bundle、disabled preservation 和 Task/Trigger
|
||
revision set。
|
||
|
||
### 为一个 contract 和一个 repository 新建 package
|
||
|
||
拒绝。它们分别属于既有 runtime migration contract 与 Cluster reconciliation storage
|
||
能力，新增微包会再次制造用户已经指出的单文件 package 问题。
|
||
|
||
## 当前验证
|
||
|
||
2026-08-24 已完成：
|
||
|
||
- runtime contract 定向测试 4/4；
|
||
- PostgreSQL repository 定向测试 5/5；
|
||
- `@qinglong/runtime-core` 与 `@qinglong/cluster-postgres` 完整 package 测试零失败；
|
||
- PostgreSQL migration/schema/readiness/entrypoint 定向门 92/92；
|
||
- 真实 PostgreSQL 18.4 应用 70 条 migration 成功；
|
||
- 实际 automation-manager create/replay/read 成功，UPDATE 被 `42501` 拒绝；
|
||
- 实际 runtime/admin SELECT 被 `42501` 拒绝；
|
||
- 带源 `envName` 的 widened JSON 被
|
||
`ql3_cluster_legacy_env_plan_json_check` 以 `23514` 拒绝。
|
||
|
||
## 边界与后续门禁
|
||
|
||
本 ADR 关闭 ADR-0491 的 **Cluster plan ledger baseline**，但不把 ADR-0491 整体转为
|
||
Accepted，也不声明：
|
||
|
||
1. Legacy source scan、sealed bundle 或 signed decision 已在 Cluster 中生产装配；
|
||
2. Task/Trigger current head 已逐项复验或 revision mutation 已提交；
|
||
3. Secret material 已写入 Kubernetes/Vault/KMS/HSM；
|
||
4. migration Job、短期身份、receipt 与 promotion 后 exact replay 已完成；
|
||
5. PostgreSQL physical failover、CloudNativePG promotion 或多架构结果已由本切片重新证明；
|
||
6. 固定低性能路由设备的空间、写放大、断电和恢复证据已完成。
|
||
|
||
下一切片应在 Automation Manager 同一事务内绑定 current Task/Trigger revision set、逐项
|
||
mutation 与 receipt，同时保持计划表 append-only；随后再接入外部 custody 和 HA promotion
|
||
后的 exact replay。任何一步都不能回写源 Env 明文或放宽其他数据库角色。
|