45 分钟搭好 MinIO 监控：从指标抓取到 Grafana 完整指南

45 分钟搭好 MinIO 监控：从指标抓取到 Grafana 完整指南

【免费下载链接】minioMinIO is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license.项目地址: https://gitcode.com/GitHub_Trending/mi/minio

周五下午磁盘告警响了，你打开 Grafana，面板是空的——因为 Prometheus 根本没抓到数据。MinIO 监控这件事没有想象中复杂：服务端默认就内置了完整的指标体系，V2 按 cluster、bucket、node、resource 四类端点暴露数据，V3 又把这些指标拆成十几条按模块划分的采集路径，比如/cluster/health、/api/requests。这篇文章按实操顺序走一遍 MinIO 监控的完整链路：验证端点、配置 Prometheus 抓取任务、导入官方仪表盘，最后给集群仲裁丢失配上告警。

做完这篇你能做到：

• 用一条 curl 确认 MinIO 指标端点是否可用
• 配好 Prometheus 抓取任务并看到时序数据入库
• 在 Grafana 里看到集群健康、容量和桶级流量，并在仲裁丢失时收到告警

它到底能帮你看见什么

MinIO 把 Prometheus 兼容数据作为默认能力内置在服务端，不需要额外插件。最实用的一点是：集群级指标可以从任意单个节点读到，也就是说哪怕你只在负载均衡器后面配了一个抓取目标，也能拿到整个集群的数据。V3 指标体系在 cmd/metrics-v3.go 里把指标按模块组织成一条条采集路径，统一挂在/minio/metrics/v3前缀下，请求时带上?list参数还能列出该路径下所有指标的名称、类型和标签，不用猜指标名。

按你实际会盯的东西分，大致是这么几块：

桶级数据在 V3 里单独成路径，形如/bucket/api/<桶名>，后面配抓取任务时会用到。

动手前的准备

• 一个跑起来的 MinIO 实例，单节点或分布式都行，默认服务端口 9000。
• 一套 Prometheus，能改配置并能访问 MinIO 的 9000 端口。
• 一套 Grafana，任意近两年的版本即可。
• 一个有mc admin prometheus generate权限的账号（通常是根账号），用于生成抓取 token。

缺了哪一步会怎样：MinIO 没起来，所有抓取直接 404；拿不到生成 token 的权限，而指标端点默认是 jwt 鉴权，Prometheus 侧就会一直看到 401。这两个是后面步骤里最常见的卡点。

从零跑通全流程

验证指标端点连通性

先确认 Prometheus 将来要抓的路径是通的：

curl -s http://<minio-node>:9000/minio/metrics/v3/cluster/health?list

返回一张指标表格说明路径存在；返回 401 也属正常，说明鉴权拦住了你，后面用 token 解决。这里的关键是?list参数：它只输出指标清单而不采集数值，适合快速验证路径拼写。

确认路径没拼错之后，给 Prometheus 生成一份现成的抓取配置。

配置 Prometheus 抓取任务

MinIO 的官方文档 docs/metrics/prometheus/README.md 给出了完整流程，核心是先用 mc 生成带 token 的配置片段：

mc admin prometheus generate <your-alias>

把输出合并进prometheus.yml：

scrape_configs: - job_name: minio-job bearer_token: <your-secret> metrics_path: /minio/v2/metrics/cluster scheme: http static_configs: - targets: ['<minio-node-1>:9000'] # 其余配置省略

bearer_token直接来自刚才 mc 命令的输出，metrics_path指向集群端点，所以 targets 只写一个节点就够。重启 Prometheus 后，在 Targets 页面应该能看到 minio-job 状态为 UP。

导入官方 Grafana 集群仪表盘

docker run -d -p 3000:3000 grafana/grafana

进 Grafana 后新建一个 Prometheus 数据源指向你的 Prometheus 地址，然后走 Import 流程，粘贴仓库里的仪表盘 JSON——官方集群大盘是 minio-dashboard.json，桶级、节点级、复制相关也有各自的 JSON，都在docs/metrics/prometheus/grafana/目录下。导入后集群大盘长这样：

大盘只是起点，真正防止半夜被叫醒的是告警规则。

配置仲裁丢失告警规则

Prometheus 侧接入 AlertManager（alerting段配置 AlertManager 地址即可），再写一条规则。MinIO 官方给的示例规则是监控纠删集健康指标：

groups: - name: minio-alerts rules: - alert: MinIOClusterTolerance expr: minio_cluster_health_erasure_set_status < 1 for: 5m labels: severity: critical

minio_cluster_health_erasure_set_status来自 cluster/health 模块，某个纠删集低于仲裁阈值持续 5 分钟就触发，规则写法细节在 docs/metrics/prometheus/alerts.md 里有完整示例和验证步骤。

容易踩的几个坑 ⚠️

抓取 401/403。现象是 Prometheus Targets 里 job 状态 RED、HTTP 401。原因是指标端点默认走 jwt 鉴权，默认值写在 cmd/metrics-router.go 里。解法：用mc admin prometheus generate生成的bearer_token抓取；只有测试环境才建议设MINIO_PROMETHEUS_AUTH_TYPE=public放行。

单机能抓，挂到负载均衡后面就 404。原因是 Prometheus 请求时会把 Host 头设为domain:port，而不少负载均衡器不认识这条 metrics 路径，直接把请求丢了。解法是在 nginx、HAProxy 这类反向代理上显式把/minio/前缀的请求路由到 MinIO 集群。

桶级指标怎么都是空的。原因：V3 的桶指标默认不返回任何桶的数据，必须在路径里带桶名（如/minio/metrics/v3/bucket/api/<your-bucket>）或传buckets参数，否则该组 gatherer 直接跳过。需要桶级视图时，用仓库里对应的桶仪表盘：

跑通之后，建议把抓取间隔、保留策略按自己的规模调一调，再根据业务加面板。想查指标定义去 docs/metrics/prometheus/list.md 翻清单，想做桶级或复制视图就从 docs/metrics/prometheus/grafana/ 目录里挑对应的 JSON 导入。

【免费下载链接】minioMinIO is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license.项目地址: https://gitcode.com/GitHub_Trending/mi/minio