运维手册

Alauda Data Services Relational Database E3 集群的 day-2 运维实用参考。每个部分均可独立使用——直接跳转到所需的操作。

TIP

在 kubectl 命令中,将 CNPG 集群表示为 cluster.postgresql.cnpg.io ——在 ACP 集群上,裸 cluster 短名称会解析为 Cluster API 的资源。以下多个操作步骤使用 cnpg kubectl 插件(kubectl cnpg ...);请从上游 CloudNativePG 发布构件中安装该插件。

集群生命周期

创建集群

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata: { name: <name>, namespace: <ns> }
spec:
  instances: 3
  # Omit image fields to run the PostgreSQL version shipped with this
  # release. To select a major explicitly, set imageName to an operand
  # image from your platform registry, or create a ClusterImageCatalog
  # (not installed by default) and use imageCatalogRef — see
  # Configuration (Images section).
  storage:
    size: 5Gi
    # storageClass: <override>   # omit to use the default block SC
  bootstrap:
    initdb:
      database: app
      owner: app
      # postInitApplicationSQL:  # runs in the 'app' DB after init
      #   - "CREATE EXTENSION IF NOT EXISTS vector"

等待 phase: Cluster in healthy state。3 实例集群通常需要两到五分钟才能达到健康状态(首次使用时,镜像拉取所需时间占主要部分)。

扩缩实例

通过编辑 spec.instances 增加或减少 Replica:

kubectl patch cluster.postgresql.cnpg.io <name> -n <ns> \
  --type=merge -p '{"spec":{"instances":4}}'

扩容会添加新的 standby pod(一次添加一个);缩容会移除编号最高的 Replica。缩容操作永远不会删除 primary——若要移除 primary 的 pod,请先执行 switchover。

Switchover(计划内,不丢失数据)

使用 cnpg kubectl 插件提升指定的 Replica:

kubectl cnpg status <name> -n <ns>          # see current topology
kubectl cnpg promote <name> <name>-2 -n <ns>

当前 primary 会完成正在执行的事务,目标 Replica 提升为 primary,旧 primary 作为 standby 重新加入。写入停机时间通常为 5–15 秒。(spec.switchoverDelay 控制 operator 等待旧 primary 正常关闭的时长。)

删除集群

kubectl delete cluster.postgresql.cnpg.io <name> -n <ns>
DANGER

删除 Cluster 会删除其 PVC,因此也会删除其中的数据。 实例 PVC 归 Cluster 所有,并会随 Cluster 一起进行垃圾回收。删除前,请执行一次最终备份(并验证备份确实存在!);或者改为休眠集群(使用 cnpg.io/hibernation: "on" annotation),以便停止计算资源但保留卷。

备份和恢复

配置备份存储

CNPG 使用 Barman Cloud plugin 进行兼容 S3 的备份。有关创建流程(包括 plugin attach 触发的滚动重启,请在首次备份前等待集群达到健康状态),请参阅快速入门:第 3 步。

按需备份

apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata: { name: <name>-backup-20260610, namespace: <ns> }
spec:
  cluster: { name: <cluster-name> }
  method: plugin
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

查看进度:kubectl get backup -n <ns>。phase 会从 running 转换为 completed(或 failed)。小型集群的备份通常需要 10–60 秒。

计划备份

apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata: { name: <name>-daily, namespace: <ns> }
spec:
  schedule: "0 0 3 * * *"   # 03:00 UTC daily — 6-field cron WITH seconds
  immediate: false
  suspend: false
  backupOwnerReference: self
  cluster: { name: <cluster-name> }
  method: plugin
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

若要在创建时立即运行首次备份,请设置 immediate: true。注意:将 immediate: true 修补到现有 ScheduledBackup 上不会追溯触发备份——该设置仅在创建时生效。

从备份恢复

