需求迭代

pull/41/head
echo 5 months ago
parent c85218d7ac
commit 88f05cfb5e

@ -1,25 +1,36 @@
@startuml
title 故障检测系统总体架构
node "Hadoop Cluster" {
[NameNode]
[DataNode] as DN1
[DataNode] as DN2
}
cloud "Flume Agents" as Flume
Flume --> DN1 : 采集HDFS/YARN日志
Flume --> DN2 : 采集HDFS/YARN日志
component "FastAPI Service" as API
database "MySQL" as DB
queue "Redis" as Cache
API --> DB : 写入/查询故障记录
API --> Cache : 状态缓存/队列
API --> "LLM Diagnose" : 调用大模型\n返回FixCommand
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推送状态/诊断结果
@startuml
title 故障检测系统总体架构
node "Hadoop Cluster" {
[NameNode]
[DataNode] as DN1
[DataNode] as DN2
}
cloud "Flume Agents" as Flume
Flume --> DN1 : 采集HDFS/YARN日志
Flume --> DN2 : 采集HDFS/YARN日志
component "FastAPI Service" as API
database "PostgreSQL" as DB
queue "Redis" as Cache
API --> DB : 写入/查询故障记录
API --> Cache : 状态缓存/队列
API --> "LLM Diagnose" : 调用大模型\n返回FixCommand
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/命令执行
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推送状态/诊断结果
@enduml

