MinIO 监控实战：Healthcheck 探针与 Prometheus 指标端点完全解析

MinIO 通过一组无鉴权的健康检查端点和一组受鉴权保护的 Prometheus 指标端点，向外暴露完整的可观测性数据。本文基于官方监控指南 docs/metrics/README.md 展开，覆盖 liveness/cluster 探针的工作原理与 Kubernetes 接入方式，以及 cluster、bucket、node、resource 四类 Prometheus 指标端点的鉴权机制、采集配置与典型指标含义，并深入源码印证各端点的实现细节，帮助你为 MinIO 单节点或分布式部署搭建一套可直接运行的 Prometheus 监控方案。

监控体系总览

MinIO 的监控数据分为两大类，均通过 HTTP 端点暴露给外部工具采集：

1. 健康检查探针（Healthcheck Probe）：无需认证，供 Kubernetes 等平台做存活/就绪/集群可维护性判断；
2. Prometheus 探针（Prometheus Probe）：默认需要认证，供 Prometheus 按 pull 模型拉取时序指标。

端点一览（均以 /minio 为保留前缀）：

端点	用途	鉴权
/minio/health/live	存活探针	无
/minio/health/ready	就绪探针	无
/minio/health/cluster	集群写仲裁探针	无
/minio/health/cluster/read	集群读仲裁探针	无
/minio/v2/metrics/cluster	集群级指标（可从任一节点采集全集群数据）	默认 JWT
/minio/v2/metrics/bucket	桶级指标	默认 JWT
/minio/v2/metrics/node	单节点指标（含 Go 运行时与进程指标）	默认 JWT
/minio/v2/metrics/resource	资源级指标（CPU/内存/磁盘/网络等）	默认 JWT
/minio/prometheus/metrics	已废弃的旧版指标端点	默认 JWT

