cattle-cluster-agent 彻底修复 + 磁盘扩容 + CA-Checksum 根因分析

日期: 2026-08-15 ~ 08-17（跨三次会话）
集群: GPU AI-EAR RKE2 v1.35.6，节点 192.168.122.37 (szb122037.local)
新节点: 192.168.122.9 (szb122009) system-agent 安装
Rancher: v2.14.3，管理集群 192.168.122.32
前置: 02 号文档遗留 4 个问题（CA checksum / DNS / hosts.toml / DiskPressure）
结果: ✅ 全部 9 个问题已修复，agent 稳定运行 + watchdog v5 持久保护

一、问题总览

#	问题	根因	修复方式	状态
1	DiskPressure → Pod 驱逐	VM 磁盘仅 10G，kubelet 5% 阈值	`virsh blockresize` 扩容到 30G→99G	✅
2	DNS `search local` 导致超时	节点 resolv.conf 中 `search local` 被注入到 Pod	`/etc/rancher/rke2/resolv.conf` + `config.yaml`	✅
3	CA checksum 反复不匹配	`jq -r` 追加尾随 `\n`，改变了 SHA256	用 `jq -r .value \| sha256sum` 计算正确值	✅
4	kubectl 修改被 Rancher 回滚	Rancher 管理面 + RKE2 addon 双重覆盖	修正 import YAML 替换 manifest	✅
5	credential secret 缺少 namespace	import YAML 生成时 namespace 字段为空	watchdog 自动 patch + restart	✅
6	cacerts API 被清空致 CA 验证失败	Rancher 服务器 cacerts 设置被重置	通过 ConfigMap 挂载 serverca + 清空 checksum	✅
7	system-agent-upgrader Plan 持续 Error	Plan 中 `STRICT_VERIFY=true` + 无 CA checksum	Patch Plan env 设 `STRICT_VERIFY=false`	✅
8	新节点 system-agent 安装失败	安装脚本要求 CA checksum 但服务器未提供	手动传 `--ca-checksum` 参数	✅
9	Rancher `--no-cacerts` 致 cacerts 永远为空	Helm `ingress.tls.source=secret` 触发 `--no-cacerts`	管理集群保持 cacerts 空 + 下游 ConfigMap 提供 serverca	✅

二、问题 1：DiskPressure 磁盘扩容（10G → 30G → 99G）

2.1 背景

RKE2 + Rancher 系统组件 + 镜像存储轻松占满 10G 磁盘。 kubelet 的 nodefs.available < 5%（约 500MB）触发 Pod 驱逐，包括 cattle-cluster-agent 本身。

2.2 扩容步骤（在线，无需停机）

bash

# === 宿主机（libvirt host）===
virsh blockresize szb122037 --path /dev/vg0/szb122037 --size 30G   # 第一次 30G
virsh blockresize szb122037 --path /dev/vg0/szb122037 --size 99G   # 后续追加到 99G

# === VM 内部 ===
growpart /dev/vda 4           # 扩展 vda4 分区填满虚拟磁盘
xfs_growfs /                  # 在线扩展 XFS
df -h /                       # 验证: /dev/vda4 99G 7.5G 92G 8%
systemctl restart rke2-server # ⚠️ 必须！否则 kubelet 缓存的 stats 不更新

2.3 验证

bash

kubectl get node szb122037.local -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'
# MemoryPressure=False
# DiskPressure=False      ← 恢复正常
# PIDPressure=False
# Ready=True

三、问题 2：DNS `search local` 导致 CoreDNS 超时

3.1 症状

agent pod 启动时 DNS 解析 gpu.ai-ear.cn 超时（5s × 3 次尝试 = 15s+），偶发连接失败：

INFO: Waiting for https://gpu.ai-ear.cn/ping to be accessible...
WARN: Timed out waiting for https://gpu.ai-ear.cn/ping

3.2 排查思路

bash

# Step 1: 查看 Pod 内的 DNS 配置
kubectl exec <pod> -- cat /etc/resolv.conf
# 发现: search local cattle-system.svc.cluster.local ...

# Step 2: 查看节点 DNS 配置
cat /etc/resolv.conf
# 发现: search local  ← 罪魁祸首

# Step 3: 理解传播链
# 节点 /etc/resolv.conf → kubelet 读取 → 注入 Pod DNS policy (ClusterFirst)
# Pod DNS = CoreDNS(10.43.0.10) + 节点的 search domains
# CoreDNS 收到 "gpu.ai-ear.cn.local" 查询 → 上游 DNS 不识别 → 超时

3.3 修复

bash

# 1. 创建 RKE2 专用 resolv.conf（只含 nameserver，不含 search）
mkdir -p /etc/rancher/rke2
echo 'nameserver 192.168.122.1' > /etc/rancher/rke2/resolv.conf

# 2. 告诉 RKE2 使用这个文件代替系统 resolv.conf
cat > /etc/rancher/rke2/config.yaml << 'EOF'
resolv-conf: /etc/rancher/rke2/resolv.conf
EOF

# 3. 重启 RKE2（config.yaml 只在启动时读取）
systemctl restart rke2-server

# 4. 验证 Pod DNS 不再包含 search local
kubectl exec <pod> -- cat /etc/resolv.conf
# search cattle-system.svc.cluster.local svc.cluster.local cluster.local
# nameserver 10.43.0.10
# （无 search local）

⚠️ 节点重建会丢失这些文件，需要备份或纳入 IaC（如 Ansible/cloud-init）。这是 08-17 agent 再次崩溃的原因之一。

四、问题 3：CA Checksum 根因分析（核心陷阱）

4.1 症状

Rancher agent 启动时反复报：

ERROR: Configured cacerts checksum (6903fb1e...da4424)
does not match given --ca-checksum (cd9078b7...bec19a)
ERROR: Please check if the correct certificate is configured at https://gpu.ai-ear.cn/v3/settings/cacerts

两个 checksum 对应同一个 CA 证书，但哈希值不同。

4.2 排查思路

bash

# Step 1: 查看 agent 日志中的两个 checksum
kubectl logs <agent-pod> | grep "does not match"
# 6903fb1e... = agent 自己计算的
# cd9078b7... = deployment env 传入的（来自 Rancher 管理面）

# Step 2: 查看 deployment 的 checksum 来源
kubectl get deployment cattle-cluster-agent -n cattle-system -o yaml | grep CATTLE_CA_CHECKSUM
# value: cd9078b7...  ← 来自 Rancher import YAML

# Step 3: 查看 Rancher import YAML 中的 checksum
curl -sk https://gpu.ai-ear.cn/v3/import/<token>_<cluster-id>.yaml | grep CATTLE_CA_CHECKSUM
# value: "cd9078b7..."  ← Rancher 服务端自动生成的

# Step 4: 手动计算，确认差异
# 方式 A: jq -r（agent 行为）
curl -sk https://gpu.ai-ear.cn/v3/settings/cacerts \
  | jq -r '.value | select(length > 0)' | sha256sum
# 6903fb1eaadc30860dfe49b374cc4dedd7f45fb45d2f578f995a53b9ebda4424

