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

节点	角色	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 更新证书

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责