qinglong/docs/adr/ADR-0129-cloudnativepg-operator-and-database-role-authority.md

ADR-0129：CloudNativePG Operator 与数据库角色权威

• 状态：Accepted（operator/operand digest lock、三实例 HA 清单、十二角色 DatabaseRole、独立 Database owner、runtime/migration 离散凭据、CA/主节点 endpoint 绑定、静态负向门及显式 opt-in 的四节点 Kind/CNPG live contract 已完成；成功的远端 live 记录、CA 轮换和备份恢复仍是 Release Gate）
• 日期：2026-07-24
• 关联 RFC：QL-RFC-0001 D-06、D-34、D-105、D-123、D-124、D-125、D-127
• 关联 ADR：ADR-0104、ADR-0105、ADR-0124、ADR-0125、ADR-0126、ADR-0127

背景

ADR-0125 已用 PostgreSQL 18.4 Docker fixture 证明物理流复制、 remote_apply、fence-before-promote、timeline 1→2、旧主 pg_rewind 只读重入，以及 scheduler、credential delivery、completion 和 cancellation 在不确定提交后的收敛。但测试专用 TCP endpoint 和 promotion guard 不是生产 operator，也没有定义 Kubernetes 中谁创建数据库、角色、证书与 primary service。

QingLong 不能在应用进程内复制数据库选主；同时也不能让 operator 通过 superuser 或应用启动钩子接管 QL3 schema GRANT。部署需要一条明确分界：

• operator 管理 PostgreSQL 实例、复制、promotion、证书、Service、Database 和 LOGIN role 生命周期；
• QingLong reviewed migration stream 管理 schema、table、capability 与对象权限；
• Secret manager 管理密码和 runtime pepper；
• runtime、admin、worker-ingress 只消费各自最小权限身份。

决策

1. Cluster Profile 默认使用 CloudNativePG 1.30.0

生产 Cluster Profile 选择 CloudNativePG，而不是在 QingLong 中实现选主，也不把 Crunchy PGO 或 Zalando operator 同时引入默认发行物。原因是当前需求可以直接映射 到其稳定 read-write Service、Lease promotion gate、实例隔离、声明式 DatabaseRole、operator CA 和 pg_rewind 恢复路径；只保留一个 operator 可避免 三套 CRD、Secret 命名和故障语义进入支持矩阵。

operator 只属于 cluster-control 部署档位。edge、standalone 和普通 worker 产物不得依赖 Kubernetes client、CRD 或 operator 包；本决策不增加 workspace package 和 npm importer。

供应链锁记录：

• CloudNativePG 1.30.0： ghcr.io/cloudnative-pg/cloudnative-pg:1.30.0@sha256:a2701eb97cdd2a34b1fdb2cb51987f544b706e40bec72ae7146cd8580efefebb；
• PostgreSQL 18.4-minimal-trixie： ghcr.io/cloudnative-pg/postgresql:18.4-minimal-trixie@sha256:24d229d801663f95b584416f8ebdfad4849b1a3fa4cfcf95a7f026df7aa6e22d；
• 两个 index 均锁定已观察的 linux/amd64 和 linux/arm64 子 manifest。

operator-lock.json 还记录 release manifest、Sigstore bundle 和 certificate identity。当前本地只核验了 OCI index/platform digest；尚未保存 release asset 下载、签名验证或真实 operator 安装记录，因此不能把 lock 文件解释为部署完成。

2. 生产数据库固定为三实例同步 HA

ql3-postgres Cluster 固定：

• instances: 3，required hostname anti-affinity；
• enableSuperuserAccess: false；
• synchronous_commit=remote_apply；
• synchronous ANY 1、dataDurability: required、failoverQuorum: true；
• 只保留 primary-tracking ql3-postgres-rw 默认 Service，禁用 -r、-ro；
• CPU、memory、data PVC 与 WAL PVC 都有显式请求/上限。

