K8S 智能诊断平台教程：Kubernetes 健康诊断与 AI 根因分析

K8S 智能诊断平台是一个一键诊断 Kubernetes 集群健康状态的工具：点一下诊断，9 大检查项全面扫描集群，输出 100 分制的健康评分；再接入 OpenAI 兼容接口的 AI Agent，对诊断报告做根因分析，给出修复建议。它还提供 AI 自主诊断的双执行模式和基于 SQLite 的历史记录，适合日常巡检、故障排查和集群健康度跟踪。

一、项目简介

平台由三部分组成：Python FastAPI 后端（诊断引擎 + AI Agent + 历史记录）、Vue 3 + Element Plus 前端仪表盘、SQLite 历史库。后端直接调用 kubectl 与 Kubernetes API 做检查，AI 分析走 OpenAI 兼容的 Chat Completions 接口，模型和接口地址都可以在 .env 里配置。

• 后端：Python 3 + FastAPI + kubernetes-client（kubectl）
• 前端：Vue 3 + Element Plus + Vite + marked
• AI：OpenAI 兼容 Chat Completions API（接口地址、密钥、模型均可配置）
• 默认端口：8900
• 历史存储：SQLite（诊断结果、报告、AI 分析与 Agent 处理轨迹全部持久化）

二、功能特性

• 一键诊断：9 大检查项全面扫描集群状态，包括集群信息、Pod 状态、Node 状态、异常事件、Deployment 副本检查、Service/Endpoint 检查、PVC 存储检查、节点资源使用率、网络策略。
• 健康评分：100 分制量化集群健康度，严重问题扣 15 分，警告扣 5 分，分数一目了然。
• AI 智能分析：接入 OpenAI 兼容接口，自动分析诊断报告，给出根因定位、影响评估、修复命令、优先级排序、预防建议。
• AI 自主诊断（双执行模式）：手动执行命令与 AI 执行命令两种模式，执行前可选；AI 执行只读命令，修改类命令需人工确认，命令白名单严格限制，禁止 shell、管道、重定向和多命令拼接。
• 历史记录持久化：SQLite 保存全部诊断与处理轨迹，服务重启后仍可读取历史和恢复最近一次诊断。
• AI 追问对话：基于诊断上下文多轮追问，深入排查问题。
• Web 仪表盘：Vue 3 + Element Plus，实时展示诊断结果。

三、9 大检查项与健康评分

健康评分的规则很直接：满分 100，严重问题每项扣 15 分，警告每项扣 5 分。评分的意义在于趋势跟踪——今天 95 分、明天 80 分，比单看“有几个 Pod 异常”更能反映集群整体健康度的变化。建议每天固定时间跑一次诊断，把分数记下来，分数持续下滑时再深入排查。

四、AI 智能分析：根因分析是怎么做到的

如实说明这个功能的边界很重要：平台的 AI 分析不是魔法，它是把诊断报告（9 大检查项的结果、异常事件、资源使用率等结构化数据）发送给配置好的 OpenAI 兼容接口，由大模型输出分析结果。分析内容包括五个方面：根因定位、影响评估、修复命令、优先级排序、预防建议。模型本身不直接操作集群，它只负责分析文本并给出建议；要不要执行建议里的命令，由人决定。

• 根因定位：根据诊断数据推断最可能的故障原因，比如 Pod 反复重启是因为 OOMKilled 还是镜像拉取失败。
• 影响评估：说明问题影响了哪些服务、影响面多大。
• 修复命令：给出具体的 kubectl 命令供参考，执行前需要人工确认。
• 优先级排序：多个问题同时存在时，按严重程度排优先级，先修哪个、后修哪个。
• 预防建议：针对根因给出避免再次发生的措施，比如调整资源 limit、加健康检查。

AI 分析的质量取决于两个因素：一是诊断数据的完整性（检查项覆盖越全，分析依据越充分），二是模型的推理能力。分析结果应当作排障参考，而不是最终结论——模型可能误判，尤其是在多个问题交织的复杂场景下。正确的做法是：看 AI 给出的根因和证据链，再用 kubectl 手动验证关键结论，确认后再执行修复命令。

五、AI 自主诊断：双执行模式与安全机制

自主诊断是平台上 AI 参与程度最深的功能，启动前可以选择命令执行方式，安全设计是这部分的核心。

即使选择 AI 执行模式，修改类命令也必须经过人工确认。需要确认的命令包括 kubectl 的 apply、delete、patch、scale、rollout、exec 等，以及系统的 systemctl restart / stop / start 等。AI 自动执行的只读命令覆盖 kubectl 与节点宿主机两个维度：kubectl 侧是 get、describe、logs、top 等；系统诊断侧是 systemctl status、journalctl、crictl ps、df、free、ss、ip addr 等。

