add archlinux install

2026-03-02 14:46:28 +08:00
parent c4f4fefa0a
commit 5206b202b7
2 changed files with 376 additions and 37 deletions
--- a/README.md
+++ b/README.md
@@ -13,68 +13,267 @@ ServerGuard 是一款基于 Python 的 Linux 命令行工具，用于诊断服
 - **日志分析**：自动扫描系统日志中的硬件错误
 - **报告生成**：支持 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)

- Python 3.8+
- Linux 操作系统
- root 权限（大多数硬件诊断功能需要）
+## 克隆及安装方法

-### 安装系统依赖
+### 方法一：快速安装（推荐）
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/yourusername/ServerGuard.git
+cd ServerGuard
+
+# 2. 运行自动安装脚本（自动安装所有依赖）
+sudo ./install.sh
+```
+
+### 方法二：手动安装
+
+#### 步骤 1：克隆仓库
+
+```bash
+git clone https://github.com/yourusername/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
+sudo apt install -y \
+    lshw dmidecode smartmontools lm-sensors \
+    stress-ng memtester ipmitool edac-utils \
+    fio mdadm pciutils usbutils nvme-cli
 ```

-**CentOS/RHEL:**
+**CentOS/RHEL 7/8/9:**
 ```bash
-sudo yum install -y lshw dmidecode smartmontools lm_sensors stress-ng memtester OpenIPMI edac-utils fio mdadm pciutils usbutils
+# 启用 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 作为备选
 ```

-### 安装 Python 依赖
+**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
-sudo python3 main.py --full --format json --output report.json
-sudo python3 main.py --full --format html --output report.html
+# 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
-python3 main.py --help
+# 详细输出模式
+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
 ```

 ## 项目结构
@@ -85,6 +284,8 @@ ServerGuard/
 ├── utils.py             # 通用工具库
 ├── reporter.py          # 报告生成模块
 ├── requirements.txt     # Python 依赖
+├── install.sh           # 自动安装脚本
+├── quick_test.py        # 快速测试脚本
 ├── README.md            # 项目说明
 ├── config/
 │   └── config.yaml      # 配置文件
@@ -98,14 +299,95 @@ ServerGuard/
 │   ├── gpu.py           # 显卡检测
 │   └── log_analyzer.py  # 日志分析
 └── tests/               # 测试文件
+    ├── test_utils.py
+    └── test_modules.py
+```
+
+## 测试
+
+```bash
+# 运行快速测试
+python3 quick_test.py
+
+# 运行单元测试
+python3 -m unittest discover tests/ -v
+```
+
+## 故障排除
+
+### 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 权限运行
-2. **压力测试**：全面诊断中的压力测试会占用大量系统资源，建议在维护窗口期进行
-3. **数据安全**：存储设备坏块扫描可能破坏数据，请谨慎使用
+1. **权限要求**：大多数硬件诊断功能需要 root 权限运行，请使用 `sudo` 执行
+
+2. **压力测试警告**：
+   - 全面诊断中的压力测试会占用大量系统资源
+   - CPU 和内存使用率将接近 100%
+   - 建议在维护窗口期进行，并确保服务器可接受高负载
+   - 生产环境请谨慎使用 `--full` 模式
+
+3. **数据安全**：
+   - 存储设备坏块扫描（`badblocks`）可能破坏数据
+   - 默认情况下不会自动执行破坏性测试
+
+4. **兼容性**：
+   - 某些虚拟化环境（如容器）可能无法获取硬件信息
+   - 云服务器可能无法访问底层硬件传感器

 ## 许可证

 MIT License
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 联系我们
+
+如有问题或建议，请通过 GitHub Issues 联系。
--- a/install.sh
+++ b/install.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # ServerGuard 安装脚本
-# 支持 Debian/Ubuntu 和 CentOS/RHEL
+# 支持 Debian/Ubuntu、CentOS/RHEL 和 Arch Linux

 echo "========================================"
 echo "ServerGuard 安装脚本"
@@ -35,11 +35,17 @@ install_package() {
    local pkg=$1
    local pkg_manager=$2
    
-    if [ "$pkg_manager" = "apt" ]; then
+    case "$pkg_manager" in
+        apt)
            apt-get install -y "$pkg" 2>/dev/null && return 0
-    else
+            ;;
+        yum)
            yum install -y "$pkg" 2>/dev/null && return 0
-    fi
+            ;;
+        pacman)
+            pacman -S --noconfirm "$pkg" 2>/dev/null && return 0
+            ;;
+    esac
    
    FAILED_PACKAGES="$FAILED_PACKAGES $pkg"
    return 1
@@ -142,6 +148,46 @@ install_redhat_deps() {
    fi
 }

+# 安装 Arch Linux 依赖
+install_arch_deps() {
+    echo "正在安装 Arch Linux 依赖..."
+    
+    # 确保包数据库是最新的
+    pacman -Sy
+    
+    # 核心依赖（必须）
+    CORE_PKGS="lshw dmidecode smartmontools lm_sensors ipmitool mdadm pciutils usbutils util-linux coreutils grep gawk sed"
+    
+    # 可选依赖（Arch 中大部分都在官方仓库或 AUR）
+    # stress-ng 在官方仓库 community 中
+    OPTIONAL_PKGS="stress-ng memtester edac-utils fio nvme-cli"
+    
+    echo "安装核心依赖..."
+    for pkg in $CORE_PKGS; do
+        install_package "$pkg" "pacman" || echo "警告: $pkg 安装失败"
+    done
+    
+    echo "安装可选依赖..."
+    for pkg in $OPTIONAL_PKGS; do
+        install_package "$pkg" "pacman" || echo "注意: $pkg 安装失败（可选）"
+    done
+    
+    # 检查是否安装了 stress-ng 或 stress
+    if ! command -v stress-ng &> /dev/null && ! command -v stress &> /dev/null; then
+        echo ""
+        echo "============================================"
+        echo "警告: 未安装压力测试工具"
+        echo "============================================"
+        echo "在 Arch Linux 上安装 stress-ng:"
+        echo "  sudo pacman -S stress-ng"
+        echo ""
+        echo "或者从 AUR 安装 memtester:"
+        echo "  yay -S memtester"
+        echo "============================================"
+        echo ""
+    fi
+}
+
 # 根据发行版安装
 case "$OS" in
    *Debian*|*Ubuntu*)
@@ -150,8 +196,19 @@ case "$OS" in
    *CentOS*|*Red*Hat*|*Fedora*|*Alma*|*Rocky*)
        install_redhat_deps
        ;;
+    *Arch*Linux*|*Manjaro*)
+        install_arch_deps
+        ;;
    *)
        echo "不支持的操作系统: $OS"
+        echo ""
+        echo "ServerGuard 支持以下发行版:"
+        echo "  - Debian/Ubuntu"
+        echo "  - CentOS/RHEL 7/8/9"
+        echo "  - Fedora"
+        echo "  - Arch Linux / Manjaro"
+        echo "  - AlmaLinux / Rocky Linux"
+        echo ""
        echo "请手动安装以下工具:"
        echo "  lshw, dmidecode, smartmontools, lm-sensors, stress-ng, memtester"
        echo "  ipmitool, edac-utils, fio, mdadm, pciutils, usbutils"