わたしの部屋

一、背景与集群拓扑#

现有集群由三台 Debian 主机组成，通过 ZeroTier 组成 10.0.0.0/24 二层内网：

本次新增一台 WSL2 主机（Windows 11 + Debian 13），作为第四节点：

备份节点定位（不参与 HA）：

• 10.0.0.20 不安装 Keepalived / HAProxy，不参与 VRRP 竞选，永远不会持有 VIP；
• Patroni 配置 nofailover: true，永不成为数据库 Leader；
• 三台主机的 HAProxy / Keepalived 配置与后端均无需改动，10.0.0.20 不加入任何 HA 后端。

目标：

• WSL2 通过 ZeroTier 加入内网，固定地址 10.0.0.20；
• 部署 K3s Agent 加入现有集群，作为工作节点承载业务负载；
• 部署 PostgreSQL + Patroni 加入现有 HA 集群，作为普通副本（Replica），通过现有 etcd（端口 3379）协调。

二、环境信息#

• 操作系统：Windows 11 + WSL2 Debian 13 (trixie)
• WSL 网络：桥接模式静态 IP 192.168.86.22（宿主局域网）+ ZeroTier 内网 IP 10.0.0.20
• PostgreSQL 版本：17
• Patroni 版本：apt install patroni python3-etcd3 python3-etcd
• ZeroTier 网络 ID：88c5b1f3396eaea0，接口名一般为 ztpp6n6xmz

WSL2 桥接模式、静态 IP、systemd 等前置配置参考《WSL2 桥接模式实战：配置静态 IP、开启 IPv6 与 Systemd 避坑指南》。

三、WSL 环境准备#

1
sudo vim /etc/wsl.conf

1
[boot]
2
systemd=true
3

4
[network]
5
hostname = HyQAQ-WSL
6
generateHosts = false
7
generateResolvConf = false

1
ps -p 1 -o comm=
2
# 输出 systemd 即为成功

1
ip a show eth0
2
# 应看到 192.168.86.22/24 静态地址
3

4
cat /etc/resolv.conf
5
# nameserver 223.5.5.5
6
# nameserver 114.114.114.114

四、加入 ZeroTier 网络#

1
curl -s https://install.zerotier.com | sudo bash
2
sudo systemctl enable --now zerotier-one

1
sudo zerotier-cli join 88c5b1f***6eaea0

1
sudo zerotier-cli listnetworks
2
# ztpp6n6xmz  88c5b1f3396eaea0 ... 10.0.0.20/24 ...
3

4
ip addr show ztpp6n6xmz

1
ping -c 4 10.0.0.10
2
ping -c 4 10.0.0.30
3
ping -c 4 10.0.0.40

五、部署 K3s Agent#

1
sudo cat /var/lib/rancher/k3s/server/node-token

1
curl -sfL https://get.k3s.io | K3S_URL=https://10.0.0.10:6443 K3S_TOKEN="K10xxx::server:xxx" K3S_NODE_IP=10.0.0.20 K3S_NODE_EXTERNAL_IP=10.0.0.20 K3S_FLANNEL_IFACE=ztpp6n6xmz sh -

1
sudo kubectl get nodes

1
NAME            STATUS   ROLES    AGE   VERSION
2
hyperbola-server Ready   control-plane,master ...
3
hyperbola-txy    Ready   control-plane,master ...
4
hyperbola-aly    Ready   control-plane,master ...
5
hyqaq-wsl        Ready   <none>   1m    v1.xx.x

六、部署 etcd、PostgreSQL 与 Patroni#

1
sudo apt update
2
sudo apt install -y etcd-server etcd-client

1
etcdctl --endpoints=http://10.0.0.10:3379 member add etcd-20 --peer-urls=http://10.0.0.20:3380

1
ETCD_NAME="etcd-20"
2
ETCD_INITIAL_CLUSTER="etcd-10=http://10.0.0.10:3380,etcd-30=http://10.0.0.30:3380,etcd-40=http://10.0.0.40:3380,etcd-20=http://10.0.0.20:3380"
3
ETCD_LISTEN_CLIENT_URLS="http://10.0.0.20:3379,http://127.0.0.1:3379"
4
ETCD_LISTEN_PEER_URLS="http://10.0.0.20:3380"
5
ETCD_ADVERTISE_CLIENT_URLS="http://10.0.0.20:3379"
6
ETCD_INITIAL_ADVERTISE_PEER_URLS="http://10.0.0.20:3380"
7

