企业官网建设流程全解析

最近我把一套跑在RKE集群上的Rancher管理平台从旧机器整体迁到了新环境。Rancher本身不复杂，复杂的是它管理的一堆下游集群——每个下游集群里的agent都只认原来的server-url和证书。迁移过程中，先后经历了备份、恢复、agent重连、证书替换，最后还要处理一堆历史配置残留。这篇文章把我这次基于RKE部署的Rancher管理平台迁移的完整过程、关键命令和后来复盘出来的几个坑都写出来，希望给要做同样事情的人一个参考路径。全文涉及：Rancher版本与K8s版本的对齐、backup operator备份恢复、下游集群重连验证，以及几个我在迁移过程中踩过的典型问题。

1. 先想明白：RKE架构下Rancher迁移到底在迁什么

1.1 RKE与Rancher的分工梳理

RKE（Rancher Kubernetes Engine）是一个通过一条命令拉起Kubernetes集群的工具，它用cluster.yml描述节点信息和集群配置，执行rke up后生成一套可用的K8s集群。而Rancher是跑在这套集群上的容器化应用，通过helm chart安装到cattle-system命名空间，用来管理它所在的local集群以及其他外部集群。

这两个层次一定要分清楚：RKE负责“盖房子”，Rancher负责“住进去做管理”。迁移的时候，房子要重新盖，但里面的家具、账本、住户登记信息都要尽量原样搬过去。这里的“账本”主要就是Rancher在K8s里持久化的各种自定义资源（CRD）、configmap、secret、RBAC，以及底层etcd中的状态。

1.2 为什么不能直接“打包拷贝”

很多人第一次接触Rancher迁移时会想：Rancher不是一堆容器吗？把镜像、数据目录复制过去不就行了？实际上Rancher管理平台的状态高度依赖Kubernetes的API对象和etcd，它内部还有多个controller通过watch机制同步信息。直接拷贝镜像和静态文件完全没有意义，因为：

• Rancher生成的密码、token、私钥存在secret里，单独复制一份出来并不代表可用，对象之间的引用关系必须一起带过去。
• 下游集群通过agent和Rancher保持心跳，agent里记录的是server-url和证书信息，单纯复制会导致agent指向错误的地址。
• Kubernetes本身是分布式系统，它的etcd数据包含节点IP、证书等，不能把一套集群的etcd直接丢给另一套集群用。

可以把这个过程类比成搬家：搬家具容易，但你得先把户籍、水电燃气这些登记信息同步过去，不然新家里通电通水了，原来的账单还是寄到旧地址。迁移的本质是“数据、身份、网络信任”三者的整体搬迁。

1.3 迁移完成后的目标状态

迁移完成后，我们希望达到如下状态：

• 新集群上的Rancher版本和旧环境一致，或者至少满足升级兼容矩阵。
• 登录账号、权限角色、全局设置、用户密码全部保留。
• 下游集群仍然被Rancher管理，agent自动重新注册。
• 审计日志、监控配置等可选组件按需保留。

为此，迁移前需要把旧环境的信息完整记录下来，建议用表格逐项填写：Rancher版本、Helm chart版本、K8s版本、RKE版本、server-url、证书类型、外部认证方式、下游集群数量、以及是否有自定义的CRD或存储配置。

1.4 常见迁移方案对比

方案A：Rancher backup-restore-operator备份恢复。在旧集群安装backup operator，创建Backup CR把Rancher关键资源（resourceSet）备份到S3兼容对象存储或本地路径；新环境反向操作Restore。优点是备份粒度精准、官方维护、适合迁移场景。缺点是这个工具只覆盖Rancher自身状态，底层K8s的网络插件、ingress等需要另建。

方案B：对承载Rancher的K8s集群做etcd快照，然后在新环境用相同的RKE配置重建集群再恢复快照。优点是Rancher本身几乎无感知。缺点是对新旧环境的pod CIDR、service网段、甚至node名称一致性要求很高，灵活性差，不太适合换机器、换机房的场景。

