Compare commits

..

No commits in common. 'main' and 'develop' have entirely different histories.

Binary file not shown.

Before

Width:  |  Height:  |  Size: 46 KiB

@ -1,51 +1,29 @@
@startuml
title 核心业务流程时序图 (Updated)
title 日志诊断与自动修复流程
actor User
actor Admin
participant Frontend as FE
participant "FastAPI Auth" as Auth
participant "FastAPI Diagnosis" as Diag
participant "Agents (DA/PA/RA)" as Agents
database PostgreSQL as DB
participant FastAPI as API
participant Flume
database MySQL as DB
queue Redis
participant LLM
participant "Hadoop Cluster" as Cluster
== 用户注册与审批 ==
User -> FE : 提交注册信息
FE -> Auth : POST /api/auth/register
Auth -> DB : 写入用户 (status=pending)
Admin -> FE : 查看审批队列
FE -> Auth : GET /api/auth/pending_users
Auth -> DB : 查询
Admin -> FE : 批准注册
FE -> Auth : POST /api/auth/approve/{uid}
Auth -> DB : 更新用户 (status=active)
User -> FE : 登录 (正确/错误凭据)
FE -> Auth : POST /api/auth/login
Auth -> DB : 校验
Auth -> FE : 返回 JWT / 错误提示
Flume -> API : 推送结构化日志
API -> DB : 写入 fault_record
FE -> API : 查询 /api/logs/query
API -> FE : 返回日志列表
== 故障诊断与自动修复 ==
Cluster -> Diag : 推送日志 (Flume/SSH)
Diag -> DB : 记录 Fault (status=detected)
User -> FE : 点击 "AI 诊断"
FE -> Diag : POST /api/diagnosis/trigger
Diag -> Agents : 调用 DiagnosisAgent
Agents -> LLM : 分析日志上下文
LLM -> Agents : 返回根因与建议 (FixCommand)
Agents -> Diag : 诊断结果 (Risk Level)
Diag -> DB : 更新 Fault (status=analyzing)
Diag -> FE : WebSocket 推送报告
API -> LLM : call_llm_diagnose(logs)
LLM --> API : 返回 FixCommand(JSON)
API -> DB : 写入 exec_log
API -> Redis : 缓存/发布修复任务
API -> FE : WebSocket 推送诊断结果
User -> FE : 确认执行修复 (High risk needs approval)
FE -> Diag : POST /api/repair/execute
Diag -> Agents : 调用 PolicyAgent (评估风险)
Agents -> Agents : 调用 RepairAgent
Agents -> Cluster : SSH 执行修复脚本
Cluster -> Agents : 返回 stdout/stderr
Agents -> Diag : 修复完成
Diag -> DB : 记录 ExecLog & 更新 Fault (status=resolved/failed)
Diag -> FE : 推送最终结果
FE -> API : /api/repair/execute
API -> "修复脚本" : 执行Shell/Hadoop命令
"修复脚本" -> API : stdout/stderr
API -> DB : 更新 exec_log
API -> FE : 返回执行结果
@enduml

Binary file not shown.

Before

Width:  |  Height:  |  Size: 36 KiB

