doc/project/diagrams/时序图.puml

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

doc/project/diagrams/架构图.puml

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

doc/project/diagrams/活动图.puml

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

doc/project/diagrams/用例图.puml

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

doc/project/diagrams/类图.puml

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

doc/project/diagrams/部署图.puml

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

doc/project/测试报告.md

@@ -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 截图
-[占位符：插入关键功能运行截图]

doc/project/需求规格说明书.md

@@ -2,186 +2,75 @@
 
 ## 1. 引言
 
-### 1.1 文档目的
+### 1.1 目的
-本说明书详细定义了“Hadoop 故障检测与智能诊断系统”的功能性与非功能性需求。旨在指导系统的设计与开发，为测试人员提供验收标准，并作为项目评审的权威依据。适用人群包括后端开发工程师、前端开发工程师、QA 测试工程师及项目管理者。
+本说明书详细定义了“Hadoop 故障检测与智能诊断系统”的功能性与非功能性需求，作为系统设计、开发、测试及验收的权威依据。
 
-### 1.2 项目背景
+### 1.2 范围
-随着分布式集群规模的扩大，Hadoop 集群的日常运维与故障排查变得日益复杂。传统的人工排查方式效率低下且依赖专家经验。本项目旨在通过自动化指标采集、实时日志增量分析以及集成 AI 智能体技术，解决集群故障定位难、修复慢的业务痛点。
+本系统包含：基于 FastAPI 的异步后端、基于 SSH 的分布式日志与指标采集引擎、基于 OpenAI 的 AI 诊断智能体、以及配套的 PostgreSQL 数据库模型。
-
-### 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 大核心模块，量化非功能需求，完善接口与数据规范 |
-
----
 
 ## 2. 总体描述
 
-### 2.1 产品愿景
+### 2.1 软件架构
-打造一个集监控、预警、诊断、修复于一体的智能化 Hadoop 运维平台。通过 AI 赋能，实现从“被动告警”到“主动诊断”的跨越
+系统采用前后端分离架构，后端通过异步任务驱动采集逻辑，利用智能体技术封装运维经验，支持水平扩展以管理多个 Hadoop 集群。
-
-### 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.4 设计与实现约束
+### 2.2 用户角色
-- **技术栈约束**: 必须使用异步驱动（Asyncio）以支持高并发采集。
+- **管理员**: 拥有所有集群的管理权限，可增删改查用户及全局配置。
-- **安全性约束**: 敏感配置（如 SSH 密码、API Key）必须加密存储，符合数据隐私规范。
+- **运维人员**: 可执行诊断任务、配置采集器、下发修复指令。
-- **扩展性约束**: 采集引擎必须支持多集群并行接入。
+- **审计员**: 仅可查看执行日志与审计报表。
-
----
 
 ## 3. 功能需求
 
-### 3.1 功能模块划分
+### 3.1 集群与节点管理 (Cluster & Node Management)
-系统划分为五个核心模块：认证授权、集群管理、自动化采集、AI 智能诊断、运维审计。
+- **F-01-01 集群注册**: 支持通过名称、NameNode IP 注册集群。
-
+- **F-01-02 SSH 校验**: 注册时自动测试 SSH 连接，确保后端可操控节点。
-### 3.2 单个功能详细说明
+- **F-01-03 节点发现**: 自动同步集群下的所有节点（DataNode, ResourceManager 等）。
-
-#### 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 响应时间 ≤ 500ms；AI 首字输出延迟 ≤ 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 检索` -> `返回前端`。
-
----
 
-## 6. 接口需求
+### 3.2 自动化指标采集 (Automated Metrics Collection)
+- **F-02-01 周期采集**: 默认每 60 秒采集一次各节点的 CPU 和内存占用。
+- **F-02-02 趋势分析**: 提供历史指标接口，支持前端绘制负载曲线。
+- **F-02-03 采集控制**: 支持手动启动或停止特定集群的采集任务。
 
