K3s 多节点集群离线安装指南

K3s 是轻量级 Kubernetes 发行版，二进制单文件部署，适合资源受限或网络隔离的环境。本文面向需要在离线（无外网）环境中搭建多节点高可用 K3s 集群的运维工程师，完整覆盖离线安装包制作与分发、Server 节点初始化、HA 扩容、Worker 加入、外部数据库、自定义 CNI、升级备份及常见问题。

1. 准备工作

1.1 环境要求

至少两台 Linux 服务器（推荐相同操作系统版本）
节点间网络互通（建议内网）
每节点至少 1GB 内存（生产环境建议 2GB 以上）
唯一主机名（通过 hostnamectl set-hostname <name> 设置）

1.2 网络要求

节点间开放端口：TCP 6443（API Server）、TCP 2379-2380（etcd）、TCP 8472（Flannel VXLAN）、UDP 51820（WireGuard）
确保防火墙允许节点间通信

2. 制作并分发离线安装包

离线安装需要三类文件：安装脚本、k3s 二进制、系统依赖与容器镜像包。在任意一台可联网机器上下载：

bash

# 1. 安装脚本
curl -sfL https://get.k3s.io -o install.sh
chmod +x install.sh

# 2. k3s 二进制（按目标架构选择，此处以 amd64 为例）
curl -sfL https://github.com/k3s-io/k3s/releases/download/v1.32.5+k3s1/k3s -o k3s
chmod +x k3s

# 3. 镜像包（包含 containerd、coredns 等全部系统组件镜像）
curl -sfL https://github.com/k3s-io/k3s/releases/download/v1.32.5+k3s1/k3s-airgap-images-amd64.tar.zst -o k3s-airgap-images-amd64.tar.zst

将三个文件分发到所有节点：

bash

for node in node-1 node-2 node-3; do
  scp install.sh k3s k3s-airgap-images-amd64.tar.zst ${node}:/tmp/
done

在每个节点上部署到位：

bash

# 二进制放到 PATH
sudo cp /tmp/k3s /usr/local/bin/k3s

# 镜像包放到 k3s 约定目录，安装时自动导入
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp /tmp/k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/

后续所有安装命令均使用本地脚本并加 INSTALL_K3S_SKIP_DOWNLOAD=true，禁止脚本联网下载：

bash

INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh <参数>

3. 安装 Server 节点（控制平面）

在第一个控制平面节点（node-1）上执行：

bash

INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh server \
  --cluster-init \
  --tls-san <负载均衡IP或DNS> \
  --node-taint CriticalAddonsOnly=true:NoExecute \
  --disable servicelb \
  --disable traefik

也可显式指定集群 Token（用于其他节点加入）：

bash

INSTALL_K3S_SKIP_DOWNLOAD=true K3S_TOKEN=<集群Token> ./install.sh server \
  --cluster-init

安装完成后：

获取 node-token：sudo cat /var/lib/rancher/k3s/server/node-token
获取 kubeconfig：sudo cat /etc/rancher/k3s/k3s.yaml

4. 添加额外 Server 节点（高可用）

在其他控制平面节点（node-2、node-3）上执行：

bash

INSTALL_K3S_SKIP_DOWNLOAD=true K3S_TOKEN=<集群Token> ./install.sh server \
  --server https://192.168.10.11:6443 \
  --disable servicelb \
  --disable traefik

其中 192.168.10.11 为第一个 Server 节点地址。生产环境建议配置 3 个 Server 节点保证 etcd 高可用。

5. 添加 Worker 节点

在所有工作节点上执行：

bash

INSTALL_K3S_SKIP_DOWNLOAD=true \
  K3S_URL=https://192.168.10.11:6443 \
  K3S_TOKEN=<集群Token> ./install.sh

6. 验证集群状态

在任意 Server 节点上执行：

bash

# 查看节点状态
kubectl get nodes -o wide

# 查看集群信息
kubectl cluster-info

# 检查所有 Pod 状态
kubectl get pods -A

# 检查 k3s 服务状态
sudo systemctl status k3s

7. 高级配置选项

7.1 使用外部数据库（替代嵌入式 etcd）

支持 MySQL、PostgreSQL、etcd 作为外部数据存储：

bash

INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh server \
  --datastore-endpoint="mysql://username:<YOUR_PASSWORD>@tcp(hostname:3306)/database-name" \
  --tls-san <负载均衡IP或DNS>

7.2 自定义网络插件（Calico）

bash

# 禁用默认 Flannel，安装时不启用网络策略组件
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh server \
  --flannel-backend=none \
  --disable-network-policy \
  --cluster-init

# 然后安装 Calico（离线环境需提前下载 calico.yaml 及其镜像）
kubectl apply -f calico.yaml

7.3 持久化存储配置

