Rancher HA高可用部署实战：K8s集群管理面架构设计与踩坑记录

1. 内容整体设计与思路拆解

1.1 为什么生产环境必须上高可用

先说个真实教训。我见过某团队把Rancher单容器模式跑了一年多，平时看着挺稳，直到某次节点内存飙升触发OOM，Rancher容器直接挂掉，整个K8s集群的控制面瞬间"失明"——不是说业务容器停了，而是你再也无法通过Rancher UI做任何变更、扩缩容、日志查看，连kubectl都要绕道去翻证书才能用。那一刻团队才意识到，Rancher本身挂了，比某个业务Pod挂了的后果严重得多。

所以生产环境部署Rancher，第一条铁律就是：绝不能单点。Rancher作为Kubernetes集群的"管理面"，它挂了不等于业务挂了，但你会失去对集群的掌控力。任何时候失去掌控力，对生产环境来说都是不可接受的。Rancher HA的本质，就是把Rancher Server本身也变成一个由多个副本组成的高可用服务，配合负载均衡器对外提供统一入口。

1.2 Rancher2的架构逻辑：管理集群与业务集群分离

Rancher2的HA架构里有一个容易混淆的概念：管理集群（Local Cluster）和被纳管的业务集群（Downstream Cluster）。

管理集群就是运行Rancher Server的那套Kubernetes集群，Rancher以Deployment形式跑在上面，通常3个节点，加上etcd、controlplane、worker角色的合理分配。业务集群则是你实际跑业务应用的工作集群，可以是Rancher通过UI创建的新集群，也可以是导入进来的已有集群。

这里的关键思路是：管理集群和业务集群尽量物理分离。我见过有人图省事，把Rancher直接装在自己的业务集群里，结果升级Rancher时业务集群一起跟着动，风险面瞬间扩大。生产环境就该老老实实单独搞一套3节点的K8s，只跑Rancher，别放任何业务负载。Rancher官方文档也是这个建议——管理集群保持"纯净"，后续升级、备份、故障恢复都干净利索。

1.3 方案选型背后的取舍

搭建Rancher HA，通常有两三条路可以走：

第一条路，在每台机器上装Docker，用docker run方式把Rancher跑起来，前面再架一层Nginx或硬件LB做负载均衡。这种方式的优点是简单直接，不依赖Kubernetes本身，适合已经有裸机资源、不想额外维护一套K8s的环境，而且Rancher官方早期也支持这种模式。但缺点也明显：副本之间的状态同步依赖etcd-master的额外配置，需要手工维护三个容器的健康检查、日志、升级，Rancher高版本对docker runHA的支持力度也在逐步弱化。

第二条路，先用RKE（Rancher Kubernetes Engine）或者kubeadm搭一套3节点的Kubernetes集群，再把Rancher以Helm Chart方式部署进去。这是目前官方最推荐、也是我实际落地中最稳的方案。优势在于：Rancher本身就依赖Kubernetes API，跑在真正的K8s集群里，天然具备故障自愈、滚动更新、编排调度能力；etcd、控制面组件都交给K8s生命周期管理；后续升级Rancher就是改个Helm values再helm upgrade，比手动换容器优雅太多。

第三条路，用RKE2。RKE2是Rancher后续主推的"下一代"Kubernetes发行版，和RKE最大的区别是内置了etcd快照、嵌入式容器运行时（containerd）、以及更简化的安装方式。如果是新环境、新项目，我倾向于直接用RKE2；如果是老环境已经跑着RKE或kubeadm集群，那就没必要折腾迁移，继续用RKE即可。

我在生产环境里选的是"3节点RKE2集群 + Helm部署Rancher + Nginx四层负载均衡"的组合。为什么不用七层Nginx？因为Rancher UI和Kubernetes API走的是HTTPS WebSocket长连接，七层代理做证书终结反而容易引入连接超时、WebSocket断连的问题。四层TCP转发，把443端口原封不动地透传过去，证书统一在Rancher侧管理，链条短、故障点少，实测最省心。

1.4 需要提前想清楚的生产级需求

动手之前，有几个问题必须跟团队对齐，否则后面全是返工：

