# K8S 智能诊断平台

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

![界面预览](/home/cnbugs/.hermes/cache/screenshots/browser_screenshot_b258ca152c1e489fa186583946ecbd9e.png)

## 功能特性

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

## 快速开始

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

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

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

## 配置

编辑 `.env` 文件：

```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|ai` |
| 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 大检查项)
│   └── ai_agent.py      # AI Agent 分析模块
├── frontend/
│   ├── src/App.vue      # 仪表盘界面
│   ├── index.html
│   └── vite.config.js
├── .env                 # 配置文件
├── start.sh             # 一键启动脚本
└── README.md
```