企业官网建设流程全解析

离线安装单节点 Rancher 2.5.11，听起来像是个“退一步”的选择：生产环境不能联网，又需要完整的容器管理能力，只能在内网自己搭一套。但真正动手之后你会发现，离线部署的难点从来不是那几条启动命令，而是镜像、仓库、证书、数据目录这些环节的连锁判断。任何一个环节漏掉，Rancher 可能容器起来了，UI 却打不开、下游集群建不了，或者重启一次数据直接没了。

这篇文章我会把从物料准备、环境配置，到 docker run 启动、日常备份的完整链路拆开讲清楚，包含实操步骤和踩坑记录，适合要在隔离网络里快速搭出 Rancher 管理平台的运维、开发或者架构同学参考。单节点方案不能替代高可用，但它是测试环境、小规模生产场景里性价比很高的一条路。

1. 先搞清楚：离线单节点部署到底解决什么问题

动手之前，先把“为什么要离线”“为什么单节点”这两件事想清楚。部署方案的设计，很大程度上取决于这两个答案，而不是命令本身。

1.1 什么场景会把 Rancher 逼成“离线安装”

最常见的触发条件就是安全隔离。某些数据中心、科研项目、政务系统、生产机房，物理上就和公网切断，或者只允许通过特定的跳板机访问。还有一些企业内网虽然能上外网，但出于合规要求，所有依赖组件的版本必须受控，不允许运行时不定期到公网拉取镜像。此时标准的docker run rancher/rancher:v2.5.11一行命令虽然能拉下镜像，但后续 Rancher 初始化、创建下游集群时，还会去拉一堆系统组件镜像，断网环境就会卡死在 ImagePullBackOff。

另外，有的环境不是完全断网，而是对 Docker Hub 的访问不稳定、时快时慢。这种情况下虽然能联网，但为了部署结果可预测，很多人也愿意选择离线方案：一次性把镜像准备好，后面每次部署都是同一个版本、同一批镜像，完全可控。

还有一类场景是“低频交付”。比如某方案商要给多个客户交付同一套容器管理平台，现场网络千差万别，提前把所有镜像打包成一个交付盘，到现场 load 进来就行。这比现场下载靠谱得多，也给客户留下了“专业”的印象。

1.2 单节点部署的技术定位

单节点，指的是 Rancher Server 以独立容器方式跑在一台机器上。Rancher 2.5.11 这个版本里，docker run启动的容器本质上是内嵌了一个轻量 K3s，Rancher 运行在这个内嵌集群里。这种方式不依赖外部数据库，不需要先搭一套 Kubernetes 再装 Rancher，是单机环境里最省事、最不容易出错的部署形态。

它和高可用（HA）部署的区别很直白：HA 要把 Rancher 部署在一套高可用 Kubernetes 集群上，需要至少三个节点、外置数据库或者 ETCD 集群、负载均衡入口，链路长得多。单节点省掉了这些复杂度，但牺牲的是容错能力。机器一挂，Rancher 就没了，所以数据备份必须作为方案的一部分提前设计。

从经验来看，单节点适合这些场景：测试环境、开发环境、演示环境、小规模生产（比如管理几十个节点的内部集群）。如果是要支撑几百个集群、要求 SLA 的正式生产环境，老老实实上 HA，别拿单节点硬撑。

1.3 整体流程认知：四个阶段

把整个离线部署拆成四个阶段，思路会清晰很多：

1. 物料准备：在能联网的机器上拉取 Rancher 镜像、系统组件镜像，以及对应的镜像清单文件，打包导出。
2. 仓库准备：在离线网内搭建私有镜像仓库，把离线包推送进去，或者至少在目标机器上完成镜像本地导入。
3. 环境准备：配置操作系统、Docker、内核参数、防火墙、数据目录。
4. 容器部署：拉取/加载镜像，启动 Rancher 容器，初始化登录，配置 server-url 和默认镜像仓库。

这四个阶段顺序不能乱。尤其是仓库准备和环境准备，很多人喜欢先启动容器再去想镜像源，结果容器起来了，日志里一堆拉取失败，反而浪费时间。

2. 离线物料准备：镜像、发布包和内网仓库