8
ETCD_ENABLE_V2="true"
9
ETCD_DATA_DIR="/var/lib/etcd/default"
10
ETCD_INITIAL_CLUSTER_STATE="existing"
11
ETCD_INITIAL_CLUSTER_TOKEN="pg-cluster-token"

1
sudo systemctl enable --now etcd
2
etcdctl --endpoints=http://10.0.0.20:3379 endpoint health
3
etcdctl --endpoints=http://10.0.0.10:3379,http://10.0.0.20:3379 member list

1
ETCD_INITIAL_CLUSTER="etcd-10=http://10.0.0.10:3380,etcd-30=http://10.0.0.30:3380,etcd-40=http://10.0.0.40:3380,etcd-20=http://10.0.0.20:3380"

1
etcd3:
2
  hosts: 10.0.0.10:3379,10.0.0.30:3379,10.0.0.40:3379,10.0.0.20:3379

1
sudo systemctl reload patroni

1
sudo apt install -y postgresql-17

1
sudo apt install -y patroni python3-etcd3 python3-etcd

1
python3 -c "from patroni.dcs.etcd import Etcd; print('etcd driver OK')"

1
---
2
scope: pg-cluster
3
namespace: /db/
4
name: pg-20
5

6
restapi:
7
  listen: 10.0.0.20:8008
8
  connect_address: 10.0.0.20:8008
9

10
etcd3:
11
  hosts: 10.0.0.10:3379,10.0.0.30:3379,10.0.0.40:3379,10.0.0.20:3379
12

13
bootstrap:
14
  dcs:
15
    ttl: 30
16
    loop_wait: 10
17
    retry_timeout: 10
18
    maximum_lag_on_failover: 1048576
19
    master_start_timeout: 300
20
    synchronous_mode: true
21
    synchronous_mode_strict: false
22
    postgresql:
23
      use_pg_rewind: true
24
      parameters:
25
        max_connections: 200
26
        shared_buffers: 256MB
27
        wal_level: replica
28
        wal_keep_size: 128
29
        max_wal_senders: 10
30
        max_replication_slots: 10
31
        synchronous_commit: "remote_apply"
32
        synchronous_standby_names: "*"
33
  pg_hba:
34
    - local all all trust
35
    - host all all 0.0.0.0/0 md5
36
    - host replication all 0.0.0.0/0 md5
37

38

39
postgresql:
40
  listen: 10.0.0.20:5432
41
  connect_address: 10.0.0.20:5432
42
  data_dir: /var/lib/postgresql/17/main
43
  conf_dir: /etc/postgresql/17/main
44
  bin_dir: /usr/lib/postgresql/17/bin
45
  pgpass: /tmp/pgpass
46
  authentication:
47
    replication:
48
      username: replicator
49
      password: '@512710&Sql'
50
    superuser:
51
      username: postgres
52
      password: '@512710&Sql'
53
  parameters:
54
    unix_socket_directories: '/var/run/postgresql'
55

56
tags:
57
  nofailover: true    # 备份节点，永不参与选主，不能成为 Leader
58
  clonefrom: false
59
  failover-priority: 10

1
sudo systemctl stop patroni postgresql 2>/dev/null
2
sudo pkill -9 -u postgres
3
sudo rm -rf /var/lib/postgresql/17/main
4
sudo -u postgres mkdir -p /var/lib/postgresql/17/main
5
sudo chmod 700 /var/lib/postgresql/17/main   # PG 要求 0700/0750，否则启动失败
6

7
sudo systemctl daemon-reload
8
sudo systemctl enable --now patroni

七、接入 HA：三台主机无需任何调整#

10.0.0.20 的定位是纯备份节点：不承接任何业务流量，不能成为数据库 Leader，也不能成为 VIP 节点。因此：

• HA/Keepalived 仍由原有三台主机（10.0.0.10、10.0.0.30、10.0.0.40）承担，10.0.0.20 不安装 Keepalived 与 HAProxy，不参与 VRRP 竞选；
• 三台主机的 HAProxy 后端完全不动，pg_write、pg_read、k3s_servers 均不加入 10.0.0.20；
• 三台主机的 Keepalived 配置完全不动，VIP 10.0.0.100 只会在三台之间漂移，永远不会到 10.0.0.20。

