#配置

如何在 Alauda Container Platform 上配置 CloudNativePG Cluster： PostgreSQL 参数、用户和数据库、复制、存储以及镜像。首次部署请参阅快速开始；有关架构请参阅 架构。

#PostgreSQL 参数

spec:
  postgresql:
    parameters:
      shared_buffers: 512MB
      max_connections: "200"
      work_mem: 8MB
    pg_hba:
      - host all all 10.0.0.0/8 scram-sha-256

• 一组参数由 operator 管理，如果设置则会被拒绝 (archive_mode, archive_command, restore_command, port, hot_standby, ssl*, synchronous_standby_names, shared_preload_libraries, recovery targets, listen/log/file-path settings)。请改用专用字段： spec.postgresql.shared_preload_libraries, spec.postgresql.synchronous（如下）。
• 常见的调优参数（max_connections, shared_buffers, work_mem, effective_cache_size、autovacuum 和 checkpoint 设置等）均允许使用。
• operator 会注入合理的默认值，包括 wal_level=logical, archive_timeout=5min, wal_keep_size=512MB 和 TLS ≥ 1.3。
• ALTER SYSTEM 默认禁用 (spec.postgresql.enableAlterSystem) — 配置采用声明式方式；更改会在 cluster 中滚动生效，由 spec.primaryUpdateStrategy （默认 unsupervised）和 spec.primaryUpdateMethod （restart 或 switchover）控制。
• pg_hba 条目会插入在 operator 管理的固定规则 （本地 peer 访问、证书认证复制）与末尾默认规则 host all all all scram-sha-256 之间。

#用户和数据库

引导数据库和所有者来自 spec.bootstrap.initdb （默认值：数据库 app、所有者 app，凭据位于 <cluster>-app secret 中）。额外的 role 通过声明式方式定义：

spec:
  managed:
    roles:
      - name: alice
        ensure: present
        login: true          # managed roles default to login: false
        createdb: true
        passwordSecret:
          name: alice-creds  # kubernetes.io/basic-auth secret

其他数据库作为各自独立的 Database 资源：

apiVersion: postgresql.cnpg.io/v1
kind: Database
metadata:
  name: pg-demo-reporting
spec:
  cluster:
    name: pg-demo
  name: reporting
  owner: alice
  extensions:
    - name: vector        # pgvector

Superuser 访问默认禁用；可通过 spec.enableSuperuserAccess: true 启用（会创建 <cluster>-superuser secret）。

#扩展和 pgaudit

standard PostgreSQL operands 包含 pgvector、pgaudit、PostGIS、 zhparser、TimescaleDB（Apache-2 OSS，PG 15+）以及 pg_failover_slots —— 均可在不启用 Kubernetes ImageVolume feature gate 的情况下使用。

大多数扩展可通过 Database 资源（spec.extensions，见上文）或直接执行 CREATE EXTENSION 按数据库启用。其中有两个是加载时扩展，必须通过 spec.postgresql.shared_preload_libraries 声明（裸的 shared_preload_libraries GUC 由 operator 管理并会被拒绝）：

spec:
  postgresql:
    shared_preload_libraries:
      - pgaudit
      - pg_failover_slots
      - timescaledb        # PG 15+ only
    parameters:
      pgaudit.log: "ddl, write"   # configure pgaudit declaratively

• pgaudit 必须以声明式方式配置。 它是由 operator 管理的扩展： 手动执行的 CREATE EXTENSION pgaudit 会在下一次重启时被删除。 请将 pgaudit 添加到 shared_preload_libraries，并按上文设置 pgaudit.* 参数——operator 会为你创建并维护该扩展。
• pg_failover_slots 按设计仅支持预加载（不需要 CREATE EXTENSION 步骤）：一旦加入 shared_preload_libraries， 它会自动将 logical replication slots 同步到从节点。
• timescaledb 需要 shared_preload_libraries，且仅在 PG 15–18 上可用 （Debian trixie 上没有适用于 PG 14 的 OSS 包）。仅提供 Apache-2 版本—— 不包含 TSL 功能（压缩、continuous aggregates）。

#复制和高可用性

spec:
  instances: 3
  postgresql:
    synchronous:                 # optional synchronous replication
      method: any
      number: 1
      dataDurability: required   # 'preferred' favors availability
  affinity:
    podAntiAffinityType: required   # default 'preferred'
    topologyKey: kubernetes.io/hostname

Failover 是自动的（operator 会提升同步最先进的从节点）。可通过 cnpg kubectl 插件执行手动 switchover （kubectl cnpg promote <cluster> <instance>）。

#存储

spec:
  storage:
    size: 10Gi                  # grow in place by raising it (no shrink)
    storageClass: sc-topolvm    # use a TopoLVM class for production
  walStorage:                   # optional dedicated WAL volume
    size: 5Gi
    storageClass: sc-topolvm

可通过 spec.tablespaces 支持 tablespace（每个 tablespace 都会获得各自的 PVC）。

#镜像和升级

Operand 镜像默认使用随 operator bundle 提供的版本。若要显式固定，请将 spec.imageName 设置为来自平台 registry 的 PostgreSQL operand 镜像——始终 使用不可变 tag。小版本更新采用滚动重启；大版本升级采用声明式方式（更改 镜像的 major 版本；cluster 会执行离线升级）。参阅 升级。

#IPv6 注记

在单栈 IPv6 cluster 上，不包含 upstream url.Build 括号修复 （upstream PR #10682）的 operator 版本无法通过裸 IPv6 Pod IP 访问 instance managers。双栈 cluster 不受影响。请查阅你所使用 operator 版本的 release notes。

#故障排查速查