451 lines
11 KiB
Markdown
451 lines
11 KiB
Markdown
# ServerGuard - 服务器硬件健康诊断系统
|
||
|
||
ServerGuard 是一款基于 Python 的 Linux 命令行工具，用于诊断服务器硬件（CPU、内存、存储、电源、显卡等）的潜在故障。
|
||
|
||
## 功能特性
|
||
|
||
- **硬件信息概览**：收集 CPU、内存、主板、存储、显卡等详细信息
|
||
- **CPU 检测**：温度监控、MCE 错误检查、压力测试
|
||
- **内存检测**：DIMM 信息、ECC 状态检查、内存压力测试
|
||
- **存储检测**：SMART 数据分析、I/O 性能测试、RAID 状态检查
|
||
- **传感器监控**：电压、风扇转速、温度监控（支持 IPMI）
|
||
- **显卡检测**：GPU 信息、温度、驱动状态检查
|
||
- **日志分析**：自动扫描系统日志中的硬件错误
|
||
- **报告生成**：支持 JSON、CSV、纯文本、HTML 格式
|
||
|
||
## 系统要求
|
||
|
||
- **操作系统**: Linux (CentOS/RHEL 7/8/9, Ubuntu 18.04+, Debian 9+, Fedora, Arch Linux, Manjaro 等)
|
||
- **Python**: 3.6 或更高版本
|
||
- **权限**: root 权限（大多数硬件诊断功能需要）
|
||
- **架构**: x86_64 (AMD64)
|
||
- **磁盘空间**: 至少 100MB 可用空间（用于日志和报告）
|
||
|
||
## 克隆及安装方法
|
||
|
||
### 方法一：快速安装（推荐）
|
||
|
||
```bash
|
||
# 1. 克隆仓库
|
||
git clone https://git.yuyujing.cn/zj/ServerGuard.git
|
||
cd ServerGuard
|
||
|
||
# 2. 运行自动安装脚本（自动安装所有依赖）
|
||
sudo ./install.sh
|
||
```
|
||
|
||
### 方法二：手动安装
|
||
|
||
#### 步骤 1：克隆仓库
|
||
|
||
```bash
|
||
git clone https://git.yuyujing.cn/zj/ServerGuard.git
|
||
cd ServerGuard
|
||
```
|
||
|
||
#### 步骤 2：安装系统依赖
|
||
|
||
**Debian/Ubuntu:**
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y \
|
||
lshw dmidecode smartmontools lm-sensors \
|
||
stress-ng memtester ipmitool edac-utils \
|
||
fio mdadm pciutils usbutils nvme-cli
|
||
```
|
||
|
||
**CentOS/RHEL 7/8/9:**
|
||
```bash
|
||
# 启用 EPEL 仓库
|
||
sudo yum install -y epel-release
|
||
|
||
# CentOS 8/RHEL 8 需要启用 PowerTools
|
||
sudo yum config-manager --set-enabled powertools 2>/dev/null || true
|
||
|
||
# 安装依赖
|
||
sudo yum install -y \
|
||
lshw dmidecode smartmontools lm_sensors \
|
||
stress memtester ipmitool edac-utils \
|
||
fio mdadm pciutils usbutils nvme-cli
|
||
|
||
# 注意：stress-ng 在 CentOS 8 上需要从源码编译
|
||
# 如果没有 stress-ng，会使用 stress 作为备选
|
||
```
|
||
|
||
**Arch Linux / Manjaro:**
|
||
```bash
|
||
# 更新包数据库
|
||
sudo pacman -Sy
|
||
|
||
# 安装依赖
|
||
sudo pacman -S --noconfirm \
|
||
lshw dmidecode smartmontools lm_sensors \
|
||
stress-ng ipmitool mdadm pciutils usbutils \
|
||
coreutils grep gawk sed util-linux
|
||
|
||
# 可选依赖（部分在 AUR）
|
||
# 使用 AUR 助手（如 yay）安装额外工具
|
||
yay -S memtester edac-utils
|
||
|
||
# fio 和 nvme-cli 在官方仓库中
|
||
sudo pacman -S fio nvme-cli
|
||
```
|
||
|
||
#### 步骤 3：安装 Python 依赖
|
||
|
||
```bash
|
||
# 方式 1：使用虚拟环境（推荐）
|
||
python3 -m venv venv
|
||
source venv/bin/activate
|
||
pip install -r requirements.txt
|
||
|
||
# 方式 2：直接安装到系统
|
||
sudo pip3 install -r requirements.txt
|
||
|
||
# 方式 3：用户安装
|
||
pip3 install --user -r requirements.txt
|
||
```
|
||
|
||
#### 步骤 4：配置 lm-sensors（可选）
|
||
|
||
```bash
|
||
# 检测传感器芯片
|
||
sudo sensors-detect --auto
|
||
```
|
||
|
||
#### 步骤 5：创建快捷方式（可选）
|
||
|
||
```bash
|
||
# 创建全局命令
|
||
sudo ln -sf $(pwd)/main.py /usr/local/bin/serverguard
|
||
sudo chmod +x /usr/local/bin/serverguard
|
||
|
||
# 现在可以直接使用
|
||
sudo serverguard --quick
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 快速开始
|
||
|
||
```bash
|
||
# 快速检测（非侵入性，推荐日常使用）
|
||
sudo python3 main.py --quick
|
||
|
||
# 全面诊断（包含压力测试，耗时较长）
|
||
sudo python3 main.py --full
|
||
|
||
# 查看帮助
|
||
python3 main.py --help
|
||
```
|
||
|
||
### 常用命令示例
|
||
|
||
#### 1. 快速检测模式
|
||
|
||
快速收集系统硬件信息，不执行压力测试，适合日常使用：
|
||
|
||
```bash
|
||
sudo python3 main.py --quick
|
||
```
|
||
|
||
#### 2. 全面诊断模式
|
||
|
||
执行包括压力测试在内的全面硬件诊断（需要确认）：
|
||
|
||
```bash
|
||
# 默认 300 秒压力测试
|
||
sudo python3 main.py --full
|
||
|
||
# 自定义压力测试时长（单位：秒）
|
||
sudo python3 main.py --full --stress-duration 600
|
||
|
||
# 自动确认，跳过警告提示
|
||
sudo python3 main.py --full --yes
|
||
```
|
||
|
||
#### 3. 运行特定模块
|
||
|
||
只检测指定的硬件模块：
|
||
|
||
```bash
|
||
# 单模块检测
|
||
sudo python3 main.py --module cpu
|
||
sudo python3 main.py --module memory
|
||
sudo python3 main.py --module storage
|
||
sudo python3 main.py --module sensors
|
||
sudo python3 main.py --module gpu
|
||
sudo python3 main.py --module logs
|
||
|
||
# 多模块组合检测
|
||
sudo python3 main.py --module cpu,memory,storage
|
||
|
||
# 查看所有可用模块
|
||
python3 main.py --list-modules
|
||
```
|
||
|
||
#### 4. 生成报告
|
||
|
||
支持多种格式的报告输出：
|
||
|
||
```bash
|
||
# JSON 格式（机器可读，方便程序处理）
|
||
sudo python3 main.py --quick --format json --output report.json
|
||
|
||
# HTML 格式（可视化报告）
|
||
sudo python3 main.py --quick --format html --output report.html
|
||
|
||
# CSV 格式（表格数据）
|
||
sudo python3 main.py --quick --format csv --output report.csv
|
||
|
||
# 纯文本格式（默认，适合终端查看）
|
||
sudo python3 main.py --quick --format text --output report.txt
|
||
```
|
||
|
||
#### 5. 高级选项
|
||
|
||
```bash
|
||
# 详细输出模式
|
||
sudo python3 main.py --quick --verbose
|
||
|
||
# 指定日志文件
|
||
sudo python3 main.py --quick --log /var/log/serverguard.log
|
||
|
||
# 组合使用多个选项
|
||
sudo python3 main.py --full --format json --output diag-$(date +%Y%m%d).json --yes
|
||
```
|
||
|
||
### 使用场景示例
|
||
|
||
#### 场景 1：服务器定期健康检查
|
||
|
||
创建一个定时任务，每天自动检测并生成报告：
|
||
|
||
```bash
|
||
# 编辑 crontab
|
||
sudo crontab -e
|
||
|
||
# 添加以下内容（每天凌晨 2 点执行）
|
||
0 2 * * * cd /opt/ServerGuard && python3 main.py --quick --format html --output /var/log/serverguard/daily-$(date +\%Y\%m\%d).html
|
||
```
|
||
|
||
#### 场景 2：故障排查
|
||
|
||
当服务器出现异常（如频繁重启、性能下降）时：
|
||
|
||
```bash
|
||
# 1. 首先查看系统日志中的硬件错误
|
||
sudo python3 main.py --module logs
|
||
|
||
# 2. 检查 CPU 和内存状态
|
||
sudo python3 main.py --module cpu,memory
|
||
|
||
# 3. 检查存储设备健康状态
|
||
sudo python3 main.py --module storage --format json
|
||
|
||
# 4. 执行全面压力测试（维护窗口期）
|
||
sudo python3 main.py --full --stress-duration 600
|
||
```
|
||
|
||
#### 场景 3：新服务器验收
|
||
|
||
新服务器上架前的全面检测：
|
||
|
||
```bash
|
||
# 生成完整的验收报告
|
||
sudo python3 main.py --full --format html --output acceptance-report.html
|
||
|
||
# 同时生成 JSON 格式供后续分析
|
||
sudo python3 main.py --full --format json --output acceptance-data.json
|
||
```
|
||
|
||
### 快捷命令使用
|
||
|
||
如果创建了 `/usr/local/bin/serverguard` 快捷方式：
|
||
|
||
```bash
|
||
# 快速检测
|
||
sudo serverguard --quick
|
||
|
||
# 全面诊断
|
||
sudo serverguard --full
|
||
|
||
# 查看 CPU 信息
|
||
sudo serverguard --module cpu
|
||
|
||
# 生成 JSON 报告
|
||
sudo serverguard --quick -f json -o report.json
|
||
```
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
ServerGuard/
|
||
├── main.py # 程序入口和核心调度器
|
||
├── utils.py # 通用工具库
|
||
├── reporter.py # 报告生成模块
|
||
├── requirements.txt # Python 依赖
|
||
├── install.sh # 自动安装脚本
|
||
├── quick_test.py # 快速测试脚本
|
||
├── README.md # 项目说明
|
||
├── config/
|
||
│ └── config.yaml # 配置文件
|
||
├── modules/
|
||
│ ├── __init__.py
|
||
│ ├── system_info.py # 系统信息概览
|
||
│ ├── cpu.py # CPU 检测
|
||
│ ├── memory.py # 内存检测
|
||
│ ├── storage.py # 存储检测
|
||
│ ├── sensors.py # 传感器监控
|
||
│ ├── gpu.py # 显卡检测
|
||
│ └── log_analyzer.py # 日志分析
|
||
└── tests/ # 测试文件
|
||
├── test_utils.py
|
||
└── test_modules.py
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行快速测试
|
||
python3 quick_test.py
|
||
|
||
# 运行单元测试
|
||
python3 -m unittest discover tests/ -v
|
||
```
|
||
|
||
## 日志记录
|
||
|
||
ServerGuard 会实时记录详细的测试日志，方便排查问题：
|
||
|
||
### 日志文件位置
|
||
|
||
默认日志文件路径：`/var/log/serverguard.log`
|
||
|
||
```bash
|
||
# 查看实时日志
|
||
tail -f /var/log/serverguard.log
|
||
|
||
# 查看最近 100 行日志
|
||
tail -n 100 /var/log/serverguard.log
|
||
```
|
||
|
||
### 日志内容说明
|
||
|
||
日志包含以下关键信息：
|
||
- **启动信息**: 程序启动时间、命令行参数、Python版本等
|
||
- **进度记录**: 每个模块的检测开始和结束时间
|
||
- **详细步骤**: 压力测试前后的温度、执行的命令等
|
||
- **错误信息**: 详细的异常信息和堆栈跟踪
|
||
|
||
### 日志示例
|
||
|
||
```
|
||
2026-03-02 15:41:28 - ServerGuard 启动
|
||
2026-03-02 15:41:28 - [DIAGNOSTIC START] 全面硬件诊断
|
||
2026-03-02 15:41:28 - [PROGRESS] 模块 1/7: system
|
||
2026-03-02 15:41:28 - [MODULE START] cpu - stress_test=True, duration=300
|
||
2026-03-02 15:41:28 - [CPU STRESS TEST] 测试前温度: 45°C
|
||
2026-03-02 15:46:28 - [CPU STRESS TEST] 测试后温度: 78°C
|
||
2026-03-02 15:46:28 - [CPU STRESS TEST] 压力测试通过
|
||
```
|
||
|
||
### 排查机器重启/关机问题
|
||
|
||
如果测试过程中机器意外关机或重启，查看日志文件：
|
||
|
||
```bash
|
||
# 查找最后的日志记录
|
||
tail -n 50 /var/log/serverguard.log
|
||
|
||
# 查找压力测试相关的日志
|
||
grep "STRESS TEST" /var/log/serverguard.log
|
||
|
||
# 查找错误信息
|
||
grep -i "error\|exception\|failed" /var/log/serverguard.log
|
||
```
|
||
|
||
**常见情况分析：**
|
||
- 如果在 `[CPU STRESS TEST]` 或 `[MEMORY STRESS TEST]` 后没有 `[END]` 记录，说明机器在压力测试中出现问题
|
||
- 查看压力测试前后的温度记录，判断是否因过热导致关机
|
||
- 查看系统日志 `dmesg` 或 `/var/log/messages` 确认硬件错误
|
||
|
||
## 故障排除
|
||
|
||
### 1. 提示 "未找到压力测试工具"
|
||
|
||
**问题**: stress-ng 或 stress 未安装
|
||
|
||
**解决**:
|
||
```bash
|
||
# Debian/Ubuntu
|
||
sudo apt install -y stress-ng
|
||
|
||
# CentOS/RHEL 7
|
||
sudo yum install -y stress
|
||
|
||
# CentOS/RHEL 8/9（stress-ng 需要编译安装）
|
||
sudo yum install -y gcc make libaio-devel libattr-devel libbsd-devel
|
||
sudo git clone https://github.com/ColinIanKing/stress-ng.git /tmp/stress-ng
|
||
cd /tmp/stress-ng && make && sudo make install
|
||
|
||
# Arch Linux / Manjaro
|
||
sudo pacman -S stress-ng
|
||
# 或从 AUR 安装 memtester
|
||
yay -S memtester
|
||
```
|
||
|
||
### 2. IPMI 传感器无法读取
|
||
|
||
**问题**: 需要加载 IPMI 内核模块
|
||
|
||
**解决**:
|
||
```bash
|
||
sudo modprobe ipmi_msghandler
|
||
sudo modprobe ipmi_si
|
||
sudo modprobe ipmi_devintf
|
||
```
|
||
|
||
### 3. SMART 数据无法获取
|
||
|
||
**问题**: 部分磁盘需要特殊权限或固件支持
|
||
|
||
**解决**:
|
||
```bash
|
||
# 检查磁盘是否支持 SMART
|
||
sudo smartctl -i /dev/sda
|
||
|
||
# 启用 SMART
|
||
sudo smartctl -s on /dev/sda
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **权限要求**：大多数硬件诊断功能需要 root 权限运行，请使用 `sudo` 执行
|
||
|
||
2. **压力测试警告**：
|
||
- 全面诊断中的压力测试会占用大量系统资源
|
||
- CPU 和内存使用率将接近 100%
|
||
- 建议在维护窗口期进行，并确保服务器可接受高负载
|
||
- 生产环境请谨慎使用 `--full` 模式
|
||
|
||
3. **数据安全**：
|
||
- 存储设备坏块扫描（`badblocks`）可能破坏数据
|
||
- 默认情况下不会自动执行破坏性测试
|
||
|
||
4. **兼容性**：
|
||
- 某些虚拟化环境（如容器）可能无法获取硬件信息
|
||
- 云服务器可能无法访问底层硬件传感器
|
||
|
||
## 许可证
|
||
|
||
MIT License
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 联系我们
|
||
|
||
如有问题或建议，请通过 GitHub Issues 联系。
|