WARNING

为什么不在 pg_read 后端加 pg20？

客户端只通过 VIP 10.0.0.100:5433 访问读库，而 VIP 只存在于三台主机的 Keepalived 上。10.0.0.20 作为纯备份节点，平时不承接任何流量，加入读库后端反而会让只读请求分担到一台随时可能因 WSL 睡眠而掉线的节点上，得不偿失。

20 的价值在于：主链路整体故障时可手动拉起恢复，而非自动承接流量。

因此本步骤三台主机无需任何改动，保持原有 HA 配置即可。

八、验证集群状态#

1
sudo patronictl -c /etc/patroni/config.yml list

1
+ Cluster: pg-cluster (...) ----+----+-----------+------------------------+
2
| Member | Host      | Role      | State     | TL | Lag in MB | Tags      |
3
+--------+-----------+-----------+-----------+----+-----------+------------+
4
| pg-10  | 10.0.0.10 | Leader    | running   |  1 |           | prio: 100 |
5
| pg-30  | 10.0.0.30 | Replica   | streaming |  1 |         0 | prio: 50  |
6
| pg-40  | 10.0.0.40 | Replica   | streaming |  1 |         0 | prio: 0   |
7
| pg-20  | 10.0.0.20 | Replica   | streaming |  1 |         0 | prio: 10  |
8
+--------+-----------+-----------+-----------+----+-----------+------------+

1
sudo kubectl get nodes
2
sudo kubectl get pods -A -o wide

1
# 在 10.0.0.10 主库
2
psql -h 10.0.0.10 -U postgres -c "CREATE TABLE IF NOT EXISTS test(id int); INSERT INTO test VALUES (1);"
3

4
# 在 10.0.0.20 副本
5
psql -h 10.0.0.20 -U postgres -c "SELECT * FROM test;"

九、踩坑记录#

1. WSL 必须启用 systemd
   若不设置 systemd=true，K3s 与 Patroni 都无法以 systemd 服务方式运行，systemctl 会报 System has not been booted with systemd as init system。

2. Patroni 依赖 ZeroTier 接口的启动顺序
   与集群中 etcd 的问题类似，若 Patroni/PostgreSQL 绑定 10.0.0.20 而 ZeroTier 尚未分配该 IP，会报 cannot assign requested address。在服务文件中添加依赖：

   1
   After=zerotier-one.service network-online.target
   2
   Requires=zerotier-one.service

3. Flannel 接口必须与集群一致
   K3s Agent 的 flannel-iface 若与现有节点不同（集群使用 host-gw 后端），Pod 间通信异常。

4. WSL 存在双 IP
   桥接静态 IP（192.168.86.22）与 ZeroTier IP（10.0.0.20）并存。集群内一律使用 10.0.0.20，Patroni 的 connect_address 不能写成 192.168.86.22，否则其他节点无法回连。

5. PostgreSQL 使用 0.0.0.0 监听
   若需同时接受桥接网段与 ZeroTier 网段的连接，可让 PostgreSQL 监听 0.0.0.0，但 Patroni 的 connect_address 仍必须指向 10.0.0.20。

6. etcd 对等端口配置错误导致 Cluster ID Mismatch
   etcd-20 加入集群时报错，member list 中该节点一直处于 unstarted。故障原因有两层：

   • 对等端口配置错误：集群初始元数据中记录的 etcd-20 节点对等通信端口为默认的 2380，而实际配置文件使用的是 3380，导致节点无法与其他成员建立内部通信。
   • 集群 ID 不匹配（Cluster ID Mismatch）：由于上述网络不通，etcd-20 启动时未能成功加入现有集群，而是基于本地残留的旧数据，自行初始化了一个全新的单节点集群。这导致它与其他三个节点拥有完全不同的集群 ID，从而被集群拒绝。

   恢复步骤：

   1
   # 1. 在健康节点上移除错误成员
   2
   etcdctl --endpoints=http://10.0.0.10:3379 member remove <错误memberID>
   3
   
   4
   # 2. 重新添加成员，指定正确的对等地址（端口 3380）
   5
   etcdctl --endpoints=http://10.0.0.10:3379 member add etcd-20 --peer-urls=http://10.0.0.20:3380
   6
   
   7
   # 3. 在故障节点（10.0.0.20）上停止服务并清理旧数据
   8
   sudo systemctl stop etcd
   9
   sudo rm -rf /var/lib/etcd/default
   10
   
   11
   # 4. 确认配置中 ETCD_INITIAL_CLUSTER_STATE="existing"，重启并验证
   12
   sudo systemctl start etcd
   13
   etcdctl --endpoints=http://10.0.0.20:3379 endpoint health
   14
   etcdctl --endpoints=http://10.0.0.10:3379,http://10.0.0.20:3379 member list

   member list 中该节点状态应变为 started，集群恢复健康。

   TIP

   member add 的输出会给出 ETCD_INITIAL_CLUSTER 与新的成员 ID，务必保存并严格按输出配置 ETCD_INITIAL_CLUSTER_STATE="existing"。一旦以错误端口/旧数据启动过，先 member remove + 清理数据目录再重来，不要直接叠加。

