企业官网建设流程全解析

• 云原生
• 后端
• 数据库
• 运维

本指南以 README.md 为核心骨架，结合仓库内的 概念文档、快速上手、配置参数参考、集群清单参考 以及 v1→v2 迁移指南，并辅以pkg/目录下的控制器与集群源码，系统讲解 Postgres Operator 的工作原理、功能矩阵、版本支持、部署方式与迁移要点。读完本文，你将掌握如何在 Kubernetes 上通过 CRD 清单声明式地创建、升级、备份和删除 Patroni 驱动的高可用 PostgreSQL 集群，并理解滚动更新、在线扩容、连接池、就地大版本升级等关键能力的实现机制。

一、Postgres Operator 是什么：核心工作模型

Postgres Operator 在 Kubernetes 上交付"易于运行、开箱即用"的高可用 PostgreSQL 集群，底层由 Patroni 驱动（README 原文："delivers an easy to run highly-available PostgreSQL clusters on Kubernetes powered by Patroni"）。它的核心设计哲学是：只通过 Postgres 清单（即 CRD）进行配置，从而无缝融入没有 Kubernetes API 直接访问权限的自动化 CI/CD 流水线，以基础设施即代码（Infrastructure as Code）替代人工运维。

概念文档 将它的工作方式归纳为四条循环：

1. 监听清单变化：operator 监听 PostgreSQL 集群清单（manifest）的增、删、改事件，并据此变更运行中的集群。当用户提交一个新清单时，operator 拉取该清单并创建一整套必要的实体——如 K8s StatefulSet、Postgres 角色、Service 与 Endpoint 等。
2. 监听自身配置变化：operator 同时监听自身配置的变化。例如当 Pod 中的 Docker 镜像变更时，operator 会执行滚动更新（rolling update），即逐个重启每个受管 StatefulSet 的 Pod 以应用新镜像。
3. 周期性对账：operator 定期把每个 Postgres 集群的实际状态与清单定义的期望状态进行同步（sync），确保两者收敛一致。在源码中，这一机制体现为 pkg/controller/operator_config.go 中的resync_period（默认30m）与repair_period（默认5m）两个配置项。
4. 免人工介入：所有配置均通过清单完成，无需直接访问 K8s API，方便自动化部署流水线集成。

职责边界（Scope）：operator 的职责聚焦于供应（provisioning）、修改配置与清理使用 Patroni 的 Postgres 集群——既包括 K8s 资源层面，也包括集群启动后的数据库与角色供应。它尽量把工作交给 Kubernetes 与 Patroni 完成（尤其是集群引导和高可用），自身只承担滚动更新等全局性编排。监控（Monitoring）与调优（tuning）Postgres不在当前 operator 的职责范围内，但可以通过全局可配置的 sidecar灵活补充 Prometheus、ZMON 等工具。

二、Operator 功能全览

README 罗列了 operator 的核心功能。以下逐条展开，并结合源码说明其实现路径。

1. 滚动更新（Rolling updates）

集群清单的任何变更——包括快速的次版本升级——都会触发滚动更新：operator 逐个重新创建 StatefulSet 的 Pod，用新镜像/新配置替换旧实例。滚动更新由 pkg/cluster/cluster.go 的Update流程驱动，其中compareStatefulSetWith（pkg/cluster/cluster.go）负责对比新旧 StatefulSet 并判断是否需要滚动。

与之相关的还有enable_lazy_spilo_upgrade参数（默认false）：开启后 operator 只更新 StatefulSet 中的镜像（Spilo 与 InitContainer）而不立即执行滚动更新，假设 Pod 会在稍后（如节点轮换时）以新镜像重启。

2. 在线卷扩容（Live volume resize）

支持不重启 Pod的在线卷扩容，覆盖AWS EBS与PVC两种场景。该行为由storage_resize_mode配置项控制，共四种取值：

相关实现位于 pkg/util/volumes（EBS 相关见 pkg/util/volumes/ebs.go）。注意 AWS 上运行需要 Spilo 容器以特权模式运行（spilo_privileged: "true"），因为 EBS 扩容依赖该能力。

