接手过不少生产环境，也帮人排过不少Rancher部署的坑，单节点离线安装其实是个挺典型的场景。尤其在内网环境、政务云、工业现场这类地方，没外网、没DNS、甚至没镜像仓库，装一套Rancher能把人折腾到怀疑人生。网上教程不少，但大多只告诉你“执行这个脚本就行”，至于为什么要这么干、哪一步是成败关键、踩了坑怎么排查，讲得不多。这篇就把我实际跑过的完整流程和核心心得捋一遍，重点聊聊那“关键一步”——离线镜像包的准备和导入。
这个方案适合谁？就是要在完全离线的环境里，用一台机器把Rancher单节点跑起来，作为后续纳管K8s集群的入口。也适合那些想搞明白Rancher离线装到底卡在哪、怎么绕过坑的运维和平台工程师。我自己走过几遍这个流程，中间踩过镜像tag不对、私有仓库地址写错、导出包不完整这些坑，后面一个个都解决了。这篇文章就按我的实操顺序来写，从环境规划到验证落地，把关键细节和排查方法都交代清楚。
1. 整体思路拆解：先搞明白离线安装到底难在哪
先说结论，单节点Rancher离线安装，本质上只有两件事：第一，把Rancher运行所需的镜像全部搞到内网；第二，让内网环境能加载这些镜像并正常启动Rancher。听起来简单，实际卡住80%的人的，都是第一件事的细节。
1.1 为什么离线安装比在线安装麻烦这么多
在线安装很简单，一条命令拉镜像、起容器就完事。但离线环境没有镜像源，Rancher依赖的镜像又多又碎。我第一次做离线部署的时候，光镜像列表就扯了半天，有的带v2.7.5这种具体版本号，有的又是什么rancher/rancher-agent之类的中间产物。如果你在装Rancher之前，对“这个平台要拉哪些镜像、它们之间的依赖顺序是什么”没有整体概念，后面百分之百会出问题。
这里先普及一个背景知识：Rancher用容器化的方式部署自己，而它又负责管理K8s集群。所以它既要自己有镜像，又要内置一套K8s组件的镜像。你要做的事，就是把这一整套镜像包都导进内网。
1.2 关键一步：镜像包从“有网机器”到“离线集群”的搬运
整个离线部署可以拆成五大步，其中第三步是成败的关键，我后面会重点讲：
- 在一台能访问公网的机器上，按照目标Rancher版本拉取官方镜像列表。
- 把镜像列表里的所有镜像，从公网源拉下来，保存成tar包。
- 把tar包传到离线机器的私有镜像仓库里，并保证Rancher启动时能从这个仓库拉镜像。
- 在内网机器上配置好私有仓库地址、证书，然后执行业务初始化脚本。
- 启动Rancher容器，验证UI和K8s集群状态。
如果从架构思路来讲，第3步就是真正的“心脏”。原因很简单：Rancher容器起不来，不是因为它缺代码，而是因为它在启动的一瞬间要拉镜像。你把tar包导进去了，但仓库地址没配对、tag对不上，它照样启动失败。
1.3 选型考量：单节点场景下为什么推荐“私有仓库+tar包”组合
有人会问，我就一个节点，能不能直接把tar包用docker加载上去，然后直接跑Rancher，不搭私有仓库？答案是不建议。
单节点实验环境可以这么干，但真实的生产内网环境，你后面还要用Rancher去创建K8s集群，K8s节点在创建时也会拉一串镜像，不可能每台节点都去手工docker load一遍。搭建一个私有镜像仓库（比如Harbor或Registry），让Rancher和K8s节点都从这个仓库拉镜像，才是标准的离线玩法。这也是官方脚本为什么要先把镜像推到仓库里的原因。
2. 前置准备：版本选型和镜像清单生成细节
动手之前，版本定死是个特别容易被忽略的细节。我之前见过有人装了最新的Rancher主版本，结果内置K8s版本匹配不上，后面创建集群的时候全是奇怪报错。这个版本不是你在界面上看到的那个主版本号，而是具体的v2.x.x小版本号。
2.1 先定K8s版本还是先定Rancher版本
Rancher和K8s版本有对应关系表。我的习惯是，先想清楚内网里要跑的K8s大概在哪个版本段（比如1.24还是1.26），然后反向找Rancher版本。为什么要这样？因为Rancher要内置对应K8s的镜像，版本匹配不上，后面装出来的集群很可能处于非官方支持状态，排查的时候人会疯。
选定版本之后，去Rancher官方仓库把对应版本的镜像列表拉下来。这个列表长什么样？就是一行一个镜像名，从rancher/rancher核心镜像到各种rancher/mirrored-*开头的基础组件镜像，可能上百个。如果你是在有网机器上操作，一般官方脚本会自动生成这个列表，不需要手工去抄。
2.2 清单生成过程中的一个常见误区
很多第一次离线安装的人，拿到镜像列表之后，第一反应是把整个列表直接丢给脚本拉取，结果发现拉到一半就失败。为什么？因为列表里有一部分镜像是给特定架构用的，比如AMD64之外还有ARM64的变体。如果你的有网机器或者内网服务器是ARM64，但你拉的是AMD64的包，导入的时候轻则浪费空间，重则镜像跑不起来。
正确操作是：先确定目标节点的CPU架构，然后过滤镜像列表，只保留对应架构的镜像。这一步看似简单，但实际操作时，docker pull的时候会默认拉当前机器的架构，所以如果你在有网机器上操作，直接拉出来的就是这台机器的架构。也就是说，准备离线包用的中转机，架构最好和内网服务器保持一致。
提示：架构不一致导致的启动失败，在排查时非常难发现，日志里通常只会告诉你“exec format error”或者“无法找到镜像”，不会直接提示架构问题。
3. 实操过程：从构建镜像包到完成离线导入
这里是文章的重点，我把每一步都拆开来，结合我实际操作过的命令和思考逻辑来写。准备好了吗，接下来是真正的干活环节。
3.1 在有网机器上拉取镜像并导出tar包
首先，在有网机器上安装好Docker，并且能够访问正常的镜像源。然后把清单保存成images.txt，每行一个镜像名加tag，格式如：
rancher/rancher:v2.7.5 rancher/rancher-agent:v2.7.5 ...然后写一个循环脚本去拉这些镜像。为什么不一条一条手动拉？因为镜像数太多了，上百个镜像一个个敲命令太不现实。用类似下面的循环脚本，把失败重试也加进去：
while read img; do docker pull "$img" || echo "pull failed: $img" done < images.txt拉完之后，用docker save把所有镜像打包成一个tar文件。注意，这里我建议把所有镜像打成一个包，而不是每个镜像单独打包。原因很简单，单个大文件在传输和导入时要省事得多。
docker save $(cat images.txt) -o rancher-images-all.tar包打好之后，顺手检查一下文件大小。Rancher加配套K8s组件的镜像包，几个GB到十几个GB都很正常。如果包太小，八成是镜像列表不全，后面导入完会发现某些组件还是拉不到。
3.2 在离线机器上搭建私有镜像仓库
离线机器的Docker装好后，需要起一个私有仓库服务。这里我以Registry为例，轻量够用；如果内网环境更大，要多个团队共用，可以上Harbor，但单节点场景Registry往往就够了。
启动Registry容器的命令：
mkdir -p /opt/registry/data docker run -d \ -p 5000:5000 \ --restart=always \ --name registry \ -v /opt/registry/data:/var/lib/registry \ registry:2为什么用registry:2而不是别的版本？因为这是最稳定的Registry镜像版本，兼容性也最好。操作的时候注意，如果你的内网DNS没有给这台机器配域名，直接用IP加端口访问仓库即可，比如192.168.1.10:5000。后面Rancher配置的仓库地址，就用这个IP加端口，尽量别用机器名，否则证书和地址解析容易出问题。
3.3 关键一步：重新打tag并推送到私有仓库
这一步就是我说的最关键环节。很多人导完tar包，就以为万事大吉了，直接去启动Rancher，然后发现日志里全是镜像拉取失败的报错。原因很简单：你从公网拉下来的镜像，镜像名里带着的是原始仓库路径，比如rancher/rancher:v2.7.5，而内网私有仓库地址是192.168.1.10:5000。Rancher不会自己知道该去哪找镜像，它还是会去默认的公网地址拉，结果当然拉不到。
所以，你需要把这些镜像全部重新打tag，改成私有仓库的地址前缀，再推送到私有仓库。具体命令形如：
docker tag rancher/rancher:v2.7.5 192.168.1.10:5000/rancher/rancher:v2.7.5 docker push 192.168.1.10:5000/rancher/rancher:v2.7.5这个动作要循环对每个镜像执行。自己写脚本可以这么来：
while read img; do new_img="192.168.1.10:5000/${img}" docker tag "$img" "$new_img" docker push "$new_img" done < images.txt这段操作是整个离线安装过程中最麻烦但最必要的一步。你以为你在给镜像“改名字”，本质上是在给Rancher建立一套它能理解的内网寻址方式。这一步做错了或者漏做了，后面所有步骤都白搭。
3.4 Rancher安装脚本与证书配置的实际处理
镜像推到私有仓库之后，下一步就要处理Rancher的安装配置了。Rancher官方支持通过Helm或Docker命令安装单节点。离线环境下，我建议直接使用Docker命令，因为Helm在线拉chart又是一个新的网络瓶颈，没必要给自己找麻烦。
用Docker方式启动单节点Rancher，核心命令长这样：
docker run -d --restart=unless-stopped \ -p 443:443 -p 80:80 \ -e CATTLE_BOOTSTRAP_PASSWORD=${密码} \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY=192.168.1.10:5000 \ -v /opt/rancher:/var/lib/rancher \ --name rancher \ 192.168.1.10:5000/rancher/rancher:v2.7.5注意这里的CATTLE_SYSTEM_DEFAULT_REGISTRY环境变量，这一行就等于告诉Rancher：你去所有镜像默认从192.168.1.10:5000拿。这就是和3.3遥相呼应的关键配置。如果不加这个变量，即使你3.3里把镜像都推到私有仓库了，Rancher启动时依然会自觉去公网找镜像，然后失败。
还有两个细节值得强调：
- 密码环境变量：有些版本支持用
CATTLE_BOOTSTRAP_PASSWORD设置管理员初始密码，但我建议第一次启动时不刻意设置，让他随机生成，然后到日志里拿临时密码登录，再改密，这样更稳。 - 数据目录的持久化：
/var/lib/rancher一定要挂到宿主机目录，这个目录存了Rancher所有的配置和状态数据，容器删了重起数据不能丢。
3.5 验证安装成功：镜像拉取不再报错就是最大胜利
启动Rancher容器后，别急着访问UI，先看容器状态和日志。这一步我有强迫症，每次都要确认：
docker logs -f rancher日志里如果出现Bootstrap Password相关信息，说明容器核心启动逻辑正常。再观察一会儿，没有镜像拉取失败的报错，没有反复重启，基本就成了。用docker ps看容器状态，应该是Up，而不是Restarting。如果一切正常，访问https://你的内网IP，能看到Rancher的欢迎页，输入密码即可进入。
4. 常见问题排查：离线安装最容易踩的坑
离线部署Rancher这种东西，难点不在于步骤有多深奥，而在于容错率低。出了问题，日志不会告诉你“因为你是离线环境所以失败”，只会给你一个模糊的错误。下面这些坑是我自己踩过或者帮别人排查过的，按出现概率排个序。
4.1 镜像推送到私有仓库后，Rancher拉取还是失败
这大概是最常见的问题，没有之一。现象是：日志里提示manifest unknown或者repository ... not found。
排查思路：
- 先看
CATTLE_SYSTEM_DEFAULT_REGISTRY环境变量设置没有，没设置或者写错了，Rancher绝对不会去私有仓库拉。 - 确认私有仓库里真的有对应镜像。直接浏览器访问
https://192.168.1.10:5000/v2/_catalog，或者用docker pull手动测试一下。 - 确认镜像的tag是否完整，很多离线包在save和load过程中会丢掉tag，导出导入后变成
<none>，这种情况需要重新打tag。
这里有个我自己的排查小技巧：先在Rancher机器上手动执行docker pull 192.168.1.10:5000/rancher/rancher:v2.7.5。能拉通，说明仓库没问题，问题在Rancher配置；拉不通，说明仓库或网络有问题，就不用去Rancher那边纠结了。
4.2 容器启动后反复重启，日志里提示找不到镜像
这个情况通常是两种情况之一：
- 镜像tag写错了。比如Rancher镜像明明是
v2.7.5，你启动命令里写成了latest，而仓库里没有latest这tag，当然起不来。 - K8s组件镜像没推全。Rancher启动时可能需要内部的K8s组件镜像，如果你导入的镜像列表不全，它会去默认仓库拉，然后失败。
解决办法倒不复杂：补全镜像列表，重新走一遍3.3的推送流程，然后重启容器。但这提醒了一件事，第一次准备镜像列表时，尽量用和Rancher版本配套的完整清单，不要随手砍掉几个你觉得“用不上”的镜像。离线环境里，你省掉的每一个镜像都可能变成后续的一个坑。
4.3 私有仓库HTTPS证书导致Docker登录失败
如果你的私有仓库配了TLS证书（尤其是自签证书），而内网机器不信任这个证书，执行docker login或docker push时会报x509: certificate signed by unknown authority。
处理方案有两种：
- 最好：把自签证书放到每台需要访问仓库的机器的
/etc/docker/certs.d/目录下，并把仓库地址按目录结构组织好，例如/etc/docker/certs.d/192.168.1.10:5000/ca.crt，然后重启Docker。 - 临时方案：在
/etc/docker/daemon.json里配置"insecure-registries": ["192.168.1.10:5000"]，跳过证书验证。
我个人的建议是能用证书就用证书，尤其是要长期维护的内网环境。配insecure-registries虽然方便，但每次你在内网机器上执行涉及私仓的操作时，都会隐隐觉得不踏实。
4.4 tar包导入后镜像全成了<none>，怎么处理
用docker load导入tar包时，理论上会自动还原镜像名和tag，但实际操作中遇到过导入后docker images显示一堆<none>的情况。这多数是因为tar包打包时，docker save的参数或者镜像列表有重复镜像名，导致元数据覆盖。
处理办法：删掉这些<none>镜像，重新从有网机器生成一遍tar包，注意把镜像列表去重之后再save。我后来为了省事，干脆写了个小脚本，保存前先对镜像列表做去重和排序，这样导出的tar包干净很多。
5. 稳定运行的一些后续建议
Rancher装完了、UI也能访问了，工作其实只完成了一半。单节点部署属于All-in-One架构，这个节点挂了，整个管理面就没了，所以后续稳定运行要做的事也不少。
5.1 数据备份不可省
单节点Rancher的数据全在/var/lib/rancher目录下，建议至少每天把这个目录备份一次。我习惯配合定时任务加tar打包，然后传到内网另一台存储机器上。恢复方法也不复杂，把备份的目录解压回去，重新启动容器就行。不要迷信主机硬盘不会坏，真的遇到过硬盘故障然后数据全没的情况，那滋味不太好受。
5.2 定期检查磁盘空间
镜像包好几个G，私有仓库数据也会越积越大，Rancher自身的日志和etcd数据也在涨。单节点机器磁盘一旦满了，表面上看只是启动不了新容器，实际可能连带导致Rancher数据库损坏。建议设个监控，磁盘使用率超过80%就预警。
5.3 版本升级要留后路
后面如果想升级Rancher小版本，离线情况下依然要走镜像准备、推送、替换容器这套流程。升级前先把当前数据目录完整备份一下，再拉新版镜像包。别直接在旧包基础上升级镜像tag，很多组件版本是耦合的，混着升极容易出问题。
5.4 多架构环境的额外提醒
如果你内网里同时有AMD64和ARM64的机器，后面用Rancher创建集群时，节点镜像也要区分架构。那就不只是Rancher本身的镜像问题了，K8s组件镜像都需要两套架构的包，提前规划好目录结构或者仓库项目空间，能省不少重复劳动。
说实话，单节点Rancher离线安装这件事，难度不大，但门槛不低。难不在技术深度，而在你能否把一个多步骤流程里的每一环都串起来理解。镜像清单准备要全，私有仓库地址要对，tag要修正好，缺一个环节就起不来。上面这套流程是我实际操作中反复调整后沉淀下来的，照着走一遍，大多数内网环境都能顺利跑通。要是中间哪个环节还是卡住了，建议回头重点检查镜像tag和私有仓库地址这两处，绝大多数离线安装的疑难杂症都能在这两个地方找到答案。
