k8smanager-cli/README.md

K8S 智能诊断平台

一键诊断 Kubernetes 集群健康状态，接入 AI Agent 自动分析故障根因并给出修复建议。

功能特性

• 一键诊断：9 大检查项全面扫描集群状态
  • 集群信息、Pod 状态、Node 状态、异常事件
  • Deployment 副本检查、Service/Endpoint 检查
  • PVC 存储检查、节点资源使用率、网络策略
• 健康评分：100 分制量化集群健康度（严重问题 -15 分，警告 -5 分）
• AI 智能分析：接入 OpenAI 兼容接口，自动分析诊断报告
  • 根因定位、影响评估、修复命令、优先级排序、预防建议
• AI 自主诊断（双执行模式）：启动前可选择命令执行方式
  • 手动执行命令：Agent 只生成命令，用户复制到自己的终端执行，服务端不会运行
  • AI 执行命令：自动执行只读诊断命令，覆盖 kubectl 与节点宿主机两个维度
    • kubectl: get、describe、logs、top 等只读命令
    • 系统诊断: systemctl status、journalctl、crictl ps、df、free、ss、ip addr 等只读命令
  • 实时展示思考步骤、执行命令和真实输出
  • 即使选择 AI 执行，修改命令人工确认：
    • kubectl: apply、delete、patch、scale、rollout、exec 等
    • 系统: systemctl restart/stop/start 等
  • 命令白名单严格限制，禁止 shell、管道、重定向和多命令拼接
• 历史记录持久化：使用 SQLite 保存全部诊断与处理轨迹
  • 保存完整诊断结果、文本报告、AI 分析结果
  • 保存 Agent 思考、命令、真实输出、审批和执行结果
  • 支持按状态、命名空间查询并查看完整详情
  • 服务重启后仍可读取历史和恢复最近一次诊断
• AI 追问对话：基于诊断上下文多轮追问，深入排查问题
• Web 仪表盘：Vue3 + Element Plus，实时展示诊断结果

快速开始

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

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

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

配置

编辑 .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

API 接口

方法	路径	说明
GET	/api/health	健康检查
GET	/api/checks	列出所有诊断项
POST	/api/diagnose	执行诊断 {"namespace":"", "checks":[]}
GET	/api/diagnosis/latest	获取最近诊断结果
POST	/api/analyze	AI 分析诊断结果 {"question":""}
GET	/api/agent/diagnose/stream	自主诊断 SSE 流，`execution_mode=manual
POST	/api/agent/approve	批准或拒绝待执行命令 {"approval_id":"...","approved":true}
GET	/api/history/diagnoses	查询全部诊断历史，支持 status、namespace 过滤
GET	/api/history/diagnoses/{id}	查询诊断详情及全部 AI/Agent 处理轨迹
POST	/api/chat	AI 多轮对话 {"messages":[...]}
GET	/api/report	获取诊断报告文本

技术栈

• 后端：Python 3 + FastAPI + kubernetes-client (kubectl)
• 前端：Vue 3 + Element Plus + Vite + marked
• AI：OpenAI 兼容 Chat Completions API

项目结构

k8smanager-cli/
├── backend/
│   ├── main.py          # FastAPI 主应用
│   ├── config.py        # 配置管理
│   ├── diagnosis.py     # K8S 诊断引擎 (9 大检查项)
│   ├── agent_tools.py   # Agent 命令工具与安全策略 (kubectl + 系统诊断白名单)
│   └── ai_agent.py      # AI Agent 分析模块
├── frontend/
│   ├── src/App.vue      # 仪表盘界面
│   ├── index.html
│   └── vite.config.js
├── .env                 # 配置文件
├── start.sh             # 一键启动脚本
└── README.md