3. 数据库连接池（PGBouncer）

通过PGBouncer提供数据库连接池。连接池既可以按集群清单启用（enableConnectionPooler/enableReplicaConnectionPooler），也可以在 operator 配置中预设全局默认值（见 pkg/util/constants/pooler.go）。全局默认配置包括：

• connection_pooler_number_of_instances：pooler 实例数，默认2（也是最低要求）；
• connection_pooler_image：默认镜像ghcr.io/zalando/postgres-operator/pgbouncer:v2.0.3；
• connection_pooler_max_db_connections：pooler 最大连接数，默认60（会在多个 pooler Pod 间均分，即默认两实例时每 Pod 30 连接）；
• connection_pooler_mode：默认transaction（事务级池化），可选session；
• connection_pooler_schema：默认pooler，用于存放凭据查询函数；
• connection_pooler_user：默认pooler。

连接池的核心处理逻辑见 pkg/cluster/connection_pooler.go。

4. 快速的就地大版本升级（In-place major version upgrade）

支持原地（in-place）大版本升级，并可对全部集群执行全局升级。升级模式由major_version_upgrade_mode配置（源码默认值见 pkg/util/config/config.go，CRD 合并逻辑见 pkg/controller/operator_config.go）：

三种模式下，在清单中调高版本号都会触发 Pod 滚动更新。当模式为full时，GetDesiredMajorVersion（pkg/cluster/majorversionupgrade.go）会把低于minimal_major_version（默认"14"）的集群版本覆盖为target_major_version（默认"18"）；模式为off时，major_version_upgrade_team_allow_list中的团队集群仍可升级（见 pkg/cluster/majorversionupgrade.go）。升级成败会以last-major-upgrade-success/last-major-upgrade-failure注解写回 Postgres 资源（pkg/cluster/majorversionupgrade.go）。

5. Pod 引导期保护与可配置维护窗口

集群在引导（bootstrap）阶段受到保护，并支持可配置的维护窗口（maintenance windows）。enable_maintenance_windows（默认true）控制该特性，maintenance_windows定义允许执行自动大版本升级、主 Pod 迁移等维护操作的时间窗口，支持"01:00-06:00"（每日）或"Sat:00:00-04:00"（指定星期）两种格式，时间为 UTC。清单中的maintenanceWindows字段可覆盖全局配置。集群级 Pod 中断预算（PDB）默认开启（enable_pod_disruption_budget: "true"），PDB 名称模板为postgres-{cluster}-pdb（pdb_name_format）。

6. 集群恢复与克隆（AWS / GCS / Azure）

支持在AWS、GCS、Azure上恢复和克隆 Postgres 集群。克隆通过清单的clone顶层键配置：可从一个正在运行的集群或S3 上的 basebackup克隆，支持cluster（源集群名）、uid（源集群的 K8s UID，保证 S3 bucket 路径唯一）、timestamp（恢复截止时间戳，非包含式）、s3_wal_path、s3_endpoint、s3_access_key_id等参数。恢复能力建立在 Spilo + WAL 归档之上，相关配置见下文"备份与 WAL 归档"。

7. 逻辑备份（Logical backups）

除了 WAL 归档，还可以配置逻辑备份到 S3 或 GCS bucket。逻辑备份由 operator 管理的 K8sCronJob执行：对副本运行pg_dumpall（若可能），把压缩结果上传到<configured-s3-bucket-prefix>/<pg_cluster_name>/<cluster_k8s_uuid>/logical_backups（示例镜像见 logical-backup/Dockerfile）。关键参数（CRD 配置下归入logical_backup键）：

• logical_backup_schedule：Cron 格式调度，默认30 00 * * *；
• logical_backup_s3_bucket/logical_backup_s3_bucket_prefix（默认spilo）/logical_backup_s3_sse（默认AES256）；
• logical_backup_provider：s3（默认）、gcs或az；
• logical_backup_s3_retention_time：备份保留时间，如"3 days"、"2 weeks"、"1 month"，新备份上传后删除过期文件；
• logical_backup_successful_jobs_history_limit/logical_backup_failed_jobs_history_limit（均默认3）；
• logical_backup_ttl_seconds_after_finished：完成后自动删除任务，默认86400秒。

