K8sGPT 集群 AI 故障分析部署文档

环境：RKE2 v1.35.6（6 节点）｜内部 Harbor 192.168.122.156:30000｜AI 后端：阿里百炼 DashScope（qwen-plus）组件：k8sgpt-operator 0.2.27 + k8sgpt 分析服务器 v0.4.9 更新：2026-08-01

1. 架构与原理

k8sgpt-operator ──监听 K8sGPT CR──► 拉起 k8sgpt 分析服务器（同命名空间）
       │                                    │
       │ 每 10m 触发                        │ 逐项 Analyzer 扫描集群
       └─────────── gRPC ──────────────────►│ 发现问题 → AI 解释 → Result CR
                                            │ 新结果 → sink(cloudevents)
                                            ▼              │
                              DashScope OpenAI 兼容 API     ▼
                              （发送前 anonymize 打码）  feishu-adapter → 飞书群机器人

分析器覆盖：Pod/Service/Deployment/StatefulSet/Node/Ingress/PVC/CronJob/HPA/NetworkPolicy 等 20+ 类
结果以 results.core.k8sgpt.ai CR 存储，命名规则：<namespace><kind><name> 去后缀
只报告异常项，健康集群 Result 数量少属正常

2. 镜像与 Chart（全部来自内部 Harbor）

内容	内部地址	来源
operator 镜像	`k8sgpt/k8sgpt-operator:v0.2.27`	ghcr.io/k8sgpt-ai（经 ghcr.nju.edu.cn 镜像站）
分析服务器镜像	`k8sgpt/k8sgpt:v0.4.9`	同上
rbac-proxy 镜像	`k8sgpt/kube-rbac-proxy:v0.19.1`	quay.io/brancz（经 quay.m.daocloud.io）
operator chart	`oci://…/charts/k8sgpt-operator:0.2.27`	charts.k8sgpt.ai（可直连）

3. 前置准备

bash

# 1. Harbor 建公开项目
curl -u 'admin:xxx' -X POST 'http://192.168.122.156:30000/api/v2.0/projects' \
  -H 'Content-Type: application/json' -d '{"project_name":"k8sgpt","public":true}'

# 2. 同步镜像/chart（skopeo 多镜像源自动回退：ghcr 直连 → nju → dockerproxy → daocloud）
export HARBOR_USER=admin HARBOR_PASS='xxx'
./deploy.sh sync

# 3. 准备 AI 后端密钥（DashScope 控制台 https://bailian.console.aliyun.com/ 申请 API-KEY）
#    写入 .secrets.env: DASHSCOPE_API_KEY / OPENAI_BASE_URL / 模型名

K8sGPT 为纯无状态组件，不需要 NFS/PV；结果存于 etcd（Result CR）。集群需能访问 dashscope.aliyuncs.com:443（已实测 Pod 出网正常）。

4. 一键部署

交付目录 k8sgpt/：

k8sgpt/
├── deploy.sh            # 一键部署（all|sync|check）
├── k8sgpt-values.yaml   # operator 参数（内部镜像、ServiceMonitor、动态 RBAC）
├── k8sgpt-cr.yaml       # K8sGPT 分析实例 + 后端 Secret（最佳实践配置，含 sink）
├── feishu-adapter.yaml  # 飞书通知适配器（ConfigMap 脚本 + Secret + Deployment + Service）
├── .secrets.env         # DashScope API Key + 飞书 webhook（勿提交公共仓库）
└── README.md / 部署文档.md / 操作文档.md

bash

export KUBECONFIG=~/.kube/config-122.31
cd k8sgpt/
./deploy.sh

手动分步（等价命令）

bash

kubectl create ns k8sgpt

helm install k8sgpt oci://192.168.122.156:30000/charts/k8sgpt-operator \
  --version 0.2.27 --plain-http -n k8sgpt -f k8sgpt-values.yaml

kubectl apply -f feishu-adapter.yaml -f k8sgpt-cr.yaml

飞书通知链路

K8sGPT sink 原生仅支持 slack / mattermost / cloudevents（无飞书），而飞书自定义机器人要求 msg_type 消息格式，因此部署了轻量适配器（python stdlib 单文件）。通知以飞书互动卡片呈现：红色标题栏 + 资源类型/名称分栏 + ❌问题/🛠修复建议 markdown 排版 + 底部注释：

K8sGPT CR sink(cloudevents) → k8sgpt-feishu-adapter Service:8080 → 飞书 webhook

📖 适配器的报文格式、处理流水线、中文兜底翻译、日志与最佳实践详见飞书适配器详解。

webhook 地址存于 Secret k8sgpt-feishu，更换群机器人只需改 Secret：

bash

kubectl -n k8sgpt edit secret k8sgpt-feishu   # 更新 webhook-url（base64）
kubectl -n k8sgpt rollout restart deploy/k8sgpt-feishu-adapter

5. 部署后验证

bash

# operator 与分析服务器均 Running；分析服务器镜像为内部 Harbor 固定版本
kubectl -n k8sgpt get pods -o wide
kubectl -n k8sgpt get deploy k8sgpt -o jsonpath='{.spec.template.spec.containers[0].image}'

