open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2026-09-20 16:07:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
1d83d1d6bbd1c3f5edf599a2a7d6454511eadbe5
qinglong/docs/adr/ADR-0130-cloudnativepg-barman-backup-and-isolated-restore.md
T

13 KiB
Raw Blame History

ADR-0130：CloudNativePG Barman 备份与隔离恢复

  • 状态：Proposed（CNPG-I 配置、私有 ObjectStore 边界、定时备份、隔离恢复清单、 6 项配置 mutation gate，以及 Barman v0.13.0 release/controller/sidecar 的 exact candidate lock 与 6 项供应链 mutation gate，以及 ADR-0131 的 cert-manager v1.20.3/Kubernetes 1.32.8 兼容选择、Release manifest/OCI 双平台供应链锁和 mutation gate 已完成； 9 项非密钥灾备 evidence mutation gate 已固定 latest/PITR/rotation/RTO/RPO 完成条件；真实对象存储与证书轮换演练仍是 Release Gate）
  • 日期：2026-08-03
  • 关联 RFC：QL-RFC-0001 D-06、D-123、D-127、D-128
  • 关联 ADR：ADR-0125、ADR-0127、ADR-0128、ADR-0129、ADR-0131

2026-08-10 当前增量：直接执行 ql3-cloudnativepg-barman-live-contract 也必须在任何临时目录、 Docker network/container 或 K3s 状态创建前，以 statfs 证明临时数据所在文件系统至少有 35 GiB 可用空间；不再只依赖 GitHub workflow 的外层 shell 检查。当前开发机只有 10,918,137,856 bytes 可用，真实调用已证明立即失败且前后 ql3-barman-dr-* 临时目录、容器与网络 都为零；因此没有把容量不足伪装为 live restore 通过。相关 DR 静态/报告门 44/44、backup/Barman/ cert-manager 审计 compatible；独立 PostgreSQL 18.4 arm64 HA contract 同轮 gates.passed=true 且 容器、命名卷和网络零残留。D-128 仍必须在不少于 35 GiB 的候选 runner 上取得 current-source continuous WAL、latest restore、PITR、证书轮换和 RPO/RTO 私有报告后才能 Accepted。

背景

CloudNativePG 三实例同步复制只保护节点故障时的已确认写入，不保护误删除、错误 migration、凭据破坏、整个集群或存储故障。ADR-0129 已明确“三副本不代表备份”， 但若只提交一个对象存储 YAML，又会留下多套 WAL authority、把恢复凭据变成写入 凭据、原地覆盖源集群或将清单存在误报为恢复证据等风险。

CloudNativePG 的 Barman Cloud 已把对象存储能力迁移到 CNPG-I plugin。QL3 不再 引入 deprecated in-tree spec.backup.barmanObjectStore，也不在应用包内增加 Kubernetes、Barman 或对象存储依赖。

决策

1. 备份能力只属于 Cluster 部署层

components/barman-cloud-backup 是显式启用的 Kustomize Component：

  • 为 ql3-postgres 安装且只安装一个 barman-cloud.cloudnative-pg.io plugin；
  • 该 plugin 是唯一 WAL archiver，绑定 ql3-postgres-backup ObjectStore；
  • ScheduledBackup/ql3-postgres-daily 使用六字段 cron 0 0 0 * * *、method: plugin、target: prefer-standby 和 backupOwnerReference: self；
  • 禁止同时出现 in-tree backup 或第二个 WAL archiver。

该能力不增加 workspace package、npm importer、edge/standalone/worker 闭包、 QL3 timer 或数据库 connection。Barman plugin 与其证书依赖由 cluster-admin 安装，不能由 cluster-control Pod 自助安装。

2. ObjectStore 是部署私有输入

共享 Component 不包含 ObjectStore 和 Secret，只提交带占位符的 schema example。 私有 overlay 必须：

  • 使用支持 versioning 的专用 bucket/prefix，并在 provider 层启用 object lock 或 等价不可变保护及受审 lifecycle；
  • 只使用 HTTPS endpoint；
  • 从独立 Secret 引用 access key，不在 ObjectStore、Kustomization、日志或 RFC 中保存密钥；
  • 对 WAL 和 base backup 使用 LZ4 与服务端 AES256，WAL 上传并发固定为 2；
  • 将 Barman retention 固定为 30 天；provider lifecycle 不得早于该窗口删除仍被 catalog 引用的对象；
  • 每个源 Cluster 使用独立 ObjectStore 和 server prefix，不能让两个写入集群共享 同一 serverName。

Secret manager、对象存储 IAM、bucket versioning/object lock 和跨故障域复制仍是 部署 authority；Kubernetes Secret 或 CRD 的存在不能证明这些策略已生效。

3. 恢复永远创建新 Cluster

operations/cloudnative-pg-restore 创建独立 Cluster/ql3-postgres-restore，保留 ADR-0129 的三实例同步 HA、digest-pinned PostgreSQL 和非 superuser 边界。它通过 external cluster ql3-postgres-origin 与 recovery-only ObjectStore ql3-postgres-recovery-source 读取源 serverName: ql3-postgres。