# 方式 B: Python hashlib（Rancher 服务端行为）
curl -sk https://gpu.ai-ear.cn/v3/settings/cacerts > /tmp/cacerts_raw.json
python3 -c "
import json, hashlib
v = json.load(open('/tmp/cacerts_raw.json'))['value']
print(f'长度: {len(v)} bytes')   # 1090
print(hashlib.sha256(v.encode()).hexdigest())  # cd9078b7...
"

# Step 5: 对比字节数差异
curl -sk https://gpu.ai-ear.cn/v3/settings/cacerts \
  | jq -r '.value | select(length > 0)' | wc -c    # 1091（多了 1 字节）
python3 -c "
import json
v = json.load(open('/tmp/cacerts_raw.json'))['value']
print(len(v))                                       # 1090
"

4.3 根因：`jq -r` 的尾随换行符

Rancher agent 的 run.sh entrypoint 内部使用以下方式计算 checksum：

bash

# Rancher agent 内部代码 (run.sh)
curl --insecure -s -fL $CATTLE_SERVER/v3/settings/cacerts \
  | jq -r '.value | select(length > 0)' > $temp
CATTLE_SERVER_CHECKSUM=$(sha256sum $temp | awk '{print $1}')

关键细节：jq -r 将 JSON 字符串值解析后输出到 stdout 时，会在末尾追加一个换行符 \n。

例如，JSON value 是 "abc"（3 字节），jq -r 输出 abc\n（4 字节）。

这导致：

Rancher 服务端 (import YAML / nodeCommand):
  SHA256(原始 JSON value) = SHA256(1090 bytes) = cd9078b7f2b7e605ab8d6fd8629d8de8dda9efbd5fd6fa5455f634c769bec19a

Rancher Agent (run.sh 内部):
  curl API | jq -r '.value' | sha256sum = SHA256(1091 bytes) = 6903fb1eaadc30860dfe49b374cc4dedd7f45fb45d2f578f995a53b9ebda4424
  (jq -r 在输出末尾追加 \n，多了 1 字节)

计算方式	输入长度	SHA256	是否正确
`jq -r .value \| sha256sum`	1091 bytes（PEM + `\n`）	`6903fb1e...`	✅ 正确（agent 行为）
Python `hashlib.sha256(value.encode())`	1090 bytes	`cd9078b7...`	❌ 错误（Rancher UI 显示的值）

4.4 正确的 checksum 计算方法

bash

# 方法 1：使用 jq（推荐，与 agent 行为一致）
curl -sk https://gpu.ai-ear.cn/v3/settings/cacerts \
  | jq -r '.value | select(length > 0)' | sha256sum | awk '{print $1}'

# 方法 2：Python 模拟 jq -r 行为（需追加 \n）
python3 -c "
import json, hashlib
v = json.load(open('/tmp/cacerts_raw.json'))['value']
print(hashlib.sha256((v + '\n').encode()).hexdigest())
"

# 方法 3：如果已知道正确的 PEM 文件
sha256sum /path/to/cacert.pem

4.5 为什么无法从 Rancher 服务端修复

caChecksum 不是 ClusterRegistrationToken 的 spec 字段，而是 status 中自动计算的
Rancher controller 会不断回滚 status 到自动计算值
无法从外部修改 Rancher 的内部计算逻辑
只能从下游集群（被管理集群）侧修正

⚠️ 教训：对 Rancher 的任何 checksum 值，永远不要信任 UI/API 给出的值，必须用 curl ... | jq -r .value | sha256sum 重新计算。不要用 Python/Go 的 JSON parser 直接读取 .value 字符串再哈希——少了那个 \n 就会导致不匹配。

五、问题 4：Rancher 管理面反复覆盖 manifest

5.1 症状

通过 kubectl set env 修改 cattle-cluster-agent 的 CATTLE_CA_CHECKSUM 后，几分钟内又被回滚为旧值 cd9078b7...。即使直接编辑 manifest 文件，也会被覆盖。

5.2 排查思路

bash

# Step 1: 确认 manifest 被覆盖
sed -i 's/WRONG/RIGHT/' /var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml
sleep 120
grep CATTLE_CA_CHECKSUM /var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml
# 又回到了 WRONG...

# Step 2: 理解覆盖链
# Rancher 管理集群 → 检测到集群状态变化 → 重新生成 import YAML → 推送到下游集群
# RKE2 addon controller → 定期同步 manifest 文件到集群资源
# 双重覆盖 → 任何手动修改最终都会被回滚

5.3 根因

存在两层覆盖机制：

Rancher 管理面：Rancher controller 监控集群状态，当集群状态变化时，重新生成 import YAML 并写入 manifest 文件
RKE2 addon controller：定期从 /var/lib/rancher/rke2/server/manifests/ 重建 Kubernetes 资源

5.4 解决方案

必须用修正后的 import YAML 整体替换 manifest 文件：

bash

curl -sk https://gpu.ai-ear.cn/v3/import/<TOKEN>_<CLUSTER_ID>.yaml \
  | sed 's/WRONG_CHECKSUM/CORRECT_CHECKSUM/g' \
  > /var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml

加上 watchdog 守护脚本每 2 分钟自动修正。

六、问题 5：Credential Secret 缺少 Namespace

6.1 症状

agent 连接成功（日志显示 "Connected to proxy"），但 Rancher UI 仍然显示 "Waiting for cluster agent to connect"。 fleet-agent 运行正常，但 Rancher 不承认集群已就绪。

6.2 排查思路

bash

# Step 1: 检查 credential secrets
kubectl get secret -n cattle-system -l cattle.io/creator=norman -o yaml | grep namespace:
# 发现: namespace: ""   ← 空值！

# Step 2: 理解 namespace 的作用
# cattle-credentials secret 中的 .data.namespace 字段存储的是集群 ID（如 c-m-9nj98wcj）
# Rancher 通过此字段将 agent 映射到对应的集群记录
# 空值 → Rancher 无法识别此 agent 属于哪个集群

# Step 3: 查看 import YAML 中的 namespace 字段
curl -sk https://gpu.ai-ear.cn/v3/import/<TOKEN>_<CLUSTER_ID>.yaml | grep -A2 "namespace:"
# import YAML 生成的 secret 中 namespace 字段为空

# Step 4: 计算正确的 base64 值
echo -n "c-m-9nj98wcj" | base64
# Yy1tLTluajk4d2Nq

6.3 根因

Rancher v2.14.3 import YAML 生成 credential secret 时，.data.namespace 字段为空字符串。 Rancher 期望此字段包含 cluster ID 的 base64 编码值，用于将 agent 映射到集群。

6.4 修复

bash

CLUSTER_ID="c-m-9nj98wcj"
NS_B64=$(echo -n "$CLUSTER_ID" | base64)   # Yy1tLTluajk4d2Nq

# 修复所有 cattle-credentials secrets
for SECRET in $(kubectl get secret -n cattle-system -o name | grep cattle-credentials-); do
    kubectl patch "$SECRET" -n cattle-system \
        --type=merge -p "{\"data\":{\"namespace\":\"$NS_B64\"}}"
done

# 同时修复 manifest 文件
sed -i "s/namespace: \"\"/namespace: \"$NS_B64\"/" \
    /var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml

七、完整修复步骤（一键执行）

以下为在节点 192.168.122.37 上的完整修复流程，适用于从零开始修复。

7.1 前提条件

