|
|
@@ -1,9 +1,24 @@
|
|
|
# 网页端本机硬件设备基础信息监控系统
|
|
|
|
|
|
-## 1. 项目简介
|
|
|
-
|
|
|
基于 **Java 21 + Spring Boot 3.4 + React 18** 的本机硬件监控系统，通过 OSHI 采集硬件指标，WebSocket 实时推送至前端仪表盘，支持历史数据持久化与趋势分析。
|
|
|
|
|
|
+---
|
|
|
+
|
|
|
+## 目录
|
|
|
+
|
|
|
+- [1. 项目简介](#1-项目简介)
|
|
|
+- [2. 环境依赖](#2-环境依赖)
|
|
|
+- [3. 快速开始](#3-快速开始)
|
|
|
+- [4. 启动命令](#4-启动命令)
|
|
|
+- [5. 使用说明](#5-使用说明)
|
|
|
+- [6. 部署说明](#6-部署说明)
|
|
|
+- [7. 项目结构](#7-项目结构)
|
|
|
+- [8. 常见问题](#8-常见问题)
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 1. 项目简介
|
|
|
+
|
|
|
### 技术栈
|
|
|
|
|
|
| 层 | 技术 |
|
|
|
@@ -25,67 +40,128 @@
|
|
|
| 网络 | 上下行速率、接口详情、MAC/IP 脱敏 |
|
|
|
| 系统 | 主板、BIOS、OS 版本 |
|
|
|
|
|
|
+### 页面功能
|
|
|
+
|
|
|
+| 页面 | 路由 | 功能说明 |
|
|
|
+|------|------|----------|
|
|
|
+| 仪表盘总览 | `/` | 6 个核心指标卡片，异常告警高亮 |
|
|
|
+| CPU 详情 | `/cpu` | 各核心柱状图 + 温度 + 频率 |
|
|
|
+| 内存详情 | `/memory` | 环形图 + 交换分区 + 内存条表格 |
|
|
|
+| 磁盘详情 | `/disk` | 容量饼图 + 读写速率 + S.M.A.R.T. |
|
|
|
+| GPU 详情 | `/gpu` | 仪表盘 + 温度 + 显存 |
|
|
|
+| 网络详情 | `/network` | 实时速率对比 + 接口详情 |
|
|
|
+| 系统信息 | `/system` | 主板/BIOS/OS 静态信息 |
|
|
|
+| 历史趋势 | `/history` | 时间范围 + 指标类型筛选 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 2. 环境依赖
|
|
|
+
|
|
|
+| 依赖 | 版本 | 说明 |
|
|
|
+|------|------|------|
|
|
|
+| JDK | 21+ | 后端运行环境 |
|
|
|
+| Maven | 3.9+ | 后端构建工具 |
|
|
|
+| Node.js | 18+ | 前端构建工具（仅开发/构建时需要） |
|
|
|
+| 操作系统 | Windows / Linux / macOS | 支持主流桌面系统 |
|
|
|
+
|
|
|
---
|
|
|
|
|
|
-## 2. 使用说明
|
|
|
+## 3. 快速开始
|
|
|
|
|
|
-### 2.1 启动方式
|
|
|
+### 3.1 一键启动（推荐）
|
|
|
|
|
|
-#### 方式一：开发模式（前后端分离）
|
|
|
+**Windows：**
|
|
|
|
|
|
```bash
|
|
|
-# 终端 1：启动后端
|
|
|
-cd hw-monitor
|
|
|
-mvn clean package -DskipTests
|
|
|
-java -jar target/hw-monitor-1.0.0.jar
|
|
|
+# 双击 start.bat 即可启动
|
|
|
+start.bat
|
|
|
+```
|
|
|
|
|
|
-# 终端 2：启动前端开发服务器
|
|
|
-cd hw-monitor/frontend
|
|
|
-npm install
|
|
|
-npm run dev
|
|
|
+**Linux / macOS：**
|
|
|
+
|
|
|
+```bash
|
|
|
+chmod +x start.sh
|
|
|
+./start.sh
|
|
|
```
|
|
|
|
|
|
-访问 **http://127.0.0.1:3000** 查看仪表盘。
|
|
|
+启动后浏览器自动打开 `http://127.0.0.1:9988`。
|
|
|
|
|
|
-#### 方式二：生产模式（前端打包进后端）
|
|
|
+### 3.2 手动启动
|
|
|
+
|
|
|
+```bash
|
|
|
+java -Xms256m -Xmx512m -jar target/hw-monitor-1.0.0.jar
|
|
|
+```
|
|
|
+
|
|
|
+### 3.3 从源码构建
|
|
|
|
|
|
```bash
|
|
|
# 1. 构建前端
|
|
|
-cd hw-monitor/frontend
|
|
|
+cd frontend
|
|
|
npm install
|
|
|
npm run build
|
|
|
|
|
|
-# 2. 复制构建产物到 static 目录
|
|
|
-cp -r dist/* ../src/main/resources/static/
|
|
|
-
|
|
|
-# 3. 打包并运行
|
|
|
+# 2. 复制前端产物到后端 static 目录（Windows PowerShell）
|
|
|
cd ..
|
|
|
+Copy-Item -Recurse .\frontend\dist .\src\main\resources\static -Force
|
|
|
+
|
|
|
+# 2. 复制前端产物到后端 static 目录（Linux / macOS）
|
|
|
+cp -r frontend/dist/* src/main/resources/static/
|
|
|
+
|
|
|
+# 3. 打包
|
|
|
mvn clean package -DskipTests
|
|
|
+
|
|
|
+# 4. 启动
|
|
|
java -jar target/hw-monitor-1.0.0.jar
|
|
|
```
|
|
|
|
|
|
-访问 **http://127.0.0.1:9988** 查看仪表盘。
|
|
|
+### 3.4 开发模式（前后端分离）
|
|
|
|
|
|
-### 2.2 页面导航
|
|
|
+```bash
|
|
|
+# 终端 1：启动后端
|
|
|
+mvn clean package -DskipTests
|
|
|
+java -jar target/hw-monitor-1.0.0.jar
|
|
|
|
|
|
-| 页面 | 路由 | 功能说明 |
|
|
|
-|------|------|----------|
|
|
|
-| 仪表盘总览 | `/` | 6 个核心指标卡片，异常告警高亮 |
|
|
|
-| CPU 详情 | `/cpu` | 各核心柱状图 + 温度 + 频率 |
|
|
|
-| 内存详情 | `/memory` | 环形图 + 交换分区 + 内存条表格 |
|
|
|
-| 磁盘详情 | `/disk` | 容量饼图 + 读写速率 + S.M.A.R.T. |
|
|
|
-| GPU 详情 | `/gpu` | 仪表盘 + 温度 + 显存 |
|
|
|
-| 网络详情 | `/network` | 实时速率对比 + 接口详情 |
|
|
|
-| 系统信息 | `/system` | 主板/BIOS/OS 静态信息 |
|
|
|
-| 历史趋势 | `/history` | 时间范围 + 指标类型筛选 |
|
|
|
+# 终端 2：启动前端开发服务器（支持热更新）
|
|
|
+cd frontend
|
|
|
+npm install
|
|
|
+npm run dev
|
|
|
+```
|
|
|
|
|
|
-### 2.3 采集频率切换
|
|
|
+访问 `http://127.0.0.1:3000`，API 请求自动代理到 `9988` 端口。
|
|
|
|
|
|
-Header 右侧提供 **30 秒 / 60 秒** 两档切换按钮，点击即时生效，无需重启。
|
|
|
+---
|
|
|
+
|
|
|
+## 4. 启动命令
|
|
|
+
|
|
|
+| 命令 | 说明 |
|
|
|
+|------|------|
|
|
|
+| `java -jar target/hw-monitor-1.0.0.jar` | 直接启动 |
|
|
|
+| `java -Xms256m -Xmx512m -jar target/hw-monitor-1.0.0.jar` | 指定内存限制启动 |
|
|
|
+| `java -jar target/hw-monitor-1.0.0.jar --server.port=8080` | 指定端口启动 |
|
|
|
+| `start.bat` | Windows 一键启动脚本 |
|
|
|
+| `./start.sh` | Linux/macOS 一键启动脚本 |
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 5. 使用说明
|
|
|
+
|
|
|
+### 5.1 采集频率切换
|
|
|
+
|
|
|
+Header 右侧提供 **30 秒 / 60 秒** 两档切换按钮，点击即时生效，无需重启。也可通过 API 修改：
|
|
|
+
|
|
|
+```bash
|
|
|
+curl -X PUT http://127.0.0.1:9988/api/v1/config/interval \
|
|
|
+ -H "Content-Type: application/json" \
|
|
|
+ -d '{"intervalSeconds": 60}'
|
|
|
+```
|
|
|
+
|
|
|
+### 5.2 实时刷新
|
|
|
|
|
|
-### 2.4 告警阈值
|
|
|
+仪表盘页面顶部提供 **"实时刷新"** 按钮，点击后立即触发一次全量采集并通过 WebSocket 推送最新数据，无需等待定时周期。
|
|
|
|
|
|
-仪表盘卡片在以下情况自动红色高亮边框：
|
|
|
+### 5.3 告警阈值
|
|
|
+
|
|
|
+仪表盘卡片在以下情况下自动红色高亮边框：
|
|
|
|
|
|
| 指标 | 阈值 |
|
|
|
|------|------|
|
|
|
@@ -94,7 +170,7 @@ Header 右侧提供 **30 秒 / 60 秒** 两档切换按钮，点击即时生效
|
|
|
| 磁盘使用率 | > 90% |
|
|
|
| 温度 | > 80°C |
|
|
|
|
|
|
-### 2.5 REST API
|
|
|
+### 5.4 REST API
|
|
|
|
|
|
| 方法 | 端点 | 说明 |
|
|
|
|------|------|------|
|
|
|
@@ -106,11 +182,12 @@ Header 右侧提供 **30 秒 / 60 秒** 两档切换按钮，点击即时生效
|
|
|
| GET | `/api/v1/network` | 获取网络详情 |
|
|
|
| GET | `/api/v1/system` | 获取系统信息 |
|
|
|
| GET | `/api/v1/history` | 获取历史数据（支持 `?start=&end=&category=` 筛选） |
|
|
|
+| POST | `/api/v1/refresh` | 触发即时采集 |
|
|
|
| GET | `/api/v1/config/interval` | 获取当前采集间隔 |
|
|
|
| PUT | `/api/v1/config/interval` | 修改采集间隔（body: `{"intervalSeconds": 30}`） |
|
|
|
| GET | `/api/v1/health` | 健康检查 |
|
|
|
|
|
|
-### 2.6 WebSocket
|
|
|
+### 5.5 WebSocket
|
|
|
|
|
|
- 地址：`ws://127.0.0.1:9988/ws/metrics`
|
|
|
- 推送频率：与采集间隔一致（默认 30 秒）
|
|
|
@@ -121,30 +198,21 @@ Header 右侧提供 **30 秒 / 60 秒** 两档切换按钮，点击即时生效
|
|
|
"type": "metrics",
|
|
|
"timestamp": 1700000000000,
|
|
|
"data": {
|
|
|
- "cpu": { "usagePercent": 23.0, "temperature": 45.0, ... },
|
|
|
- "memory": { "usagePercent": 74.2, "usedBytes": 25125584896, ... },
|
|
|
- "disk": { "partitions": [...] },
|
|
|
- "gpu": { "name": "Intel(R) Arc(TM) 130T GPU", ... },
|
|
|
- "network": { "interfaces": [...] },
|
|
|
- "system": { "osName": "Windows 11", ... }
|
|
|
+ "cpu": { "usagePercent": 23.0, "temperature": 45.0 },
|
|
|
+ "memory": { "usagePercent": 74.2, "usedBytes": 25125584896 },
|
|
|
+ "disk": { "partitions": [{"usagePercent": 21.6, "usedBytes": 214255665152}] },
|
|
|
+ "gpu": { "name": "Intel(R) Arc(TM) 130T GPU" },
|
|
|
+ "network": { "interfaces": [] },
|
|
|
+ "system": { "osName": "Windows 11" }
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 3. 部署说明
|
|
|
-
|
|
|
-### 3.1 环境要求
|
|
|
+## 6. 部署说明
|
|
|
|
|
|
-| 依赖 | 版本 |
|
|
|
-|------|------|
|
|
|
-| JDK | 21+ |
|
|
|
-| Maven | 3.9+ |
|
|
|
-| Node.js | 18+ (仅前端开发) |
|
|
|
-| 操作系统 | Windows / Linux / macOS |
|
|
|
-
|
|
|
-### 3.2 配置参数
|
|
|
+### 6.1 配置参数
|
|
|
|
|
|
所有可配置参数位于 `src/main/resources/application.yml`：
|
|
|
|
|
|
@@ -173,24 +241,23 @@ hwmonitor:
|
|
|
read-only: true # 只读模式
|
|
|
```
|
|
|
|
|
|
-### 3.3 安全措施
|
|
|
+### 6.2 安全措施
|
|
|
|
|
|
| 措施 | 说明 |
|
|
|
|------|------|
|
|
|
| 网络隔离 | 服务仅监听 `127.0.0.1`，不对外暴露 |
|
|
|
-| 只读原则 | 所有 API 均为 `GET` 请求（除配置修改外） |
|
|
|
+| 只读原则 | 所有数据采集 API 均为 `GET` 请求 |
|
|
|
| 数据脱敏 | MAC 地址掩码、公网 IP 仅显示前两段、磁盘序列号脱敏 |
|
|
|
| 日志安全 | 不输出敏感硬件信息 |
|
|
|
| H2 Console | 已禁用 |
|
|
|
-| Actuator | 仅暴露 `/health` 端点 |
|
|
|
|
|
|
-### 3.4 数据存储
|
|
|
+### 6.3 数据存储
|
|
|
|
|
|
- 数据库文件：`./data/hwmonitor.mv.db`
|
|
|
- 历史数据每天凌晨 3:00 自动清理超过 7 天的记录
|
|
|
-- 若要重置数据，删除 `./data` 目录后重启即可
|
|
|
+- 如需重置数据，删除 `./data` 目录后重启即可
|
|
|
|
|
|
-### 3.5 系统服务部署（Windows）
|
|
|
+### 6.4 Windows 服务部署
|
|
|
|
|
|
使用 WinSW 将 jar 注册为 Windows 服务：
|
|
|
|
|
|
@@ -218,7 +285,7 @@ hw-monitor-service.exe install
|
|
|
hw-monitor-service.exe start
|
|
|
```
|
|
|
|
|
|
-### 3.6 系统服务部署（Linux）
|
|
|
+### 6.5 Linux systemd 部署
|
|
|
|
|
|
```ini
|
|
|
# /etc/systemd/system/hw-monitor.service
|
|
|
@@ -246,60 +313,82 @@ sudo systemctl start hw-monitor
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 4. 项目结构
|
|
|
+## 7. 项目结构
|
|
|
|
|
|
```
|
|
|
hw-monitor/
|
|
|
+├── start.bat # Windows 一键启动脚本
|
|
|
+├── start.sh # Linux/macOS 一键启动脚本
|
|
|
+├── pom.xml # Maven 配置
|
|
|
+├── README.md # 项目文档
|
|
|
+├── .gitignore # Git 忽略规则
|
|
|
├── src/main/java/com/hwmonitor/
|
|
|
│ ├── HwMonitorApplication.java # Spring Boot 启动类
|
|
|
-│ ├── collector/ # 硬件采集器（6个）
|
|
|
-│ │ ├── CpuCollector.java
|
|
|
-│ │ ├── MemoryCollector.java
|
|
|
-│ │ ├── DiskCollector.java
|
|
|
-│ │ ├── GpuCollector.java
|
|
|
-│ │ ├── NetworkCollector.java
|
|
|
-│ │ └── SystemCollector.java
|
|
|
-│ ├── config/ # 配置类
|
|
|
-│ │ ├── BrowserLauncher.java # 启动自动打开浏览器
|
|
|
-│ │ ├── CacheConfig.java # Caffeine 缓存
|
|
|
-│ │ ├── MonitorConfig.java # 采集频率配置
|
|
|
-│ │ └── WebSocketConfig.java # WebSocket 配置
|
|
|
-│ ├── controller/ # 控制器
|
|
|
-│ │ ├── MetricsController.java # REST API
|
|
|
-│ │ ├── ConfigController.java # 配置 API
|
|
|
-│ │ ├── HistoryController.java # 历史数据 API
|
|
|
-│ │ └── MetricsWebSocketHandler.java # WebSocket 处理器
|
|
|
-│ ├── model/ # 数据模型
|
|
|
-│ │ ├── dto/ # 7个 DTO
|
|
|
-│ │ └── entity/ # 1个实体
|
|
|
-│ ├── repository/ # JPA Repository
|
|
|
-│ ├── scheduler/ # 定时调度
|
|
|
-│ └── service/ # 业务服务
|
|
|
+│ ├── collector/ # 硬件采集器（6个）
|
|
|
+│ │ ├── CpuCollector.java # CPU 采集
|
|
|
+│ │ ├── MemoryCollector.java # 内存采集
|
|
|
+│ │ ├── DiskCollector.java # 磁盘采集
|
|
|
+│ │ ├── GpuCollector.java # GPU 采集
|
|
|
+│ │ ├── NetworkCollector.java # 网络采集（含 IP 脱敏）
|
|
|
+│ │ └── SystemCollector.java # 系统信息采集
|
|
|
+│ ├── config/ # 配置类
|
|
|
+│ │ ├── BrowserLauncher.java # 启动自动打开浏览器
|
|
|
+│ │ ├── CacheConfig.java # Caffeine 缓存
|
|
|
+│ │ ├── MonitorConfig.java # 采集频率动态配置
|
|
|
+│ │ └── WebSocketConfig.java # WebSocket 配置
|
|
|
+│ ├── controller/ # 控制器
|
|
|
+│ │ ├── MetricsController.java # REST API + 刷新端点
|
|
|
+│ │ ├── ConfigController.java # 配置管理 API
|
|
|
+│ │ ├── HistoryController.java # 历史数据 API
|
|
|
+│ │ └── MetricsWebSocketHandler.java # WebSocket 推送
|
|
|
+│ ├── model/ # 数据模型
|
|
|
+│ │ ├── dto/ # 7 个数据传输对象
|
|
|
+│ │ └── entity/ # 1 个 JPA 实体
|
|
|
+│ ├── repository/ # JPA Repository
|
|
|
+│ ├── scheduler/ # 定时调度（动态 TaskScheduler）
|
|
|
+│ └── service/ # 业务服务
|
|
|
├── src/main/resources/
|
|
|
-│ └── application.yml # 全局配置
|
|
|
-├── frontend/ # 前端项目
|
|
|
-│ └── src/
|
|
|
-│ ├── components/ # 页面组件（8个）
|
|
|
-│ ├── services/api.ts # API 封装
|
|
|
-│ ├── store/metricsStore.ts # 状态管理
|
|
|
-│ ├── types.ts # TypeScript 类型
|
|
|
-│ └── App.tsx # 根组件
|
|
|
-└── pom.xml # Maven 配置
|
|
|
+│ ├── application.yml # 全局配置
|
|
|
+│ └── static/ # 前端打包产物
|
|
|
+└── frontend/ # 前端源码
|
|
|
+ ├── package.json # 前端依赖
|
|
|
+ ├── vite.config.ts # Vite 配置
|
|
|
+ └── src/
|
|
|
+ ├── App.tsx # 根组件 + 路由
|
|
|
+ ├── main.tsx # 入口
|
|
|
+ ├── types.ts # TypeScript 类型
|
|
|
+ ├── components/ # 页面组件（8个）
|
|
|
+ │ ├── Dashboard/ # 仪表盘总览
|
|
|
+ │ ├── CpuDetail/ # CPU 详情
|
|
|
+ │ ├── MemoryDetail/ # 内存详情
|
|
|
+ │ ├── DiskDetail/ # 磁盘详情
|
|
|
+ │ ├── GpuDetail/ # GPU 详情
|
|
|
+ │ ├── NetworkDetail/ # 网络详情
|
|
|
+ │ ├── SystemInfo/ # 系统信息
|
|
|
+ │ ├── History/ # 历史趋势
|
|
|
+ │ └── Layout/ # 布局（含频率切换 + 连接状态）
|
|
|
+ ├── services/api.ts # API 封装
|
|
|
+ └── store/metricsStore.ts # Zustand 状态管理
|
|
|
```
|
|
|
|
|
|
-## 5. 常见问题
|
|
|
+---
|
|
|
+
|
|
|
+## 8. 常见问题
|
|
|
|
|
|
**Q: 启动后浏览器显示"连接断开"？**
|
|
|
A: 等待 3-5 秒，WebSocket 会自动重连。若持续断开，检查后端是否正常启动在 9988 端口。
|
|
|
|
|
|
**Q: 磁盘使用率显示 0%？**
|
|
|
-A: 某些磁盘分区信息需管理员权限才能获取使用量，以管理员身份运行可解决。
|
|
|
+A: 以管理员身份运行可解决部分权限问题。本项目已修复 Windows 下分区匹配逻辑，正常情况应显示非零值。
|
|
|
|
|
|
**Q: GPU 信息显示 "--"？**
|
|
|
A: OSHI 在某些平台无法获取 GPU 使用率，型号和显存信息正常即可。
|
|
|
|
|
|
**Q: 如何修改采集频率？**
|
|
|
-A: 方式一：点击前端 Header 右侧 30秒/60秒 按钮即时切换；方式二：修改 `application.yml` 中的 `collect-interval-seconds` 配置后重启。
|
|
|
+A: 方式一：点击前端 Header 右侧 30秒/60秒 按钮即时切换；方式二：通过 API 修改；方式三：修改 `application.yml` 后重启。
|
|
|
|
|
|
**Q: 历史数据占用空间大吗？**
|
|
|
-A: 按默认 30 秒采集间隔，每条记录约 100 字节，7 天约产生 2MB 数据，可忽略不计。
|
|
|
+A: 按默认 30 秒采集间隔，每条记录约 100 字节，7 天约产生 2MB 数据，可忽略不计。
|
|
|
+
|
|
|
+**Q: 如何卸载服务？**
|
|
|
+A: Windows: `hw-monitor-service.exe uninstall`；Linux: `sudo systemctl stop hw-monitor && sudo systemctl disable hw-monitor`。
|
肖天鹤