创建一个新的 Cluster,并使用 bootstrap.recovery 指向源集群的 ObjectStore。使用 externalClusters 声明源集群:

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata: { name: source-backup-readonly, namespace: <ns> }
spec:
  configuration:
    destinationPath: s3://<bucket>/<source-prefix>/   # SOURCE cluster's path
    endpointURL: http://<your-s3-endpoint>
    s3Credentials:
      accessKeyId:     { name: s3-creds, key: ACCESS_KEY_ID }
      secretAccessKey: { name: s3-creds, key: ACCESS_SECRET_KEY }
---
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata: { name: <new-name>, namespace: <ns> }
spec:
  instances: 1
  storage: { size: 5Gi }
  bootstrap:
    recovery:
      source: source-cluster   # alias name
      # recoveryTarget:        # optional, for PITR
      #   targetTime: "2026-05-12 14:00:00.000000+00:00"
  externalClusters:
  - name: source-cluster
    plugin:
      name: barman-cloud.cloudnative-pg.io
      parameters:
        barmanObjectName: source-backup-readonly
        serverName: <source-cluster-name>   # the name of the SOURCE Cluster

系统会先运行完整恢复作业(小型集群通常需要约 30–60 秒),然后新的 primary 启动。PITR 要求恢复目标时间位于源集群的 WAL 归档范围内。

验证备份是否存在

mc alias set s3 http://<your-s3-endpoint> '<access>' '<secret>'
mc ls --recursive s3/<bucket>/<prefix>/base/
# Each base/<timestamp>/ directory is one full backup
mc ls --recursive s3/<bucket>/<prefix>/wals/ | tail -20
# WAL segments are continuously archived

故障转移场景

主 pod 丢失时自动故障转移

如果主 pod 被删除、终止或其节点发生故障,operator 会自动将 复制进度最超前的备用节点提升为主节点。无需手动操作。

kubectl delete pod <cluster>-1 -n <ns>   # simulate
kubectl get cluster.postgresql.cnpg.io <cluster> -n <ns> -w
# Watch the PRIMARY column change

kubectl cnpg status <cluster> -n <ns> 显示复制拓扑以及当前哪个 pod 是主节点。

手动故障转移(替换异常的主节点)

对于计划内替换,请使用上面的切换操作步骤 (kubectl cnpg promote)。避免在主节点上使用 kubectl delete pod——切换更加简洁。

灾难恢复(整个集群丢失)

按照从备份恢复操作步骤,将最近的备份恢复到新的 namespace 或使用新的集群名称。

节点驱逐和节点维护

驱逐工作节点

CNPG 会为每个集群创建 PodDisruptionBudgets,因此 kubectl drain 可以安全运行:

kubectl drain <node> --ignore-daemonsets --delete-emptydir-data

具体行为取决于被驱逐节点上运行的是哪个 pod:

场景预期结果
仅有从节点PDB 允许驱逐一个从节点;驱逐操作会快速完成
主节点operator 首先执行切换;在新的主节点提升之前,主节点 PDB 会阻止驱逐
主节点和一个从节点位于同一节点上先执行切换,然后驱逐从节点;集群会暂时处于冗余降低状态

对于同步复制集群,一次仅驱逐一个节点,并等待 kubectl cnpg status 显示所有从节点再次处于流式复制状态,然后再驱逐下一个节点。

升级期间隔离节点

升级工作节点时,先隔离节点,然后再驱逐。operator 会自动将 pod 重新调度到其他工作节点。如果 pod 无法重新调度(容量不足),请添加节点,或在驱逐前临时降低 spec.instances。

Operator 和 PostgreSQL 升级

Operator(OLM bundle)升级

当 installPlanApproval: Automatic 时,OLM 会自动从 catalog 获取新版本。CSV 会从旧版本过渡到新版本,operator pod 只会重启一次。Operator 升级期间不会重新创建 PostgreSQL pod ——它们会继续按原样运行。

如果存在 installPlanApproval: Manual,InstallPlan 会保持在 phase: RequiresApproval,直到你对其进行修补:

kubectl patch installplan <name> -n cnpg-system \
  --type=merge -p '{"spec":{"approved":true}}'

有关版本间升级的具体信息,请参阅 Upgrade。

PostgreSQL 主版本升级(例如 17 → 18)