bash

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
KUBECTL=/var/lib/rancher/rke2/bin/kubectl
${KUBECTL} version --short 2>/dev/null

7.2 Step 1: DNS 修复

bash

mkdir -p /etc/rancher/rke2
echo 'nameserver 192.168.122.1' > /etc/rancher/rke2/resolv.conf

cat > /etc/rancher/rke2/config.yaml << 'EOF'
resolv-conf: /etc/rancher/rke2/resolv.conf
EOF

systemctl restart rke2-server
sleep 30

7.3 Step 2: 计算正确的 CA Checksum

bash

CORRECT_CHECKSUM=$(curl -sk https://gpu.ai-ear.cn/v3/settings/cacerts \
  | jq -r '.value | select(length > 0)' | sha256sum | awk '{print $1}')

WRONG_CHECKSUM="cd9078b7f2b7e605ab8d6fd8629d8de8dda9efbd5fd6fa5455f634c769bec19a"
echo "Correct: $CORRECT_CHECKSUM"
echo "Wrong:   $WRONG_CHECKSUM"

7.4 Step 3: 替换 Manifest + 修复 Namespace

bash

RANCHER_URL="https://gpu.ai-ear.cn"
TOKEN="xxx"
CLUSTER_ID="c-m-9nj98wcj"
NS_B64=$(echo -n "$CLUSTER_ID" | base64)
MANIFEST="/var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml"

curl -sk "${RANCHER_URL}/v3/import/${TOKEN}_${CLUSTER_ID}.yaml" \
  | sed "s/${WRONG_CHECKSUM}/${CORRECT_CHECKSUM}/g" \
  | sed "s/namespace: \"\"/namespace: \"${NS_B64}\"/" \
  > "$MANIFEST"

7.5 Step 4: 修复 Credential Secrets

bash

for SECRET in $(${KUBECTL} get secret -n cattle-system -o name | grep cattle-credentials-); do
    ${KUBECTL} patch "$SECRET" -n cattle-system \
        --type=merge -p "{\"data\":{\"namespace\":\"${NS_B64}\"}}"
done

7.6 Step 5: 重启 Agent + 部署 Watchdog

bash

${KUBECTL} rollout restart deployment/cattle-cluster-agent -n cattle-system

# 部署 watchdog（见第八节）
chmod +x /usr/local/bin/fix-cattle-agent-checksum.sh
systemctl daemon-reload
systemctl enable --now cattle-agent-watchdog.timer

八、Watchdog 守护脚本（核心持久方案）

8.1 设计思路

由于 Rancher 管理面和 RKE2 addon controller 会持续覆盖 manifest 和 deployment，单次修复不够——需要一个后台守护进程，每 2 分钟自动检测并修正被回滚的配置。

8.2 脚本文件

/usr/local/bin/fix-cattle-agent-checksum.sh

bash

#!/bin/bash
# Watchdog: 防止 Rancher 管理面覆盖导致 cattle-cluster-agent 崩溃
# 根因:
#   1. Rancher v2.14.3 bug - 服务端和 agent 计算 checksum 方式不同(jq -r 追加 \n)
#   2. import YAML 生成的 secret 缺少 namespace 字段 (应为 c-m-9nj98wcj)

KUBECTL=/var/lib/rancher/rke2/bin/kubectl
export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
WRONG_ID="cd9078b7f2b7e605ab8d6fd8629d8de8dda9efbd5fd6fa5455f634c769bec19a"
CORRECT="6903fb1eaadc30860dfe49b374cc4dedd7f45fb45d2f578f995a53b9ebda4424"
CLUSTER_ID="c-m-9nj98wcj"
NS_B64=$(echo -n "$CLUSTER_ID" | base64)
MANIFEST=/var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml
LOG_TAG="cattle-agent-watchdog"
CHANGED=false

# 1. 修复 manifest 文件中的 CA checksum
if grep -q "$WRONG_ID" "$MANIFEST" 2>/dev/null; then
    logger -t "$LOG_TAG" "Manifest has wrong CA checksum, fixing..."
    sed -i "s/$WRONG_ID/$CORRECT/g" "$MANIFEST"
    CHANGED=true
fi

# 2. 修复 manifest 文件中的 secret namespace
if grep -q 'namespace: ""' "$MANIFEST" 2>/dev/null; then
    logger -t "$LOG_TAG" "Manifest has empty secret namespace, fixing..."
    sed -i "s/namespace: \"\"/namespace: \"$NS_B64\"/" "$MANIFEST"
    CHANGED=true
fi

# 3. 修复 deployment 的 CA checksum（如果被覆盖）
DEPLOY_ENV=$(${KUBECTL} get deployment cattle-cluster-agent -n cattle-system \
    -o jsonpath='{.spec.template.spec.containers[0].env}' 2>/dev/null)
if echo "$DEPLOY_ENV" | grep -q "$WRONG_ID"; then
    logger -t "$LOG_TAG" "Deployment has wrong checksum, patching..."
    ${KUBECTL} set env deployment/cattle-cluster-agent -n cattle-system \
        CATTLE_CA_CHECKSUM="$CORRECT" 2>&1
    CHANGED=true
fi

# 4. 修复 credential secrets 的 namespace 字段
for SECRET_NAME in cattle-credentials-c65c301312 cattle-credentials-ddc753072d; do
    NS_VAL=$(${KUBECTL} get secret "$SECRET_NAME" -n cattle-system \
        -o jsonpath='{.data.namespace}' 2>/dev/null | base64 -d 2>/dev/null)
    if [ -z "$NS_VAL" ]; then
        logger -t "$LOG_TAG" "Secret $SECRET_NAME has empty namespace, fixing..."
        ${KUBECTL} patch secret "$SECRET_NAME" -n cattle-system \
            --type=merge -p "{\"data\":{\"namespace\":\"$NS_B64\"}}" 2>&1
        CHANGED=true
    fi
done

# 5. 如果有任何修改，重启 agent
if [ "$CHANGED" = true ]; then
    logger -t "$LOG_TAG" "Changes made, restarting agent..."
    ${KUBECTL} rollout restart deployment/cattle-cluster-agent -n cattle-system 2>&1
fi

# 6. 检查 pod 是否在 CrashLoopBackOff (兜底)
if ${KUBECTL} get pods -n cattle-system -l app=cattle-cluster-agent 2>/dev/null \
    | grep -q CrashLoopBackOff; then
    logger -t "$LOG_TAG" "Agent in CrashLoopBackOff, re-applying manifest..."
    sed -i "s/$WRONG_ID/$CORRECT/g" "$MANIFEST" 2>/dev/null
    sed -i "s/namespace: \"\"/namespace: \"$NS_B64\"/" "$MANIFEST" 2>/dev/null
    ${KUBECTL} apply -f "$MANIFEST" 2>&1
    ${KUBECTL} rollout restart deployment/cattle-cluster-agent -n cattle-system 2>&1
fi

/etc/systemd/system/cattle-agent-watchdog.service

ini

[Unit]
Description=Fix cattle-cluster-agent CA checksum if overwritten by Rancher
After=rke2-server.service

[Service]
Type=oneshot
ExecStart=/usr/local/bin/fix-cattle-agent-checksum.sh

/etc/systemd/system/cattle-agent-watchdog.timer

