KnoAI 技术站

主题

K8sGPT 飞书告警卡片排障与定制手册 ​

  • 日期：2026-08-03
  • 集群：uat1（RKE2 v1.35.6，Rancher 下游集群，192.168.122.31 等 5 节点）
  • 组件：K8sGPT v0.4.9（operator + server，AI 后端：阿里云百炼 qwen-plus，OpenAI 兼容接口）+ 自研 k8sgpt-feishu-adapter（ConfigMap 内嵌 Python）
  • 告警链路：
K8sGPT operator ──gRPC Analyze──> K8sGPT server ──AI 解释──> 阿里云百炼(qwen-plus)
      │ 生成 Result CR(spec.error + spec.details)
      │ cloudevents sink(每 10 分钟巡检)
      ▼
k8sgpt-feishu-adapter ──POST 卡片──> 飞书群机器人

1. 背景 ​

uat1 集群通过 K8sGPT 每 10 分钟巡检集群异常，经 feishu-adapter 推送飞书卡片。出现两个问题：

  1. 卡片信息不全：只有告警标题，没有「原因」和「解决建议」;
  2. 重复误报:Service cattle-monitoring-system/rancher-monitoring-windows-exporter 每 10 分钟刷一次。

2. 故障一：卡片没有原因和解决建议 ​

2.1 排查链（自底向上） ​

检查项结果
飞书卡片 → adapter 日志sink 载荷 attachments:[{text:""}] 报告体为空
adapter → K8sGPT Result CRspec.details: "" AI 诊断详情为空
Result → AI 后端连通性节点/Pod → dashscope 均正常，API Key 实测可用
k8sgpt server 日志历史日志有大量 failed while calling AI provider openai: lookup dashscope.aliyuncs.com ... server misbehaving（集群 DNS 瘫痪期间）；近期 Analyze 请求"completed"但参数中没有 explain:true
operator 行为K8sGPT CR 配置了 backOff: {enabled: true, maxRetries: 3};AI 连续失败触发熔断后，operator 不再请求 AI 解释，且状态驻留内存不自动恢复

2.2 根因链 ​

8月1日集群 CoreDNS 故障（见《uat1 集群 Rancher Monitoring 部署与故障排查手册》）
  → AI 调用连续失败 ≥3 次 → operator backOff 熔断（内存状态）
  → 后续 Analyze 请求不再带 explain:true
  → Result.details 永远为空
  → operator 判定 "Result unchanged (historical)" 不再重新分析
  → sink 载荷报告体为空 → 飞书卡片只有标题没有内容

2.3 修复（两步缺一不可） ​

bash
# ① 重启 operator，重置内存中的熔断状态
kubectl rollout restart deployment -n k8sgpt k8sgpt-k8sgpt-operator-controller-manager

# ② 删除存量 Result，强制下一轮巡检重新分析（否则空 details 永久卡死）
kubectl delete results.core.k8sgpt.ai -n k8sgpt --all

注意：只重启 k8sgpt server pod 无效——explain 参数由 operator 在 gRPC 请求中决定，熔断状态也在 operator 内存中。

2.4 验证 ​

下一轮巡检（≤10 分钟）后：

bash
kubectl get results.core.k8sgpt.ai -n k8sgpt -o json | python3 -c "..."
# details长度 > 0，含 Error:/Solution: 中文诊断

adapter 日志可见载荷从 424B（空报告）变为 800B+（含完整 Error/Solution），飞书卡片恢复「❌ 问题 + 🛠 修复建议」。

3. 故障二：windows-exporter Service 周期性误报 ​

3.1 根因 ​

rancher-monitoring chart 默认启用 windows-exporter（Windows 节点监控组件），其 DaemonSet 带 kubernetes.io/os=windows 节点选择器。集群没有 Windows 节点 → 永远 0 Pod → Service 永远无 endpoints → K8sGPT 每 10 分钟误报一次，且通用大模型对此场景容易给出不准确诊断。

3.2 修复（无 Windows 节点时直接禁用组件） ​

bash
helm upgrade rancher-monitoring rancher-monitoring-109.0.4+up80.9.1-rancher.18.tgz \
  -n cattle-monitoring-system --reuse-values \
  --set windowsExporter.enabled=false --wait --timeout 10m

验证：DaemonSet/Service 全部清除，operator 自动清理对应 Result，误报根除，其余监控组件不受影响。

4. 卡片定制：资源标识改到标题栏 ​

4.1 修改内容 ​

adapter 的 build_card()（ConfigMap k8sgpt/k8sgpt-feishu-adapter 内嵌 adapter.py）：

python
def build_card(kind: str, name: str, report: str) -> dict:
    elements = []
    elements.append({"tag": "div", "text": lark(md_report(report))})
    elements.append({"tag": "note", "elements": [
        {"tag": "plain_text", "content": "K8sGPT AI 诊断 · 每 10 分钟巡检 · 数据脱敏后分析"}]})
    # 标题栏动态显示资源标识；解析失败回退原标题
    title = f"🔍 K8sGPT 异常: {kind} {name}".strip() if (kind or name) else "🔍 K8sGPT 发现集群异常"
    return {"msg_type": "interactive", "card": {
        "config": {"wide_screen_mode": True},
        "header": {"template": "red",
                   "title": {"tag": "plain_text", "content": title}},
        "elements": elements}}
改前改后
标题固定 🔍 K8sGPT 发现集群异常，资源信息在正文小字段标题 🔍 K8sGPT 异常: Pod mysql/mysql-primary-0，正文去掉重复字段块

4.2 发布流程（ConfigMap 内嵌代码的标准更新方式） ​

bash
# ① 取出现行代码 → 本地修改 → 语法校验
kubectl get cm -n k8sgpt k8sgpt-feishu-adapter -o "jsonpath={.data.adapter\.py}" > adapter.py
python3 -m py_compile adapter.py

# ② 回写 ConfigMap 并滚动重启（挂载的 py 不会被进程热加载）
kubectl create configmap k8sgpt-feishu-adapter -n k8sgpt \
  --from-file=adapter.py=adapter.py --dry-run=client -o yaml | kubectl apply -f -
kubectl rollout restart deployment -n k8sgpt k8sgpt-feishu-adapter

4.3 验证 ​

向 adapter 发送模拟 K8sGPT cloudevents 载荷，飞书返回 success，卡片标题显示为 🔍 K8sGPT 异常: Pod mysql/mysql-primary-0。

5. 经验总结 ​

  1. 熔断状态要纳入排障视野:K8sGPT operator 的 backOff 熔断是内存态，AI 后端恢复后不会自愈，必须重启 operator；仅重启 server pod 无效。
  2. "Result unchanged (historical)" 是更新陷阱：存量 Result 内容不变时 operator 不重新分析，修复上游后需删 Result 强制重建。
  3. 排障自底向上逐段验证：卡片 → sink 载荷 → Result CR → AI 调用，每一段都有独立的验证方法（adapter 日志 / CR spec / 日志中的请求参数）。
  4. 无 Windows 节点的集群应禁用 windows-exporter:--set windowsExporter.enabled=false，根除 endpoints 类误报。
  5. ConfigMap 内嵌脚本类服务：改代码 = 改 ConfigMap + 滚动重启，不要忘语法校验。