每个集群清单里可用enableLogicalBackup（默认false）、logicalBackupRetention、logicalBackupSchedule单独控制。

8. Standby 集群（Standby cluster）

可从S3 / GCS WAL 归档或远程主机创建 standby 集群。清单的standby顶层键支持：s3_wal_path、gs_wal_path、standby_host（远程主库地址）、standby_port（默认5432）、standby_primary_slot_name。三者至少指定其一，且s3_wal_path与gs_wal_path互斥，可与standby_host组合获得额外冗余。一个可直接使用的示例见 manifests/standby-manifest.yaml。

9. 面向非云环境的可配置性

operator 不强制依赖云厂商：watched_namespace、storage_resize_mode: off、etcd_host（当使用 etcd 而非 Kubernetes 原生 DCS 时）、自定义storageClass等参数使其可以在裸机、本地 kind/minikube 等环境运行。

10. 基础凭据与用户管理

在 K8s 上提供基础的凭据与用户管理，简化应用部署。清单的users段声明要创建的数据库用户（支持SUPERUSER、REPLICATION、CREATEROLE、CREATEDB、BYPASSRLS、LOGIN/NOLOGIN等标志），databases段声明数据库及其属主。operator 会把每个用户凭据写入 K8s Secret（模板见secret_name_template，默认{namespace}.{username}.{cluster}.credentials.{tprkind}.{tprgroup}），支持enable_password_rotation（默认false）、password_rotation_interval（默认90天）、password_rotation_user_retention（默认180天），也支持不额外建用户的原地改密（usersWithInPlaceSecretRotation）。此外可通过 Teams API 自动创建团队成员用户（见teams_api配置组）。

11. 自定义 TLS 证书

清单的tls键支持加载自定义证书：secretName指定承载证书的 K8s Secret（可由 CertManager 等工具管理），certificateFile（默认tls.crt）、privateKeyFile（默认tls.key）、caFile与caSecretName定义 CA 路径。使用前需要在清单或全局配置中定义spiloFSGroup/spilo_fsgroup。

12. 可视化 UI

提供创建与编辑 Postgres 集群清单的 Web UI（postgres-operator-ui）。UI 通过 operator 的 REST API（api_port，默认8080）工作，具体用法见 docs/operator-ui.md，UI 源码位于 ui/。

13. OpenShift 兼容

兼容OpenShift：部署时需把kubernetes_use_configmaps设为"true"（因为 OpenShift 不支持用 Endpoints 存储 leader 与配置键），并使用专用的 RBAC 清单 manifests/operator-service-account-rbac-openshift.yaml。

14. 多架构支持（Multi-arch）

operator 与 Spilo 镜像均支持多种 CPU 架构（multi-arch）。

三、PostgreSQL 能力

版本支持

支持PostgreSQL 18，起始版本 14+（对应 Spilo 镜像ghcr.io/zalando/spilo-18，详见 manifests/configmap.yaml 中的docker_image）。

Patroni 流复制集群

所有集群通过Patroni构建流复制拓扑：主库与副本使用application=spilo标签标识，spilo-role标签标识当前角色（主/副本）。operator 会为主库与副本分别创建 Service/Endpoint（副本 Service 带-repl后缀），由 Patroni 负责故障转移与角色切换。

基于时间点恢复（PITR）

通过 pg_basebackup 与 WAL-G 或 WAL-E（经由 Spilo 镜像）实现基于时间点恢复。WAL 归档目标由wal_s3_bucket（S3）、wal_gs_bucket（GCS）、wal_az_storage_account（Azure）等全局参数配置。

预加载库（Preload libraries）

Spilo 镜像预加载了 bg_mon、pg_stat_statements、pgextwlist、pg_auth_mon。

内置流行扩展

Spilo 内置了大量流行的 Postgres 扩展，包括（来自 README）：decoderbufs、hypopg、pg_cron、pg_repack、pg_partman、pg_stat_kcache、pg_audit、pgfaceting、pgq、pgvector、plpgsql_check、plproxy、postgis、roaringbitmap、set_user、timescaledb。