@ -1,52 +1,36 @@
@startuml
title 故障检测系统总体架构 (Aligned with Backend)
title 故障检测系统总体架构
node "Hadoop Cluster" {
[NameNode]
[ResourceManager]
[DataNode / NodeManager] as Node
[DataNode] as DN1
[DataNode] as DN2
}
cloud "Log & Metrics Collection" {
[Flume Agent] as Flume
[SSH Probe Service] as Probe
Flume --> Node : 采集 Hadoop 日志
Probe --> Node : 采集系统指标 (CPU/Mem/Disk)
}
cloud "Flume Agents" as Flume
Flume --> DN1 : 采集HDFS/YARN日志
Flume --> DN2 : 采集HDFS/YARN日志
package "Backend Service (FastAPI)" {
component "Auth Router" as Auth
component "Cluster/Node Router" as ClusterSvc
component "Fault/Log Router" as FaultSvc
component "AI/Chat Router" as ChatSvc
component "Orchestrator" as Orchestrator
component "DiagnosisAgent" as DA
component "PolicyAgent" as PA
component "RepairAgent" as RA
Auth --> [PostgreSQL] : users
ClusterSvc --> [PostgreSQL] : clusters, nodes
FaultSvc --> [PostgreSQL] : fault_records, hadoop_exec_logs
ChatSvc --> [PostgreSQL] : chat_sessions, chat_messages
Orchestrator --> DA
Orchestrator --> PA
Orchestrator --> RA
DA --> [LLM Service] : LangChain / OpenAI
RA --> [Hadoop Cluster] : SSH (Paramiko)
}
component "FastAPI Service" as API
database "PostgreSQL" as DB
queue "Redis" as Cache
API --> DB : 写入/查询故障记录
API --> Cache : 状态缓存/队列
API --> "LLM Diagnose" : 调用大模型\n返回FixCommand
package "Frontend (Vue 3)" {
component "Dashboard" as Dash
component "Diagnosis Chat" as DiagUI
component "Admin UI" as Admin
}
component "Agent Orchestrator" as Orchestrator
component "Diagnosis Agent" as DA
component "Repair Agent" as RA
component "Policy Agent" as PA
API --> Orchestrator : 触发诊断/修复流程
Orchestrator --> DA : 传递结构化日志
Orchestrator --> PA : 风险评估与审批策略
Orchestrator --> RA : 下发修复命令
DA --> "LLM Diagnose" : 调用LLM分析
RA --> Cluster : SSH/命令执行
Dash --> ClusterSvc
DiagUI --> ChatSvc
Admin --> Auth
component "Frontend Web (Vue/React + ECharts)" as FE
FE --> API : /api/cluster/status\n/api/logs/query\n/api/diagnosis/result\n/api/repair/execute
API --> FE : WebSocket推送状态/诊断结果
Orchestrator ..> [Redis] : 任务状态与实时推送
@enduml

Binary file not shown.

Before

Width:  |  Height:  |  Size: 10 KiB