7. 二次踩坑：AI 重构步骤时”掐头去尾”，遗漏关键配置导致 Cluster ID Mismatch 复现
   明明旧文档踩坑记录里已经写过 Cluster ID Mismatch，实际部署时还是再次踩坑，且根因不止一个。原因是：用 AI 重构部署步骤时，将配置”掐头去尾”了——只保留了看起来”核心”的部分，遗漏了与现有集群保持一致的关键项。

   本次复现的实际故障链（三层）：

   • etcd 旧数据残留（Cluster ID Mismatch）：20 的 etcd 数据目录 /var/lib/etcd/default 里残留了之前以错误端口初始化的单节点集群数据（cluster-id 16f1bc0c8e86d48e），与主集群 cluster-id（7667324251917980557）不符。etcd 启动后恢复本地旧数据，被主集群以 rejected Raft message to mismatch member 拒绝，随后正常退出（日志是 Deactivated successfully，非崩溃，极具迷惑性）。

   • Patroni 误用 etcd: 后端而非 etcd3:：这是最隐蔽的一层。集群其他节点（如 txy）的配置用的是 etcd3:（Patroni 走 etcd v3 API），而重构后的 20 配置用的是 etcd:（Patroni 默认走 etcd v2 API）。主集群的 etcd 虽开启 ETCD_ENABLE_V2="true"，但 v2 API 下 /db/pg-cluster/ 只有 members 和 initialize，读不到 leader、config、status。于是 20 的 Patroni 能连上 etcd、却认为集群从未初始化，一直卡在 waiting for leader to bootstrap（Lock owner: None），甚至报出与主集群不同的 cluster ID。

   • 数据目录权限（附带）：重建 /var/lib/postgresql/17/main 时默认权限 755，PostgreSQL 要求 0700/0750，导致 PG 启动 FATAL: data directory has invalid permissions。

   排查过程关键命令：

   1
   # 1. 先看 etcd 成员状态 —— 发现 20 是 unstarted
   2
   etcdctl --endpoints=http://10.0.0.10:3379,http://10.0.0.30:3379,http://10.0.0.40:3379 member list
   3
   # → db828958631541e5, unstarted, , http://10.0.0.20:3380
   4
   
   5
   # 2. 看 20 的 etcd 启动日志 —— 发现本地旧数据 + mismatch
   6
   journalctl -u etcd -n 30 --no-pager
   7
   # → server has been already initialized / cluster-id 16f1bc0c...
   8
   # → rejected Raft message to mismatch member / Deactivated successfully
   9
   
   10
   # 3. 对比正常节点（txy）的 Patroni 配置 —— 发现 etcd3: vs etcd:
   11
   sudo cat /etc/patroni/config.yml   # 正常节点用 etcd3:
   12
   
   13
   # 4. v2 vs v3 视角对比 etcd 数据 —— 确认 v2 读不到 leader/config/status
   14
   etcdctl --endpoints=http://10.0.0.20:3379 get /db --prefix --keys-only   # v3，数据完整
   15
   ETCDCTL_API=2 etcdctl --endpoints=http://10.0.0.20:3379 ls /db/pg-cluster/   # v2，只有 members/initialize

   修复步骤（按顺序）：

   1
   # 1. 停服务
   2
   sudo systemctl stop patroni
   3
   sudo systemctl stop etcd
   4
   
   5
   # 2. 清空 etcd 旧数据（Cluster ID Mismatch 根因）
   6
   sudo mv /var/lib/etcd/default /var/lib/etcd/default.bak
   7
   sudo mkdir -p /var/lib/etcd/default && sudo chown etcd:etcd /var/lib/etcd/default
   8
   
   9
   # 3. 启动 etcd，确认成员 started
   10
   sudo systemctl start etcd
   11
   etcdctl --endpoints=http://10.0.0.20:3379 endpoint health
   12
   
   13
   # 4. 修正 Patroni 配置：etcd: → etcd3:，补齐 bootstrap.dcs / conf_dir / retry_timeout
   14
   sudo tee /etc/patroni/config.yml << 'EOF'
   15
   # ... 与正常节点完全对齐：etcd3: + bootstrap.dcs + postgresql.conf_dir 等
   16
   EOF
   17
   
   18
   # 5. 修正数据目录权限（PG 要求 0700/0750）
   19
   sudo chmod 700 /var/lib/postgresql/17/main
   20
   sudo chown -R postgres:postgres /var/lib/postgresql/17/main
   21
   
   22
   # 6. 启动 patroni，从 Leader 自动 pg_basebackup 加入
   23
   sudo systemctl start patroni
   24
   sudo patronictl -c /etc/patroni/config.yml list
   25
   # → pg-20 Replica running, TL 24, Lag 0 MB

   IMPORTANT

   教训：新增节点的配置必须与现有集群节点”逐字段对齐”，而不是凭印象重写。 Patroni 的 DCS 后端（etcd3: vs etcd:）、bootstrap.dcs、postgresql.conf_dir、端口、token 等任何一个被”掐头去尾”地省略，都会导致节点无法正确加入集群，且报错极具迷惑性（etcd 正常退出、Patroni 卡 bootstrap、cluster ID 不同）。部署新节点前，务必 ssh 现有节点 cat /etc/patroni/config.yml 逐项对比。