物料准备是整个离线部署里最费心的一步。原因很简单：你要准备的不只是 Rancher Server 镜像本身。

2.1 版本锁定：为什么不能只看“2.5.11”这个标签

Rancher 的离线安装最忌讳“随手拉 latest”。因为 Rancher 的镜像 tag 和配套的系统组件镜像清单是强绑定的，不同小版本之间，rancher-images.txt里的内容都不一样。锁定v2.5.11之后，所有镜像版本、charts 版本、默认组件版本都以这个 tag 为准，避免出现“Server 镜像 2.5.11 但 agent 是 2.5.12”这种混跑情况。

确认版本是否可用的一个重要动作是核对发布说明。2.5.11 是 2.5 系列里的一个稳定小版本，官方发布页会有对应的镜像列表、发布说明和安装文档。虽然这里是离线环境，但你在联网机器上准备物料时，还是要把这套核对工作做完。版本锁定之后，才会有后面导出镜像清单的前提。

2.2 全量镜像清单：别只拿 Server 镜像

很多第一次做离线的人会这样想：Rancher 是容器，我拉一个rancher/rancher:v2.5.11导过去不就完了？这个思路只对“只跑 Rancher UI、不创建任何集群”的场景成立。只要你想用 Rancher 创建或导入下游 Kubernetes 集群，Rancher 就会在目标节点上拉取一组系统镜像，包括：

• rancher/rancher-agent：下游节点上部署的 agent，用于建立到 Server 的管理通道。
• rancher/pause：Kubernetes 每个 Pod 都要用到的基础暂停容器。
• rancher/mirrored-coreos-etcd：ETCD 容器镜像，用于下游集群的存储节点。
• rancher/mirrored-k8s-*：核心组件镜像，比如 kube-apiserver、kube-controller-manager、kube-scheduler、kube-proxy。
• 网络插件镜像：比如rancher/mirrored-flannel、rancher/mirrored-calico-*、rancher/mirrored-canal-*。
• 附加组件镜像：CoreDNS、Metrics Server、Traefik、NGINX Ingress、Kubernetes Dashboard 等。

这些镜像的完整清单在官方发布页的rancher-images.txt文件里。离线环境正确的做法是：在联网机器上，下载这个 txt 文件以及配套的rancher-save-images.sh、rancher-load-images.sh脚本，然后用脚本一次性把所有镜像拉下来打包。

使用脚本前先看一眼rancher-images.txt的内容，理解一下“离线物料”到底包含多少东西。你会看到几十甚至上百个镜像条目，这是正常的。如果只拿 Server 镜像，后面创建集群会有大量拉取失败，排查起来相当痛苦。

2.3 导出、传输与本地导入

联网机器上准备好清单和脚本之后，执行如下操作：

# 为脚本添加执行权限 chmod +x rancher-save-images.sh rancher-load-images.sh # 拉取全部镜像并打包成 tar.gz ./rancher-save-images.sh --image-list ./rancher-images.txt

执行完成后，你会得到一个很大的 tar.gz 文件，可能几百兆甚至几 GB，取决于镜像数量和大小。这个文件就是离线交付的核心物料。

把小文件（txt 文件和两个脚本）也一起保留，不要只拿 tar.gz。因为后续推送私有仓库时，rancher-load-images.sh还是要依赖rancher-images.txt来遍历镜像名。如果现场只有 tar.gz 没有脚本，手动处理会很痛苦。

把 tar.gz 传到目标网络的机器后，如果只是本机部署，直接导入本地 Docker 即可：

docker load -i rancher-images.tar.gz

导入完成后验证一下：

docker images | grep rancher

注意，这里的“本机导入”方式只解决当前这一台机器的镜像来源问题。如果有多台下游节点都要从这台 Server 获取组件镜像，必须走私有镜像仓库，否则每台节点都要 load 一次，运维成本非常高。

2.4 推送私有仓库的标准姿势

在离线环境里，搭建私有镜像仓库是绕不开的一步。最常用的方案是跑一个 registry 容器，或者用 Harbor。这里我用最基础的 registry 容器演示。

先准备一台内网机器，创建 registry：

