企业官网建设流程全解析

简介：容器编排已成为企业应用交付的标准方式，Kubernetes 作为底层调度平台解决了单集群的资源管理问题，但面对多个集群分散在测试、生产与边缘环境时，统一管控与权限治理便成为运维瓶颈。Rancher 作为运行在 Kubernetes 之上的容器管理平台，通过可视化的多集群管理、统一 RBAC 与一键升级能力，有效简化了基础设施团队的日常操作。本文以实际部署为主线，从轻量级 K3s 单机起步，到生产环境推荐的三节点 RKE2 底座，再到 Helm 在线安装与离线镜像同步等关键环节，系统梳理了 Rancher 部署所需的参数配置、主机初始化要求及常见故障排查方法，为私有化交付和长期运维提供可落地的参考。

1. 为什么运维手上已经握着 kubectl，我还是建议上 Rancher

Rancher 是一套运行在 Kubernetes 之上的容器管理平台，专门解决“多集群一台台分开管”的痛点。当你只有一两个集群时，kubectl 够用；当集群到了三五个，且分散在测试、生产、边缘节点时，每个人的 kubeconfig 到处传，权限不好审计，升级只能手动逐台操作，Rancher 的价值就体现出来了：一个 Web 页面看所有集群状态，一条命令创建一个新集群，一套 RBAC 规则管住不同团队的操作边界。这篇内容面向一线运维工程师和负责私有化交付的同学，目标是让你从零把 Rancher 部署成一个可长期维护的平台，并把生产里容易踩的坑提前拆掉。

2. 部署前把地扫干净：K3s、RKE2 与主机参数一个都不能少

Rancher Server 本身是跑在 Kubernetes 上的应用，所以部署 Rancher 的第一步不是下载安装包，而是先决定承载集群用什么发行版。常见做法有两种：K3s 和 RKE2。K3s 是轻量级发行版，适合单机、边缘、资源受限场景；RKE2 是 Rancher 官方维护的安全加固版 Kubernetes 发行版，生产底座基本都选它。选型错了，后面做高可用和升级都会很别扭。

2.1 K3s 轻量起步：单机装完 Rancher 的最小步骤

如果你只是验证功能、做小规模交付，K3s 是最省事的选择。它默认集成了 containerd、CoreDNS 和 Traefik Ingress，一条命令就能把 Kubernetes 拉起来：

curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--write-kubeconfig-mode 644" sh -

装完后验证节点状态：

sudo k3s kubectl get node kubectl get node

第一条命令是 K3s 自带 kubectl 的调用方式，第二条能直接用，是因为--write-kubeconfig-mode 644让/etc/rancher/k3s/k3s.yaml对普通用户可读。这参数在测试机上很实用，省得每次 kubectl 都带 sudo。生产环境建议把 kubeconfig 放到固定位置，在.bashrc里export KUBECONFIG=/etc/rancher/k3s/k3s.yaml。

K3s 默认启用 Traefik，Rancher 的 Ingress 会复用它，一般不用额外装 Ingress Controller。如果业务侧对入口有特殊要求，安装时可以用--disable traefik关掉，但后面要自己补一个 nginx-ingress，否则 Rancher 的入口规则没有 Controller 消费。对多数交付场景，我建议保持默认。

2.2 RKE2 当生产底座：为什么要走三节点加 Etcd

RKE2 也叫“RKE Government”，它通过 CIS 安全基线校验，组件全部来自加固过的镜像，etcd 默认独立部署在高可用模式下。和生产集群相比，K3s 更像一个“开箱即用”的发行版，而 RKE2 更适合需要长期升级、合规审计、多租户隔离的环境。

RKE2 的第一个 Server 节点初始化：

curl -sfL https://get.rke2.io | sh - systemctl enable rke2-server systemctl start rke2-server

后续 Server 节点通过配置文件加入，核心是server指向第一个节点的 9345 端口，以及共享同一个 token：

# /etc/rancher/rke2/config.yaml token: my-shared-token server: https://10.0.0.11:9345 write-kubeconfig-mode: "0644"