此外，operator 还通过 Postgres 逻辑解码与pgoutput插件支持变更数据捕获（CDC）流（清单streams键），并为每个applicationId创建独立的逻辑复制槽与PUBLICATION，消费端可对接 Debezium 等外部工具（详见 docs/reference/cluster_manifest.md）。

四、版本支持矩阵

README 给出了各 release 对 Postgres、Kubernetes 与 Golang 的版本支持情况（以仓库当前内容为准）：

其中 v2.0.x 系列是当前主线版本，仓库中的 Helm chart 与部署清单（manifests/postgres-operator.yaml）默认使用v2.0.3镜像。README 同时说明该项目由 Zalando 开发，并已在生产环境中运行超过五年。

五、快速上手

本节内容基于 docs/quickstart.md，可在本地 Kubernetes 环境（minikube / kind / k3d，或 Docker Desktop 内置 K8s）快速体验。

前置条件

• 一个本地 K8s 集群：minikube（容器/VM 内建集群，需 Docker/KVM 等）、kind 或 k3d（基于 Docker 的多节点集群）均可；
• kubectl命令行工具。

配置方式说明

operator 的配置只能在部署新集群之前完成，有两种互斥方式：ConfigMap（传统方式）或OperatorConfiguration CRD。详见 docs/reference/operator_parameters.md。下文以 ConfigMap 方式为例。

部署方式（三选一）

方式一：手动应用 YAML 清单（注意 manifests/ 目录仅为示例，应按实际环境调整命名空间等）：

git clone https://github.com/zalando/postgres-operator.git cd postgres-operator # 按顺序应用以下清单 kubectl create -f manifests/configmap.yaml # operator 配置 kubectl create -f manifests/operator-service-account-rbac.yaml # 身份与权限 kubectl create -f manifests/postgres-operator.yaml # operator Deployment kubectl create -f manifests/api-service.yaml # 供 UI 使用的 operator API

方式二：Kustomization（kubectl 1.14+）：

kubectl apply -k github.com/zalando/postgres-operator/manifests

方式三：Helm chart（仅支持 Helm v3，v1.8.0 起移除 Helm v2 支持）：

# 添加 operator 与 UI 的 chart 仓库 helm repo add postgres-operator-charts https://opensource.zalando.com/postgres-operator/charts/postgres-operator helm repo add postgres-operator-ui-charts https://opensource.zalando.com/postgres-operator/charts/postgres-operator-ui # 安装 helm install postgres-operator postgres-operator-charts/postgres-operator helm install postgres-operator-ui postgres-operator-ui-charts/postgres-operator-ui

仓库自带的 chart 源码位于 charts/postgres-operator/ 与 charts/postgres-operator-ui/。

OpenShift 部署：需将kubernetes_use_configmaps设为"true"并使用专用 RBAC：

oc create -f manifests/operator-service-account-rbac-openshift.yaml

本地一键启动：仓库提供自动化脚本，启动 minikube 并应用 manifests/minimal-postgres-manifest.yaml：

./run_operator_locally.sh

检查 operator 是否运行

启动可能需要数秒，务必先确认 operator Pod 处于Running状态再提交集群清单：

# YAML 清单部署 kubectl get pod -l name=postgres-operator # Helm chart 部署 kubectl get pod -l app.kubernetes.io/name=postgres-operator

若未进入Running，用kubectl describe查看事件或直接查看日志：

kubectl logs "$(kubectl get pod -l name=postgres-operator --output='name')"

部署 operator UI（可选）

确保 operator 的 REST API 通过 manifests/api-service.yaml 可达，并在 UI 的 部署清单 中配置该 API 地址。然后：

# 手动部署 kubectl apply -f ui/manifests/ # 或 kustomization kubectl apply -k github.com/zalando/postgres-operator/ui/manifests # 或 helm chart helm install postgres-operator-ui ./charts/postgres-operator-ui

确认 UI Pod 运行后，通过端口转发访问（浏览器打开localhost:8081）：

kubectl get pod -l name=postgres-operator-ui kubectl port-forward svc/postgres-operator-ui 8081:80

