|
|
# Hadoop 故障诊断系统 - 后端服务 (FastAPI)
|
|
|
|
|
|
本项目是 Hadoop 故障诊断系统的后端核心，基于 FastAPI 构建，提供集群监控、日志采集、指标分析以及基于 AI 的智能故障诊断功能。
|
|
|
|
|
|
## 🚀 核心功能
|
|
|
|
|
|
- **用户与认证**: 基于 JWT 的无状态认证，支持用户注册、登录及权限管理。
|
|
|
- **集群与节点管理**: 支持 Hadoop 集群的注册、SSH 连通性校验、HDFS UUID 获取及节点状态管理。
|
|
|
- **指标采集与监控**:
|
|
|
- 自动采集集群及节点的 CPU、内存使用率。
|
|
|
- 提供实时指标查询与趋势图数据支持。
|
|
|
- **Hadoop 日志管理**:
|
|
|
- 远程日志读取：通过 SSH 实时读取各节点 Hadoop 日志。
|
|
|
- 自动日志采集：增量 tail 模式采集日志并持久化至数据库。
|
|
|
- 批量回填：支持对历史日志进行批量同步。
|
|
|
- **AI 智能诊断**:
|
|
|
- 集成 LangChain 与 OpenAI，提供流式对话接口 (SSE)。
|
|
|
- 智能智能体 (Agent) 可自动调用工具：查看日志、执行远程命令、分析集群状态。
|
|
|
- **系统执行日志**: 记录所有远程运维操作与系统任务的执行过程。
|
|
|
|
|
|
## 🛠 技术栈
|
|
|
|
|
|
- **框架**: [FastAPI](https://fastapi.tiangolo.com/) - 高性能异步 Web 框架。
|
|
|
- **数据库**: [PostgreSQL](https://www.postgresql.org/) + [SQLAlchemy (Async)](https://www.sqlalchemy.org/) - 异步 ORM 驱动。
|
|
|
- **SSH 通信**: [Paramiko](https://www.paramiko.org/) - 处理远程命令执行与日志读取。
|
|
|
- **AI/LLM**: [LangChain](https://www.langchain.com/) + OpenAI API - 实现故障诊断智能体。
|
|
|
- **任务调度**: 内置线程化采集器，支持异步指标与日志采集任务。
|
|
|
- **认证**: PyJWT + Passlib (BCrypt) - 安全的身份验证。
|
|
|
|
|
|
## 📂 项目结构
|
|
|
|
|
|
```text
|
|
|
backend/
|
|
|
├── app/
|
|
|
│ ├── agents/ # AI 智能体定义与工具编排
|
|
|
│ ├── deps/ # FastAPI 依赖注入（如认证、数据库）
|
|
|
│ ├── models/ # SQLAlchemy 异步模型
|
|
|
│ ├── routers/ # API 路由模块（集群、指标、日志、AI等）
|
|
|
│ ├── services/ # 业务逻辑服务（SSH管理、LLM调用等）
|
|
|
│ ├── workers/ # 异步任务处理逻辑
|
|
|
│ ├── config.py # 环境变量与全局配置
|
|
|
│ ├── db.py # 数据库引擎与会话管理
|
|
|
│ ├── main.py # 应用入口与路由注册
|
|
|
│ └── log_collector.py # 日志采集器核心实现
|
|
|
├── scripts/ # 数据库初始化与验证脚本
|
|
|
├── tests/ # 单元测试与集成测试
|
|
|
├── requirements.txt # 依赖清单
|
|
|
└── start_backend.sh # 一键启动脚本
|
|
|
```
|
|
|
|
|
|
## ⚙️ 环境变量配置
|
|
|
|
|
|
在 `backend/` 目录下创建 `.env` 文件，配置如下关键参数：
|
|
|
|
|
|
| 参数 | 描述 | 默认值 |
|
|
|
| :--- | :--- | :--- |
|
|
|
| `DATABASE_URL` | PostgreSQL 异步连接串 | `postgresql+asyncpg://postgres:password@localhost:5432/hadoop_fault_db` |
|
|
|
| `JWT_SECRET` | JWT 签名密钥 | `dev-secret` |
|
|
|
| `JWT_EXPIRE_MINUTES` | 令牌有效期（分钟） | `60` |
|
|
|
| `SSH_PORT` | 默认远程 SSH 端口 | `22` |
|
|
|
| `SSH_TIMEOUT` | SSH 连接超时时间 | `10` |
|
|
|
| `HADOOP_LOG_DIR` | Hadoop 远程日志默认路径 | `/usr/local/hadoop/logs` |
|
|
|
| `APP_TIMEZONE` | 系统时区 | `Asia/Shanghai` |
|
|
|
| `OPENAI_API_KEY` | OpenAI 密钥（用于 AI 诊断） | - |
|
|
|
|
|
|
## 🛠 安装与启动
|
|
|
|
|
|
### 1. 环境准备
|
|
|
- Python 3.10+
|
|
|
- PostgreSQL 14+
|
|
|
|
|
|
### 2. 安装依赖
|
|
|
```bash
|
|
|
cd backend
|
|
|
python3 -m venv .venv
|
|
|
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
|
|
|
pip install -r requirements.txt
|
|
|
```
|
|
|
|
|
|
### 3. 初始化数据库
|
|
|
执行 `scripts/` 目录下的 SQL 脚本或通过内置脚本初始化：
|
|
|
```bash
|
|
|
# 导入 SQL 脚本
|
|
|
psql -h <host> -U <user> -d <db> -f ../doc/project/数据库建表脚本_postgres.sql
|
|
|
```
|
|
|
|
|
|
### 4. 启动服务
|
|
|
```bash
|
|
|
# 开发模式
|
|
|
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
|
|
```
|
|
|
或使用提供的启动脚本：
|
|
|
```bash
|
|
|
bash start_backend.sh
|
|
|
```
|
|
|
|
|
|
## 📖 API 接口预览
|
|
|
|
|
|
所有接口均带有 `/api/v1` 前缀。
|
|
|
|
|
|
- **Health**: `GET /health`
|
|
|
- **Auth**: `POST /auth/login`, `POST /auth/register`
|
|
|
- **Clusters**: `GET /clusters`, `POST /clusters/register`
|
|
|
- **Metrics**: `GET /metrics/trend`, `POST /metrics/collector/start`
|
|
|
- **Hadoop Logs**: `GET /hadoop/logs/all/{log_type}`, `GET /hadoop/collectors/status`
|
|
|
- **AI**: `POST /ai/chat` (支持 SSE 流式返回)
|
|
|
|
|
|
详细接口文档启动后访问：`http://localhost:8000/docs`
|
|
|
|
|
|
## 🧪 验证与测试
|
|
|
运行端到端验证脚本：
|
|
|
```bash
|
|
|
python scripts/verify_register.py
|
|
|
```
|