docker run -d \ --name registry \ --restart=always \ -p 5000:5000 \ -v /data/registry:/var/lib/registry \ registry:2

如果镜像已经在本机 Docker 里，可以手动 tag 后推送。比如把rancher/rancher:v2.5.11推送到registry.internal:5000：

docker tag rancher/rancher:v2.5.11 registry.internal:5000/rancher/rancher:v2.5.11 docker push registry.internal:5000/rancher/rancher:v2.5.11

但手动 tag 成百上千个镜像显然不现实，所以要直接用官方提供的 load 脚本：

# Docker 已经 load 过 tar.gz 的前提下 ./rancher-load-images.sh \ --image-list ./rancher-images.txt \ --registry registry.internal:5000

这个脚本会自动读取 txt 里的每一行，把本地镜像重新 tag 成registry.internal:5000/<原始路径>，然后推送。执行过程中如果某个镜像推送失败，脚本会打出来，最后再针对失败项单独处理。

这里有一个容易忽略的坑：如果你的 registry 走 HTTP 而不是 HTTPS，目标机器上的 Docker daemon 必须把 registry 地址加进insecure-registries，否则 pull 和 push 都会报证书错误。修改/etc/docker/daemon.json：

{ "insecure-registries": ["registry.internal:5000"] }

改完重启 Docker：

systemctl restart docker

注意在重启之前，最好先确认没有其他容器依赖当前 Docker 状态，避免影响正在运行的业务。

3. 目标节点环境准备：这是大多数人翻车的地方

在导入镜像、启动容器之前，目标节点的系统和运行环境必须先“长”成 Rancher 喜欢的样子。很多人忽略这步，结果容器启动半分钟就退出，日志里全是网络、权限、依赖错误。

3.1 操作系统、内存与磁盘基线

Rancher 2.5.x 对操作系统的要求不苛刻，常见的 CentOS 7.x 和 8.x、Ubuntu 18.04/20.04、RHEL 7.x/8.x 都能跑。但要注意，操作系统内核版本不能太低，Kubernetes 相关功能依赖较新的内核能力，CentOS 7 建议确认内核至少 3.10 且已升级到系统最新补丁。可以用uname -r查看。

内存方面，单节点 Rancher Server 建议至少 4GB 可用内存，基础装上后，Rancher 内嵌 K3s 和容器管理组件会消耗大约 1.5GB 到 2GB。如果计划在同一台机器上跑下游集群的工作负载，内存要按双倍以上考虑。

磁盘占用也不能小看。Rancher 数据目录包含内嵌 K3s 的 ETCD 数据库，如果管理大量集群，数据会持续增长。建议系统盘至少 50GB，数据盘单独挂载，容量给到 100GB 以上比较稳妥。磁盘类型最好用 SSD 或高性能云盘，Rancher 的 etcd 对 IOPS 比较敏感，机械盘在压力下容易出现 apiserver 超时。

3.2 Docker 安装与版本核对

Rancher 2.5.x 官方兼容的 Docker 版本主要是 19.03 和 20.10 系列。安装 Docker 时不要只用“最新”作为标准，应该对照 Rancher 发布说明里的兼容矩阵选择版本。实际项目中踩过 Docker 版本过高导致 Rancher 初始化异常的情况，所以这里建议先锁定一个版本，然后在同一套离线物料里包含对应版本的 Docker rpm/deb 包，现场离线安装。

安装 Docker 后，建议顺手设置开机自启：

systemctl enable docker systemctl restart docker

同时确认 Docker 存储驱动是overlay2，而不是老旧的devicemapper。查看方式：

docker info | grep "Storage Driver"

如果是 overlay2，就不需要额外处理；如果是其他驱动，要考虑重装或升级 Docker，避免后续容器性能问题和兼容性报错。

3.3 内核参数、防火墙与 SELinux

Rancher Server 容器需要启动内嵌 K3s，而 K3s 对内核网络转发、iptables bridge 调用都有要求。最常见的三个内核参数是：

cat <<EOF | sudo tee /etc/sysctl.d/99-rancher.conf net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-iptables = 1 net.bridge.bridge-nf-call-ip6tables = 1 EOF sudo sysctl -p /etc/sysctl.d/99-rancher.conf

