本文详细记录了在多台服务器上安装和配置 Rancher v2.9.2 及其相关组件（如 K3s 和 Docker）的全过程，涵盖了安装步骤、遇到的问题及其解决方案、配置调整以及集群导入的操作，重点解决了集群重置死锁问题和 Docker 镜像拉取失败的情况。

---

关键流程与步骤

Rancher 安装与启动

• 在 141 主节点 上传了 Rancher 相关镜像文件：
  • 使用命令：

    docker load −i /opt/rancher/rancher_v2.9.2_imagedocker load −i /opt/rancher/rancher_agent_2.9.2

    • 

• 运行 Rancher 容器命令示例：

  docker run −d −−privileged −−restart=unless−stopped −−name rancher−p 8880:80 −p 8443:443 −e CATTLE_SYSTEM_CATALOG=bundled−v /var/lib/rancher:/var/lib/rancher rancher/rancher:v2.9.2

集群死锁问题排查与解决

• K3s 出现集群重置（Cluster Reset）状态死锁，导致 Kubernetes API Server（127.0.0.1:6444）未启动，Rancher 报错连接拒绝（connection refused）。
• 解决方案：
  • 删除重置标记文件：

    rm −f /var/lib/rancher/k3s/server/db/reset−flagrm −f /var/lib/rancher/k3s/server/db/reset−flag

  • 删除数据目录：

    rm −rf /var/lib/rancherrm −rf /var/lib/rancher

  • 重启 rancher 容器：

    docker restart rancherdocker restart rancher

  • 若无效，则需重新安装 Rancher。
  • 解决：该问题参考了社区 GitHub 解决方案：rancher/issues/44279。

#放弃141之后Rancher 再次部署与访问

• 在 142 从节点 使用类似命令运行，端口更改为 7880 和 7443，且访问需使用 HTTPS：

  docker run −d −−privileged −−restart=unless−stopped −−name rancher−p 7880:80 −p 7443:443−e CATTLE_SYSTEM_CATALOG=bundled−v /var/lib/rancher:/var/lib/rancher rancher/rancher:v2.9.2

• 初始密码为：123456abcdef

集群导入与配置调整

• 在 Rancher UI 生成导入主集群命令。
• 需要先绕过证书检查，编辑 Deployment：
  • 执行命令：

    kubectl edit deployment cattle−cluster−agent −n cattle−systemkubectl edit deployment cattle−cluster−agent −n cattle−system

  • 替换标签字段：
    • 将 beta.kubernetes.io 替换为 kubernetes.io
    • 将 node-role.kubernetes.io/master 替换为 node-role.kubernetes.io/control-plane

---

Docker 镜像拉取问题与解决

• 问题描述：Kubernetes 无法连接 Docker 官方仓库，导致无法拉取镜像，如 nginx:1.25.3。
• 解决方法：更换为国内镜像源以提高下载速度和成功率。

镜像源网址	备注
https://docker.mirrors.ustc.edu.cn	中国科技大学镜像
https://hub-mirror.c.163.com	网易镜像
https://registry.docker-cn.com	Docker 中国镜像
https://docker.m.daocloud.io	DaoCloud 镜像

• 配置步骤：

  • 创建配置文件：

    sudo mkdir −p /etc/dockersudo mkdir −p /etc/docker

    sudo tee /etc/docker/daemon.json <<−′EOF′{"registry−mirrors":["https://docker.mirrors.ustc.edu.cn","https://hub−mirror.c.163.com","https://registry.docker−cn.com","https://docker.m.daocloud.io"]}EOFsudo tee /etc/docker/daemon.json <<−′EOF′{"registry−mirrors":["https://docker.mirrors.ustc.edu.cn","https://hub−mirror.c.163.com","https://registry.docker−cn.com","https://docker.m.daocloud.io"]}EOF

  • 重载守护进程并重启 Docker 服务：

    sudo systemctl daemon−reloadsudo systemctl daemon−reload

    sudo systemctl restart dockersudo systemctl restart docker

• 配置完成后，镜像拉取成功可用。

Rancher 导入已有 K8s 集群（141 master）

1️⃣ 导入整体流程（逻辑图文字版）

纯文本

纯文本