ini

[Unit]
Description=Periodically fix cattle-cluster-agent CA checksum

[Timer]
OnBootSec=30
OnUnitActiveSec=120
AccuracySec=5

[Install]
WantedBy=timers.target

8.3 安装命令

bash

chmod +x /usr/local/bin/fix-cattle-agent-checksum.sh
systemctl daemon-reload
systemctl enable --now cattle-agent-watchdog.timer

# 手动执行一次测试
systemctl start cattle-agent-watchdog.service

# 检查 timer 状态
systemctl list-timers cattle-agent-watchdog.timer

8.4 日志查看

bash

journalctl -t cattle-agent-watchdog --no-pager -n 20

九、验证清单

9.1 完整验证命令

bash

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
KUBECTL=/var/lib/rancher/rke2/bin/kubectl

echo "=== 1. Node 状态 ==="
${KUBECTL} get nodes -o wide
${KUBECTL} get node szb122037.local \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'

echo "=== 2. Agent Pod 状态 ==="
${KUBECTL} get pods -n cattle-system -o wide

echo "=== 3. Agent 环境变量 ==="
${KUBECTL} exec deployment/cattle-cluster-agent -n cattle-system -- env \
  | grep -E "CATTLE_CA_CHECKSUM|CATTLE_CREDENTIAL_NAME|CATTLE_SERVER="

echo "=== 4. Agent 日志 ==="
${KUBECTL} logs deployment/cattle-cluster-agent -n cattle-system --tail=10

echo "=== 5. Secret Namespace ==="
for S in $(${KUBECTL} get secret -n cattle-system -o name | grep cattle-credentials-); do
    echo -n "$S: "
    ${KUBECTL} get "$S" -n cattle-system -o jsonpath='{.data.namespace}' | base64 -d
    echo
done

echo "=== 6. Manifest Checksum ==="
grep -A1 "CATTLE_CA_CHECKSUM" \
  /var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml | head -2

echo "=== 7. Manifest Namespace ==="
grep -B1 -A1 "namespace:.*Yy1t" \
  /var/lib/rancher/rke2/server/manifests/rancher/cluster-agent.yaml

echo "=== 8. Fleet Agent ==="
${KUBECTL} get pods -n cattle-fleet-system -o wide

echo "=== 9. Watchdog Timer ==="
systemctl list-timers cattle-agent-watchdog.timer --no-pager

echo "=== 10. 磁盘 ==="
df -h /

9.2 期望输出

检查项	期望值
Node Status	`Ready`
DiskPressure	`False`
Agent Pod	`1/1 Running`, 无 `CrashLoopBackOff`
CATTLE_CA_CHECKSUM	`6903fb1eaadc30860dfe49b374cc4dedd7f45fb45d2f578f995a53b9ebda4424`
CATTLE_CREDENTIAL_NAME	`cattle-credentials-c65c301312`
Agent 日志	`Connected to proxy`
Secret Namespace	`c-m-9nj98wcj`（非空）
Manifest Checksum	`6903fb1e...`（非 `cd9078b7...`）
Fleet Agent	`Running`
Watchdog Timer	`active/waiting`，下次触发在 2 分钟内
磁盘使用率	< 50%

十二、最终集群状态（2026-08-17 13:00 UTC）

=== Nodes ===
NAME              STATUS   ROLES                       AGE   VERSION          INTERNAL-IP
szb122037.local   Ready    control-plane,etcd,worker   97m   v1.35.6+rke2r1   192.168.122.37

=== Key Pods ===
cattle-cluster-agent-85f8865cd6-5wl6s   1/1  Running  0  (Connected to proxy ✅)
fleet-agent-778d865986-pnzx2            1/1  Running  0

=== Agent Connection ===
CATTLE_SERVER=https://gpu.ai-ear.cn
CATTLE_CA_CHECKSUM=6903fb1eaadc30860dfe49b374cc4dedd7f45fb45d2f578f995a53b9ebda4424
CATTLE_CREDENTIAL_NAME=cattle-credentials-c65c301312
Connecting to wss://gpu.ai-ear.cn/v3/connect/register
Connected to proxy ✅

=== Disk ===
/dev/vda4   99G   7.5G   92G   8%

=== Node Conditions ===
MemoryPressure=False  DiskPressure=False  PIDPressure=False  Ready=True

=== Secret Namespace ===
cattle-credentials-c65c301312: c-m-9nj98wcj
cattle-credentials-ddc753072d: c-m-9nj98wcj

十三、经验总结

🔑 五大关键知识点

#	要点	说明
1	Rancher UI 的 checksum 不可信	Rancher 服务端用 `SHA256(raw_value)`，agent 用 `SHA256(jq -r output)` — 差了 1 字节 `\n`（v2.14.3 bug）
2	DNS search domain 注入 Pod	节点的 `search local` 通过 kubelet 注入 Pod DNS 策略，导致 `gpu.ai-ear.cn.local` 查询超时
3	Manifest 会被双重覆盖	Rancher 管理面 + RKE2 addon controller 会持续同步 manifest，单次 `kubectl set env` 会被回滚
4	Credential secret 必须有 namespace	import YAML 生成的 secret `.data.namespace` 为空，Rancher 无法映射 agent 到集群
5	Watchdog 是持久方案	每 2 分钟自动检测并修正被覆盖的配置，是唯一能对抗 Rancher 管理面持续覆盖的方案

📝 排查决策树

agent CrashLoopBackOff / 连接失败
│
├─ 检查日志: "does not match" checksum
│  └─ 计算正确 checksum: curl API | jq -r .value | sha256sum
│     └─ 替换 manifest + deployment env
│
├─ 检查日志: DNS 超时 / "Timed out waiting"
│  └─ Pod resolv.conf 有 "search local"？
│     └─ 创建 /etc/rancher/rke2/resolv.conf + config.yaml + 重启 RKE2
│
├─ agent 正常但 Rancher UI "Waiting for agent"
│  └─ credential secret namespace 为空？
│     └─ patch secret .data.namespace = base64(cluster-id)
│
├─ 修复后又被覆盖
│  └─ 部署 watchdog systemd timer（每 2 分钟）
│
└─ Pod 被驱逐 / DiskPressure
   └─ 磁盘扩容 + systemctl restart rke2-server

📁 本次修复涉及的所有文件

文件	位置	用途
`/etc/rancher/rke2/resolv.conf`	192.168.122.37	自定义 DNS（去除 `search local`）
`/etc/rancher/rke2/config.yaml`	192.168.122.37	指向自定义 resolv.conf
`.../manifests/rancher/cluster-agent.yaml`	192.168.122.37	agent deployment manifest
`/usr/local/bin/fix-cattle-agent-checksum.sh`	192.168.122.37	watchdog 修复脚本
`/etc/systemd/system/cattle-agent-watchdog.service`	192.168.122.37	systemd service 单元
`/etc/systemd/system/cattle-agent-watchdog.timer`	192.168.122.37	systemd timer 单元（每 2 分钟）

⚠️ 注意事项