• 命令白名单严格限制：只允许白名单内的命令，禁止 shell、管道、重定向和多命令拼接，防止 Agent 通过命令组合绕过限制。
• 实时展示：思考步骤、执行命令和真实输出实时展示在界面上，Agent 做了什么全程可见。
• 人工确认：任何修改类命令都要先经过批准或拒绝，批准接口为 POST /api/agent/approve，请求体带 approval_id 和 approved 字段。

安全建议：AI 执行模式只建议在测试集群或非核心命名空间先用，熟悉 Agent 的行为模式后再考虑生产集群。生产集群上优先用手动执行模式，命令先过一遍人眼再执行。白名单机制是最后一道防线，但不是万能的——定期检查 agent_tools.py 里的白名单定义，确认没有放宽。

六、安装部署

部署前确保 kubectl 已配置好，能正常访问目标集群。平台通过 kubectl 与 Kubernetes API 做检查，kubeconfig 配不对，诊断跑起来全是连接失败。

# 1. 确保 kubectl 已配置
kubectl cluster-info
kubectl get nodes

# 2. 启动服务
./start.sh

# 3. 打开浏览器
# http://localhost:8900

仓库里除了 start.sh 还有 setup.sh（README 未说明其用法，使用前请先阅读脚本内容确认它会安装哪些依赖、做哪些改动）。项目还自带 tests/ 目录下的 pytest 测试（诊断引擎、Agent 工具、历史记录等模块都有测试覆盖），部署前或改动代码后可以跑一遍测试验证：

# 跑测试验证（按仓库实际的测试配置为准）
python -m pytest tests/ -v

# 检查服务健康
curl -s http://localhost:8900/api/health | python3 -m json.tool

# 列出所有诊断项
curl -s http://localhost:8900/api/checks | python3 -m json.tool

七、配置详解

配置全部放在 .env 文件里，重点是 AI 接口三件套和历史库路径。AI 接口要填 OpenAI 兼容格式的地址、密钥和模型名；README 示例里用的是本地接口地址 http://localhost:8648/v1 和 qwen3.8-max-preview 模型，实际使用时换成你自己的服务地址和模型。

# .env 配置示例
# AI 分析接口（OpenAI 兼容格式）
AI_API_BASE=http://localhost:8648/v1
AI_API_KEY=your-api-key
AI_MODEL=qwen3.8-max-preview

# 服务端口
PORT=8900

# Kubeconfig 路径（留空使用默认 ~/.kube/config）
KUBECONFIG_PATH=

# 历史记录 SQLite 文件（K8S 部署时请挂载持久卷到该路径）
HISTORY_DB_PATH=/app/data/history.db

• AI_API_BASE / AI_API_KEY / AI_MODEL：AI 分析与自主诊断都走这个接口。密钥不要提交进 Git，生产环境用环境变量或密钥管理服务注入。
• PORT：服务监听端口，默认 8900。
• KUBECONFIG_PATH：留空时使用默认的 ~/.kube/config；多集群场景可以指向不同的 kubeconfig 文件切换目标集群。
• HISTORY_DB_PATH：SQLite 历史库路径。如果把平台本身部署在 Kubernetes 里，务必挂载持久卷到这个路径，否则 Pod 重建后历史记录全部丢失。

八、使用示例：诊断、分析与追问

网页上的标准流程是：打开仪表盘，点一键诊断，等 9 大检查项跑完，看健康评分和各项结果，再点 AI 分析看根因和修复建议，有疑问就用追问对话继续深挖。下面是对应的 API 调用方式，适合写自动化巡检脚本。

# 执行诊断（全集群；指定命名空间可传 namespace 参数）
curl -s -X POST http://localhost:8900/api/diagnose \
  -H 'Content-Type: application/json' \
  -d '{"namespace": "", "checks": []}' | python3 -m json.tool

# 获取最近一次诊断结果
curl -s http://localhost:8900/api/diagnosis/latest | python3 -m json.tool

# AI 分析诊断结果
curl -s -X POST http://localhost:8900/api/analyze \
  -H 'Content-Type: application/json' \
  -d '{"question": "为什么 payment 服务的 Pod 反复重启？"}' | python3 -m json.tool

# 获取诊断报告文本
curl -s http://localhost:8900/api/report

# AI 多轮追问（基于诊断上下文）
curl -s -X POST http://localhost:8900/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"messages": [{"role": "user", "content": "这个 OOMKilled 是内存 limit 设小了还是内存泄漏？"}]}' | python3 -m json.tool

一个典型的排障会话是这样的：诊断发现 payment 命名空间有两个 Pod 处于 CrashLoopBackOff，健康评分扣了 15 分；AI 分析指出事件里有 OOMKilled 记录，根因是内存 limit 设得过小，建议调大 limit 或排查内存泄漏，并给出验证命令；追问对话里进一步问“怎么区分是 limit 小了还是泄漏”，AI 会建议观察内存使用曲线——持续增长是泄漏，瞬间冲顶是 limit 不足。这个流程里 AI 负责缩小排查范围，最终结论还是要靠 kubectl top 和日志验证。