-### 6.1 用户接口
+### 3.3 日志管理与采集 (Log Management)
-- **主界面**: 采用侧边导航栏架构，左侧为功能菜单，右侧为数据展示区。
+- **F-03-01 远程读取**: 支持按路径或预定义类型（Hadoop/System）读取远程日志。
-- **AI 对话窗**: 浮动于页面右下角，支持代码块高亮显示。
+- **F-03-02 增量采集**: 采集器自动维持 SSH 链接，实时将日志增量写入数据库。
+- **F-03-03 日志检索**: 提供多维度（级别、内容、节点、时间）的高性能检索。
 
-### 6.2 内部接口
+### 3.4 AI 故障诊断 (AI-Powered Diagnosis)
-- **采集引擎接口**: `InternalWorker.start_collection(cluster_id)`。
+- **F-04-01 SSE 流式对话**: 支持基于 OpenAI 的流式输出，提升用户交互体验。
-- **诊断服务接口**: `AIDiagnostic.run(context_json)`。
+- **F-04-02 工具链调用**: AI 可自动调用“读取日志”、“执行命令”等工具收集证据。
+- **F-04-03 报告生成**: 自动根据诊断上下文生成 MD 格式的分析报告。
 
-### 6.3 外部接口
+### 3.5 运维审计 (Operations Auditing)
-- **RESTful API**: 遵循 OpenAPI 3.0 标准。
+- **F-05-01 命令记录**: 记录所有通过平台执行的远程 shell 命令及其退出码。
-- **认证方式**: Header 携带 `Authorization: Bearer <token>`。
+- **F-05-02 审计追踪**: 记录关键配置修改及登录行为。
 
----
+## 4. 接口规范 (API Specification)
 
-## 7. 验收标准
+### 4.1 认证接口
+- `POST /api/v1/auth/login`: 登录并返回 JWT。
+- `POST /api/v1/auth/register`: 注册新账户。
 
-### 7.1 功能验收
+### 4.2 集群接口
-- **用例**: 注册一个不存在的 IP。
+- `GET /api/v1/clusters`: 获取集群列表。
-- **预期结果**: 系统在 15s 内返回 `Connection Timeout` 错误，且不写入数据库。
+- `POST /api/v1/clusters/verify`: 验证 SSH 连接。
 
-### 7.2 性能验收
+### 4.3 日志接口
-- **压测**: 使用 JMeter 模拟 50 个并发用户请求 `/api/v1/logs`。
+- `GET /api/v1/hadoop/logs`: 分页检索持久化日志。
-- **预期结果**: 95% 的请求响应时间小于 800ms，系统无 OOM 报错。
+- `GET /api/v1/hadoop/logs/{node}/{type}`: 读取节点实时日志。
 
----
+### 4.4 AI 接口
+- `POST /api/v1/ai/chat`: 发起诊断对话（SSE）。
 
-## 8. 附录
+## 5. 数据库设计要点
 
-### 8.1 术语表
+- **用户表 (users)**: 存储哈希后的密码及角色。
-- **Bcrypt**: 一种跨平台的自适应哈希算法，用于存储密码。
+- **集群表 (clusters)**: 存储 UUID、管理 IP 及配置 JSON。
-- **asyncpg**: 高性能的异步 PostgreSQL 驱动。
+- **日志表 (hadoop_logs)**: 采用分表或索引优化，存储大规模结构化日志。
+- **指标表 (node_metrics)**: 动态 Schema，存储时序监控数据。
 
-### 8.2 图表集
+## 6. 非功能需求
-- 系统架构图、ER 实体关系图（详见项目源码 `doc/diagrams/`）。
 
-### 8.3 需求变更记录
+- **可用性**: 核心采集服务具备断线重连机制。
-| 变更日期 | 变更项 | 变更原因 | 状态 |
+- **性能**: API 接口平均响应时间 < 500ms（不含 AI 调用）。
-| :--- | :--- | :--- | :--- |
+- **安全性**: 所有接口必须经过 JWT 校验（除公开健康检查外）。
-| 2026-01-10 | 增加 SSE 支持 | 提升 AI 交互体验 | 已完成 |
+- **兼容性**: 支持 Hadoop 2.x/3.x 版本的标准日志路径。