K3s离线安装保姆级避坑指南：从镜像准备到集群验证（含Harbor私有仓库配置）

K3s离线安装全流程实战从私有仓库搭建到集群高可用在金融、军工、政务等对网络安全要求极高的领域离线环境部署Kubernetes集群已成为刚需。作为轻量级Kubernetes发行版K3s凭借其小于50MB的二进制体积和内置组件简化设计成为隔离环境下的首选方案。本文将深入解析两种主流离线部署模式——基于Harbor私有仓库的标准化部署与手动导入镜像的快速部署通过对比测试数据揭示各自适用场景并提供从单节点到高可用集群的完整避坑指南。1. 离线部署方案选型与核心准备1.1 基础设施需求矩阵在开始前需确保满足以下硬件条件组件最低配置要求生产环境推荐配置Master节点2核CPU/4GB内存4核CPU/8GB内存Worker节点1核CPU/2GB内存2核CPU/4GB内存磁盘空间20GB100GB SSD网络延迟100ms50ms离线环境还需准备可访问的NTP时间服务器内部DNS解析服务至少一台具备外网能力的跳板机用于初始资源下载1.2 镜像获取与校验通过跳板机下载所需资源时务必验证文件完整性# 下载K3s二进制和离线镜像包 wget https://github.com/k3s-io/k3s/releases/download/v1.26.2k3s1/k3s wget https://github.com/k3s-io/k3s/releases/download/v1.26.2k3s1/k3s-airgap-images-amd64.tar # 校验SHA256哈希值 echo 预期的哈希值 checksum.txt sha256sum -c checksum.txt注意不同架构需下载对应版本ARM设备应选择arm64后缀的包2. Harbor私有仓库部署实践2.1 快速搭建Harbor 2.7使用Docker Compose部署生产级Harborversion: 3 services: registry: image: goharbor/harbor:v2.7.0 container_name: harbor environment: - HARBOR_ADMIN_PASSWORDYourStrongPassw0rd volumes: - /data/harbor:/data ports: - 8080:8080启动后执行docker-compose up -d关键配置项说明必须启用HTTPS自签名证书需导入各节点建议开启垃圾回收定时任务访问控制建议采用项目级权限隔离2.2 镜像推送标准化流程将K3s依赖镜像导入Harbor# 加载离线镜像包 docker load -i k3s-airgap-images-amd64.tar # 批量重打标签并推送 for image in $(docker images | grep rancher | awk {print $1:$2}); do new_image${image/rancher/harbor.example.com/library} docker tag $image $new_image docker push $new_image done常见问题处理遇到x509证书错误时需将CA证书放入/etc/docker/certs.d/[harbor_host]推送大镜像时建议调整Docker守护进程的--max-concurrent-uploads参数3. 两种离线安装模式对比3.1 私有仓库模式配置registries.yaml实现透明镜像重定向mirrors: docker.io: endpoint: - https://harbor.example.com configs: docker.io: auth: username: admin password: Harbor12345优势支持自动镜像同步便于多集群统一管理天然兼容Helm Chart仓库劣势需要额外维护仓库服务初期配置复杂度较高3.2 手动导入模式将镜像包放置到固定路径sudo mkdir -p /var/lib/rancher/k3s/agent/images/ sudo cp k3s-airgap-images-amd64.tar /var/lib/rancher/k3s/agent/images/适用场景临时测试环境资源受限的边缘设备安全审计要求严格的场景性能对比测试结果操作类型Harbor模式(s)手动模式(s)首次Pod启动3.22.8并发创建10个Pod12.49.7节点扩展时间28354. 高可用集群部署方案4.1 外部数据库配置使用MySQL作为集群数据存储后端CREATE DATABASE k3s_cluster; GRANT ALL ON k3s_cluster.* TO k3s% IDENTIFIED BY SecureDBpass!;启动首个Server节点INSTALL_K3S_SKIP_DOWNLOADtrue \ K3S_DATASTORE_ENDPOINTmysql://k3s:SecureDBpass!tcp(10.0.0.100:3306)/k3s_cluster \ ./install.sh4.2 负载均衡配置建议使用KeepalivedHAProxy实现API Server高可用frontend k3s_api bind 10.0.0.200:6443 mode tcp default_backend k3s_servers backend k3s_servers mode tcp balance roundrobin server k3s1 10.0.0.101:6443 check server k3s2 10.0.0.102:6443 check关键参数调优保持长连接超时大于5分钟监控端口建议使用/healthz端点生产环境应启用TLS双向认证5. 集群验证与排错指南5.1 健康状态检查验证核心组件运行状态# 查看节点准备情况 kubectl get nodes -o wide # 检查系统Pod状态 kubectl get pods -n kube-system # 测试DNS解析 kubectl run -it --rm --imagealpine test -- sh ping kubernetes.default5.2 常见故障处理镜像拉取失败确认crictl images列出所需镜像检查/etc/rancher/k3s/registries.yaml权限为644查看kubelet日志中的镜像仓库认证错误节点无法加入journalctl -u k3s-agent -f | grep Failed to join可能原因防火墙阻断6443/TCP端口Token过期默认有效期为12小时时间不同步超过5秒网络插件问题 Flannel在离线环境需指定--flannel-ifaceINSTALL_K3S_EXEC--flannel-ifaceeth1 ./install.sh6. 版本升级与长期维护6.1 离线升级流程下载新版本二进制文件替换/usr/local/bin/k3s更新镜像包到/var/lib/rancher/k3s/agent/images/滚动重启服务systemctl restart k3s6.2 自动化升级方案部署System Upgrade Controllerkubectl apply -f https://github.com/rancher/system-upgrade-controller/releases/download/v0.9.1/system-upgrade-controller.yaml创建升级计划示例apiVersion: upgrade.cattle.io/v1 kind: Plan metadata: name: k3s-upgrade spec: concurrency: 1 nodeSelector: matchExpressions: - {key: node-role.kubernetes.io/control-plane, operator: In, values: [true]} serviceAccountName: system-upgrade-controller upgrade: image: rancher/k3s-upgrade:v1.26.2-k3s1实际项目中发现在跨大版本升级时如1.24→1.25需要特别注意CSI驱动和Ingress控制器的兼容性问题。建议先在测试环境验证工作负载的启动情况特别是使用特定Kubernetes特性的应用。