九、API 接口

# 健康检查与诊断
curl -s http://localhost:8900/api/health
curl -s http://localhost:8900/api/checks

# 自主诊断 SSE 流（execution_mode=manual 或 ai）
curl -s -N "http://localhost:8900/api/agent/diagnose/stream?execution_mode=manual"

# 批准或拒绝待执行命令
curl -s -X POST http://localhost:8900/api/agent/approve \
  -H 'Content-Type: application/json' \
  -d '{"approval_id": "abc123", "approved": true}'

# 查询诊断历史（支持 status、namespace 过滤）
curl -s "http://localhost:8900/api/history/diagnoses?status=failed&namespace=payment" | python3 -m json.tool

# 查询单次诊断详情及全部 AI/Agent 处理轨迹
curl -s http://localhost:8900/api/history/diagnoses/7 | python3 -m json.tool

接口设计上有两个值得注意的点：自主诊断用 SSE 流推送，思考步骤、命令和输出是边执行边返回的，适合前端实时展示；历史查询接口支持按状态和命名空间过滤，出了问题先按命名空间筛，再看单次详情里的完整轨迹。

十、历史记录与多轮追问

每次诊断的结果、文本报告、AI 分析结果都会保存到 SQLite；自主诊断时 Agent 的思考过程、生成的命令、真实输出、审批记录和执行结果也都会保存。服务重启后仍可读取历史和恢复最近一次诊断，这对故障复盘很有用——上周某次故障当时怎么分析的、执行了哪些命令、结果如何，都能翻出来对照。

AI 追问对话基于诊断上下文做多轮对话，不用每次重复描述集群状态。比如先问“这次诊断最严重的问题是什么”，再追问“这个问题的根因有哪些可能性”，再问“怎么验证是不是存储的问题”，对话会带着前面的上下文连续回答。追问同样走配置好的 OpenAI 兼容接口，回答质量取决于模型和诊断数据的完整性。

十一、常见问题

• 诊断全部失败、连不上集群？先检查 kubectl 本身是否能访问集群（kubectl cluster-info），再确认 KUBECONFIG_PATH 是否指向正确的 kubeconfig 文件。
• 健康评分突然掉了很多分？先看是哪些检查项扣的分，再去看对应检查项的详情。一次掉 15 分通常是出了严重问题（如节点 NotReady、大面积 Pod 异常），掉 5 分多是警告（如资源使用率偏高）。
• AI 分析报错或没返回？检查 .env 里的 AI_API_BASE 是否能连通、AI_API_KEY 是否有效、模型名是否正确。接口不通时诊断本身不受影响，只是分析功能不可用。
• AI 给的修复命令能直接执行吗？不能直接执行。AI 生成的命令是建议，先人工确认命令的作用范围和风险，尤其是涉及 apply、delete、scale 这类修改操作，平台本身也会要求人工批准。
• 历史记录丢了？检查 HISTORY_DB_PATH 指向的 SQLite 文件是否还在；部署在 K8S 里时确认持久卷挂载正确，Pod 重建不会丢数据。
• 自主诊断时 Agent 一直不输出？先看 SSE 流是否正常连接，再检查 AI 接口的响应速度；模型推理慢或接口超时都会导致长时间无输出。

十二、安全与运维建议

• 访问控制：平台能查看集群状态、调用 AI 执行命令，不要直接暴露到公网。内网访问，或前面加带认证的反向代理。
• 密钥管理：AI_API_KEY 和 kubeconfig 都属于敏感信息，不要写进 Git。kubeconfig 建议用最小权限的 ServiceAccount 凭证，而不是集群管理员凭证。
• 执行模式选择：生产集群优先用手动执行模式；AI 执行模式先在测试集群熟悉行为，确认白名单和审批流程符合预期后再考虑生产使用。
• 定期巡检：每天固定时间跑一次一键诊断，把健康评分记下来做趋势跟踪；分数持续下滑时及时排查，不要等到业务受影响才动手。
• 历史库备份：定期备份 HISTORY_DB_PATH 的 SQLite 文件，故障复盘和审计都依赖它。
• AI 结果复核：AI 分析是排障参考，不是结论。执行修复命令前，先用 kubectl 手动验证根因，确认无误再动手。

总结：K8S 智能诊断平台把三件事串在了一起——9 大检查项做体检、健康评分做量化、AI Agent 做根因分析和自主诊断。它的价值不在于替代人的判断，而在于把“发现问题、定位原因、给出修复方向”这个链条缩短。日常巡检用一键诊断，出问题时用 AI 分析缩小范围，修复前人工确认命令，这个节奏跑顺了，集群故障的平均处理时间能明显缩短。

Mr丶点心

打赏 海报 链接