cnbugs
32bea0d4ea
扩展 Agent 命令工具，除 kubectl 外新增节点宿主机系统诊断命令支持：
- agent_tools.py: 新增 shell 命令白名单分类器 (classify_shell_command)
- 只读白名单: systemctl status/is-active、journalctl、crictl ps/logs、
docker ps/logs、df、free、ss、ip addr、ps、mount、lsmod、dmesg、
ping、nslookup、cat (限 /proc /sys /etc/kubernetes 等安全路径) 等 30+ 命令
- 写白名单: systemctl restart/stop/start/reload 等需人工审批
- 统一分发器 classify_agent_command 按命令前缀路由
- 统一执行入口 execute_command 走 subprocess_exec (无 shell 注入风险)
- ai_agent.py: 更新 AGENT_SYSTEM_PROMPT 告知 AI 两类可用工具及安全规则
- 三个调用点 (初始探测/分类/执行) 切换到统一接口
- main.py: 审批执行处改用 execute_command
- tests: 新增 19 个用例覆盖 shell 命令分类、混合执行、白名单拒绝
- 全部 44 个测试通过
- 前端/README: 文案与文档补充 shell 命令支持说明
安全策略不变: 禁止 shell 操作符/管道/重定向/多命令拼接，
非白名单命令 (rm/vi/apt 等) 直接拒绝。
107 lines
4.2 KiB
Markdown
107 lines
4.2 KiB
Markdown
# 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，实时展示诊断结果
|
||
|
||
## 快速开始
|
||
|
||
```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 大检查项)
|
||
│ ├── agent_tools.py # Agent 命令工具与安全策略 (kubectl + 系统诊断白名单)
|
||
│ └── ai_agent.py # AI Agent 分析模块
|
||
├── frontend/
|
||
│ ├── src/App.vue # 仪表盘界面
|
||
│ ├── index.html
|
||
│ └── vite.config.js
|
||
├── .env # 配置文件
|
||
├── start.sh # 一键启动脚本
|
||
└── README.md
|
||
```
|