MinIO 监控实战Healthcheck 探针与 Prometheus 指标端点完全解析【免费下载链接】minioMinIO is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license.项目地址: https://gitcode.com/GitHub_Trending/mi/minioMinIO 通过一组无鉴权的健康检查端点和一组受鉴权保护的 Prometheus 指标端点向外暴露完整的可观测性数据。本文基于官方监控指南 docs/metrics/README.md 展开覆盖 liveness/cluster 探针的工作原理与 Kubernetes 接入方式以及cluster、bucket、node、resource四类 Prometheus 指标端点的鉴权机制、采集配置与典型指标含义并深入源码印证各端点的实现细节帮助你为 MinIO 单节点或分布式部署搭建一套可直接运行的 Prometheus 监控方案。监控体系总览MinIO 的监控数据分为两大类均通过 HTTP 端点暴露给外部工具采集健康检查探针Healthcheck Probe无需认证供 Kubernetes 等平台做存活/就绪/集群可维护性判断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: 3Readiness 探针/minio/health/ready就绪探针比 liveness 多做两件事见 ReadinessCheckHandlerKMS 可达性若配置了 KMS会用 1 分钟超时执行一次GenerateKey调用验证密钥服务可用etcd 可达性若配置了 etcd执行一次带超时的Get(health)探测。任一检查失败则返回错误Kubernetes 会停止向该容器路由流量。参考配置readinessProbe: httpGet: path: /minio/health/ready port: 9000 scheme: HTTP initialDelaySeconds: 120 periodSeconds: 15 timeoutSeconds: 10 successThreshold: 1 failureThreshold: 3Cluster 探针/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; modeblock 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/readClusterReadCheckHandler逻辑相同只是以HealthyRead判断并返回X-Minio-Read-Quorum。维护模式判断节点能否安全下线通过查询参数maintenancetrue可以让探针回答「这台节点现在是否可以摘除做维护」。文档给出的语义在源码中一一对应healthcheck-handler.go集群不健康 maintenancetrue→412 Precondition Failed表示摘除该节点会丢失 HA 能力不要下线集群不健康 非维护模式 →503 Service Unavailable健康 →200 OK可以安全下线。curl http://minio1:9001/minio/health/cluster?maintenancetrue HTTP/1.1 412 Precondition Failed ... X-Minio-Write-Quorum: 3这一端点特别适合在编排平台Kubernetes、Ansible 等滚动升级前做前置检查。此外源码还支持deployment-type查询参数用于按部署形态调整健康判定可结合 healthcheck 文档 使用。Prometheus 指标端点与鉴权鉴权模式MINIO_PROMETHEUS_AUTH_TYPEMinIO 的 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_TYPEpublic后四个 v2 端点均可匿名抓取适合内网可信环境export MINIO_PROMETHEUS_AUTH_TYPEpublic minio server ~/test在jwt模式下AuthMiddleware 做了两层校验校验 bearer token 是合法 JWT且 issuer 必须为prometheus即由mc admin prometheus generate签发的专用 token通过 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. 下载并解压 Prometheustar xvfz prometheus-*.tar.gz cd prometheus-* ./prometheus --helpPrometheus 是单一二进制支持--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_TYPEpublic无需 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.fileprometheus.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}无认证支持maintenancetrue判断节点可否安全下线412 表示摘除会损失 HA指标采集走/minio/v2/metrics/{cluster,bucket,node,resource}默认 JWT 鉴权可用mc admin prometheus generate生成带 token 的scrape_configs内网可信环境可设MINIO_PROMETHEUS_AUTH_TYPEpublic简化配置cluster端点一次抓取即可覆盖全集群是负载均衡部署下的首选node/resource端点需按节点逐一抓取以获得 Go 运行时、进程与硬件资源细节抓取配置落地后配合仓库提供的 Grafana 面板与告警规则文档即可形成完整的 MinIO 监控闭环。【免费下载链接】minioMinIO is a high-performance, S3 compatible object store, open sourced under GNU AGPLv3 license.项目地址: https://gitcode.com/GitHub_Trending/mi/minio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考