单节点部署

K3s 高可用集群实操笔记：3 Master + 外部 PostgreSQL-15 部署全流程

本文档为“3个Master节点+外部PostgreSQL-15”架构的K3s高可用集群部署指南，包含核心优势解析、环境配置、实操步骤，优化后更突出逻辑层级与关键信息，便于快速查阅与执行。

一、核心优势解析

1. 外部PostgreSQL-15优势

采用外部PostgreSQL-15作为K3s后端数据存储，替代默认的内置etcd或SQLite，核心价值体现在以下三点：

• 数据解耦与独立存活：控制平面（Master节点）与数据存储分离，即使所有Master节点临时故障，数据库数据不会丢失，集群恢复仅需重新连接数据库。
• 更高数据可靠性：支持主从复制、定时备份、故障自动切换，规避内置存储（如单节点etcd）的“数据单点风险”，满足生产环境对数据一致性的要求。
• 运维扩展更灵活：数据库可单独进行性能优化、扩容或升级，无需重启K3s集群；同时兼容专业数据库运维工具，便于监控、备份与故障排查。

2. 3个Master节点集群优势

3个Master节点是K3s高可用控制平面的标准配置，核心围绕“冗余”与“高可用”设计：

• 避免控制平面单点故障：满足分布式系统“奇数选主”机制（K3s HA基于Raft协议），任意1个Master节点故障，剩余2个节点仍能正常提供API服务、调度Pod，集群不中断。
• 分担控制平面负载：API Server、Controller Manager等组件自动负载均衡，3个节点分摊请求压力，支持更多Worker节点与Pod的管理（优于单Master/双Master架构）。
• 故障恢复更高效：故障Master节点修复后，可通过PostgreSQL统一存储自动同步数据，快速回归集群，无需手动重建控制平面。

二、实践环境信息

先决条件

两个节点不能具有相同的主机名。

如果多个节点将具有相同的主机名，或者如果主机名可能被自动配置系统重用，请使用–with-node-id选项为每个节点附加随机后缀，或设计一个唯一名称，使用–node-name或$K3S_NODE_NAME传递给您添加到集群的每个节点。

或是按照本教程对服务器进行标志

三、前置准备（所有服务器执行）

需完成服务器重命名与Hosts解析配置，确保节点间通信正常。

1. 服务器重命名

分别在对应节点执行以下命令，设置节点 hostname：

• K3s-Master-1：hostnamectl set-hostname K3s-Master-1
• K3s-Master-2：hostnamectl set-hostname K3s-Master-2
• K3s-Master-3：hostnamectl set-hostname K3s-Master-3
• PostgreSQL服务器：hostnamectl set-hostname pgsql-server

2. 添加Hosts解析

所有节点执行 vim /etc/hosts，添加以下内容（实现节点间通过 hostname 通信）：

1
2
3
4

192.168.66.142  K3s-Master-1
192.168.66.151  K3s-Master-2
192.168.66.152  K3s-Master-3
192.168.66.150  pgsql-server

四、PostgreSQL数据库部署（仅在pgsql-server节点执行）

采用Docker Compose部署PostgreSQL-15，需先确保节点已安装Docker与Docker Compose。

1. 编写Docker Compose文件

创建 docker-compose.yml 文件，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

version: '3'
services:
  postgres:
    image: postgres:15
    container_name: postgres_15  # 容器名称，便于管理
    volumes:
      - /docker/data/postgresql15/data:/var/lib/postgresql/data  # 数据持久化目录
    environment:
      POSTGRES_USER: root        # 数据库初始用户名
      POSTGRES_DB: postgres      # 初始数据库名称
      POSTGRES_PASSWORD: 202019.Lv  # 初始密码（建议生产环境修改为复杂密码）
    ports:
      - "5433:5432"  # 端口映射：主机5433端口 -> 容器5432端口
    restart: always  # 容器异常退出时自动重启

使用docker-compose up -d启动命令，如果你还没配置远程连接那么还需

1

vim /docker/data/postgresql15/data/pg_hba.conf

listen_addresses = ‘‘ # 默认为’localhost’，修改为’‘

1

vim /docker/data/postgresql15/data/pg_hba.conf

格式：host 数据库名 用户名 来源IP 认证方式

host all all 0.0.0.0/0 md5

2. 启动PostgreSQL容器

执行以下命令启动容器，并检查运行状态：

1
2
3
4
5

# 启动容器（后台运行）
docker-compose up -d

# 检查容器运行状态
docker ps | grep postgres_15

3. 创建K3s专用数据库与用户

进入PostgreSQL容器，执行SQL语句创建K3s所需的数据库（k3sdb）与用户（k3s）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 进入PostgreSQL容器
docker exec -it postgres_15 psql -U root -d postgres