8. 集群故障转移后副本 timeline 冲突：requested timeline is not a child of this server's history
   现象：主集群发生故障转移（原 Leader pg-10 宕机，Leader 漂移到 pg-40）后，备份节点 pg-20 的 Patroni 反复 start failed，日志报：

   1
   FATAL:  requested timeline 25 is not a child of this server's history
   2
   DETAIL:  Latest checkpoint is at 0/15000028 on timeline 24, but in the history of the requested timeline, the server forked off from that timeline at 0/140002B0.

   原因：集群在 failover 时发生了 timeline 分支（新 Leader 在旧 timeline 上分叉）。pg-20 本地残留旧 timeline 的历史记录，与新的复制时间线不匹配，无法直接从旧位置继续流复制。

   解决：清空数据目录，让 Patroni 从当前 Leader 重新 pg_basebackup 全量同步：

   1
   sudo systemctl stop patroni
   2
   sudo rm -rf /var/lib/postgresql/17/main
   3
   sudo -u postgres mkdir -p /var/lib/postgresql/17/main
   4
   sudo chmod 700 /var/lib/postgresql/17/main
   5
   sudo systemctl start patroni
   6
   # 日志应出现：trying to bootstrap from leader 'pg-XX' → in progress
   7
   sudo patronictl -c /etc/patroni/config.yml list
   8
   # → pg-20 Replica streaming, 0 lag

   IMPORTANT

   备份节点/副本遇到 timeline 分支，直接清空数据重新全量同步是最可靠的修复。 集群发生 failover 后，任何副本都可能因 timeline 分叉而无法增量追赶，pg_basebackup 重建是标准做法。同理，备份节点也要配合验证数据完整性。

十、总结#

通过 ZeroTier，WSL2 主机顺利加入了既有高可用集群：

• K3s Agent 作为工作节点，接入现有控制面，可承载业务负载；
• Patroni + PostgreSQL 作为 Replica，通过现有 etcd 协调并实时从 Leader 流复制，nofailover: true + failover-priority 低位确保其永不成为 Leader；
• 接入 HA：三台主机的 HAProxy / Keepalived 完全不变，10.0.0.20 不加入任何后端、不安装 HA/Keepalived，永不持有 VIP。

至此，集群从三节点扩展为四节点。10.0.0.20 作为纯备份节点定位明确：不承接任何业务流量，不参与数据库选主，也不参与 VIP 竞选，仅在主链路整体故障时手动拉起恢复，故障时不影响主链路高可用。