# ADR-0127：有界 PostgreSQL 私有 CA 文件绑定

- 状态：Accepted
- 日期：2026-07-24
- 关联 RFC：QL-RFC-0001 D-06、D-34、D-105、D-123、D-124、D-125
- 关联 ADR：ADR-0042、ADR-0045、ADR-0125、ADR-0126

## 背景

ADR-0126 已提供独立 QL3 Cluster 镜像和 Kubernetes 双副本基线，但
PostgreSQL `verify-full` 只能使用 Node 系统 trust store。多数 Kubernetes
PostgreSQL operator 使用集群私有 CA；把 CA 烘焙进镜像会把证书轮换和应用发布
耦合，把任意文件路径直接交给 `pg` 又缺少大小、类型、权限和证书用途边界。

runtime、worker-ingress 和 migration 使用不同数据库角色与 Secret 域。即使它们
信任同一 operator CA，也不能因此合并 URL、pepper 或 DDL credential。

## 决策

### 1. 在既有 cluster-postgres runtime subpath 提供唯一 CA loader

不新增 package。`loadPostgresCertificateAuthorityFile()` 在打开文件后验证：

- 路径绝对、无控制字符且不超过 4096 字节；
- `fstat` 结果是普通文件；
- group/world write bit 均未设置；
- 文件为 1–256 KiB；
- 单次有界读取必须与打开时大小一致；
- 内容是严格 UTF-8，且除 PEM certificate block 外没有其他数据；
- 只允许 1–16 张唯一 X.509 certificate；
- 每张证书的 Basic Constraints 必须为 CA。

Kubernetes projected Secret 的外层路径可以是 symlink；loader 验证已打开 target
的真实文件，因此兼容 kubelet 原子 `..data` 切换，又不把目录或 socket 当信任
材料。

输出为规范化 PEM bundle，只存在于当前进程内并直接绑定到 `pg` 的
`ssl.ca`；文件路径、PEM 和证书 subject 不进入普通进程日志。

### 2. TLS disable 与 CA file 互斥

以下配置分别接入同一 loader：

- control runtime：`QL3_POSTGRES_TLS_CA_FILE`
- migration：`QL3_POSTGRES_TLS_CA_FILE`
- Worker ingress：`QL3_WORKER_INGRESS_POSTGRES_TLS_CA_FILE`

只有 `verify-full` 可以使用 CA file。即使设置了 insecure 双门，
`TLS_MODE=disable` 与 CA file 同时存在也必须拒绝，避免部署者误以为连接仍在
校验证书。

CA file 可省略以继续支持系统 trust store，但 QL3 Kubernetes Cluster base 固定
配置私有 CA 路径。

### 3. Runtime 与 migration 保持独立投影

runtime Deployment 只从 `ql3-cluster-control-runtime` Secret 投影
`postgres-ca.crt` 到：

`/var/run/secrets/qinglong3/postgres-runtime/ca.crt`

migration Job 只从 `ql3-cluster-migration` Secret 投影同名 key 到：

`/var/run/secrets/qinglong3/postgres-migration/ca.crt`

两个 volume 都是 read-only、mode 292（八进制 0444），并用 `items` 只投影 CA
key。control Pod 不取得 migration URL，migration Job 不取得 runtime URL 或 API
pepper。

### 4. Trust rotation 以新 activation 生效

CA 在 config 装载时读取一次。kubelet 更新 Secret 后，现有 Pool 不热切换信任
根；必须滚动创建新 Pod，新 activation 重新读取 bundle，再依次通过 TLS、
schema/role readiness、startup recovery 与 lifecycle gate。

这与 ADR-0125 的 one-way availability fence 一致：数据库失联后的旧 activation
不能因文件变化原地恢复 ready。

### 5. 显式 DNS 身份与 old → overlap → new 契约

production `verify-full` 配置必须显式提供 DNS servername；不得使用 IP literal、
省略后依赖 driver 隐式推断，或用 URL `ssl*` 参数覆盖。runtime、migration 与
worker-ingress 三条配置链在创建 Pool 前执行同一 DNS servername 约束。

