简介Rancher平台部署与运维的完整技术手册面向系统运维、DevOps工程师以及容器云项目实施人员解决从环境规划到Rancher集群上线的实操问题。资源以单个docx文档交付大小6.16MB内容覆盖部署前置要求硬件、操作系统、软件、网络、主机名、开发/测试与生产环境集群拓扑设计Docker安装配置与开机自启、时钟同步Harbor镜像仓库部署、项目配置与镜像清理Rancher镜像准备与实例部署并延伸到RKE集群搭建、kubectl和helm工具安装文档后半部分还给出Dockerfile示例、镜像构建与推送流程可作为日常构建镜像的参照。章节采用编号目录并带版本变更记录便于快速定位和追溯已有543人学习下载适合处于容器云建设初期的团队也是Rancher多集群运维场景的实用参考资料。1. 把 Rancher 平台部署与运维拆开看多集群管理为什么不能靠 kubectl 硬扛当团队手里的 Kubernetes 集群从 1 个变成 5 个问题往往不是「怎么装 K8s」而是「怎么让几十个人在多个集群之间切换不混乱」。Rancher 平台部署与运维这件事核心不是把 Rancher 装起来而是把散落在多个集群上的认证、权限、监控、证书、升级这些运维动作收拢到一个入口里。Rancher 的价值就是给 Kubernetes 加了一层可交互的管理面导入已有集群、创建新集群、按项目划分权限、统一查看资源状态。适合的人群也很清楚要维护多个集群的运维工程师、给团队提供自服务平台的平台组、以及不想天天和 kubeconfig 打交道的业务开发。下面从部署路径开始一步一步把方案讲透。2. 部署 Rancher Server单节点与高可用两条路径怎么选2.1 单节点 Docker 部署最小成本跑通全流程Rancher Server 本身是一个容器应用最常见的起步方式是直接跑 Docker 单容器。这条路径适合预发环境、个人实验、或者下游集群数量很少个位数的场景目的是先把「管理面」完整跑起来再决定要不要上高可用。# 拉取 stable 镜像并启动 Rancher Server docker run -d --name rancher-server \ --restartunless-stopped \ -p 80:80 -p 443:443 \ --privileged \ rancher/rancher:stable这段命令里几个关键点值得说明。--privileged是 Rancher 容器运行所必需的它需要在内嵌的 Kubernetes 集群中操作 iptables 和挂载点-p 80:80 -p 443:443把管理界面的 HTTP 和 HTTPS 端口暴露到宿主机后续下游集群的 agent 也是通过这两个端口回连镜像 tag 建议用stable而不是latest避免某次latest升级引入行为变化导致 Server 重启异常。启动后用浏览器访问https://服务器IP首次进入会要求设置 admin 密码和 Server URL这个 URL 必须填下游集群能够访问到的地址填错了后面导入集群会全部失败。单节点部署的边界要提前知道Rancher Server 内嵌的 etcd 就在容器里docker stop再做docker start一般没问题但宿主机断电、磁盘写满这类异常恢复会比较痛苦。所以我的习惯是单节点只用来验证流程和功能生产环境至少给三台机器做准备。2.2 高可用部署RKE 引导集群加 Helm 安装的常见组合生产环境的标准路径是先用 RKERancher Kubernetes Engine创建一个用于承载 Rancher Server 的 Kubernetes 集群再在集群里通过 Helm 安装 Rancher Chart。这样 Rancher Server 本身也是跑在 K8s 上的工作负载节点挂了可以调度etcd 也在独立的节点上可备份、可恢复。# 1. 准备 cluster.yml三节点其中两个用于 etcd controlplane nodes: - address: 192.168.1.11 user: ubuntu role: [controlplane, etcd] - address: 192.168.1.12 user: ubuntu role: [controlplane, etcd] - address: 192.168.1.13 user: ubuntu role: [worker] # 2. 创建引导集群 rke up --config cluster.yml # 3. 安装 cert-managerRancher 的证书签发依赖 kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/版本/cert-manager.yaml # 4. 通过 Helm 安装 Rancher helm repo add rancher-latest https://releases.rancher.com/server-charts/latest helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --create-namespace \ --set hostnamerancher.example.com \ --set bootstrapPasswordadmin123这里要解释清楚一个容易混淆的地方RKE 只是用来搭建承载 Rancher 的「引导集群」Rancher 本身是通过 Helm Chart 安装到该集群的。bootstrapPassword是首次登录时用来设置 admin 密码的随机凭证生产环境建议改成强密码并通过密钥管理方式传入而不是直接写在命令行里。安装完成后kubectl get pods -n cattle-system看到 rancher Pod 处于 Running再访问配置的 hostname 完成初始化。为什么不用 Docker 单节点跑生产因为 Rancher Server 一旦承担了多个生产集群的认证和调度转发它的可用性就直接决定了所有下游集群的「管理可用性」。即使下游集群本身还能对外提供服务管理员没法登录控制台、没法改权限那种状态已经算半个事故了。高可用部署虽然前期多花半天时间但后面每次升级、重启、迁移节点都会感谢当初这个选择。2.3 资源规划与部署前准备Rancher Server 本身不算重真正吃资源的是内嵌的监控、日志、审计组件以及管理大量下游集群时的 API 缓存。我一般按下游集群数量和节点规模给如下参考管理 15 个集群引导集群至少 3 台 4C8G管理 10 个以上集群或单集群节点超过 50 个引导集群节点建议升到 8C16G 并把 etcd 放到独立 SSD 上。磁盘方面etcd 所在节点给 50G 以上容器镜像和日志另算。资源维度轻量使用≤5 下游集群较重使用10 下游集群引导集群节点数3 台35 台单节点 CPU/内存4C 8G8C 16Getcd 节点磁盘50G SSD100G SSDServer 端口80 / 44380 / 443可加 6443环境准备阶段有三件事别偷懒第一所有节点的系统时间必须同步etcd 对时钟偏移极其敏感建议配置 chrony 并纳入巡检第二hostname 要规划好Rancher 导入集群后节点名会出现在 UI 上一堆ip-172-31-1-1会让你在排查问题时多花很多时间第三防火墙端口要提前确认下游集群到 Server 的 443 出站必须通Server 到下游集群的 kube-api 端口默认 6443出站也要通否则集群导入后 agent 会反复报错。3. 接入并管理下游集群从导入集群到 RBAC 划分3.1 导入已有 K8s 集群一条命令背后的 Agent 机制如果团队已经有了用 kubeadm、二进制方式或云厂商托管服务创建好的集群最常见做法是走「导入集群」这条路径。在 Rancher UI 上点击「创建集群」并选择「导入」Rancher 会生成一段用于在目标集群上执行的命令通常长这样curl --insecure -sfL https://rancher.example.com/v3/import/集群ID.yaml | kubectl apply -f -这段命令真正做的事情是在目标集群的cattle-system命名空间下创建一套资源和 ServiceAccount并启动cattle-cluster-agent与cattle-agent两个工作负载。Agent 以反向连接方式与 Rancher Server 通信也就是说不需要目标集群把 6443 端口暴露给公网只要 Agent 能访问到 Server 的 443 端口即可。这也是 Rancher 能够管理云上托管集群的原因——集群本身可以不对外暴露 API。这里有个参数要特别注意--insecure是因为 Server 用了自签名证书时 curl 会报证书错误才加上的。如果 Server 已经配置了 Lets Encrypt 或企业 CA 证书去掉--insecure会更安全。不过即使保留它也只影响下载 manifest 这一步Agent 后续与 Server 通信仍然会校验证书只是这里的跳过会埋下一个不安全的观感。我的建议是在测试环境把命令跑通后尽快给 Server 换一个可信证书然后重新生成导入命令让生产集群走安全链路。3.2 新建集群还是导入集群两类场景的取舍场景推荐方式理由已有 kubeadm/二进制自建集群导入保留原集群控制面与节点规划Rancher 只做管理云厂商托管集群EKS、ACK、GKE导入托管集群本身有控制面Rancher 不需要参与建集群从零交付一套新环境新建Rancher 通过 Node Template 在主机上装节点开箱即用边缘节点批量接入新建 自定义脚本可以配合主机初始化工具批量拉起如果是从零开始且基础设施以裸机或虚拟机为主「新建集群」会让你省掉手工装 K8s 的步骤。Rancher 会在选定的主机上自动部署 Kubernetes 组件并通过 Node Template 实现节点的预配置。但要注意一点Rancher「新建集群」生成的 Kubernetes 版本是由它自身维护的发布渠道提供的版本选择会比上游 Kubernetes 官方少一些对版本有强依赖的场景建议还是自建集群然后导入。3.3 项目和命名空间以团队为单位的权限边界Rancher 里的「项目Project」是一个比命名空间更高一层的概念。一个项目可以包含多个 Kubernetes 命名空间同一个项目下的命名空间可以共享资源配额和一组用户权限。运维实践中我通常这样划分一个业务线建一个项目项目内按环境拆分命名空间比如order-prod、order-staging再把对应的团队成员绑定到项目角色上开发默认只给「查看」或「项目成员」权限只有技术 lead 给「项目所有者」。验证权限配置是否生效不一定要依赖 UI。在引导集群或下游集群上可以用 kubectl 模拟用户身份来检查# 以普通用户身份尝试访问指定命名空间 kubectl --asuser-dev get pods -n order-staging # 预期结果如果 RBAC 配置正确这里要么能列出资源要么明确返回 Forbidden kubectl --asuser-dev get pods -n order-prod这个做法的价值在于把权限验证变成可重复执行的脚本而不是靠人工在 UI 上点。只要--as验证通过说明 Rancher 生成的下游 kubeconfig 对应的 RBAC 规则是对的。Rancher 在向用户签发 kubeconfig 时会把用户在项目上的角色映射成下游集群的 RBAC 规则这个映射关系出问题的时候UI 上看着有权限实际却Forbidden用上面的方式能快速定位是映射问题还是集群本身 RBAC 异常。4. 日常运维证书、备份、升级与监控四件套4.1 证书生命周期不要等到集群失联再处理Rancher 默认生成的证书是自签名的有效期为一年。最典型的故障场景是某天早上进控制台发现所有下游集群变成「Unavailable」排查发现是 Server 的证书过期下游 Agent 和 Server 之间的 TLS 握手全部失败。证书问题不是一次性配置完就结束的必须主动纳入巡检。# 查看当前证书到期时间以下游集群访问的 Server 域名为例 echo | openssl s_client -servername rancher.example.com -connect rancher.example.com:443 2/dev/null | openssl x509 -noout -enddate # 轮换 Rancher Ingress 证书仅适用于 Server 使用自签名证书的场景 kubectl -n cattle-system delete secret tls-rancher-ingress删除tls-rancher-ingress这个 Secret 后Rancher 的证书管理组件会自动签发一个新的自签名证书。但如果你给 Server 配置的是外部证书比如企业 CA 签发删除默认 Secret 并不会生效反而可能让 ingress 找不到证书导致页面直接 502。对这种环境正确做法是替换cattle-system命名空间下对应的证书 Secret并确保 Ingress Controller 的--default-ssl-certificate参数指向新的 Secret。无论哪种方式操作前先确认 Rancher 的 UI 设置里显示的是自签名证书还是自定义证书。4.2 etcd 备份唯一能买的「后悔药」Rancher Server 的引导集群承载了所有下游集群的元数据和用户权限配置这部分数据一旦丢失虽然下游集群本身还能跑但管理面的重建代价极高。所以备份的核心对象是引导集群的 etcd。RKE 部署的集群可以直接用 RKE 命令做快照# 按日期命名做一次性快照 rke etcd snapshot-save --name daily-$(date %F) --config cluster.yml # 快速恢复思路注意生产恢复前要暂停写入流量 # rke etcd snapshot-restore --name daily-2024-01-01 --config cluster.ymlrke etcd snapshot-save会把快照保存在 etcd 节点上的/opt/rke/etcd-snapshots目录并保留一份在本地。建议把快照同步到对象存储里而不是只存在原节点上。Rancher UI 里也自带部署备份工具通过 Backups 应用配置 S3其本质同样是定期对引导集群做 etcd 快照并上传。我个人的习惯是双重备份RKE 做日级快照配置保留 7 天再每周用 UI 里的备份工具传一份到 S3。这样即使某台机器整体损坏也能从远端拉回快照恢复。恢复操作最容易翻车的地方在于时间点etcd 快照恢复会让引导集群回到过去某个状态如果你在这之后创建了下游集群那些集群的元数据会消失需要重新导入。恢复不是「后悔药随便吃」吃之前要确认两点一是数据丢失的窗口和快照时间点的关系二是恢复后所有下游集群的 Agent 是否还连着。4.3 版本升级与 Agent 同步Rancher 的升级节奏和 Kubernetes 类似小版本迭代频繁跨大版本升级需要谨慎。常规升级路径是先备份、再看 Release Notes、再用 Helm 升级 Server。# 更新 chart 仓库并升级 Rancher helm repo update helm upgrade rancher rancher-latest/rancher \ --namespace cattle-system \ --set hostnamerancher.example.com升级 Rancher Server 后要特别注意一个现象Server 版本新了但下游集群的 Agent 还是旧版本。Rancher 的做法是兼容一段范围的 Agent 版本超过这个范围 UI 会显示集群状态异常。此时需要到每个集群的「工具」菜单里手动点击「升级集群 Agent」。如果 Agent 升级一直失败先看 Pod 日志大概率是因为目标集群无法拉取新版 agent 镜像——内网环境需要提前把镜像同步到私有仓库并给cattle-system命名空间配置 imagePullSecret。跨大版本升级比如从 2.6 到 2.8 这一类的跨度不能跳级。如果当前版本中间隔了多个大版本Release Notes 里通常会写清楚要分两步还是一次性升级。我踩过一次坑直接从旧版跳到新版结果 Rancher Server 启动后数据库迁移脚本报错只能回滚到中间版本再走一遍迁移。所以升级前先用helm list记录当前版本再确认目标版本和前一个版本之间的兼容性说明。4.4 监控告警落地不用另起炉灶用内置 MonitoringRancher 自带监控方案是对接 Prometheus 生态的。在集群页面安装 Monitoring 应用后会部署 Prometheus、Grafana 和告警规则UI 里能直接看到集群和节点的核心指标。相比自己维护一套 Prometheus operatorRancher 内置方案减少了部署和升级的联动成本。需求内置 Monitoring自建 Prometheus 或外部 SaaS快速看到集群基础指标推荐开箱即用不推荐成本高与 Rancher UI 的告警联动好一般需自己配置 webhook多集群统一查询Rancher 层面聚合需要自己部署 Thanos长期存储与高基数指标弱默认保留时间短按需配置告警配置上我一般会优先关注三组指标etcd 的 leader 变化次数、节点内存和磁盘使用率、以及 apiserver 的错误率。Rancher 内置的告警规则里已经覆盖了前两类但 apiserver 错误率这类更细的规则建议自己在 Monitoring 里补上。日志方面Rancher 的 Logging 功能可以对接 Elasticsearch、Splunk 等后端但它的定位是「采集与转发」不负责长期存储和数据清洗。如果团队已经有统一的 ELK 或 Loki 体系Rancher 的 Logging 值得用如果没有不建议为了看日志而单独引入重量级链路。5. Rancher 部署运维避坑5 个真实的「现象→原因→解决」5.1 下游集群导入后一直 Pendingagent 反复 CrashLoopBackOff现象导入集群命令执行成功但集群状态在 UI 上卡在 Pending查看cattle-cluster-agentPod 发现处于 CrashLoopBackOff。原因最常见的是 Agent 无法访问 Rancher Server 的 443 端口或者 Server 的自签名证书不被 Agent 信任。解决先做连通性验证在一台和 Server 网络互通的机器上执行curl -v https://rancher-server-ip/healthz确认端口通、证书能正常响应再登录目标集群查看 agent 日志kubectl -n cattle-system logs agent-pod-name如果日志里出现x509相关报错说明证书信任有问题。证书层面优先给 Server 配置可信证书而不是想方设法让 agent 跳过校验临时验证时可以在 agent Deployment 的环境变量里调整 CA 配置但生产环境不要长期这么挂。5.2 Rancher Server 容器重启后页面 502控制台直接不可用现象宿主机重启或 Docker 服务重启后访问 Rancher 页面出现 502等待 10 分钟仍未恢复。原因Rancher 容器内嵌的 etcd 在异常停机后可能发生数据损坏或者宿主机内存不足导致容器被 OOM Kill。前者表现为日志里有wal相关的错误后者表现为启动后反复退出。解决先看docker logs rancher-server最近的日志和系统dmesg确认是 OOM 还是 etcd 异常。OOM 就调整宿主机资源后重启容器etcd 数据损坏时不要试图裸启动旧容器去反复挂载数据盘正确做法是使用最近的 etcd 快照恢复。这一步也印证了为什么生产环境不建议单节点部署——单节点的数据恢复手段太单一。5.3 证书过期导致所有下游集群失联现象某天 UI 上所有下游集群状态变为 Unavailable执行任何 kubectl 命令都超时检查发现是 Server 的证书过期。原因Rancher 默认自签名证书有效期一年到期后 Server 与 Agent 之间的 TLS 握手失败Agent 无法上报心跳所以集群全部显示失联。解决按 4.1 的方法轮换证书删除tls-rancher-ingressSecret 等待签发新证书然后滚动重启所有下游集群的cattle-cluster-agent让 Agent 以新证书重新建立连接。这里最容易翻车的是如果你用的是外部证书删除默认 Secret 会适得其反。所以操作前先去 UI 的「设置」里确认证书来源再做对应处理。5.4 升级 Server 后集群 Agent 版本间隙过大现象Server 升级成功但某个下游集群 UI 上出现黄色警告提示 Agent 版本不兼容某些功能不可用。原因Rancher 的 Server 和 Agent 存在版本兼容区间跳版本升级 Server 后Agent 被落下了。解决到该集群的「工具」菜单点击「升级集群 Agent」等滚动更新完成。如果升级 Agent 一直失败看镜像能否拉取内网环境需要先推送新的 agent 镜像到私有仓库并把cattle-system的 Secret 配好。这里给个经验升级 Server 前就把下游集群逐个升级 Agent 到当前 Server 的兼容版本再升 Server 本体能少一半告警。5.5 导入 manifest 时 curl 报 x509 证书错误现象执行curl --insecure -sfL ... | kubectl apply -f -时如果去掉--insecure直接报x509: certificate signed by unknown authority。原因Server 使用自签名证书或企业内网私有 CA执行命令的机器没有导入对应 CA 证书。解决临时验证用-k或--insecure下载 manifest 没问题但生产集群导入后要把 CA 证书分发到各节点系统信任区并配置容器运行时信任私有 CA。否则后续 Agent 在目标集群内拉取镜像或与 Server 通信时还会遇到证书信任问题。不要因为在导入命令里加了-k就忽略 server 端证书的正式化——这一步偷懒后面所有集群都会带着不安全的隐患在跑。6. 把运维脚本化用 Rancher API 做自动化巡检与批量操作Rancher 的 UI 背后是一套完整的 v3 API。日常运维如果还停留在「打开浏览器点来点去」那 Rancher 的价值只发挥了一半。API 的典型用途是做多集群巡检每个下游集群的健康状态、版本信息、节点资源用量都可以定时拉取并在异常时通过 webhook 通知到 IM 工具。下面这段脚本用来拉取所有集群的列表和状态#!/usr/bin/env bash set -euo pipefail RANCHER_URLhttps://rancher.example.com API_TOKEN从 UI 生成的 API Token # 获取所有集群列表输出集群名、健康状态和版本号 curl -s -k ${RANCHER_URL}/v3/clusters \ -H Authorization: Bearer ${API_TOKEN} | jq -r .data[] | [.name, .state, .version.gitVersion] | tsv这段脚本的要点有两个。第一Authorization: Bearer用 Token 而不是用户名密码Token 可以在 Rancher UI 的「用户 → API 密钥」里生成支持设置过期时间和作用范围但不要把 Token 硬编码在脚本里建议放到环境变量或 Git 仓库的 Secret 管理中。第二字段名可能随着 Rancher 版本有小幅调整如果执行后得到空值先跑curl -s -k ${RANCHER_URL}/v3/clusters -H Authorization: Bearer ${API_TOKEN} | jq .data[0] | keys看看真实结构再改 jq 表达式。这是 API 调试最基础的思路别背字段要看数据。有了这个基础脚本可以继续扩展成巡检任务比如检查所有集群的状态字段是否为active把非 active 的集群名输出并触发告警或者用/v3/clusters/id/nodes拉取每个集群的节点状态配合设定的阈值判断是否需要扩容。更进一步还可以把集群导入、项目创建这类重复操作也封装成 API 调用方便在自建平台上提供给其他团队自助申请而不是每次都向运维要账号权限。另外提醒一个实战中常见的误区Rancher API 的功能和 UI 并非完全一致UI 上的一些「便捷操作」背后可能涉及多个 API 调用直接模拟时要注意调用顺序和参数依赖。比如「创建集群」这个操作API 层面通常需要先创建 Node Template再创建 ClusterCluster 的节点配置里引用 Template ID顺序反了会一直报参数错误。稳妥的做法是先在一个测试环境里用浏览器的开发者工具观察 UI 发出的真实请求再复制到脚本里。我自己以前也是靠 UI 一个集群一个集群地检查状态直到一次大规模升级时点错了集群才发现人工操作在集群数量上来之后既低效又危险。后来所有重复性操作都改成 API 脚本每一步有日志、有回滚记录心里踏实很多。Rancher 用得越深越会意识到它的长期价值不在于那个漂亮界面而在于把多集群运维变成可编程、可审计的工程动作。希望这套部署与运维的思路能帮到你少走几步我当年走过的弯路。本文还有配套的精品资源点击获取