CloudNativePG 副本集群搭建指南:跨集群复制、延迟回放与提升(Promotion)机制详解

原创2026-11-12 11:38:151,720 阅读

CloudNativePG 副本集群搭建指南:跨集群复制、延迟回放与提升(Promotion)机制详解

在 Kubernetes 上运行 PostgreSQL,CloudNativePG(简称 CNPG)副本集群是读写分离与异地容灾的核心能力。本指南基于 CNPG 官方 Helm charts 仓库中的 cluster chart,手把手讲清楚如何搭建 CloudNativePG 副本集群,并深入解析三大机制:跨集群复制(Streaming Replication)、延迟回放(minApplyDelay)与副本提升(Promotion),帮你快速完成跨集群复制搭建并掌握生产环境的容灾策略。

一、为什么需要 CloudNativePG 副本集群?🚀

副本(Replica)集群是一个完整的新 CNPG 集群,它通过流复制持续同步源集群(Source / Primary)的数据。典型用途包括:

  • 📖 读扩展:把报表、BI 等只读流量分流到副本集群,降低主库压力
  • 🌍 异地容灾:将副本部署在另一个可用区甚至另一个 Kubernetes 集群,主集群故障时可接管
  • 🛡️ 变更隔离:在副本上提前验证升级、扩容等变更操作
  • ⏳ 延迟回放:故意让副本"慢几秒",为主库误操作(如误删表)争取回滚窗口

cluster chart 通过一个 mode 参数决定集群的运行方式,这是理解整个配置体系的第一把钥匙:

mode 说明 典型场景
standalone(默认) 创建全新的独立集群 生产主库
replica 从已有 CNPG 集群创建副本集群 跨集群复制、容灾
recovery 从备份或流复制恢复出新集群 灾备恢复、迁移

💡 该 chart 定位为"约定优于配置"(opinionated),只提供一小部分稳定、安全的配置组合。需要复杂拓扑时,建议直接使用 operator 的 Cluster 清单管理。详见 charts/cluster/README.md 与 charts/cluster/docs/Getting Started.md。

二、前置条件:先有一个健康的源集群

搭建副本集群前,源集群(primary)需要满足两点:

  1. 开启备份(推荐):副本若走 object_store 引导方式,源集群必须把数据归档到对象存储(S3/Azure/GCS);
  2. 网络可达:副本 Pod 能通过 TCP 访问源集群的 <source-cluster>-rw 读写 Service(如跨集群部署,需要打通网络与 TLS 证书)。

仓库内置了完整的测试用例,源集群配置可参考 charts/cluster/test/replica/01-source_cluster.yaml:

type: postgresql
mode: standalone

cluster:
  instances: 2
  storage:
    size: 256Mi

backups:
  enabled: true
  provider: s3
  endpointURL: "https://object-store-svc.object-store.svc.cluster.local:9000"
  s3:
    bucket: "mybucket"
    path: "/replica/v1"

Operator 安装只需一条命令(官方 chart 仓库):

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg --namespace cnpg-system \
  --create-namespace cnpg/cloudnative-pg

三、三种引导方式,任选其一

副本集群的"第一桶数据"从哪来,由 replica.bootstrap.source 决定,官方支持三种方式。模板逻辑见 charts/cluster/templates/_bootstrap.tpl:

引导方式 参数值 数据路径 特点
流复制 pg_basebackup 直接连接源库做 pg_basebackup 最快、最简单,适合同源集群
对象存储 object_store 从 Barman Object Store 拉取基备 + WAL 源集群不在线也能引导,冷备能力强
混合 两者都配置 先用对象存储引导,再用流复制追平 兼顾速度与可用性

chart 会为副本自动生成名为 originCluster 的 externalCluster(外部集群连接),把源库信息注入到 bootstrap 和 replica 段中,渲染逻辑见 charts/cluster/templates/_external_clusters.tpl。

方式一:pg_basebackup 流复制(最常用)✅

参考测试用例 charts/cluster/test/replica/04-replica_cluster.yaml:

type: postgresql
mode: replica

cluster:
  instances: 2
  storage:
    size: 256Mi

replica:
  bootstrap:
    source: pg_basebackup
  origin:
    pg_basebackup:
      host: "source-cluster-rw"          # 源集群 rw Service
      username: "streaming_replica"       # 源库中的流复制账号
      sslMode: "require"
      sslKeySecret:
        name: source-cluster-replication
        key: tls.key
      sslCertSecret:
        name: source-cluster-replication
        key: tls.crt