如果执行sysctl时报net.bridge相关项找不到，说明br_netfilter模块没有加载：

modprobe br_netfilter

为了重启后依然有效，把br_netfilter写进模块加载配置：

echo "br_netfilter" >> /etc/modules-load.d/rancher.conf

防火墙方面，单节点最少放行 TCP 80 和 443，因为 Rancher UI 和 API 都走这两个端口。如果后面创建下游集群时要使用 NodePort，还要放行 TCP 30000-32767 段。如果只在内部使用，可以直接关掉 firewalld 减少干扰：

systemctl stop firewalld systemctl disable firewalld

但关防火墙要在安全边界允许的情况下做，否则宁可逐条添加规则。

SELinux 也是 CentOS/RHEL 环境里容易被忽略的干扰项。如果 SELinux 没有关闭，Rancher 容器在写数据目录时可能被拒绝。两种处理方式：一种是在/etc/selinux/config里改成SELINUX=permissive后重启；另一种是对数据目录打标签：

chcon -Rt container_file_t /opt/rancher

前者简单粗暴，后者更精细。测试环境可以直接关掉 SELinux，生产环境按安全策略来。

3.4 数据目录规划与持久化思考

单节点 Rancher 的数据都在容器的/var/lib/rancher目录下。如果不挂载出来，容器删除或升级时，所有数据都会消失，包括管理员账号、集群配置、ETCD 数据。所以启动容器之前一定要规划好数据目录。

我一般选择挂载到宿主机的/opt/rancher。这样做的好处是：

• 备份直接打包宿主目录即可，不用进容器看路径。
• 容器重建或升级，数据能继续用。
• 磁盘扩容时，宿主机目录操作更方便。

规划好路径之后，提前创建目录并设置权限：

mkdir -p /opt/rancher chmod 755 /opt/rancher

如果你使用命名卷，比如rancher-data:/var/lib/rancher，也要在启动前就把卷名记清楚，别随便换。后续恢复数据时，卷名不一致会导致数据读不出来。

时区同步也建议在这个阶段做。Rancher 以及后续接入的下游 Kubernetes 节点，对时间一致性很敏感，时间偏差会让证书校验和节点注册失败。安装 chrony 或 ntpd 并确保时间源可达：

systemctl enable chronyd --now chronyc sources -v

4. 单节点 Rancher 容器部署实操

准备工作完成后，终于可以进入正题：把 Rancher Server 容器跑起来。这一节我会给出完整命令，并解释每个参数到底为什么重要。

4.1 镜像是从哪来的：本地导入 vs 私有仓库

启动容器之前，先确定镜像来源。如果你在目标机器上已经docker load过离线包，那 Docker 可以直接用本地镜像启动，不需要网络：

docker images | grep "rancher/rancher"

如果没有做本地导入，只做了私有仓库推送，可以从私有仓库拉取：

docker pull registry.internal:5000/rancher/rancher:v2.5.11

拉下来之后，为了保持镜像名干净，可以再打回原始 tag：

docker tag registry.internal:5000/rancher/rancher:v2.5.11 rancher/rancher:v2.5.11

Rancher Server 自身镜像只需要存在于 Server 所在机器即可。但如果你想让 Rancher 后续从私有仓库拉系统镜像，必须在启动容器时设置CATTLE_SYSTEM_DEFAULT_REGISTRY环境变量。这个变量的值就是你的内网仓库地址，例如registry.internal:5000。它会成为 Rancher 创建下游集群时的默认镜像源。

4.2 带持久化的 docker run 启动命令

这是整个部署的核心命令。我给出的版本是经过多次验证的：

docker run -d \ --name rancher \ --restart=unless-stopped \ --privileged \ -p 80:80 \ -p 443:443 \ -v /opt/rancher:/var/lib/rancher \ -e CATTLE_SYSTEM_DEFAULT_REGISTRY=registry.internal:5000 \ rancher/rancher:v2.5.11

逐个参数说明一下：