• 域名和证书：生产环境肯定不用自签证书，需要提前申请好正式的SSL证书，或者准备好内部CA签发的证书，并确认证书的信任链。我建议在规划阶段就把域名绑定到负载均衡器上，避免后期迁移域名引起证书不匹配。
• 数据备份方案：Rancher的配置数据、etcd快照、还有Rancher自身的etcd目录（如果用的是Docker部署）都要纳入备份体系。生产环境不能等出事才想备份。
• 资源预留：管理集群虽然只跑Rancher，但它要承担很多API请求，同时etcd对磁盘性能敏感。3台节点的规格不能太低，否则Rancher UI会卡顿，etcd会因磁盘IO抖动产生不稳定。

2. 核心细节解析与实操要点

2.1 节点规划与角色分配

我这次用的环境是三台物理机（虚拟机也行，但要注意磁盘IO），假设域名是rancher.example.internal，三台节点分别叫node01、node02、node03。

生产环境的RKE2集群，角色分配上有一个推荐配置：三台节点全部同时承担etcd、controlplane、worker三个角色。为什么？因为集群只有3个节点，如果拆分成2个etcd+2个controlplane+3个worker，每个角色的节点数其实都不够高可用。比如etcd只有2个节点，挂一个就只剩1个，无法形成多数派。三节点全角色，每类角色都是3副本，任何一台宕机，剩余两台依然满足多数派要求，这才是真正的高可用。

但要注意，RKE2默认会安装nginx-ingress和kube-proxy等组件。纯管理集群不需要对外暴露业务流量，ingress可以留着，因为Rancher本身要通过Ingress暴露HTTP服务，后面配置中会用到。

另外，节点时间同步必须做。etcd对时钟漂移极其敏感，时间差超过一定阈值会直接导致集群脑裂。我踩过一次坑：虚拟机宿主机休眠导致三台节点时间差了好几秒，etcd疯狂报clock skew，集群反复进入选举状态，Rancher UI时好时坏。后来统一部署了chrony，配置了内网NTP源，再没出过问题。

2.2 证书策略：内部CA还是公网证书

Rancher默认安装时会生成一个自签证书，浏览器打开会提示不安全，生产环境绝对不能这样用。

我推荐两种做法：

第一种，如果你有内部的PKI体系，比如公司已经部署了AD证书服务或内部CA，可以给rancher.example.internal签发一张证书，并把根证书下发到所有需要访问Rancher的终端。这种方式适合内网环境，成本低，而且一旦内部根证书被信任，各个环境之间的证书管理就统一了。

第二种，直接用公网购买的证书，或者用Let's Encrypt自动签发。Rancher支持通过cert-manager自动申请证书，配置letsEncrypt.email字段即可。不过生产环境变更频繁，我倾向于把证书做成长效证书，避免证书到期前忘了续签导致的意外。

我的实际选择是第一种，内部CA签发，有效期两年。注意证书必须是CA:TRUE签发的，且包含*.example.internal通配符也行，单独域名也行，但一定要包含rancher.example.internal这个SAN条目。Rancher在安装时通过ingress.tls.source=secret指定提供证书的Kubernetes Secret，后续证书要续期时，替换Secret内容然后重启Rancher Deployment即可。

2.3 Helm Chart参数选型

生产环境在Helm安装Rancher时，有若干关键参数值得逐一说明。先给出一个可用的values片段：

# values.yaml hostname: rancher.example.internal replicas: 3 ingress.tls.source: secret privateCA: true bootstrapPassword: "YourStrongBootstrapPass" auditLog: level: 1 maxAge: 30 maxBackups: 10 maxSize: 100

replicas: 3，让Rancher Server的Deployment跑3个副本，配合PodAntiAffinity把副本分散到不同节点上。这里有个隐含逻辑：Rancher UI和API都无状态，数据都落在Kubernetes和etcd里，所以可以放心做多副本。如果Rancher跑的是单副本，那跟单容器模式没有本质区别，谈不上HA。

privateCA: true，告诉Rancher你用的是私有CA证书，Rancher在生成Agent连接信息时会正确带上你的CA链。这个参数漏掉的后果很严重：业务集群的Agent连接Rancher时会因为证书校验失败而一直处于Pending状态，排查半天发现是CA没传。