关键点:

  • replica.bootstrap.source: pg_basebackup 指定引导方式;
  • origin.pg_basebackup.host 指向源集群的读写端点(默认 <集群名>-rw);
  • 用户名建议使用专用的 streaming_replica 复制账号,密码与 TLS 证书统一存放在 Secret 中,通过 passwordSecret / sslCertSecret 等引用;
  • 完成后副本即成为源集群的"跨集群热备",其 Cluster 资源中 replica.enabled: true、source: originCluster,可对照断言文件 charts/cluster/test/replica/04-replica_cluster-assert.yaml。

方式二:object_store 对象存储引导 🧊

适用于副本部署在不同 Kubernetes 集群、无法直连源库的场景:源集群先把基备与 WAL 归档到对象存储,副本再从对象存储恢复成流复制从库。

参考 charts/cluster/test/replica/06-replica_object_store_cluster.yaml:

mode: replica

replica:
  name: "off-site-backup1"        # 副本集群自身名称(用于主从识别)
  bootstrap:
    source: object_store
  origin:
    objectStore:
      clusterName: source-cluster  # 源集群名(即 barman 的 serverName)
      provider: s3
      endpointURL: "https://object-store-svc.object-store.svc.cluster.local:9000"
      s3:
        bucket: "mybucket"
        path: "/replica/v1"        # 需与源集群 backups.path 一致
        region: "us-east-1"
        accessKey: "objectstore"
        secretKey: "objectstore123"

注意事项:

  • origin.objectStore.clusterName 必须与源集群名一致,它决定了 Barman 的 serverName;
  • 对象存储的 bucket、path、凭据要与源集群 backups 配置完全对应(参考 charts/cluster/test/replica/01-source_cluster.yaml 中的 S3 配置);
  • replica.self / replica.name 用于告诉 operator"我是谁",配合 replica.primary 判断当前集群是主还是副本。

方式三:混合模式(Hybrid)⚡

同时配置 objectStore 和 pg_basebackup 两个 origin,chart 会先走对象存储完成冷引导,再自动切换到流复制实时追平——既容忍源集群短暂不可达,又能尽快进入实时复制状态。

完整示例见 charts/cluster/test/replica/08-replica_hybrid_cluster.yaml,它在前述两段配置的基础上同时给出了对象存储与 pg_basebackup 连接信息。

四、延迟回放:minApplyDelay 参数详解 ⏱️

minApplyDelay 是副本集群一个非常实用的小参数(定义见 charts/cluster/values.yaml 的 replica.minApplyDelay 段):

设置后,副本只在系统时间晚于事务提交时间该时长之后才应用该事务。

它解决了什么真实问题?

  • 有人在主库误执行了 DROP TABLE 或错误 UPDATE,需要几分钟才能发现并回滚;
  • 如果副本是实时的,错误数据会立刻被复制过去,之后在主库回滚时,副本反而"多"了脏数据,造成数据不一致。

配置示例:

replica:
  minApplyDelay: "10 minutes"   # 副本故意落后 10 分钟应用事务

这样主库有 10 分钟的"反悔窗口":在副本追上之前完成修复与回滚,副本最终状态就是干净的。

⚠️ 重要限制:官方明确说明,设置 minApplyDelay 后不能同时使用 promotion token(replica.promotionToken),二者互斥。也就是说:要"慢放"就不要配自动提升条件,要"可提升"就不要配延迟回放。

模板中该参数直接透传给 replica.minApplyDelay,参见 _bootstrap.tpl 第 144-146 行。

五、提升(Promotion)机制:副本如何安全变成主库 👑

当源集群彻底损坏(如存储故障、误操作清空数据)时,需要把副本**提升(promote)为新的主集群。CNPG 的分布式拓扑支持降级令牌(demotion token)**机制来避免"双主"冲突:

核心参数都在 replica 段(详见 charts/cluster/values.yaml):

参数 作用
replica.self 声明"本集群"名称
replica.primary 声明拓扑中的主集群名称;operator 比较两者判断本集群是主还是副本
replica.promotionToken 提升令牌:由外部集群生成的 demotion token,用于校验"提升条件是否满足",满足后副本才允许提升

工作流程可以这样理解:

  1. 正常状态:源集群(primary)健康,副本集群持续流复制,self ≠ primary,自身保持只读副本角色;
  2. 源集群故障:运维在副本上设置/验证 promotionToken,operator 检查提升条件(令牌匹配、复制状态等);
  3. 满足条件后:副本执行 promote,脱离流复制,对外提供读写;
  4. 重建原集群:原位置重建后,应以该副本为新的 primary 重新建立复制方向。

