1. 为什么需要国内镜像加速安装K3s第一次接触K3s的朋友可能会疑惑为什么不能直接从官网下载安装这里有个很现实的痛点国内网络环境访问国外资源经常不稳定。我刚开始用K3s时就遇到过一个简单的安装命令卡了半小时最后还超时失败。后来才发现默认安装脚本会从国外服务器拉取镜像和二进制文件这对国内开发者来说简直是噩梦。K3s作为轻量级Kubernetes发行版本身设计非常优秀但网络问题让很多新手在第一步就栽了跟头。使用国内镜像源加速后安装时间能从半小时缩短到3分钟成功率也从50%提升到99%。这就像原本要绕地球半圈才能拿到的快递现在直接从隔壁仓库发货效率提升不是一点半点。国内常见的镜像源包括阿里云、网易、中科大等它们都会定期同步官方仓库。不过要注意的是不同镜像源的同步频率和完整性可能有差异。我在实际使用中发现阿里云的镜像通常比较及时而网易的镜像在某些冷门版本上可能会有延迟。建议优先选择大厂的镜像服务稳定性更有保障。2. 准备工作与环境检查2.1 系统要求确认在开始安装前先确认你的系统是否符合要求。K3s官方支持大多数Linux发行版我在CentOS 7/8、Ubuntu 18.04/20.04上都成功部署过。内存建议至少1GB虽然K3s号称能在512MB内存运行但实际使用时你会发现1GB才是比较舒服的起点。检查内核版本也很重要uname -r建议内核版本不低于4.14否则可能会遇到cgroup v2相关的问题。如果是在云服务器上部署还要注意安全组规则确保6443端口K3s API server端口没有被屏蔽。2.2 依赖组件安装K3s本身依赖很少但有些组件能让你用得更顺手。我习惯先安装这些工具# 对于CentOS/RHEL sudo yum install -y curl vim # 对于Ubuntu/Debian sudo apt-get update sudo apt-get install -y curl vim特别是curl后面安装脚本会用到。vim则是为了方便编辑配置文件当然你也可以用nano等其他编辑器。3. 使用国内镜像源安装K3s3.1 一键安装命令解析原始文章给出了一个很好的安装命令模板我来详细解释下每个参数的作用sudo curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn sh -s - server \ --system-default-registry registry.cn-hangzhou.aliyuncs.com \ --write-kubeconfig ~/.kube/config \ --write-kubeconfig-mode 666 \ --disable traefik关键参数说明INSTALL_K3S_MIRRORcn指定使用国内镜像源下载K3s二进制文件--system-default-registry设置默认容器镜像仓库这里用了阿里云镜像--disable traefik禁用内置的ingress controller如果你需要可以保留这个命令会下载安装脚本并自动执行整个过程通常2-3分钟就能完成。我第一次用时简直惊喜之前用官方源卡住的问题完全消失了。3.2 安装后验证安装完成后用这个命令检查状态sudo k3s kubectl get pods -A正常情况下应该看到类似这样的输出NAMESPACE NAME READY STATUS RESTARTS AGE kube-system local-path-provisioner-xxx 1/1 Running 0 1m kube-system coredns-xxx 1/1 Running 0 1m如果所有pod都是Running状态说明安装成功了。如果有问题可以查看日志journalctl -u k3s -f4. 配置容器镜像加速4.1 配置镜像仓库mirror虽然安装时指定了默认仓库但Docker Hub的镜像还是可能被墙。这时候需要配置mirror创建配置文件sudo mkdir -p /etc/rancher/k3s/ sudo tee /etc/rancher/k3s/registries.yaml EOF mirrors: docker.io: endpoint: - http://hub-mirror.c.163.com - https://docker.mirrors.ustc.edu.cn - https://registry.docker-cn.com EOF这个配置会让所有对docker.io的请求被重定向到国内镜像站。我测试过网易和中科大的镜像速度都能达到10MB/s以上。4.2 测试镜像加速效果配置完成后需要重启服务sudo systemctl restart k3s然后测试拉取镜像sudo crictl pull nginx:alpine如果看到类似这样的输出说明加速生效了Image is up to date for docker.io/library/nginxsha256:xxx拉取速度应该在几秒内完成如果还是很慢可能是某个镜像源不可用可以尝试修改registries.yaml换用其他源。5. 部署测试应用验证集群5.1 创建Nginx Deployment为了验证集群是否正常工作我们来部署一个简单的Nginx应用。创建文件nginx-deployment.yamlapiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment spec: replicas: 2 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:alpine ports: - containerPort: 80 --- apiVersion: v1 kind: Service metadata: name: nginx-service spec: type: NodePort selector: app: nginx ports: - protocol: TCP port: 80 targetPort: 80 nodePort: 30080这个配置会创建一个Deployment运行2个Nginx实例一个NodePort类型的Service通过30080端口暴露服务5.2 部署与访问应用应用部署命令sudo k3s kubectl apply -f nginx-deployment.yaml检查部署状态sudo k3s kubectl get pods -l appnginx如果一切正常可以通过curl测试curl http://localhost:30080应该能看到Nginx的欢迎页面。如果是在云服务器上部署记得在安全组中开放30080端口。6. 多节点集群配置可选6.1 添加Worker节点单节点适合开发和测试生产环境建议至少3个节点。添加Worker节点的命令如下curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn \ K3S_URLhttps://server-ip:6443 \ K3S_TOKENnode-token sh -其中server-ip替换为主节点的IPnode-token从主节点的/var/lib/rancher/k3s/server/node-token获取我在AWS上测试过添加一个节点大约需要2分钟比直接用官方源快很多。6.2 检查节点状态在主节点上运行sudo k3s kubectl get nodes应该能看到类似输出NAME STATUS ROLES AGE VERSION master Ready control-plane,master 5m v1.21.5k3s2 worker1 Ready none 1m v1.21.5k3s27. 常见问题排查7.1 镜像拉取失败如果遇到镜像拉取失败首先检查sudo crictl pull nginx:alpine如果失败可能是镜像源不可用。尝试修改registries.yaml换用其他源比如华为云镜像mirrors: docker.io: endpoint: - https://mirror.ccs.tencentyun.com7.2 端口冲突如果30080端口被占用可以修改Service配置中的nodePort范围是30000-32767。我遇到过几次端口冲突后来养成了习惯先用netstat检查端口使用情况。7.3 卸载K3s如果需要重新安装先彻底卸载sudo /usr/local/bin/k3s-uninstall.sh这个脚本会清理所有K3s相关资源。有次我没卸载干净就直接重装结果遇到了各种奇怪的问题后来发现是残留的etcd数据导致的。
K3s国内镜像加速安装与配置实战指南
发布时间：2026/7/30 0:16:56
1. 为什么需要国内镜像加速安装K3s第一次接触K3s的朋友可能会疑惑为什么不能直接从官网下载安装这里有个很现实的痛点国内网络环境访问国外资源经常不稳定。我刚开始用K3s时就遇到过一个简单的安装命令卡了半小时最后还超时失败。后来才发现默认安装脚本会从国外服务器拉取镜像和二进制文件这对国内开发者来说简直是噩梦。K3s作为轻量级Kubernetes发行版本身设计非常优秀但网络问题让很多新手在第一步就栽了跟头。使用国内镜像源加速后安装时间能从半小时缩短到3分钟成功率也从50%提升到99%。这就像原本要绕地球半圈才能拿到的快递现在直接从隔壁仓库发货效率提升不是一点半点。国内常见的镜像源包括阿里云、网易、中科大等它们都会定期同步官方仓库。不过要注意的是不同镜像源的同步频率和完整性可能有差异。我在实际使用中发现阿里云的镜像通常比较及时而网易的镜像在某些冷门版本上可能会有延迟。建议优先选择大厂的镜像服务稳定性更有保障。2. 准备工作与环境检查2.1 系统要求确认在开始安装前先确认你的系统是否符合要求。K3s官方支持大多数Linux发行版我在CentOS 7/8、Ubuntu 18.04/20.04上都成功部署过。内存建议至少1GB虽然K3s号称能在512MB内存运行但实际使用时你会发现1GB才是比较舒服的起点。检查内核版本也很重要uname -r建议内核版本不低于4.14否则可能会遇到cgroup v2相关的问题。如果是在云服务器上部署还要注意安全组规则确保6443端口K3s API server端口没有被屏蔽。2.2 依赖组件安装K3s本身依赖很少但有些组件能让你用得更顺手。我习惯先安装这些工具# 对于CentOS/RHEL sudo yum install -y curl vim # 对于Ubuntu/Debian sudo apt-get update sudo apt-get install -y curl vim特别是curl后面安装脚本会用到。vim则是为了方便编辑配置文件当然你也可以用nano等其他编辑器。3. 使用国内镜像源安装K3s3.1 一键安装命令解析原始文章给出了一个很好的安装命令模板我来详细解释下每个参数的作用sudo curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn sh -s - server \ --system-default-registry registry.cn-hangzhou.aliyuncs.com \ --write-kubeconfig ~/.kube/config \ --write-kubeconfig-mode 666 \ --disable traefik关键参数说明INSTALL_K3S_MIRRORcn指定使用国内镜像源下载K3s二进制文件--system-default-registry设置默认容器镜像仓库这里用了阿里云镜像--disable traefik禁用内置的ingress controller如果你需要可以保留这个命令会下载安装脚本并自动执行整个过程通常2-3分钟就能完成。我第一次用时简直惊喜之前用官方源卡住的问题完全消失了。3.2 安装后验证安装完成后用这个命令检查状态sudo k3s kubectl get pods -A正常情况下应该看到类似这样的输出NAMESPACE NAME READY STATUS RESTARTS AGE kube-system local-path-provisioner-xxx 1/1 Running 0 1m kube-system coredns-xxx 1/1 Running 0 1m如果所有pod都是Running状态说明安装成功了。如果有问题可以查看日志journalctl -u k3s -f4. 配置容器镜像加速4.1 配置镜像仓库mirror虽然安装时指定了默认仓库但Docker Hub的镜像还是可能被墙。这时候需要配置mirror创建配置文件sudo mkdir -p /etc/rancher/k3s/ sudo tee /etc/rancher/k3s/registries.yaml EOF mirrors: docker.io: endpoint: - http://hub-mirror.c.163.com - https://docker.mirrors.ustc.edu.cn - https://registry.docker-cn.com EOF这个配置会让所有对docker.io的请求被重定向到国内镜像站。我测试过网易和中科大的镜像速度都能达到10MB/s以上。4.2 测试镜像加速效果配置完成后需要重启服务sudo systemctl restart k3s然后测试拉取镜像sudo crictl pull nginx:alpine如果看到类似这样的输出说明加速生效了Image is up to date for docker.io/library/nginxsha256:xxx拉取速度应该在几秒内完成如果还是很慢可能是某个镜像源不可用可以尝试修改registries.yaml换用其他源。5. 部署测试应用验证集群5.1 创建Nginx Deployment为了验证集群是否正常工作我们来部署一个简单的Nginx应用。创建文件nginx-deployment.yamlapiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment spec: replicas: 2 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:alpine ports: - containerPort: 80 --- apiVersion: v1 kind: Service metadata: name: nginx-service spec: type: NodePort selector: app: nginx ports: - protocol: TCP port: 80 targetPort: 80 nodePort: 30080这个配置会创建一个Deployment运行2个Nginx实例一个NodePort类型的Service通过30080端口暴露服务5.2 部署与访问应用应用部署命令sudo k3s kubectl apply -f nginx-deployment.yaml检查部署状态sudo k3s kubectl get pods -l appnginx如果一切正常可以通过curl测试curl http://localhost:30080应该能看到Nginx的欢迎页面。如果是在云服务器上部署记得在安全组中开放30080端口。6. 多节点集群配置可选6.1 添加Worker节点单节点适合开发和测试生产环境建议至少3个节点。添加Worker节点的命令如下curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRRORcn \ K3S_URLhttps://server-ip:6443 \ K3S_TOKENnode-token sh -其中server-ip替换为主节点的IPnode-token从主节点的/var/lib/rancher/k3s/server/node-token获取我在AWS上测试过添加一个节点大约需要2分钟比直接用官方源快很多。6.2 检查节点状态在主节点上运行sudo k3s kubectl get nodes应该能看到类似输出NAME STATUS ROLES AGE VERSION master Ready control-plane,master 5m v1.21.5k3s2 worker1 Ready none 1m v1.21.5k3s27. 常见问题排查7.1 镜像拉取失败如果遇到镜像拉取失败首先检查sudo crictl pull nginx:alpine如果失败可能是镜像源不可用。尝试修改registries.yaml换用其他源比如华为云镜像mirrors: docker.io: endpoint: - https://mirror.ccs.tencentyun.com7.2 端口冲突如果30080端口被占用可以修改Service配置中的nodePort范围是30000-32767。我遇到过几次端口冲突后来养成了习惯先用netstat检查端口使用情况。7.3 卸载K3s如果需要重新安装先彻底卸载sudo /usr/local/bin/k3s-uninstall.sh这个脚本会清理所有K3s相关资源。有次我没卸载干净就直接重装结果遇到了各种奇怪的问题后来发现是残留的etcd数据导致的。
