利用 Rancher 和 K3S 构建高效 Kubernetes 集群的实战手册

1. 为什么你需要 Rancher + K3S 这套组合拳？

如果你正在或者打算搞容器化，那你肯定绕不开 Kubernetes。这玩意儿现在火得不行，几乎成了云原生时代的“操作系统”。但说实话，K8S 的原生安装和运维，对很多团队来说，门槛不低。你得操心 etcd 集群、网络插件、存储、证书管理……一堆事情，没点经验真容易掉坑里。

我自己带团队这些年，从裸机到云上，部署过不下几十套 K8S 集群。早期我们也头铁，硬啃原生安装，结果光是版本升级就能折腾一整天，更别说管理多套不同环境（开发、测试、生产）的集群了，那简直是运维的噩梦。后来我们发现了 K3S 和 Rancher 这套黄金组合，一下子就把效率提上来了。

简单来说，K3S 是 Kubernetes 的一个“瘦身版”。它把一些生产环境中可能用不到的原生组件（比如旧的云供应商驱动、alpha 功能）给去掉了，默认用更轻量的 SQLite 代替了 etcd，整个二进制文件就几十兆。这意味着它启动飞快，对硬件资源（CPU、内存）的需求也大大降低。我试过在一台 1核1G 的虚拟机上就能跑起来一个单节点的 K3S 集群，用来做本地开发测试简直完美。

而 Rancher，你可以把它理解为一个 Kubernetes 集群的“总控台”或者“管理面板”。它自己也是一个运行在 K8S 上的应用。有了它，你就不需要再分别登录到每个集群去敲 kubectl 命令了。Rancher 提供了一个统一的 Web 界面，能同时管理成百上千个 K8S 集群，不管这些集群是跑在你自己机房，还是在阿里云、腾讯云、AWS 上，甚至是混合的。它把集群的创建、监控、日志、告警、用户权限、应用商店这些功能都打包好了，开箱即用。

所以，这套组合拳的核心价值就是：用 K3S 实现快速、低成本的集群部署，用 Rancher 实现集中、可视化的集群管理。特别适合那些资源有限（比如边缘计算、开发测试环境）、但又需要管理多套 K8S 集群的中小团队或企业。接下来，我就手把手带你从零开始，把这套系统搭起来。

2. 动手之前：环境与心态准备

在开始敲命令之前，有两件事比技术本身更重要：一是把环境理清楚，二是把心态摆端正。别小看准备工作，很多后续的坑其实都是前期没规划好埋下的。

2.1 硬件与网络规划

原始文章里提到了硬件配置，我这里结合实战经验再细化一下。对于 生产环境，高可用是必须的。这意味着你至少需要：

• 3台服务器作为 K3S Server 节点：这三台机器将组成 K3S 的控制平面（Control Plane），实现高可用。它们之间需要稳定的低延迟网络，因为要运行 etcd（如果你选择外部 etcd 或嵌入式高可用模式）来存储集群状态。配置建议至少 2核4GB，系统盘 50GB。如果预算允许，CPU 和内存再好点，集群操作会更流畅。
• N台服务器作为 K3S Agent 节点：这些是真正跑你业务容器的工作节点。配置完全取决于你的业务负载。跑几个 Web 服务，2核4GB 起步；跑数据库、AI 训练任务，那就得 16核64GB 甚至更高，配 SSD 硬盘。
• 1台独立的服务器安装 Rancher：强烈建议将 Rancher 管理平台安装在一个独立的 K3S 集群上，不要和你准备管理的业务集群混在一起。这叫“管理平面与数据平面分离”。好处是，即使你管理的业务集群全部挂了，你的 Rancher 控制台依然能访问，方便你排查问题。这台机器配置 2核4GB 也够了。

对于 开发测试或个人学习，一切从简。一台配置好点的电脑（16GB内存以上），用虚拟机软件（如 VirtualBox, VMware）开 3-4 台 Linux 虚拟机（每台 1-2核，2-4GB内存）就完全可以玩转这套体系。

网络是重中之重：

1. 所有节点之间必须能互相通信，特别是 6443（Kubernetes API Server）、2379-2380（etcd）、8472（Flannel VXLAN 默认端口）这几个端口要开放。
2. 提前规划好 IP 地址段。集群 Pod 的网络（CIDR）和服务（Service）的网络不要和你的物理机网络冲突。比如，你的服务器内网是 192.168.1.0/24，那 Pod 网段可以设为 10.42.0.0/16，Service 网段设为 10.43.0.0/16。
3. 想好域名。Rancher 需要通过一个域名来访问，比如 rancher.mycompany.com。你需要提前将这个域名解析到安装 Rancher 的那台服务器的 IP 上。本地测试可以修改自己电脑的 hosts 文件。

2.2 软件与依赖安装