auditLog配置了审计日志的轮转参数，生产环境的合规需求建议开启审计日志，但要注意控制日志量。level: 1记录的是请求级别的摘要，对排障足够用了。maxSize: 100单位是MB，测试环境可以不设置，生产建议加上。

2.4 负载均衡器的正确姿势

前端负载均衡我用了Nginx，四层配置如下：

stream { upstream rancher_ha { server 192.168.1.11:443 max_fails=3 fail_timeout=10s; server 192.168.1.12:443 max_fails=3 fail_timeout=10s; server 192.168.1.13:443 max_fails=3 fail_timeout=10s; } server { listen 443; proxy_pass rancher_ha; proxy_timeout 120s; proxy_next_upstream on; } }

注意几点：proxy_timeout设长一点，Rancher UI页面里有些操作要调后端API，短超时会导致页面报502。proxy_next_upstream on可以在上游节点异常时自动切换到健康节点，减少单点故障窗口。四层模式不做TLS终止，证书透传到后端Rancher，这个最稳。

如果公司有硬件负载均衡器（F5）或者云厂商的SLB，思路一样：TCP 443转发到3台节点，健康检查用TCP或HTTPS探测。注意健康检查的探测路径不要用根路径，因为根路径可能会被重定向，建议用/healthz或/v3这类可稳定响应的URL。

3. 实操过程与核心环节实现

3.1 RKE2集群安装

服务器基础配置略过，直接讲RKE2部分。RKE2安装非常清爽，官方提供了脚本方式：

curl -sfL https://get.rke2.io | sh -

在3台节点上执行完后，创建配置文件。第一台节点（node01）作为server节点，/etc/rancher/rke2/config.yaml内容如下：

token: my-shared-secret-token tls-san: - rancher.example.internal - 192.168.1.10

token是集群内部各节点通信的共享密钥，3台节点必须一致。tls-san把域名和负载均衡器的虚拟IP写进去，这样生成的API Server证书才会包含这些地址。这一步不做的话，后面Rancher Agent连过来时证书校验会失败，报x509: certificate is valid for xxx, not yyy。

node01启动：

systemctl enable --now rke2-server

然后确认集群起来了：

journalctl -u rke2-server -f

看到apiserver监听地址正常、kubelet也注册成功之后，再在node02和node03上执行同样的安装，但配置文件稍有不同：

server: https://192.168.1.11:9345 token: my-shared-secret-token tls-san: - rancher.example.internal - 192.168.1.10

server指向node01的内网IP和端口9345（这是RKE2的etcd peer端口）。后加入的节点会从这个server节点同步集群状态，然后自动成为集群成员。全部加入完后，通过kubectl get nodes确认三台都是Ready状态。

RKE2会把kubectl和kubeconfig放在/var/lib/rancher/rke2/bin和/var/lib/rancher/rke2/agent里，可以做个软链接方便使用。这一步虽小，但能省去后面反复找kubeconfig的麻烦。

3.2 部署cert-manager和Rancher

RKE2自带了一些组件，但cert-manager和Rancher还是需要自己装。先装cert-manager，因为Rancher的Helm Chart依赖它来管理证书资源。虽然我们用的是自己的secret证书，但cert-manager作为Rancher生态的基础组件，最好还是统一装上，万一以后要用到Let's Encrypt或者内部CA签发，直接就能用。

helm repo add jetstack https://charts.jetstack.io helm repo update helm install cert-manager jetstack/cert-manager \ --namespace cert-manager \ --create-namespace \ --version v1.14.x \ --set installCRDs=true

等待cert-manager pod全部Running之后，创建证书Secret。假设我们拿到了rancher.example.internal.pem和rancher.example.internal-key.pem：

kubectl -n cattle-system create secret tls tls-rancher \ --cert=rancher.example.internal.pem \ --key=rancher.example.internal-key.pem

cattle-system命名空间还不存在，可以提前kubectl create namespace cattle-system。这一步对应values里的ingress.tls.source: secret，Rancher会直接读取这个名为tls-rancher的Secret来配置Ingress的TLS证书。