方案C：全新部署Rancher，再手工配置或通过API迁移用户、项目。优点是环境干净。缺点是工作量大、极易遗漏，而且有很多不可复制的内容，比如agent注册token、审计日志历史、部分CRD状态。

我这次采用的是方案A为主，B作为备选兜底。这也是官方推荐路径，下文主要围绕它展开。

2. 动手前先把家底盘清楚：必须带走的数据和状态

2.1 资源清单：不止cattle-system一个命名空间

Rancher在K8s里并不是只往cattle-system里写数据。备份的时候至少要考虑这些对象：

• cattle-system命名空间：Rancher pod、service、相关configmap。
• cattle-pipeline：流水线相关配置。
• cattle-logging、cattle-monitoring、cattle-alerting：日志、监控、告警配置，如果没启用就没有。
• management.cattle.io组下的CRD：Cluster、Project、User、GlobalRole、Setting、Token等。
• secret：包括admin密码hash、服务账户token、agent注册token等。
• RBAC：自定义的角色绑定和权限设置。

使用backup operator时，它默认的resourceSet已经覆盖了这些主流对象。实际操作中，我在Backup CR里显式使用官方预置的resourceSetName，这样不容易漏。不建议手工指定一堆命名空间，因为很容易漏掉某个CRD，等恢复后缺数据再排查就很被动了。

2.2 版本和配置信息盘点：迁移前必须记下来

除了数据，还有几类配置信息必须提前记录。否则迁移到一半会发现server-url指向旧地址，AI大模型都救不了你：

• rancher/rancher镜像版本，以及helm chart版本，用helm ls -n cattle-system查看。
• RKE版本，用rke --version查看。
• K8s版本，用kubectl version查看，或者看RKE cluster.yml里的kubernetes_version。
• server-url，在Rancher UI的全局设置里查看，这是下游agent连接的关键。
• 认证方式：如果用的是本地用户，备份里有密码hash，恢复后原密码仍可用；如果接的是外部LDAP或OIDC，迁移后需要在新环境重新配置认证提供方地址或信任关系。
• ingress证书类型：自签还是受信CA签发。如果在迁移中更换域名或IP，证书也要同步更新。

强烈建议把上面这些写到一个固定文档里，迁移过程中每一步都对照着核对。我的经验是，文档里漏掉一个版本号，后面恢复时可能多花两个小时来排查。

2.3 备份实操：安装backup operator并创建Backup CR

backup operator通过helm chart安装，命名空间是rancher-backup。安装完成后，创建一个Backup CR，结构类似：

apiVersion: resources.cattle.io/v1 kind: Backup metadata: name: rancher-backup spec: storageLocation: s3: bucketName: my-rancher-backups region: ap-east-1 endpoint: s3.example.com resourceSetName: rancher-resource-set encryptionConfigSecretName: backup-encryption-secret

几个字段的意图说下：

• storageLocation：备份文件存到S3兼容对象存储，也可以配置local存到节点路径。生产环境建议S3兼容存储，方便新环境读取。
• encryptionConfigSecretName：可选。如果旧环境有敏感数据需要加密，就得用同样的加密配置，否则新环境restore时解不开。
• resourceSetName：官方预置的资源集，默认使用rancher-resource-set。

创建后观察状态，等状态变为Completed表示备份完成。备份文件会生成一个tar.gz包，里面是包含Rancher资源和CRD定义的一个清单。备份成功后，确认一下输出的文件名，后面Restore要用到。

提示：关于加密secret，如果旧集群里配置了，新集群安装backup operator时也要把这个secret一起建出来，并且内容一致，否则restore会直接失败。这是最容易忽略的坑。

2.4 备份完成后的验证