操作系统我习惯用 Ubuntu 22.04 LTS 或者 CentOS Stream 8/9，社区活跃，问题好查。以下命令以 Ubuntu 为例。

第一步，在所有节点上安装 Docker。虽然 K3S 默认包含 containerd，但 Rancher 的安装脚本和一些工具可能依赖 Docker。安装最新稳定版就行：

# 更新包索引
sudo apt-get update

# 安装必要的工具，允许 apt 通过 HTTPS 使用仓库
sudo apt-get install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 的官方 GPG 密钥
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 设置 Docker 的稳定版仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 再次更新包索引，并安装 Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 启动 Docker 并设置开机自启
sudo systemctl enable --now docker

# 验证安装，运行 hello-world 镜像
sudo docker run hello-world

安装成功后，建议将当前用户加入 docker 组，这样就不用每次都 sudo 了：sudo usermod -aG docker $USER，然后退出终端重新登录生效。

3. 核心实战：一步步构建你的集群

环境准备好，我们就可以开始真正的“烹饪”了。这个过程就像搭积木，顺序很重要。

3.1 安装第一个 K3S 集群（管理集群）

还记得我们之前说的“管理平面分离”吗？第一步，我们先搭建一个独立的 K3S 集群，专门用来运行 Rancher。假设我们有三台虚拟机：node-mgmt-1, node-mgmt-2, node-mgmt-3。

在第一台服务器 (node-mgmt-1) 上，安装 K3S Server，并启用高可用模式。这里我们使用内置的嵌入式 etcd（对于小型管理集群够用了）：

# 在 node-mgmt-1 上执行
curl -sfL https://get.k3s.io | sh -s - server \
  --cluster-init \
  --tls-san <你的Rancher域名或IP> \
  --node-ip <node-mgmt-1的IP地址>

参数解释：

• --cluster-init：告诉 K3S 这是第一个 Server 节点，并初始化一个嵌入式 etcd 集群。
• --tls-san：在 TLS 证书中添加额外的主机名或 IP。这里填你准备访问 Rancher 的域名（如 rancher.mycompany.com）或 IP。这个非常重要，不然后面 Rancher 访问会有证书错误。
• --node-ip：显式指定节点的 IP，避免在多网卡环境下出错。

安装完成后，在 /var/lib/rancher/k3s/server/node-token 路径下会生成一个 token。把它记下来，后面其他 Server 节点要加入集群需要它。

接着，在第二台和第三台服务器上，将它们作为 Server 节点加入到第一个节点形成的集群中：

# 在 node-mgmt-2 和 node-mgmt-3 上分别执行
curl -sfL https://get.k3s.io | sh -s - server \
  --server https://<node-mgmt-1的IP>:6443 \
  --token <从node-mgmt-1获取的token> \
  --tls-san <你的Rancher域名或IP> \
  --node-ip <当前节点的IP地址>

这样，一个三节点高可用的 K3S 管理集群就搭建好了。你可以通过 sudo k3s kubectl get nodes 在任意节点上查看集群状态，应该能看到三个节点都是 Ready 状态。

3.2 在管理集群上安装 Rancher

现在，我们在刚刚建好的 K3S 管理集群上安装 Rancher。这里使用 Helm 来安装，这是管理 K8S 应用的标准包管理工具。首先，在任意一个管理集群节点上安装 Helm 和配置必要的组件。

第一步，安装 cert-manager。Rancher 依赖它来自动管理 HTTPS 证书。

# 添加 Jetstack Helm 仓库
helm repo add jetstack https://charts.jetstack.io
helm repo update

# 安装 cert-manager 的 CustomResourceDefinitions (CRDs)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.2/cert-manager.crds.yaml

# 创建命名空间
kubectl create namespace cert-manager

# 使用 Helm 安装 cert-manager
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --version v1.13.2 \
  --set installCRDs=true

等待 cert-manager 的所有 Pod 都变成 Running 状态：kubectl get pods -n cert-manager。

第二步，安装 Rancher。

# 添加 Rancher 稳定版 Helm 仓库
helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm repo update

# 为 Rancher 创建命名空间
kubectl create namespace cattle-system

# 使用 Helm 安装 Rancher
# 将 hostname 替换成你实际的域名，比如 rancher.mycompany.com
helm install rancher rancher-stable/rancher \
  --namespace cattle-system \
  --set hostname=rancher.mycompany.com \
  --set replicas=3 \
  --set bootstrapPassword=<设置一个强密码>

这里有几个关键点：

• hostname：必须是你提前解析到这三台服务器任一 IP 的域名。Rancher 会为这个域名自动申请 Let‘s Encrypt 的免费证书（通过 cert-manager）。如果你在内网测试，没有公网域名，可以设置 --set ingress.tls.source=rancher 使用 Rancher 自签的证书，但浏览器访问时需要手动信任不安全连接。
• bootstrapPassword：这是你第一次登录 Rancher 时，为 admin 用户设置的密码。务必记牢。
• replicas=3：指定 Rancher 的副本数，和我们三个 Server 节点匹配，实现高可用。