然后添加Rancher的Helm仓库并安装：

helm repo add rancher-latest https://releases.rancher.com/charts helm repo update helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --values values.yaml

安装过程通常3~5分钟。观察Pod状态：

kubectl -n cattle-system get pods -w

等到rancher这个Deployment的三个副本都变成Running状态，日志中不再有错误，就可以进入初始化环节。

3.3 前端负载均衡配置

Nginx配置按前面stream模块方式写入。但要注意，Nginx的stream模块不是默认编译进去的，安装时选nginx-extras或者自己编译时加上--with-stream。配置完成后，用nginx -t检查语法，然后systemctl reload nginx。

到这里，DNS解析也该配上。公司内网DNS加一条A记录，rancher.example.internal解析到负载均衡器的IP，三台Rancher节点通过负载均衡器对外提供统一入口。所有浏览器、kubectl、Rancher Agent的请求都走这个域名，不走具体节点IP。

配置好之后用浏览器访问https://rancher.example.internal，第一次会要求设置管理员密码和Rancher Server URL。Rancher Server URL必须和hostname对应，否则后面导入下游集群时生成的Agent YAML里的server地址就会不对，导致Agent连不回来。这个坑我们后面细说。

3.4 导入下游集群的完整流程

Rancher HA搭好了，真正的业务集群怎么接入？Rancher支持两种方式：一种是直接在Rancher里创建新集群，Rancher会在对应的云平台或现有节点上自动化部署Kubernetes；另一种是导入已有集群。生产环境里，很多团队已经有自己用kubeadm、二进制或者云厂商托管的K8s集群了，这时候用导入最方便。

导入时Rancher会给出一段YAML，内容是一个rancher-agent的DaemonSet和Secret。在目标集群上执行：

kubectl apply -f rancher-agent.yaml

Agent启动后会反向连接到Rancher Server，也就是主动訪問https://rancher.example.internal，然后注册集群信息。

这个过程中最常遇到的错误是Agent Pod日志里不断出现x509证书错误，或者Connection refused。前者多半是Rancher Server URL你填成了某个节点IP，而证书里没有这个IP；后者是网络不通，目标集群访问不到负载均衡器IP。排查思路很直接：

• 在目标集群的节点上curl https://rancher.example.internal/ping，看能不能返回pong。
• curl -v看证书链是否完整，确认私有CA的根证书有没有被Agent信任。如果Agent所在的K8s集群之前没有安装过私有根证书，就只能在生成Agent YAML时选择"跳过证书校验"（Rancher UI里有个选项），或者手动把根证书注入节点的/etc/ssl/certs。生产环境不建议跳过校验。

导入完成后，在Rancher UI的集群列表里能看到目标集群状态变为Active，然后就可以正常管理了。Rancher HA本身的管理集群（叫local）也会出现在列表里，这个没事，是正常的。

3.5 Rancher自身的etcd快照与备份方案

说完导入，补充一个很多人忽略的部分：Rancher本身的数据备份。Rancher通过Helm部署后，它的大部分配置（全局设置、用户、项目、集群凭证）都存在管理集群的Kubernetes里，特别是Rancher创建的各种CRD对象和Secret。这些数据都受Kubernetes管理，所以备份的关键是备份etcd。

RKE2自带了快照功能，非常值得用起来。在/etc/rancher/rke2/config.yaml里加配置：

etcd-snapshot-schedule-cron: "0 2 * * *" etcd-snapshot-retention: 5

每天凌晨2点自动打快照，保留最近5份。快照文件默认放在/var/lib/rancher/rke2/server/db/snapshots。为了异地容灾，建议再用脚本把快照同步到对象存储或者公司的备份服务器上。这是底线，至少保证管理集群的etcd出问题后能在几小时内恢复。我写过最简单的同步脚本：

#!/bin/bash find /var/lib/rancher/rke2/server/db/snapshots -name "*.zip" -mtime -2 | xargs -I {} scp {} backup@backup-server:/data/rancher-etcd-backup/

配合crontab每天执行一次，数据就基本不丢了。

4. 常见问题与排查技巧实录

