Loading... # Scrutiny 硬盘 S.M.A.R.T 监控工具详解 # 一、概述 ## 1. 简介 ### A. 是什么 Scrutiny 是一个硬盘健康仪表板和监控解决方案，将厂商提供的 S.M.A.R.T 指标与真实世界故障率相结合。它是一个基于 Web 的监控工具，用于跟踪硬盘的 S.M.A.R.T 属性历史趋势，并使用真实世界故障率来定制阈值，从而在硬盘故障前提前预警。 ### B. 为什么需要 传统 smartd 守护进程存在以下问题： - S.M.A.R.T 属性超过百种，smartd 无法区分关键指标和信息性指标 - smartd 不记录 S.M.A.R.T 属性历史，难以判断属性是否随时间缓慢恶化 - 厂商设定的阈值有时未设置或过高，只能确认已故障的硬盘，无法检测即将故障的硬盘 - smartd 仅提供命令行界面，对于无头服务器来说 Web UI 更有价值 ### C. 核心价值 - 历史趋势跟踪：记录 S.M.A.R.T 指标的变化历史 - 智能阈值：基于真实世界故障率定制告警阈值 - 可视化仪表板：Web 界面专注于关键指标 - 多设备支持：自动检测所有连接的硬盘驱动器 ## 2. 项目背景 ### A. 原始项目 Scrutiny 最初由 AnalogJ 创建，是一个开源的硬盘监控解决方案。 ### B. Fork 版本 本文档介绍的是 Starosdev 维护的 Fork 版本。原始项目在 2024 年开发速度显著放缓，而社区贡献和功能请求持续增长。这个 Fork 版本接续原始项目的工作，合并了待处理的社区 PR 并添加了新功能。 ### C. 版本对比 | 特性 | 原始版本 | 本 Fork 版本 | |------|---------|-------------| | 最新版本 | v0.8.1 (2024年4月) | v1.21.0 (2026年2月) | | 前端框架 | Angular 13 | 现代 Angular (Angular 21) | | 维护状态 | 最小更新 | 积极维护 | | 社区 PR | 多个待处理 | 已合并 | ## 3. 前置知识 ### A. 必备技能 - 基本了解硬盘和 S.M.A.R.T 技术 - Docker 基础知识 - Linux 命令行操作 ### B. 推荐知识 - InfluxDB 时序数据库 - Web 服务配置 # 二、系统架构 ## 1. 整体架构 Scrutiny 采用分层架构设计，包含数据采集层、Web 服务层和数据存储层。 ```mermaid graph LR A[Collector] --> B[smartctl] B --> C[Physical Drives] C --> D[Device Devices] A --> E[ZFS Collector] E --> F[ZFS Pools] G[Web Container] --> H[Angular Frontend] G --> I[Go API Backend] J[InfluxDB] --> K[Time Series Data] L[SQLite] --> M[Device Metadata] A --> I I --> J I --> L H --> I ```  ## 2. 组件说明 ### A. Collector（采集器） - 职责：定期采集硬盘 S.M.A.R.T 数据 - 工具：集成 smartctl 二进制文件 - 调度：默认每日执行一次 - 类型：标准采集器、ZFS 采集器 ### B. Web 服务 - 前端：Angular 框架开发的 Web UI - 后端：Go 语言开发的 API 服务 - 功能：提供仪表板、设备管理、配置接口 ### C. 数据存储 - InfluxDB：存储 S.M.A.R.T 时序数据 - SQLite：存储设备元数据和配置信息 ## 3. 数据流转流程 ```mermaid sequenceDiagram participant User as 用户 participant Web as Web UI participant API as API Backend participant Collector as Collector participant InfluxDB as InfluxDB participant SQLite as SQLite User->>Web: 访问仪表板 Web->>API: GET /api/devices API->>SQLite: 查询设备列表 SQLite-->>API: 返回设备数据 API-->>Web: JSON 响应 Web-->>User: 显示仪表板 Note over Collector: 定时执行 (默认每日) Collector->>Collector: smartctl --scan Collector->>Collector: smartctl --info Collector->>Collector: smartctl --xall Collector->>API: POST /api/collect API->>InfluxDB: 写入时序数据 API->>SQLite: 更新设备元数据 API-->>Collector: 确认成功 ```  # 三、部署模式 ## 1. Omnibus 部署 ### A. 概述 Omnibus 模式将所有组件打包在一个 Docker 镜像中，适合单机部署和小规模使用。 ### B. 特点 - 一个容器包含 Web 服务、API 和 Collector - 内置 InfluxDB - 配置简单，快速上手 ## 2. Hub/Spoke 部署 ### A. 概述 Hub/Spoke 模式将组件分离，适合多服务器环境和大规模部署。 ### B. 架构对比 ```mermaid graph TB subgraph Omnibus[Omnibus 部署模式] O1[scrutiny omnibus] O1 --> O2[Web UI] O1 --> O3[API Backend] O1 --> O4[Collector] end subgraph HubSpoke[Hub Spoke 部署模式] H1[scrutiny web] --> H2[Web UI] H1 --> H3[API Backend] C1[scrutiny collector] --> C4[smartctl] C2[scrutiny collector zfs] --> C5[ZFS] C1 --> H3 C2 --> H3 end O1 --> D1[InfluxDB] H1 --> D2[InfluxDB] ```  ### C. 组件分离 - Web 容器：包含 Web UI 和 API，只需一个实例 - Collector 容器：包含数据采集器和 smartctl，每台服务器一个 - InfluxDB：独立容器，只需一个实例 # 四、新功能特性 ## 1. ZFS 池监控 - 监控 ZFS 池健康状态 - 跟踪池容量和使用情况 - 与单独硬盘监控并行展示 ## 2. Prometheus 指标 - 暴露 /api/metrics 端点 - 支持与 Grafana 集成 - 便于纳入现有监控系统 ## 3. 设备归档 - 隐藏已退役硬盘 - 保留历史数据不删除 - 简化仪表板显示 ## 4. 设备级别通知控制 - 按设备静音通知 - 适用于已知问题但暂未更换的硬盘 ## 5. 自定义设备标签 - 为硬盘添加有意义的名称 - 方便识别和管理 ## 6. 天级温度图表 - 更细粒度的温度历史 - 支持日级别数据展示 ## 7. SAS 硬盘温度支持 - 正确读取 SAS 设备温度 - 修复原有温度显示问题 ## 8. 心跳通知 - 定期发送一切正常的通知 - 默认每 24 小时一次 - 用于集成 Uptime Kuma 等监控工具 ## 9. S.M.A.R.T 属性覆盖 - 通过 UI 或配置文件覆盖厂商阈值 - 按设备自定义阈值 ## 10. 改进的 UI 布局 - 侧边栏导航移至顶部 - 更好的 S.M.A.R.T 属性可见性 - 移动端优化 # 五、安装部署 ## 1. 系统要求 ### A. 硬件要求 - 支持的硬盘类型：ATA、IDE、SCSI-3、SATA、NVMe、SAS - RAID 控制器：支持 smartctl 的所有 RAID 控制器 ### B. 支持的架构 | 架构名称 | 二进制文件 | Docker 镜像 | |---------|----------|------------| | linux-amd64 | 支持 | 支持 | | linux-arm64 | 支持 | 支持 | | linux-arm-7 | 支持 | 仅 web/collector | | macos-amd64 | 支持 | 支持 | | macos-arm64 | 支持 | 支持 | | freebsd-amd64 | 支持 | 不支持 | | windows-amd64 | 支持 | 开发中 | ## 2. Docker Omnibus 部署 ### A. 快速启动 ```bash docker run -p 8080:8080 -p 8086:8086 --restart unless-stopped \ -v /path/to/config:/opt/scrutiny/config \ -v /path/to/influxdb2:/opt/scrutiny/influxdb \ -v /run/udev:/run/udev:ro \ --cap-add SYS_RAWIO \ --device=/dev/sda \ --device=/dev/sdb \ --name scrutiny \ ghcr.io/starosdev/scrutiny:latest-omnibus ``` ### B. 参数说明 | 参数 | 说明 | |------|------| | -p 8080:8080 | Web UI 端口映射 | | -p 8086:8086 | InfluxDB 端口映射 | | -v /run/udev | 提供设备元数据访问 | | --cap-add SYS_RAWIO | 允许 smartctl 查询 S.M.A.R.T 数据 | | --device | 将硬盘设备映射到容器内 | | NVMe 硬盘 | 需要额外添加 --cap-add SYS_ADMIN | ### C. 手动触发采集 ```bash docker exec scrutiny /opt/scrutiny/bin/scrutiny-collector-metrics run ``` ## 3. Hub/Spoke 部署 ### A. 启动 InfluxDB ```bash docker run -p 8086:8086 --restart unless-stopped \ -v /path/to/influxdb2:/var/lib/influxdb2 \ --name scrutiny-influxdb \ influxdb:2.2 ``` ### B. 启动 Web 服务 ```bash docker run -p 8080:8080 --restart unless-stopped \ -v /path/to/config:/opt/scrutiny/config \ --name scrutiny-web \ ghcr.io/starosdev/scrutiny:latest-web ``` ### C. 启动 Collector ```bash docker run --restart unless-stopped \ -v /run/udev:/run/udev:ro \ --cap-add SYS_RAWIO \ --device=/dev/sda \ --device=/dev/sdb \ -e COLLECTOR_API_ENDPOINT=http://SCRUTINY_WEB_IPADDRESS:8080 \ --name scrutiny-collector \ ghcr.io/starosdev/scrutiny:latest-collector ``` ### D. 启动 ZFS Collector（可选） ```bash docker run --restart unless-stopped \ -e COLLECTOR_API_ENDPOINT=http://SCRUTINY_WEB_IPADDRESS:8080 \ --name scrutiny-collector-zfs \ ghcr.io/starosdev/scrutiny:latest-collector-zfs ``` # 六、配置说明 ## 1. 配置文件位置 默认路径：/opt/scrutiny/config ## 2. 配置文件类型 ### A. scrutiny.yaml Webapp/API 配置文件 ### B. collector.yaml Collector 配置文件 ### C. collector-zfs.yaml ZFS Collector 配置文件 ## 3. Cron 调度配置 ### A. 环境变量配置 使用 COLLECTOR_CRON_SCHEDULE 环境变量覆盖默认调度： ```bash docker run -e COLLECTOR_CRON_SCHEDULE="0 0 * * *" \ ghcr.io/starosdev/scrutiny:latest-collector ``` ### B. 默认调度 每日午夜执行：0 0 * * * ## 4. 日志配置 ### A. 日志级别（从高到低） | 级别 | 说明 | |------|------| | PANIC | 记录后调用 panic | | FATAL | 记录后调用 os.Exit(1) | | ERROR | 错误条件 | | WARN | 警告条件（也接受 WARNING） | | INFO | 一般操作消息（默认） | | DEBUG | 详细诊断信息 | | TRACE | 非常细粒度的诊断信息 | ### B. Web 服务器日志配置 ```bash # 环境变量方式 DEBUG=true SCRUTINY_LOG_FILE=/tmp/web.log # 配置文件方式 log: file: '/tmp/web.log' level: DEBUG # CLI 参数方式 scrutiny start --debug --log-file /tmp/web.log ``` ### C. Collector 日志配置 ```bash # 环境变量方式 DEBUG=true COLLECTOR_LOG_FILE=/tmp/collector.log # CLI 参数方式 scrutiny-collector-metrics run --debug --log-file /tmp/collector.log ``` ## 5. 环境变量覆盖 ### A. Web 服务器环境变量（部分） | 配置键 | 环境变量 | 默认值 | |--------|---------|--------| | web.listen.port | SCRUTINY_WEB_LISTEN_PORT | 8080 | | web.listen.host | SCRUTINY_WEB_LISTEN_HOST | 0.0.0.0 | | web.database.location | SCRUTINY_WEB_DATABASE_LOCATION | /opt/scrutiny/config/scrutiny.db | | web.influxdb.host | SCRUTINY_WEB_INFLUXDB_HOST | localhost | | web.influxdb.port | SCRUTINY_WEB_INFLUXDB_PORT | 8086 | | web.metrics.enabled | SCRUTINY_WEB_METRICS_ENABLED | true | ### B. Collector 环境变量（部分） | 配置键 | 环境变量 | 默认值 | |--------|---------|--------| | host.id | COLLECTOR_HOST_ID | - | | api.endpoint | COLLECTOR_API_ENDPOINT | http://localhost:8080 | | api.timeout | COLLECTOR_API_TIMEOUT | 60 | | commands.metrics_smartctl_bin | COLLECTOR_COMMANDS_METRICS_SMARTCTL_BIN | smartctl | ### C. Docker 专用环境变量 | 环境变量 | 默认值 | 说明 | |---------|--------|------| | COLLECTOR_CRON_SCHEDULE | 0 0 * * * | Cron 调度表达式 | | COLLECTOR_RUN_STARTUP | false | 容器启动时立即运行 | | COLLECTOR_RUN_STARTUP_SLEEP | 1 | 启动采集前延迟秒数 | # 七、告警通知 ## 1. 支持的通知服务 - 自定义脚本 - Email - Webhooks - Discord - Gotify - Hangouts - IFTTT - Join - Mattermost - ntfy - Pushbullet - Pushover - Slack - Teams - Telegram - Tulip ## 2. 配置示例 查看 example.scrutiny.yaml 中的 notify.urls 部分获取配置示例。 ## 3. 测试通知 ```bash curl -X POST http://localhost:8080/api/health/notify ``` ## 4. 心跳通知 - 默认禁用，通过 Web UI 的设置或 /api/settings API 启用 - 可配置间隔，默认每 24 小时 - 有硬盘故障时心跳通知被抑制（故障通知优先） ## 5. 设备级别通知控制 通过 Web UI 可以为特定设备静音通知，适用于已知问题但暂未更换的硬盘。 # 八、Prometheus 集成 ## 1. 指标端点 /api/metrics ## 2. Prometheus 配置示例 ```yaml scrape_configs: - job_name: 'scrutiny' static_configs: - targets: ['scrutiny:8080'] metrics_path: '/api/metrics' ``` # 九、迁移指南 ## 1. 从原始项目迁移 如果当前使用 AnalogJ/scrutiny，迁移非常简单： ### A. 更新镜像引用 从： ``` ghcr.io/analogj/scrutiny ``` 改为： ``` ghcr.io/starosdev/scrutiny ``` ### B. 数据兼容性 - 现有的 SQLite 数据库无需更改 - InfluxDB 数据完全兼容 ### C. 配置文件兼容性 - scrutiny.yaml 无需修改 - collector.yaml 无需修改 # 十、故障排除 ## 1. RAID/虚拟硬盘 ### A. 设备检测 Scrutiny 使用 smartctl --scan 检测设备。 ### B. RAID 控制器支持 所有 smartctl 支持的 RAID 控制器都自动支持。 ### C. 设备类型覆盖 如果 --scan 未正确检测设备类型，可在配置文件中覆盖。 ## 2. NVMe 硬盘 NVMe 硬盘需要额外添加： ```bash --cap-add SYS_ADMIN ``` ## 3. 设备映射 确保将所有硬盘设备映射到容器： ```bash --device=/dev/sda --device=/dev/sdb ``` # 十一、技术栈 ## 1. 后端 - 语言：Go - 版本：84.4% 代码占比 ## 2. 前端 - 框架：Angular 21（从 Angular 13 升级） - 版本：14.1% 代码占比 ## 3. 数据库 - 时序数据：InfluxDB 2.x - 元数据：SQLite ## 4. 许可证 MIT License *** ## 参考资料 1. [Starosdev/scrutiny GitHub 仓库](https://github.com/Starosdev/scrutiny) 2. [AnalogJ/scrutiny 原始项目](https://github.com/AnalogJ/scrutiny) 最后修改：2026 年 02 月 07 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