节点重建会丢失自定义配置 — /etc/rancher/rke2/resolv.conf、config.yaml、watchdog 文件都需要备份或纳入 IaC
DNS 修复需 RKE2 重启 — config.yaml 中的 resolv-conf 只在 RKE2 启动时读取
CA 证书更换后需更新 checksum — 如果 Rancher 更换了 CA 证书，watchdog 脚本中的 checksum 值需要同步更新
Watchdog 脚本中的 secret 名称是硬编码的 — 如果 Rancher 生成了新的 credential secret，需要更新脚本中的 SECRET_NAME 列表
Rancher UI 可能需要刷新 — 如果后端已正常但 UI 仍显示 "Waiting"，尝试 Ctrl+F5 硬刷新或重启 Rancher pods

📋 Checklist（新节点加入时）

□ 磁盘 ≥ 30G（all-in-one 控制面节点）
□ /etc/rancher/rke2/resolv.conf 和 config.yaml 已配置
□ registries.yaml 使用命名 mirror（非 * 通配符）
□ hosts.toml 确认 HTTP 协议（非 HTTPS）
□ CA checksum 通过 jq -r | sha256sum 计算（非 Rancher UI 的值）
□ 修改 manifest 文件而非 kubectl set env
□ 部署 watchdog systemd timer
□ credential secret 的 namespace 字段已填充
□ serverca ConfigMap 存在且挂载到 agent pod
□ CATTLE_CA_CHECKSUM 保持为空（使用 serverca 文件验证）

---

## 十、问题 6：Rancher cacerts API 被清空（2026-08-17 复发）

### 10.1 现象

agent 修复后约 20 分钟再次 CrashLoopBackOff。新日志显示两个新错误：

unable to read CA file from /etc/kubernetes/ssl/certs/serverca: no such file or directory Strict CA verification is enabled but encountered error finding root CA


后续测试还发现：

ERROR: The environment variable CATTLE_CA_CHECKSUM is set but there is no CA certificate configured at https://gpu.ai-ear.cn/v3/settings/cacerts


### 10.2 根因链

Rancher 服务器 cacerts 设置被清空（value: "", 0 bytes） ↓ Rancher 重新生成 import YAML，CATTLE_CA_CHECKSUM 变为空字符串 "" ↓ Agent pod 启动后： ├─ 若 checksum 非空 → 从 /v3/settings/cacerts 下载 CA → 服务器返回空 → 报错退出 └─ 若 checksum 为空 → 尝试读取本地 /etc/kubernetes/ssl/certs/serverca → 文件不存在 → 报错退出 ↓ 无论哪种情况都崩溃


### 10.3 关键发现

1. **`STRICT_VERIFY=true`** 被设置在 deployment env 中，强制要求有效的 CA 验证
2. **Rancher 服务器 TLS 证书是自签名的** (`subject=CN=gpu.ai-ear.cn, issuer=CN=gpu.ai-ear.cn`)
3. **`stv-aggregation` secret** 中的 `ca.crt` 字段保存了完整的自签名 CA 证书（1091 bytes）
4. **kubeconfig 用户 token** (`/home/xxx/.kube/config`) 没有权限修改 Rancher 服务器的 settings

### 10.4 修复方案：ConfigMap + 空 Checksum

核心思路：**绕过 Rancher cacerts API，直接将 CA 证书挂载到 agent pod**。

```bash
# Step 1: 从 stv-aggregation 提取 CA 证书，创建 ConfigMap
kubectl get secret stv-aggregation -n cattle-system -o jsonpath='{.data.ca\.crt}' \
  | base64 -d > /tmp/ca.pem

kubectl create configmap rancher-server-ca -n cattle-system \
  --from-file=serverca=/tmp/ca.pem

# Step 2: 给 deployment 添加 volume 和 volumeMount
kubectl patch deployment cattle-cluster-agent -n cattle-system --type=json -p='[
  {"op":"add","path":"/spec/template/spec/volumes/-",
   "value":{"name":"serverca","configMap":{"name":"rancher-server-ca"}}},
  {"op":"add","path":"/spec/template/spec/containers/0/volumeMounts/-",
   "value":{"name":"serverca","mountPath":"/etc/kubernetes/ssl/certs","readOnly":true}}
]'

# Step 3: 确保 CATTLE_CA_CHECKSUM 为空
kubectl set env deployment/cattle-cluster-agent -n cattle-system CATTLE_CA_CHECKSUM=

为什么 checksum 必须为空？

CATTLE_CA_CHECKSUM 值	Agent 行为	结果
正确的 checksum 值	从 `/v3/settings/cacerts` 下载 CA → 服务器返回空 → 校验失败	❌ 崩溃
错误的 checksum 值	下载 CA → 校验不匹配	❌ 崩溃
空字符串 `""`	跳过下载，直接使用本地 `/etc/kubernetes/ssl/certs/serverca` 文件	✅ 正常运行

10.5 更新后的 Watchdog 脚本（v2）

v2 版本新增以下检查项：

bash

# 检查 deployment 的 CA checksum — 如果非空（无论正确还是错误），清空
DEPLOY_CS=$(kubectl get deployment ... | grep CATTLE_CA_CHECKSUM | cut -d= -f2)
if [ "$DEPLOY_CS" != "" ]; then
    kubectl set env deployment/cattle-cluster-agent -n cattle-system CATTLE_CA_CHECKSUM=
fi

# 检查 deployment 的 serverca volume — 如果缺失，通过 JSON patch 添加
if ! echo "$DEPLOY_VOLS" | grep -q "rancher-server-ca"; then
    kubectl patch deployment cattle-cluster-agent -n cattle-system --type=json -p='...'
fi

# 检查 ConfigMap 是否存在 — 如果被删除，从 stv-aggregation 重建
if ! kubectl get configmap rancher-server-ca -n cattle-system; then
    kubectl get secret stv-aggregation -n cattle-system -o jsonpath='{.data.ca\.crt}' \
      | base64 -d > /tmp/ca_watchdog.pem
    kubectl create configmap rancher-server-ca -n cattle-system \
      --from-file=serverca=/tmp/ca_watchdog.pem
fi

10.6 验证结果

cattle-cluster-agent-74c865d6fc-gn4k8   1/1   Running   0   2m20s
CATTLE_CA_CHECKSUM=                          ← 空值，正确
STRICT_VERIFY=true                           ← 保持严格验证
serverca ConfigMap 挂载到 /etc/kubernetes/ssl/certs/serverca  ← CA 文件存在
Watchdog 每 2 分钟检查，无干扰               ← 稳定

10.7 架构对比

修复前（崩溃循环）：
  Agent Pod
    ├── CATTLE_CA_CHECKSUM="6903fb1e..."
    ├── 下载 CA: GET /v3/settings/cacerts → 空
    └── 校验失败 → 退出

修复后（稳定运行）：
  Agent Pod
    ├── CATTLE_CA_CHECKSUM=""  (空)
    ├── serverca ConfigMap → /etc/kubernetes/ssl/certs/serverca (从 stv-aggregation 提取)
    ├── 本地验证: sha256(serverca) == 空检查 → 跳过远程下载
    └── STRICT_VERIFY 使用本地 serverca 验证 TLS → 成功

十一、根治排查：从管理集群 192.168.122.32 追溯根因 (2026-08-17)

11.1 为什么需要根治

前述修复（ConfigMap hack + watchdog）虽然能维持 agent 运行，但本质是绕过问题。根治要求找到 cacerts 被清空的根本原因。

11.2 连接管理集群

管理集群位于 192.168.122.32/33/34（3 节点 RKE2），SSH 不通。使用本地 kubeconfig：

bash

K=/home/xxx/docs/docs/ai-ear-website/worker/apps/jenkins/tools/kubectl
MC=/home/xxx/docs/docs/ai-ear-website/worker/apps/k8s-gpu/scripts/kubeconfig-rke2.yaml

11.3 根因 #7：Rancher `--no-cacerts` 启动参数

bash

$K --kubeconfig=$MC get deployment rancher -n cattle-system \
  -o jsonpath='{.spec.template.spec.containers[0].args}'
# → ["--no-cacerts", "--http-listen-port=80", "--https-listen-port=443", "--add-local=true"]

--no-cacerts 参数告诉 Rancher 不生成也不管理自签名 CA 证书 → settings.management.cattle.io/cacerts 永远为空。

11.4 根因 #8：Helm values `ingress.tls.source: "secret"`

json

{
  "hostname": "gpu.ai-ear.cn",
  "ingress": { "tls": { "source": "secret" } },
  "rancherImageTag": "v2.14.3",
  "replicas": 1
}

11.5 完整根因链

Helm values: ingress.tls.source = "secret" (用户提供 TLS)
  → Helm chart 生成 deployment 时加 --no-cacerts 参数
    → Rancher 启动不生成/管理 CA
      → settings.management.cattle.io/cacerts 永远为空
        → Agent 无法通过 /v3/settings/cacerts API 获取 CA
          → CATTLE_CA_CHECKSUM 不匹配 → CrashLoopBackOff

11.6 尝试修复：设置 cacerts 为 ingress 证书

将 tls-rancher-ingress PEM 设为 cacerts 后，发现 Rancher v2.14.3 checksum 计算 bug：

服务器: sha256(cacerts_value)        = cd9078b7...
Agent:  sha256(downloaded_content+\n) = 6903fb1e...
→ checksum 永远不匹配!

再修正 checksum 后，agent 尝试写入本地文件但 ConfigMap 挂载是只读的：

mv: inter-device move failed: Read-only file system

11.7 最终根治方案

在 --no-cacerts 配置下，最稳定的方案：

层面	配置
管理集群	`cacerts` 保持空（agent 不尝试下载和写入）
下游 ConfigMap	`rancher-server-ca` 提供本地 serverca 文件
`CATTLE_CA_CHECKSUM`	保持空（agent 直接用本地文件验证）
RKE2 addon	自动维护此状态（删除 addon 可强制重建）

11.8 验证结果

cattle-cluster-agent-b864f9497-xxbbr  1/1  Running  0  75s
CATTLE_CA_CHECKSUM= (空)
STRICT_VERIFY=true
serverca: 1091 bytes, sha256=6903fb1e...
管理集群: AgentDeployed=True, Connected=True, AgentTlsStrictCheck=True

11.9 长期建议

推荐在维护窗口执行 Helm 升级，将 ingress.tls.source 改为 rancher：

bash

helm upgrade rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=gpu.ai-ear.cn \
  --set ingress.tls.source=rancher \
  --set rancherImage=192.168.122.156:30000/rancher/rancher \
  --set systemDefaultRegistry=192.168.122.156:30000

11.10 管理集群连接信息

参数	值
kubeconfig	`.../scripts/kubeconfig-rke2.yaml`
API server	`https://192.168.122.32:6443`
节点	szb122032 / szb122033 / szb122034
K8s 版本	v1.35.6+rke2r1
Rancher 版本	v2.14.3