Rancher UI（142）
   │
   │ 生成 import YAML（含 cluster-agent / node-agent）
   ▼
kubectl apply（141 master）
   │
   │ 跳过自签名证书校验
   ▼
cattle-cluster-agent 启动
   │
   │ 适配 K8s v1.32 标签
   ▼
Agent 注册成功 → Rancher UI 显示 Active

---

2️⃣ 前置条件检查（很多人忽略）

检查项	命令	期望结果
kubectl 可用	kubectl get nodes	正常返回节点
API Server 可达	kubectl cluster-info	无报错
节点时间同步	date	所有节点时间一致
网络连通	curl https://142:7443	能访问 Rancher

⚠️ 时间不同步会导致 TLS 握手失败

---

3️⃣ Step-by-Step 操作详解

✅ ① Rancher UI 生成导入命令

路径

纯文本

纯文本

Rancher → Clusters → Add Cluster → Import Existing Cluster

填写信息

字段	值
Cluster Name	k8s-master
Labels	可不填
Agent Environment	默认

📌 点击 Create​ 后，会生成一条类似命令：

bash

bash

kubectl apply -f https://142:7443/v3/import/abcd1234.yaml

---

✅ ② 在 141 master 执行导入（关键）

❗ 必须绕过证书

Rancher 使用自签名证书，直接 kubectl apply会失败。

✅ 正确方式

bash

bash

curl --insecure -sfL \
https://192.168.222.142:7443/v3/import/abcd1234.yaml \
| kubectl apply -f -

📌 参数解释：

参数	作用
--insecure	跳过证书校验
-s	静默模式
-f	失败不报错
-L	跟随重定向

---

✅ ③ 验证 Agent 是否已创建

bash

bash

kubectl get pods -n cattle-system

期望看到：

纯文本

纯文本

cattle-cluster-agent-xxxxx     0/1   Pending / Running
cattle-node-agent-xxxxx        1/1   Running

---

✅ ④ 修复 K8s v1.32 标签不兼容（重点）

🔴 问题现象

• Agent Pod 一直 Pending

• Rancher UI 显示：

纯文本

纯文本

Cluster agent is not connected

🔴 原因

项目	旧（≤1.23）	新（≥1.24）
架构标签	beta.kubernetes.io/*	kubernetes.io/*
Master 标签	node-role.kubernetes.io/master	node-role.kubernetes.io/control-plane

Agent YAML 仍使用旧标签​ → 调度失败

---

✅ 修复方法（必须做）

bash

bash

kubectl edit deployment cattle-cluster-agent -n cattle-system

进入 vi 后，末行模式执行：

vim

vim

:%s/beta.kubernetes.io/kubernetes.io/g
:%s/node-role.kubernetes.io\/master/node-role.kubernetes.io\/control-plane/g

保存退出：

vim

vim

:wq

📌 这会触发 Rolling Update，Agent 自动重建。

---

4️⃣ 状态确认（导入成功标志）

✅ Rancher UI

位置	状态
Cluster List	Active
Node Count	≥1
Agent Status	Connected

---

✅ 命令行验证（141）

bash

bash

kubectl get nodes
kubectl get pods -A | grep cattle

✅ 正常结果：

• 所有节点 Ready

• cattle-cluster-agentRunning

• 无 ImagePullBackOff

---

5️⃣ 常见故障 & 精准排查表

故障现象	根因	排查命令	解决
x509 certificate error	自签名证书	curl https://142:7443	加 --insecure
Agent Pending	标签不兼容	kubectl describe pod cattle-cluster-agent	替换标签
Agent CrashLoopBackOff	版本不匹配	kubectl logs cattle-cluster-agent	升级 Rancher
UI 一直 Unavailable	网络不通	telnet 142 7443	放通防火墙
node-agent Missing	DaemonSet 未调度	kubectl get ds -n cattle-system	检查污点

---

6️⃣ 核心原理说明（为什么一定要这样）

🔹 Rancher 导入 ≠ 接管

项目	说明
etcd	不接管
apiserver	不接管
控制面	保留原样
Agent	仅做管理通道

🔹 Agent 的作用

组件	作用
cattle-cluster-agent	集群级心跳、状态同步
cattle-node-agent	节点级操作（exec/logs）