安装命令执行后，需要等待几分钟，直到所有 Rancher 相关的 Pod 都就绪。可以用 kubectl get pods -n cattle-system -w 来观察状态。当都显示 Running 后，就可以用浏览器访问 https://rancher.mycompany.com 了。首次登录会要求你设置新密码（就是上面 bootstrapPassword 那个）。

3.3 使用 Rancher 创建被管理的业务集群

登录进 Rancher 后，你会看到一个非常清爽的界面。点击左上角的“集群管理”，然后点击“创建集群”。Rancher 支持导入已有集群和创建新集群。这里我们演示创建新的 K3S 集群。

选择“自定义”选项。Rancher 会生成一个集群配置模板。你需要关注几个核心参数：

• 集群名称：起个有意义的名字，比如 prod-cluster, dev-cluster。
• Kubernetes 版本：Rancher 会提供一系列它测试过的 K3S 版本，选一个稳定的。
• 网络提供商：K3S 默认使用 Flannel，够用了。也可以选 Calico，功能更强大。
• 云提供商：如果你在公有云上，可以选择对应的提供商以集成负载均衡器等服务；私有环境就选 none。

配置好后，Rancher 会生成两条命令：一条是给 Server（控制平面） 节点的，一条是给 Agent（工作） 节点的。这个设计非常巧妙。

假设你现在有三台新的物理机要作为业务集群节点。你在第一台上运行生成的那条 Server 命令。这条命令本质上是一个 Docker 命令，它会拉取 Rancher Agent 镜像，并自动连接到 Rancher 服务器，将这台主机注册为一个新的集群的控制平面。Rancher 会在后台，通过这台主机，自动为你部署一个完整的 K3S 集群。

命令类似这样：

sudo docker run -d --privileged --restart=unless-stopped \
  --net=host -v /etc/kubernetes:/etc/kubernetes \
  -v /var/run:/var/run rancher/rancher-agent:v2.7.0 \
  --server https://rancher.mycompany.com \
  --token <RANCHER生成的令牌> \
  --ca-checksum <校验和> \
  --etcd --controlplane --worker

运行后，回到 Rancher UI，你就能看到新集群正在“Provisioning”（配置中）。等待几分钟，状态变成“Active”，控制平面就部署好了。

然后，在另外两台物理机上，运行生成的那条 Agent 命令（命令里没有 --etcd --controlplane 参数）。它们会作为纯工作节点加入这个新集群。就这样，你不需要手动去这些机器上安装 K3S，Rancher 帮你全搞定了。所有集群的状态、节点信息，都清晰地展示在 Rancher 的同一个控制台里。

4. 避坑指南与进阶调优

一路顺风安装下来的情况不多，总会遇到些小波折。这里分享几个我踩过的坑和对应的解决办法。

4.1 常见故障排查

问题一：节点注册超时或失败。

• 现象：在 Rancher UI 点击创建集群，节点状态一直卡在 Waiting 或 Provisioning，最后报错。
• 排查：
  1. 网络连通性：这是最常见的原因。确保你的业务节点能访问 Rancher Server 的域名和 443 端口。在业务节点上执行 curl -vk https://rancher.mycompany.com 看看。
  2. 防火墙/SELinux：检查业务节点和 Rancher 节点之间的防火墙规则，确保 6443、2379-2380、8472（UDP）等端口是通的。如果是 CentOS，临时关闭 SELinux 试试：setenforce 0。
  3. 时间同步：所有节点的时间必须同步！偏差过大会导致证书验证失败。使用 ntpdate 或 chronyd 同步时间。

问题二：Pod 网络不通，跨节点容器无法互访。

• 现象：部署的应用，Pod 分散在不同节点上时，互相 ping 不通。
• 排查：
  1. Flannel 后端：K3S 默认使用 VXLAN 模式的 Flannel。检查 Flannel Pod 是否正常运行：kubectl get pods -n kube-system -l app=flannel。
  2. 主机路由：对于某些网络环境（如某些公有云 VPC），可能需要将 Flannel 后端改为 host-gw 模式。在安装 K3S 时添加参数：--flannel-backend=host-gw。这要求主机在同一二层网络。
  3. 内核模块：确保主机加载了 ip_tables， ip6_tables， br_netfilter 等模块。

问题三：镜像拉取缓慢或失败。

• 现象：Pod 状态一直是 ImagePullBackOff。
• 解决：为 K3S 配置国内镜像加速。编辑 K3S 的配置文件 /etc/rancher/k3s/registries.yaml，添加阿里云等镜像仓库镜像。然后重启 K3S 服务：sudo systemctl restart k3s。