这些路径在路由注册代码中统一定义于 metrics 路由：prometheusMetricsPathLegacy = "/prometheus/metrics" 与四个 v2 路径并存，这也印证了文档中「旧端点已废弃」的说明——代码仍保留兼容处理，但新接入应一律使用 /minio/v2/metrics/*。

Healthcheck 探针详解

端点注册与整体结构

四个健康检查路由统一在 healthcheck 路由 中注册，全部同时支持 GET 与 HEAD 方法：

healthCheckPath            = "/health"
healthCheckLivenessPath    = "/live"
healthCheckReadinessPath   = "/ready"
healthCheckClusterPath     = "/cluster"
healthCheckClusterReadPath = "/cluster/read"
healthCheckPathPrefix      = minioReservedBucketPath + healthCheckPath

因此完整对外路径为 /minio/health/...。

Liveness 探针：/minio/health/live

官方文档说明该探针几乎总是返回 200 OK，仅在配置了 etcd 且 etcd 不可达时失败；失败时 Kubernetes 类平台会重启容器。结合 LivenessCheckHandler 源码 可以看到其设计意图：

• 若对象存储层尚未初始化，会写入 X-Minio-Server-Status: offline 响应头；
• 内部节点间互查请求（携带 X-Minio-Peer-Call 头）直接短路返回 200，避免级联误判；
• 若排队请求数超过 requestsPoolCapacity 上限，返回 ErrBusy（即过载保护）；
• 源码注释明确指出：liveness 检查「不联系外部系统」，以防止外部依赖抖动引发 Pod 被误重启。

典型的 Kubernetes 配置（来自 healthcheck 文档）：

livenessProbe:
  httpGet:
    path: /minio/health/live
    port: 9000
    scheme: HTTP
  initialDelaySeconds: 120
  periodSeconds: 30
  timeoutSeconds: 10
  successThreshold: 1
  failureThreshold: 3

Readiness 探针：/minio/health/ready

就绪探针比 liveness 多做两件事（见 ReadinessCheckHandler）：

1. KMS 可达性：若配置了 KMS，会用 1 分钟超时执行一次 GenerateKey 调用验证密钥服务可用；
2. etcd 可达性：若配置了 etcd，执行一次带超时的 Get("health") 探测。

任一检查失败则返回错误，Kubernetes 会停止向该容器路由流量。参考配置：

readinessProbe:
  httpGet:
    path: /minio/health/ready
    port: 9000
    scheme: HTTP
  initialDelaySeconds: 120
  periodSeconds: 15
  timeoutSeconds: 10
  successThreshold: 1
  failureThreshold: 3

Cluster 探针：/minio/health/cluster 与 /minio/health/cluster/read

写仲裁探针由 ClusterCheckHandler 实现：

• 先经过 checkHealth 前置检查（对象层未就绪、bucket 元数据系统未初始化、IAM 系统未初始化时直接返回 503）；
• 再调用 objLayer.Health(ctx, opts) 跨节点汇聚集群状态，在 globalAPIConfig.getClusterDeadline() 超时窗口内完成；
• 集群具备写仲裁时返回 200 OK，否则返回 503 Service Unavailable。

响应头中携带了诊断信息，文档给出的真实响应示例：

curl http://minio1:9001/minio/health/cluster
HTTP/1.1 503 Service Unavailable
Accept-Ranges: bytes
Content-Length: 0
Server: MinIO
Vary: Origin
X-Amz-Bucket-Region: us-east-1
X-Minio-Write-Quorum: 3
X-Amz-Request-Id: 16239D6AB80EBECF
X-Xss-Protection: 1; mode=block
Date: Tue, 21 Jul 2020 00:36:14 GMT

从源码看，该端点还会附带：

• X-Minio-Write-Quorum：当前写仲裁数；
• X-Minio-Storage-Defaults：是否正在使用默认存储类；
• X-Minio-Healing-Drives：正在被修复的磁盘数（仅在大于 0 时输出）。

读仲裁探针 /minio/health/cluster/read（ClusterReadCheckHandler）逻辑相同，只是以 HealthyRead 判断并返回 X-Minio-Read-Quorum。

维护模式：判断节点能否安全下线

通过查询参数 maintenance=true，可以让探针回答「这台节点现在是否可以摘除做维护」。文档给出的语义在源码中一一对应（healthcheck-handler.go）：

• 集群不健康 + maintenance=true → 412 Precondition Failed，表示摘除该节点会丢失 HA 能力，不要下线；
• 集群不健康 + 非维护模式 → 503 Service Unavailable；
• 健康 → 200 OK，可以安全下线。

curl http://minio1:9001/minio/health/cluster?maintenance=true
HTTP/1.1 412 Precondition Failed
...
X-Minio-Write-Quorum: 3

这一端点特别适合在编排平台（Kubernetes、Ansible 等）滚动升级前做前置检查。此外源码还支持 deployment-type 查询参数，用于按部署形态调整健康判定，可结合 healthcheck 文档 使用。

Prometheus 指标端点与鉴权

鉴权模式：MINIO_PROMETHEUS_AUTH_TYPE

MinIO 的 Prometheus 端点支持两种鉴权模式，由环境变量 MINIO_PROMETHEUS_AUTH_TYPE 控制，默认是 jwt（需要认证）。这一逻辑在 metrics 路由 中非常直观：

authType := prometheusAuthType(strings.ToLower(env.Get(EnvPrometheusAuthType, string(prometheusJWT))))
auth := AuthMiddleware
if authType == prometheusPublic {
    auth = NoAuthMiddleware
}

metricsRouter.Handle(prometheusMetricsV2ClusterPath, auth(metricsServerHandler()))
metricsRouter.Handle(prometheusMetricsV2BucketPath, auth(metricsBucketHandler()))
metricsRouter.Handle(prometheusMetricsV2NodePath, auth(metricsNodeHandler()))
metricsRouter.Handle(prometheusMetricsV2ResourcePath, auth(metricsResourceHandler()))

• 保持默认 jwt 模式时，Prometheus 通过 bearer token 认证，token 需由 mc 生成；
• 设置 MINIO_PROMETHEUS_AUTH_TYPE="public" 后，四个 v2 端点均可匿名抓取，适合内网可信环境：

export MINIO_PROMETHEUS_AUTH_TYPE="public"
minio server ~/test

在 jwt 模式下，AuthMiddleware 做了两层校验：

1. 校验 bearer token 是合法 JWT，且 issuer 必须为 prometheus（即由 mc admin prometheus generate 签发的专用 token）；
2. 通过 IAM 策略检查 PrometheusAdminAction，允许把抓取权限授予专门的监控账号而非主账号。

四类 v2 端点的差异

理解四个端点的关键在于它们各自聚合的数据范围（结合 metrics-v2.go 与 metrics-resource.go 的处理器实现）：

• /minio/v2/metrics/cluster：由 clusterCollector 提供，可从集群任一单节点读取整个集群的指标。对负载均衡后面的多节点部署，只需抓取 LB 地址即可拿到全集群视图，无需知道每个节点地址——这正是监控指南强调的核心能力；
• /minio/v2/metrics/bucket：由 bucketCollector 提供，以桶为中心的指标（桶容量、对象数、按桶的 TTFB 等）；
• /minio/v2/metrics/node：由 nodeCollector 加上 prometheus.NewGoCollector() 和 NewProcessCollector() 注册组成，即文档所说「包含额外的 go metrics 或 process metrics」。由于这些指标是本机视角，需要在每个节点上分别抓取，targets 里列出所有服务器；
• /minio/v2/metrics/resource：由 resourceCollector 提供资源子系统的指标（处理器、内存、磁盘、网络等），同样建议按节点抓取。

典型指标速览

完整的指标定义清单见 metrics 列表文档，这里摘录几个最有代表性的集群级指标：

指标名	含义
minio_cluster_capacity_raw_total_bytes	集群在线原始总容量
minio_cluster_capacity_raw_free_bytes	集群在线原始剩余容量
minio_cluster_capacity_usable_total_bytes	集群可用总容量（扣除纠删码开销等）
minio_cluster_usage_total_bytes	集群总使用量
minio_cluster_drive_online_total / minio_cluster_drive_offline_total	集群在线/离线磁盘数
minio_cluster_ilm_transitioned_bytes	已过渡到存储层的字节数
s3_ttfb_seconds	请求服务耗时直方图，bucket 为 .05, .1, .25, .5, 1, 2.5, 5, 10 秒

其中 s3_ttfb_seconds 在 metrics.go 中定义为 HistogramVec，按 api 标签（桶级版本还带 bucket 标签）分桶，可直接用于 P99 延迟告警。版本信息则通过 minio_version_info{version, commit} gauge 暴露，方便在告警与面板中标注部署版本。

Prometheus 接入实战

以下步骤完整继承自 Prometheus 监控指南，可直接照做。

1. 下载并解压 Prometheus

tar xvfz prometheus-*.tar.gz
cd prometheus-*
./prometheus --help

Prometheus 是单一二进制，支持 --help 查看全部选项。

2. 生成认证模式下的 scrape_configs

如果 MinIO 保持默认 jwt 模式，使用 mc 生成带 bearer token 的抓取配置（token 有时效性，定期重新生成即可）：

mc admin prometheus generate <alias> [METRIC-TYPE]

METRIC-TYPE 可选 cluster、node、bucket、resource，缺省为 cluster。生成结果形如：

# Cluster
scrape_configs:
- job_name: minio-job
  bearer_token: <secret>
  metrics_path: /minio/v2/metrics/cluster
  scheme: http
  static_configs:
  - targets: ['localhost:9000']

# Bucket centric
- job_name: minio-job-bucket
  bearer_token: <secret>
  metrics_path: /minio/v2/metrics/bucket
  scheme: http
  static_configs:
  - targets: ['localhost:9000']

# Node centric（可选，需按节点抓取）
- job_name: minio-job-node
  bearer_token: <secret>
  metrics_path: /minio/v2/metrics/node
  scheme: http
  static_configs:
  - targets: ['localhost:9000']

# Resource centric（可选）
- job_name: minio-job-resource
  bearer_token: <secret>
  metrics_path: /minio/v2/metrics/resource
  scheme: http
  static_configs:
  - targets: ['localhost:9000']

3. public 模式下的简化配置

若设置了 MINIO_PROMETHEUS_AUTH_TYPE="public"，无需 bearer token，一次抓取即可收集集群指标：

scrape_configs:
- job_name: minio-job
  metrics_path: /minio/v2/metrics/cluster
  scheme: http
  static_configs:
  - targets: ['localhost:9000']

桶级指标同理指向 /minio/v2/metrics/bucket。节点级指标必须在每个服务器实例上分别抓取，targets 需要列出全部节点，这样 Grafana 才能对每个节点分别画图：

scrape_configs:
- job_name: minio-job
  metrics_path: /minio/v2/metrics/node
  scheme: http
  static_configs:
  - targets: ['server1:9000','server2:9000','server3:9000','server4:9000']

4. 启动 Prometheus 并验证

把生成的 scrape_configs 段落粘贴进 prometheus.yml，然后启动：

./prometheus --config.file=prometheus.yml

默认 Prometheus Web UI 位于 http://localhost:9090，可以在此确认 MinIO 指标已成功入站。

负载均衡场景注意事项：Prometheus 会对 MinIO 指标端点发出 Host: domain:port 头。若 MinIO 部署在 HAProxy、nginx、pfSense、OPNsense 等负载均衡/反向代理之后，需要确保网络设备能把这些请求正确路由到 MinIO 部署，否则抓取会失败。

可视化与告警

指标入站后，Grafana 是标准的可视化载体：仓库内提供了开箱即用的 Dashboard JSON，包括总览面板 minio-dashboard.json、桶级 minio-bucket.json、节点级 minio-node.json 以及复制相关面板，导入说明见 Grafana 配置文档。

告警方面，Prometheus AlertManager 与 MinIO 相关的告警规则（如纠删码容错阈值）配置在 alerts 文档，可配合 AlertManager 接入通知渠道。

关于已废弃端点

旧版 /minio/prometheus/metrics 端点已废弃：源码中它仍映射到 metricsHandler()（metrics-router.go），但仅注册了基础 collector，指标覆盖面远小于 v2 端点。新环境不应再配置该路径；已有抓取配置应迁移到 /minio/v2/metrics/cluster 等 v2 端点。

小结

• 健康检查走 /minio/health/{live,ready,cluster,cluster/read}，无认证，支持 maintenance=true 判断节点可否安全下线，412 表示摘除会损失 HA；
• 指标采集走 /minio/v2/metrics/{cluster,bucket,node,resource}，默认 JWT 鉴权，可用 mc admin prometheus generate 生成带 token 的 scrape_configs；内网可信环境可设 MINIO_PROMETHEUS_AUTH_TYPE="public" 简化配置；
• cluster 端点一次抓取即可覆盖全集群，是负载均衡部署下的首选；node/resource 端点需按节点逐一抓取以获得 Go 运行时、进程与硬件资源细节；
• 抓取配置落地后，配合仓库提供的 Grafana 面板与告警规则文档，即可形成完整的 MinIO 监控闭环。