恢复约束：

  • 恢复 ObjectStore 使用独立、尽可能 read/list-only 的凭据；
  • 恢复 Cluster 不配置 WAL archiver，避免把新 WAL 写回恢复源；
  • 不设置 cnpg.io/skipEmptyWalArchiveCheck；
  • 不修改、缩容、暂停或覆盖源 Cluster；
  • 只有另行创建全新 destination ObjectStore、完成 WAL archive 健康检查和切换 审批后，恢复 Cluster 才能成为新的生产写入源；
  • 原地 restore、复用源写凭据或在 source bucket 上以相同 server name 开启归档 一律拒绝。

4. 恢复演练以证据报告为完成条件

每次发布候选至少执行一次 latest restore，并按发布策略定期执行 PITR：

  1. 记录 operator、PostgreSQL、Barman plugin/sidecar 的实际 platform imageID、 CRD version、对象存储策略摘要和非密钥 IAM identity；
  2. 在源库写入唯一 before_backup marker，强制 WAL switch，并等待归档健康；
  3. 创建显式 Backup，等待其 Completed，记录 backup name、begin/end WAL、 server name 和完成时间；
  4. 写入唯一 after_backup marker，再强制 WAL switch并等待后续 WAL 可恢复；
  5. 以独立恢复凭据创建 ql3-postgres-restore，不得改动源集群；
  6. latest restore 必须同时看到两个 marker；PITR 到二者之间时必须只看到 before_backup；
  7. 复验 52 条 core migration、control-core capability v51、当前完整 schema、 受审 function、十二个非特权 role、 database owner、schema GRANT、remote_apply、三实例 ready 和应用 readiness；
  8. 记录从创建恢复 Cluster 到数据库 ready、schema ready、应用 ready 的分段 RTO， 以及最后可恢复 WAL 与故障时刻之间的 RPO；
  9. 保存非密钥 JSON 报告、operator event 和 Backup/Cluster condition；失败时保留 恢复环境供取证，不自动删除源对象。

清单可渲染、Backup 为 Completed 或 Pod 为 Ready 都不能单独替代上述报告。没有 marker、schema/role 和 RTO/RPO 证据时，不得宣称恢复成功。

ql3-cloudnativepg-dr-evidence-audit.cjs 把该报告固定为 exact-shape、最大 1 MiB、 不可 group/world writable 的非密钥 JSON。它拒绝密码、token、access key、私钥和 含密码 DSN，并交叉验证：

  • actual CNPG/PostgreSQL/Barman/cert-manager imageID；
  • 两个有序 marker、backup begin/end WAL、无 gap 连续归档；
  • latest 同时包含两个 marker，PITR 只包含第一个且 target time 位于二者之间；
  • 52 条 core migration、capability v51、当前完整 schema、受审 function、十二个 非特权 role、 数据库 owner 与同步 HA；
  • writer/read-only recovery identity 分离、versioning/immutability/30 天 lifecycle；
  • client/server serial 与 Secret resourceVersion 推进，轮换后仍完成 WAL、backup、 latest restore 和 PITR；
  • 每个部署显式给出 RPO、database RTO、application RTO 目标，observed 值不得超标。

5. Plugin 安装供应链独立锁定

operators/barman-cloud/plugin-lock.json 已把 Barman Cloud plugin 0.13.0 绑定到：

  • release manifest SHA-256 d2e71e7b06822448f1a421f05781846cfdb9cc621e7ef32eef5e20c5133213b0；
  • controller index sha256:71589dbac582333442812b07b31f7ea4d00324a8358aac7ca507dabf9f4b6c96；
  • sidecar index sha256:990361af3319f9e23aafa0f6d7981f99bf1f69b4e6a85cf1bc7d71d6f09bb288；
  • 两个 image 的 linux/amd64、linux/arm64 platform manifest；
  • CloudNativePG >=1.26.0 compatibility 与本项目受审的 1.30.0 baseline。

该 lock 明确 releaseReady: false，且共享目录不得出现安装 manifest。ADR-0131 已锁定兼容 Kubernetes 1.32.8 的 cert-manager v1.20.3 Release manifest SHA-256、 controller/cainjector/webhook OCI index 与 amd64/arm64 子 manifest，并固定 Barman client/server Certificate 身份与轮换窗口。tag-only installer 只能在下载摘要匹配后 按锁改写使用；供应链锁完成仍不等于 cert-manager API、mTLS 轮换或灾备演练完成。

替代方案

  • 继续使用 in-tree barmanObjectStore：拒绝。它复制新旧配置模型，并阻塞 CNPG-I 迁移。
  • 把 ObjectStore example 直接加入公共 Kustomization：拒绝。占位符可能被 误应用，也会迫使所有部署共享 endpoint、Secret 名称和保留策略。
  • 恢复覆盖现有 Cluster/PVC：拒绝。会同时破坏故障源、回滚点和取证证据。
  • 恢复 Cluster 直接向源 ObjectStore 归档：拒绝。相同 server name 可覆盖或 混淆恢复源 WAL。
  • 三副本或成功 Backup condition 视为灾备完成：拒绝。前者同步逻辑破坏， 后者没有证明对象可读、WAL 连续、schema 可用或 RTO/RPO。