K3s 默认已内置 local-path-provisioner，无需额外安装，直接创建 PVC 即可使用节点本地存储。

8. 管理集群

8.1 节点维护

bash

# 安全驱逐节点
kubectl drain <node-name> --ignore-daemonsets

# 删除节点
kubectl delete node <node-name>

8.2 升级集群

升级前先在每台节点替换新版 k3s 二进制与镜像包（同第 2 节流程），然后滚动重启：

bash

# 在每个 Server 节点上执行
INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh server \
  --cluster-init \
  --disable servicelb \
  --disable traefik

# 然后在每个 Worker 节点上执行
INSTALL_K3S_SKIP_DOWNLOAD=true \
  K3S_URL=https://192.168.10.11:6443 \
  K3S_TOKEN=<集群Token> ./install.sh

8.3 备份与恢复

bash

# 备份（在 Server 节点上）
sudo k3s etcd-snapshot save --name pre-upgrade-backup

# 恢复
sudo k3s server \
  --cluster-init \
  --cluster-reset \
  --etcd-snapshot-name pre-upgrade-backup

9. 常见问题解决

9.1 节点加入失败

检查 token 是否正确
验证网络连接（特别是 6443 端口）
检查时间同步（timedatectl status）

9.2 Pod 网络问题

检查 Flannel 或 Calico Pod 是否运行正常
验证节点路由是否正确
检查 8472 等 CNI 端口是否在防火墙放行

9.3 存储问题

确认 local-path-provisioner 正常运行（kubectl get pods -n kube-system）
检查节点磁盘空间

9.4 镜像拉取失败（ImagePullBackOff）

离线环境确认 k3s-airgap-images 包已放入 /var/lib/rancher/k3s/agent/images/
业务镜像需提前推送到内网镜像仓库，并在 /etc/rancher/k3s/registries.yaml 中配置仓库地址与凭据

10. 生产环境建议

最少 3 个 Server 节点：确保 etcd 集群高可用
负载均衡：在 Server 节点前部署负载均衡器，并通过 --tls-san 加入其地址
监控：安装 Prometheus 和 Grafana 监控集群
备份策略：定期执行 etcd 快照备份并异地留存
安全加固：
- 限制 kubelet API 访问
- 启用网络策略
- 定期轮换证书

故障速查

现象	排查方向
安装脚本卡在下载	确认 `INSTALL_K3S_SKIP_DOWNLOAD=true` 已设置，且 /usr/local/bin/k3s 存在
系统组件 Pod 一直 ImagePullBackOff	镜像包未放入 /var/lib/rancher/k3s/agent/images/ 或架构不匹配
新 Server 无法加入集群	Token 错误、6443 端口不通、节点时间不同步
Pod 跨节点无法通信	CNI 端口（Flannel 8472 / WireGuard 51820）被防火墙拦截
cluster-reset 恢复失败	需在停止 k3s 服务的首个 Server 节点操作，其余 Server 节点清空数据目录后重新加入

通过以上步骤，可以建立一个稳定可靠的 K3s 多节点集群，适用于离线及生产环境。

K3s 多节点集群离线安装指南 ​

1. 准备工作 ​

1.1 环境要求 ​

1.2 网络要求 ​

2. 制作并分发离线安装包 ​

3. 安装 Server 节点（控制平面） ​

4. 添加额外 Server 节点（高可用） ​

5. 添加 Worker 节点 ​

6. 验证集群状态 ​

7. 高级配置选项 ​

7.1 使用外部数据库（替代嵌入式 etcd） ​

7.2 自定义网络插件（Calico） ​

7.3 持久化存储配置 ​

8. 管理集群 ​

8.1 节点维护 ​

8.2 升级集群 ​

8.3 备份与恢复 ​

9. 常见问题解决 ​

9.1 节点加入失败 ​

9.2 Pod 网络问题 ​

9.3 存储问题 ​

9.4 镜像拉取失败（ImagePullBackOff） ​

10. 生产环境建议 ​

故障速查 ​

K3s 多节点集群离线安装指南

1. 准备工作

1.1 环境要求

1.2 网络要求

2. 制作并分发离线安装包

3. 安装 Server 节点（控制平面）

4. 添加额外 Server 节点（高可用）

5. 添加 Worker 节点

6. 验证集群状态

7. 高级配置选项

7.1 使用外部数据库（替代嵌入式 etcd）

7.2 自定义网络插件（Calico）

7.3 持久化存储配置

8. 管理集群

8.1 节点维护

8.2 升级集群

8.3 备份与恢复

9. 常见问题解决

9.1 节点加入失败

9.2 Pod 网络问题

9.3 存储问题

9.4 镜像拉取失败（ImagePullBackOff）

10. 生产环境建议

故障速查