• -d：后台运行。
• --name rancher：容器名固定，方便后面docker logs和启停管理。
• --restart=unless-stopped：机器重启后自动拉起容器，除非手动停止。这是单节点部署保命的基础配置。
• --privileged：Rancher 容器需要操作 iptables、挂载文件系统、管理内核模块，没有特权模式会出现各种诡异权限错误。这个参数一定不能省。
• -p 80:80 -p 443:443：暴露 UI 和 API 端口。如果有负载均衡器，可以只映射 443，或者改成自定义端口，但对应关系要提前规划。
• -v /opt/rancher:/var/lib/rancher：数据持久化挂载。
• -e CATTLE_SYSTEM_DEFAULT_REGISTRY=registry.internal:5000：指定系统默认镜像仓库。如果你的所有镜像都直接 load 在每台节点上，不需要私有仓库，这个参数可以不写。但写上有益无害，万一后续要加新节点，能少很多手动操作。

启动后立刻查看状态：

docker ps

期望看到状态为Up，如果状态是Restarting或者Exited，不要反复 restart 同一命令，直接看日志定位原因。

4.3 证书处理与私有 CA 场景

Rancher 默认会在首次启动时生成一套自签名证书，用于 UI 和 API 的 HTTPS 访问。在离线内部环境里，直接使用这套自签证书没问题，浏览器会提示不信任，点击信任即可。团队成员觉得提示烦，也可以把 Rancher 生成的 CA 证书导入浏览器信任库。

如果想要使用企业内部 CA 签发的证书，在启动时额外挂载证书文件，并加--no-cacerts：

docker run -d \ --name rancher \ --restart=unless-stopped \ --privileged \ -p 80:80 \ -p 443:443 \ -v /opt/rancher:/var/lib/rancher \ -v /etc/rancher/ssl/rancher.crt:/etc/rancher/ssl/cert.pem \ -v /etc/rancher/ssl/rancher.key:/etc/rancher/ssl/key.pem \ rancher/rancher:v2.5.11 --no-cacerts

这里的/etc/rancher/ssl/cert.pem和key.pem是容器内固定路径，不能随便改。证书必须包含完整证书链，私钥格式为 PEM，权限也不能太放开，否则容器内进程读取会失败。首次启动前最好用openssl verify验证一下证书链：

openssl verify -CAfile ca.crt rancher.crt

关于 Let’s Encrypt 证书：它的签发依赖公网域名和 HTTP 验证，离线环境基本不可用。所以离线部署要么默认自签，要么走企业私有 CA。别在离线环境里死磕 Let’s Encrypt。

4.4 初始化流程：登录、server-url、内网仓库设置

容器启动之后，还不能马上用，因为 Rancher 需要完成初始化和设置管理员密码。

打开浏览器访问：

https://<服务器IP>

首次访问会进入初始化页面。根据界面提示设置管理员密码。有些 2.5.x 版本会在容器日志里输出初始登录密码，如果页面没有让你设置密码而是要求输入，那么执行：

docker logs rancher 2>&1 | grep -i "bootstrap"

日志里出现的Bootstrap Password就是临时登录密码，用它登录后系统会要求修改。

登录后的第一件事，是检查server-url。路径为“设置 -> Cluster Management -> Server URL”，这个地址必须是所有下游集群都能访问到的 HTTPS 地址。如果部署机有域名，填域名；没有域名，填https://<IP>。这里填错会导致后续导入集群或 agent 连接失败，是最常见的初始化坑之一。

第二件事，确认CATTLE_SYSTEM_DEFAULT_REGISTRY是否生效。在设置里找到system-default-registry项，看值是否为你的内网仓库地址。如果不为空且正确，之后创建集群时，系统组件会从内网仓库拉取，离线链路才算真正闭合。

第三件事，验证 Rancher API 是否健康：

curl -k https://localhost/ping

正常会返回pong。这条命令后续排查“容器活着但服务不正常”时非常有用。

5. 运维闭环：日志、备份与坑位排查

Rancher 容器跑起来只算完成一半，另一半是让它长期稳定跑下去。单节点部署天生没有冗余，所以日常运维必须前置。

5.1 容器健康检查与日志定位

日常巡检先看容器状态和资源占用：

docker ps --filter name=rancher docker stats rancher --no-stream

日志是定位问题的第一入口。查看最近日志：