第二个和第三个节点执行同样的安装命令，systemd 启动后会自动加入集群。这里的 9345 是 RKE2 的 Supervisor 端口，负责节点注册和证书分发，不是 etcd 的 2379。很多第一次接触的人容易混淆，导致加入失败。

选型结论我一般这么说：几十个节点以内、单团队使用、资源紧，选 K3s；超过这个规模、要长期跑生产、有安全审计要求，直接 RKE2 三节点起。Rancher Server 本身对承载集群的要求不高，但它管理的业务集群稳定性，取决于你这个底座选得对不对。

2.3 主机初始化清单：时区、内核转发与必要系统参数

不管 K3s 还是 RKE2，主机层面有几项参数不调好，后面排查会非常痛苦。我一般在交付环境里按这套模板初始化：

# 设置主机名和时区 hostnamectl set-hostname k8s-node01 timedatectl set-timezone Asia/Shanghai # 开启内核转发与桥接过滤，容器网络依赖这两个参数 cat <<'EOF' > /etc/sysctl.d/99-k8s.conf net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-iptables = 1 vm.swappiness = 0 EOF sysctl --system # 关闭 swap，Kubernetes 节点不建议开 swap swapoff -a && sed -i '/swap/s/^/#/' /etc/fstab # 内网环境直接关 firewalld，外网环境请按端口放行 systemctl disable --now firewalld

net.ipv4.ip_forward不开，Pod 与 Pod 之间的流量转发会断；bridge-nf-call-iptables不开，Calico 或 Flannel 的 iptables 规则不会作用于桥接流量，Service 访问会随机失败，这是典型的“时好时坏”问题。vm.swappiness = 0让内核尽量不把匿名内存换出，容器应用的内存水位会更稳定。

如果防火墙不能关，需要放行的端口参考下表：

节点内存方面，单台 K3s 跑 Rancher 建议不低于 4GB；RKE2 三节点承载 Rancher 时，每台建议 8GB 起。这不是硬性指标，但低于这个值，Rancher 的 Webhook、Controller 和监控组件一起跑起来，内存很容易被打满，后面查 OOM 会查到你怀疑服务器本身有问题。

3. Rancher Server 安装：在线、离线两条路，参数决定后序

承载集群就绪后，Rancher Server 的安装本质就是往集群里部署一套 Helm Chart。在线环境一条命令能搞定，内网环境要提前把镜像和证书方案准备好。这一章把两条路和关键参数讲透，装完你至少能说清楚每个参数改了什么、动了会有什么后果。

3.1 用 Helm 在线安装 Rancher：cert-manager 与主命令

Rancher 生成 HTTPS 证书依赖 cert-manager，所以官方推荐的标准流程里，cert-manager 要先就位，除非你自己提供证书并走ingress.tls.source=secret模式。完整命令如下：

# 1. 安装 cert-manager kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.yaml # 2. 等待 cert-manager 就绪 kubectl -n cert-manager rollout status deploy/cert-manager --timeout=120s # 3. 添加 Rancher Helm 仓库 helm repo add rancher-latest https://releases.rancher.com/server-charts/latest helm repo update # 4. 创建命名空间并安装 Rancher kubectl create namespace cattle-system helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --set hostname=rancher.example.com \ --set bootstrapPassword=admin-init-123 \ --set replicas=1 \ --set ingress.tls.source=rancher # 5. 等待 Deployment 就绪 kubectl -n cattle-system rollout status deploy/rancher --timeout=300s

第 1 步用 GitHub 上的 cert-manager 清单，网络环境要能访问；第 4 步的hostname是 Rancher 对外暴露的访问域名，不是随便填的主机名。装完后浏览器访问https://rancher.example.com，用bootstrapPassword里设置的密码完成首次登录。

安装后第一件事是确认 Pod 状态和日志：

kubectl -n cattle-system get pods kubectl -n cattle-system logs deploy/rancher --tail=100

如果 Pod 一直CrashLoopBackOff，先把日志拉出来看，常见的是cert-manager还没就绪或hostname解析失败。不要反复重装，先定位，再改参数。

3.2 必调的五个安装参数：hostname、replicas、bootstrapPassword 等

