1. K3S国内部署的痛点与解决方案在国内部署K3S时最让人头疼的就是镜像下载速度慢甚至失败的问题。这主要是因为K3S默认使用的镜像仓库如gcr.io在国内访问受限。我刚开始接触K3S时就踩过这个坑花了一整天时间反复尝试安装结果还是因为网络问题失败了。好在现在有成熟的国内镜像源解决方案。阿里云和Rancher官方都提供了完整的K3S镜像仓库实测下载速度能提升10倍以上。下面这个对比表很能说明问题镜像源类型平均下载速度成功率适用场景国外官方源50KB/s30%海外服务器阿里云镜像5MB/s99%国内环境Rancher镜像3MB/s95%国内环境除了镜像源K3S在国内部署还有几个常见问题系统依赖缺失导致安装失败防火墙规则阻止节点通信资源限制导致组件启动失败证书问题导致节点无法加入集群针对这些问题我总结了一套完整的解决方案接下来会详细介绍从环境准备到集群验证的全流程。2. 环境准备与系统配置2.1 硬件与系统要求K3S对硬件要求很低这是它最大的优势之一。我在树莓派4B4GB内存上都能稳定运行一个三节点集群。以下是推荐配置Master节点至少1核CPU1GB内存生产环境建议2核4GWorker节点至少1核CPU512MB内存磁盘空间每个节点至少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. 使用国内镜像源安装K3S3.1 选择最适合的镜像源目前国内可用的K3S镜像源主要有两个阿里云镜像https://rancher-mirror.oss-cn-beijing.aliyuncs.com/k3sRancher官方中国镜像https://rancher-mirror.rancher.cn/k3s我对比测试过这两个源阿里云的速度稍快但更新可能有1-2天延迟Rancher官方源更新及时但偶尔会有短暂不可用的情况。建议根据实际情况选择。3.2 单节点集群安装这是最简单的部署方式适合开发和测试环境。关键是要设置INSTALL_K3S_MIRRORcn环境变量# 设置使用国内镜像源 export INSTALL_K3S_MIRRORcn # 指定K3S版本可选 export INSTALL_K3S_VERSIONv1.26.5k3s1 # 执行安装 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_MIRRORcn \ INSTALL_K3S_EXEC--docker \ sh -只安装不自动启动curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn \ INSTALL_K3S_SKIP_STARTtrue \ sh -指定数据目录curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn \ 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_MIRRORcn \ K3S_NODE_NAMEk3s-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_MIRRORcn \ K3S_URLhttps://MASTER_IP:6443 \ K3S_TOKENTOKEN_FROM_MASTER \ K3S_NODE_NAMEk3s-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-hardmemory.available100Mi - eviction-minimum-reclaimmemory.available0Mi EOF6. 生产环境进阶配置6.1 高可用部署对于生产环境建议配置高可用集群。最简单的方式是使用嵌入式etcd# 第一个Master节点 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn \ K3S_NODE_NAMEk3s-master-1 \ sh -s - server --cluster-init # 后续Master节点 curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn \ K3S_NODE_NAMEk3s-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_MIRRORcn \ INSTALL_K3S_VERSIONv1.26.5k3s1 \ 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