CloudNativePG 副本集群搭建指南:跨集群复制、延迟回放与提升(Promotion)机制详解
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)需要满足两点:
- 开启备份(推荐):副本若走
object_store引导方式,源集群必须把数据归档到对象存储(S3/Azure/GCS); - 网络可达:副本 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,用于校验"提升条件是否满足",满足后副本才允许提升 |
工作流程可以这样理解:
- 正常状态:源集群(primary)健康,副本集群持续流复制,
self ≠ primary,自身保持只读副本角色; - 源集群故障:运维在副本上设置/验证
promotionToken,operator 检查提升条件(令牌匹配、复制状态等); - 满足条件后:副本执行 promote,脱离流复制,对外提供读写;
- 重建原集群:原位置重建后,应以该副本为新的 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,其处置思路值得记住:
- 查状态:在主库执行
SELECT * FROM pg_stat_replication;确认副本是否在线、延迟多大; - 查资源:网络带宽、CPU/内存、磁盘 I/O 是最常见瓶颈(跨集群复制对网络尤其敏感);
- 查配置:开启
wal_compression: "on"可显著降低跨网络复制的带宽占用,且无需重启;实例数较多时调大max_wal_senders; - 查查询:长时间运行的会话会阻碍 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/。