# K8sGPT 实例状态
kubectl -n k8sgpt get k8sgpt

# 分析结果（首轮全量分析约 5~10 分钟，只报异常项）
kubectl get results.core.k8sgpt.ai -A

# 看某条结果的 AI 解决方案
kubectl -n k8sgpt get result <NAME> -o jsonpath='{.spec.details}'

6. 最佳实践配置说明（k8sgpt-cr.yaml）

yaml

spec:
  repository: 192.168.122.156:30000/k8sgpt/k8sgpt   # 分析服务器镜像走内部 Harbor
  version: v0.4.9                                   # 固定版本，不用 latest
  ai:
    backend: openai          # OpenAI 兼容协议
    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen-plus
    anonymized: true         # 公有云 API：资源名打码后送出
    language: chinese
    maxTokens: "2000"
    backOff: { enabled: true, maxRetries: 3 }
  analysis:
    interval: 10m            # 注意必须是 "10m" 这种 Go duration 格式

决策	说明
后端选 DashScope qwen-plus	国内可达、按 token 计费、qwen 对 K8s 中文术语理解好；可平滑切换内网 vLLM（改 baseUrl/model/key 即可，内网后可关 anonymize 提升准确率）
`anonymized: true`	资源名 base64 打码后送出，防敏感信息出域；代价是 AI 对打码名可能误读（如把打码当故障特征），换内网后端后建议关闭
`autoRemediation` 保持关闭	生产环境不接受 AI 直接变更集群
`interval: 10m`	过快浪费 API 费用，过慢失去时效；按集群规模调整
不开 trivy 集成	避免引入镜像扫描组件；需要漏洞分析时再开（需同步 trivy 镜像）
ServiceMonitor 开启	operator 指标接入 rancher-monitoring

7. 踩坑记录

operator 会再拉一个分析服务器镜像：ghcr.io/k8sgpt-ai/k8sgpt:latest（默认），必须在 CR 里用 spec.repository/version 改为内部 Harbor 固定版本，否则依赖 ghcr 直连。
analysis.interval 必须是字符串且匹配 ^[0-9]+[smh]$：600 和 "600" 都会被 CRD 拒绝，用 "10m"。
chart 镜像在 ghcr/quay 双仓：国内同步时分别走对应镜像站（deploy.sh sync 已内置回退）。
anonymize 的副作用：打码后的名字会让 AI 误判（把 base64 当故障原因），解读结果时注意甄别。
飞书需适配器中转：sink 枚举只有 slack/mattermost/cloudevents；飞书要求 msg_type 格式，直连会返回 19002 params error, msg_type need（已实测）。
cloudevents sink 真实载荷是 slack 风格，不是 Result CR（重大踩坑）：operator v0.2.x 的 sink 实际发送 data = {text: "...analysis of the Kind ns/name...", attachments: [{text: <AI报告>, ...}]}，而非 Result CR 结构。按 Result CR 解析会字段全空，导致飞书消息只有标题没有内容（已实测踩坑）。适配器 extract() 已兼容两种载荷：优先识别 {text, attachments}，兜底按 Result CR（data.spec）解析；解析异常时直接把原始报文截断转发，保证消息永不为空。适配器已开 stdout 日志（收包摘要 + 飞书响应），kubectl -n k8sgpt logs deploy/k8sgpt-feishu-adapter 可直接排查。
AI 报告语言：language 值必须写 "简体中文"，不能写 "chinese"（重大踩坑）：该值会被原样插入提示词 written in --- <值> --- language，实测 qwen-plus 遇到 chinese 仍输出英文（输出格式模板本身是英文，权重更高）；改成 简体中文 后基本稳定中文输出。缓存 key 含语言值，改后新分析会重新调 AI。
个别报告仍可能英文（anonymize 打码内容干扰模型）：适配器内置兜底翻译——报告主体无中文字符时，复用 k8sgpt-backend Secret 的 Key 调 AI 翻译成中文再推送（翻译失败静默降级为原文，不影响通知可达性）。日志出现 translated report to Chinese 即兜底生效。
健康集群 Result 很少：不是问题，说明集群没毛病。

8. 费用估算

每次异常项分析约 1~2K tokens（prompt+completion），qwen-plus 约 ¥0.0008/千 tokens。集群 10 个异常项、10 分钟一轮：≈ ¥0.02/轮，¥3/天以内。异常少时费用可忽略。

K8sGPT 集群 AI 故障分析部署文档 ​

1. 架构与原理 ​

2. 镜像与 Chart（全部来自内部 Harbor） ​

3. 前置准备 ​

4. 一键部署 ​

手动分步（等价命令） ​

飞书通知链路 ​

5. 部署后验证 ​

6. 最佳实践配置说明（k8sgpt-cr.yaml） ​

7. 踩坑记录 ​

8. 费用估算 ​

K8sGPT 集群 AI 故障分析部署文档

1. 架构与原理

2. 镜像与 Chart（全部来自内部 Harbor）

3. 前置准备

4. 一键部署

手动分步（等价命令）

飞书通知链路

5. 部署后验证

6. 最佳实践配置说明（k8sgpt-cr.yaml）

7. 踩坑记录

8. 费用估算