Helm 安装 Rancher 时，真正影响后续运维的参数就五个，其余大多数保持默认即可：

hostname是最容易埋雷的参数。它不只影响浏览器访问，还写进 Rancher Server 向 agent 暴露的注册地址里。如果你填了192.168.1.10，集群导入后 agent 会拿着这个 IP 去连 Rancher，一旦 IP 换了或证书 SAN 对不上，所有子集群全部掉线。所以我在交付时坚持用域名，哪怕是内网 DNS 里的名字，也要比裸 IP 稳得多。

replicas在单节点上不要随意填 3。Rancher 的默认调度逻辑会尽量把多个副本分散到不同节点，单节点上三个副本要么调度不满足被卡在 Pending，要么因为资源互相挤占不断重启。后面你加了节点，再通过helm upgrade把replicas改成 3 就行。

3.3 内网离线安装：registries.yaml 与镜像私有仓库的配合

不少交付环境从第一天开始就没有外网，Rancher 的镜像、Helm Chart、cert-manager 清单都需要提前准备好。离线安装的套路是：先把镜像同步到内网镜像仓库，再让 K3s 或 RKE2 的 containerd 把所有docker.io拉取请求都指向内网仓库。

在有外网的机器上先同步镜像，以 Rancher v2.9.0 为例：

# 拉取核心镜像并打内网仓库的 tag docker pull rancher/rancher:v2.9.0 docker tag rancher/rancher:v2.9.0 registry.internal.example.com/rancher/rancher:v2.9.0 docker push registry.internal.example.com/rancher/rancher:v2.9.0

实际操作时，Rancher 依赖的镜像不止这一个，还有 cert-manager、mirrored-core 等一大批。一般做法是从官方离线包脚本里拿rancher-images.txt清单，用脚本批量同步。内网节点上，关键步骤是写/etc/rancher/k3s/registries.yaml：

# /etc/rancher/k3s/registries.yaml mirrors: docker.io: endpoint: - "https://registry.internal.example.com" configs: "registry.internal.example.com": tls: insecure_skip_verify: true

配置完重启 K3s：

systemctl restart k3s

这里有个常见的坑：K3s 用的是 containerd，不是 docker。你在节点上执行docker load把镜像塞进 docker 的存储目录，containerd 根本不会认。正确做法就是上面的registries.yaml镜像配置，或者在 Helm 安装时用--set rancherImage=registry.internal.example.com/rancher/rancher显式指定内网镜像。RKE2 的配置文件路径是/etc/rancher/rke2/registries.yaml，逻辑一样。

4. 日常运维要点：升级、备份、节点管理与监控

Rancher 装好只是开始，真正考验平台稳定性的在于后续的升级、备份和节点生命周期管理。这章讲的都是我在项目里反复用到的操作，顺序和参数都经过验证，照着做基本不会翻车。

4.1 Rancher 升级：先备份再 helm upgrade，回滚才不慌

Rancher 的升级路径官方有严格要求：小版本可以连续升，大版本之间往往要求先升到中间版本。跨大版本直接helm upgrade，轻则 UI 一直 Waiting，重则 controller 起不来。升级前把当前 values 导出来，这是你最重要的后悔药：

# 1. 导出当前 Helm values helm -n cattle-system get values rancher > rancher-values-before-upgrade.yaml # 2. 记录当前版本 helm -n cattle-system list # 3. 升级 helm repo update helm upgrade rancher rancher-latest/rancher \ -n cattle-system \ -f rancher-values-before-upgrade.yaml \ --wait --timeout 10m # 4. 确认 Pod 状态 kubectl -n cattle-system get pods

-f带旧 values 的作用是保证升级后不会丢失之前的参数，比如hostname和replicas。不带的话，Helm 会用 Chart 里的默认值覆盖，可能导致 hostname 变化、副本数被重置。

升级过程中如果发现 UI 长时间卡在 Waiting，先不要反复 upgrade，按第 5.3 节的排查思路走。最稳妥的做法是：先读官方 Release Notes 确认升级路径，再在测试环境复演一遍，最后动生产。

4.2 Etcd 快照与 Rancher 数据恢复流程

