离线部署Rancher V2.4.5：镜像打包、内网导入与K8s集群接入全指南

简介：针对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 不像普通 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 \ --restart=unless-stopped \ --privileged \ -p 80:80 -p 443:443 \ -e CATTLE_SERVER_URL=https://rancher.example.com \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY=192.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 依然会让你手动初始化。

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_LIST="rancher-images.txt" ARCHIVE_FILE="rancher-images.tar" # 导入归档文件 docker load -i "$ARCHIVE_FILE" # 逐行检查镜像是否存在，缺失则报错退出 FAILED=0 while read -r IMAGE; do [ -z "$IMAGE" ] && continue if ! docker image inspect "$IMAGE" >/dev/null 2>&1; then echo "[MISSING] $IMAGE" FAILED=1 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.tar，load 后再用docker run启动并观察日志，缺什么镜像就补什么。这种“缺啥补啥”的方式只适合救急，不适合批量交付，因为 Rancher 某些组件要到特定操作时才触发拉取，你永远不知道哪一步会突然崩。

3.2 推送到内网 registry：tag 命名规则不能乱来

镜像导入到内网机器的本地 Docker 之后，下一步要把它们推送到内网 Harbor 或 Registry，因为 Rancher 创建下游集群时，cattle-node-agent 会在各节点上拉镜像，不可能每台机器都本地 load 一遍。推送前需要给镜像打上内网 registry 的地址前缀，这个步骤有讲究：

#!/bin/bash # push-all.sh REGISTRY="192.168.1.10:5000" IMAGE_LIST="rancher-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.5

docker push 报权限错误时，先确认是否已经docker login过内网 registry，再看/etc/docker/daemon.json。insecure-registries配置项是 HTTP 仓库访问的关键，内网 Harbor 如果用 HTTP 而不是 HTTPS，daemon.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 方式导入的核心是：Rancher 会在下游集群里创建 cattle-system 命名空间，部署 cattle-cluster-agent，由 agent 主动建立到 Rancher Server 的 WebSocket 连接。这意味着网络方向是下游 → Rancher，下游集群只要能访问到 Rancher 的 443 端口就行，对 Rancher Server 访问下游没有要求。而 kubeconfig 方式导入恰恰相反，它要求 Rancher Server 能够访问到下游集群的 API Server 地址——如果你的 API Server 是内网 IP，Rancher 在另一个网段，这条路就走不通。

实际操作中，我的经验是：能用 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 app=cattle-cluster-agent --tail=50

logs 输出里最常见的两种错误：连接超时和证书校验失败。连接超时对应的是 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 回连也要走 443，SELinux 不调成 permissive 或加对规则，容器启动后网络行为会非常诡异。

# 一键检查三项基线 date docker info 2>/dev/null | grep -A5 "Registry Mirrors" systemctl status firewalld --no-pager | head -5 getenforce

5.2 逐个问题拆解：现象、原因、解决

坑 1：docker 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

坑 2：UI 能打开，但登录后接口一直 401，集群列表转圈

现象：浏览器能访问 Rancher UI，输入密码后能进首页，但所有列表数据加载不出来，打开开发者工具看 API 返回 401。

原因：服务器系统时间偏差导致 Rancher 签发的校验 Token 连带过期。这是内网环境最容易被忽略的问题。

解决：ntpdate ntp.aliyun.com或配置内网 NTP 服务，同步时间后重跑docker restart rancher。如果重启后仍 401，需要删掉容器保留数据卷重新docker run，数据不会被清掉，因为数据卷是宿主机目录。

坑 3：local 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) 2>&1 | grep -A3 "ERROR\|Fail"

坑 4：导入 kubeconfig 方式的集群后，集群是 Active 但所有资源为空

现象：集群状态是 Active，但节点、命名空间、工作负载列表全部空白。

原因：kubeconfig 中的 ServiceAccount 权限不足。Rancher 不会主动检验权限，数据拉不完。

解决：为 kubeconfig 使用的 ServiceAccount 绑定 cluster-admin：

kubectl create clusterrolebinding kubeconfig-admin \ --clusterrole=cluster-admin \ --serviceaccount=default:admin-user

坑 5：HTTP 镜像仓库 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”的完整演练，整个过程纯手动做一次不超过四十分钟，但客户机房出问题时，这段操作能省下的是几个通宵。数据卷备份这件事，希望帮到你。

本文还有配套的精品资源，点击获取