k3s部署有四种方法：一、国内镜像一键安装（推荐新手）；二、air-gap离线安装（适用于无外网环境）；三、多节点高可用集群部署（含etcd备份与证书复用）；四、自定义内核模块与网络插件预加载安装。
如果您希望在 Linux 系统上部署轻量级 Kubernetes 发行版 K3s，但遇到安装失败、服务未启动或配置不生效等问题，则可能是由于基础环境未就绪或安装参数不匹配所致。以下是针对进阶场景的多种安装部署方法：
一、国内镜像加速的一键安装（推荐新手与开发测试）
该方法利用 Rancher 中国镜像源规避网络阻塞，自动下载二进制、pause 镜像及依赖组件，并生成标准 kubeconfig，适合无代理、无离线包的常规环境。
1、执行魔改安装命令，启用国内镜像并禁用 Traefik（避免端口冲突）：
2、运行以下命令（请确保已关闭 swap 和防火墙）：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--disable traefik --write-kubeconfig-mode 644" sh -
3、验证服务状态：
systemctl status k3s
4、确认配置文件可读：
chmod 644 /etc/rancher/k3s/k3s.yaml
二、Air-gap 离线安装（适用于无外网生产环境）
该方法完全脱离公网，所有组件均通过预下载的压缩包加载，杜绝网络超时与镜像拉取失败，适用于金融、政务等强隔离网络。
1、在有网机器上下载离线包（以 v1.30.2+k3s1 为例）：
wget https://github.com/k3s-io/k3s/releases/download/v1.30.2+k3s1/k3s-airgap-images-amd64.tar.gz
wget https://github.com/k3s-io/k3s/releases/download/v1.30.2+k3s1/k3s
2、将两个文件复制至目标节点，解压镜像包：
gunzip k3s-airgap-images-amd64.tar.gz
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/
3、赋予执行权限并安装：
chmod +x k3s
sudo cp k3s /usr/local/bin/
sudo INSTALL_K3S_SKIP_DOWNLOAD=true ./k3s server --node-name master --disable traefik
4、关键校验点：
必须确认 /var/lib/rancher/k3s/agent/images/ 目录下存在 tar 文件且不可为空
三、多节点高可用集群部署（含 etcd 备份与证书复用）
该方法构建具备主节点冗余能力的集群，使用嵌入式 etcd 替代默认 sqlite，支持节点故障自动恢复，并复用初始证书避免 TLS 重签风险。
1、首台 server 节点执行（指定数据目录与外部 etcd 模式）：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--cluster-init --datastore-endpoint='sqlite:///var/lib/rancher/k3s/db/rancher.db' --write-kubeconfig-mode 644" sh -
2、其余 server 节点加入时复用首节点证书：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn K3S_URL=https://
3、获取并分发 token：
cat /var/lib/rancher/k3s/server/node-token
4、验证 etcd 成员状态：
sudo k3s etcd member list
四、自定义内核模块与网络插件预加载安装
该方法在安装前显式加载 br_netfilter、ip_vs 等必需内核模块，并预置 Calico 或 Cilium 所需参数，避免运行时因模块缺失导致 Pod 网络异常。
1、加载内核模块并持久化：
echo "br_netfilter" | sudo tee -a /etc/modules
echo "ip_vs" | sudo tee -a /etc/modules
sudo modprobe br_netfilter ip_vs
2、配置 sysctl 参数：
cat
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
sudo sysctl --system
3、安装时注入 CNI 插件路径与参数：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--flannel-backend=none --disable-network-policy --kube-proxy-arg=proxy-mode=ipvs" sh -
4、后续手动部署 Calico：
kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
五、带 Helm 与 Kuboard 面板的一体化安装
该方法在 K3s 启动后自动集成 Helm v3 与 Kuboard v3 控制台，实现开箱即用的图形化管理能力，适用于需要快速交付演示环境的场景。
1、安装 K3s 并预留 Helm 兼容配置：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--disable servicelb --disable traefik --write-kubeconfig-mode 644" sh -
2、安装 Helm 并添加仓库：
curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | sh
helm repo add kuboard https://e1z7m8c9.github.io/kuboard-chart
helm repo update
3、部署 Kuboard：
helm install kuboard kuboard/kuboard --namespace kuboard --create-namespace
4、暴露访问端口：
kubectl patch svc kuboard -n kuboard -p '{"spec":{"type":"NodePort","ports":[{"port":80,"nodePort":32567}]}}'
5、关键访问凭证：
kubectl -n kuboard get secret kuboard -o jsonpath="{.data.username}" | base64 -d; echo
kubectl -n kuboard get secret kuboard -o jsonpath="{.data.password}" | base64 -d; echo