Rancher 的元数据、集群配置、用户权限全部落在承载集群的 etcd 里。对 K3s 来说，etcd 快照是最直接的备份手段。我习惯每天定时打一个快照，文件名带日期，保留最近七天：

# 手动创建快照 sudo k3s etcd-snapshot save --name daily-$(date +%F) # 查看已有快照 sudo k3s etcd-snapshot ls # 恢复快照（顺序不能乱） sudo systemctl stop k3s sudo k3s server --cluster-reset --cluster-reset-restore-path=/var/lib/rancher/k3s/server/db/snapshots/daily-2025-03-10T120000Z sudo systemctl start k3s

恢复前必须确认快照文件的实际路径和名称，执行k3s etcd-snapshot ls后复制完整名字。恢复后 Rancher 会回到快照时间点的状态，这之后创建的业务集群和配置变更都会丢失。所以快照策略不能只靠手动，建议加 crontab：

0 2 * * * /usr/local/bin/k3s etcd-snapshot save --name cron-$(date +\%F)

生产环境建议同时启用 Rancher 官方的 rancher-backup 应用，它可以把备份推到 S3 兼容存储或本地 PV。我的习惯是“双写”：etcd 快照负责承载集群本身，rancher-backup 负责 Rancher 业务数据，两层防护，单点故障也不怕。

4.3 节点管理操作：编辑标签、排水与重新添加 agent

Rancher UI 里“集群管理 → 节点”可以完成大部分节点操作，但对已经用 K3s/RKE2 拉起集群的场景，命令行仍是最后一道保障：

# 给节点打标签，常用于指定工作负载调度 kubectl label node node01 disktype=ssd # 排水：将节点标记为不可调度并驱逐 Pod kubectl drain node01 --ignore-daemonsets --delete-emptydir-data # 重新启用调度 kubectl uncordon node01

drain操作在维护物理机、替换故障硬件时必不可少。不带--ignore-daemonsets会报错，因为 DaemonSet 的 Pod 不能被驱逐；--delete-emptydir-data是让使用 emptyDir 的临时 Pod 能安全删除，如果你在意数据，先确认业务侧没有把状态放在 emptyDir 里。

如果是节点彻底损坏，需要在 Rancher UI 删除节点，再重新生成加入命令。这条命令里带着集群 token，注意别泄露到日志或聊天工具里。替换节点后用同一命令加入，Kubernetes 会自动调度工作负载回来。

5. Rancher 常见问题与避坑速查：四个真实故障的处理记录

这一章把我在项目里真正遇到过的四个故障场景拆开写，按“现象 → 原因 → 解决”的顺序。这些问题你大概率也会碰见，能省下不少排查时间。

5.1 单节点硬启 replicas=3：Pod 起不来是预期的

现象：安装时图省事直接--set replicas=3，等半天kubectl -n cattle-system get pods里 Rancher 一直 Pending 或 CrashLoopBackOff，kubectl describe看到事件里有调度失败记录。

原因：Rancher Chart 默认带 Pod 反亲和性，多个副本倾向于分散在不同节点。单节点上三个副本互相约束，再加上每个副本的内存请求加起来超过了节点可用量，调度器满足不了约束条件，Pod 自然起不来。

解决：把副本数改回 1，先把平台跑起来：

helm upgrade rancher rancher-latest/rancher -n cattle-system \ --set replicas=1

等承载集群真正扩到三个节点后，再改成replicas=3。不要在一台 4G 内存的机器上硬撑三个副本，Rancher 本身占用的资源比你想象的高。

5.2 hostname 写成了 IP：自签证书和 agent 一起罢工

现象：安装参数里--set hostname=192.168.1.10，装完用 IP 打开浏览器，提示证书不受信任；强行跳过提示后，导入的集群 agent 一直 Waiting，日志里是连接不上 Rancher Server。

原因：hostname参数同时用于生成证书 SAN 和向 agent 暴露注册地址。写成 IP 后，自签证书里只包含这个 IP，后续任何通过域名访问的请求都会因证书不匹配被浏览器拦掉；agent 注册时拿到的地址也是这个 IP，一旦网络拓扑变动，agent 与 Server 之间的通道就断了。