该配置优先保证已确认写入在一个同步副本 remote apply。代价是只剩一个可写实例且 没有合格同步副本时，mutation 可用性会停止；不得通过改成异步提交来“恢复健康”。 required anti-affinity 也意味着生产至少需要三个合格节点。单节点开发环境可以用 私有 overlay 放宽拓扑，但不能作为 HA 证据。

3. Operator 管理 LOGIN role，migration 管理对象 GRANT

operator 声明且只声明十二个非特权 LOGIN role：

Role	Connection limit	Password Secret	用途
ql3_migration	2	ql3-postgres-migration-auth	Database owner 与短生命周期 DDL
ql3_ai_maintenance	4	ql3-postgres-ai-maintenance-auth	Prompt output retention/rekey 维护
ql3_ai_credential_manager	4	ql3-postgres-ai-credential-manager-auth	AI Provider credential 管理事务
ql3_ai_credential_tester	2	ql3-postgres-ai-credential-tester-auth	一次性 Provider 连通性测试
ql3_runtime	32	ql3-postgres-runtime-auth	cluster-control runtime
ql3_admin	4	ql3-postgres-admin-auth	短生命周期管理事务
ql3_package_manager	4	ql3-postgres-package-manager-auth	Plugin Package 管理事务
ql3_package_executor	4	ql3-postgres-package-executor-auth	Package 执行/恢复事务
ql3_automation_manager	4	ql3-postgres-automation-manager-auth	Task/Trigger 管理事务
ql3_worker_credential_manager	4	ql3-postgres-worker-credential-manager-auth	Worker credential 管理事务
ql3_worker_credential_executor	4	ql3-postgres-worker-credential-executor-auth	Worker credential 执行事务
ql3_worker_ingress	32	ql3-postgres-worker-ingress-auth	Worker ingress

十二者均为 LOGIN，且显式禁止 SUPERUSER、CREATEDB、CREATEROLE、 REPLICATION 和 BYPASSRLS；删除 CR 时 role reclaim policy 为 retain，防止 operator 删除声明时同时破坏仍被数据库对象引用的身份。qinglong Database 的 owner 固定为 ql3_migration。

pg-0017-database-role-grants 将 PostgreSQL stream 推进到 17 条 migration、 control-core capability v16。它先复验四个 role 已存在且属性精确，再撤销 PUBLIC 对数据库/schema/table 的默认访问，并安装 runtime/admin/worker-ingress 所需的精确对象 GRANT。CI 和 HA fixture 只预创建 role 与 Database owner，不再 复制一份手工 GRANT。readiness 同时复验当前 role 可登录、无高权限且拥有 Database CONNECT，避免 operator 配置与 schema 权限静默漂移。

ADR-0137 的 pg-0018-plugin-package-installs 在上述 role-grant authority 上继续推进 到 18 条 migration、control-core capability v17、30 张表。Plugin Package installation 三表仍只授予 ql3_admin；单用途 Project lock function 固定由 ql3_migration 拥有、撤销 PUBLIC EXECUTE，并只给 admin 调用。runtime 与 worker-ingress 权限不因该能力扩大。

后续 ADR-0144、ADR-0242 与 ADR-0259 在同一 operator authority 中依次加入 Package manager/executor、Worker credential manager/executor、Automation manager 与三个 AI 专用身份；当前生产清单的唯一事实源是十二个非特权 LOGIN role、52 条 migration 与 control-core capability v51。新增 role 不改变本 ADR 的原则：operator 只管理 登录身份，所有对象 GRANT 仍由 reviewed migration stream 管理。

4. 应用不再复制含密码 DSN

CloudNativePG overlay 使用离散配置：

• HOST=ql3-postgres-rw.qinglong3-system.svc；
• PORT=5432、DATABASE=qinglong；
• USER/PASSWORD 分别读取对应 basic-auth Secret；
• QL3_POSTGRES_TLS_SERVERNAME 与 primary Service DNS 完全相同；
• CA 从 operator 管理的 ql3-postgres-ca 只读投影。

runtime 与 migration 的 Secret、环境键和 CA mount 保持分离。兼容用 URL 仍可供 非 operator 部署使用，但 URL 与离散配置混用、部分离散凭据、URL ssl* override 以及非法 identifier 全部失败关闭。credential example 只含固定 username 与 占位符，且不进入 Kustomize resources。