4.1 Agent连不上Rancher：证书与URL不匹配

这个可以说是Rancher HA搭建里遇到频率最高的问题。症状是导入集群时，Agent Pod反复CrashLoopBackOff，日志里出现：

ERRO[000x] Failed to connect to proxy: x509: certificate is valid for rancher.example.internal, not 192.168.1.10

原因基本就是两个：一是Rancher Server URL你填了节点IP或者和证书SAN不一致的地址；二是负载均衡器的健康检查指向了某个具体的节点IP，而证书里没有这个IP。解决办法：

• 确认Rancher UI -> 全局设置 ->server-url的值必须和证书域名一致。
• 确认RKE2的tls-san包含了所有客户端可能访问的地址（域名、VIP、节点IP）。改tls-san后需要重启相关组件，实际操作中可能是重生成证书并重启kube-apiserver等容器，这是停机操作，要在维护窗口做。
• 如果是Internal CA，还要确认Agent节点信任了根证书。Rancher Agent容器启动时会尝试加载本地系统的CA证书链，如果根证书没装进去，就必须在生成的YAML里明确指定CA哈希或者跳过校验。

我在实际操作中总结了一个快速排错顺序：先kubectl logs看Agent错误是网络层、TLS层还是认证层。网络层报connect: connection refused，先去检查负载均衡器和防火墙；TLS层报x509，去查证书SAN和server-url；认证层报401或token相关，那十有八九是导入YAML里的Secret有问题，重新在UI里生成一份即可。

4.2 Rancher UI偶发502

负载均衡器配置没问题的情况下，UI偶尔502多发生在Rancher副本滚动更新或者节点资源紧张时。排查路径：

• 看Nginx错误日志，确认是connect() failed还是upstream timed out。
• 如果是connect() failed，看后面的地址指向哪台节点，去那台节点上看Rancher Pod状态和节点负载。
• 如果是upstream timed out，多半是某个操作触发了慢查询或Rancher ApiServer过载，把proxy_timeout再调大一点，并检查Rancher Pod的内存使用情况。

生产环境我建议给Rancher Deployment设置资源请求和限制。如果节点的内存只有8G，同时跑etcd、Rancher、各种系统组件，节点内存经常逼近临界值，Rancher Pod被OOM Kill的概率很高。这时优先调整K8s调度策略，让Rancher Pod跑在三节点里空闲较多的一台，并设立资源配额，避免被系统组件挤死。

4.3 etcd磁盘IO抖动导致集群不稳定

etcd对磁盘延迟非常敏感，尤其在fsync上。我的经验是：生产环境用SSD/NVMe是基本要求，机械硬盘或者网络存储运行etcd就是给自己挖坑。如果已经遇到IO抖动，日志里会出现大量wal fsync failed或者apply request took too long，集群选举会频繁发生。

解决方案：

• 给RKE2的max-request-bytes、quota-backend-bytes这些参数感觉太大时，可以先检查磁盘是否被打满。quota-backend-bytes默认值相对安全，但快速增长的集群要注意在config.yaml里显式设置大一点：

etcd-arg: - "quota-backend-bytes=8589934592" - "max-request-bytes=10485760"

• 同时把节点上的其他IO密集型业务（比如日志采集、监控Agent）挪到别的机器上，保证etcd读写性能。

4.4 Rancher升级时的注意事项

Rancher版本升级是生产环境最紧张的操作之一。Rancher官方要求不支持跨版本跳跃升级，必须一个一个主版本递进。

升级前备份是必须的。我的标准流程是：

kubectl -n cattle-system get deployments rancher -o yaml > rancher-deploy-backup.yaml kubectl -n cattle-system get secrets -o yaml > rancher-secrets-backup.yaml

然后执行helm upgrade。升级后先用日志确认Rancher API能正常响应，再观察下游集群的Agent连接状态，最后才放量让团队进UI操作。曾经有次升级后，Rancher UI能看到集群列表，但点进某个集群一直转圈，后来发现是旧版cattle-cluster-agent的镜像没更新，手动删除cattle-cluster-agent这个Deployment让Rancher重建即可。