解决：还没导入多少集群时，直接用正确的域名重来一遍：

helm upgrade rancher rancher-latest/rancher -n cattle-system \ --set hostname=rancher.example.com

改完之后把已经导入的集群 agent 重新部署一次，操作路径是集群详情页 → 编辑 → 重新生成 agent manifest。这个教训说明，初始化时把域名定死，比后期迁移省太多事。

5.3 升级后界面卡在 Waiting：先看 helm history 再 rollback

现象：把 Rancher 从旧版本一次跳到新版本，UI 长时间停在 Waiting，后端 Pod 反复重启，部分 cattle-* 命名空间出现大量异常 Pod。

原因：跨大版本升级时，Chart 的 API 资源版本、webhook 配置可能不兼容；也可能是 cert-manager 版本太低，Rancher 新版本需要的 CRD 没有及时更新。

解决：先看 Helm 历史和当前日志，不要反复 upgrade：

helm -n cattle-system history rancher kubectl -n cattle-system logs deploy/rancher --tail=200

如果日志里明确指向 cert-manager 或 CRD，先把 cert-manager 升级到 Rancher 官方文档要求的版本，再重试升级。如果确认 Chart 本身不兼容，且刚升级不到一小时，用 rollback 退回去：

helm -n cattle-system rollback rancher <上一个可用版本号> --wait

升级这件事，备份永远是第一位的。没有 etcd 快照和 values 文件，回滚就是空谈。

5.4 导入集群一直 Waiting：检查 443 连通性与 hostname 解析

现象：用“导入现有集群”功能生成 manifest，在目标集群执行后，agent Pod 创建成功但状态一直是 Waiting，日志里反复出现连接 Rancher Server 失败。

原因：目标集群到 Rancher Server 的 443 端口网络不通，或者 DNS 解析不到hostname。常见于 Rancher 部署在办公网、目标集群在生产网，中间隔了安全域或防火墙策略。

解决：在目标集群侧先看日志再测连通性：

kubectl -n cattle-system get pods -l app=cattle-cluster-agent kubectl -n cattle-system logs deploy/cattle-cluster-agent --tail=100 nc -vz rancher.example.com 443

网络不通就在防火墙上放行；网络通了还 Waiting，继续确认目标集群侧的 DNS 解析是否指向正确的 Rancher Server IP。这里最容易出的问题是把hostname解析到了一个内网别名，证书 SAN 却不匹配，agent 连接失败。

6. 进阶玩法：用 Rancher API 和 Terraform 管住多集群

平台稳定运行之后，下一步是减少人肉操作。Rancher 提供了完整的/v3API，几乎所有 UI 操作都能用接口完成。我日常用得最多的是通过 API 拿 token 后批量查看集群状态，再配合 Terraform 做集群生命周期管理。

先登录拿 API Token：

curl -k -X POST https://rancher.example.com/v3-public/localProviders/local?action=login \ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"<你的密码>"}' | jq -r .token

拿到 token 后，用一段脚本就能把几十个集群的状态拉下来：

curl -k -s https://rancher.example.com/v3/clusters \ -H "Authorization: Bearer <token>" | jq '.data[].name'

这种方式很适合接入内部的运维平台或告警系统。Terraform 的rancher2provider 能管理整个集群生命周期，集群定义可以进 Git，变更可审阅、可回滚：

terraform { required_providers { rancher2 = { source = "rancher/rancher2" } } } provider "rancher2" { api_url = "https://rancher.example.com" token_key = var.rancher_token } resource "rancher2_cluster" "prod" { name = "prod-cluster" kubernetes_version = "v1.28.7+rke2r1" }

我个人的实践节奏是：创建集群、加节点、换证书这三件事交给 Terraform 和 API 脚本，发布应用和权限管理留在 Rancher UI 或 YAML 里。不要把每件事都自动化，先把重复度最高、出错成本最大的环节脚本化。Rancher 本身不复杂，真正复杂的永远是数据备份和网络边界这些基本功，把 hostname 写对、把 etcd 快照定时做好，后面能少熬好几个夜。希望这个方向对你有帮助。

本文还有配套的精品资源，点击获取