十四、问题 7：system-agent-upgrader Plan 持续 Error (2026-08-17)

14.1 现象

cattle-system 命名空间中出现大量 apply-system-agent-upgrader-on-szb122037-with-* Error pods：

apply-system-agent-upgrader-on-szb122037-with-28d15204c5d-vxwrq   0/1  Error  0  18m
apply-system-agent-upgrader-on-szb122037-with-1b2feddbb93-dcx54   0/1  Error  0  6m48s
...（13 个 Error pods）

14.2 错误日志

bash

+ chroot /host /var/lib/rancher/agent/tmp/tmp.WbE4twEqiu/install.sh
[INFO]  CA strict verification is set to true
[INFO]  Using default agent configuration directory /etc/rancher/agent
[FATAL]  Aborting system-agent installation due to requested strict CA verification
        with no CA checksum provided

14.3 根因

Plan CRD（由 system-upgrade-controller 管理）中环境变量配置：

yaml

spec:
  upgrade:
    envs:
    - name: STRICT_VERIFY
      value: "true"       # ← 要求 CA checksum
    # 缺少 CATTLE_CA_CHECKSUM 环境变量

与 cattle-cluster-agent 相同的问题：STRICT_VERIFY=true 要求提供 CATTLE_CA_CHECKSUM，但服务器 cacerts 为空。

14.4 修复

bash

# 1. 修改 Plan：将 STRICT_VERIFY 改为 false
kubectl patch plan system-agent-upgrader -n cattle-system --type=json -p='[
  {"op": "replace", "path": "/spec/upgrade/envs/0/value", "value": "false"}
]'

# 2. 同样修复 Windows Plan
kubectl patch plan system-agent-upgrader-windows -n cattle-system --type=json -p='[
  {"op": "add", "path": "/spec/upgrade/envs/-",
   "value": {"name": "STRICT_VERIFY", "value": "false"}}
]'

# 3. 清理失败的 pods
kubectl delete pods -n cattle-system --field-selector=status.phase=Failed

14.5 验证

修复后新 pod 成功完成：

apply-system-agent-upgrader-on-szb122037-with-9dfec85d901-zrxrl  0/1  Completed  0  38s

日志确认安装成功：

[INFO]  Successfully downloaded and validated Rancher connection information
[INFO]  systemd: Creating service file
[INFO]  Enabling rancher-system-agent.service
[INFO]  Starting/restarting rancher-system-agent.service

注意：rancher-system-agent systemd 服务本身已在 2 小时前正常运行（active (running)），upgrader 只是重复尝试安装/升级被阻止。修复 Plan 后不再产生 Error pods。

十五、问题 8：新节点 system-agent 安装失败 (2026-08-17)

15.1 现象

在新节点 192.168.122.9 (szb122009) 上执行 Rancher 安装命令时失败：

bash

sudo curl --insecure -fL https://gpu.ai-ear.cn/system-agent-install.sh | \
  sudo sh -s - --server https://gpu.ai-ear.cn \
  --label 'cattle.io/os=linux' \
  --token czs7h849lgzxcjrnkj54d2294ms2plb8xw5g2f5jn9l8h665hpw5sm \
  --worker

输出：

[INFO]  Label: cattle.io/os=linux
[INFO]  Role requested: worker
[INFO]  CA strict verification is set to true
[INFO]  Using default agent configuration directory /etc/rancher/agent
[INFO]  Using default agent var directory /var/lib/rancher/agent
[FATAL]  Aborting system-agent installation due to requested strict CA verification
        with no CA checksum provided

15.2 根因

安装脚本检测到 STRICT_VERIFY=true（从服务器端继承），但无法获取 CA checksum（cacerts 为空）。

15.3 修复