升级前还要确认当前的Rancher版本对应的Kubernetes版本。管理集群是RKE2版本如果太老，可能不兼容新版的Rancher，所以先升RKE2再升Rancher，顺序不能反。

4.5 常见问题速查表

4.6 再补一个细节：防火墙与安全组

整个链条上，有很多端口需要提前放通。负载均衡器到三台Rancher节点的443端口；Rancher节点之间的9345（etcd peer）、6443（kube-apiserver）、10250（kubelet）等端口；如果是RKE2 Agent节点，还需要放行12379~12381范围的etcd端口。端口不通，集群能起来但节点间的通信时好时坏，问题非常隐蔽。

所以我在给每台机器配防火墙时，都会先执行一遍ss -lntp看清楚实际监听端口，再逐条配置。别只看官方文档的端口清单，因为不同版本、不同网络的端口可能略有差异，以实际监听的为准。

5. 后续扩展与运维建议

5.1 监控告警的补充

Rancher HA搭完之后，最好立刻接上监控。管理集群的etcd、Rancher Pod本身都需要盯。我常用的是Prometheus Operator + kube-prometheus-stack，配合Grafana仪表盘。重点关注几个指标：etcd的fsync耗时、Rancher Pod的OOM次数、3个副本Pod的分布情况、负载均衡器的后端健康检查状态。

告警规则里至少要有一条：任意一台Rancher节点上的Pod副本数少于3时告警。这条规则能第一时间发现节点故障或Pod驱逐，比业务监控更直接。

5.2 灾难恢复演练

Rancher HA搭起来只是第一步，真正的生产保障是演练。强烈建议每季度做一次"模拟节点宕机"演练：手动停掉一台节点上的RKE2服务，观察集群是否自动完成恢复，Rancher UI在5分钟内是否重新可用，etcd是否有数据丢失。这个动作看起来简单，但真做一次你就会发现，很多平时没暴露的问题全浮出来了。

我演过最极端的情况：三台节点里两台同时宕机。这种情况下管理集群已经无法形成多数派，Rancher会进入只读或不可用状态。真正恢复需要找出健康的节点，手动编辑etcd成员，或者直接用快照恢复。这个过程的详细步骤虽然没写在这篇手顺里，但建议团队提前准备好一份"节点全挂恢复手册"，别等事故来了再查文档。

5.3 关于节点扩缩容的建议

管理集群要扩充节点也是常见需求，比如发现3台扛不住并发API请求了。RKE2的扩缩容非常简单：新节点安装RKE2并配置相同的token和server地址后加入即可。注意扩容后要确认PodAntiAffinity规则依然生效，Rancher副本会均匀调度到新节点上。缩容反而要小心：先kubectl drain然后kubectl delete node，再停止对应节点的RKE2服务，保证etcd成员数量不因此少于3个。管理集群的etcd节点最好保持奇数且不少于3个，否则高可用无从谈起。

最后的几点体会

这套Rancher HA手顺我前前后后在多个环境里落地过，最难的不是命令本身，而是很多默认配置在关键时刻给你使绊子。比如tls-san没配、私CA没传、Server URL填错，这些都是"配置一条少，排查两小时"的典型坑。后来我养成了个习惯：把Rancher HA的所有外部依赖列成一张清单——DNS解析、证书SAN、负载均衡健康检查路径、节点时间同步、etcd快照保留策略，逐项打勾确认后才算真正初始化完成。

还有一个非常容易忽略的体验：Rancher HA搭好后，日常使用中你根本感觉不到它是HA——UI照常打开，操作照常响应。直到某天机房报修、某台节点断电，你才发现UI依然能访问、集群操作依然正常，那一刻才真正体会到前面所有工作的价值。生产环境的可用性，从来不是靠运气，而是靠提前把每个环节的冗余度都设计到位。

最后再分享一个小技巧：把安装过程中用到的所有命令、配置参数、版本号，整理成一份可复现的脚本和文档，放在团队内部知识库里。Rancher版本升级、节点重建、证书续期这类操作，直接对照文档执行，远比临时翻官方文档、现查现试要稳得多。踩过的坑记录下来，后面的人就能少踩一遍。