5. 安装和激活有固定顺序

部署顺序为：

1. 以 cluster-admin authority 安装并验证锁定的 CloudNativePG；
2. 创建 namespace 和由 Secret manager 生成的十二个 role Secret、control runtime Secret 与 Worker ingress Secret；
3. 应用 Cluster、DatabaseRole 和 Database；
4. 等待三个实例、-rw Service、十二个 role、Database 和 -ca Secret ready；
5. 创建固定名称的 one-shot migration Job，等待 migration_completed，随后删除或留给 TTL 清理；
6. 才应用 cluster-control runtime overlay。

应用 readiness 不能替代 operator readiness；operator ready 也不能替代 QL3 schema/role readiness。重新运行 migration Job 前必须确认旧 Job 已删除。

备份、TLS 与故障边界

CloudNativePG 自动维护 server/client certificate 不等于完成 CA rollover 证明。 QL3 仍要求 ADR-0127 的 old → overlap → new → rollback contract，每阶段创建新 activation 并重跑可写主库/schema/role/recovery gate。真实 operator endpoint 上的 轮换尚未执行。

ADR-0130 已定义 Barman CNPG-I、私有 ObjectStore、连续 WAL、每日 base backup 与隔离恢复 Cluster 的静态合同，并锁定 Barman v0.13.0 candidate release、 controller/sidecar 及双平台 digest；certificate authority 供应链和真实对象存储 restore evidence 仍未完成。三副本和可渲染清单都不能冒充备份。基础设施 STONITH、Kubernetes control-plane 故障、Pod/节点网络分区、存储故障和 raw PostgreSQL response loss 仍是独立 Release Gate。

替代方案

• QingLong 内建 Patroni/选主或轮询多个 host：拒绝。复制数据库控制面并扩大 split-brain 风险。
• 默认同时支持多个 PostgreSQL operator：拒绝。3.0 首发会把 CRD、Secret、 Service、证书和升级矩阵成倍放大；其他 operator 后续只能通过独立 ADR/overlay 加入。
• operator role 成为 superuser，由应用启动时自动 GRANT：拒绝。常驻进程会 获得 DDL/role authority，副本并发启动还会把 migration 变成隐式副作用。
• 在一个 Secret 中保存 runtime、migration、admin 和 worker-ingress DSN： 拒绝。会合并独立 authority，并在 URL 中复制用户名、密码、host 和 TLS 选择。
• 单实例 operator 清单作为生产默认值：拒绝。它只能证明 CRD 可启动，不能 支撑 D-123 的 failover/RPO 声明。
• 三副本等同于备份：拒绝。复制会同步删除和逻辑破坏，不能替代离线恢复点。

验证

• pnpm audit:cloudnativepg:ql3
• node --test test/back/ql3CloudNativePgDeploymentAudit.test.cjs
• kubectl kustomize deploy/kubernetes/ql3-cluster/operators/cloudnative-pg
• kubectl kustomize deploy/kubernetes/ql3-cluster/overlays/cloudnative-pg
• kubectl kustomize deploy/kubernetes/ql3-cluster/operations/cloudnative-pg
• pnpm --filter @qinglong/cluster-postgres test
• pnpm --filter @qinglong/cluster-control test
• pnpm test:postgres-ha:ql3
• QL3_CLOUDNATIVEPG_LIVE=1 pnpm test:cloudnativepg-live:ql3

静态负向门必须拒绝单实例、未锁 digest、特权 role、错误 Database owner、把 credential example 加入 Kustomize、runtime/migration Secret 串用、重新引入 DSN、 非 -rw endpoint 或错误 CA。live contract 必须保存 operator/operand 实际 platform imageID、三实例跨 worker 调度、migration/runtime ready、主 worker 停止后的 Lease/timeline promotion、旧主回归和最小权限 role 复验；脚本和 CI 定义本身不构成成功证据。发布前还必须保存一次成功记录，并独立完成 CA 轮换/回退和备份恢复证据。