#架构

参考：CloudNativePG 项目文档。

Alauda 版 CloudNativePG 将上游 CNPG operator、mirror-registry 镜像以及与 ACP 对齐的 RBAC 打包在一起。下面的架构同时适用于上游版本和 Alauda 发行版；与 ACP 相关的新增内容会在适用处单独说明。

#核心组件

1. Operator Controller (cnpg-controller-manager)

   • 在 cnpg-system 命名空间中以单个 Deployment 运行，监视所有命名空间（AllNamespaces 安装模式）。
   • 协调 CNPG Custom Resources：Cluster、Backup、ScheduledBackup、Pooler、Database、Publication、Subscription、ImageCatalog、ClusterImageCatalog。
   • 处理集群生命周期：创建、扩缩容、配置更新、故障切换时的主节点提升，以及 PG pod 的滚动升级。
   • Kubernetes 原生：不同于封装 Patroni 并依赖独立分布式一致性存储（etcd、ZooKeeper）的旧版 operator，CNPG 仅使用 Kubernetes 原语（Leases、Endpoints）实现主从协调。

2. Instance Manager（pod 内 sidecar）

   • 每个 PostgreSQL pod 一个，通过 gRPC 与 operator 通信。
   • 负责本地 PostgreSQL 生命周期：启动/停止 server、应用配置、管理 WAL archive。
   • 将实例状态（recovery mode、replication lag、磁盘使用量）回传给 operator。
   • 消除了对独立 Patroni 进程及其 etcd 依赖的需求。

3. PostgreSQL Container Image

   • Alauda 发行版：build-harbor.alauda.cn/middleware/cnpg/postgresql:<MM.mm>-{minimal,standard}-trixie，适用于 PostgreSQL 14、15、16、17、18。
   • 上游对应版本：ghcr.io/cloudnative-pg/postgresql:<MM.mm>-{system,minimal,standard}-trixie。
   • Standard 变体：包含 pgaudit、pgvector、pg-failover-slots、postgis（在受支持的平台上）。
   • Minimal 变体：仅包含基础 PostgreSQL；适用于扩展通过其他方式分层提供的场景。
   • 两种变体均提供多架构支持（amd64 + arm64）。

4. Pooler / PgBouncer

   • 可选的 Pooler CR 会在 Cluster 前创建一个 PgBouncer Deployment。
   • 镜像：build-harbor.alauda.cn/middleware/cnpg/pgbouncer:1.25.1。
   • 模式：session、transaction、statement。基于上游 PgBouncer。

5. Barman Cloud Plugin（独立的同级包，Alpha 之后）

   • 用于对象存储备份的 CNPG-I plugin，采用 pgBackRest 语义。
   • 作为 cloudnative-pg-barman-cloud-plugin ACP 包提供；不随 operator 包一起发布。

#CRD 布局

#集群拓扑

一个带有 instances: 3 的 Cluster CR 会生成：

cluster-example-1     (primary, accepts writes)
cluster-example-2     (replica, streaming from primary)
cluster-example-3     (replica, streaming from primary)

每个实例都是独立的 StatefulSet 风格 pod，并拥有各自的 PVC。没有共享存储；复制方式为流式 WAL 复制。

系统会自动创建三个 Service：

#高可用与故障切换

• 主节点选举：operator 在启动时以及发生故障切换时选举主节点。选举使用 Kubernetes Lease 对象进行分布式协调。
• 故障切换触发条件：pod 丢失、节点丢失、复制堆积量超过阈值，或通过 cluster.spec.targetPrimary 由 operator 发起切换。
• 故障切换时间：通常为个位数秒。operator 通过 instance manager 心跳检测主节点故障，使用 pg_promote 提升某个从节点，并更新 <cluster>-rw Service 端点以重定向流量。
• 同步复制：可通过 spec.minSyncReplicas 和 spec.maxSyncReplicas 进行配置，要求 N 个从节点在每次写入被接受为持久化之前完成确认。
• 无脑裂：operator 的提升逻辑在 K8s API 层面基于一致性协议；当原主节点仍被视为存活时，不会提升第二个主节点。

#存储模型

• 每个实例一个 PVC，命名为 <cluster>-N，其中 N 为实例编号。
• 存储类通过 spec.storage.storageClass 按 Cluster 设置（CNPG 中没有集群级默认回退）。
• 卷大小通过 spec.storage.size 设置。
• 回收策略：对于短生命周期测试集群，通常使用 Delete；生产环境建议使用 Retain。该策略在 StorageClass 本身上设置。
• WAL 归档：可选的单独 spec.walStorage 块可将 WAL 路由到不同的卷/StorageClass，以实现性能隔离。

#镜像目录模型

ImageCatalog 和 ClusterImageCatalog CR 允许集群 operator 集中管理 PostgreSQL 镜像版本：

apiVersion: postgresql.cnpg.io/v1
kind: ClusterImageCatalog
metadata:
  name: postgresql
spec:
  images:
    - major: 14
      image: build-harbor.alauda.cn/middleware/cnpg/postgresql:14.22-standard-trixie
    - major: 18
      image: build-harbor.alauda.cn/middleware/cnpg/postgresql:18.3-standard-trixie

随后，Cluster 可以按主版本引用该目录：

spec:
  imageCatalogRef:
    apiGroup: postgresql.cnpg.io
    kind: ClusterImageCatalog
    name: postgresql
    major: 18

这样可以将 Cluster CR 规范与具体镜像标签解耦，从而简化整个集群池的 PostgreSQL 升级。

#ACP RBAC 架构

Alauda 版 CloudNativePG 打包了一个五角色的 L5 RBAC 体系，并接入 ACP 的 namespace-admin / namespace-developer 聚合链：

每个角色都包含一个公开的 shell ClusterRole（携带 ACP target-role 聚合标签）以及一个或多个 base ClusterRoles（包含实际规则）。ACP 的 AND-matcher 聚合机制要求 base role 同时具备这两个标签（target-role + scope）才会生效。Cluster 作用域资源（ClusterImageCatalog）位于专用的 cluster-scope:*-base ClusterRoles 中。

#对比：Alauda CNPG 与 Alauda PostgreSQL（Zalando 路线）

这两个 operator 相互独立，可以在同一个集群中共存（不同命名空间、不同 CRD group）。二者之间的迁移通过逻辑复制或备份/恢复完成，而不是原地迁移。