故障场景描述

在 K3s 集群经历长时间运行（如 2 年以上）或底层容器运行时（Containerd）崩溃重启后，Rancher 界面显示集群状态为 Unavailable，错误提示通常为 "Cluster agent is not connected"。

故障诊断流程

第一阶段：排查 K3s 节点健康度

在手动处理 Rancher 连接前，必须确保 K3s 核心服务已恢复。

  • 检查容器运行时状态：

    1
    2
    # 如果报错 connection refused，说明 containerd 没起
    crictl ps

  • 检查孤儿挂载点（Device busy）： Kubelet 频繁报错 device or resource busy 会导致 API Server 响应极慢，进而撑挂 Rancher 隧道。

    1
    2
    # 查找并懒卸载残留路径
    grep "kubelet/pods" /proc/mounts | awk '{print $2}' | xargs -I {} umount -l {}

  • 检查镜像拉取（Nexus/Registry）： 确保业务 Pod 不再处于 ImagePullBackOff，否则 API Server 会因处理大量重试请求而无暇顾及 Rancher 隧道。

第二阶段：排查 Rancher Agent 日志

观察 cattle-system 命名空间下的 Agent 状态：

1
kubectl logs -f -n cattle-system -l app=cattle-cluster-agent

  • 正常状态：日志最后一行停在 Connecting to proxy。

  • 异常状态：出现 websocket: close 1006 或 tunnel disconnect，通常意味着长连接被中断或 Token/证书失效。

渐进式解决方案

方案 A：平滑重启（首选）

在不破坏资源的情况下，尝试重置连接 Session。

  1. 重启 Rancher Server 容器（在 Rancher 宿主机上）：

    1
    docker restart <rancher_container_id>

  2. 重置 Agent Deployment（在 K3s 节点上）：

    1
    kubectl rollout restart deployment cattle-cluster-agent -n cattle-system

方案 B：重新注册 Agent（终极方案）

如果平滑重启无效，说明 Rancher 的 Webhook 或 Agent 状态机已死锁，需要彻底重建。

清理现有 Agent 资源

1
2
# 删除整个命名空间
kubectl delete ns cattle-system

关键步骤：打破 Webhook 死锁

创建新命名空间时，旧的 Webhook 规则会因为找不到 rancher-webhook 服务而拦截请求，导致创建失败。必须先手动移除：

1
2
3
4
# 删除拦截命名空间创建的验证规则
kubectl delete validatingwebhookconfigurations rancher.cattle.io
# 删除变更规则（防止干扰 Pod 重建）
kubectl delete mutatingwebhookconfigurations rancher.cattle.io

获取并执行导入命令

在 Rancher UI 中找到该集群，进入 Registration（注册）页面，复制 kubectl apply 命令并执行：

1
2
# 示例命令（请以实际生成的为准）
curl --insecure -sfL https://<RANCHER_URL>/v3/import/<TOKEN>.yaml | kubectl apply -f -

恢复验证

执行完重新注册后，按以下顺序检查：

  1. 命名空间重建：kubectl get ns cattle-system 状态应为 Active。

  2. Pod 状态：kubectl get pod -n cattle-system 应显示 Running。

  3. Rancher UI 状态：集群状态应在 1 分钟内从 Unavailable 变为 Active。

经验总结与预防

  • 时间同步：Rancher 与节点时间偏差超过 60s 会导致隧道立即断开，确保存储和计算节点均开启 NTP。

  • Webhook 风险：手动删除 cattle-system 时，务必记得清理 validatingwebhookconfigurations，否则无法重新 apply。

  • 证书周期：对于运行 2 年以上的集群，注意 K3s 自动生成的证书是否已自动轮换，重启 K3s 服务通常能触发此逻辑。