# 执行SQL语句（复制以下内容到容器内执行）
CREATE USER k3s WITH PASSWORD '202019';

CREATE DATABASE k3sdb 
  OWNER k3s 
  ENCODING 'UTF8' 
  LC_COLLATE 'en_US.UTF-8' 
  LC_CTYPE 'en_US.UTF-8' 
  TEMPLATE template0; 

GRANT ALL PRIVILEGES ON DATABASE k3sdb TO k3s;

# 退出容器
\q

五、初始化K3s集群（Master节点执行）

需按顺序初始化Master-1（作为集群初始节点），再加入Master-2与Master-3，所有节点均需连接外部PostgreSQL数据库。

1. 初始化Master-1节点

提供在线安装与离线安装两种方式，选择一种执行即可。

方式1：在线安装（需联网，自动下载K3s二进制文件）

1
2

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -s - server \
  --datastore-endpoint "postgres://root:202019.Lv@192.168.66.163:5433/k3sdb?sslmode=disable"

方式2：离线安装（适用于无外网环境，需提前下载K3s二进制文件）

1. 将提前下载的k3s二进制文件上传至Master-1节点，执行以下命令：

   1 2 3 4 5 6 7 8 9 10 11 12 13

   # 复制K3s文件到系统目录并赋予执行权限 cp ./k3s /usr/local/bin/k3s chmod +x /usr/local/bin/k3s # 跳过自动下载（因已手动提供K3s文件） export INSTALL_K3S_SKIP_DOWNLOAD=true # 初始化Master-1（参数与在线安装一致） curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn bash -s - server \ --datastore-endpoint "postgres://root:202019.Lv@192.168.66.150:5433/k3sdb?sslmode=disable" \ --token "202019" \ --disable traefik \ --write-kubeconfig-mode 644

配置Master-1环境变量（便于使用kubectl命令）

1
2
3
4
5
6
7
8

# 创建kubectl配置目录
mkdir -p $HOME/.kube

# 复制K3s默认配置文件到用户目录
sudo cp /etc/rancher/k3s/k3s.yaml $HOME/.kube/config

# 赋予当前用户配置文件权限
sudo chown $(id -u):$(id -g) $HOME/.kube/config

2. 加入Master-2节点（指向Master-1初始化）

方式1：在线安装

1
2
3
4

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | bash -s - server \
  --datastore-endpoint "postgres://root:202019.Lv@192.168.66.150:5433/k3sdb?sslmode=disable" \
  --token "202019" \
  --server "https://192.168.66.142:6443"  # 指向Master-1的API地址

方式2：离线安装（需提前上传k3s二进制文件与对应的hash文件，hash文件用于校验完整性）

1
2
3
4
5
6
7
8
9
10
11
12

# 复制K3s文件并赋予权限
cp ./k3s /usr/local/bin/k3s
chmod +x /usr/local/bin/k3s

# 跳过自动下载
export INSTALL_K3S_SKIP_DOWNLOAD=true

# 加入集群（参数与在线安装一致）
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | bash -s - server \
  --datastore-endpoint "postgres://root:202019.Lv@192.168.66.150:5433/k3sdb?sslmode=disable" \
  --token "202019" \
  --server "https://192.168.66.142:6443"

配置Master-2环境变量

1
2
3

mkdir -p $HOME/.kube
sudo cp /etc/rancher/k3s/k3s.yaml $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

3. 加入Master-3节点（指向Master-1初始化）

方式1：在线安装

1
2
3
4
5
6

curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | sh -s - server \
  --datastore-endpoint "postgres://root:202019.Lv@192.168.66.150:5433/k3sdb?sslmode=disable" \
  --token "202019" \
  --server "https://192.168.66.142:6443" \
  --disable traefik \
  --write-kubeconfig-mode 644

方式2：离线安装

1
2
3
4
5
6
7
8
9
10
11
12

# 复制K3s文件并赋予权限
cp ./k3s /usr/local/bin/k3s
chmod +x /usr/local/bin/k3s

# 跳过自动下载
export INSTALL_K3S_SKIP_DOWNLOAD=true

# 加入集群
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | bash -s - server \
  --datastore-endpoint "postgres://root:202019.Lv@192.168.66.150:5433/k3sdb?sslmode=disable" \
  --token "202019" \
  --server "https://192.168.66.142:6443"

配置Master-3环境变量

1
2
3

mkdir -p $HOME/.kube
sudo cp /etc/rancher/k3s/k3s.yaml $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

六、集群状态验证（任意Master节点执行）

执行以下命令查看所有Master节点状态，若均为Ready则表示集群初始化成功：

1

k3s kubectl get nodes