|
|
# Hadoop Fault Detecting API 文档
|
|
|
|
|
|
## 项目概述
|
|
|
|
|
|
这是一个用于Hadoop故障检测的API服务，基于FastAPI框架开发。该服务提供了集群管理、节点监控、日志分析、故障检测等功能，帮助管理员实时监控和管理Hadoop集群。
|
|
|
|
|
|
## 技术栈
|
|
|
|
|
|
- **框架**: FastAPI
|
|
|
- **语言**: Python 3.13
|
|
|
- **依赖**: SQLAlchemy, asyncpg, python-dotenv, passlib, PyJWT, langchain, httpx, paramiko
|
|
|
|
|
|
## 目录结构
|
|
|
|
|
|
```
|
|
|
app/
|
|
|
├── agents/ # AI智能代理
|
|
|
├── deps/ # 依赖项
|
|
|
├── models/ # 数据库模型
|
|
|
├── routers/ # API路由
|
|
|
├── services/ # 业务逻辑
|
|
|
├── config.py # 配置文件
|
|
|
├── db.py # 数据库连接
|
|
|
├── log_collector.py # 日志收集器
|
|
|
├── log_reader.py # 日志阅读器
|
|
|
├── main.py # 应用入口
|
|
|
├── schemas.py # 数据模型
|
|
|
├── ssh_utils.py # SSH工具
|
|
|
└── __init__.py # 包初始化
|
|
|
```
|
|
|
|
|
|
## API 路由概述
|
|
|
|
|
|
| 模块 | 路径前缀 | 功能描述 |
|
|
|
|------|----------|----------|
|
|
|
| health | /api/v1 | 健康检查 |
|
|
|
| auth | /api/v1 | 身份认证 |
|
|
|
| secure | /api/v1 | 安全相关 |
|
|
|
| clusters | /api/v1 | 集群管理 |
|
|
|
| nodes | /api/v1 | 节点管理 |
|
|
|
| metrics | /api/v1 | 指标监控 |
|
|
|
| users | /api/v1 | 用户管理 |
|
|
|
| hadoop_logs | /api/v1 | Hadoop日志管理 |
|
|
|
| faults | /api/v1 | 故障检测 |
|
|
|
| hadoop_exec_logs | /api/v1 | Hadoop执行日志 |
|
|
|
| ops | /api/v1 | 操作管理 |
|
|
|
| ai | /api/v1 | AI智能分析 |
|
|
|
| sys_exec_logs | /api/v1 | 系统操作日志 |
|
|
|
|
|
|
## 详细API文档
|
|
|
|
|
|
### 1. 健康检查 (health.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /health | 健康检查，包括数据库连接验证 | 否 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /health
|
|
|
|
|
|
**功能描述**：
|
|
|
检查服务健康状态，同时验证数据库连接是否正常。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"status": "ok",
|
|
|
"database": "connected" // 或 "disconnected: 错误信息"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"status": "ok",
|
|
|
"database": "connected"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"status": "ok",
|
|
|
"database": "disconnected: connection refused"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 2. 身份认证 (auth.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| POST | /user/login | 用户登录 | 否 |
|
|
|
| POST | /user/register | 用户注册 | 否 |
|
|
|
| GET | /user/me | 获取当前用户信息 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### POST /user/login
|
|
|
|
|
|
**功能描述**：
|
|
|
用户登录，验证用户名和密码，返回JWT令牌。
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "string",
|
|
|
"password": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "admin",
|
|
|
"password": "admin123"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true,
|
|
|
"username": "string",
|
|
|
"fullName": "string",
|
|
|
"token": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true,
|
|
|
"username": "admin",
|
|
|
"fullName": "admin",
|
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "invalid_credentials"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /user/register
|
|
|
|
|
|
**功能描述**：
|
|
|
用户注册，创建新用户并返回JWT令牌。
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "string",
|
|
|
"email": "string",
|
|
|
"password": "string",
|
|
|
"fullName": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "newuser",
|
|
|
"email": "newuser@example.com",
|
|
|
"password": "NewPass123",
|
|
|
"fullName": "New User"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**验证规则**：
|
|
|
- 用户名：3-50个字符，以字母开头，支持字母/数字/下划线
|
|
|
- 邮箱：有效的邮箱格式
|
|
|
- 密码：至少8位，包含大小写字母和数字
|
|
|
- 姓名：2-100个字符
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true,
|
|
|
"username": "string",
|
|
|
"fullName": "string",
|
|
|
"token": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true,
|
|
|
"username": "newuser",
|
|
|
"fullName": "New User",
|
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": {
|
|
|
"errors": [
|
|
|
{
|
|
|
"field": "password",
|
|
|
"code": "weak_password",
|
|
|
"message": "密码至少8位，需包含大小写字母与数字"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /user/me
|
|
|
|
|
|
**功能描述**：
|
|
|
获取当前登录用户的信息。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "string",
|
|
|
"fullName": "string",
|
|
|
"isActive": boolean
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "admin",
|
|
|
"fullName": "admin",
|
|
|
"isActive": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 3. 集群管理 (clusters.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /clusters | 获取当前用户可访问的集群列表 | 是 |
|
|
|
| POST | /clusters | 注册新集群并建立用户归属映射 | 是 |
|
|
|
| DELETE | /clusters/{uuid} | 注销指定集群并清理用户归属映射 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /clusters
|
|
|
|
|
|
**功能描述**：
|
|
|
按当前用户归属返回其可访问的集群列表。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"clusters": [
|
|
|
{
|
|
|
"uuid": "string",
|
|
|
"host": "string",
|
|
|
"ip": "string",
|
|
|
"count": 0,
|
|
|
"health": "string"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"clusters": [
|
|
|
{
|
|
|
"uuid": "123e4567-e89b-12d3-a456-426614174000",
|
|
|
"host": "hadoop-master",
|
|
|
"ip": "192.168.1.100",
|
|
|
"count": 5,
|
|
|
"health": "running"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /clusters
|
|
|
|
|
|
**功能描述**：
|
|
|
注册一个新集群并建立当前用户的归属映射。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"uuid": "string",
|
|
|
"host": "string",
|
|
|
"ip": "string",
|
|
|
"count": 0,
|
|
|
"health": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"uuid": "123e4567-e89b-12d3-a456-426614174000",
|
|
|
"host": "hadoop-master",
|
|
|
"ip": "192.168.1.100",
|
|
|
"count": 5,
|
|
|
"health": "running"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_allowed"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### DELETE /clusters/{uuid}
|
|
|
|
|
|
**功能描述**：
|
|
|
注销指定集群，并清理用户归属映射。
|
|
|
|
|
|
**请求参数**：
|
|
|
- uuid: 集群的UUID（路径参数）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": {
|
|
|
"errors": [
|
|
|
{
|
|
|
"field": "uuid",
|
|
|
"message": "UUID 格式不正确"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 4. 节点管理 (nodes.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /nodes | 拉取指定集群的节点列表 | 是 |
|
|
|
| GET | /nodes/{name} | 查询节点详情 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /nodes
|
|
|
|
|
|
**功能描述**：
|
|
|
拉取指定集群的节点列表。
|
|
|
|
|
|
**请求参数**：
|
|
|
- cluster: 集群UUID（查询参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"nodes": [
|
|
|
{
|
|
|
"name": "string",
|
|
|
"ip": "string",
|
|
|
"status": "string",
|
|
|
"cpu": "string",
|
|
|
"mem": "string",
|
|
|
"updated": "string"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"nodes": [
|
|
|
{
|
|
|
"name": "hadoop-node1",
|
|
|
"ip": "192.168.1.101",
|
|
|
"status": "running",
|
|
|
"cpu": "25%",
|
|
|
"mem": "60%",
|
|
|
"updated": "10分钟前"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /nodes/{name}
|
|
|
|
|
|
**功能描述**：
|
|
|
查询指定节点的详细信息。
|
|
|
|
|
|
**请求参数**：
|
|
|
- name: 节点名称（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"name": "string",
|
|
|
"metrics": {
|
|
|
"cpu": "string",
|
|
|
"mem": "string",
|
|
|
"disk": "string",
|
|
|
"status": "string",
|
|
|
"ip": "string",
|
|
|
"lastHeartbeat": "string"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"name": "hadoop-node1",
|
|
|
"metrics": {
|
|
|
"cpu": "25%",
|
|
|
"mem": "60%",
|
|
|
"disk": "45%",
|
|
|
"status": "running",
|
|
|
"ip": "192.168.1.101",
|
|
|
"lastHeartbeat": "2025-12-18T00:00:00+00:00"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 5. 指标监控 (metrics.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /metrics/cpu_trend | 获取指定集群的CPU使用率趋势数据 | 是 |
|
|
|
| GET | /metrics/memory_usage | 获取指定集群的内存使用情况 | 是 |
|
|
|
| GET | /metrics/cpu_trend_node | 获取指定节点的CPU使用率趋势数据 | 是 |
|
|
|
| GET | /metrics/memory_usage_node | 获取指定节点的内存使用情况 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /metrics/cpu_trend
|
|
|
|
|
|
**功能描述**：
|
|
|
获取指定集群的CPU使用率趋势数据。
|
|
|
|
|
|
**请求参数**：
|
|
|
- cluster: 集群UUID（查询参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"times": ["string"],
|
|
|
"values": [0]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"times": ["00:00","04:00","08:00","12:00","16:00","20:00","24:00"],
|
|
|
"values": [20, 25, 30, 35, 40, 35, 30]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /metrics/memory_usage
|
|
|
|
|
|
**功能描述**：
|
|
|
获取指定集群的内存使用情况（单位：百分比）。
|
|
|
|
|
|
**请求参数**：
|
|
|
- cluster: 集群UUID（查询参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"used": 0.0,
|
|
|
"free": 0.0
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"used": 60.5,
|
|
|
"free": 39.5
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /metrics/cpu_trend_node
|
|
|
|
|
|
**功能描述**：
|
|
|
获取指定节点的CPU使用率趋势数据。
|
|
|
|
|
|
**请求参数**：
|
|
|
- cluster: 集群UUID（查询参数，必填）
|
|
|
- node: 节点名称（查询参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"times": ["string"],
|
|
|
"values": [0]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"times": ["00:00","04:00","08:00","12:00","16:00","20:00","24:00"],
|
|
|
"values": [15, 20, 25, 30, 35, 30, 25]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /metrics/memory_usage_node
|
|
|
|
|
|
**功能描述**：
|
|
|
获取指定节点的内存使用情况（单位：百分比）。
|
|
|
|
|
|
**请求参数**：
|
|
|
- cluster: 集群UUID（查询参数，必填）
|
|
|
- node: 节点名称（查询参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"used": 0.0,
|
|
|
"free": 0.0
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"used": 55.2,
|
|
|
"free": 44.8
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 6. 故障检测 (faults.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /faults | 获取故障列表，支持筛选条件 | 是 |
|
|
|
| POST | /faults | 创建新故障（仅管理员/操作员） | 是 |
|
|
|
| PUT | /faults/{fid} | 更新故障信息（仅管理员/操作员） | 是 |
|
|
|
| DELETE | /faults/{fid} | 删除故障（仅管理员/操作员） | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /faults
|
|
|
|
|
|
**功能描述**：
|
|
|
获取故障列表，支持筛选条件。
|
|
|
|
|
|
**请求参数**：
|
|
|
- cluster: 集群UUID或名称（可选）
|
|
|
- node: 节点名称（可选）
|
|
|
- time_from: 开始时间（ISO格式，可选）
|
|
|
- page: 页码（默认1）
|
|
|
- size: 每页条数（默认10，1-100）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"items": [
|
|
|
{
|
|
|
"id": "string",
|
|
|
"type": "string",
|
|
|
"level": "string",
|
|
|
"status": "string",
|
|
|
"title": "string",
|
|
|
"cluster": "string",
|
|
|
"node": "string",
|
|
|
"created": "string"
|
|
|
}
|
|
|
],
|
|
|
"total": 0
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"items": [
|
|
|
{
|
|
|
"id": "fault-123",
|
|
|
"type": "disk",
|
|
|
"level": "error",
|
|
|
"status": "active",
|
|
|
"title": "磁盘空间不足",
|
|
|
"cluster": "123e4567-e89b-12d3-a456-426614174000",
|
|
|
"node": "hadoop-node1",
|
|
|
"created": "2025-12-18T00:00:00+00:00"
|
|
|
}
|
|
|
],
|
|
|
"total": 1
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /faults
|
|
|
|
|
|
**功能描述**：
|
|
|
创建新故障，仅管理员和操作员可使用。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"id": "string",
|
|
|
"type": "string",
|
|
|
"level": "string",
|
|
|
"status": "string",
|
|
|
"title": "string",
|
|
|
"cluster": "string",
|
|
|
"node": "string",
|
|
|
"created": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"id": "fault-123",
|
|
|
"type": "disk",
|
|
|
"level": "error",
|
|
|
"status": "active",
|
|
|
"title": "磁盘空间不足",
|
|
|
"cluster": "123e4567-e89b-12d3-a456-426614174000",
|
|
|
"node": "hadoop-node1",
|
|
|
"created": "2025-12-18T00:00:00+00:00"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_allowed"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### PUT /faults/{fid}
|
|
|
|
|
|
**功能描述**：
|
|
|
更新故障信息，仅管理员和操作员可使用。
|
|
|
|
|
|
**请求参数**：
|
|
|
- fid: 故障ID（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"status": "string",
|
|
|
"title": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"status": "resolved",
|
|
|
"title": "磁盘空间不足已解决"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_found"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### DELETE /faults/{fid}
|
|
|
|
|
|
**功能描述**：
|
|
|
删除故障，仅管理员和操作员可使用。
|
|
|
|
|
|
**请求参数**：
|
|
|
- fid: 故障ID（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_allowed"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 7. Hadoop执行日志 (hadoop_exec_logs.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /exec-logs | 获取所有执行日志 | 是 |
|
|
|
| POST | /exec-logs | 创建新的执行日志 | 是 |
|
|
|
| PUT | /exec-logs/{log_id} | 更新执行日志 | 是 |
|
|
|
| DELETE | /exec-logs/{log_id} | 删除执行日志 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /exec-logs
|
|
|
|
|
|
**功能描述**：
|
|
|
获取所有执行日志，按开始时间倒序排列。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"items": [
|
|
|
{
|
|
|
"id": 0,
|
|
|
"from_user_id": 0,
|
|
|
"cluster_name": "string",
|
|
|
"description": "string",
|
|
|
"start_time": "string",
|
|
|
"end_time": "string"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /exec-logs
|
|
|
|
|
|
**功能描述**：
|
|
|
创建新的执行日志。
|
|
|
|
|
|
**请求参数**：
|
|
|
- from_user_id: 用户ID (必填)
|
|
|
- cluster_name: 集群名称 (必填)
|
|
|
- description: 描述 (可选)
|
|
|
- start_time: 开始时间 (ISO格式，可选)
|
|
|
- end_time: 结束时间 (ISO格式，可选)
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true,
|
|
|
"id": 1
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### PUT /exec-logs/{log_id}
|
|
|
|
|
|
**功能描述**：
|
|
|
更新指定的执行日志信息。
|
|
|
|
|
|
**请求参数**：
|
|
|
- log_id: 执行日志ID (路径参数，必填)
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"description": "string",
|
|
|
"start_time": "string",
|
|
|
"end_time": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### DELETE /exec-logs/{log_id}
|
|
|
|
|
|
**功能描述**：
|
|
|
删除指定的执行日志。
|
|
|
|
|
|
**请求参数**：
|
|
|
- log_id: 执行日志ID (路径参数，必填)
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 8. 操作管理 (ops.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| POST | /ops/read-log | 读取远端日志文件内容，支持可选筛选 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### POST /ops/read-log
|
|
|
|
|
|
**功能描述**：
|
|
|
读取远端日志文件内容，支持可选筛选，仅管理员和操作员可使用。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"node": "string",
|
|
|
"path": "string",
|
|
|
"lines": 200,
|
|
|
"pattern": "string",
|
|
|
"sshUser": "string",
|
|
|
"timeout": 20
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求参数说明**：
|
|
|
- node: 目标节点主机名（必填）
|
|
|
- path: 日志文件路径（必填）
|
|
|
- lines: 读取行数，默认为200，范围1-5000（可选）
|
|
|
- pattern: 可选过滤正则（可选）
|
|
|
- sshUser: SSH用户名（可选）
|
|
|
- timeout: 命令超时时间，默认为20秒，范围1-120秒（可选）
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"node": "hadoop-node1",
|
|
|
"path": "/var/log/hadoop/hdfs/hadoop-hdfs-datanode.log",
|
|
|
"lines": 100,
|
|
|
"pattern": "ERROR",
|
|
|
"timeout": 30
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"execId": "string",
|
|
|
"exitCode": 0,
|
|
|
"lines": ["string"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"execId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
|
|
|
"exitCode": 0,
|
|
|
"lines": [
|
|
|
"2025-12-18 00:00:00,000 ERROR [main] org.apache.hadoop.hdfs.server.datanode.DataNode: Initialization failed",
|
|
|
"2025-12-18 00:00:01,000 ERROR [main] org.apache.hadoop.hdfs.server.datanode.DataNode: java.io.IOException: Failed to bind to port 50010"
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_allowed"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 9. AI智能分析 (ai.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| POST | /ai/diagnose-repair | AI诊断与修复 | 是 |
|
|
|
| POST | /ai/chat | AI聊天 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### POST /ai/diagnose-repair
|
|
|
|
|
|
**功能描述**：
|
|
|
AI诊断与修复，根据提供的条件分析日志并提供修复建议，支持自动修复。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"cluster": "string",
|
|
|
"node": "string",
|
|
|
"timeFrom": "string",
|
|
|
"keywords": "string",
|
|
|
"auto": true,
|
|
|
"maxSteps": 3
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求参数说明**：
|
|
|
- cluster: 集群UUID（可选）
|
|
|
- node: 节点主机名（可选）
|
|
|
- timeFrom: ISO起始时间（可选）
|
|
|
- keywords: 关键词（可选）
|
|
|
- auto: 是否允许自动修复，默认为true（可选）
|
|
|
- maxSteps: 最多工具步数，默认为3，范围1-6（可选）
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"cluster": "123e4567-e89b-12d3-a456-426614174000",
|
|
|
"node": "hadoop-node1",
|
|
|
"keywords": "ERROR",
|
|
|
"auto": true,
|
|
|
"maxSteps": 3
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"result": "string",
|
|
|
"steps": [
|
|
|
{
|
|
|
"action": "string",
|
|
|
"content": "string",
|
|
|
"result": "string"
|
|
|
}
|
|
|
],
|
|
|
"repair": {
|
|
|
"success": true,
|
|
|
"details": "string"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"result": "已检测到磁盘空间不足问题",
|
|
|
"steps": [
|
|
|
{
|
|
|
"action": "分析日志",
|
|
|
"content": "检查hadoop-hdfs-datanode.log",
|
|
|
"result": "发现磁盘空间不足错误"
|
|
|
},
|
|
|
{
|
|
|
"action": "检查磁盘",
|
|
|
"content": "df -h",
|
|
|
"result": "/dev/sda1 已使用95%"
|
|
|
}
|
|
|
],
|
|
|
"repair": {
|
|
|
"success": true,
|
|
|
"details": "已清理临时文件，释放了10GB空间"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "server_error"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /ai/chat
|
|
|
|
|
|
**功能描述**：
|
|
|
AI聊天，与LLM模型进行对话。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"messages": [
|
|
|
{
|
|
|
"role": "string",
|
|
|
"content": "string"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求参数说明**：
|
|
|
- messages: 对话消息列表，包含角色和内容（必填）
|
|
|
- role: 角色，可选值：system, user, assistant
|
|
|
- content: 消息内容
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"messages": [
|
|
|
{
|
|
|
"role": "user",
|
|
|
"content": "Hadoop NameNode 启动失败怎么办？"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"reply": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"reply": "Hadoop NameNode 启动失败可能有多种原因，建议检查以下几点：\n1. 检查日志文件 /var/log/hadoop/hdfs/hadoop-hdfs-namenode.log\n2. 验证namenode数据目录权限\n3. 检查fsimage和edits文件是否损坏\n4. 确保端口50070未被占用"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "llm_unavailable"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 10. Hadoop日志管理 (hadoop_logs.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /logs | 获取Hadoop聚合日志列表 | 是 |
|
|
|
| GET | /hadoop/nodes/ | 获取所有Hadoop节点列表 | 是 |
|
|
|
| GET | /hadoop/logs/{node_name}/{log_type}/ | 获取特定Hadoop节点的日志 | 是 |
|
|
|
| GET | /hadoop/logs/all/{log_type}/ | 获取所有Hadoop节点的日志 | 是 |
|
|
|
| GET | /hadoop/logs/files/{node_name}/ | 获取特定Hadoop节点的日志文件列表 | 是 |
|
|
|
| GET | /hadoop/collectors/status/ | 获取所有Hadoop日志收集器状态 | 是 |
|
|
|
| POST | /hadoop/collectors/start/{node_name}/{log_type}/ | 启动特定Hadoop节点和日志类型的收集 | 是 |
|
|
|
| POST | /hadoop/collectors/stop/{node_name}/{log_type}/ | 停止特定Hadoop节点和日志类型的收集 | 是 |
|
|
|
| POST | /hadoop/collectors/stop/all/ | 停止所有Hadoop日志收集器 | 是 |
|
|
|
| POST | /hadoop/collectors/set-interval/{interval}/ | 设置所有Hadoop收集器的收集间隔 | 是 |
|
|
|
| POST | /hadoop/collectors/set-log-dir/{log_dir}/ | 设置所有Hadoop收集器的日志目录 | 是 |
|
|
|
| POST | /hadoop/nodes/{node_name}/execute/ | 在特定Hadoop节点上执行命令 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /hadoop/nodes/
|
|
|
|
|
|
**功能描述**：
|
|
|
获取所有Hadoop节点列表。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"nodes": ["string"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"nodes": ["hadoop-master", "hadoop-node1", "hadoop-node2"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /hadoop/logs/{node_name}/{log_type}/
|
|
|
|
|
|
**功能描述**：
|
|
|
获取特定Hadoop节点的日志。
|
|
|
|
|
|
**请求参数**：
|
|
|
- node_name: 节点名称（路径参数，必填）
|
|
|
- log_type: 日志类型（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"node_name": "string",
|
|
|
"log_type": "string",
|
|
|
"log_content": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"node_name": "hadoop-master",
|
|
|
"log_type": "namenode",
|
|
|
"log_content": "2025-12-18 00:00:00,000 INFO NameNode: Starting namenode..."
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /hadoop/logs/all/{log_type}/
|
|
|
|
|
|
**功能描述**：
|
|
|
获取所有Hadoop节点的日志。
|
|
|
|
|
|
**请求参数**：
|
|
|
- log_type: 日志类型（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"logs": [
|
|
|
{
|
|
|
"node_name": "string",
|
|
|
"log_type": "string",
|
|
|
"log_content": "string"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"logs": [
|
|
|
{
|
|
|
"node_name": "hadoop-master",
|
|
|
"log_type": "namenode",
|
|
|
"log_content": "2025-12-18 00:00:00,000 INFO NameNode: Starting namenode..."
|
|
|
},
|
|
|
{
|
|
|
"node_name": "hadoop-node1",
|
|
|
"log_type": "datanode",
|
|
|
"log_content": "2025-12-18 00:00:01,000 INFO DataNode: Starting datanode..."
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /hadoop/logs/files/{node_name}/
|
|
|
|
|
|
**功能描述**：
|
|
|
获取特定Hadoop节点的日志文件列表。
|
|
|
|
|
|
**请求参数**：
|
|
|
- node_name: 节点名称（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"node_name": "string",
|
|
|
"log_files": ["string"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"node_name": "hadoop-master",
|
|
|
"log_files": ["hadoop-hdfs-namenode.log", "hadoop-hdfs-namenode.out"]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### GET /hadoop/collectors/status/
|
|
|
|
|
|
**功能描述**：
|
|
|
获取所有Hadoop日志收集器状态。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"collectors": {
|
|
|
"string": 0
|
|
|
},
|
|
|
"total_running": 0
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"collectors": {
|
|
|
"hadoop-master_namenode": 1,
|
|
|
"hadoop-node1_datanode": 1
|
|
|
},
|
|
|
"total_running": 2
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /hadoop/collectors/start/{node_name}/{log_type}/
|
|
|
|
|
|
**功能描述**：
|
|
|
启动特定Hadoop节点和日志类型的收集。
|
|
|
|
|
|
**请求参数**：
|
|
|
- node_name: 节点名称（路径参数，必填）
|
|
|
- log_type: 日志类型（路径参数，必填）
|
|
|
- interval: 收集间隔（秒，默认5）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "string",
|
|
|
"interval": 5
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "Started log collection for hadoop-master_namenode",
|
|
|
"interval": 5
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /hadoop/collectors/stop/{node_name}/{log_type}/
|
|
|
|
|
|
**功能描述**：
|
|
|
停止特定Hadoop节点和日志类型的收集。
|
|
|
|
|
|
**请求参数**：
|
|
|
- node_name: 节点名称（路径参数，必填）
|
|
|
- log_type: 日志类型（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "Stopped log collection for hadoop-master_namenode"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /hadoop/collectors/stop/all/
|
|
|
|
|
|
**功能描述**：
|
|
|
停止所有Hadoop日志收集器。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "Stopped all log collectors"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /hadoop/collectors/set-interval/{interval}/
|
|
|
|
|
|
**功能描述**：
|
|
|
设置所有Hadoop收集器的收集间隔。
|
|
|
|
|
|
**请求参数**：
|
|
|
- interval: 收集间隔（秒，路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "Set collection interval to 10 seconds"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /hadoop/collectors/set-log-dir/{log_dir}/
|
|
|
|
|
|
**功能描述**：
|
|
|
设置所有Hadoop收集器的日志目录。
|
|
|
|
|
|
**请求参数**：
|
|
|
- log_dir: 日志目录（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"message": "Set log directory to /var/log/hadoop"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /hadoop/nodes/{node_name}/execute/
|
|
|
|
|
|
**功能描述**：
|
|
|
在特定Hadoop节点上执行命令。
|
|
|
|
|
|
**请求参数**：
|
|
|
- node_name: 节点名称（路径参数，必填）
|
|
|
- command: 要执行的命令（请求体参数，必填）
|
|
|
- timeout: 超时时间（秒，默认30）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"command": "string",
|
|
|
"timeout": 30
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"command": "hdfs dfsadmin -report",
|
|
|
"timeout": 60
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"node_name": "string",
|
|
|
"command": "string",
|
|
|
"stdout": "string",
|
|
|
"stderr": "string",
|
|
|
"status": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"node_name": "hadoop-master",
|
|
|
"command": "hdfs dfsadmin -report",
|
|
|
"stdout": "Configured Capacity: 1000000000000 (931.32 GB)\nPresent Capacity: 500000000000 (465.66 GB)",
|
|
|
"stderr": "",
|
|
|
"status": "success"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 11. 用户管理 (users.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /users | 获取所有用户列表（仅管理员） | 是 |
|
|
|
| POST | /users | 创建新用户（仅管理员） | 是 |
|
|
|
| PATCH | /users/{username} | 更新用户信息（仅管理员） | 是 |
|
|
|
| DELETE | /users/{username} | 删除用户（仅管理员） | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /users
|
|
|
|
|
|
**功能描述**：
|
|
|
获取所有用户列表，仅管理员可访问。
|
|
|
|
|
|
**请求参数**：
|
|
|
无
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"users": [
|
|
|
{
|
|
|
"username": "string",
|
|
|
"email": "string",
|
|
|
"role": "string",
|
|
|
"status": "string"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"users": [
|
|
|
{
|
|
|
"username": "admin",
|
|
|
"email": "admin@example.com",
|
|
|
"role": "admin",
|
|
|
"status": "enabled"
|
|
|
},
|
|
|
{
|
|
|
"username": "ops",
|
|
|
"email": "ops@example.com",
|
|
|
"role": "operator",
|
|
|
"status": "enabled"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_admin"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /users
|
|
|
|
|
|
**功能描述**：
|
|
|
创建新用户，仅管理员可访问。
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "string",
|
|
|
"email": "string",
|
|
|
"role": "string",
|
|
|
"status": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求参数说明**：
|
|
|
- username: 用户名，3-50个字符，以字母开头，支持字母/数字/下划线（必填）
|
|
|
- email: 电子邮箱（必填）
|
|
|
- role: 角色，可选值：admin, operator, observer（必填）
|
|
|
- status: 状态，可选值：enabled, pending, disabled（必填）
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"username": "newuser",
|
|
|
"email": "newuser@example.com",
|
|
|
"role": "observer",
|
|
|
"status": "enabled"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": {
|
|
|
"errors": [
|
|
|
{
|
|
|
"field": "username",
|
|
|
"message": "用户名已存在"
|
|
|
}
|
|
|
]
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### PATCH /users/{username}
|
|
|
|
|
|
**功能描述**：
|
|
|
更新用户信息，仅管理员可访问。
|
|
|
|
|
|
**请求参数**：
|
|
|
- username: 用户名（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**请求体**：
|
|
|
```json
|
|
|
{
|
|
|
"role": "string",
|
|
|
"status": "string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**请求参数说明**：
|
|
|
- role: 角色，可选值：admin, operator, observer（可选）
|
|
|
- status: 状态，可选值：enabled, disabled（可选）
|
|
|
|
|
|
**请求示例**：
|
|
|
```json
|
|
|
{
|
|
|
"role": "operator",
|
|
|
"status": "enabled"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_found"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### DELETE /users/{username}
|
|
|
|
|
|
**功能描述**：
|
|
|
删除用户，仅管理员可访问。
|
|
|
|
|
|
**请求参数**：
|
|
|
- username: 用户名（路径参数，必填）
|
|
|
|
|
|
**请求头**：
|
|
|
```
|
|
|
Authorization: Bearer {token}
|
|
|
```
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**错误示例**：
|
|
|
```json
|
|
|
{
|
|
|
"detail": "not_admin"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 12. 安全相关 (secure.py)
|
|
|
|
|
|
**说明**：安全相关模块当前只包含一个获取当前用户信息的接口，该接口已在身份认证模块中详细描述。
|
|
|
|
|
|
### 13. 系统操作日志 (sys_exec_logs.py)
|
|
|
|
|
|
#### 接口列表
|
|
|
|
|
|
| 方法 | 路径 | 功能描述 | 认证要求 |
|
|
|
|------|------|----------|----------|
|
|
|
| GET | /sys-exec-logs | 获取系统操作日志列表 | 是 |
|
|
|
| POST | /sys-exec-logs | 创建系统操作日志 | 是 |
|
|
|
| DELETE | /sys-exec-logs/{operation_id} | 删除系统操作日志 | 是 |
|
|
|
|
|
|
#### 详细接口说明
|
|
|
|
|
|
##### GET /sys-exec-logs
|
|
|
|
|
|
**功能描述**：
|
|
|
获取系统操作日志列表，支持分页。
|
|
|
|
|
|
**请求参数**：
|
|
|
- page: 页码 (默认1)
|
|
|
- size: 每页数量 (默认10)
|
|
|
|
|
|
**响应格式**：
|
|
|
```json
|
|
|
{
|
|
|
"items": [
|
|
|
{
|
|
|
"operation_id": "string",
|
|
|
"user_id": 0,
|
|
|
"description": "string",
|
|
|
"operation_time": "string"
|
|
|
}
|
|
|
],
|
|
|
"total": 0
|
|
|
}
|
|
|
```
|
|
|
|
|
|
##### POST /sys-exec-logs
|
|
|
|
|
|
**功能描述**：
|
|
|
创建系统操作日志。
|
|
|
|
|
|
**请求参数**：
|
|
|
- user_id: 用户ID (必填)
|
|
|
- description: 操作描述 (必填)
|
|
|
|
|
|
**响应示例**：
|
|
|
```json
|
|
|
{
|
|
|
"ok": true,
|
|
|
"operation_id": "uuid-string"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 数据模型
|
|
|
|
|
|
### 用户模型 (User)
|
|
|
|
|
|
| 字段名 | 类型 | 描述 |
|
|
|
|--------|------|------|
|
|
|
| id | int | 用户ID |
|
|
|
| username | str | 用户名，最大50字符，唯一 |
|
|
|
| email | str | 电子邮箱，最大100字符，唯一 |
|
|
|
| password_hash | str | 密码哈希，最大255字符 |
|
|
|
| full_name | str | 全名，最大100字符 |
|
|
|
| is_active | bool | 是否激活，默认True |
|
|
|
| last_login | datetime | 最后登录时间 |
|
|
|
| created_at | datetime | 创建时间 |
|
|
|
| updated_at | datetime | 更新时间 |
|
|
|
|
|
|
### 集群模型 (Cluster)
|
|
|
|
|
|
| 字段名 | 类型 | 描述 |
|
|
|
|--------|------|------|
|
|
|
| id | int | 集群ID |
|
|
|
| uuid | UUID | 集群UUID，唯一 |
|
|
|
| name | str | 集群名称，最大100字符，唯一 |
|
|
|
| type | str | 集群类型，最大50字符 |
|
|
|
| node_count | int | 节点数量，默认0 |
|
|
|
| health_status | str | 健康状态，默认"unknown"，最大20字符 |
|
|
|
| description | str | 集群描述 |
|
|
|
| config_info | JSON | 配置信息 |
|
|
|
| created_at | datetime | 创建时间 |
|
|
|
| updated_at | datetime | 更新时间 |
|
|
|
|
|
|
### 节点模型 (Node)
|
|
|
|
|
|
| 字段名 | 类型 | 描述 |
|
|
|
|--------|------|------|
|
|
|
| id | int | 节点ID |
|
|
|
| uuid | UUID | 节点UUID，唯一 |
|
|
|
| cluster_id | int | 所属集群ID |
|
|
|
| hostname | str | 主机名，最大100字符 |
|
|
|
| ip_address | INET | IP地址 |
|
|
|
| status | str | 节点状态，默认"unknown"，最大20字符 |
|
|
|
| cpu_usage | float | CPU使用率 |
|
|
|
| memory_usage | float | 内存使用率 |
|
|
|
| disk_usage | float | 磁盘使用率 |
|
|
|
| last_heartbeat | datetime | 最后心跳时间 |
|
|
|
| created_at | datetime | 创建时间 |
|
|
|
| updated_at | datetime | 更新时间 |
|
|
|
|
|
|
### Hadoop日志模型 (HadoopLog)
|
|
|
|
|
|
| 字段名 | 类型 | 描述 |
|
|
|
|--------|------|------|
|
|
|
| log_id | int | 日志ID (主键, 自增) |
|
|
|
| cluster_name | str | 集群名称 |
|
|
|
| node_host | str | 节点主机名 |
|
|
|
| title | str | 日志标题 |
|
|
|
| info | str | 日志详细信息 |
|
|
|
| log_time | datetime | 日志时间 |
|
|
|
|
|
|
### Hadoop执行日志模型 (HadoopExecLog)
|
|
|
|
|
|
| 字段名 | 类型 | 描述 |
|
|
|
|--------|------|------|
|
|
|
| id | int | 执行日志ID (主键, 自增) |
|
|
|
| from_user_id | int | 操作用户ID |
|
|
|
| cluster_name | str | 集群名称 |
|
|
|
| description | str | 执行描述 |
|
|
|
| start_time | datetime | 开始时间 |
|
|
|
| end_time | datetime | 结束时间 |
|
|
|
|
|
|
### 系统操作日志模型 (SysExecLog)
|
|
|
|
|
|
| 字段名 | 类型 | 描述 |
|
|
|
|--------|------|------|
|
|
|
| operation_id | UUID | 操作ID (主键, UUID) |
|
|
|
| user_id | int | 用户ID |
|
|
|
| description | str | 操作描述 |
|
|
|
| operation_time | datetime | 操作时间 |
|
|
|
|
|
|
## 认证与授权
|
|
|
|
|
|
### 认证方式
|
|
|
|
|
|
- **JWT Token**: 使用JSON Web Token进行认证
|
|
|
- **登录接口**: `/api/v1/login` 获取访问令牌和刷新令牌
|
|
|
- **刷新令牌**: `/api/v1/refresh` 用于刷新访问令牌
|
|
|
- **登出接口**: `/api/v1/logout` 使令牌失效
|
|
|
|
|
|
### 授权角色
|
|
|
|
|
|
- **admin**: 管理员，拥有所有权限
|
|
|
- **operator**: 操作员，拥有操作权限
|
|
|
- **observer**: 查看员，只有查看权限
|
|
|
|
|
|
## 错误处理
|
|
|
|
|
|
### 错误响应格式
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"detail": "错误描述"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 常见错误码
|
|
|
|
|
|
| 状态码 | 描述 |
|
|
|
|--------|------|
|
|
|
| 400 | 请求错误 |
|
|
|
| 401 | 未授权 |
|
|
|
| 403 | 禁止访问 |
|
|
|
| 404 | 资源不存在 |
|
|
|
| 500 | 服务器错误 |
|
|
|
|
|
|
## 开发与部署
|
|
|
|
|
|
### 开发环境
|
|
|
|
|
|
```bash
|
|
|
# 安装依赖
|
|
|
pip install -r requirements.txt
|
|
|
|
|
|
# 启动开发服务器
|
|
|
python -m uvicorn app.main:app --reload
|
|
|
```
|
|
|
|
|
|
### 生产环境
|
|
|
|
|
|
```bash
|
|
|
# 安装依赖
|
|
|
pip install -r requirements.txt
|
|
|
|
|
|
# 启动生产服务器
|
|
|
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
|
|
|
```
|
|
|
|
|
|
## 监控与维护
|
|
|
|
|
|
### 日志
|
|
|
|
|
|
- 应用日志：由FastAPI内置日志系统记录
|
|
|
- Hadoop日志：通过`hadoop_logs`模块收集和分析
|
|
|
- 执行日志：通过`exec_logs`模块记录操作执行情况
|
|
|
|
|
|
### 指标
|
|
|
|
|
|
- 系统指标：CPU、内存、磁盘使用情况
|
|
|
- 服务指标：请求数、响应时间、错误率
|
|
|
- Hadoop指标：集群状态、节点状态、作业状态
|
|
|
|
|
|
## 版本历史
|
|
|
|
|
|
| 版本 | 日期 | 描述 |
|
|
|
|------|------|------|
|
|
|
| v1 | 2025-12-16 | 初始版本 |
|
|
|
|
|
|
## 联系方式
|
|
|
|
|
|
- 开发团队：Hadoop故障检测团队
|
|
|
- 邮箱：support@hadoop-fault-detect.example.com
|
|
|
- 文档：http://localhost:8000/docs
|
|
|
- 红文档：http://localhost:8000/redoc
|
|
|
|
|
|
## 许可证
|
|
|
|
|
|
MIT License
|
