1. K3S国内部署的痛点与解决方案
在国内部署K3S时，最让人头疼的就是镜像下载速度慢甚至失败的问题。这主要是因为K3S默认使用的镜像仓库如gcr.io在国内访问受限。我刚开始接触K3S时就踩过这个坑，花了一整天时间反复尝试安装，结果还是因为网络问题失败了。
好在现在有成熟的国内镜像源解决方案。阿里云和Rancher官方都提供了完整的K3S镜像仓库，实测下载速度能提升10倍以上。下面这个对比表很能说明问题：
| 镜像源类型 | 平均下载速度 | 成功率 | 适用场景 |
|---|---|---|---|
| 国外官方源 | 50KB/s | 30% | 海外服务器 |
| 阿里云镜像 | 5MB/s | 99% | 国内环境 |
| Rancher镜像 | 3MB/s | 95% | 国内环境 |
除了镜像源，K3S在国内部署还有几个常见问题：
- 系统依赖缺失导致安装失败
- 防火墙规则阻止节点通信
- 资源限制导致组件启动失败
- 证书问题导致节点无法加入集群
针对这些问题，我总结了一套完整的解决方案，接下来会详细介绍从环境准备到集群验证的全流程。
2. 环境准备与系统配置
2.1 硬件与系统要求
K3S对硬件要求很低，这是它最大的优势之一。我在树莓派4B（4GB内存）上都能稳定运行一个三节点集群。以下是推荐配置：
- Master节点：至少1核CPU，1GB内存（生产环境建议2核4G）
- Worker节点：至少1核CPU，512MB内存
- 磁盘空间：每个节点至少10GB
- 操作系统：Ubuntu 20.04/22.04、CentOS 7/8等主流Linux发行版
注意：如果使用CentOS 7，需要先关闭firewalld和SELinux，否则可能导致网络通信问题。
2.2 前置依赖安装
虽然K3S号称"零依赖"，但实际部署时还是需要一些基础工具。这是我整理的必备软件清单：
# Ubuntu/Debian sudo apt update && sudo apt install -y curl wget git vim net-tools # CentOS/RHEL sudo yum install -y curl wget git vim net-tools如果要用Docker作为容器运行时（非必须），还需要先安装Docker：
# Docker安装 curl -fsSL https://get.docker.com | sh sudo systemctl enable --now docker2.3 系统参数调优
为了让K3S运行更稳定，建议调整以下内核参数：
cat <<EOF | sudo tee /etc/sysctl.d/k3s.conf net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-iptables = 1 fs.inotify.max_user_instances = 512 EOF sudo sysctl --system3. 使用国内镜像源安装K3S
3.1 选择最适合的镜像源
目前国内可用的K3S镜像源主要有两个：
- 阿里云镜像：
https://rancher-mirror.oss-cn-beijing.aliyuncs.com/k3s - Rancher官方中国镜像：
https://rancher-mirror.rancher.cn/k3s
我对比测试过这两个源，阿里云的速度稍快但更新可能有1-2天延迟，Rancher官方源更新及时但偶尔会有短暂不可用的情况。建议根据实际情况选择。
3.2 单节点集群安装
这是最简单的部署方式，适合开发和测试环境。关键是要设置INSTALL_K3S_MIRROR=cn环境变量：
# 设置使用国内镜像源 export INSTALL_K3S_MIRROR=cn # 指定K3S版本（可选） export INSTALL_K3S_VERSION="v1.26.5+k3s1" # 执行安装 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | sh -安装完成后，检查服务状态：
systemctl status k3s如果一切正常，你应该能看到类似这样的输出：
● k3s.service - Lightweight Kubernetes Loaded: loaded (/etc/systemd/system/k3s.service; enabled; vendor preset: enabled) Active: active (running) since Thu 2023-08-10 14:23:45 CST; 1min ago3.3 自定义安装选项
K3S支持多种自定义安装方式，以下是我常用的几个配置示例：
使用Docker作为运行时：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ INSTALL_K3S_EXEC="--docker" \ sh -只安装不自动启动：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ INSTALL_K3S_SKIP_START=true \ sh -指定数据目录：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ INSTALL_K3S_EXEC="--data-dir /opt/k3s" \ sh -4. 多节点集群部署实战
4.1 Master节点初始化
首先在Master节点执行安装，并获取加入集群所需的token：
# Master节点安装 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=k3s-master \ sh - # 获取node-token cat /var/lib/rancher/k3s/server/node-token记下输出的token，格式类似于：
K100bdf2558019e82aaf8adda1c30efc341049702d2f5dbc9144f8f49c088120039::server:1855d8a39ab04c368ec9a324fa1a82c14.2 Worker节点加入集群
在Worker节点上执行以下命令加入集群：
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_URL=https://<MASTER_IP>:6443 \ K3S_TOKEN=<TOKEN_FROM_MASTER> \ K3S_NODE_NAME=k3s-worker-01 \ sh -替换<MASTER_IP>为Master节点的实际IP地址，<TOKEN_FROM_MASTER>为上一步获取的token。
4.3 集群网络配置
K3S默认使用Flannel作为CNI插件，在国内环境下可能需要调整其配置：
cat <<EOF | sudo tee /etc/rancher/k3s/config.yaml flannel-backend: host-gw node-ip: <本机IP> EOF systemctl restart k3s如果节点间网络延迟较高，建议使用wireguard后端：
cat <<EOF | sudo tee /etc/rancher/k3s/config.yaml flannel-backend: wireguard EOF5. 集群验证与问题排查
5.1 基础检查命令
安装完成后，这些命令可以帮助你验证集群状态：
# 查看节点状态 kubectl get nodes -o wide # 查看所有资源 kubectl get all -A -o wide # 检查核心组件状态 kubectl -n kube-system get pods5.2 常见问题解决
镜像拉取失败：
# 查看正在拉取的镜像 journalctl -u k3s -f | grep "Pulling image" # 手动拉取镜像 crictl pull <镜像名称>节点无法加入集群：
- 检查Master节点的6443端口是否开放
- 确认token是否正确
- 检查节点时间是否同步
Pod网络不通：
# 检查Flannel接口 ip addr show flannel.1 # 检查路由表 ip route show5.3 性能优化建议
对于资源有限的节点，可以关闭不需要的组件：
cat <<EOF | sudo tee /etc/rancher/k3s/config.yaml disable: - traefik - local-storage - metrics-server EOF如果内存不足，可以调整Kubelet参数：
cat <<EOF | sudo tee /etc/rancher/k3s/config.yaml kubelet-arg: - "eviction-hard=memory.available<100Mi" - "eviction-minimum-reclaim=memory.available=0Mi" EOF6. 生产环境进阶配置
6.1 高可用部署
对于生产环境，建议配置高可用集群。最简单的方式是使用嵌入式etcd：
# 第一个Master节点 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=k3s-master-1 \ sh -s - server --cluster-init # 后续Master节点 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_NODE_NAME=k3s-master-2 \ sh -s - server --server https://<第一个Master节点IP>:64436.2 持久化存储配置
K3S支持多种存储方案，我推荐使用本地存储卷：
# 创建存储类 cat <<EOF | kubectl apply -f - apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: local-storage provisioner: kubernetes.io/no-provisioner volumeBindingMode: WaitForFirstConsumer EOF6.3 监控与日志
使用K3S内置的Prometheus和Grafana：
# 启用监控 helm upgrade --install kube-prometheus-stack \ --namespace monitoring \ --create-namespace \ --repo https://prometheus-community.github.io/helm-charts \ prometheus-community/kube-prometheus-stack7. 日常维护技巧
7.1 版本升级
K3S支持原地升级，非常方便：
# 查看可用版本 curl -s https://api.github.com/repos/k3s-io/k3s/releases | grep tag_name # 执行升级 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ INSTALL_K3S_VERSION="v1.26.5+k3s1" \ sh -7.2 备份与恢复
备份K3S集群数据：
# 备份etcd数据 sudo k3s etcd-snapshot save --name pre-upgrade-backup # 查看备份列表 sudo k3s etcd-snapshot ls # 从备份恢复 sudo k3s server \ --cluster-reset \ --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/etcd-old/pre-upgrade-backup7.3 资源清理
卸载K3S并清理残留：
# 卸载K3S /usr/local/bin/k3s-uninstall.sh # 清理残留数据 rm -rf /etc/rancher /var/lib/rancher在实际项目中，我发现定期清理无用镜像能节省大量空间：
# 清理无用镜像 k3s crictl rmi --prune