备份状态Completed不代表万事大吉。建议先下载备份文件，确认tar.gz包大小不是0字节，再用tar解压看一眼里面的资源列表。我遇到过备份文件生成成功，但因为S3接口兼容问题，文件内容是残缺的，到restore阶段才暴露。提前解压验证几秒的事，能省下后面一整天的排查。

3. 新环境搭建：RKE拉起集群时的版本对齐与资源规划

3.1 版本对齐是迁移的第一原则

先决定新环境的K8s版本。原则是：新集群的版本与旧集群一致，或者至少位于Rancher版本对应的支持矩阵之内。版本差太大的话，Rancher chart在restore过程中可能出现CRD版本冲突、API group变更等问题，导致升级不动、pod起不来。

RKE本身也分版本，旧环境用哪个版本生成的RKE，新环境最好也用同一个版本。RKE生成的集群里，kube-system下的一些组件版本和配置会有细微差异，版本不一致会加大后面排查的难度。

另外，如果这次迁移同时想升级Rancher大版本，我的建议是分两步走：先按旧版本迁移，稳定运行后再做升级。不要边迁移边升级，一次只引入一个变量，否则出了问题你不知道是迁移导致的还是升级导致的。

3.2 cluster.yml的关键配置保持一致性

在RKE集群的cluster.yml里，有几个参数会影响Kubernetes网络层和证书层，迁移时尽量跟旧环境保持一致：

• network.plugin：最常用canal或flannel，新旧环境建议一致。
• services.kube-controller的service_cluster_ip_range与cluster_cidr：集群内部地址段，建议保持与旧集群一致。如果变了，Rancher里已存在的服务路由和网络策略可能会出问题。
• kubernetes_version：保持同版本。
• nodes配置：可以用新的主机名和IP，这是允许变化的，因为K8s节点身份会重新生成。

老规矩：改节点IP没问题，但pod CIDR和service网段不能随意改，迁移后很多已创建的服务地址和网络策略都是基于原网段的。

3.3 新环境节点资源规划

Rancher管理平台自身不重，但也不要太寒酸。承载Rancher的K8s集群至少用3个节点组成etcd+controlplane角色，生产建议每个节点4核8G起步，磁盘用SSD并且40G以上。如果还要在下游集群上使用监控、告警，资源再往上浮。

RKE要求节点能访问公开镜像仓库，或者提前把镜像推到私有仓库并在cluster.yml里配置registry认证。新环境的节点时间同步也一定要做好，K8s证书和agent锚定时间，偏差太大会直接握手失败。这些基础项出了问题，后面恢复Rancher时出现的报错会非常奇怪。

3.4 初始化后先做基础验证，别急着恢复

执行rke up之后，先用kubectl get nodes -o wide确认所有节点Ready，再用kubectl get pods -A确认kube-system和ingress-nginx的pod全部Running。这时候先不要急着装Rancher或者做restore，先把网络层验证一遍。比如随便跑一个测试服务，确认集群内部DNS正常、pod之间可以通信。

等基础集群稳定后，再用helm安装Rancher chart。安装时用一个临时的bootstrapPassword即可，后续会被备份数据覆盖。

4. 恢复数据那一刻：backup operator restore实操细节

4.1 恢复前置准备

新环境恢复之前，先把backup operator装上，命名空间同样是rancher-backup。这一步和旧环境安装基本一致，需要注意两点：

• 如果备份时用了encryptionConfigSecretName，新环境要先创建同名secret，内容保持一致。
• 如果备份文件在S3兼容对象存储，新环境要确保网络可以访问这个地址，尤其是私有化部署的对象存储，防火墙规则要提前配好。

4.2 restore CR的编写

restore CR示例：

apiVersion: resources.cattle.io/v1 kind: Restore metadata: name: rancher-restore spec: backupFilename: "rancher-backup-xxx.tar.gz" storageLocation: s3: bucketName: my-rancher-backups region: ap-east-1 endpoint: s3.example.com resourceSetName: rancher-resource-set prune: true

