使用K3s 搭建K8S集群保姆级教学

一、架构概览

二、环境准备（所有节点）

[2.1 系统配置](#2.1 系统配置)

[关闭 Swap](#关闭 Swap)

配置时间同步

配置主机名（各节点分别执行）

[配置 /etc/hosts](#配置 /etc/hosts)

[2.2 防火墙与内核参数](#2.2 防火墙与内核参数)

放行必要端口（或直接关闭防火墙）

内核参数

[三、安装 K3s（HA 模式）](#三、安装 K3s（HA 模式）)

[3.1 在线安装（有外网访问）](#3.1 在线安装（有外网访问）)

[第一步：安装 master-1（集群初始化节点）](#第一步：安装 master-1（集群初始化节点）)

[第二步：验证 master-1 就绪](#第二步：验证 master-1 就绪)

[第三步：加入 master-2](#第三步：加入 master-2)

[第四步：加入 worker-1 和 worker-2](#第四步：加入 worker-1 和 worker-2)

[3.2 离线安装（无外网）](#3.2 离线安装（无外网）)

[四、配置 kubectl 访问](#四、配置 kubectl 访问)

[4.1 本地访问（在 master 节点上）](#4.1 本地访问（在 master 节点上）)

[4.2 远程访问（从运维机访问）](#4.2 远程访问（从运维机访问）)

五、验证集群状态

[5.1 基础检查](#5.1 基础检查)

[5.2 HA 故障转移测试](#5.2 HA 故障转移测试)

六、迁移现有工作负载

[6.1 导出现有资源](#6.1 导出现有资源)

[6.2 为支付业务添加反亲和性](#6.2 为支付业务添加反亲和性)

[6.3 配置 PodDisruptionBudget（PDB）](#6.3 配置 PodDisruptionBudget（PDB）)

[6.4 应用资源到新集群](#6.4 应用资源到新集群)

[七、与现有 Prometheus 集成](#七、与现有 Prometheus 集成)

[7.1 K3s metrics 接口](#7.1 K3s metrics 接口)

[7.2 更新 Prometheus 配置](#7.2 更新 Prometheus 配置)

[7.3 关键告警规则（新增）](#7.3 关键告警规则（新增）)

八、常用运维命令

[8.1 集群管理](#8.1 集群管理)

[8.2 K3s 服务管理](#8.2 K3s 服务管理)

[8.3 升级 K3s](#8.3 升级 K3s)

附录：常见问题排查

4 台 8H16G 服务器 | 双 Master HA | 2 Worker 节点

|----------|------------------------------|
| 适用版本 | K3s v1.29+ |
| 操作系统 | Ubuntu 22.04 LTS / CentOS 7+ |
| 更新日期 | 2026年4 月 |

一、架构概览

本方案采用 2 Master + 2 Worker 的高可用架构，适合聚合支付场景对可用性和资源利用率的双重要求。

节点	角色	IP （示例）	规格	说明
master-1	Control Plane + etcd	192.168.1.10	8H16G	主控节点，现有机器
master-2	Control Plane + etcd	192.168.1.11	8H16G	副控节点，新增机器
worker-1	Worker	192.168.1.12	8H16G	业务负载节点
worker-2	Worker	192.168.1.13	8H16G	业务负载节点

|---------------|-------------------------------------------------------------------------------------------------------|
| 💡 说明 | K3s HA 模式使用 embedded etcd（内置 etcd），3 个以上奇数 master 节点才能保证选主。本方案 2 master 为最小 HA 配置，生产环境建议扩展至 3 master。 |

二、环境准备（所有节点）

以下操作需要在全部 4 台服务器上执行，建议使用 root 用户或 sudo 权限。

2.1 系统配置

关闭 Swap

|----------------------------------------------------|
| # 临时关闭 |
| swapoff -a |
| |
| # 永久关闭（注释 /etc/fstab 中的 swap 行） |
| sed -i '/ swap / s/^$.*$$/#\1/g' /etc/fstab |

配置时间同步

|-----------------------------------------------------------|
| # Ubuntu |
| apt install -y chrony && systemctl enable chrony --now |
| |
| # CentOS |
| yum install -y chrony && systemctl enable chronyd --now |

配置主机名（各节点分别执行）

|-----------------------------------|
| # master-1 |
| hostnamectl set-hostname master-1 |
| |
| # master-2 |
| hostnamectl set-hostname master-2 |
| |
| # worker-1 |
| hostnamectl set-hostname worker-1 |
| |
| # worker-2 |
| hostnamectl set-hostname worker-2 |

配置 /etc/hosts

|------------------------------|
| cat >> /etc/hosts << EOF |
| 192.168.1.10 master-1 |
| 192.168.1.11 master-2 |
| 192.168.1.12 worker-1 |
| 192.168.1.13 worker-2 |
| EOF |

2.2 防火墙与内核参数

放行必要端口（或直接关闭防火墙）

端口	协议	节点	用途
6443	TCP	Master	API Server
2379-2380	TCP	Master	etcd 集群通信
10250	TCP	所有节点	Kubelet API
8472	UDP	所有节点	Flannel VXLAN 覆盖网络
51820	UDP	所有节点	WireGuard（可选加密）
30000-32767	TCP/UDP	Worker	NodePort 服务

|---------------------------------------------------|
| # Ubuntu（ufw） |
| ufw allow 6443/tcp && ufw allow 2379:2380/tcp |
| ufw allow 10250/tcp && ufw allow 8472/udp |
| ufw allow 30000:32767/tcp |
| |
| # CentOS（firewalld） |
| firewall-cmd --permanent --add-port=6443/tcp |
| firewall-cmd --permanent --add-port=2379-2380/tcp |
| firewall-cmd --permanent --add-port=10250/tcp |
| firewall-cmd --permanent --add-port=8472/udp |
| firewall-cmd --reload |

内核参数

|-----------------------------------------|
| cat > /etc/sysctl.d/k3s.conf << EOF |
| net.bridge.bridge-nf-call-iptables = 1 |
| net.bridge.bridge-nf-call-ip6tables = 1 |
| net.ipv4.ip_forward = 1 |
| EOF |
| |
| sysctl --system |

三、安装 K3s（HA 模式）

|---------------|----------------------------------------------|
| ⚠️ 注意 | 生产环境建议提前下载安装包，避免在线安装受网络影响。以下提供在线安装和离线安装两种方式。 |

3.1 在线安装（有外网访问）

第一步：安装 master-1（集群初始化节点）

|-------------------------------------|
| # K3S_TOKEN 自行设置一个强密码，后续节点加入时需要 |
| curl -sfL https://get.k3s.io | \ |
| K3S_TOKEN=your_strong_token_here \ |
| sh -s - server \ |
| --cluster-init \ |
| --tls-san 192.168.1.10 \ |
| --tls-san 192.168.1.11 \ |
| --write-kubeconfig-mode 644 |

|-----------------|------------------------------------------------------------------------------------|
| 💡 参数说明 | --cluster-init 初始化 embedded etcd，--tls-san 将两个 master IP 加入证书 SAN（切换 VIP 时无需重新签证书） |

第二步：验证 master-1 就绪

|-------------------------------|
| # 等待 K3s 启动（约 30 秒） |
| systemctl status k3s |
| |
| # 查看节点状态（应显示 Ready） |
| kubectl get nodes |
| |
| # 查看集群健康 |
| kubectl get componentstatuses |

第三步：加入 master-2

|--------------------------------------|
| # 在 master-2 上执行 |
| curl -sfL https://get.k3s.io | \ |
| K3S_TOKEN=your_strong_token_here \ |
| K3S_URL=https://192.168.1.10:6443 \ |
| sh -s - server \ |
| --tls-san 192.168.1.10 \ |
| --tls-san 192.168.1.11 \ |
| --write-kubeconfig-mode 644 |

第四步：加入 worker-1 和 worker-2

|--------------------------------------|
| # 在 worker-1、worker-2 上分别执行 |
| curl -sfL https://get.k3s.io | \ |
| K3S_TOKEN=your_strong_token_here \ |
| K3S_URL=https://192.168.1.10:6443 \ |
| sh -s - agent |

3.2 离线安装（无外网）

适合内网生产环境，步骤如下：

在有外网的机器下载安装包：

|---------------------------------------------------------------------------------------------------|
| # 下载安装脚本 |
| curl -sfL https://get.k3s.io -o install.sh |
| |
| # 下载 K3s 二进制（选择对应架构） |
| wget https://github.com/k3s-io/k3s/releases/download/v1.29.4+k3s1/k3s |
| |
| # 下载镜像包 |
| wget https://github.com/k3s-io/k3s/releases/download/v1.29.4+k3s1/k3s-airgap-images-amd64.tar.zst |

将文件传输到各目标服务器后执行：

|-----------------------------------------------------------------------|
| # 放置镜像包 |
| mkdir -p /var/lib/rancher/k3s/agent/images/ |
| cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/ |
| |
| # 放置二进制 |
| cp k3s /usr/local/bin/k3s && chmod +x /usr/local/bin/k3s |
| |
| # 离线模式安装（master-1） |
| INSTALL_K3S_SKIP_DOWNLOAD=true \ |
| K3S_TOKEN=your_strong_token_here \ |
| bash install.sh server --cluster-init \ |
| --tls-san 192.168.1.10 --tls-san 192.168.1.11 |

四、配置 kubectl 访问

4.1 本地访问（在 master 节点上）

|--------------------------------------------------------------------|
| # K3s 自动写入 kubeconfig |
| export KUBECONFIG=/etc/rancher/k3s/k3s.yaml |
| |
| # 或者添加到 .bashrc |
| echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc |
| source ~/.bashrc |
| |
| # 验证 |
| kubectl get nodes -o wide |

4.2 远程访问（从运维机访问）

|-----------------------------------------------------------------|
| # 将 kubeconfig 复制到本地 |
| scp root@192.168.1.10:/etc/rancher/k3s/k3s.yaml ~/.kube/config |
| |
| # 修改 server 地址（替换 127.0.0.1 为实际 master IP） |
| sed -i 's/127.0.0.1/192.168.1.10/g' ~/.kube/config |
| |
| # 验证远程连接 |
| kubectl get nodes |

五、验证集群状态

5.1 基础检查

|-------------------------------------------------------|
| # 查看所有节点 |
| kubectl get nodes -o wide |
| |
| # 期望输出： |
| # NAME STATUS ROLES AGE VERSION |
| # master-1 Ready control-plane,master 5m v1.29.x+k3s1 |
| # master-2 Ready control-plane,master 3m v1.29.x+k3s1 |
| # worker-1 Ready <none> 2m v1.29.x+k3s1 |
| # worker-2 Ready <none> 2m v1.29.x+k3s1 |
| # 查看系统 Pod |
| kubectl get pods -n kube-system |
| |
| # 查看 etcd 健康状态 |
| kubectl get pods -n kube-system | grep etcd |

5.2 HA 故障转移测试

|-------------------------------|
| # 停止 master-1 的 k3s 服务，模拟节点故障 |
| systemctl stop k3s |
| |
| # 在 master-2 或其他节点上验证集群仍然可用 |
| kubectl get nodes |
| |
| # 恢复 master-1 |
| systemctl start k3s |

|----------------|--------------------------------------------------------------------|
| ✅ 预期结果 | master-1 停止后，master-2 会继续提供 API 服务，Worker 节点的业务 Pod 不受影响，支付服务持续可用。 |

六、迁移现有工作负载

如果你的业务之前跑在单节点 k8s 上，迁移步骤如下：

6.1 导出现有资源

|------------------------------------------------------------------------|
| # 导出所有 Deployment、Service、ConfigMap 等 |
| kubectl get deploy,svc,cm,secret,ingress -A -o yaml > backup.yaml |
| |
| # 过滤掉 kube-system 命名空间的系统资源 |
| kubectl get deploy,svc,cm -n your-namespace -o yaml > app-backup.yaml |

6.2 为支付业务添加反亲和性

确保支付核心服务的 Pod 分散在不同节点上，提升可用性：

|-------------------------------------------------|
| # 在 Deployment spec.template.spec 下添加： |
| affinity: |
| podAntiAffinity: |
| requiredDuringSchedulingIgnoredDuringExecution: |
| - labelSelector: |
| matchLabels: |
| app: payment-service # 替换为你的应用标签 |
| topologyKey: kubernetes.io/hostname |

6.3 配置 PodDisruptionBudget（PDB）

防止滚动更新期间支付服务中断：

|----------------------------------|
| apiVersion: policy/v1 |
| kind: PodDisruptionBudget |
| metadata: |
| name: payment-pdb |
| namespace: your-namespace |
| spec: |
| minAvailable: 1 |
| selector: |
| matchLabels: |
| app: payment-service # 替换为你的应用标签 |

6.4 应用资源到新集群

|--------------------------------------------|
| # 在新 K3s 集群上执行 |
| kubectl apply -f app-backup.yaml |
| |
| # 确认 Pod 正常启动 |
| kubectl get pods -n your-namespace -w |
| |
| # 确认 Pod 分布在不同节点 |
| kubectl get pods -n your-namespace -o wide |

七、与现有 Prometheus 集成

K3s 内置 metrics 接口，无需修改 Prometheus 配置文件，只需更新 target 地址。

7.1 K3s metrics 接口

|---------------------------------------------------------------------------|
| # 验证 metrics 接口可访问 |
| curl -k https://192.168.1.10:6443/metrics \ |
| --header "Authorization: Bearer $(cat /var/lib/rancher/k3s/server/token)" |

7.2 更新 Prometheus 配置

|------------------------------------------------|
| # prometheus.yml 新增抓取配置 |
| scrape_configs: |
| - job_name: 'k3s-nodes' |
| static_configs: |
| - targets: |
| - '192.168.1.10:9100' # master-1 node-exporter |
| - '192.168.1.11:9100' # master-2 node-exporter |
| - '192.168.1.12:9100' # worker-1 node-exporter |
| - '192.168.1.13:9100' # worker-2 node-exporter |
| |
| - job_name: 'k3s-etcd' |
| static_configs: |
| - targets: |
| - '192.168.1.10:2381' # etcd metrics |
| - '192.168.1.11:2381' |
| scheme: https |
| tls_config: |
| insecure_skip_verify: true |

7.3 关键告警规则（新增）

|------------------------------------------------------------------------|
| # etcd leader 丢失（影响整个控制面） |
| - alert: EtcdNoLeader |
| expr: etcd_server_has_leader == 0 |
| for: 1m |
| labels: |
| severity: critical |
| |
| # Node 不可用 |
| - alert: NodeNotReady |
| expr: kube_node_status_condition{condition='Ready',status='true'} == 0 |
| for: 2m |
| labels: |
| severity: critical |
| |
| # K3s 进程异常 |
| - alert: K3sServiceDown |
| expr: up{job='k3s-nodes'} == 0 |
| for: 1m |
| labels: |
| severity: critical |

八、常用运维命令

8.1 集群管理

|-------------------------------------------------------------------|
| # 查看集群信息 |
| kubectl cluster-info |
| |
| # 查看节点详情 |
| kubectl describe node master-1 |
| |
| # 查看所有命名空间资源 |
| kubectl get all -A |
| |
| # 驱逐节点（维护前） |
| kubectl drain worker-1 --ignore-daemonsets --delete-emptydir-data |
| |
| # 恢复节点调度 |
| kubectl uncordon worker-1 |

8.2 K3s 服务管理

|-----------------------------|
| # 查看 K3s 服务状态 |
| systemctl status k3s |
| |
| # 查看 K3s 日志 |
| journalctl -u k3s -f |
| |
| # 重启 K3s（master） |
| systemctl restart k3s |
| |
| # 重启 K3s（worker/agent） |
| systemctl restart k3s-agent |
| |
| # 查看 K3s 版本 |
| k3s --version |

8.3 升级 K3s

|-------------------------------------------------------------------------------------------------------------------------------|
| # 方法一：使用官方脚本升级 |
| curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.30.0+k3s1 sh - |
| |
| # 方法二：使用 system-upgrade-controller（推荐生产环境） |
| kubectl apply -f https://github.com/rancher/system-upgrade-controller/releases/latest/download/system-upgrade-controller.yaml |
| |
| # 注意：先升级 master，再升级 worker |

附录：常见问题排查

问题	可能原因	解决方法
节点 NotReady	网络插件未就绪 / 防火墙	检查 CNI Pod 状态，确认 8472 UDP 放行
etcd 选主失败	master 节点数为偶数	增加第三台 master 节点
Pod 一直 Pending	节点资源不足 / 污点	kubectl describe pod 查看 Events
kubectl 连接超时	API Server 地址错误	检查 KUBECONFIG 中 server 地址
镜像拉取失败	镜像仓库不可达	配置私有镜像仓库或代理
证书过期	K3s 默认 1 年有效期	执行 k3s certificate rotate 更新证书