创建第一个 Postgres 集群

operator 运行后即监听postgresql资源事件。提交最小集群清单：

kubectl create -f manifests/minimal-postgres-manifest.yaml

manifests/minimal-postgres-manifest.yaml 的内容如下：

apiVersion: "acid.zalan.do/v1" kind: postgresql metadata: name: acid-minimal-cluster spec: teamId: "acid" volume: size: 1Gi numberOfInstances: 2 users: zalando: # database owner - superuser - createdb foo_user: [] # role for application foo databases: foo: zalando # dbname: owner preparedDatabases: bar: {} postgresql: version: "18"

清单通过校验后，operator 会创建 Service、Endpoint 与 StatefulSet，并按其numberOfInstances拉起指定数量的 Pod。所有资源以集群名命名，数据库 Pod 编号从-0开始，运行 Zalando 的 Spilo 容器镜像；主库与副本各有独立的 Service/Endpoint（副本带-repl后缀）。用标签验证：

# 查看集群 kubectl get postgresql # 查看数据库 Pod（标签 spilo-role 标识当前主库） kubectl get pods -l application=spilo -L spilo-role # 查看 Service kubectl get svc -l application=spilo -L spilo-role

更完整的配置示例见 manifests/complete-postgres-manifest.yaml，其中展示了preparedDatabases（预置数据库、默认角色与扩展）、additionalVolumes、users等高级用法；完整的键说明见 docs/reference/cluster_manifest.md。

通过 psql 连接集群

可对数据库 Pod 做端口转发连接（详见 docs/user.md）。用 minikube 时可直接从指向主库的 Service 取连接串：

export HOST_PORT=$(minikube service acid-minimal-cluster --url | sed 's,.*/,,') export PGHOST=$(echo $HOST_PORT | cut -d: -f 1) export PGPORT=$(echo $HOST_PORT | cut -d: -f 2)

从 K8s Secret 中取密码。默认拒绝非加密连接，需指定 SSL 模式：

export PGPASSWORD=$(kubectl get secret postgres.acid-minimal-cluster.credentials.postgresql.acid.zalan.do -o 'jsonpath={.data.password}' | base64 -d) export PGSSLMODE=require psql -U postgres

删除集群

直接删除postgresql自定义资源即可：

kubectl delete postgresql acid-minimal-cluster

这会删除关联的 StatefulSet、数据库 Pod、Service 与 Endpoint，释放 PersistentVolume 并删除 PodDisruptionBudget；但Secret 不会被删除，备份也会保留。注意：若集群仍处于启动阶段或卡在引导期就删除，可能出现postgresql资源已删而组件残留的情况（见 issue #551），此时重新部署一个干净的本地集群即可。

六、从 v1 迁移到 v2

如果你正在使用 v1.x 版本，在部署 v2 operator 前务必阅读 docs/migrate.md。v2.0 修改了部分默认值并移除了一批废弃字段，要点如下。

1. 默认启用 scram-sha-256 密码加密

v2 operator 默认将密码加密方式设为scram-sha-256。除非在清单spec.postgresql.parameters中显式配置password_encryption: md5，否则 operator 会用scram-sha-256重新加密受管 K8s Secret 中的密码并 ALTER 相应数据库用户；升级后 Pod 会以滚动方式轮换，请确保依赖这些凭据的客户端和驱动支持scram-sha-256。

为兼容旧客户端，当前默认 Spilo 镜像（spilo-18:4.1-p2）的pg_hba.conf仍允许md5密码，因此可以只把清单用户切换到scram-sha-256，未受管用户继续用md5连接。但该兼容不适用于依赖md5的pgBouncer连接，这种情况需在清单中配置password_encryption: md5。注意：修改清单中的加密方式需要重启 operator 才会更新数据库密码；同时建议在下一个移除md5的 Spilo 镜像发布前，主动更换未受管用户的md5密码。

2. K8s Endpoints 已弃用，改用 ConfigMap

