用途：在 Kubernetes homelab 中管理 CloudNative-PG（CNPG）PostgreSQL 数据库，覆盖共享平台集群与按应用独立集群两种模式，以及凭据、连接池、监控和排障。
架构：所有集群位于 database 命名空间。共享平台集群（platform-0/1/2）使用 spec.managed.roles 加每应用一个 Database CRD，PgBouncer 池地址为 platform-pooler-rw.database.svc。独立集群（如 Immich）通过 initdb 自建数据库与属主。两种模式下凭据均通过 kubernetes-replicator 复制到消费方应用命名空间。
选择：标准负载且无需特殊扩展用共享集群；需要自定义扩展（vector、PostGIS）或隔离用独立集群并指定 imageName；不确定时先用共享，必要时再迁移。
共享集群关键文件位于 kubernetes/platform/config/database/：cluster.yaml（含 spec.managed.roles）、databases.yaml（每应用一个 Database CRD）、role-secrets.yaml（角色密码，secret-generator 加 replicator）、pooler.yaml（PgBouncer 池）、superuser-secret.yaml、prometheus-rules.yaml。
新增应用数据库流程：在 cluster.yaml 的 spec.managed.roles 添加角色；在 role-secrets.yaml 创建角色密码 secret；在 databases.yaml 创建 Database CRD（多库应用如 sonarr-main、sonarr-log 共用一个角色，建多个同属主 Database CR）；在 kubernetes/clusters/<cluster>/config/<app>/ 创建凭据副本；在 namespaces.yaml 对应命名空间加标签 access.network-policy.homelab/postgres: "true"；在应用 kustomization.yaml 注册凭据副本。
独立集群流程：在 kubernetes/clusters/<cluster>/config/<app>/<app>-cluster.yaml 定义 Cluster，设置 inheritedMetadata 以允许复制自动生成的应用 secret；将凭据复制到消费方命名空间（CNPG 自动生成 <cluster-name>-app）；为应用命名空间加上述网络策略标签并在 kustomization.yaml 注册文件。
监控：Cluster 与 Pooler 均设 monitoring.enablePodMonitor: true，Prometheus 自动发现，无需手动 ServiceMonitor。告警规则在 prometheus-rules.yaml，包括 CNPGClusterNotHealthy（cnpg_pg_replication_streaming == 0，critical）、CNPGClusterHighConnections（连接使用率超 max_connections 80%，warning）、CNPGInstanceNotReady（副本 WAL receiver 断开，critical）。关键指标：cnpg_pg_replication_streaming、cnpg_pg_stat_activity_count、cnpg_pg_settings_setting{name="max_connections"}、cnpg_pg_replication_is_wal_receiver_up。
排障：可用 scripts/check-connection.sh <cluster> <app-namespace> [app-name] 做结构化健康检查。常见问题：Pod Pending 多为无 PV，检查 StorageClass fast 与 Longhorn；CrashLoopBackOff 查日志并调内存；应用连不上多为缺网络策略标签或 secret 未复制；复制后 secret 为空检查 replicate-from 指向；扩展缺失检查 imageName；数据库未创建检查 Database CRD；角色未创建检查 managed.roles；角色密码不匹配可删除 role-password secret 由 secret-generator 重建。手动连通性测试：kubectl run -n <app-ns> pg-test --rm -it --image=postgres:17 -- psql "postgresql://user:pass@platform-pooler-rw.database.svc:5432/dbname"。
限制：资料未提供具体版本要求、资源配额、备份恢复与升级步骤，暂未提供。