几个字段的意图：

• backupFilename必须指向备份时生成的文件名。
• prune：恢复时是否删除目标集群中已有的、不在备份里的Rancher资源。强烈建议设为true，否则新环境安装Rancher chart时会预创建一些默认对象，和备份数据混在一起容易冲突。
• storageLocation和备份时保持一致。

创建restore后，backup operator会在cattle-system里启动Rancher pod并恢复数据，期间UI可能短时不可用，需要耐心等。观察restore状态到Completed，再删除restore对象。

4.3 恢复后的首次登录和原始凭据

恢复完成后，Rancher会自动重启。用旧环境的管理员账号密码登录，如果用临时bootstrapPassword是登不进去的。如果旧环境密码也没记录，在恢复前提前从旧集群的secret里把admin密码hash导出，或者干脆在迁移前重置一次管理员密码并记录下来。

登录之后，全局设置里的server-url非常关键。如果新环境地址变了，要立刻改过来。改server-url时，Rancher会尝试重新生成下游集群的agent注册配置。

4.4 为什么顺序必须是先有Rancher基础chart，再restore

有人问，为什么不能在一台空K8s集群上直接安装backup operator然后restore？因为restore本质上是把Rancher自身的资源对象覆盖进去，但它没有能力重建Rancher chart全部初始化流程所依赖的骨架。比如cattle-system命名空间的基础对象、ingress、serviceAccount等。先安装Rancher chart可以把这些骨架搭好，然后再用备份数据覆盖血肉。骨架和血肉来自同一个版本时最稳。

4.5 恢复后的第一轮验证

登录Rancher UI后，先看全局设置、用户列表、角色权限是否完整。再进入local集群，看节点负载是否正常。此时下游集群大概率显示Disconnected，不用慌，这一步正常，下一步处理。

5. 迁移后最麻烦的部分：下游集群怎么重新接回Rancher

5.1 失联原因分解

下游集群失联的直接原因通常是：

• agent注册时保存的server-url还是旧地址，DNS切换后连不上。
• 证书不匹配，TLS握手失败。
• Rancher服务端生成的新token没有分发下去。
• 防火墙或安全组没放行新的管理集群端口。

可以这么理解：下游集群的agent就像一台老式电话机，号码簿里记的还是旧号码。你要让Rancher这边的座机先确认自己的新号码，然后想办法把新号码通知给所有电话机。

5.2 先让server-url和证书确定下来

迁移后第一件事，是把全局设置里的server-url改为最终对外地址，并确认证书有效。如果地址变化导致证书不匹配，通常需要：

1. 更新Rancher ingress的TLS secret，换成覆盖新地址的证书。
2. 在Rancher UI的Settings里触发配置刷新。
3. 之后下游集群的agent如果自动重连失败，再手动重发。

如果旧环境用了自签证书，迁移时要保留私钥和完整证书链，不能只带一个crt。私钥不匹配的话，agent全部握手失败，报的都是x509错误。

5.3 自动重连与手动兜底

大部分情况下，只要server-url正确、网络通畅，cattle-cluster-agent和cattle-node-agent会在几分钟内恢复正常。判断方法：

• 在Rancher UI查看下游集群的状态，从Disconnected慢慢变回Active。
• 在下游集群执行kubectl get pods -n cattle-system，看cattle-cluster-agent和cattle-node-agent是否Running。
• 如果仍异常，查看agent日志，常见的是x509证书错误或request timeout。

手动兜底路径：

1. 在Rancher UI进入对应集群的编辑页面，找到Registration Token，重新生成或查看kubeconfig。
2. 拿到该集群的agent manifest。
3. 在下游集群里删除旧的agent Deployment/DaemonSet，让它们重新拉取最新配置。

更直接的做法：在目标集群对应页面，用Edit Cluster重新保存一次，Rancher会重新下发注册命令。

5.4 验证每类角色的状态