方案 1：获取 CA checksum 并传入（推荐）

bash

# 先获取 TLS 证书的 SHA256 指纹
echo | openssl s_client -connect gpu.ai-ear.cn:443 -servername gpu.ai-ear.cn 2>/dev/null \
  | openssl x509 -outform PEM | sha256sum
# cd9078b7f2b7e605ab8d6fd8629d8de8dda9efbd5fd6fa5455f634c769bec19a  -

# 安装命令加上 --ca-checksum
sudo curl --insecure -fL https://gpu.ai-ear.cn/system-agent-install.sh | \
  sudo sh -s - --server https://gpu.ai-ear.cn \
  --label 'cattle.io/os=linux' \
  --token czs7h849lgzxcjrnkj54d2294ms2plb8xw5g2f5jn9l8h665hpw5sm \
  --ca-checksum cd9078b7f2b7e605ab8d6fd8629d8de8dda9efbd5fd6fa5455f634c769bec19a \
  --worker

方案 2：禁用严格验证（推荐，因 `--no-cacerts` 模式无法使用 checksum）

⚠️ 必须在目标节点上执行，不能在管理集群节点上执行。

最可靠方式：下载脚本 → 硬编码修改 STRICT_VERIFY + 所有 curl 加 --insecure → 安装 → 追加 CA 到系统信任链 → 修复 systemd 服务

bash

# 1. 在目标节点上下载脚本
curl --insecure -fL https://gpu.ai-ear.cn/system-agent-install.sh -o /tmp/agent-install.sh

# 2. 修改 STRICT_VERIFY 默认值
sed -i "s/export STRICT_VERIFY='true'/export STRICT_VERIFY='false'/" /tmp/agent-install.sh

# 3. 所有 curl 调用替换 ${CURL_CAFLAG} 为 --insecure（因 cacerts 为空）
sed -i 's/\${CURL_CAFLAG}/--insecure/g' /tmp/agent-install.sh

# 4. 验证修改
head -2 /tmp/agent-install.sh  # 应显示 STRICT_VERIFY='false'

# 5. 安装
sudo sh /tmp/agent-install.sh \
  --server https://gpu.ai-ear.cn \
  --label 'cattle.io/os=linux' \
  --token &lt;YOUR_TOKEN&gt; \
  --worker \
  --address &lt;NODE_IP&gt; \
  --internal-address &lt;NODE_IP&gt; \
  --node-name &lt;NODE_NAME&gt;

# 6. 安装后修复：追加 CA 证书到系统信任链（解决 Go 程序 TLS 校验失败）
echo | openssl s_client -connect gpu.ai-ear.cn:443 -servername gpu.ai-ear.cn 2>/dev/null \
  | openssl x509 | sudo tee /usr/local/share/ca-certificates/gpu-ai-ear-cn.crt
sudo bash -c 'cat /usr/local/share/ca-certificates/gpu-ai-ear-cn.crt >> /etc/ssl/certs/ca-certificates.crt'

# 7. 修复 systemd 服务文件（安装脚本会覆盖回 STRICT_VERIFY=true）
sudo sed -i 's/CATTLE_AGENT_STRICT_VERIFY=true/CATTLE_AGENT_STRICT_VERIFY=false/' \
  /etc/systemd/system/rancher-system-agent.service
sudo bash -c 'echo "Environment=SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt" \
  >> /etc/systemd/system/rancher-system-agent.service'
sudo systemctl daemon-reload
sudo systemctl restart rancher-system-agent

关键踩坑点：
STRICT_VERIFY='true' 是安装脚本第 2 行硬编码的 export，sudo env 无法覆盖
安装脚本中 CURL_CAFLAG 指向 /cacerts 端点（--no-cacerts 模式下为空），导致 curl --cacert 参数无效
安装脚本会覆盖已有的 systemd service 文件，把 STRICT_VERIFY 改回 true
Go 程序（rancher-system-agent）使用 SSL_CERT_FILE 环境变量定位 CA 包，需要显式设置

安全提示：方案 1 更安全，仍验证 TLS 证书指纹。方案 2 完全跳过 CA 验证。

十六、Watchdog v5 最终版 (2026-08-17)

16.1 监控项

Watchdog v5 监控流程:
├── 1. ConfigMap rancher-server-ca 存在性 → 缺失则从 stv-aggregation 重建
├── 2. Deployment CATTLE_CA_CHECKSUM 为空 → 非空则清空
├── 3. Credential secret namespace 正确 → 空则修补
├── 4. Plan STRICT_VERIFY = false → true 则 patch 为 false
├── 5. 清理 Failed pods
└── 6. CrashLoopBackOff → 删除 addon 强制重建 + 重新 import

16.2 脚本位置

/usr/local/bin/fix-cattle-agent-checksum.sh  (192.168.122.37 节点上)

通过 cron 每 2 分钟执行一次：

bash

*/2 * * * * /usr/local/bin/fix-cattle-agent-checksum.sh >> /var/log/cattle-agent-watchdog.log 2>&1

十七、全局根因总结

17.1 因果链全景图

Helm install rancher (管理集群 192.168.122.32)
│
├── ingress.tls.source = "secret"  (用户自提供 TLS 证书)
│     └── 自动添加 --no-cacerts 启动参数
│           └── Rancher 不生成/管理 CA
│                 └── cacerts setting 永远为空
│                       │
│                       ├── 下游集群 cattle-cluster-agent:
│                       │     ├── CATTLE_CA_CHECKSUM 非空 → 下载 cacerts → 空 → CRASH
│                       │     ├── CATTLE_CA_CHECKSUM 空 + serverca 不存在 → CRASH
│                       │     └── CATTLE_CA_CHECKSUM 空 + ConfigMap serverca → ✅
│                       │
│                       ├── system-agent-upgrader Plan:
│                       │     ├── STRICT_VERIFY=true + 无 checksum → FATAL
│                       │     └── STRICT_VERIFY=false → ✅
│                       │
│                       └── 新节点安装 system-agent:
│                             ├── 默认 STRICT_VERIFY=true + 无 checksum → FATAL
│                             ├── --ca-checksum &lt;sha256&gt; → ✅
│                             └── STRICT_VERIFY=false → ✅
│
└── 双重覆盖机制 (Rancher controller + RKE2 addon controller)
      └── kubectl 手动修改 manifest → 被回滚
            └── 必须从 import YAML 或管理集群层面修复

17.2 问题清单 (共 9 个)

#	问题	修复状态
1	DiskPressure 磁盘 10G 不足	✅ 扩容到 99G
2	DNS `search local` 导致超时	✅ resolv.conf 覆盖
3	CA checksum 不匹配 (`jq -r` 尾随 `\n`)	✅ 正确计算 checksum
4	Rancher 回滚 manifest 修改	✅ 重新 import + watchdog
5	credential secret namespace 缺失	✅ watchdog 自动 patch
6	cacerts API 被清空	✅ ConfigMap serverca + 空 checksum
7	system-agent-upgrader Plan Error	✅ Plan STRICT_VERIFY=false
8	新节点 system-agent 安装失败	✅ `--ca-checksum` 参数
9	Rancher `--no-cacerts` 根因	✅ 保持 cacerts 空 + ConfigMap 方案

17.3 长期根治方案

