Checkmate 基础设施监控磁盘选择指南：精确控制磁盘与挂载点的监控范围-创锋一号

Checkmate 基础设施监控磁盘选择指南：精确控制磁盘与挂载点的监控范围

【免费下载链接】CheckmateCheckmate is an open-source, self-hosted tool designed to track and monitor server hardware, uptime, response times, and incidents in real-time with beautiful visualizations. Don't be shy, join here: https://discord.com/invite/NAb6H3UTjK :)项目地址: https://gitcode.com/GitHub_Trending/checkm/Checkmate

Checkmate 是开源、自托管的实时监控工具，其基础设施监控模块负责采集并展示目标服务器的 CPU、内存、磁盘与温度等硬件指标。本文以仓库文档 docs/infrastructure-disk-selection.md 为主体，讲解磁盘选择（Disk Selection）功能的配置入口、行为规则与典型使用场景，并结合源码说明该功能从配置存储、数据采集到前端渲染的完整实现链路。读完本文，你将掌握如何针对多盘服务器制定精准的磁盘监控策略，并能从代码层面理解磁盘数据在 Checkmate 中的流转过程。

功能概述：为什么需要磁盘选择

默认情况下，Checkmate 会监控目标服务器上被采集代理（Capture agent）检测到的所有磁盘，每块磁盘都会对应一个使用率仪表盘（Gauge）与一条时间序列图表。在生产环境中，服务器上往往存在大量分区：系统盘、数据盘、日志盘、临时存储、虚拟/网络挂载盘等，并非每一块都值得纳入日常监控视野。

磁盘选择功能允许用户在已创建的基础设施监控器上，从自动检测到的磁盘/挂载点列表中勾选需要关注的条目，从而精确控制仪表盘、图表与汇总表中展示的磁盘范围，让监控界面聚焦于真正重要的存储资源。

前置条件

使用磁盘选择功能前，需要满足以下条件：

Checkmate 服务端运行中，且目标服务器上已安装并运行 Capture agent；
已创建并配置完成一个基础设施监控器；
Capture agent 至少检测到一块磁盘。

关于基础设施监控器的配置要点，可参考 client/src/locales/en.json 中创建监控器表单的提示文本：监控器的 URL 必须填写 Capture 指标端点的完整路径，例如http://192.168.1.10:5001/api/v1/metrics；若配置了鉴权 token，只需粘贴 token 字符串本身，不要附带Bearer前缀。从源码看，HardwareProvider 直接复用 HttpProvider 对该 URL 发起请求，将返回的 JSON 解析为硬件指标负载（HardwareStatusPayload）；请求失败时抛出携带 URL 上下文信息的AppError。

使用磁盘选择功能

进入功能入口

打开Infrastructure monitors（基础设施监控器）页面；
点击一个已有的基础设施监控器进入详情；
点击"Configure"或"Edit"按钮；
向下滚动到Disk Selection区域。

注意：磁盘选择功能仅在编辑"已经检测到磁盘"的现有监控器时可用。新建监控器时尚无检测结果可供选择。

选择磁盘的步骤

查看可用磁盘：系统自动列出从目标服务器检测到的全部磁盘/挂载点；
勾选磁盘：勾选想要监控的磁盘（可多选）；
应用更改：点击"Save"保存，监控器配置随即更新。

理解磁盘标识符

磁盘通过挂载点或设备名两种形式标识：

挂载点（Mountpoint）：/（根分区）、/home、/var等；
设备名（Device）：/dev/sda1、/dev/nvme0n1p1等。

这两类标识都会随检查数据一同采集并落库（见下文数据链路部分），前端渲染时以设备名作为列表 key。

行为规则

全部磁盘已选择：所有检测到的磁盘都显示在仪表盘（Gauge）与图表中；
选择了特定磁盘：监控界面只展示所选磁盘；
未检测到磁盘：界面显示 "No disk detected for the moment" 提示。

被过滤的内容

当选择了特定磁盘后，以下三类界面元素只反映所选磁盘的数据：

磁盘使用率仪表盘（Disk Usage Gauges）：详情页顶部的磁盘使用率仪表；
磁盘使用率图表（Disk Usage Charts）：按时间序列展示的磁盘使用率曲线；
监控器汇总表（Monitor Table）：监控列表页的磁盘概览列。

由于这三处渲染均以"遍历磁盘数组、逐个渲染"的方式实现，磁盘选择通过控制磁盘数组中实际包含的条目，即可统一影响所有展示位置。

配置如何存储与校验：selectedDisks 字段

从源码结构看，磁盘选择结果通过监控器（Monitor）文档上的selectedDisks字符串数组持久化，贯穿类型定义、Mongoose Schema 与仓库映射三层：

类型定义：server/src/domain/monitors/monitor.type.ts 中声明selectedDisks: string[]；
Mongoose Schema：server/src/domain/monitors/monitor.model.ts 中定义为[String]数组，默认值为[]（空数组）；
仓库映射：server/src/domain/monitors/monitor.repository.mongo.ts 读取文档时以doc.selectedDisks ?? []兜底，保证旧数据也能安全读取。