可以用一张表辅助验证：

5.5 证书和token的实操经验

如果要保留原有自签证书，新环境必须把旧证书的私钥、证书链完整带入，不能只带一个crt。如果是迁移后重新签发证书，那么下游集群必须能通过新地址验证服务端身份，否则agent全部握手失败。比较省事的做法是迁移后直接换成受信CA签发的域名证书，一劳永逸。

还有一个细节：Rancher的agent注册token是有有效期的，如果迁移间隔太久，token可能已经过期。这种情况下重新生成新token即可。

6. 复盘走过的弯路：典型失败场景与排查链路

6.1 场景一：恢复后Rancher UI起来了，但登录一直报错

我遇到过restore完成后页面反复提示Unauthorized的情况。排查下来发现是临时装的Rancher chart和备份数据的版本不一致，导致admin用户相关CRD冲突。解决方法是把Rancher chart卸载，重新装到与旧环境一致的chart版本，再restore。所以恢复前核对chart版本，绝对不要省。这一条异常重要。

6.2 场景二：下游集群显示Disconnected，agent日志报TLS错误

agent日志里的典型错误是certificate signed by unknown authority或x509: certificate is valid for xxx。这说明agent拿到的证书和当前server-url不匹配。处理步骤：

1. 确认server-url和实际访问地址一致。
2. 确认ingress证书是新地址的有效证书。
3. 在下游集群删除cattle-system下agent相关pod，强制重建。
4. 如果还不行，直接在Rancher里重新生成registration token并apply。

6.3 场景三：新集群上的Rancher pod一直ImagePullBackOff

新环境通常还没配好镜像仓库的登录信息，特别是从私有镜像仓库拉Rancher镜像时。处理手段是提前在节点上配置docker login，或者在cluster.yml和Rancher chart的values里配置imagePullSecrets。旧环境用了哪些镜像，建议提前导出镜像清单，避免新环境临时找镜像。

6.4 场景四：prune没开，恢复后Rancher里混着一堆重复对象

临时安装的Rancher chart会预创建默认的集群对象。如果restore时prune没开，备份里没有的默认对象会留在系统里，看起来像多出来几个服务或项目。它们的资源类型和正常对象混在一起，排查很费劲。所以restore时prune尽量设成true。

6.5 排查思路的层次

总结几条排错顺序：

• 第一层：网络通不通。从下游集群节点执行curl -k https://新server-url:443。
• 第二层：证书对不对。检查证书域名、有效期。
• 第三层：server-url对不对。在Rancher全局设置里看。
• 第四层：Token和agent配置有没有更新。看agent日志和registration token。
• 第五层：版本和CRD有没有冲突。看Rancher pod日志和CRD版本。

按这个顺序走，大部分问题的根因都能定位到前四层。如果真的到第五层，基本就是版本规划的问题，需要回到备份和chart版本匹配这条线上重新对齐。

6.6 一个小建议：迁移前先完整演练一遍

如果你的环境比较复杂，比如下游集群非常多、有自定义RBAC、有外部认证，强烈建议先搭一个临时环境完整演练一遍：备份、恢复、下游重连、验证。演练过程能暴露大部分问题，也会让你对restore的耗时和UI中断时间有预期，真迁的时候心里有底。

回到开头说的那次迁移。整个过程让我印象最深的，不是restore那一下，而是备份清单和版本记录是否完整。只要这些基础信息是齐的，迁移就像按照地图走一遍；反过来，最基础的版本不匹配就能让你卡住半天。以后再接到类似的Rancher迁移任务，我会先花半小时盘点版本、server-url、证书和备份文件，再动手。迁移窗口期尽量选在业务低峰，restore过程中的UI中断时间通常不会太长，但下游集群重新注册的时间取决于集群数量和网络状况。总体来看，基于RKE部署的Rancher迁移只要把握住数据、身份、网络信任这三件事，不会出大问题。