★ FEATURED ARTICLE 家里的测试机房有台服务器一直断外网想搭一套容器管理平台来做演示结果发现这类平台基本都是按“在线拉镜像”的思路设计的没有公网的时候安装流程会卡在镜像获取那一步。折腾了几轮之后我把整个过程收敛成一个核心问题先把镜像准备好再让安装程序能找到镜像。这篇文章就围绕单节点 Rancher 离线安装的关键一步展开讲清楚镜像包怎么准备、怎么传进离线环境、容器怎么启动以及这中间最容易翻车的几个细节。这个内容适合三种人看一是刚接触容器编排、需要在隔离网络里做最小化验证的同学二是公司内部有物理机或虚拟机想要搭建统一管理入口但网络策略很严格只能靠离线包交付的运维同事三是已经装过在线版、想了解离线升级路径的实践者。Rancher 负责管理 Kubernetes 集群单节点方式不追求高可用适合测试、预生产或边缘节点核心诉求是“一台机器、离线环境、能跑起来、能导入集群”。先说结论避免大家浪费时间单节点 Rancher 离线安装的成功率几乎完全取决于镜像包的制作和加载是否完整。安装程序本身是一个容器它依赖的镜像有几十个甚至上百个任何一个缺失都会导致界面能打开但功能不可用或者集群导入后组件反复崩溃。关键一步就是把所有需要的镜像打包、传输、再加载到目标机器的容器运行时里。下面我会把这一步拆开讲。1. 为什么“关键一步”是镜像准备而不是配置文件或安装命令1.1 离线安装的核心矛盾Rancher 的在线安装方式非常简单服务器上装好 Docker然后执行一条 docker run 命令系统会自动从公共镜像仓库拉取 rancher/rancher 以及相关的组件镜像。这个过程依赖公网仓库离线环境里网络不通这条命令就会一直停留在 Pulling 状态直到超时。有人会觉得断网环境下把 docker run 命令里的镜像名称改成私有仓库地址问题就解决了。但这里有个隐藏前提私有仓库里得有这些镜像。而镜像从哪来还是得有网络的时候先准备好。所以离线安装的本质是“转移镜像”不是在目标机器上从头生成镜像。这一步做不好后面所有配置都是空中楼阁。1.2 单节点模式与高可用模式的路径差异Rancher 支持多种部署形态单节点 Docker 安装是最轻量的一种它不依赖 Kubernetes 集群来承载 Rancher 自身而是直接以容器方式运行。这种形态下数据目录是挂载在宿主机上的备份和恢复也比较简单。高可用模式则复杂得多需要先有一套 Kubernetes 集群再用 helm 把 Rancher 安装进去离线时还要准备 helm chart 和对应的镜像列表。单节点模式的优势在于镜像集中、启动参数直观、依赖少特别适合内网演示和功能验证。要理解“关键一步”先要明白我们选择的是单节点容器模式而不是高可用模式因为两者的镜像准备方法差异很大。1.3 两种离线安装路径对比在实际操作中我见过两种常见的离线镜像交付方式方式核心思路适用场景缺点镜像打包传输在联网机器上拉取镜像save 成 tar 文件拷进离线环境后 load单机离线、镜像总量不大tar 包体积大导入耗时私有仓库中转在联网机器上拉取镜像并推送到内网私有仓库目标机器从私有仓库拉取多台目标机器、团队协作需要额外搭建和维护 registry单节点安装用第一种方式更直接初学者也更容易理解。生产环境或者需要重复安装的场景才值得引入私有仓库。无论哪种方式核心路径都是获取镜像列表 - 拉取镜像 - 传输 - 加载 - 让 Rancher 容器使用这些镜像。2. 动手前的三个准备步骤2.1 明确 Rancher 版本锁定镜像列表确定要安装的 Rancher 版本这一步不能省。不同版本的镜像清单和兼容性差异很大比如 2.6、2.7、2.8 这几个常用大版本虽然启动方式大致相同但镜像数量和依赖组件有调整。我建议到官网或更新日志里查一下当前稳定版本记录下准确的镜像版本号比如 v2.7.x 这样的完整标签。为什么要强调完整标签因为 Rancher 镜像列表中的镜像除了 rancher/rancher 主镜像还包括 rancher/rancher-agent、rancher/rancher-webhook、rancher/kubectl、registry、pause、ingress-nginx-controller、cert-manager 的一些组件等。这些镜像分别承担集群管理、调度、网络、证书等职责。如果版本号不一致运行时可能因为镜像拉取策略导致回退或失败。2.2 准备镜像清单的两种手段获取镜像清单我常用的方法是看 Rancher 官方在 GitHub 上发布的镜像列表文件里面按版本列出了全部所需镜像。这个文件通常叫 rancher-images.txt内容格式是一行一个镜像地址。生成这个文件后再按行执行 docker pull 即可。另一种手段是直接运行官方提供的镜像拉取脚本脚本内部会读取镜像列表并一次性拉取。这个方法方便但不一定适用于所有网络环境如果你所在的联网机器有下载限制建议还是自己写个循环逐个拉取失败重试更可控。这里还要注意镜像列表本身也会更新比如安全补丁发布后镜像清单会替换部分组件版本。建议每次安装都用当时最新的列表不要拿半年前的清单来装新版 Rancher否则启动后还会自动尝试拉取新镜像导致离线环境内出现 Pulling 错误。2.3 目标机器的运行时准备目标机器要提前装好 Docker。离线环境下安装 Docker 本身也是个问题但相对简单提前准备好 Docker 的 rpm 或 deb 包内网安装即可。我习惯用 docker-ce 的离线包解压后 binaries 拷贝到 /usr/bin再配置 systemd 服务。这样安装完的 Docker 版本可控不会因为内网源缺失导致版本不符。同时要检查目标机器的磁盘空间。Rancher 主镜像加上相关组件镜像整体占用通常在 5GB 到 10GB 之间。如果还要承载 Kubernetes 集群镜像那空间预留要更充足。我见过因为 /var/lib/docker 所在分区空间不足导致镜像 load 一半就失败的情况排查时还很难一眼看出来原因就是磁盘满了但报错信息指向的是镜像层解压错误。3. 核心实操镜像打包、加载、启动 Rancher 容器3.1 第一步在联网环境生成离线镜像包先找一台能访问公共镜像仓库的机器安装好 Docker。之后的工作都在这台机器上完成。# 假设镜像列表文件名为 rancher-images.txt # 逐行拉取镜像 while read image; do docker pull $image || echo 拉取失败: $image done rancher-images.txt拉取完成后把镜像保存成一个或多个 tar 文件。单个 tar 文件太大时建议按类别拆分比如核心镜像一个包、组件镜像一个包、依赖镜像一个包。这样做的好处是传输时可以并行拷贝导入时也能分段验证。# 将所有镜像保存为一个 tar 包 docker save $(cat rancher-images.txt) -o rancher-images.tar这里有个小技巧如果镜像列表里有重复行或者镜像名和标签写得不规范save 命令会报错。可以在 save 之前先做一次 sort 去重。sort -u rancher-images.txt rancher-images-dedup.txt然后将 tar 包拷贝到离线环境。拷贝介质可以是 U 盘、移动硬盘也可以通过内网 scp。传输完成后在目标机器上校验一下文件完整性尤其是 tar 包比较大时可以用 sha256sum 对比两边哈希避免拷贝过程中文件损坏。3.2 第二步在目标机器导入镜像目标机器执行 docker load 命令。这一步就是把 tar 包中的镜像加载到本地 Docker 的镜像层存储中。docker load -i rancher-images.tar加载过程会有大量输出每一行都是 Loaded image 这样的提示。我建议把输出重定向到日志文件方便后续检查是否有镜像加载失败。加载完成后可以用 docker images 查看当前机器上的镜像列表确认关键镜像是否在列。注意docker load 只是把镜像放到了本地并没有自动推送进私有仓库。如果后续 Rancher 在运行过程中需要动态拉取某些组件镜像而镜像并不存在于本地它仍会去配置的 registry 拉取。所以单节点模式下最好把私有仓库也配置上或者确保所有可能用到的镜像都提前 load 到本地。3.3 第三步配置私有仓库并推送镜像如果你决定使用私有仓库中转方案先在内网搭建一个 registry 服务。单节点测试环境中直接在目标机器上跑一个 registry 容器就可以。# 启动一个简单的 registry 容器 docker run -d -p 5000:5000 --restartalways --name registry registry:2然后把之前加载的镜像重新打 tag推送到内网仓库。# 示例将 rancher/rancher:v2.7.x 推送到内网仓库 docker tag rancher/rancher:v2.7.x registry.local:5000/rancher/rancher:v2.7.x docker push registry.local:5000/rancher/rancher:v2.7.xRancher 容器启动时的镜像地址决定了它后续拉取组件镜像的地址。如果 rancher/rancher 容器本身来自内网仓库但里面的 Carla 的配置还写死为公共仓库地址那么一些组件还是会尝试从公共仓库拉取因此需要配合 Rancher 的启动参数来配置镜像仓库地址。3.4 第四步启动单节点 Rancher 容器启动 Rancher 容器的命令有两种情况一种是直接使用公共镜像启动适用于本地已经 load 的镜像且不需要触发额外镜像的拉取另一种是使用私有仓库地址启动适用于所有镜像都从内网仓库获取。核心启动参数如下docker run -d \ --name rancher \ --restartunless-stopped \ -p 443:443 \ -p 80:80 \ -v /opt/rancher:/var/lib/rancher \ registry.local:5000/rancher/rancher:v2.7.x \ --acme-domain false这里解释几个参数-v /opt/rancher:/var/lib/rancher 是数据目录挂载。Rancher 的配置、Kubernetes 集群状态、用户数据都会写到 /var/lib/rancher 下。挂载到宿主机是为了升级、备份、回滚时方便操作。--acme-domain false 是关闭 Let‘s Encrypt 域名自动签发。离线环境没有公网域名如果保留默认的 acme 配置容器启动后会尝试访问证书签发服务然后失败可能导致初始化流程卡住。-p 443:443 和 -p 80:80 暴露访问端口。如果你不想暴露 80可以只映射 443但 Rancher 的 UI 重定向逻辑有时会牵扯到 80 端口所以我习惯两个都映射。启动后可以查看容器日志docker logs -f rancher日志中出现诸如 “Rancher has started” 这样的提示时说明容器启动完成。首次访问 https://服务器IP/ 会看到一个设置初始密码的页面设置完成后就能登录。3.5 第五步验证功能导入或创建集群登录后第一件事不是急着创建集群而是先验证 Rancher 自带的组件是否正常运行。在界面上查看“本集群”的状态如果显示 Active说明控制面是健康的。如果只是演示可以创建一个新的 Kubernetes 集群或者导入一个已有的集群。导入集群时目标机器需要能访问 Rancher 服务器的地址如果地址不可达节点注册会失败。这一点和离线安装本身关系不大但很容易被误判为离线镜像问题。建议提前确认 Rancher 服务器 IP 和端口防火墙放行 443 和用于节点通信的其他端口。4. 现场问题排查与避坑记录4.1 镜像导入后容器仍然拉取镜像这是我在离线环境遇到最多的一个现象docker load 明明成功了docker images 也能看到镜像但启动 Rancher 容器后日志里依然出现 manifest unknown 或 pull access denied 之类的错误。原因通常有两种。第一种是启动命令使用的镜像名和本地镜像名不一致比如本地镜像标签是 v2.7.0但启动命令写成了 v2.7.1Docker 会尝试拉取远程镜像。第二种是 Rancher 运行时会去拉一些辅助镜像这些镜像不在本地而默认仓库是公共仓库离线环境无法访问。排查思路先在 docker images 里确认本地镜像的准确标签再确认启动命令的镜像标签一致如果 Rancher 还是会尝试远程拉取就需要把相关辅助镜像也 load 进来并在启动参数里加一些仓库配置。简单说容器运行时的镜像来源不只是启动命令那一个镜像这算是一个隐藏知识点。4.2 容器启动成功但 UI 页面证书不受信任离线环境没有合法的公网证书Rancher 默认生成的是自签名证书浏览器会提示不受信任。这在测试环境中很正常选择继续访问即可。如果你有内网证书也可以直接在启动命令中挂载证书目录Rancher 会优先使用挂载的证书而不是自动生成。这个操作涉及证书文件格式最好是 tls.crt 和 tls.key 的组合。没有证书管理经验的话不建议手工处理直接用自签名证书做演示即可。4.3 磁盘空间不足导致数据目录写失败Rancher 运行后会在 /var/lib/rancher 下写大量数据包括 etcd 备份、日志、临时文件。如果这个目录所在分区比较小初期可能看不出问题但运行一段时间后会发现容器变得很卡日志报错也指向文件写入失败。我建议把数据目录放到一个独立分区至少预留 20GB。如果已经出现磁盘满的情况先清理 /var/lib/rancher 下的旧日志和临时文件再考虑扩容。这虽然不是“关键一步”的核心但却是直接影响长期稳定性的因素。4.4 使用代理的坑在部分网络环境下Docker 的拉取操作需要配置代理。但离线环境不允许代理访问公网反而要检查 Docker daemon 是否残留了代理配置。我在一台服务器上碰到过启动 Rancher 失败日志显示网络连接被拒排查半天发现 Docker systemd 配置里有一行 HTTP_PROXY 指向了旧的代理地址而代理服务早已停止。解决办法是检查 /etc/systemd/system/docker.service.d 下的 http-proxy.conf 等文件清掉不再使用的代理配置然后重启 Docker。这个坑很有迷惑性因为问题不在 Rancher 本身而在容器运行时的网络配置。4.5 版本升级时镜像不一致单节点 Rancher 的升级流程是停止老容器用新镜像启动新容器数据目录保持不变。实际操作中容易漏掉的是新版本需要的镜像列表和老版本不同仅仅替换 rancher/rancher 主镜像还不够。我在升级到新版本时踩过坑Rancher 主容器启动后某些组件镜像还是旧版本相互之间不兼容导致集群列表异常。解决办法是升级前先把新版本的完整镜像列表重新拉到本地再执行启动操作。这个流程可以理解为“先补镜像再升容器”。5. 写在最后我从这个“关键一步”里得到的经验重复装了几次单节点 Rancher 之后我对离线安装的理解已经从“执行命令”转变成“管理镜像生命周期”。镜像包不是一次性资产它会随着版本升级而变化所以最佳实践是把版本号和镜像列表文件固定下来连同 tar 包一起归档方便日后复盘或重装。我个人在动手前的检查顺序是查版本号、拉镜像列表、确认磁盘空间、检查 Docker 版本。这四件事只要都做好了单节点 Rancher 离线安装基本不会卡住。真正浪费时间的地方往往不是命令写错而是镜像不完整、证书不一致、代理残留这类看似不起眼的细节。如果你是第一次尝试建议在测试环境里完整走一遍“联网准备镜像包 - 离线加载 - 启动容器”的流程。这个过程大概需要两个小时其中一大半时间花在镜像传输和加载上。走通一次之后之后再装就会顺畅很多。这个内容后续还可以往两个方向扩展一是把镜像包制作流程脚本化做成一条命令自动完成二是引入私有仓库方案让多台机器共享镜像减少重复传输。不过那些都是后话了先把单机装好才是真正的关键一步。
阅读完成 · 觉得有帮助？