v1.x 默认使用 K8s Endpoints 存储 Patroni 的 HA 状态，但 Endpoints 自 K8s 1.33 起被标记为弃用。v2.0 把kubernetes_use_configmaps的默认值改为true，因此升级前必须显式把该参数设为false（保留旧行为）。

官方明确警告：不要让带副本的集群直接从 Endpoints 一步切换到 ConfigMap——滚动更新期间若 leader endpoint 与 leader configmap 同时存在，有**脑裂（split-brain）**风险。安全的迁移步骤：

1. 把所有数据库集群缩容到仅剩一个主实例（把全局配置max_instances、min_instances设为1；若配置了ignore_instance_limits_annotation_key，先移除它）；
2. 等待所有集群健康，将kubernetes_use_configmaps改为true——这会触发全部集群主 Pod 的替换，期间会有与 Pod 重调度等长的停机；
3. 再次确认集群健康且 ConfigMap 已创建：每个集群应有三个 ConfigMap，名称分别为集群名加-config、-failover、-leader后缀；然后撤销第 1 步，按清单缩放到目标实例数；
4. 与 ConfigMap 同名的遗留 Endpoints 需要你或 K8s 垃圾回收机制自行删除。

3. 已移除的清单字段

请确保集群清单中不再出现以下字段，否则请改用替代项：

七、配置体系：ConfigMap 与 OperatorConfiguration CRD

operator 支持两种互斥的配置方式（详见 docs/reference/operator_parameters.md）：

ConfigMap 方式（传统）：配置放在由CONFIG_MAP_NAME环境变量指定的 key-value ConfigMap 中，参数名以下划线分隔；列表用逗号分隔，map 用key:value逗号分隔。仓库示例即 manifests/configmap.yaml，其中包含workers（默认8）、resync_period（30m）、repair_period（5m）、watched_namespace（*表示全命名空间）、docker_image（默认 Spilo 镜像）等完整默认配置。

OperatorConfiguration CRD 方式（推荐）：配置存于名为OperatorConfiguration的自定义资源中，在 operator 部署清单 里设置POSTGRES_OPERATOR_CONFIGURATION_OBJECT环境变量指向它即可启用。CRD 配置没有内置默认值，未提供的参数为空值，建议复制 manifests/postgresql-operator-default-configuration.yaml 再修改。本地启用方式：

kubectl create -f manifests/operatorconfiguration.crd.yaml # 注册 CRD kubectl create -f manifests/postgresql-operator-default-configuration.yaml kubectl create -f manifests/operator-service-account-rbac.yaml kubectl create -f manifests/postgres-operator.yaml # 记得设置上述 env var kubectl get operatorconfigurations postgresql-operator-default-configuration -o yaml

CRD 方式功能更强（支持 YAML 嵌套结构），官方建议使用它；ConfigMap 方式后续将被废弃。注意 CRD 方式下resource_check_interval/resource_check_timeout无效，改由CRD_READY_WAIT_INTERVAL/CRD_READY_WAIT_TIMEOUT环境变量控制（在 cmd/main.go 中解析，默认分别为 4s 与 30s）。

命令行与环境变量：operator 还支持若干命令行参数（-kubeconfig、-outofcluster、-nodatabaseaccess、-noteamsapi、-kubeqps默认 10、-kubeburst默认 20）与环境变量（CONFIG_MAP_NAME、OPERATOR_NAMESPACE、WATCHED_NAMESPACE、ENABLE_JSON_LOGGING等），完整清单见 docs/reference/command_line_and_environment.md。

八、文档导航

README 指向的完整文档体系（已转换为仓库根目录相对路径）：

• 工作原理与核心概念
• 安装与快速上手（含全部部署选项）
• K8s 上的 Postgres 使用体验
• Postgres Operator UI 使用指南
• DBA 选项：从 RBAC 到备份
• 构建、调试与扩展 operator
• 配置参数参考
• Postgres 集群清单参考
• 命令行选项与环境变量
• v1 到 v2 迁移指南

相关源码与清单可直接在仓库中查阅：控制器实现、集群生命周期管理、大版本升级逻辑、连接池实现、部署清单、最小集群清单 与 完整集群清单。

• 云原生
• 后端
• 数据库
• 运维