📌 令牌机制的本质是分布式共识:多个外部集群互相持有"降级凭证",避免在脑裂场景下两个集群都认为自己该当主,从而防止数据分叉。

六、复制延迟监控:别让副本"悄悄掉队" 📈

副本集群的价值取决于数据新鲜度,因此监控物理复制延迟必不可少。chart 在开启 cluster.monitoring 后会自动生成 PrometheusRule 告警规则,其中与副本最相关的是 CNPGClusterPhysicalReplicationLag:

  • ⚠️ Warning:复制延迟超过 1 秒
  • 🚨 Critical:复制延迟超过 15 秒

告警规则定义见 charts/cluster/prometheus_rules/cluster-physical_replication_lag-warning.yaml 与 charts/cluster/prometheus_rules/cluster-physical_replication_lag-critical.yaml。

仓库内置了完整的处置 runbook charts/cluster/docs/runbooks/CNPGClusterPhysicalReplicationLag.md,其处置思路值得记住:

  1. 查状态:在主库执行 SELECT * FROM pg_stat_replication; 确认副本是否在线、延迟多大;
  2. 查资源:网络带宽、CPU/内存、磁盘 I/O 是最常见瓶颈(跨集群复制对网络尤其敏感);
  3. 查配置:开启 wal_compression: "on" 可显著降低跨网络复制的带宽占用,且无需重启;实例数较多时调大 max_wal_senders;
  4. 查查询:长时间运行的会话会阻碍 WAL 回收并放大延迟,必要时 pg_terminate_backend 清理。

🎯 跨集群(尤其跨 Region)场景下,建议把 Warning 阈值理解为"常态抖动容忍度",重点关注 Critical 告警与持续上涨的趋势,而非单点数值。

七、快速搭建清单:5 步完成副本集群 📋

步骤 操作 关键参数
1️⃣ 安装 Operator helm upgrade --install cnpg cnpg/cloudnative-pg 命名空间 cnpg-system
2️⃣ 准备源集群 以 standalone 模式部署并开启 backups backups.enabled: true
3️⃣ 选择引导方式 直连选 pg_basebackup;异地选 object_store 或混合 replica.bootstrap.source
4️⃣ 配置连接信息 主机、用户、TLS 证书 / 对象存储凭据 replica.origin.*
5️⃣ 部署并验证 helm install replica-cluster cnpg/cluster -f values.yaml 检查 status.readyInstances

验证技巧:部署后执行 kubectl get cluster -n <ns> -w,副本就绪后 readyInstances 应等于 instances;再登录副本执行只读查询,确认数据与主库一致(SELECT txid_current(); 对比事务号可快速判断复制位点)。

八、常见问题 FAQ ❓

Q1:副本集群可以写数据吗? 可以,但一般不建议。副本具备完整 PostgreSQL 能力,生产环境应通过应用层或 PgBouncer(chart 支持 poolers 配置 ro 类型的只读池)把写流量锁定在主集群。

Q2:跨 Kubernetes 集群部署副本需要哪些网络打通? 两种:副本直连源库的 rw Service(pg_basebackup / 流复制),以及副本访问对象存储端点(object_store 引导与 WAL 归档)。跨集群时注意 TLS 证书分发自带的 sslCertSecret 机制即可复用。

Q3:副本能反向复制回主集群吗? 不能。云原生 PG 的副本是单向流复制(或经对象存储的"恢复 + 复制"组合),复制方向由源集群拓扑决定,提升后原主应作为新副本重建。

Q4:minApplyDelay 和 promotionToken 为什么不能同时用? 延迟回放意味着副本随时可能"不够新",此时自动判断提升条件会不可靠;CNPG 因此强制二选一,确保提升决策建立在可信的数据状态上。

总结

通过 cluster chart 的 replica 模式,你只需要几段 YAML 就能获得一个完整的 CloudNativePG 跨集群复制副本:pg_basebackup 引导适合同集群快速搭建,object_store 引导适合跨集群冷备,混合模式两者兼得;minApplyDelay 为主库误操作争取回滚窗口;promotionToken 机制则保证了副本在提升为主库时不会发生"双主"冲突。配合 chart 内置的复制延迟告警与 runbook,从日常运维到灾难接管都有章可循。

更多配置示例(PostGIS、TimescaleDB、PgBouncer、恢复场景)可在 charts/cluster/examples/ 目录中找到,测试场景全集见 charts/cluster/test/replica/。

登录后查看全文
charts