影响

  • Cluster 部署增加 Barman plugin、证书和对象存储运维面，但不增加 QL3 应用常驻 资源，也不影响路由器 Profile。
  • 每日 base backup、连续 WAL、30 天保留和 provider 不可变策略会产生可预期的 存储与请求费用。
  • 恢复需要独立三节点容量和独立凭据；这是隔离证据的成本，不能通过原地恢复省略。
  • 真实 cert-manager API/mTLS 轮换与灾备演练完成前，ADR 保持 Proposed。

验证

  • QL3_CLOUDNATIVEPG_BARMAN_LIVE=1 pnpm test:cloudnativepg-barman-live:ql3 -- --report=/absolute/private-dr-report.json 是一体化、显式 opt-in 的本地孵化门：它创建隔离的四节点 K3s、TLS MinIO、 writer/read-only recovery ObjectStore、三实例 source/latest/PITR Cluster，使用正式 cluster-control runtime 镜像运行 migration 与恢复后的 /readyz，并在 base backup 前固化 52 条 migration、capability v51、十二 DatabaseRole 和 ql3_migration database owner。成功时 stdout 直接输出可由下述 DR evidence audit 消费的 qinglong/cloudnativepg-disaster-recovery@v1 exact report；静态测试或 runner 源码存在不能替代该 live 成功记录。报告必须包含本次 workflow checkout 的 40–64 hex sourceRevision，不能把另一 commit 的演练结果重命名后用于发布。 --report 只接受绝对路径，在 Docker mutation 前拒绝已有目标，成功后以同目录临时文件、fsync、原子 no-replace link 和 0600 权限发布，避免半写或覆盖历史演练证据。
  • .github/workflows/ql3-cloudnativepg-dr-live.yml 只允许手动触发，并在至少 35 GiB 临时磁盘、checksum-locked operator manifest 和固定工具链上执行同一 runner。它在 live 前后精确比较 dangling Docker volume 集合，验证隔离 container/network 零残留， 禁止任何 prune；报告再次通过 evidence audit 后才作为保留 14 天的私有 artifact 上传。
  • .github/workflows/ql3-image-release.yml 的 cluster-dr-release-evidence Job 在 ql3-production-release-evidence 环境的 ephemeral private runner 上读取固定 /run/qinglong3-release-evidence/<source-commit>/cloudnativepg-dr-evidence.json。 它重新执行 backup、Barman、cert-manager 三项静态锁审计，再要求 live report 与发布 commit 精确一致、年龄不超过 24 小时、未来偏差不超过 5 分钟。所有 image publisher 同时依赖该 Job、Worker management private evidence 与 OS vulnerability Job；失败时 publisher 不获得 registry/OIDC 写权限。静态 selection lock 仍保持 releaseReady:false，因为只有每次发布的外部 live report 才能解除本次发布 blocker。
  • runner 必须把 Registry 的 /var/lib/registry 以及每个 K3s 节点的 /var/lib/cni、 /var/lib/kubelet、/var/lib/rancher/k3s、/var/log 全部 bind mount 到本次演练的 0700 私有临时树，使镜像 VOLUME 不再隐式创建匿名卷；退出时仍以 docker rm -f -v 作为兜底。每个 container/network 必须同时带固定 scope label 和 随机 run label，使零残留检查及异常退出后的精确归因不依赖模糊名称匹配。历史卷的 归因与删除属于独立运维动作，不能由 live gate 自动扩大清理范围。
  • pnpm audit:cloudnativepg-backup:ql3
  • pnpm audit:barman-cloud-supply-chain:ql3
  • pnpm audit:cert-manager-selection:ql3
  • node --test test/back/ql3CloudNativePgBackupAudit.test.cjs
  • node --test test/back/ql3BarmanCloudSupplyChainAudit.test.cjs
  • node --test test/back/ql3CloudNativePgDrEvidenceAudit.test.cjs
  • pnpm audit:cloudnativepg-dr-evidence:ql3 -- --report=/absolute/private-report.json
  • pnpm gate:cloudnativepg-dr-release:ql3 -- --report=/run/qinglong3-release-evidence/$GITHUB_SHA/cloudnativepg-dr-evidence.json --source-commit=$GITHUB_SHA --release-version=3.0.0
  • kubectl kustomize deploy/kubernetes/ql3-cluster/operations/cloudnative-pg-restore
  • 用部署私有 ObjectStore 渲染 components/barman-cloud-backup，确认 shared Component 未包含 Secret/example
  • 真实 Backup/WAL/latest restore/PITR 演练及非密钥 RTO/RPO 报告
Reference in New Issue View Git Blame Copy Permalink