docker logs rancher --tail 100

持续跟踪日志：

docker logs -f rancher

常见的启动阶段问题包括：

• level=fatal msg="failed to listen on 443"：端口被占用，用ss -lntp | grep 443查，释放后重启容器。
• Failed to connect to localhost:2379：内嵌 ETCD 启动失败，通常是数据目录权限不对，或者以前遗留的/opt/rancher里有损坏数据。
• context deadline exceeded：容器启动超时，常见于磁盘 IO 太慢或者内存不足。

如果一眼看不到明确错误，不要反复重启，先把完整日志保存下来：

docker logs rancher > /tmp/rancher.log 2>&1

然后 grep 其中的error、fatal、failed关键词，一步一定位。

5.2 数据备份与恢复的实操方案

单节点备份，本质上是把宿主机上挂载的数据目录完整复制下来。推荐用最简单直接的方式：

先停止容器，确保数据一致：

docker stop rancher

备份目录：

tar czf /backup/rancher-$(date +%F).tar.gz -C /opt . /opt/rancher

注意这里是到/opt的层级打包，恢复时直接解包回/opt即可。恢复流程：

docker stop rancher mv /opt/rancher /opt/rancher.old tar xzf /backup/rancher-2024-XX-XX.tar.gz -C /opt docker start rancher

启动后用浏览器访问，确认之前的集群和管理员账号都在。如果启动失败，不要删/opt/rancher.old，它就是你最后的物理保底。

Rancher 2.5.x 也提供了基于应用的备份方案，在集群管理里启用 Rancher Backup Operator，支持定时备份到 S3 或本地卷。离线环境如果有内网对象存储，这个方案更优雅，可以配置定期自动备份。但如果只是单机，tar 包方案已经足够可靠，关键是定期执行、异地保存一份。

备份的周期一般是：每天备份一次，保留 7 天。如果集群变更频繁（创建/删除集群、改配置），建议在操作前手动备份一次。

5.3 离线环境常见问题速查表

下面这些是离线部署单节点 Rancher 时出现频率最高的问题，整理成一张速查表方便对照。

每个问题基本都有对应的前置动作可以规避。比如“创建集群卡住”这个问题，提前把rancher-images.txt里的内容全部推送到内网仓库，并在启动容器时设置CATTLE_SYSTEM_DEFAULT_REGISTRY，就能避免。

5.4 给单节点部署套上“保命措施”

单节点最大的威胁是宿主机故障，所以下面几条保命措施建议都做上。

第一，周期备份，而且备份必须复制到另一台机器或对象存储。只放在同一台机器上，那只能叫“备份”，不能叫“灾备”。磁盘挂了，数据目录和备份一起没。

第二，把 Rancher Server 容器和下游集群数据分开。不要让 Rancher Server 所在机器同时充当下游集群的业务节点。因为 Rancher Server 的容器资源使用率高，会影响业务；反过来，业务压力也可能把 Rancher 拖垮。

第三，对管理端口做访问限制。Rancher UI 是管理者入口，默认自签证书的情况下，不要把它暴露到不受信网络。至少加一层防火墙白名单，只允许运维网段访问 443 端口。

第四，资源监控要跟上。单节点 Rancher 最常见的死法是“内存耗尽”。设置一个简单的内存告警，比如使用率超过 80% 就报警，能在问题发生前给你留出时间处理。

第五，升级前务必备份。2.5.11 要升级到同系列的小版本，流程是拉新镜像、停老容器、用新镜像启动并复用数据目录。升级动作有风险，备份是底线，不要在没备份的情况下做版本迁移。

离线环境里的 Rancher 一旦稳定跑起来，你会发现这套内网管理系统其实很好用。它不依赖外网，不受 Docker Hub 波动影响，所有组件版本都掌握在自己手里。但“稳定”的前提，是前期物料要齐全，数据目录要挂载，备份要养成习惯。我个人的体会是，离线部署比在线部署更考验“全局规划”能力——你在联网机器上多花一小时准备镜像，现场就能少折腾一整天。下次再遇到断网环境要搭容器管理平台，不妨按这条链路走一遍，整个过程会顺畅很多。