方案	描述	推荐度
当前方案	`--no-cacerts` + ConfigMap + watchdog	⭐⭐⭐ 稳定但需维护
Helm 升级	`ingress.tls.source=rancher`	⭐⭐⭐⭐⭐ 让 Rancher 自管理 CA
外部 CA	使用正式 CA 签发证书	⭐⭐⭐⭐ 最干净但需外部 CA

bash

# 推荐：维护窗口执行 Helm 升级
helm upgrade rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=gpu.ai-ear.cn \
  --set ingress.tls.source=rancher \
  --set rancherImage=192.168.122.156:30000/rancher/rancher \
  --set systemDefaultRegistry=192.168.122.156:30000

cattle-cluster-agent 彻底修复 + 磁盘扩容 + CA-Checksum 根因分析 ​

一、问题总览 ​

二、问题 1：DiskPressure 磁盘扩容（10G → 30G → 99G） ​

2.1 背景 ​

2.2 扩容步骤（在线，无需停机） ​

2.3 验证 ​

三、问题 2：DNS search local 导致 CoreDNS 超时 ​

3.1 症状 ​

3.2 排查思路 ​

3.3 修复 ​

四、问题 3：CA Checksum 根因分析（核心陷阱） ​

4.1 症状 ​

4.2 排查思路 ​

4.3 根因：jq -r 的尾随换行符 ​

4.4 正确的 checksum 计算方法 ​

4.5 为什么无法从 Rancher 服务端修复 ​

五、问题 4：Rancher 管理面反复覆盖 manifest ​

5.1 症状 ​

5.2 排查思路 ​

5.3 根因 ​

5.4 解决方案 ​

六、问题 5：Credential Secret 缺少 Namespace ​

6.1 症状 ​

6.2 排查思路 ​

6.3 根因 ​

6.4 修复 ​

七、完整修复步骤（一键执行） ​

7.1 前提条件 ​

7.2 Step 1: DNS 修复 ​

7.3 Step 2: 计算正确的 CA Checksum ​

7.4 Step 3: 替换 Manifest + 修复 Namespace ​

7.5 Step 4: 修复 Credential Secrets ​

7.6 Step 5: 重启 Agent + 部署 Watchdog ​

八、Watchdog 守护脚本（核心持久方案） ​

8.1 设计思路 ​

8.2 脚本文件 ​

8.3 安装命令 ​

8.4 日志查看 ​

九、验证清单 ​

9.1 完整验证命令 ​

9.2 期望输出 ​

十二、最终集群状态（2026-08-17 13:00 UTC） ​

十三、经验总结 ​

🔑 五大关键知识点 ​

📝 排查决策树 ​

📁 本次修复涉及的所有文件 ​

⚠️ 注意事项 ​

📋 Checklist（新节点加入时） ​

10.5 更新后的 Watchdog 脚本（v2） ​

10.6 验证结果 ​

10.7 架构对比 ​

十一、根治排查：从管理集群 192.168.122.32 追溯根因 (2026-08-17) ​

11.1 为什么需要根治 ​

11.2 连接管理集群 ​

11.3 根因 #7：Rancher --no-cacerts 启动参数 ​

11.4 根因 #8：Helm values ingress.tls.source: "secret" ​

11.5 完整根因链 ​

11.6 尝试修复：设置 cacerts 为 ingress 证书 ​

11.7 最终根治方案 ​

11.8 验证结果 ​

11.9 长期建议 ​

11.10 管理集群连接信息 ​

十四、问题 7：system-agent-upgrader Plan 持续 Error (2026-08-17) ​

14.1 现象 ​

14.2 错误日志 ​

14.3 根因 ​

14.4 修复 ​

14.5 验证 ​

十五、问题 8：新节点 system-agent 安装失败 (2026-08-17) ​

15.1 现象 ​

15.2 根因 ​

15.3 修复 ​

方案 1：获取 CA checksum 并传入（推荐） ​

方案 2：禁用严格验证（推荐，因 --no-cacerts 模式无法使用 checksum） ​

十六、Watchdog v5 最终版 (2026-08-17) ​

16.1 监控项 ​

16.2 脚本位置 ​

十七、全局根因总结 ​

17.1 因果链全景图 ​

17.2 问题清单 (共 9 个) ​

cattle-cluster-agent 彻底修复 + 磁盘扩容 + CA-Checksum 根因分析

一、问题总览

二、问题 1：DiskPressure 磁盘扩容（10G → 30G → 99G）

2.1 背景

2.2 扩容步骤（在线，无需停机）

2.3 验证

三、问题 2：DNS `search local` 导致 CoreDNS 超时

3.1 症状

3.2 排查思路

3.3 修复

四、问题 3：CA Checksum 根因分析（核心陷阱）

4.1 症状

4.2 排查思路

4.3 根因：`jq -r` 的尾随换行符

4.4 正确的 checksum 计算方法

4.5 为什么无法从 Rancher 服务端修复

五、问题 4：Rancher 管理面反复覆盖 manifest

5.1 症状

5.2 排查思路

5.3 根因

5.4 解决方案

六、问题 5：Credential Secret 缺少 Namespace

6.1 症状

6.2 排查思路

6.3 根因

6.4 修复

七、完整修复步骤（一键执行）

7.1 前提条件

7.2 Step 1: DNS 修复

7.3 Step 2: 计算正确的 CA Checksum

7.4 Step 3: 替换 Manifest + 修复 Namespace

7.5 Step 4: 修复 Credential Secrets

7.6 Step 5: 重启 Agent + 部署 Watchdog

八、Watchdog 守护脚本（核心持久方案）

8.1 设计思路

8.2 脚本文件

8.3 安装命令

8.4 日志查看

九、验证清单

9.1 完整验证命令

9.2 期望输出

十二、最终集群状态（2026-08-17 13:00 UTC）

十三、经验总结

🔑 五大关键知识点

📝 排查决策树

📁 本次修复涉及的所有文件

⚠️ 注意事项

📋 Checklist（新节点加入时）

10.5 更新后的 Watchdog 脚本（v2）

10.6 验证结果

10.7 架构对比

十一、根治排查：从管理集群 192.168.122.32 追溯根因 (2026-08-17)

11.1 为什么需要根治

11.2 连接管理集群

11.3 根因 #7：Rancher `--no-cacerts` 启动参数

11.4 根因 #8：Helm values `ingress.tls.source: "secret"`

11.5 完整根因链

11.6 尝试修复：设置 cacerts 为 ingress 证书

11.7 最终根治方案

11.8 验证结果

11.9 长期建议

11.10 管理集群连接信息

十四、问题 7：system-agent-upgrader Plan 持续 Error (2026-08-17)

14.1 现象

14.2 错误日志

14.3 根因

14.4 修复

14.5 验证

十五、问题 8：新节点 system-agent 安装失败 (2026-08-17)

15.1 现象

15.2 根因

15.3 修复

方案 1：获取 CA checksum 并传入（推荐）

方案 2：禁用严格验证（推荐，因 `--no-cacerts` 模式无法使用 checksum）

十六、Watchdog v5 最终版 (2026-08-17)

16.1 监控项

16.2 脚本位置

十七、全局根因总结

17.1 因果链全景图

17.2 问题清单 (共 9 个)