4.2 生产环境进阶配置

当集群要承载真实业务时，一些默认配置需要调整。

资源预留与驱逐：Kubernetes 节点上的系统进程（如 kubelet、容器运行时）和内核也需要资源。不预留的话，业务 Pod 可能把资源吃光，导致节点不稳定。我们需要修改 K3S Agent 的启动参数，在 /etc/systemd/system/k3s-agent.service 文件中的 ExecStart 行后添加：

--kubelet-arg="system-reserved=cpu=200m,memory=512Mi" \
--kubelet-arg="kube-reserved=cpu=200m,memory=256Mi" \
--kubelet-arg="eviction-hard=memory.available<5%,nodefs.available<10%"

这表示为系统预留 200m CPU 和 512Mi 内存，为 K8S 系统组件预留 200m CPU 和 256Mi 内存，并在内存不足 5% 或磁盘不足 10% 时开始驱逐 Pod。

持久化存储：K3S 默认没有提供动态存储供应（StorageClass）。对于有状态应用，你需要自己部署。一个简单的方案是使用 local-path-provisioner（K3S 自带），但它只提供本地存储，Pod 不能漂移。生产环境建议部署网络存储方案，如 NFS Client Provisioner 或 Ceph RBD。

日志与监控：Rancher 自带了项目级别的日志查看，但长期存储和集中分析需要额外部署 EFK（Elasticsearch, Fluentd, Kibana）或 Loki 栈。监控方面，可以在 Rancher 的应用商店一键部署 Prometheus-Operator，它集成了 Grafana，能提供非常专业的集群和应用监控面板。

安全加固：

1. 定期更新：关注 Rancher 和 K3S 的安全公告，及时升级版本。
2. RBAC 与权限：在 Rancher 中创建不同的用户和角色，遵循最小权限原则分配集群和项目访问权，不要所有人都用 admin。
3. Pod 安全策略：虽然 Kubernetes 的 PodSecurityPolicy (PSP) 已被弃用，但可以通过 Rancher 集成 OPA Gatekeeper 来定义更强大的安全策略，比如禁止容器以 root 用户运行、禁止使用宿主机网络等。

5. 从“能用”到“好用”：生态集成与自动化

集群稳定运行后，我们就可以考虑如何让它更好地为研发流程服务了。Rancher 的强大之处在于它提供了一个平台，能很方便地集成各种工具。

CI/CD 流水线：这是 DevOps 的核心。你可以在 Rancher 中创建一个专门的项目（Project），然后部署一套 Jenkins。通过 Jenkins 的 Kubernetes 插件，它可以直接在你的 K3S 集群中动态创建 Pod 来运行构建任务。结合 Git Webhook，代码一提交就自动触发构建、测试、镜像打包，并最终通过 kubectl 或 Helm 部署到指定的 K3S 集群中。Rancher 的多集群管理能力让“一次构建，多处部署”（开发、测试、生产）变得非常顺畅。

混合云与边缘管理：这是 Rancher 的杀手级功能。假设你有业务跑在公司的私有云（基于 K3S），同时为了容灾和低延迟，在公有云（如 AWS EKS）上也有一套集群，甚至在一些工厂、门店的本地服务器（边缘节点）也部署了轻量级的 K3S。你可以通过 Rancher 的“集群导入”功能，将这些异构的 Kubernetes 集群全部纳管进来。在 Rancher 的全局视图中，你可以统一查看所有集群的健康状态、统一下发应用（通过 Rancher Fleet 这个 GitOps 工具）、统一管理访问策略。这种“一处管控，全局生效”的能力，极大地简化了混合基础设施的运维复杂度。

应用商店与标准化交付：Rancher 内置了 Helm 应用商店，你可以一键部署 MySQL、Redis、Nginx Ingress Controller 等常见中间件。更重要的是，你可以搭建自己的私有应用商店。将公司内部通用的业务中间件、前端后台模板等打包成 Helm Chart，上传到私有商店。这样，各个业务团队的开发人员不需要关心复杂的 YAML 编写，直接从商店选择版本、填写几个配置参数，就能一键部署一套标准化的、带监控和日志的测试环境。这极大地提升了交付速度和规范性。

踩过几次坑之后，我最大的体会是，技术选型不仅要看技术本身，更要看它的生态和可维护性。Rancher + K3S 这套组合，不仅降低了 Kubernetes 的使用门槛，更重要的是，它通过一个统一的管理平面，把集群部署、运维监控、安全策略、应用交付这些分散的痛点串联了起来，形成了一套完整的解决方案。对于资源和技术储备都相对有限的团队来说，它能让你用最小的运维投入，获得接近大厂的云原生能力。刚开始可能会觉得配置项有点多，但一旦跑顺了，你会发现它为团队节省的时间和精力是巨大的。