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 地址规划

1
2
3
4
5
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

最终架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
                   家庭局域网

┌──────────────┐
│ 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
1
2
3
4
5
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

安装完成后创建地址池：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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：

1
2
3
4
5
6
7
8
# 添加并更新仓库
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

创建 PostgreSQL 集群