企业官网建设流程全解析

别再为K3s镜像拉取慢发愁了！保姆级国内源安装配置指南（含Docker运行时设置）

当你在国内服务器上尝试部署K3s时，是否经历过漫长的等待和频繁的超时？作为轻量级Kubernetes发行版，K3s的安装本应快速简单，但网络问题往往让这个过程变得异常痛苦。本文将彻底解决这个痛点，通过国内镜像源实现秒级拉取，并完整覆盖从单节点部署到多节点集群的配置细节。

1. 为什么国内安装K3s总是失败？

K3s默认从Google Container Registry（gcr.io）拉取核心组件镜像，这在国内网络环境下几乎注定会失败。即使部分用户通过特殊网络手段能够访问，其速度也慢得令人难以忍受。更糟糕的是，一旦某个镜像拉取失败，整个安装过程就会中断，需要从头开始。

典型错误现象包括：

• Failed to pull image "k8s.gcr.io/pause:3.6"等镜像拉取错误
• 安装脚本长时间卡在Downloading k3s阶段
• 随机出现的TLS握手超时（ssl handshake timeout）

# 官方安装命令（不推荐国内使用） curl -sfL https://get.k3s.io | sh -

2. 国内镜像源解决方案全景对比

阿里云提供的镜像服务是目前最稳定的国内替代方案，其核心优势在于：

配置关键：INSTALL_K3S_MIRROR=cn环境变量会告诉安装脚本：

1. 自动替换所有gcr.io镜像为阿里云镜像地址
2. 从国内CDN下载k3s二进制文件
3. 使用本地化的组件校验机制

3. 单节点极速安装实战

以下是在纯净CentOS 7系统上的完整操作流程：

3.1 基础环境准备

# 关闭防火墙（生产环境需按需调整） systemctl stop firewalld && systemctl disable firewalld # 禁用SELinux setenforce 0 sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config # 加载内核模块 modprobe overlay modprobe br_netfilter

3.2 使用国内源安装K3s

# 设置关键环境变量 export INSTALL_K3S_MIRROR=cn export INSTALL_K3S_VERSION="v1.26.5+k3s1" # 指定稳定版本 export INSTALL_K3S_EXEC="--docker" # 使用Docker作为容器运行时 # 执行安装（注意管道左右不要有空格） curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | sh -

安装完成后验证服务状态：

systemctl status k3s

常见问题处理：

• 如果遇到Failed to find memory cgroup错误，需要在/boot/cmdline.txt添加：

  cgroup_memory=1 cgroup_enable=memory

• Docker未安装时，可先执行：

  curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

4. 多节点集群配置技巧

构建生产级集群需要特别注意以下配置：

4.1 Master节点初始化

# 首个Master节点（额外保存token） curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_TOKEN=MySecureToken \ sh -s - server --cluster-init

4.2 Worker节点加入

# Worker节点执行（替换实际IP和token） curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | \ INSTALL_K3S_MIRROR=cn \ K3S_URL=https://<master-ip>:6443 \ K3S_TOKEN=MySecureToken \ sh -

关键参数说明：

• K3S_URL：指向Master节点的HTTPS端点
• K3S_TOKEN：位于Master节点的/var/lib/rancher/k3s/server/node-token
• K3S_NODE_NAME：每个节点必须唯一（默认为主机名）

5. 安装后必须的优化配置

5.1 镜像加速配置

在/etc/docker/daemon.json中添加：

{ "registry-mirrors": [ "https://registry.cn-hangzhou.aliyuncs.com", "https://docker.mirrors.ustc.edu.cn" ] }

重启Docker生效：

systemctl restart docker

5.2 K3s服务调优

修改/etc/systemd/system/k3s.service：

[Service] LimitNOFILE=infinity LimitNPROC=infinity TimeoutStartSec=300s

重新加载配置：

systemctl daemon-reload systemctl restart k3s

6. 验证与故障排查

6.1 基础集群检查

# 查看节点状态 kubectl get nodes -o wide # 检查核心组件 kubectl -n kube-system get pods # Docker容器状态 docker ps -a

6.2 常见错误解决

问题1：Unable to connect to the server: x509: certificate signed by unknown authority

解决方案：

# 检查~/.kube/config中的证书路径 kubectl config view # 或直接复制配置文件 mkdir -p $HOME/.kube sudo cp /etc/rancher/k3s/k3s.yaml $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config

问题2：The connection to the server localhost:8080 was refused

通常是因为kubectl没有正确配置：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

7. 进阶：自定义组件镜像

对于需要自定义镜像仓库的场景，可以创建/etc/rancher/k3s/registries.yaml：

mirrors: docker.io: endpoint: - "https://docker.mirrors.ustc.edu.cn" gcr.io: endpoint: - "https://gcr.mirrors.ustc.edu.cn"

重启服务使配置生效：

systemctl restart k3s

在实际项目部署中，我们发现使用国内源后，K3s的安装时间从原来的30+分钟（且经常失败）缩短到3分钟以内。特别是在CI/CD流水线中，这种稳定性的提升直接影响了部署频率的成功率。