`audit:postgres-ca-overlap:ql3` 复用上述有界 CA loader 读取 old、overlap 和 new
三个 bundle，并只输出低敏 anchor count 与集合 SHA-256。overlap 必须是 old/new
anchor 的精确并集，不得遗漏旧 anchor 或夹带第三方 anchor；新旧集合必须至少
引入和退役一张证书。部署固定按“扩信任并全量滚动 → operator 轮换 endpoint
certificate → 再滚动新连接 → 收缩信任并全量滚动”的顺序执行，回退则先恢复
overlap trust，再回退 server certificate。

具体命令、停止条件、回退顺序和证据字段冻结在
`deploy/kubernetes/ql3-cluster/operations/postgres-ca-rotation.md`。

## 不代表什么

本 ADR 证明 CA 文件到 `pg ssl.ca` 的本地和清单契约，不证明：

- 任一真实 PostgreSQL operator/proxy endpoint 的证书链和 SAN；
- 在真实 operator 上执行 CA 重叠轮换、旧 CA 移除和 rollback 演练；
- operator primary Service、promotion 或基础设施 STONITH；
- Pod 网络分区、raw PostgreSQL packet loss，或 ADR-0128 远端多架构 release
  workflow 的成功记录。

这些仍需使用实际 operator 与集群故障注入验证。

## 替代方案

- **把私有 CA 烘焙进镜像 trust store**：拒绝。轮换需要重建镜像，并扩大所有
  Node TLS consumer 的信任面。
- **URL `sslrootcert`/`sslmode` 参数**：拒绝。会绕过统一 TLS 配置和静态审计。
- **把整个 Secret volume 暴露给进程**：拒绝。只投影 CA key，避免无意暴露
  URL、pepper 或其他 authority。
- **监听文件并热更新 Pool**：拒绝。增加 watcher 和 trust 切换竞态，且不能为
  已建立连接重新完成 readiness/recovery。
- **runtime 与 migration 共用 Secret**：拒绝。信任根相同不等于数据库权限相同。

## 验证

- CA loader 正向覆盖 projected-Secret symlink；
- 负向覆盖相对/缺失/目录/可写/超限文件；
- 负向覆盖 trailing data、非 CA、重复和超过 16 张证书；
- runtime、migration、worker-ingress config 验证 exact `tls.ca`；
- 三条 `verify-full` 配置链拒绝缺失、IP literal 或非法 DNS servername；
- TLS disable + CA file 必须拒绝；
- old/overlap/new auditor 正向验证精确集合并集，负向拒绝遗漏、夹带、无退役和
  非规范 fingerprint；
- `qinglong/postgresql-tls-rotation@v1` 在本机 arm64 `postgres:18`
  （PostgreSQL 18.4）建立真实 TLS 1.3 会话：错误 SAN servername 以
  `ERR_TLS_CERT_ALTNAME_INVALID` 拒绝；old certificate 下 old-only/overlap
  通过，SIGHUP 切换 new certificate 后 old-only 以
  `UNABLE_TO_VERIFY_LEAF_SIGNATURE` 拒绝而 new-only/overlap 通过；回退 old
  certificate 后 new-only 被拒绝、old-only/overlap 恢复。每个成功连接同时
  证明 `pg_stat_ssl.ssl=true`、`pg_is_in_recovery()=false` 与
  `transaction_read_only=off`；
- x64/arm64 原生 PostgreSQL 18 physical-promotion CI job 在 promotion 门前执行
  独立 TLS rotation gate；
- 部署静态门拒绝错误路径、Secret、mount、mode 或投影 key；
- runtime base 通过离线 Kustomize 渲染，`generateName` migration Job 通过严格
  YAML/静态契约验证；
- 最小镜像在 UID 10001、只读根、drop ALL、no-new-privileges 下从正式 mount
  path 为 runtime/migration 读取同一 CA bundle；
- cluster-postgres、cluster-control 全量类型和测试门通过。