@ -23,7 +23,62 @@
二、项目核心任务框架
项目核心任务共分为 4 大类、10 个模块,各模块按 “基础支撑→功能实现→落地保障” 的逻辑分层,具体框架如下:
任务类别 任务编号 具体任务模块 核心目标 衔接关系 基础环境搭建 1 Hadoop 集群部署与配置 构建项目运行的计算与存储基础集群 为任务 3日志采集、任务 4日志处理提供 Hadoop 环境支撑 2 分布式数据存储体系构建及持续性维护 搭建 “原始日志归档 + 业务数据管理” 的存储架构 为任务 3日志存储、任务 4数据查询、任务 7结果存储提供数据支撑 应用开发 3 Hadoop 日志实时采集模块开发 实现 Hadoop 集群日志的全量、实时采集 为任务 4日志处理提供原始数据输入依赖任务 1Hadoop 环境)、任务 2HDFS 存储) 4 日志传输、处理及与工具的通信接口开发 完成日志结构化处理与跨工具通信 衔接任务 3日志输入与任务 6大模型调用依赖任务 2MySQL/Redis 存储) 5 交互式 Web 应用前端开发 实现集群监控、故障管理、结果展示的可视化 依赖任务 4后端接口数据为运维人员提供操作入口 核心功能实现 6 基于大模型的故障智能诊断与分析 实现故障类型识别、原因分析、修复方案生成 依赖任务 4结构化日志输入为任务 7修复执行提供决策依据 7 故障修复指令自动化执行及结果反馈机制 打通 “诊断 - 修复 - 反馈” 闭环 依赖任务 6修复方案结果同步至任务 2MySQL 存储)与任务 5前端展示 落地保障 8 全流程系统性测试与迭代优化 验证模块兼容性与系统性能,解决潜在问题 覆盖任务 1-7为任务 9部署上线扫清障碍 9 项目部署上线及全周期运维监控体系搭建 实现从开发环境到生产环境的平稳过渡 依赖任务 8测试优化结果保障上线后系统稳定运行 10 处理结果的量化评估与持续改进 量化系统效果,驱动模块迭代优化 基于任务 7修复结果、任务 9运维数据反哺任务 4日志处理、任务 6大模型 三、各任务模块详细说明
任务类别
任务编号
具体任务模块
核心目标
衔接关系
基础环境搭建
1
Hadoop 集群部署与配置
构建项目运行的计算与存储基础集群
为任务 3日志采集、任务 4日志处理提供 Hadoop 环境支撑
2
分布式数据存储体系构建及持续性维护
搭建 “原始日志归档 + 业务数据管理” 的存储架构
为任务 3日志存储、任务 4数据查询、任务 7结果存储提供数据支撑
应用开发
3
Hadoop 日志实时采集模块开发
实现 Hadoop 集群日志的全量、实时采集
为任务 4日志处理提供原始数据输入依赖任务 1Hadoop 环境)、任务 2HDFS 存储)
4
日志传输、处理及与工具的通信接口开发
完成日志结构化处理与跨工具通信
衔接任务 3日志输入与任务 6大模型调用依赖任务 2MySQL/Redis 存储)
5
交互式 Web 应用前端开发
实现集群监控、故障管理、结果展示的可视化
依赖任务 4后端接口数据为运维人员提供操作入口
核心功能实现
6
基于大模型的故障智能诊断与分析
实现故障类型识别、原因分析、修复方案生成
依赖任务 4结构化日志输入为任务 7修复执行提供决策依据
7
故障修复指令自动化执行及结果反馈机制
打通 “诊断 - 修复 - 反馈” 闭环
依赖任务 6修复方案结果同步至任务 2MySQL 存储)与任务 5前端展示
落地保障
8
全流程系统性测试与迭代优化
验证模块兼容性与系统性能,解决潜在问题
覆盖任务 1-7为任务 9部署上线扫清障碍
9
项目部署上线及全周期运维监控体系搭建
实现从开发环境到生产环境的平稳过渡
依赖任务 8测试优化结果保障上线后系统稳定运行
10
处理结果的量化评估与持续改进
量化系统效果,驱动模块迭代优化
基于任务 7修复结果、任务 9运维数据反哺任务 4日志处理、任务 6大模型
三、各任务模块详细说明
(一)基础环境搭建类
任务 1Hadoop 集群部署与配置
? 任务定位:项目运行的基础计算支撑,提供 HDFS存储日志、YARN资源调度、MapReduce可选批量处理核心组件。
@ -42,16 +97,24 @@ c.
d. HDFS 存储配置:
? 创建日志归档目录hdfs dfs -mkdir -p /user/hadoop/log_archive设置权限hdfs dfs -chmod 755 /user/hadoop/log_archive仅允许 Flume、后端服务写入
? 配置副本策略hdfs-site.xml中设置dfs.replication=3确保日志数据高可用避免单点丢失。
e. MySQL+Redis 部署与配置:
? MySQL安装 MySQL 8.0+创建数据库hadoop_fault_db设计核心数据表如下
e. PostgreSQL+Redis 部署与配置:
? PostgreSQL安装 PostgreSQL 14+创建数据库hadoop_fault_db按项目脚本初始化表结构参见 doc/project/数据库建表脚本_postgres.sql
表名 核心字段 cluster_node 节点 ID、IP 地址、角色NameNode/DataNode、磁盘阈值、状态在线 / 离线) fault_record 故障 ID、类型、发生时间、诊断结果、修复脚本、修复状态、执行日志 operation_log 操作 ID、用户名、操作时间、操作内容、结果成功 / 失败) ? Redis安装 Redis 6.0+,配置缓存策略(集群状态数据缓存 10 分钟,故障列表数据缓存 5 分钟),避免高频查询穿透 MySQL。
表名
核心字段
cluster_node
节点 ID、IP 地址、角色NameNode/DataNode、磁盘阈值、状态在线 / 离线)
fault_record
故障 ID、类型、发生时间、诊断结果、修复脚本、修复状态、执行日志
operation_log
操作 ID、用户名、操作时间、操作内容、结果成功 / 失败)
? Redis安装 Redis 6.0+,配置缓存策略(集群状态数据缓存 10 分钟,故障列表数据缓存 5 分钟),避免高频查询穿透 PostgreSQL。
f. 存储维护:
? HDFS每周执行hdfs fsck /检查文件完整性,每月将 3 个月前的日志归档至冷存储(如低成本云存储);
? MySQL配置每日增量备份mysqldump -u root -p hadoop_fault_db > backup_$(date +%Y%m%d).sql保留 30 天备份文件;
? 权限管控MySQL 仅允许后端服务 IP 访问Redis 设置密码认证,避免数据泄露。
? 实施要点:用 Navicat 等工具管理 MySQL记录数据库账号密码与备份路径定期验证备份文件可用性。
? 必要性HDFS 解决 TB 级原始日志存储问题MySQL 解决业务数据高效查询问题,缺少任一存储均会导致系统功能断裂(如前端无法加载故障列表、日志无法归档)。
? PostgreSQL配置每日增量备份pg_dump -U postgres -d hadoop_fault_db > backup_$(date +%Y%m%d).sql保留 30 天备份文件;
? 权限管控:PostgreSQL 仅允许后端服务 IP 访问Redis 设置密码认证,避免数据泄露。
? 实施要点:用 pgAdmin 等工具管理 PostgreSQL记录数据库账号密码与备份路径定期验证备份文件可用性。
? 必要性HDFS 解决 TB 级原始日志存储问题,PostgreSQL 解决业务数据高效查询问题,缺少任一存储均会导致系统功能断裂(如前端无法加载故障列表、日志无法归档)。
(二)应用开发类
任务 3Hadoop 日志实时采集模块开发
? 任务定位:实现 Hadoop 集群日志的 “全量、实时” 采集,为后续日志处理提供原始数据来源。
@ -67,10 +130,10 @@ i.
? 实施要点:避免 Flume 进程占用过多 CPU / 内存,定期清理 Flume 日志(/var/log/flume-ng/),防止磁盘满。
? 必要性:无日志采集则后续日志处理、大模型诊断均无数据输入,系统无法感知集群故障。
任务 4日志传输、处理及与工具的通信接口开发
? 任务定位:作为系统 “数据中枢”完成日志结构化处理、跨工具Flume / 大模型 / MySQL通信衔接 “采集” 与 “诊断” 环节。
? 任务定位:作为系统 “数据中枢”完成日志结构化处理、跨工具Flume / 大模型 / PostgreSQL通信衔接 “采集” 与 “诊断” 环节。
? 核心内容:
j. 后端服务搭建(基于 FastAPI
? 项目初始化pip install fastapi uvicorn mysql-connector-python redis requests创建主程序main.py
? 项目初始化pip install fastapi uvicorn sqlalchemy asyncpg redis requests pydantic创建主程序main.py
? 接口开发:
? 日志接收接口POST /api/log/auto-upload接收 Flume 推送的日志调用preprocess_log函数提取时间戳、日志级别、组件名结构化
? 集群状态接口GET /api/cluster/status调用 Hadoop APIhdfs dfsadmin -report获取节点状态缓存至 Redis
@ -78,7 +141,7 @@ j.
k. 日志结构化处理编写preprocess_log函数用正则匹配 Hadoop 日志格式((\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) (\w+) (\w+): (.*)输出结构化字典含timestamp、log_level、component、content字段
l. 工具通信适配:
? 与 Hadoop 通信用subprocess调用 Hadoop 命令如hdfs dfs -du -h /),或通过 PyHive 连接 Hive 获取任务日志;
? 与 MySQL/Redis 通信封装数据读写函数save_fault_to_mysql、get_cluster_status_from_redis确保数据一致性。
? 与 PostgreSQL/Redis 通信封装数据读写函数save_fault_to_pg、get_cluster_status_from_redis确保数据一致性。
? 实施要点用uvicorn启动服务时配置--workers 4提高并发能力接口添加参数校验如用 Pydantic 定义LogModel避免非法数据输入。
? 必要性:原始日志格式杂乱,缺少结构化处理则大模型无法精准诊断;无通信接口则各工具无法协同,系统呈 “碎片化”。
任务 5交互式 Web 应用前端开发
@ -94,10 +157,11 @@ o.
? 实施要点用axios拦截器处理 Token 过期(自动跳转登录页),图表采用懒加载减少首屏加载时间。
? 必要性:无前端则运维人员无法直观查看集群状态与故障信息,系统缺少 “人机交互” 入口,实用性大幅降低。
(三)核心功能实现类
任务 6基于大模型的故障智能诊断与分析
任务 6基于大模型与多智能体的故障智能诊断与分析
? 任务定位:系统 “决策核心”,通过大模型分析结构化日志,实现故障类型识别、原因定位、修复方案生成。
? 核心内容:
p. 大模型选型与 API 配置:选择支持工具调用的大模型(如通义千问 Qwen-Max、Scholar ICP申请 API 密钥配置调用参数temperature=0.3,降低随机性)。
p. 大模型选型与 API 配置:选择支持工具调用的大模型(如通义千问 Qwen-Max、文心一言申请 API 密钥配置调用参数temperature=0.3,降低随机性)。
? 多智能体架构:采用 Agent Orchestrator如 LangGraph/Ray/Celery编排 DiagnosisAgent诊断、LogParserAgent解析、PolicyAgent风险与审批策略
q. Prompt 工程设计:构造结构化 Prompt强制大模型输出可执行修复指令示例
你是Hadoop运维专家需基于以下结构化日志输出
@ -106,7 +170,8 @@ q. Prompt
3. fix_script可执行Shell/Hadoop命令无多余解释
4. risk_level风险等级low/medium/high
输出格式为JSON不含其他文字
日志:{结构化日志列表} r. 诊断逻辑开发:在 FastAPI 中编写call_llm_diagnose函数传递结构化日志至大模型 API解析返回结果用 Pydantic 定义FixCommand类校验格式过滤危险指令如rm -rf /*)。
日志:{结构化日志列表}
r. 诊断逻辑开发:在 FastAPI 中编写call_llm_diagnose函数传递结构化日志至大模型 API解析返回结果用 Pydantic 定义FixCommand类校验格式过滤危险指令如rm -rf /*)。
s. 诊断验证:模拟 “磁盘满” 故障dd if=/dev/zero of=/tmp/test bs=1G count=5查看大模型是否正确输出 “清理临时文件” 的修复脚本。
? 实施要点:添加大模型调用重试机制(失败后重试 2 次,间隔 5 秒),记录调用日志(含输入 / 输出),便于问题排查。
? 必要性:无大模型诊断则需人工分析日志,无法实现 “自动化故障识别”,违背项目核心目标。
@ -118,10 +183,10 @@ t.
? clean_temp.shssh datanode-ip "rm -rf /tmp/hadoop-* && hdfs dfsadmin -refreshNodes"
? kill_timeout_job.shyarn application -kill <appId>(需动态传入 appId
u. 风险控制逻辑:
? 风险分级low如清理临时文件→ 自动执行medium如重启 DataNode→ 前端弹窗确认后执行high如格式化 HDFS→ 钉钉告警 + 人工审批;
? 风险分级low如清理临时文件RepairAgent 自动执行medium如重启 DataNode→ 前端弹窗确认后执行high如格式化 HDFS→ 钉钉告警 + 人工审批(由 PolicyAgent 协同)
? 权限控制修复脚本仅允许后端服务用户如hadoop执行禁止 root 权限。
v. 结果反馈:
? 执行日志记录用subprocess捕获脚本输出stdout/stderr存入 MySQLfault_record表的exec_log字段
? 执行日志记录用subprocess捕获脚本输出stdout/stderr存入 PostgreSQL 的 exec_logs 表
? 前端同步:修复完成后,通过 WebSocket 实时更新前端故障状态(如 “未修复”→“已修复”),弹窗提示结果。
? 实施要点脚本添加参数校验如clean_temp.sh检查/tmp/hadoop-*是否存在避免空执行执行前备份关键配置文件如hdfs-site.xml
? 必要性:缺少自动修复则系统仅能 “发现故障”,无法 “解决故障”,运维效率无实质提升,项目价值大打折扣。
@ -134,7 +199,19 @@ w. ģ
? 功能测试:后端接口(用 Postman 测试参数合法性、返回格式)、前端页面(测试筛选 / 分页 / 按钮点击功能)。
x. 场景测试:模拟 3 类核心故障,验证全流程通顺性:
故障类型 模拟方式 预期结果 DataNode 磁盘满 dd if=/dev/zero of=/tmp/test bs=1G count=5 日志采集→大模型诊断 “磁盘满”→输出clean_temp.sh→执行后磁盘使用率下降 任务超时 提交sleep 3600的 MapReduce 任务 日志采集→大模型诊断 “任务超时”→输出kill_timeout_job.sh→任务被成功终止 DataNode 宕机 sudo systemctl stop hadoop-hdfs-datanode 日志采集→大模型诊断 “DataNode 离线”→输出restart_datanode.sh→节点重启成功 y. 性能优化:
故障类型
模拟方式
预期结果
DataNode 磁盘满
dd if=/dev/zero of=/tmp/test bs=1G count=5
日志采集→大模型诊断 “磁盘满”→输出clean_temp.sh→执行后磁盘使用率下降
任务超时
提交sleep 3600的 MapReduce 任务
日志采集→大模型诊断 “任务超时”→输出kill_timeout_job.sh→任务被成功终止
DataNode 宕机
sudo systemctl stop hadoop-hdfs-datanode
日志采集→大模型诊断 “DataNode 离线”→输出restart_datanode.sh→节点重启成功
y. 性能优化:
? 前端:优化图表加载(懒加载非首屏图表),接口请求合并(减少重复调用);
? 后端:给高频接口(/api/cluster/status加 Redis 缓存,优化大模型调用超时时间(设为 30 秒)。
? 实施要点:记录测试用例与缺陷(用 Excel 或 Jira优先修复 “阻断性缺陷”(如日志采集丢数据、修复脚本执行失败)。
@ -146,10 +223,10 @@ z.
? 编写 Dockerfile
? 前端:基于 Nginx 镜像复制dist目录至/usr/share/nginx/html
? 后端:基于 Python 3.9 镜像,安装依赖,暴露 8000 端口;
? 编写docker-compose.yml定义前端、后端、MySQL、Redis 服务,配置端口映射(如前端 80→容器 80后端 8000→容器 8000
? 编写docker-compose.yml定义前端、后端、PostgreSQL、Redis 服务,配置端口映射(如前端 80→容器 80后端 8000→容器 8000
aa. 生产环境配置:
? Hadoop 集群:在生产节点部署 Flume Agent配置生产级大模型 API 密钥(替换测试密钥);
? 安全配置:设置防火墙规则(仅允许运维 IP 访问前端 80 端口、后端 8000 端口),MySQL/Redis 开启密码认证。
? 安全配置:设置防火墙规则(仅允许运维 IP 访问前端 80 端口、后端 8000 端口),PostgreSQL/Redis 开启密码认证。
bb. 运维监控:
? 系统监控面板:开发监控页面(基于 ECharts展示 Flume 采集量、大模型调用成功率、修复执行成功率;
? 异常告警:配置钉钉机器人,触发告警条件(如 Flume 5 分钟无日志采集、大模型调用失败率 > 5%)时自动推送消息。
@ -163,7 +240,7 @@ cc.
? 时效性从日志产生到修复完成的平均耗时目标≤5 分钟;
? 有效性:修复后故障复发率(复发次数 / 总修复次数目标≤5%。
dd. 评估实施:
? 数据采集:从 MySQLfault_record表提取每日诊断 / 修复数据,用 Excel 或 PythonPandas统计
? 数据采集:从 PostgreSQL 的 fault_records 与 exec_logs 表提取每日诊断 / 修复数据,用 Excel 或 PythonPandas统计
? 报告生成:每周输出《系统运行评估报告》,包含 3 个维度指标、环比变化、异常案例(如诊断错误的故障日志)。
ee. 优化迭代:
? 若准确性低:优化大模型 Prompt增加故障示例、过滤无效日志减少干扰数据
@ -174,11 +251,41 @@ ee.
四、任务衔接与实施顺序建议
1. 实施顺序(按阶段划分)
阶段 持续时间 核心任务(按优先级) 阶段目标 基础搭建阶段 2 周 任务 1Hadoop 部署)→ 任务 2存储体系 完成硬件与存储基础,可产生日志数据 应用开发阶段 3 周 任务 3日志采集→ 任务 4后端接口→ 任务 5前端开发 完成 “采集 - 处理 - 展示” 链路,可查看集群状态 核心落地阶段 2 周 任务 6大模型诊断→ 任务 7自动修复 实现 “诊断 - 修复” 闭环,系统具备核心功能 保障优化阶段 1 周 任务 8测试优化→ 任务 9部署上线→ 任务 10评估改进 系统上线运行,建立长期优化机制 2. 关键衔接点
阶段
持续时间
核心任务(按优先级)
阶段目标
基础搭建阶段
2 周
任务 1Hadoop 部署)→ 任务 2存储体系
完成硬件与存储基础,可产生日志数据
应用开发阶段
3 周
任务 3日志采集→ 任务 4后端接口→ 任务 5前端开发
完成 “采集 - 处理 - 展示” 链路,可查看集群状态
核心落地阶段
2 周
任务 6大模型诊断→ 任务 7自动修复
实现 “诊断 - 修复” 闭环,系统具备核心功能
保障优化阶段
1 周
任务 8测试优化→ 任务 9部署上线→ 任务 10评估改进
系统上线运行,建立长期优化机制
2. 关键衔接点
? 任务 1→任务 3Hadoop 集群部署完成后,才能在节点部署 Flume Agent
? 任务 2→任务 4MySQL/Redis 部署完成后,后端接口才能实现数据存储与缓存;
? 任务 2→任务 4PostgreSQL/Redis 部署完成后,后端接口才能实现数据存储与缓存;
? 任务 4→任务 6后端完成日志结构化后大模型才能接收有效输入
? 任务 8→任务 9测试修复所有阻断性缺陷后才能启动生产环境部署。
五、风险提示与应对建议
潜在风险 应对建议 Hadoop 集群部署失败 提前准备集群部署文档(参考 Apache 官方指南),预留 1 个备用节点,失败后快速重建 大模型 API 不稳定 申请 2 个备用大模型 API如通义千问 + 百度文心一言),代码中添加 API 切换逻辑 修复脚本执行导致集群异常 执行前备份关键数据(如 HDFS 目录),高风险脚本先在测试集群验证效果 生产环境磁盘满 定期清理日志Flume / 后端 / 容器日志),配置磁盘使用率告警(阈值 85% (注:文档部分内容可能由 AI 生成)
潜在风险
应对建议
Hadoop 集群部署失败
提前准备集群部署文档(参考 Apache 官方指南),预留 1 个备用节点,失败后快速重建
大模型 API 不稳定
申请 2 个备用大模型 API如通义千问 + 百度文心一言),代码中添加 API 切换逻辑
修复脚本执行导致集群异常
执行前备份关键数据(如 HDFS 目录),高风险脚本先在测试集群验证效果
生产环境磁盘满
定期清理日志Flume / 后端 / 容器日志),配置磁盘使用率告警(阈值 85%
(注:文档部分内容可能由 AI 生成)

@ -33,6 +33,14 @@ table th:nth-child(6), table td:nth-child(6) { width: 36%; }
- **主要类型**: `JSONB`、`UUID`、`INET`、`TIMESTAMPTZ`
- **字符集**: UTF8
- **时区**: 推荐使用UTC并统一为`TIMESTAMPTZ`
- **后端**: `FastAPI` + `Uvicorn` + `Pydantic`
- **数据库访问**: `SQLAlchemy` + `asyncpg`
- **缓存/消息**: `Redis`(状态缓存/速率限制)
- **日志采集**: `Apache Flume`(可选替代:`Fluent Bit`
- **前端**: `Vue3` + `Vite` + `Element Plus` + `ECharts`
- **实时通信**: WebSocket状态与诊断结果推送
- **多智能体编排**: `LangGraph`/`Ray`Diagnosis/Repair/Policy Agent
- **可观测性**: `Prometheus` + `Grafana`API与Agent指标监控
### 1.3 命名规范
- 表名:小写字母+下划线,复数形式

@ -0,0 +1,149 @@
# 基于Hadoop的故障检测与自动恢复项目 需求规格说明书SRS
## 1. 引言
- 目的:定义系统的功能与非功能需求,为设计、开发、测试与验收提供统一依据。
- 范围Web 应用(前端、后端、多智能体编排)、日志采集、数据库与缓存、可观测性。
- 术语Cluster、Node、Fault、ExecLog、Agent、Policy、JSONB、INET、TIMESTAMPTZ。
- 参考:
- `doc/project/数据库设计文档.md`
- `doc/project/数据库建表脚本_postgres.sql`
- `doc/project/ER图设计说明.md`
- `src/fronted/index.html`(前端原型)
- `doc/project/项目前景与范围文档.md`
## 2. 总体概述
- 产品透视:为 Hadoop 运维提供监控、日志分析、智能诊断与自动修复的一体化平台。
- 用户特征:管理员、操作员、观察员(角色权限定义与审批流程)。
- 约束PostgreSQL 14+、Redis、FastAPI、Vue3、Flume遵循安全与合规最佳实践。
## 3. 功能需求(按模块)
### F-01 身份认证与注册审批
- 说明:登录、注册(审批队列)、用户状态管理。
- 前端映射:`#login`、`#register`、`#user-management`(审批列表)。
- 接口示例:`POST /api/user/login`、`POST /api/user/register`、`GET /api/admin/approvals`、`POST /api/admin/approvals/{id}/approve`。
- 数据映射:`users`、`audit_logs`、`roles/user_role_mapping`。
- 验收:登录成功生成会话与角色;注册进入审批队列;操作审计记录完整。
### F-02 集群列表与注册
- 说明:查看已注册集群、注册新集群、注销集群。
- 前端映射:`#cluster-list`(注册面板/列表)。
- 接口示例:`GET /api/clusters`、`POST /api/clusters`、`DELETE /api/clusters/{uuid}`。
- 数据映射:`clusters(uuid,name,type,node_count,health_status,config_info)`。
- 验收集群唯一性uuid/name健康状态检查约束审计可追踪。
### F-03 仪表板监控
- 说明节点概览、状态指标、趋势图CPU/内存、WebSocket 状态。
- 前端映射:`#dashboard`(统计卡片、图表、节点表格)。
- 接口示例:`GET /api/cluster/status`、`GET /api/nodes?cluster=...`、WS `/ws/status`
- 数据映射:`nodes(cluster_id,hostname,ip_address,status,usage,last_heartbeat)`。
- 验收节点列表与统计一致图表数据刷新正常WS 在线率达标。
### F-04 日志查询
- 说明:按级别/来源集群/来源节点/操作类型/用户ID/时间范围筛选,支持导出。
- 前端映射:`#logs`(搜索条件/列表/分页)。
- 接口示例:`GET /api/logs?level=&cluster=&node=&op=&user=&time_range=`、`GET /api/logs/export`。
- 数据映射:`system_logs(log_id,timestamp,host,service,log_level,message,exception,raw_log,processed)`。
- 验收:筛选项工作正常;分页与导出准确;处理进度与日志条目一致。
### F-05 故障诊断(多智能体)
- 说明:拖拽上下文日志,选择智能体与模型,生成诊断结果与修复建议。
- 前端映射:`#diagnosis`(树形选择/预览/多智能体面板/对话)。
- 接口示例:`POST /api/llm/diagnose`(结构化日志→诊断结果),`POST /api/llm/report`(生成状态报告)。
- 数据映射:`fault_records(affected_nodes,affected_clusters,root_cause,repair_suggestion,status)`、`exec_logs(parameters,target_nodes)`。
- 验收DiagnosisAgent 输出结构化建议PolicyAgent 过滤高风险;生成报告成功。
### F-06 故障中心CRUD
- 说明故障列表筛选、详情、增删改状态机detected→analyzing→repairing→resolved/failed
- 前端映射:`#fault-center`(筛选/列表/操作)。
- 接口示例:`GET /api/faults`、`POST /api/faults`、`PUT /api/faults/{id}`、`DELETE /api/faults/{id}`、`POST /api/faults/{id}/transition`。
- 数据映射:`fault_records(fault_id,fault_type,fault_level,status,title,created_at,...)`。
- 验收:唯一约束 `fault_id`;状态转换合法且有审计记录;索引支持高频查询。
### F-07 执行日志CRUD
- 说明:记录修复命令执行详情,支持筛选与分页。
- 前端映射:`#exec-logs`(列表/操作)。
- 接口示例:`GET /api/exec-logs`、`POST /api/exec-logs`、`PUT /api/exec-logs/{id}`、`DELETE /api/exec-logs/{id}`。
- 数据映射:`exec_logs(exec_id,fault_id,command_type,command_content,target_nodes,risk_level,execution_status,start_time,end_time,stdout_log,stderr_log,exit_code,operator)`。
- 验收:外键 `fault_id` 关联完整;执行状态与时长约束合法;日志内容可读。
### F-08 告警配置(规则管理原型)
- 说明:新增/编辑/删除规则,通知渠道(邮件/短信/Webhook阈值条件。
- 前端映射:`#alert-config`(新增弹窗/规则列表)。
- 接口示例:`GET /api/alerts`、`POST /api/alerts`、`PUT /api/alerts/{id}`、`DELETE /api/alerts/{id}`。
- 数据映射:`app_configurations(config_type='alert_rule',config_key,config_value,is_enabled)`。
- 验收:配置值以 JSONB 存储;启用状态可控;策略与通知联动。
### F-09 用户管理与角色分配
- 说明:用户列表、状态(启用/禁用/待审核)、角色分配与撤销。
- 前端映射:`#user-management`、`#role-assignment`。
- 接口示例:`GET /api/admin/users`、`POST /api/admin/users`、`PUT /api/admin/users/{id}`、`POST /api/admin/users/{id}/roles`。
- 数据映射:`users`、`user_role_mapping`、`roles`。
- 验收:用户名/邮箱唯一;角色分配与撤销一致;审计完整。
### F-10 权限策略(原型)
- 说明:资源与操作的允许/拒绝策略配置。
- 前端映射:`#permission-policy`(策略列表)。
- 接口示例:`GET /api/policies`、`POST /api/policies`、`DELETE /api/policies/{id}`。
- 数据映射:`roles`、`permissions`、`role_permission_mapping`。
- 验收:策略生效与资源范围匹配;拒绝优先;审计记录。
### F-11 审计日志
- 说明:记录用户操作与系统事件,可筛选导出。
- 前端映射:`#audit-logs`。
- 接口示例:`GET /api/audit-logs`、`GET /api/audit-logs/export`。
- 数据映射:`audit_logs(user_id,cluster_id,role_id,action,resource_type,ip_address,request_data,response_status,created_at)`。
- 验收字段完整IP 为 INETJSONB 字段审计可读;索引满足查询需求。
### F-12 WebSocket 推送
- 说明:状态与诊断结果的实时推送;前端 WS 状态展示。
- 前端映射:`#dashboard`WebSocket 状态区)。
- 接口示例WS `/ws/status`、`/ws/diagnose`。
- 验收WS 连接稳定;消息格式统一;断线重连策略有效。
## 4. 非功能性需求
- 性能:核心查询 P95 ≤ 500msWS 延迟 ≤ 500ms后端并发 1k 连接稳定。
- 安全基于角色的访问控制敏感信息不落盘API 速率限制与审计。
- 可靠性:日常备份与恢复演练(`pg_dump`);关键链路重试与降级。
- 可维护性:模块化架构;多智能体职责清晰;日志与监控完善。
- 可用性前端可访问性ARIA 标签与语义结构);错误提示与操作引导。
- 可观测性Prometheus 指标采集Grafana 看板日志分级与追踪ID。
## 5. 数据需求
- 数据库PostgreSQLJSONB/UUID/INET/TIMESTAMPTZ参见建表脚本与数据字典。
- 关键实体:`clusters`、`nodes`、`system_logs`、`fault_records`、`exec_logs`、`app_configurations`、`users`、`audit_logs`、`roles`、`permissions`、`user_role_mapping`、`role_permission_mapping`、`user_cluster_mapping`。
- 约束:唯一键与外键完整;检查约束覆盖状态与枚举值;索引优化高频查询。
## 6. 外部接口
- 日志采集Flume → `POST /api/log/auto-upload`
- 集群状态:`GET /api/cluster/status`(可缓存 Redis
- 诊断:`POST /api/llm/diagnose`;修复报告:`POST /api/llm/report`。
- 故障与执行:`/api/faults/*`、`/api/exec-logs/*`。
- 告警与配置:`/api/alerts/*`、`/api/configs/*`。
- 审计与用户:`/api/audit-logs/*`、`/api/admin/*`。
## 7. 状态机定义
- 故障状态:`detected → analyzing → repairing → {resolved | failed}`;事件驱动与审批联动(高风险需审批)。
- 执行状态:`pending → running → {success | failed | timeout}`;时长与退出码记录完整。
## 8. 用例与原型映射
- 集群列表/注册 → `#cluster-list`、`clusters`、`/api/clusters`。
- 仪表板监控 → `#dashboard`、`nodes`、`/api/cluster/status`、WS `/ws/status`
- 日志查询 → `#logs`、`system_logs`、`/api/logs`。
- 故障诊断 → `#diagnosis`、`fault_records/exec_logs`、`/api/llm/diagnose`。
- 故障中心 → `#fault-center`、`fault_records`、`/api/faults/*`。
- 执行日志 → `#exec-logs`、`exec_logs`、`/api/exec-logs/*`。
- 告警配置 → `#alert-config`、`app_configurations`、`/api/alerts/*`。
- 用户管理/角色 → `#user-management/#role-assignment`、`users/roles/user_role_mapping`、`/api/admin/*`。
- 权限策略 → `#permission-policy`、`roles/permissions/role_permission_mapping`。
- 审计日志 → `#audit-logs`、`audit_logs`、`/api/audit-logs/*`。
## 9. 验收标准
- 端到端闭环:日志→诊断→修复→审计→报表。
- 指标达标:准确率/时效性/复发率/KPI 满足“前景与范围文档”定义。
- 安全合规:权限与审计完整,敏感信息管理符合最佳实践。
- 文档齐备API、数据字典、ER 与部署说明一致。
## 10. 需求追踪矩阵(摘要)
- 功能模块 ↔ 前端页面 ↔ 后端接口 ↔ 数据表 ↔ 指标/验证用例。
- 用于测试与验收阶段交叉核对,确保每项需求均有实现与验证。

@ -0,0 +1,57 @@
# 基于Hadoop的故障检测与自动恢复项目 前景与范围文档
## 1. 项目愿景
- 构建“采集→处理→诊断→修复→评估”的自动化闭环,降低运维成本、提升稳定性与响应速度。
- 面向多集群、复杂日志场景,提供可视化监控、智能诊断与安全可控的自动修复能力。
- 引入多智能体架构,分别承担日志解析、诊断、修复与风险策略,提升扩展性与可维护性。
## 2. 业务目标
- 实时感知 Hadoop 集群运行状态并发现异常。
- 将结构化日志与历史数据驱动的诊断结果转化为可执行修复指令。
- 在风险可控与审计可追的前提下自动闭环修复。
- 为运维人员提供一站式操作入口与报表能力。
## 3. 目标用户与角色
- 管理员admin系统配置、用户与角色、策略管理、审批。
- 操作员operator查看监控、执行修复、管理故障与执行日志。
- 观察员observer/viewer只读查看监控、日志与报表。
## 4. 使用场景
- 日常巡检:在“仪表板”查看节点健康、趋势与异常指示。
- 故障处理:在“故障中心”查看故障详情,触发诊断与修复,跟踪执行记录。
- 日志分析:在“日志查询”检索多维度日志并提交智能分析。
- 安全合规:针对关键操作记录审计日志,支持导出留存。
- 配置治理:在“告警配置”设置阈值与通知渠道,联动规则执行。
## 5. 项目范围In/Out
- In Scope
- 前端页面(参考 `src/fronted/index.html`
- 集群列表/注册、仪表板监控、日志查询、故障诊断多智能体原型、故障中心CRUD、执行日志CRUD、告警配置规则管理原型、用户管理、角色分配、权限策略、审计日志、登录/注册/审批。
- 后端服务FastAPI日志接收与结构化、集群状态查询、诊断接口、大模型调用、修复执行编排、审计与权限。
- 多智能体编排DiagnosisAgent、RepairAgent、PolicyAgent、LogParserAgent。
- 数据存储PostgreSQLJSONB/UUID/INET/TIMESTAMPTZRedis 缓存与限流。
- 可观测性Prometheus 指标采集、Grafana 展示。
- Out of Scope
- 跨租户计费与合同管理、第三方 CMDB 深度集成、复杂工单系统。
- 非 Hadoop 生态的深度治理功能(如 Kubernetes 全面管控)。
## 6. 依赖与约束
- 技术栈FastAPI + SQLAlchemy + asyncpgPostgreSQL 14+RedisApache FlumeVue3/Vite/Element Plus/EChartsWebSocketPrometheus/Grafana。
- 安全合规:严格的角色/权限/审计与敏感信息管理;禁止在代码与配置中明文保存秘钥。
- 性能约束:常用页面查询 P95 ≤ 500ms诊断与修复链路端到端 ≤ 5 分钟。
## 7. 风险与应对
- 大模型稳定性双供应商与重试PolicyAgent 风险过滤与审批策略。
- 修复脚本风险分级管控low/medium/high高风险需人工审批与备份。
- 日志采集质量Flume 异常监控与补偿,数据丢失报警与追溯。
- 数据一致性:关键事件事务化与审计留痕;定期备份与恢复演练。
## 8. 里程碑与交付物
- M1 基础环境:集群与存储、前后端骨架、日志采集链路联通。
- M2 核心功能:仪表板、日志查询、故障中心与执行日志 CRUD诊断接口闭环。
- M3 多智能体:诊断/修复/策略编排,上线审批流与风控策略。
- M4 保障与上线:测试报告、部署与监控面板、运行评估与优化计划。
## 9. 成功度量KPI
- 诊断准确率 ≥ 85%;故障闭环时效 ≤ 5 分钟;修复复发率 ≤ 5%。
- 关键页面 P95 响应 ≤ 500ms错误率 ≤ 1%WebSocket 在线率 ≥ 99%。
Loading…
Cancel
Save