简介针对Kubernetes集群管理平台Rancher v2.4.5的离线部署与迁移需求这份Docker镜像包面向需要在内网环境搭建或维护Rancher的运维工程师、平台管理员以及Kubernetes技术学习者解决从公开仓库逐个拉取镜像耗时长、网络受限等问题。整个zip压缩包共7个文件包含5个tar格式镜像归档、1个yaml网络配置清单和1个Markdown说明文档打包总体积约178.1MB。镜像归档覆盖Rancher Agent、Flannel CNI插件、kube-proxy以及Prometheus Node Exporter等核心组件其中Flannel为Pod网络提供跨节点通信能力Node Exporter用于采集节点监控指标kube-proxy维护服务转发规则配合随包的yaml文件可直接完成网络配置说明文档对导入步骤、镜像用途做了清晰注释方便离线快速复现。目前已有289人学习下载适合需要在内网或隔离环境部署Rancher v2.4.5的Kubernetes管理平台尤其适合多集群统一纳管与离线交付场景。1. 离线部署 Rancher V2.4.5这套 Docker 镜像包到底能省多少事接手过内网 K8s 交付的工程师应该都有同感客户机房不连外网docker pull 拉不动rancher 装了三天还在报错。Rancher V2.4.5 这个版本在 2.x 序列里属于典型的“够用且成熟”UI 稳定、认证链路完整但它的核心痛点就在部署——官方镜像要联网拉适配的组件镜像散在多处离线环境靠手工 docker save 几乎必漏。这套 Docker 镜像包解决的就是这个问题把 rancher/rancher:v2.4.5 主镜像、内嵌 K3s 组件、cattle-agent 系列镜像一次性打包进内网后 load 就能起。适合三类人给客户做离线交付的实施工程师、在隔离网络里自己搭 K8s 管理平台的运维、被 docker 下载慢和权限问题折腾到头大的新手。2. 镜像包结构与启动方式从文件清单到 docker run 参数拿到镜像包先别急着 docker load先花五分钟弄清里面有什么这一步能省掉后面一整天的排查时间。离线环境最大的问题不是镜像本身而是你不知道缺了什么。2.1 拆包先看清单再看镜像一个合格的 Rancher V2.4.5 离线包通常包含四类东西镜像清单文件 rancher-images.txt、导入导出脚本 rancher-save-images.sh 和 rancher-load-images.sh、打包好的 rancher-images.tar以及一份说明了启动参数和版本兼容范围的 README。核心是 tar 包但另外两个文件才是离线部署真正的关键——rancher-images.txt 里每一行对应一个必须存在的镜像少了任何一个Rancher 启动后 UI 可能正常但 local cluster 会一直起不来。文件作用缺失后果rancher-images.txt全量镜像清单逐行列出 repo:tag无法验证导入是否完整rancher-save-images.sh在有外网的机器上批量拉取并导出镜像无法生成离线包rancher-load-images.sh在内网机器上批量导入镜像手动 load 容易漏rancher-images.tar所有镜像的 Docker 归档没有它一切白搭启动脚本 / README记录版本兼容范围和推荐参数参数配错agent 回连失败为什么 Rancher 不像普通 Web 应用那样只打包一个镜像就能跑因为 v2.4.5 启动后会在内部调度一整套 K8s 组件cattle-cluster-agent、cattle-node-agent、kube-api-auth、cluster-proportional-autoscaler 等这些镜像缺一个集群导入或节点注册的时候就会卡住。镜像包的价值就在这里——它把“Rancher 运行时需要的全部镜像”和“下游集群可能用到的组件镜像”一齐打包了而不是只给你一个能画出 UI 的空壳。拆包后第一件事数一下镜像数量。用docker images -q | wc -l和wc -l rancher-images.txt对比数量不一致说明导入有遗漏。不要嫌这一步啰嗦等到集群导入失败再回头看镜像清单你会后悔没早做。2.2 单节点启动docker run 的参数要逐个较真离线镜像导入完成后启动命令不要照抄官方文档。网络通不通、agent 能不能回连全看参数怎么给。单节点场景我一般这样启动docker run -d --name rancher \ --restartunless-stopped \ --privileged \ -p 80:80 -p 443:443 \ -e CATTLE_SERVER_URLhttps://rancher.example.com \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY192.168.1.10:5000 \ rancher/rancher:v2.4.5--privileged不是可选项而是必选项Rancher 容器内部要操作 iptables、mount、cgroup普通权限会在初始化 local cluster 时报权限错误。CATTLE_SERVER_URL必须填下游所有 K8s 节点都能访问到的地址别写 localhost也别写只能在 Rancher 宿主机上解析的短域名——后面导入集群时agent 就是靠这个地址回连 Rancher Server 的。CATTLE_SYSTEM_DEFAULT_REGISTRY是离线环境的核心参数它会把 Rancher 生成的所有 Deployment 的镜像地址统一替换成内网 registry 前缀没有这个参数下游集群创建 workload 时会去公网拉镜像直接卡在 ImagePullBackOff。有一个容易踩的认知误区V2.4.5 的首次登录密码不是通过环境变量注入的。CATTLE_SERVER_ADMIN_PASSWORD是更晚版本才有的特性2.4.5 第一次访问 UI 时会引导你设置 admin 密码。如果你照着新版本的习惯加了这个变量它不会生效UI 依然会让你手动初始化。参数默认值离线环境建议CATTLE_SERVER_URLhttps://服务器IP必须设置为下游节点可访问的域名或内网 IPCATTLE_SYSTEM_DEFAULT_REGISTRY空必须设置为内网 Harbor 或 Registry 地址CATTLE_AGENT_IMAGE自动推断建议固定为内网 registry 中的 rancher/rancher-agent 镜像restart无unless-stopped避免物理机重启后容器失联2.3 docker-compose 也能拉起但它不是高可用方案很多朋友习惯用 docker-compose 管理容器生命周期这没问题Rancher 官方虽然推荐 RKE 编排高可用集群但单机场景下 compose 文件确实更直观。下面这个文件适合作为单节点部署的编排模板尤其适合交给不熟悉 docker run 参数的同事维护version: 3 services: rancher: image: rancher/rancher:v2.4.5 container_name: rancher restart: unless-stopped privileged: true ports: - 80:80 - 443:443 volumes: - ./rancher-data:/var/lib/rancher environment: CATTLE_SERVER_URL: https://rancher.example.com CATTLE_SYSTEM_DEFAULT_REGISTRY: 192.168.1.10:5000注意./rancher-data:/var/lib/rancher这个挂载。Rancher 2.4.x 的数据内嵌 MySQL、证书、集群状态都写在容器内的 /var/lib/rancher 目录不挂载数据卷容器删掉等于整个平台初始化重来已导入的集群全部要重新认证。CATTLE_SERVER_URL和 registry 地址写成硬编码在这里比在 docker run 里传参更清晰后续维护的人一眼就能看懂。但必须说明白边界docker-compose 跑起来的是单机容器不是高可用。V2.4.5 的官方 HA 形态是三个 Rancher Server 节点加外部 MySQL由 RKE 编排数据落在共享存储上。如果客户要求“Rancher 宕机不影响集群管理”单机 compose 是交不了差的该上 RKE 还是得上。compose 方案的定位是快速交付、快速验证、给数据卷做备份恢复演练用。3. 离线镜像导入load、tag、push 三步走完内网分发镜像包到了内网机器上第一件事不是启动容器而是把镜像全部导入并分发到内网 registry。很多人在这一步翻车原因都是同一个只 load 了主镜像组件镜像没导入或者没推全。3.1 bash 脚本批量导入别用 docker load 一个个敲rancher-images.txt 里可能有几十行镜像手动 docker load 不现实。官方脚本 rancher-load-images.sh 的逻辑是先读清单逐行 load再校验镜像是否齐全。如果你拿到的包里没有这个脚本用下面这段做同样的事#!/bin/bash # load-all.sh IMAGE_LISTrancher-images.txt ARCHIVE_FILErancher-images.tar # 导入归档文件 docker load -i $ARCHIVE_FILE # 逐行检查镜像是否存在缺失则报错退出 FAILED0 while read -r IMAGE; do [ -z $IMAGE ] continue if ! docker image inspect $IMAGE /dev/null 21; then echo [MISSING] $IMAGE FAILED1 fi done $IMAGE_LIST [ $FAILED -eq 0 ] echo All images imported successfully.这段脚本的逻辑很直白docker load -i一次导入整个归档然后逐行docker image inspect验证。之所以要二次检查是因为 tar 包在传输过程中可能损坏或者 save 的时候本身就不完整——docker load 不报错不代表每个镜像都在。docker image inspect返回非零退出码意味着这个 repo:tag 不存在必须补镜像。还有一个细节如果离线包只有 tar 没有 rancher-images.txt可以在有外网的机器上先docker save rancher/rancher:v2.4.5 -o rancher-server.tarload 后再用docker run启动并观察日志缺什么镜像就补什么。这种“缺啥补啥”的方式只适合救急不适合批量交付因为 Rancher 某些组件要到特定操作时才触发拉取你永远不知道哪一步会突然崩。3.2 推送到内网 registrytag 命名规则不能乱来镜像导入到内网机器的本地 Docker 之后下一步要把它们推送到内网 Harbor 或 Registry因为 Rancher 创建下游集群时cattle-node-agent 会在各节点上拉镜像不可能每台机器都本地 load 一遍。推送前需要给镜像打上内网 registry 的地址前缀这个步骤有讲究#!/bin/bash # push-all.sh REGISTRY192.168.1.10:5000 IMAGE_LISTrancher-images.txt while read -r IMAGE; do [ -z $IMAGE ] continue # 给镜像加上内网 registry 前缀并推送 docker tag $IMAGE $REGISTRY/$IMAGE docker push $REGISTRY/$IMAGE done $IMAGE_LIST注意$REGISTRY/$IMAGE这种拼法——它保留了原始 repo 路径只加前缀。为什么不能把 repo 名字也改了因为 Rancher 生成的 Deployment 清单里镜像名是固定的比如rancher/rancher-agent:v2.4.5它只会拼上CATTLE_SYSTEM_DEFAULT_REGISTRY指定的前缀。如果你在 registry 里把 repo 改成了自定义的名字Rancher 去拉镜像时对不上照样 ImagePullBackOff。这个是我实际测试过的结论repo 路径必须原样保留只动前缀。推送完成后验证 registry 里镜像是否齐全# 查询内网 registry 中 rancher 相关镜像数量 curl -s http://192.168.1.10:5000/v2/rancher/rancher/tags/list | python3 -m json.tool # 或者直接用 skopeo 检查没有 skopeo 就用 docker pull 抽查 docker pull 192.168.1.10:5000/rancher/rancher:v2.4.5docker push 报权限错误时先确认是否已经docker login过内网 registry再看/etc/docker/daemon.json。insecure-registries配置项是 HTTP 仓库访问的关键内网 Harbor 如果用 HTTP 而不是 HTTPSdaemon.json 里没有这项配置docker push 会直接拒绝连接。3.3 镜像完整性和版本兼容性检查导入完、推送完别急着启动还有最后一道检查要做。V2.4.5 这个版本对 Kubernetes 版本有明确的兼容边界它管理的下游集群建议使用 Kubernetes 1.16 到 1.19 之间的版本。下游版本太新Rancher 2.4.5 的 UI 和 API 可能不兼容集群导入后会出现“集群状态卡在 Provisioning”的假象。# 检查主镜像是否存在且版本正确 docker images | grep rancher/rancher # 检查本地镜像总数与清单行数是否一致 LINES$(grep -cve ^[[:space:]]*$ rancher-images.txt) COUNT$(docker images -q | wc -l) echo 清单行数: $LINES, 本地镜像数: $COUNT # 抽查几个关键的组件镜像 docker image inspect rancher/rancher-agent:v2.4.5 /dev/null echo agent 镜像 OK docker image inspect rancher/kube-api-auth:v0.1.8 /dev/null echo auth 镜像 OK镜像数量对不上优先怀疑两件事一是 tar 包本身不完整二是导入时有镜像因 tag 冲突被跳过。docker load遇到同 ID 不同 tag 的镜像不会报错但会静默跳过导致清单里某些 tag 在本地不存在。用上面这段脚本就能把问题暴露出来。4. 下游 Kubernetes 集群导入kubeconfig 与 agent 回连的真相Rancher Server 跑起来只是第一步真正让客户觉得“值”的是它能统一管理多个 K8s 集群。V2.4.5 导入下游集群有两条路RKE 方式导入和纯 kubeconfig 方式导入。两者的底层逻辑完全不一样选错会让你在“集群一直 Active 不了”的坑里爬不出来。4.1 两种导入方式选型RKE 导入和 kubeconfig 导入的差别很多初次用 Rancher 的人以为“导入集群”就是把 kubeconfig 粘进去就行其实 V2.4.5 里这两种方式的权限模型和功能边界差异很大对比项RKE 方式导入kubeconfig 方式导入前置条件集群由 RKE 工具创建任意方式创建的集群认证方式Rancher 自动生成 agent 证书使用已有 kubeconfig 的 token功能完整度完整可编辑节点、升级、备份受限只能查看和部署 workload底层机制在集群中部署 cattle-cluster-agent通过 kubeconfig 持续轮询 API网络要求下游集群主动连接 Rancher ServerRancher Server 访问下游 API ServerRKE 方式导入的核心是Rancher 会在下游集群里创建 cattle-system 命名空间部署 cattle-cluster-agent由 agent 主动建立到 Rancher Server 的 WebSocket 连接。这意味着网络方向是下游 → Rancher下游集群只要能访问到 Rancher 的 443 端口就行对 Rancher Server 访问下游没有要求。而 kubeconfig 方式导入恰恰相反它要求 Rancher Server 能够访问到下游集群的 API Server 地址——如果你的 API Server 是内网 IPRancher 在另一个网段这条路就走不通。实际操作中我的经验是能用 RKE 导入的集群一定用 RKE 导入功能完整度差太多。但客户环境未必是用 RKE 建的集群那才退而求其次选 kubeconfig。4.2 kubeconfig 导入实操UI 路径和文件字段kubeconfig 导入的 UI 路径在 V2.4.5 里是“全局 → 集群 → 添加集群 → 导入已有集群”输入集群名称后选择“导入”然后粘贴 kubeconfig 内容。kubeconfig 文件长这样apiVersion: v1 kind: Config clusters: - name: my-cluster cluster: server: https://192.168.1.20:6443 certificate-authority-data: LS0tLS1CRUdJTiBDRV... # 通常是一长串 base64 contexts: - name: my-context context: cluster: my-cluster user: my-admin current-context: my-context users: - name: my-admin user: token: kubeconfig-xxxxx导入前先确认三件事server地址是否在 Rancher Server 所在网络可达certificate-authority-data对应的 CA 证书没有过期token对应的 ServiceAccount 有足够的集群权限。Rancher 导入时不会主动帮你验证权限它只是把这个 kubeconfig 存下来后续所有 UI 操作都通过它发请求。权限不足的表现是集群导入成功但集群首页的节点和负载全是空的别急先去检查 kubeconfig 里那个 ServiceAccount 有没有 cluster-admin 权限。4.3 agent 回连失败看日志定位别看玄学集群导入后最常遇到的状态是“Provisioning”转圈半天不切到 Active。这时别去信什么“版本不兼容”“网络抖动”的玄学直接看下游集群里的 POD 状态# 在 下游 K8s 集群 上执行 kubectl -n cattle-system get pods -o wide kubectl -n cattle-system logs -l appcattle-cluster-agent --tail50logs 输出里最常见的两种错误连接超时和证书校验失败。连接超时对应的是 agent 访问不到 CATTLE_SERVER_URL这时先 ping 一下域名再用curl -k https://CATTLE_SERVER_URL/v3看能不能拿到响应如果返回 JSON 而不是连接拒绝说明网络通问题在证书。证书校验失败通常是因为 Rancher Server 用了自签名证书agent 容器里没有对应 CA解决方式是给 Rancher Server 配受信任的证书或者在导入集群时勾选跳过证书校验。另一个高频问题导入 RKE 集群时报“already registered”。原因是集群的 cattle-system 命名空间里残留了旧 agent 部署或者这个集群之前在别的 Rancher 实例上注册过。在集群上执行kubectl delete namespace cattle-system清掉残留后回到 Rancher UI 重新导入即可。5. 避坑内网交付 Rancher V2.4.5 的五条血泪记录这部分记录是我在三个客户现场踩过的坑每一条都花过不止半天排查。未必每条都发生在你身上但知根知底比现查文档快得多。5.1 部署前先做三件“不起眼”的检查内网环境最容易忽略的不是镜像而是基础设施。第一时间同步。Rancher 的 JWT 和证书校验强依赖系统时间节点时间偏差超过五分钟UI 上会表现出登录后接口全部 401。进内网后的第一件事就是配 NTP别着急装容器。第二Docker daemon 的 insecure-registries 配置。内网 registry 基本没有正规 HTTPS 证书不配置这项push 和 pull 全废。第三防火墙和 SELinux。Rancher 容器要占用 80、443下游 agent 回连也要走 443SELinux 不调成 permissive 或加对规则容器启动后网络行为会非常诡异。# 一键检查三项基线 date docker info 2/dev/null | grep -A5 Registry Mirrors systemctl status firewalld --no-pager | head -5 getenforce5.2 逐个问题拆解现象、原因、解决坑 1docker load 完成后镜像列表里没有 rancher/rancher:v2.4.5现象docker load -i rancher-images.tar执行成功但docker images里看不到带 tag 的 rancher 镜像。原因打包的人执行的是docker save $(docker images -q)只导出镜像 ID 不导出 tag。load 进来后镜像变成了none:none没法被 docker run 引用。解决先查镜像 ID再手动补 tag# 找到镜像 ID docker images -q --no-trunc | head -5 # 如果知道镜像 ID补回 tag docker tag IMAGE_ID rancher/rancher:v2.4.5坑 2UI 能打开但登录后接口一直 401集群列表转圈现象浏览器能访问 Rancher UI输入密码后能进首页但所有列表数据加载不出来打开开发者工具看 API 返回 401。原因服务器系统时间偏差导致 Rancher 签发的校验 Token 连带过期。这是内网环境最容易被忽略的问题。解决ntpdate ntp.aliyun.com或配置内网 NTP 服务同步时间后重跑docker restart rancher。如果重启后仍 401需要删掉容器保留数据卷重新docker run数据不会被清掉因为数据卷是宿主机目录。坑 3local cluster 一直卡在 Active 不了agent 容器 CrashLoopBackOff现象服务器安装完 Rancher 后UI 首页的 local 集群状态一直不是 Active点进去以后节点列表为空。原因cattle-cluster-agent 和 cattle-node-agent 连不上 Rancher Server 的 443 或 80 端口。最常见是 CATTLE_SERVER_URL 写错或者 CATTLE_SYSTEM_DEFAULT_REGISTRY 指向的地址在下游节点上无法解析。解决去服务器上看 agent 容器日志确认报错行docker logs --tail 50 $(docker ps -q | head -1) 21 | grep -A3 ERROR\|Fail坑 4导入 kubeconfig 方式的集群后集群是 Active 但所有资源为空现象集群状态是 Active但节点、命名空间、工作负载列表全部空白。原因kubeconfig 中的 ServiceAccount 权限不足。Rancher 不会主动检验权限数据拉不完。解决为 kubeconfig 使用的 ServiceAccount 绑定 cluster-adminkubectl create clusterrolebinding kubeconfig-admin \ --clusterrolecluster-admin \ --serviceaccountdefault:admin-user坑 5HTTP 镜像仓库 push 失败提示 trust certificate现象docker push 到内网 registry 时报错提示证书签名未知。原因docker daemon 默认要求 registry 走 HTTPS而内网 Harbor 是 HTTP。解决编辑/etc/docker/daemon.json加入对应的仓库地址后重启 Docker{ insecure-registries: [192.168.1.10:5000] }改完 daemon.json 一定要重启 Docker并且重启后重新验证docker login 192.168.1.10:5000是否成功。6. 交付后第一件事给 Rancher 做一套可恢复的备份客户机房验收之后我们的活儿其实还没完真正体现专业度的是把备份和恢复方案留下来。Rancher 2.4.5 的高可用方案走 RKE但单机交付场景更多单机最重要的资产是数据卷和集群配置。我要做的备份是“三件套”容器数据卷、RKE 下游集群快照、kubeconfig。# 1. 备份 Rancher 数据卷先停容器再拷贝避免数据库文件不一致 docker stop rancher docker cp rancher:/var/lib/rancher ./rancher-data-backup-$(date %F) docker start rancher # 2. 如果下游是 RKE 集群在 RKE 控制节点上执行 rke etcd-snapshot save --config cluster.yml \ --name pre-upgrade-$(date %F) # 3. 备份 kubeconfig 和全局配置 cp ~/.kube/config kubeconfig-backup-$(date %F).yaml恢复的顺序要反过来先恢复 etcd 快照再恢复 Rancher 数据卷。恢复到全新机器上时用第 2 章的 docker-compose 文件重新拉起容器把备份的 rancher-data 目录挂载回去容器启动后 UI 密码和集群列表应该和备份时完全一致。这里有个验证技巧恢复完后不要直接对外服务先只在本机映射 8443 端口访问一下 UI确认集群列表能正常加载再切换正式端口。从那以后我每次交付完都强制自己走一遍“备份 → 在干净机器恢复 → 验证 UI”的完整演练整个过程纯手动做一次不超过四十分钟但客户机房出问题时这段操作能省下的是几个通宵。数据卷备份这件事希望帮到你。本文还有配套的精品资源点击获取
