ErrorDetecting/backend

Hadoop 故障诊断系统 - 后端服务 (FastAPI)

本项目是 Hadoop 故障诊断系统的后端核心，基于 FastAPI 构建，提供集群监控、日志采集、指标分析以及基于 AI 的智能故障诊断功能。

🚀 核心功能

• 用户与认证: 基于 JWT 的无状态认证，支持用户注册、登录及权限管理。
• 集群与节点管理: 支持 Hadoop 集群的注册、SSH 连通性校验、HDFS UUID 获取及节点状态管理。
• 指标采集与监控:
  • 自动采集集群及节点的 CPU、内存使用率。
  • 提供实时指标查询与趋势图数据支持。
• Hadoop 日志管理:
  • 远程日志读取：通过 SSH 实时读取各节点 Hadoop 日志。
  • 自动日志采集：增量 tail 模式采集日志并持久化至数据库。
  • 批量回填：支持对历史日志进行批量同步。
• AI 智能诊断:
  • 集成 LangChain 与 OpenAI，提供流式对话接口 (SSE)。
  • 智能智能体 (Agent) 可自动调用工具：查看日志、执行远程命令、分析集群状态。
• 系统执行日志: 记录所有远程运维操作与系统任务的执行过程。

🛠 技术栈

• 框架: FastAPI - 高性能异步 Web 框架。
• 数据库: PostgreSQL + SQLAlchemy (Async) - 异步 ORM 驱动。
• SSH 通信: Paramiko - 处理远程命令执行与日志读取。
• AI/LLM: LangChain + OpenAI API - 实现故障诊断智能体。
• 任务调度: 内置线程化采集器，支持异步指标与日志采集任务。
• 认证: PyJWT + Passlib (BCrypt) - 安全的身份验证。

📂 项目结构

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. 安装依赖

cd backend
python3 -m venv .venv
source .venv/bin/activate  # Windows: .\.venv\Scripts\activate
pip install -r requirements.txt

3. 初始化数据库

执行 scripts/ 目录下的 SQL 脚本或通过内置脚本初始化：

# 导入 SQL 脚本
psql -h <host> -U <user> -d <db> -f ../doc/project/数据库建表脚本_postgres.sql

4. 启动服务

# 开发模式
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

或使用提供的启动脚本：

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

🧪 验证与测试

运行端到端验证脚本：

python scripts/verify_register.py