API 校验层（Zod）在 server/src/api/validation/monitorValidation.ts 中多处声明该字段：

位置（行号）	校验规则	说明
L211、L260	`z.array(z.string()).optional()`	创建/更新场景，磁盘选择为可选字段
L337	`z.array(z.string()).default([])`	部分更新场景，缺省为空数组
L427	`z.array(z.string())`	完整 schema 中为字符串数组

也就是说，用户勾选的每个磁盘标识（设备名或挂载点）都以字符串形式提交，经 Zod 校验后随监控器配置一同保存到数据库，之后由前端详情页读取并据此渲染。

磁盘数据从采集到渲染的完整链路

1. 采集：HardwareProvider

HardwareProvider 的handle()方法以监控器配置的 URL 为入口，复用HttpProvider向 Capture agent 的指标端点发起 HTTP 请求，成功后返回硬件指标负载，其中包含data.disk磁盘数组。

2. 归一化：CheckService

server/src/domain/checks/check.service.ts 将硬件负载中的cpu、memory、disk、host、net逐一映射到 Check 文档，其中check.disk = disk保留原始磁盘数组。

3. 落库：CheckRepository 的 mapDisks

server/src/domain/checks/check.repository.mongo.ts 对每块磁盘归一化为以下字段：

device（设备名）、mountpoint（挂载点）；
total_bytes、free_bytes、used_bytes、usage_percent（容量与使用率）；
total_inodes、free_inodes、used_inodes、inodes_usage_percent（inode 维度）；
read_bytes、write_bytes、read_time、write_time（读写统计）。

对应的数据结构定义在 check.type.ts（mountpoint?: string）与 check.model.ts（mountpoint: { type: String, default: "" }）。

4. 快照：CheckSnapshot

监控器上保存的 recentChecks 快照仅保留展示所需的核心字段：check.snapshot.ts 的mapDisk只映射device、total_bytes、used_bytes、usage_percent，用于仪表盘与详情页的即时渲染，避免快照体积膨胀。

5. 聚合：硬件时间序列

server/src/domain/checks/check.hardware.aggregations.ts 通过 MongoDB 聚合管道生成硬件统计：用$push收集每个时间桶内的磁盘数据，再用$avg计算均值，产出readSpeed、writeSpeed、totalBytes、freeBytes、usagePercent等磁盘维度指标（类型定义见 check.type.ts 的HardwareDiskStats）。

6. 渲染：前端的三个展示点

磁盘仪表盘：client/src/Pages/Infrastructure/Details/Components/Gauges.tsx 遍历snapshot.disk，以disk.device为 key 渲染磁盘使用率DetailGauge，展示used_bytes/total_bytes与百分比进度；
时间序列图表：client/src/Pages/Infrastructure/Details/Components/Charts.tsx 为每块磁盘生成一条disks[idx].usagePercent数据序列；
监控列表汇总表：client/src/Pages/Infrastructure/Monitors/Components/MonitorsTable.tsx 对磁盘数组的usage_percent取平均值后渲染 Gauge；
统计卡片：client/src/Pages/Infrastructure/Details/Components/StatusBoxes.tsx 累加所有磁盘的total_bytes显示磁盘总量。

由此可以推断：磁盘选择功能的核心作用正是控制磁盘数组（即selectedDisks对应的数据源）中实际包含哪些条目，从而让上述所有展示位置同时生效。

磁盘阈值告警与磁盘选择的关系

磁盘使用率告警独立于展示层运行。监控器上的diskAlertThreshold（默认100，单位为百分比）与diskAlertCounter（默认5，连续触发次数）定义于 server/src/api/validation/monitorValidation.ts。在 server/src/service/statusService.ts 的computeHardwareStatus中，每次检查都会基于最新hardware.disk数组评估是否达到阈值，并更新计数器、决定是否切换状态；notification.message-builder.ts 同样先判断Array.isArray(hardware.disk)再组装磁盘告警消息。

需要特别说明的是：磁盘选择影响的是"展示哪些磁盘"，而阈值告警针对采集到的磁盘数据求值。配置磁盘选择范围不会改变告警引擎对全部采集磁盘的评估逻辑，两者职责分离。

典型使用场景

多盘服务器：只监控关键系统盘，忽略临时存储分区；
数据库服务器：重点监控数据库分区，忽略日志分区；
Web 服务器：将 Web 内容盘与系统盘分开监控，各自呈现独立仪表盘；
开发环境：只跟踪与项目相关的挂载点，减少界面噪音。

故障排查

没有磁盘出现

确认目标服务器上的Capture agent 正在运行；
检查 agent 是否具有读取磁盘信息的权限；
确保监控器已运行足够长时间，至少采集到一次检查数据（磁盘列表来自检查数据，而不是创建时静态获取）。

磁盘信息缺失

部分磁盘可能因权限不足无法被 Capture agent 读取；
虚拟磁盘或网络挂载盘可能不会出现在检测列表中；
查看Capture agent 日志，确认是否存在磁盘检测错误。

企业官网建设流程全解析