K3s 从零部署 CloudNativePG：打造 Homelab 统一 PostgreSQL 平台

前言

在很多 CloudNativePG 教程中，通常只会介绍如何安装 Operator 并创建一个 PostgreSQL 集群。

但在实际 Homelab 场景中，我们更希望：

整个 K3s 集群共用一套 PostgreSQL 服务
支持 Spring Boot 项目
支持 Gitea
支持 Immich
支持未来新增应用
能够通过固定 IP 从局域网访问数据库
保留未来扩容多节点 K3s 的能力

因此本文不只是介绍 CloudNativePG 的安装，而是介绍如何将其建设为 Homelab 的统一 PostgreSQL 平台。

环境说明

K3s 节点

1	192.168.31.215

路由器

小米路由器

DHCP 配置：

1	192.168.31.5 - 192.168.31.229

MetalLB 地址规划

192.168.31.230 postgres
192.168.31.231 ingress
192.168.31.232 gitea
192.168.31.233 argocd
192.168.31.234 grafana

本文中 PostgreSQL 固定使用：

1	192.168.31.230

最终架构

                   家庭局域网

┌──────────────┐
│ MacBook      │
├──────────────┤
│ ThinkPad     │
├──────────────┤
│ DataGrip     │
├──────────────┤
│ Spring Boot  │
└───────┬──────┘
        │
        ▼
 postgres.home.lab
        │
        ▼
  192.168.31.230
        │
     MetalLB
        │
        ▼
  postgres-lb
        │
        ▼
  postgres-rw
        │
        ▼
CloudNativePG

集群外通过 LoadBalancer 访问。

集群内通过 Service DNS 访问。

安装 MetalLB

添加 Helm Repo：

1 2	helm repo add metallb https://metallb.github.io/metallb helm repo update

安装：

1
2
3

helm install metallb metallb/metallb \
  -n metallb-system \
  --create-namespace

确认：

1	kubectl get pods -n metallb-system

NAME                                            READY   STATUS    RESTARTS   AGE
metallb-controller-55846b4849-t2dr7             1/1     Running   0          18h
metallb-frr-k8s-statuscleaner-8bf664555-52sgc   1/1     Running   0          18h
metallb-frr-k8s-w2n6j                           5/5     Running   0          18h
metallb-speaker-bd4fd                           1/1     Running   0          18h

安装完成后创建地址池：

apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: homelab-pool
  namespace: metallb-system
spec:
  addresses:
    - 192.168.31.230-192.168.31.239
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: homelab
  namespace: metallb-system

安装 CloudNativePG

CloudNativePG 提供了一个非常强大的 kubectl 插件，可以帮助你轻松查看数据库状态、进行主备切换、查看日志等。

在你的控制端（或 K3s 节点上）运行以下命令安装：

1	curl -sSfL https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh \| sudo sh -s -- -b /usr/local/bin

如果你是中国用户，你可以使用gh-proxy来加速

1	curl -sSfL https://gh-proxy.com/https://github.com/cloudnative-pg/cloudnative-pg/raw/main/hack/install-cnpg-plugin.sh \| sudo sh -s -- -b /usr/local/bin

验证：

1 2	kubectl cnpg version Build: {Version:1.29.1 Commit:a4060c152 Date:2026-05-08}

使用helm来部署CNPG Operator：

# 添加并更新仓库
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm repo update

# 安装 1.29 对应的 Operator
helm install cnpg-operator cnpg/cloudnative-pg \
  --namespace cnpg-system \
  --create-namespace

使用K3s 从零部署 CloudNativePG：打造 Homelab 统一 PostgreSQL 平台