@ -1,36 +1,45 @@
@startuml
title 故障生命周期状态机与修复流程 (Updated)
title 日志诊断与自动修复 - 活动图
skinparam defaultFontName Microsoft YaHei
(*) --> "Detected (故障发现)" : 系统采集到异常日志/指标
start
:Flume采集日志;
:FastAPI接收并解析日志;
:保存 FaultRecord 到 MySQL;
partition "AI 诊断阶段" {
"Detected (故障发现)" --> "Analyzing (正在分析)" : 触发 AI 诊断 (DiagnosisAgent)
"Analyzing (正在分析)" --> "Diagnosed (已生成建议)" : LLM 分析完成并生成 FixCommand
partition "用户/系统触发" {
if (是否需要诊断?) then (是)
:聚合相关日志;
:构造 Prompt;
:调用 LLM 诊断;
:生成 FixCommand(JSON);
:安全校验(禁止高危命令);
else (否)
:等待新日志/用户请求;
stop
endif
}
partition "策略评估与修复阶段" {
"Diagnosed (已生成建议)" --> "Risk Assessment (PolicyAgent)"
if "风险等级" then
-->[High] "Pending Approval (待审批)"
-->[Approved] "Repairing (修复中)"
else
-->[Low/Medium] "Repairing (修复中)"
if (风险等级 == high?) then (是)
:前端弹窗请求人工确认;
if (用户确认执行?) then (是)
:继续执行修复;
else (否)
:记录并通知未执行;
stop
endif
"Repairing (修复中)" --> "Executing (RepairAgent)"
"Executing (RepairAgent)" --> "Post-Check (修复后校验)"
}
endif
"Post-Check (修复后校验)" --> if "是否修复成功?" then
-->[Yes] "Resolved (已解决)"
--> (*)
else
-->[No] "Failed (修复失败)"
--> "Manual Intervention (需人工介入)"
--> (*)
:修复前预检查(配置/路径/权限);
if (预检查通过?) then (是)
:执行修复脚本;
:采集stdout/stderr;
:保存 ExecLog 到 MySQL;
:更新状态到 Redis 并推送 WebSocket;
else (否)
:记录失败原因;
endif
:返回结果给前端;
stop
@enduml

Binary file not shown.

Before

Width:  |  Height:  |  Size: 22 KiB

@ -1,42 +1,38 @@
@startuml
title 故障检测系统用例图 (Updated)
title 故障检测系统 - 用例图
skinparam defaultFontName Microsoft YaHei
actor "访客" as Guest
actor "管理员" as Admin
actor "运维人员/操作员" as Operator
actor "观察员" as Observer
actor 运维工程师 as Ops
actor 前端用户 as User
actor 测试工程师 as QA
rectangle "故障检测与诊断系统" {
(注册与登录) as UC_Auth
(注册审批) as UC_Approve
(集群管理) as UC_Cluster
(实时监控) as UC_Monitor
(日志检索) as UC_Logs
(AI 故障诊断) as UC_Diag
(自动/手动修复) as UC_Repair
(操作审计) as UC_Audit
(用户权限管理) as UC_UserMgmt
rectangle "故障检测系统" {
usecase "查看集群状态" as UC_Status
usecase "查询日志" as UC_QueryLogs
usecase "发起故障诊断" as UC_Diagnose
usecase "执行自动修复" as UC_Repair
usecase "查看执行日志" as UC_ExecLogs
usecase "配置Flume收集" as UC_ConfigFlume
usecase "配置告警阈值" as UC_ConfigAlert
usecase "导出故障与诊断报告" as UC_Export
usecase "生成FixCommand" as UC_FixCmd
usecase "命令安全校验" as UC_SafeCheck
Guest --> UC_Auth
Admin --> UC_Approve
Admin --> UC_UserMgmt
Admin --> UC_Audit
Admin --> UC_Cluster
Operator --> UC_Monitor
Operator --> UC_Logs
Operator --> UC_Diag
Operator --> UC_Repair
Operator --> UC_Cluster
Observer --> UC_Monitor
Observer --> UC_Logs
UC_Diag ..> (LLM 根因分析) : <<include>>
UC_Repair ..> (风险评估审批) : <<include>>
}
User --> UC_Status
User --> UC_QueryLogs
User --> UC_Diagnose
User --> UC_Repair
User --> UC_ExecLogs
Ops --> UC_ConfigFlume
Ops --> UC_ConfigAlert
Ops --> UC_Repair
Ops --> UC_Status
QA --> UC_QueryLogs
QA --> UC_Export
UC_Diagnose --> UC_FixCmd : <<include>>
UC_Repair --> UC_SafeCheck : <<include>>
}
@enduml

Binary file not shown.

Before

Width:  |  Height:  |  Size: 54 KiB

@ -1,112 +1,130 @@
@startuml
title 故障检测与自动修复 - 领域模型类图 (Updated from Code)
title 故障检测与自动修复 - 类图
skinparam backgroundColor #FFFFFF
skinparam defaultFontName Microsoft YaHei
skinparam classAttributeIconSize 0
package "Models (SQLAlchemy)" {
class User {
+id : int <<PK>>
+username : string
+email : string
+password_hash : string
+full_name : string
+is_active : bool
+last_login : TIMESTAMP
+created_at : TIMESTAMP
}
class Cluster {
+id : int <<PK>>
+uuid : string <<Unique>>
+name : string
+type : string
+node_count : int
+health_status : string
+cpu_avg : float
+memory_avg : float
+namenode_ip : INET
+rm_ip : INET
+config_info : JSONB
+to_dict() : dict
}
class Node {
+id : int <<PK>>
+uuid : string <<Unique>>
+cluster_id : int <<FK>>
+hostname : string
+ip_address : INET
+ssh_user : string
+ssh_password : string
+status : string
+cpu_usage : float
+memory_usage : float
+disk_usage : float
+last_heartbeat : TIMESTAMP
}
class FaultRecord {
+id : int <<PK>>
+fault_id : string <<Unique>>
+cluster_id : int <<FK>>
+fault_type : string
+fault_level : string
+title : string
+description : string
+affected_nodes : JSONB
+affected_clusters : JSONB
+root_cause : string
+repair_suggestion : string
+status : string
+reporter : string
+to_dict() : dict
}
class HadoopExecLog {
+id : int <<PK>>
+from_user_id : int <<FK>>
+cluster_name : string
+description : text
+start_time : TIMESTAMP
+end_time : TIMESTAMP
+to_dict() : dict
}
class ChatSession {
+id : string <<PK>> (UUID)
+user_id : int <<FK>>
+title : string
+created_at : DateTime
+messages : List<ChatMessage>
}
class ChatMessage {
+id : int <<PK>>
+session_id : string <<FK>>
+role : string (system/user/assistant/tool)
+content : text
+created_at : DateTime
}
}
package "Agents (Logic)" {
class DiagnosisAgent {
+analyze(logs) : FixCommand
}
class PolicyAgent {
+evaluate(cmd) : RiskLevel
}
class RepairAgent {
+execute(cmd) : ExecResult
}
}
User "1" -- "0..*" HadoopExecLog : executes
User "1" -- "0..*" ChatSession : owns
Cluster "1" -- "0..*" Node : contains
Cluster "1" -- "0..*" FaultRecord : has
ChatSession "1" -- "0..*" ChatMessage : has_many
class FlumeAgent {
+config : Map
+start()
+stop()
}
class LogEvent {
+timestamp : datetime
+host : string
+source : string
+level : string
+message : string
+raw : text
}
class FastAPIService {
+ingestLog(e: LogEvent)
+getClusterStatus()
+queryLogs(filter)
+diagnose(logs)
+executeRepair(cmd: FixCommand)
}
class DiagnosisService {
+callLLM(logs) : FixCommand
+validateCommand(cmd: FixCommand) : bool
}
class LLMClient {
+apiKey : string
+endpoint : string
+invoke(prompt) : string
}
class FixCommand {
+fault_type : string
+reason : string
+fix_script : string
+risk_level : RiskLevel
}
enum RiskLevel {
low
medium
high
}
class RepairExecutor {
+run(script) : ExecResult
+precheck() : bool
}
class ExecResult {
+stdout : text
+stderr : text
+exitCode : int
}
class FaultRecord {
+id : int
+fault_type : string
+reason : string
+timestamp : datetime
+node : string
}
class ExecLog {
+id : int
+record_id : int
+stdout : text
+stderr : text
+timestamp : datetime
}
class MySQLClient {
+saveFault(record: FaultRecord)
+saveExecLog(log: ExecLog)
+queryLogs(filter)
}
class RedisCache {
+set(key, value)
+publish(channel, msg)
+get(key)
}
class ClusterStatus {
+nodesUp : int
+nodesDown : int
+hdfsUsage : float
+yarnActiveApps : int
}
class FrontendWeb {
+viewStatus()
+queryLogs()
+requestDiagnosis()
+executeRepair()
}
FlumeAgent --> FastAPIService : push(LogEvent)
FastAPIService --> DiagnosisService : diagnose(logs)
DiagnosisService --> LLMClient : call_llm_diagnose
DiagnosisService --> FixCommand : returns
FastAPIService --> RepairExecutor : execute(FixCommand)
RepairExecutor --> ExecResult : returns
FastAPIService --> MySQLClient : save FaultRecord/ExecLog
FastAPIService --> RedisCache : cache/publish status
FrontendWeb --> FastAPIService : REST/WebSocket
FastAPIService --> ClusterStatus : compose
MySQLClient --> FaultRecord
MySQLClient --> ExecLog
FixCommand --> RiskLevel
note right of FixCommand
JSON 示例:
{
fault_type: "DataNode故障",
reason: "磁盘占满",
fix_script: "ssh dn 'clean_temp.sh'",
risk_level: "medium"
}
end note
@enduml

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

@ -1,35 +1,25 @@
@startuml
title 故障检测系统部署拓扑 (Updated)
title 部署拓扑
node "Hadoop Cluster Node" {
component "Hadoop Components" as HC
component "Flume Agent" as Flume
HC - [SSH]
}
node "On-Prem / Cloud" {
node "Hadoop Cluster" {
[NameNode]
[DataNodes...]
}
node "Management Server" {
package "Backend (Docker Container)" {
[FastAPI Service] as API
[Celery Workers] as Workers
node "Logging Layer" {
[Flume Agents]
}
package "Frontend (Docker Container)" {
[Nginx / Vue App] as Web
node "Application Layer" {
[FastAPI]
[LLM Connector]
[Nginx for Frontend]
}
database "PostgreSQL" as DB
queue "Redis" as Redis
}
cloud "AI Platform" {
[OpenAI API / LangChain] as LLM
node "Storage/Caching" {
[MySQL]
[Redis]
}
}
Web --> API : HTTP/WebSocket
API --> DB : Persistence
API --> Redis : Task Queue
API --> LLM : AI Analysis
API --> HC : SSH Execution
Flume --> API : Log Streaming
@enduml

Binary file not shown.

@ -1,65 +0,0 @@
# 基于 Hadoop 的故障检测与智能诊断项目 - 测试报告
## 修订记录
| 版本号 | 修订日期 | 修订内容 | 修订人 |
| :--- | :--- | :--- | :--- |
| v1.0.0 | 2026-01-10 | 初始测试报告框架创建 | AI Assistant |
---
## 1. 测试概述
### 1.1 测试目的
验证系统在 Hadoop 集群管理、指标采集、日志检索及 AI 诊断功能上的正确性、稳定性和响应速度,确保满足《需求规格说明书》中的定义。
### 1.2 测试范围
- **功能测试**: 集群注册、SSH 校验、日志同步、AI SSE 流式对话。
- **性能测试**: 大规模日志检索响应时间、多并发指标采集压力。
## 2. 测试环境
| 类别 | 配置要求 |
| :--- | :--- |
| **硬件** | 8 vCPU, 16GB RAM (测试服务器) |
| **软件** | Docker, PostgreSQL 14, Python 3.10 |
| **集群环境** | Hadoop 3.1.3 (1 NameNode, 5 DataNodes) |
## 3. 测试用例
| 用例编号 | 功能模块 | 测试点 | 预期结果 | 状态 |
| :--- | :--- | :--- | :--- | :--- |
| TC-01 | 集群管理 | 输入合法的 SSH 信息注册集群 | 注册成功并自动发现所有节点 | [待测试] |
| TC-02 | 日志采集 | 模拟节点产生 ERROR 日志 | 数据库 5 秒内出现对应增量日志 | [待测试] |
| TC-03 | AI 诊断 | 询问集群负载情况 | AI 正确调用指标工具并给出分析建议 | [待测试] |
## 4. 测试结果
### 4.1 通过/失败统计
- **总用例数**: 0
- **通过数**: 0
- **失败数**: 0
- **跳过数**: 0
- **通过率**: 0%
## 5. 缺陷分析
### 5.1 严重等级分布
- **致命 (Blocker)**: 0
- **严重 (Critical)**: 0
- **一般 (Major)**: 0
- **次要 (Minor)**: 0
## 6. 测试结论
### 6.1 质量评估
[在此填写本次测试阶段的总体质量评价,例如:系统核心流程已打通,但 AI 诊断在极端日志量下存在响应延迟。]
## 7. 附录
### 7.1 测试日志
- 后端服务日志: `backend/logs/test_run.log`
- 采集器性能统计: `docs/metrics_report.csv`
### 7.2 截图
[占位符:插入关键功能运行截图]

Binary file not shown.

@ -2,186 +2,75 @@
## 1. 引言
### 1.1 文档目的
本说明书详细定义了“Hadoop 故障检测与智能诊断系统”的功能性与非功能性需求。旨在指导系统的设计与开发为测试人员提供验收标准并作为项目评审的权威依据。适用人群包括后端开发工程师、前端开发工程师、QA 测试工程师及项目管理者
### 1.1 目的
本说明书详细定义了“Hadoop 故障检测与智能诊断系统”的功能性与非功能性需求,作为系统设计、开发、测试及验收的权威依据
### 1.2 项目背景
随着分布式集群规模的扩大Hadoop 集群的日常运维与故障排查变得日益复杂。传统的人工排查方式效率低下且依赖专家经验。本项目旨在通过自动化指标采集、实时日志增量分析以及集成 AI 智能体技术,解决集群故障定位难、修复慢的业务痛点。
### 1.3 定义与缩写
- **API**: 应用程序编程接口
- **SSH**: 安全外壳协议,用于远程控制
- **SSE**: 服务器发送事件,用于流式数据传输
- **LLM**: 大语言模型,本项目特指 OpenAI GPT 模型
- **Agent**: 具有自主决策和工具调用能力的智能体
### 1.4 参考资料
- 《Apache Hadoop 官方文档》
- 《FastAPI 异步 Web 框架规范》
- 《PostgreSQL 数据库性能优化指南》
### 1.5 版本历史
| 版本号 | 修订日期 | 修订人 | 修订内容 |
| :--- | :--- | :--- | :--- |
| v1.0.0 | 2026-01-10 | AI Assistant | 初始版本创建 |
| v1.1.0 | 2026-01-10 | AI Assistant | 全面优化:重组 8 大核心模块,量化非功能需求,完善接口与数据规范 |
---
### 1.2 范围
本系统包含:基于 FastAPI 的异步后端、基于 SSH 的分布式日志与指标采集引擎、基于 OpenAI 的 AI 诊断智能体、以及配套的 PostgreSQL 数据库模型。
## 2. 总体描述
### 2.1 产品愿景
打造一个集监控、预警、诊断、修复于一体的智能化 Hadoop 运维平台。通过 AI 赋能,实现从“被动告警”到“主动诊断”的跨越
### 2.2 用户特征
| 角色 | 技能水平 | 使用场景 |
| :--- | :--- | :--- |
| **管理员** | 高 | 系统全局配置、用户权限分配、集群接入审核 |
| **运维人员** | 中 | 执行日常诊断任务、查看性能趋势、下发修复指令 |
| **审计员** | 低 | 查看系统操作日志、导出合规报表 |
### 2.3 运行环境
#### 硬件环境
- **服务器**: CPU 2核+, 内存 4GB+, 磁盘 20GB+ (SSD 推荐)
- **网络**: 后端服务器需具备访问 Hadoop 集群所有节点的 SSH 权限
#### 软件环境
- **操作系统**: Linux (Ubuntu 20.04+ / CentOS 7.9+)
- **数据库**: PostgreSQL 13.0+
- **后端技术栈**: Python 3.9+, FastAPI, SQLAlchemy, LangChain
- **前端技术栈**: Node.js 18+, Vue 3.4+, Element Plus
- **浏览器**: Chrome 90+, Firefox 88+, Edge 91+
### 2.1 软件架构
系统采用前后端分离架构,后端通过异步任务驱动采集逻辑,利用智能体技术封装运维经验,支持水平扩展以管理多个 Hadoop 集群。
### 2.4 设计与实现约束
- **技术栈约束**: 必须使用异步驱动Asyncio以支持高并发采集。
- **安全性约束**: 敏感配置(如 SSH 密码、API Key必须加密存储符合数据隐私规范。
- **扩展性约束**: 采集引擎必须支持多集群并行接入。
---
### 2.2 用户角色
- **管理员**: 拥有所有集群的管理权限,可增删改查用户及全局配置。
- **运维人员**: 可执行诊断任务、配置采集器、下发修复指令。
- **审计员**: 仅可查看执行日志与审计报表。
## 3. 功能需求
### 3.1 功能模块划分
系统划分为五个核心模块认证授权、集群管理、自动化采集、AI 智能诊断、运维审计。
### 3.2 单个功能详细说明
#### 3.2.1 集群注册 (F-01-01)
- **前置条件**: 用户具有管理员或运维权限。
- **操作流程**:
1. 输入集群名称及 NameNode IP 地址。
2. 提供 SSH 认证凭据(用户名/密码或私钥)。
3. 系统触发自动校验逻辑。
- **输入**: 集群元数据 JSON。
- **输出**: 注册成功/失败状态及校验报告。
- **异常处理**: 若 SSH 连接超时(默认 10s提示用户检查防火墙或凭据。
#### 3.2.2 AI 流式诊断 (F-04-01)
- **前置条件**: 已接入至少一个健康的 Hadoop 集群。
- **操作流程**:
1. 用户在聊天框输入故障现象如“HDFS 写入速度慢”)。
2. 后端建立 SSE 连接。
3. AI 自动调用工具获取节点指标和日志。
- **输入**: 用户自然语言指令。
- **输出**: Markdown 格式的流式分析结果。
### 3.3 用例图与流程图
```mermaid
graph LR
User((运维人员))
User -->|注册| Cluster[集群管理]
User -->|查询| Log[日志检索]
User -->|咨询| AI[AI 智能诊断]
AI -->|调用工具| SSH[远程 SSH 执行]
Log -->|读取| DB[(PostgreSQL)]
```
---
## 4. 非功能需求
### 4.1 性能需求
- **响应时间**: 基础数据查询 API 响应时间 ≤ 500msAI 首字输出延迟 ≤ 2s。
- **并发量**: 支持 100 个并发采集任务同时进行。
- **吞吐量**: 日志增量写入速度支持 5000 条/秒。
### 4.2 可靠性需求
- **MTBF**: 平均无故障运行时间 ≥ 2000 小时。
- **恢复时间**: 系统进程崩溃后,由 Supervisor 或 Docker 自动拉起,恢复时间 ≤ 30s。
- **数据备份**: PostgreSQL 每日凌晨 3:00 执行增量备份。
### 4.3 易用性需求
- **操作复杂度**: 运维人员通过 3 次点击即可完成一次深度故障诊断。
- **界面语言**: 全中文界面,支持后续多语言扩展。
### 4.4 安全性需求
- **认证**: 全站采用 JWT 动态令牌,有效期 24 小时。
- **加密**: 用户密码采用 Bcrypt 强哈希算法;传输过程支持 HTTPS。
### 4.5 兼容性需求
- **Hadoop 版本**: 兼容 Apache Hadoop 2.7.x 至 3.3.x 版本。
- **终端适配**: 支持 1920x1080 及以上分辨率的桌面端访问。
---
## 5. 数据需求
### 5.1 数据结构 (核心表)
- **clusters**: id (PK), uuid, name, namenode_ip, ssh_user, ssh_password_encrypted.
- **hadoop_logs**: log_id (PK), cluster_id (FK), node_host, level, info, log_time.
- **node_metrics**: id (PK), node_id, cpu_usage, memory_usage, created_at.
### 5.2 数据字典
| 字段名 | 类型 | 取值范围 | 说明 |
| :--- | :--- | :--- | :--- |
| `health_status` | varchar | {healthy, warning, error, unknown} | 集群健康状态 |
| `level` | varchar | {INFO, WARN, ERROR, FATAL} | 日志级别 |
### 5.3 数据流转流程
1. **采集阶段**: `SSH 采集器` -> `内存缓冲区` -> `PostgreSQL`
2. **诊断阶段**: `用户提问` -> `AI Agent` -> `调用 SQL 检索` -> `返回前端`
---
### 3.1 集群与节点管理 (Cluster & Node Management)
- **F-01-01 集群注册**: 支持通过名称、NameNode IP 注册集群。
- **F-01-02 SSH 校验**: 注册时自动测试 SSH 连接,确保后端可操控节点。
- **F-01-03 节点发现**: 自动同步集群下的所有节点DataNode, ResourceManager 等)。
## 6. 接口需求
### 3.2 自动化指标采集 (Automated Metrics Collection)
- **F-02-01 周期采集**: 默认每 60 秒采集一次各节点的 CPU 和内存占用。
- **F-02-02 趋势分析**: 提供历史指标接口,支持前端绘制负载曲线。
- **F-02-03 采集控制**: 支持手动启动或停止特定集群的采集任务。
### 6.1 用户接口
- **主界面**: 采用侧边导航栏架构,左侧为功能菜单,右侧为数据展示区。
- **AI 对话窗**: 浮动于页面右下角,支持代码块高亮显示。
### 3.3 日志管理与采集 (Log Management)
- **F-03-01 远程读取**: 支持按路径或预定义类型Hadoop/System读取远程日志。
- **F-03-02 增量采集**: 采集器自动维持 SSH 链接,实时将日志增量写入数据库。
- **F-03-03 日志检索**: 提供多维度(级别、内容、节点、时间)的高性能检索。
### 6.2 内部接口
- **采集引擎接口**: `InternalWorker.start_collection(cluster_id)`
- **诊断服务接口**: `AIDiagnostic.run(context_json)`
### 3.4 AI 故障诊断 (AI-Powered Diagnosis)
- **F-04-01 SSE 流式对话**: 支持基于 OpenAI 的流式输出,提升用户交互体验。
- **F-04-02 工具链调用**: AI 可自动调用“读取日志”、“执行命令”等工具收集证据。
- **F-04-03 报告生成**: 自动根据诊断上下文生成 MD 格式的分析报告。
### 6.3 外部接口
- **RESTful API**: 遵循 OpenAPI 3.0 标准
- **认证方式**: Header 携带 `Authorization: Bearer <token>`
### 3.5 运维审计 (Operations Auditing)
- **F-05-01 命令记录**: 记录所有通过平台执行的远程 shell 命令及其退出码。
- **F-05-02 审计追踪**: 记录关键配置修改及登录行为。
---
## 4. 接口规范 (API Specification)
## 7. 验收标准
### 4.1 认证接口
- `POST /api/v1/auth/login`: 登录并返回 JWT。
- `POST /api/v1/auth/register`: 注册新账户。
### 7.1 功能验收
- **用例**: 注册一个不存在的 IP
- **预期结果**: 系统在 15s 内返回 `Connection Timeout` 错误,且不写入数据库
### 4.2 集群接口
- `GET /api/v1/clusters`: 获取集群列表。
- `POST /api/v1/clusters/verify`: 验证 SSH 连接。
### 7.2 性能验收
- **压测**: 使用 JMeter 模拟 50 个并发用户请求 `/api/v1/logs`。
- **预期结果**: 95% 的请求响应时间小于 800ms系统无 OOM 报错
### 4.3 日志接口
- `GET /api/v1/hadoop/logs`: 分页检索持久化日志。
- `GET /api/v1/hadoop/logs/{node}/{type}`: 读取节点实时日志。
---
### 4.4 AI 接口
- `POST /api/v1/ai/chat`: 发起诊断对话SSE
## 8. 附录
## 5. 数据库设计要点
### 8.1 术语表
- **Bcrypt**: 一种跨平台的自适应哈希算法,用于存储密码。
- **asyncpg**: 高性能的异步 PostgreSQL 驱动。
- **用户表 (users)**: 存储哈希后的密码及角色。
- **集群表 (clusters)**: 存储 UUID、管理 IP 及配置 JSON。
- **日志表 (hadoop_logs)**: 采用分表或索引优化,存储大规模结构化日志。
- **指标表 (node_metrics)**: 动态 Schema存储时序监控数据。
### 8.2 图表集
- 系统架构图、ER 实体关系图(详见项目源码 `doc/diagrams/`)。
## 6. 非功能需求
### 8.3 需求变更记录
| 变更日期 | 变更项 | 变更原因 | 状态 |
| :--- | :--- | :--- | :--- |
| 2026-01-10 | 增加 SSE 支持 | 提升 AI 交互体验 | 已完成 |
- **可用性**: 核心采集服务具备断线重连机制。
- **性能**: API 接口平均响应时间 < 500ms(不含 AI 调用)。
- **安全性**: 所有接口必须经过 JWT 校验(除公开健康检查外)。
- **兼容性**: 支持 Hadoop 2.x/3.x 版本的标准日志路径。

Loading…
Cancel
Save