cnpg-database

CNPG 数据库管理

架构概览

所有集群都位于 database 命名空间中。共享平台集群（platform-0/1/2）为每个应用使用 spec.managed.roles + Database CRD，并在 platform-pooler-rw.database.svc 提供 PgBouncer pooler。专用集群（例如 Immich）通过 initdb 引导自己的数据库和属主。两种情况下，凭据都通过 kubernetes-replicator 复制到消费方应用命名空间。

决策树：共享集群 vs 专用集群

标准工作负载，无特殊扩展 → 共享集群（platform-pooler-rw.database.svc） 需要自定义扩展（vector、PostGIS）或隔离 → 使用自定义 imageName 的专用集群 不确定 → 先从共享集群开始，如有需要再迁移

---

关键文件（共享集群）

位置：kubernetes/platform/config/database/

文件	用途
cluster.yaml	带 spec.managed.roles 的 CNPG Cluster CR
databases.yaml	Database CRD（每个应用数据库一个）
role-secrets.yaml	按角色划分的密码 Secret（secret-generator + replicator）
pooler.yaml	PgBouncer Pooler（platform-pooler-rw）
superuser-secret.yaml	自动生成的超级用户密码（仅 database 命名空间）
prometheus-rules.yaml	CNPG 专用的 PrometheusRules

清单示例见 references/cluster-reference.md。

---

工作流：为新应用添加数据库（共享集群）

步骤 1-3 编辑 kubernetes/platform/config/database/ 中的文件。步骤 4-5 在应用的集群配置中完成。

步骤 1：添加受管角色到 cluster.yaml 的 spec.managed.roles。模板见 references/cluster-reference.md。

步骤 2：创建角色密码 Secret到 role-secrets.yaml。模板见 references/credentials.md。

步骤 3：创建 Database CRD到 databases.yaml。模板见 references/cluster-reference.md。

注意：具有多个数据库的应用（sonarr-main、sonarr-log）共享一个角色；使用相同的 owner 创建单独的 Database CR。

步骤 4：创建凭据副本到 kubernetes/clusters/<cluster>/config/<app>/。模板见 references/credentials.md。

步骤 5：添加网络策略访问标签 access.network-policy.homelab/postgres: "true" 到 kubernetes/platform/namespaces.yaml 中的命名空间条目。

步骤 6：注册凭据副本到应用的 kustomization.yaml。

凭据链图示见 references/credentials.md。

---

工作流：创建专用 CNPG 集群

当应用需要自定义 PostgreSQL 扩展或性能/数据隔离时使用。

步骤 1：定义集群，位于 kubernetes/clusters/<cluster>/config/<app>/<app>-cluster.yaml。设置 inheritedMetadata 以允许复制自动生成的应用 secret。完整的清单示例参见 references/cluster-reference.md。

与共享集群的关键区别：

特性	共享	专用
位置	kubernetes/platform/config/database/	kubernetes/clusters/<cluster>/config/<app>/
镜像	标准 PostgreSQL	带扩展的自定义镜像
角色管理	spec.managed.roles + Database CRD	bootstrap.initdb 创建数据库和所有者
凭据来源	<app>-role-password（secret-generator）	<app>-database-app（CNPG 自动生成）
inheritedMetadata	不需要	复制 secret 所必需

步骤 2：复制应用凭据到消费者命名空间。CNPG 会自动在 database 中生成 <cluster-name>-app。inheritedMetadata 注解启用复制。模板参见 references/credentials.md。

实际示例：kubernetes/clusters/live/config/immich/database-secret-replication.yaml

步骤 3： 将 access.network-policy.homelab/postgres: "true" 标签添加到应用命名空间，并在 kustomization.yaml 中注册所有文件。

---

监控

Cluster 和 Pooler 都设置了 monitoring.enablePodMonitor: true —— Prometheus 会自动发现它们。无需手动配置 ServiceMonitor。

CNPG 告警位于 kubernetes/platform/config/database/prometheus-rules.yaml：

告警	条件	严重程度
CNPGClusterNotHealthy	cnpg_pg_replication_streaming == 0	critical
CNPGClusterHighConnections	连接使用率 > max_connections 的 80%	warning
CNPGInstanceNotReady	副本 WAL 接收器宕机	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	OOM 或配置错误	检查 kubectl logs，增加内存限制
应用无法连接	缺少网络策略	添加 access.network-policy.homelab/postgres: "true"
应用无法连接	Secret 未复制	检查源 secret 上的复制注解
复制后 Secret 为空	源命名空间错误	验证 replicate-from 指向正确的 <ns>/<name>
找不到扩展	镜像错误	验证 imageName 是否包含该扩展
数据库未创建	缺少 Database CRD	将 Database CR 添加到 databases.yaml
角色未创建	managed.roles 中缺失	将角色条目添加到 cluster.yaml
角色密码不匹配	Secret 未重新生成	删除 role-password secret；secret-generator 会重新创建它

手动连通性测试：kubectl run -n <app-ns> pg-test --rm -it --image=postgres:17 -- psql "postgresql://user:[email protected]:5432/dbname"

---

交叉引用

文档	相关性
references/cluster-reference.md	Cluster CRD 字段与完整清单示例
references/credentials.md	凭证链示意图与密钥模板
scripts/check-connection.sh	结构化健康检查命令
secrets skill	secret-generator、ExternalSecret 与复制模式
deploy-app skill	端到端部署，包括数据库设置
kubernetes/platform/config/CLAUDE.md	配置子系统与 CRD 依赖模式