CNPG 支持声明式主版本升级:将集群指向下一个主版本的 operand 镜像(spec.imageName;如果你管理 catalog,则使用 spec.imageCatalogRef.major)。Operator 会执行离线升级:实例关闭,在专用 job 中运行 pg_upgrade,然后实例以新的主版本恢复运行(从节点会根据升级后的主节点重新创建)。

触发升级前请先创建备份,并首先验证扩展与新主版本的兼容性;同时预计在 pg_upgrade job 运行期间出现写入中断(时长取决于数据量)。

次版本 / 修补版本升级

更新 PostgreSQL 次版本(例如 18.3 → 18.4)属于滚动更新:从节点逐个使用新镜像重启,然后执行切换,最后更新旧主节点。典型写入中断时间为 5–15 秒(即切换所需时间)。

监控

每个实例都会通过内置 exporter 在端口 9187 上公开指标;默认查询包(位于 cnpg-system 中的 cnpg-default-monitoring ConfigMap)会在启动时由 operator 自动安装并完成连接配置 ——无需在 Cluster 上进行任何配置。

要在 ACP 上抓取这些指标,需要使用带有 prometheus: kube-prometheus 标签的 PodMonitor;如需进行可视化,请导入两个 Curated 仪表板 ——具体步骤均在 Grafana dashboards 中介绍。

日志访问

# Operator log
kubectl logs -n cnpg-system deploy/cnpg-controller-manager --tail=200

# Per-instance log (PostgreSQL + instance manager)
kubectl logs -n <ns> <cluster-name>-1 -c postgres --tail=200

日志采用 JSON 格式;可通过 jq 管道处理,以提高可读性。

故障排查矩阵

症状最可能的原因解决方法
CSV 卡在 Installing,并显示 deployment not availableoperator Pod 无法启动在 operator Pod 上运行 kubectl logs --previous
集群存在时,kubectl wait/get cluster/<name> 返回 NotFound在 ACP 上,裸 cluster 会解析为 Cluster API 的资源使用 cluster.postgresql.cnpg.io/<name>
Cluster 卡在 Setting up primary,并显示 ImagePullBackOff此集群的节点无法访问 operand 镜像将 spec.imageName 设置为平台 registry 中的 operand 镜像
PVC 卡在 Pending没有默认 StorageClasskubectl get sc;添加 spec.storage.storageClass
Backup 显示 failed,并带有 requested plugin is not availableplugin-attach 部署尚未完成就触发了备份等待 Cluster in healthy state,然后重新创建 Backup
Backup 显示 failed,并带有 no such host集群节点无法访问 ObjectStore endpointURL使用集群内部端点
Backup 显示 failed,并带有 SignatureDoesNotMatchS3 访问密钥 / 密钥对错误确认 Secret 中的密钥与 ObjectStore 中的 accessKeyId.key / secretAccessKey.key 相符
恢复 job 错误:目标 not yet streamedPITR 目标时间不在源的 WAL 归档范围内使用 mc ls <bucket>/<source>/wals/ 确认时间戳范围包含目标时间
Prometheus 中没有指标缺少 PodMonitor,或缺少 prometheus: kube-prometheus 标签请参阅 Grafana dashboards
psql -U <app> 因 Peer authentication failed 而失败以错误的 OS 用户通过 Unix socket 连接使用 TCP,通过 <cluster>-rw 服务连接,并使用 <cluster>-app Secret 中的密码

对于配置层面的问题,请参阅 故障排查快速参考。

问题反馈渠道

  • 产品问题(operator、镜像、备份插件):请通过您的 Alauda 支持渠道反馈。
  • 文档问题:GitHub alauda/cnpg-docs。

如需了解这些操作背后的深层模型,请参阅架构。

商标声明

CloudNativePG™ 是 The Linux Foundation 的商标。

PostgreSQL® 是 PostgreSQL Community Association of Canada 的注册商标。

Alauda 是一家独立供应商。本产品与 The Linux Foundation、PostgreSQL Community Association of Canada 无关联,也未获得其认可或赞助。所有商标均为其各自所有者的财产,在此仅用于标识目的。