监控与告警

• 1: 使用 Prometheus 进行监控与告警
• 2: 指标与告警
• 3: 将服务日志或审计日志发布到外部服务
• 4: 使用 InfluxDB 进行监控与告警
• 5: Metrics version 2
• 6: 健康检查 API
• 7: 使用 Grafana 监控 Silo 服务端

1 - 使用 Prometheus 进行监控与告警

SILO 20261109 / Console 2.7.0： Console 的 Metrics 页面使用 Metrics V3 指标，按节点聚合并明确区分“真实零值”与“缺失数据”。Overview 页面展示的是 Server 上报的裸盘总容量（而非扣除纠删码开销后的可用容量估算）；存储桶列表为实时读取，对象数量与空间占用则由后台扫描器（或 Console 2.7.0 可选的 console usage-worker）统计。在 SILO 20261109 中，复制工作协程指标在复制工作池不存在时不会触发 panic，并继续保留历史均值和峰值计数（099b7ddf3）；实时批处理指标则保留暂停原因以及跳过或拒绝计数（#325）。详见 Console 2.7.0 发布说明与 Metrics V3 指标映射参考。

• 使用 MinIO 和 Prometheus 进行监控：概览
• 使用 MinIO 和 Prometheus 进行监控：实验

MinIO 使用 Prometheus 数据模型 发布集群、节点、存储桶和资源指标。 本页过程说明了以下内容：

• 配置 Prometheus 服务，抓取并展示 MinIO 部署的指标
• 基于某个 MinIO 指标配置 Alert Rule，以触发 AlertManager 动作

20261109 推荐的 Metrics V3 抓取

新部署以及 Console 2.7.0 的 Metrics 页面应抓取 Metrics V3 指标。使用 mcli 20261109 显式传入 --api-version v3 即可生成配置：

mcli admin prometheus generate mysilo --api-version v3

生成的配置抓取 /minio/metrics/v3 路径并包含所需的 bearer token。将其合并到 Prometheus 配置中，把 targets 设为待监控的各个 SILO 节点，妥善保管 token，并在确认抓取正常后再启用告警规则。你可以按 cluster、system 等类别限制采集子集，但 Console 的完整监控面板依赖对应的指标族，详见命令参考。

• 集群级指标去重： 同一集群的 cluster 指标会由多个节点重复导出，查询时应保留集群标识标签并用 max 或 min 聚合去重，切勿直接跨节点 sum 求和。
• 零值与缺失数据： 部分合法零值默认不导出样本。仅在同生命周期的伴随指标存在时才应补零；抓取失败或后台扫描器尚未产出用量数据时，应保持为“无数据”（no-data）。
• 标签与单位差异： V3 API 指标使用 name 标签，节点指标带 server 标签，磁盘指标带 pool/set/drive 索引，耗时统一以秒为单位。从 V2 迁移仪表盘时需同步调整 PromQL 查询与告警阈值。

下文保留 V2 指标 的抓取与告警配置步骤，供既有仪表盘参考（省略 --api-version 时仍默认生成 V2 配置）。

配置 Prometheus 收集 MinIO 指标并触发告警

1) 生成抓取配置

使用 mc admin prometheus generate 命令生成 Prometheus 执行抓取请求所需的 scrape 配置：

mc admin prometheus generate ALIAS

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/cluster
     scheme: https
     static_configs:
     - targets: [minio.example.net]

mc admin prometheus generate ALIAS node

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job-node
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/node
     scheme: https
     static_configs:
     - targets: [minio-1.example.net, minio-2.example.net, minio-N.example.net]

mc admin prometheus generate ALIAS bucket

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job-bucket
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/bucket
     scheme: https
     static_configs:
     - targets: [minio.example.net]

mc admin prometheus generate ALIAS resource

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job-resource
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/resource
     scheme: https
     static_configs:
     - targets: [minio.example.net]

• 设置合适的 scrape_interval，确保每次抓取操作都能在下一次开始前完成。 推荐值为 60 秒。

  某些部署由于需要抓取的指标数量较多，可能需要更长的抓取间隔。 为降低 MinIO 和 Prometheus Server 的负载，请选择满足监控要求的最长间隔。

• 将 job_name 设置为与该 MinIO 部署相关的值。

  请使用唯一值，以确保该部署的指标与同一 Prometheus 服务采集的其他指标彼此隔离。

• 对于以 MINIO_PROMETHEUS_AUTH_TYPE 设置为 "public" 启动的 MinIO 部署，可以省略 bearer_token 字段。

• 对于未使用 TLS 的 MinIO 部署，请将 scheme 设置为 http。

• 在 targets 数组中设置能够解析到 MinIO 部署的主机名。

  这可以是任意单个节点，也可以是负责处理与 MinIO 节点连接的负载均衡器或代理。

  对于 Kubernetes 基础设施上的 MinIO Tenant，如果使用的是同一集群中的 Prometheus 集群，则可以指定 minio service 的 DNS 名称。 否则，你可以指定已配置为向 MinIO Tenant 路由连接的 ingress 或 load balancer 端点。

2) 使用更新后的配置重启 Prometheus

将上一步生成的目标 scrape_configs job 追加到配置文件中：

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/cluster
     scheme: https
     static_configs:
     - targets: [minio.example.net]

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job-node
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/node
     scheme: https
     static_configs:
     - targets: [minio-1.example.net, minio-2.example.net, minio-N.example.net]

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job-bucket
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/bucket
     scheme: https
     static_configs:
     - targets: [minio.example.net]

global:
   scrape_interval: 60s

scrape_configs:
   - job_name: minio-job-resource
     bearer_token: TOKEN
     metrics_path: /minio/v2/metrics/resource
     scheme: https
     static_configs:
     - targets: [minio.example.net]

使用该配置文件启动 Prometheus 集群：

prometheus --config.file=prometheus.yaml

3) 分析已采集指标

Prometheus 内置 expression browser。 你可以在其中执行查询，以分析已采集的指标。

minio_node_drive_free_bytes{job="minio-job"}[5m]
minio_node_drive_free_inodes{job="minio-job"}[5m]

minio_node_drive_latency_us{job="minio-job"}[5m]

minio_node_drive_offline_total{job="minio-job"}[5m]
minio_node_drive_online_total{job="minio-job"}[5m]

minio_node_drive_total{job="minio-job"}[5m]

minio_node_drive_total_bytes{job="minio-job"}[5m]
minio_node_drive_used_bytes{job="minio-job"}[5m]

minio_node_drive_errors_timeout{job="minio-job"}[5m]
minio_node_drive_errors_availability{job="minio-job"}[5m]

minio_node_drive_io_waiting{job="minio-job"}[5m]

4) 使用 MinIO 指标配置告警规则

你必须在 Prometheus 部署上配置 Alert Rules，以根据已采集的 MinIO 指标触发告警。

以下示例告警规则文件为 MinIO 部署提供了一组基础告警。 你可以修改这些示例，或将其作为构建自定义告警的参考。

groups:
- name: minio-alerts
  rules:
  - alert: NodesOffline
    expr: avg_over_time(minio_cluster_nodes_offline_total{job="minio-job"}[5m]) > 0
    for: 10m
    labels:
      severity: warn
    annotations:
      summary: "Node down in MinIO deployment"
      description: "Node(s) in cluster {{ $labels.instance }} offline for more than 5 minutes"

  - alert: DisksOffline
    expr: avg_over_time(minio_cluster_drive_offline_total{job="minio-job"}[5m]) > 0
    for: 10m
    labels:
      severity: warn
    annotations:
      summary: "Disks down in MinIO deployment"
      description: "Disks(s) in cluster {{ $labels.instance }} offline for more than 5 minutes"

在 Prometheus 配置中，请在 rule_files 键中指定告警文件路径：

rule_files:
- minio-alerting.yml

一旦触发，Prometheus 会将告警发送到已配置的 AlertManager 服务。

仪表板

MinIO 提供 Grafana 仪表板，用于展示由 Prometheus 采集的指标。 更多信息请参见 使用 Grafana 监控 MinIO Server

2 - 指标与告警

MinIO 使用 Prometheus 数据模型 发布指标。你可以使用任意抓取工具从 SILO 拉取指标数据，以执行进一步分析和配置告警。

SILO 20261109（RELEASE.2026-11-09T00-00-00Z）、Console 2.7.0 与 mcli 20261109 将 Metrics V3（/minio/metrics/v3）作为推荐抓取契约。在 SILO 20261109 中，复制工作协程指标在复制工作池不存在时不会触发 panic，并继续保留历史均值和峰值计数（099b7ddf3）；实时批处理作业指标保留暂停原因以及跳过或拒绝计数（#325）。

Version 3 端点

对于 metrics version 3，所有指标都位于基础端点 /minio/metrics/v3 之下。你可以抓取该基础端点一次性收集全部指标，也可以追加可选路径，仅返回特定类别的指标。

例如，以下端点会返回 audit 指标：

http://HOSTNAME:PORT/minio/metrics/v3/audit

将 HOSTNAME:PORT 替换为 SILO 部署的 FQDN 与端口。对于使用负载均衡器管理节点间连接的部署，请指定负载均衡器地址。

默认情况下，SILO 要求在抓取指标端点时进行身份验证。请使用 mcli admin prometheus generate --api-version v3（mcli 20261109）生成所需的 bearer token。你也可以将 MINIO_PROMETHEUS_AUTH_TYPE 设置为 public 以禁用指标端点认证。

相对于基础 URL，SILO 提供以下抓取端点：

各端点对应的完整指标列表，请参见可用的 version 3 指标。

如需在 Console 中启用历史数据可视化，请在部署的每个节点上设置以下环境变量：

• 将 MINIO_PROMETHEUS_URL 设置为 Prometheus 服务的 URL
• 将 MINIO_PROMETHEUS_JOB_ID 设置为分配给已采集指标的唯一 job ID

可用的 version 3 指标

SILO 为集群、API 请求、存储桶以及系统运行状态发布以下各类 V3 指标：

• API 指标
• 审计指标
• 集群指标
• 调试指标
• ILM 指标
• 日志 Webhook 指标
• 通知指标
• 复制指标
• 扫描器指标
• 系统指标

许多指标包含标签，用于标识生成该指标的资源及其他维度信息。

API 指标

当前节点所服务请求的统计指标。

/api/requests

/bucket/api

审计指标

审计日志发送状态相关指标。

/audit

集群指标

整个集群范围的运行指标。

/cluster/config

/cluster/erasure-set

/cluster/health

/cluster/iam

/cluster/usage/buckets

/cluster/usage/objects

调试指标

来自 Prometheus Go Client 基础收集器的标准 Go 运行时指标。

ILM 指标

对象生命周期管理（ILM）子系统指标。

/ilm

日志 Webhook 指标

日志 Webhook 投递指标。

/logger/webhook

通知指标

存储桶事件通知相关指标。

/notification

复制指标

站点复制与存储桶复制相关指标。

/replication

/bucket/replication

扫描器指标

后台扫描器运行指标。

/scanner

系统指标

SILO 进程及所在节点的系统指标。

/system/drive

/system/memory

/system/cpu

/system/network/internode

/system/process

3 - 将服务日志或审计日志发布到外部服务

MinIO 会将所有 silo server 操作输出到系统控制台。如何读取这些日志取决于 server 进程的管理方式。例如，如果 server 通过 systemd 服务管理，可以使用 journalctl -u SERVICENAME.service 读取日志（将 SERVICENAME 替换为服务名称，例如 silo）。

MinIO 还支持将服务日志和审计日志发布到 HTTP Webhook。

• 服务日志 包含与系统控制台中相同的 silo server 操作日志。服务日志适用于常规监控与运维排障。
• 审计日志 会以更细粒度描述 MinIO 部署上的每一次操作。审计日志适用于要求对操作进行详细追踪的安全标准与合规规范。

MinIO 会将日志作为 JSON 文档，通过 PUT 请求发送到每个已配置端点。端点服务器负责处理这些 JSON 文档。MinIO 要求显式配置每个 Webhook 端点，默认情况下 不会 向 Webhook 发布日志。

通过 mc admin config set 配置时，SILO 会在所有集群节点上动态重载 logger_webhook、audit_webhook 和 audit_kafka 目标，无需整集群重启（若启动时通过环境变量覆盖配置，环境变量优先且修改后仍需重启）。在 SILO 20261109 中，对端节点配置重载会在服务端进程生命周期内保持活跃的 audit_webhook、logger_webhook 和 audit_kafka 目标持续运行，修复了重载请求返回后对端节点停止目标工作协程并丢弃日志的问题（#259）。

将服务日志发布到 HTTP Webhook

你可以通过环境变量 或 运行时配置项，配置一个新的 HTTP Webhook 端点，让 MinIO 将 silo server 日志发布到该端点。

export MINIO_LOGGER_WEBHOOK_ENABLE_<IDENTIFIER>="on"
export MINIO_LOGGER_WEBHOOK_ENDPOINT_<IDENTIFIER>="https://webhook-1.example.net"
export MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_<IDENTIFIER>="TOKEN"

set MINIO_LOGGER_WEBHOOK_ENABLE_<IDENTIFIER>="on"
set MINIO_LOGGER_WEBHOOK_ENDPOINT_<IDENTIFIER>="https://webhook-1.example.net"
set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_<IDENTIFIER>="TOKEN"

export MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"

set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"

export MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"

set MINIO_LOGGER_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"

mc admin config set ALIAS/ logger_webhook:IDENTIFIER  \
   endpoint="https://webhook-1.example.net"           \
   auth_token="TOKEN"

将审计日志发布到 HTTP Webhook

你可以通过环境变量 或 运行时配置项，配置一个新的 HTTP Webhook 端点，让 MinIO 将审计日志发布到该端点：

export MINIO_AUDIT_WEBHOOK_ENABLE_<IDENTIFIER>="on"
export MINIO_AUDIT_WEBHOOK_ENDPOINT_<IDENTIFIER>="https://webhook-1.example.net"
export MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_<IDENTIFIER>="TOKEN"
export MINIO_AUDIT_WEBHOOK_CLIENT_CERT_<IDENTIFIER>="cert.pem"
export MINIO_AUDIT_WEBHOOK_CLIENT_KEY_<IDENTIFIER>="cert.key"

set MINIO_AUDIT_WEBHOOK_ENABLE_<IDENTIFIER>="on"
set MINIO_AUDIT_WEBHOOK_ENDPOINT_<IDENTIFIER>="https://webhook-1.example.net"
set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_<IDENTIFIER>="TOKEN"
set MINIO_AUDIT_WEBHOOK_CLIENT_CERT_<IDENTIFIER>="cert.pem"
set MINIO_AUDIT_WEBHOOK_CLIENT_KEY_<IDENTIFIER>="cert.key"

export MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"

set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_myendpoint="Bearer 1a2b3c4f5e"

export MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"

set MINIO_AUDIT_WEBHOOK_AUTH_TOKEN_xyz="ServiceXYZ 1a2b3c4f5e"

mc admin config set ALIAS/ audit_webhook:IDENTIFIER  \
   endpoint="https://webhook-1.example.net"          \
   auth_token="TOKEN"                                \
   client_cert="cert.pem"                            \
   client_key="cert.key"

审计日志结构

MinIO 审计日志类似于以下 JSON 文档：

• api.timeToFirstByte 和 api.timeToResponse 字段以纳秒表示。

• 对于 纠删码部署， tags.objectErasureMap 提供与对象相关的以下详细信息：

  • 执行该对象操作所在的 服务器池。
  • 执行该对象操作所在的 纠删码集合。
  • 参与该对象操作的纠删码集合驱动器列表。

{
   "version": "1",
   "deploymentid": "8ca2b7ad-20cf-4d07-9efb-28b2f519f4a5",
   "time": "2024-02-29T19:39:25.744431903Z",
   "event": "",
   "trigger": "incoming",
   "api": {
      "name": "CompleteMultipartUpload",
      "bucket": "data",
      "object": "test-data.csv",
      "status": "OK",
      "statusCode": 200,
      "rx": 267,
      "tx": 358,
      "txHeaders": 387,
      "timeToFirstByte": "2096989ns",
      "timeToFirstByteInNS": "2096989",
      "timeToResponse": "2111986ns",
      "timeToResponseInNS": "2111986"
   },
   "remotehost": "127.0.0.1",
   "requestID": "17B86CB0ED88EBE9",
   "userAgent": "MinIO (linux; amd64) minio-go/v7.0.67 mc/RELEASE.2024-02-24T01-33-20Z",
   "requestPath": "/data/test-data.csv",
   "requestHost": "minio.example.net:9000",
   "requestQuery": {
      "uploadId": "OGNhMmI3YWQtMjBjZi00ZDA3LTllZmItMjhiMmY1MTlmNGE1LmU3MjNlNWI4LTNiYWYtNDYyNy1hNzI3LWMyNDE3NTVjMmMzNw"
   },
   "requestHeader": {
      "Accept-Encoding": "zstd,gzip",
      "Authorization": "AWS4-HMAC-SHA256 Credential=minioadmin/20240229/us-east-1/s3/aws4_request, SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date, Signature=ccb3acdc1763509a88a7e4a3d7fe431ef0ee5ca3f66ccb430d5a09326e87e893",
      "Content-Length": "267",
      "Content-Type": "application/octet-stream",
      "User-Agent": "MinIO (linux; amd64) minio-go/v7.0.67 mc/RELEASE.2024-02-24T01-33-20Z",
      "X-Amz-Content-Sha256": "d61969719ee94f43c4e87044229b7a13b54cab320131e9a77259ad0c9344f6d3",
      "X-Amz-Date": "20240229T193925Z"
   },
   "responseHeader": {
      "Accept-Ranges": "bytes",
      "Content-Length": "358",
      "Content-Type": "application/xml",
      "ETag": "1d9fdc88af5e74f5eac0a3dd750ce58e-2",
      "Server": "MinIO",
      "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
      "Vary": "Origin,Accept-Encoding",
      "X-Amz-Id-2": "dd9025bab4ad464b049177c95eb6ebf374d3b3fd1af9251148b658df7ac2e3e8",
      "X-Amz-Request-Id": "17B86CB0ED88EBE9",
      "X-Content-Type-Options": "nosniff",
      "X-Xss-Protection": "1; mode=block"
   },
   "tags": {
      "objectLocation": {
            "name": "Mousepad Template-v03final.jpg",
            "poolId": 1,
            "setId": 1,
            "disks": [
               "/mnt/drive-1",
               "/mnt/drive-2",
               "/mnt/drive-3",
               "/mnt/drive-4"
            ]
      }
   },
   "accessKey": "minioadmin"
}

4 - 使用 InfluxDB 进行监控与告警

MinIO 使用 Prometheus 数据模型 发布集群和节点指标。 InfluxDB 支持抓取 MinIO 指标数据，用于监控和告警。

本页介绍以下内容：

• 配置 InfluxDB 服务，抓取并展示 MinIO 部署的指标
• 基于 MinIO 指标配置告警

对于 Kubernetes 上的 MinIO 部署，本文默认已具备 Ingress、负载均衡器等必要的网络控制组件，以便 MinIO 租户与 InfluxDB 服务之间能够互相访问。

配置 InfluxDB 收集 MinIO 指标并触发告警

1. 配置对 MinIO 指标的公开访问

   在 MinIO 部署的所有节点上，将 MINIO_PROMETHEUS_AUTH_TYPE 环境变量设置为 "public"。 随后可重启部署，以允许公开访问 MinIO 指标。

   可通过对指标端点执行 curl 来验证变更是否生效：

   curl https://HOSTNAME/minio/v2/metrics/cluster

   将 HOSTNAME 替换为访问 MinIO 部署所使用的负载均衡器或反向代理 URL。 也可以将任意单个节点写成 HOSTNAME:PORT，即在节点主机名之外再指定 MinIO server API 端口。

   响应正文中应包含已采集的 MinIO 指标列表。

2. 登录 InfluxDB UI 并创建 Bucket

   选择用于存储 MinIO 指标的 Organization。

   创建一个 New Bucket，用于存储该 MinIO 部署的指标。

3. 创建新的抓取源

   创建一个 新的 InfluxDB Scraper。

   指定 MinIO 部署的完整 URL，其中包含指标端点：

   https://HOSTNAME/minio/v2/metrics/cluster

   将 HOSTNAME 替换为访问 MinIO 部署所使用的负载均衡器或反向代理 URL。 也可以将任意单个节点写成 HOSTNAME:PORT，即在节点主机名之外再指定 MinIO server API 端口。

4. 验证数据

   使用 DataExplorer 可视化已采集的 MinIO 数据。

   例如，可针对 minio_cluster_capacity_usable_total_bytes 和 minio_cluster_capacity_usable_free_bytes 设置过滤条件，以比较 MinIO 部署中的总可用空间和剩余可用空间。

5. 配置 Check

   基于某个 MinIO 指标创建一个新的 Check。

   以下示例 Check 规则为 MinIO 部署提供了一组基础告警。 可按需修改这些示例，或将其作为构建自定义 Check 的参考。

   • 创建一个名为 MINIO_NODE_DOWN 的 Threshold Check。

     将过滤条件设置为 minio_cluster_nodes_offline_total 键。

     在值大于 1 时，将 Thresholds 设置为 WARN。

   • 创建一个名为 MINIO_QUORUM_WARNING 的 Threshold Check。

     将过滤条件设置为 minio_cluster_drive_offline_total 键。

     当该值比已配置的 纠删码校验值 少 1 时，将 Thresholds 设置为 CRITICAL。

     例如，使用 EC:4 的部署应将该值设置为 3。

   配置 Notification endpoints 和 Notification rules，使各类 Check 都能触发适当响应。

5 - Metrics version 2

MinIO 使用 Prometheus 数据模型 发布集群和节点指标。你可以使用任意抓取工具从 SILO 拉取指标数据，以执行分析和配置告警。

SILO 20261109 / Console 2.7.0： 新部署以及 Console 2.7.0 的 Metrics 页面建议抓取 Metrics V3（通过 mcli 20261109 执行 mcli admin prometheus generate ALIAS --api-version v3 生成配置；参见 Console 2.7.0 Metrics V3 映射参考）。在 SILO 20261109 中，复制工作协程指标在复制工作池不存在时不会触发 panic，并继续保留历史均值和峰值计数（099b7ddf3）；实时批处理作业指标保留暂停原因以及跳过或拒绝计数（#325）。

Version 2 端点

Metrics version 2 将指标划分为以下三个类别：

• 集群指标
• 存储桶指标
• 资源指标

每个 v2 端点都会返回其所属类别的全部指标。例如，抓取以下端点会返回所有集群指标：

http://HOSTNAME:PORT/minio/v2/metrics/cluster

仅访问基础端点 /minio/v2/metrics/ 也会返回集群指标。

如需更灵活的抓取方式和更完整的指标集合，请使用 metrics version 3。

现有部署仍可继续使用 version 2 指标 和 Grafana 仪表板。

MinIO Grafana 仪表板

MinIO 提供两个 Grafana 仪表板，用于可视化 v2 指标。有关为 Grafana 配置兼容 Prometheus 数据源的完整说明，请参见 Prometheus 关于 Grafana 支持的文档。

可用的 version 2 指标

以下各节描述 version 2 的端点与指标。

http://HOSTNAME:PORT/minio/v2/metrics/cluster

http://HOSTNAME:PORT/minio/v2/metrics/bucket

http://HOSTNAME:PORT/minio/v2/metrics/resource

• 集群指标
• 存储桶指标
• 资源指标

集群指标

SILO 在集群级别采集以下指标。指标可能带有一个或多个标签（例如计算该指标的节点标识）。

每次采集可从任意一个 SILO 节点通过以下 URL 拉取：

https://HOSTNAME:PORT/minio/v2/metrics/cluster

将 HOSTNAME:PORT 替换为部署的主机名和端口；部署前存在负载均衡器时，请填写负载均衡器地址。

审计指标

集群容量指标

集群磁盘指标

集群 ILM 指标

集群 KMS 指标

集群健康指标

集群复制指标

标注为“仅站点复制”的指标仅在配置了站点复制的部署上产出；对于配置了存储桶复制或批量复制的部署，相应指标会在存储桶指标端点下产出。

节点复制指标

在配置了站点复制、存储桶复制或批量复制时反映节点级复制队列与链路状态。

自愈指标

节点间网络指标

存储桶通知指标

S3 API 请求指标

软件版本指标

磁盘指标

身份与访问管理（IAM）指标

信息生命周期管理（ILM）指标

远端分层指标

系统指标

扫描器指标

存储桶指标

SILO 在存储桶级别采集以下指标。每个指标包含 bucket 标签用于标识存储桶，并可能包含计算节点等附加标签。

每次采集可从任意一个 SILO 节点通过以下 URL 拉取：

https://HOSTNAME:PORT/minio/v2/metrics/bucket

将 HOSTNAME:PORT 替换为部署的主机名和端口；部署前存在负载均衡器时，请填写负载均衡器地址。

分布指标

复制指标

以下指标仅在配置了存储桶复制或批量复制的部署上产出；对于配置了站点复制的部署，对应指标在集群指标端点下产出。

流量指标

用量指标

请求指标

资源指标

SILO 在节点级别采集以下资源指标。每个指标包含 server 标签用于标识所属节点，并可能包含磁盘路径、网卡名称等附加标签。

每次采集可从任意一个 SILO 节点通过以下 URL 拉取：

https://HOSTNAME:PORT/minio/v2/metrics/resource

将 HOSTNAME:PORT 替换为部署的主机名和端口；部署前存在负载均衡器时，请填写负载均衡器地址。

磁盘资源指标

网络接口指标

CPU 指标

内存指标

6 - 健康检查 API

MinIO 提供无需身份验证的端点，用于探测节点在线状态以及集群 高可用性，从而执行简单健康检查。这些端点返回一个 HTTP 状态码，用于表示底层资源是否健康，或是否满足读写仲裁。MinIO 不会通过这些端点暴露任何其他数据。

原生探针与应用启动

SILO 内置 silo healthcheck 子命令，可直接探测本地 /minio/health/* HTTP 端点，无需在容器内提供 curl、mc 或 shell：

silo healthcheck [FLAGS] [live|ready|cluster|cluster-read]

• CHECK 选择探测目标端点：live（默认）、ready、cluster 或 cluster-read。
• --address（或 MINIO_ADDRESS，默认 :9000，空主机名解析为 127.0.0.1）指定目标 HOST:PORT；当 --certs-dir 中存在 public.crt 与 private.key 时自动切换为 HTTPS。
• --url（或 MINIO_HEALTHCHECK_URL）使用显式 http[s]://HOST:PORT 基址覆盖 --address 与 TLS 自动判定。
• --maintenance 仅适用于 cluster，附加 ?maintenance=true，并在服务端返回 HTTP 412 Precondition Failed 时以退出码 1 结束。
• --timeout 设置探测总超时（live 与 ready 默认 5s；cluster 与 cluster-read 默认 15s）。
• 全局参数 --certs-dir、--json 与 --quiet 控制证书查找与输出格式。探测健康时退出码为 0，其余情况均为 1。

silo healthcheck ready 调用 /minio/health/ready。该端点检查 HTTP 请求队列容量以及已配置的 KMS 和 etcd 可达性，在存储层和 IAM 完成加载前也可能返回 200 OK。这一行为保证了分布式节点的启动互联；Kubernetes 无头服务必须保留 publishNotReadyAddresses: true。不要将 cluster 配置为容器存活探针或节点互联的前置条件。

-distroless 容器镜像将内置 HEALTHCHECK 配置为 /usr/bin/silo healthcheck ready。因此，Docker Compose 的 depends_on: condition: service_healthy 仅确认该就绪探针通过，不代表 S3 数据面已可读写。即使改查 cluster，仍存在下文说明的远端磁盘重连窗口。需要立即访问对象的依赖应用必须执行有界超时的签名 S3 写入与回读检查，并在失败时中止启动或升级流程。请使用专用存储桶和唯一探测对象键，并在校验完成后清理。

节点存活

使用以下端点测试 SILO 服务端 HTTP 监听器是否正在处理请求：

curl -I https://minio.example.net:9000/minio/health/live

将 https://minio.example.net:9000 替换为待检查服务端的 DNS 主机名和端口。

HTTP 监听器启动后，即使对象层尚未完成加载，/minio/health/live 也会立即返回 200 OK（存储初始化期间响应头包含 x-minio-server-status: offline）。当排队请求数超过 API 请求池容量上限时，该端点返回 503 Service Unavailable。由于存活检查失败在 Kubernetes 中会触发 Pod 重启，/minio/health/live 不访问任何外部系统（不访问 KMS，也不访问 etcd），避免在磁盘初始化缓慢或外部服务故障期间误重启容器。

存活探针仅检查当前客户端能否连通服务端 HTTP 监听器以及请求队列是否有余量。建议配置 Prometheus 告警，使用 指标 v3 的 minio_cluster_health_nodes_offline_count 或 指标 v2 的 minio_cluster_nodes_offline_total 检测集群离线节点。

节点就绪

使用以下端点测试进程就绪状态及已配置的外部依赖：

curl -I https://minio.example.net:9000/minio/health/ready

将 https://minio.example.net:9000 替换为待检查服务端的 DNS 主机名和端口。

/minio/health/ready 检查与 /minio/health/live 相同的 HTTP 请求队列容量，并在配置了 KMS 或 etcd 时进一步验证 KMS 密钥生成与 etcd 健康读写。未配置 KMS 和 etcd 时，/minio/health/ready 与 /minio/health/live 走相同的检查路径。与 /minio/health/live 一样，/minio/health/ready 在对象层或 IAM 完成加载前也可返回 200 OK（附带 x-minio-server-status: offline），以便集群启动阶段完成对端节点发现。

集群写仲裁

使用以下端点测试 MinIO 集群是否具备 写仲裁：

curl -I https://minio.example.net:9000/minio/health/cluster

将 https://minio.example.net:9000 替换为待检查 MinIO 集群中某个节点的 DNS 主机名。 对于使用负载均衡器管理传入连接的集群，请指定负载均衡器的主机名。

返回 200 OK 表示 MinIO 集群当前有足够的 MinIO server 在线，可满足写仲裁。 返回 503 Service Unavailable 表示集群当前不具备写仲裁。

单靠 healthcheck probe 无法判断某个 MinIO server 是否离线，也无法判断其是否正在正常处理写操作。 它只能根据配置的 纠删码校验值 判断当前是否有足够的 MinIO server 在线，以满足写仲裁要求。 建议配置 Prometheus 告警，使用以下指标检测 MinIO 集群中的潜在问题或错误：

• minio_cluster_nodes_offline_total：在一个或多个 MinIO 节点离线时触发告警。
• minio_node_drive_free_bytes：在集群可用磁盘空间不足时触发告警。

集群读仲裁

使用以下端点测试 MinIO 集群是否具备 读仲裁：

curl -I https://minio.example.net:9000/minio/health/cluster/read

将 https://minio.example.net:9000 替换为待检查 MinIO 集群中某个节点的 DNS 主机名。 对于使用负载均衡器管理传入连接的集群，请指定负载均衡器的主机名。

返回 200 OK 表示 MinIO 集群当前有足够的 MinIO server 在线，可满足读仲裁。 返回 503 Service Unavailable 表示集群当前不具备读仲裁。

单靠 healthcheck probe 无法判断某个 MinIO server 是否离线，也无法判断其是否正在正常处理读操作。 它只能根据配置的 纠删码校验值 判断当前是否有足够的 MinIO server 在线，以满足读仲裁要求。 建议配置 Prometheus 告警，使用 minio_cluster_nodes_offline_total 指标检测一个或多个 MinIO 节点是否离线。

集群维护检查

使用以下端点测试在将指定 MinIO server 下线维护时， MinIO 集群是否仍能同时维持 读 和 写：

curl -I https://minio.example.net:9000/minio/health/cluster?maintenance=true

将 https://minio.example.net:9000 替换为待检查 MinIO 集群中某个节点的 DNS 主机名。 对于使用负载均衡器管理传入连接的集群，请指定负载均衡器的主机名。

返回 200 OK 表示 MinIO 集群当前有足够的 MinIO server 在线，可满足写仲裁。 返回 412 Precondition Failed 表示如果该 MinIO server 离线，集群将失去仲裁。

单靠 healthcheck probe 无法判断某个 MinIO server 是否离线。 它只能判断在该节点因维护而下线后，是否仍有足够的 MinIO server 在线，以根据配置的 纠删码校验值 满足读写仲裁要求。 建议配置 Prometheus 告警，使用 minio_cluster_nodes_offline_total 指标检测一个或多个 MinIO 节点是否离线。

重启后的就绪窗口

SILO 20261109 保留这一机制：集群健康检查实现根据各对端节点上报的磁盘状态评估仲裁。恢复业务流量前，请先检查两个集群端点，再验证真实 S3 读写。完整的探针规格见健康检查探针语义。

上述 HTTP 健康端点均不能证明收到请求的节点在重启后已能立即服务对象读写。每个节点通过后台监控循环连接对端节点的远端纠删码磁盘。启动时未能连上的远端磁盘会在本节点保持未挂载状态，直到后续轮次重连成功。监控循环在每轮结束后等待 15 秒，因此 15 秒只是两次重连尝试之间的最短间隔，而非恢复耗时上限。

在远端磁盘尚未重连期间，该节点的 /minio/health/live、/minio/health/ready、两个 /minio/health/cluster* 端点、mc admin info 与 mcli ready 都可能报告健康。这是因为集群端点汇总各节点对自身本地磁盘的上报结果，而不检查当前接收节点已挂载哪些远端磁盘。在此窗口内，经由该节点的 PUT 可能返回 503 SlowDownWrite，读取其他节点刚写入的对象也可能在远端磁盘重连完成前失败。

升级与故障切换自动化流程必须以有界超时的 S3 数据面检查作为放行门槛，而不能仅依赖 HTTP 健康端点：

1. 设置固定的总截止时间，并禁用 SDK 自动重试。
2. 经由每个重启节点各写入一个签名探测小对象，按剩余截止时间分配单次请求超时。
3. 经由每个节点回读所有已确认写入的探测对象，校验字节内容和版本 ID。
4. 将“首次可用 S3 I/O 耗时”与 HTTP 探针就绪状态分开记录，并在校验完成后清理探测对象。

该检查可验证探测对象键所命中纠删集在当时的抽样 S3 读写路径，但不证明所有纠删集磁盘均已齐全或具备再次容忍节点丢失的余量。HTTP 健康端点仍应用于其设计用途：进程存活、外部依赖就绪与上报仲裁检查。

7 - 使用 Grafana 监控 Silo 服务端

无论指标存储在何处，Grafana 都允许你对其进行查询、可视化、告警和分析。

前提条件

• 已有 Prometheus 部署，并配置 Alert Manager
• 已有可通过网络访问 Prometheus 部署的 MinIO 部署
• 已安装 Grafana

MinIO Grafana 仪表板

MinIO 提供了若干官方 Grafana 仪表板，可从 Grafana Dashboard 门户下载。

1. MinIO Server 指标
2. MinIO 存储桶指标
3. MinIO 复制指标

若要跟踪 Grafana 仪表板的变更，可以查看 MinIO Server GitHub 仓库中 server 或 bucket 仪表板对应的 JSON 文件。

MinIO Server 指标仪表板

请从 Grafana 上的 MinIO 组织仪表板目录选择与部署所暴露指标版本兼容的服务端仪表板。

MinIO 为 MinIO Server 指标提供了专用的 Grafana 仪表板。 关于该仪表板配置的详细信息，请参见 GitHub 上的 JSON 文件。

对于启用了 服务端加密 的 MinIO 部署（包括 SSE-KMS 或 SSE-S3），该仪表板还包含 KMS 指标。 这些指标包括状态、请求错误率和请求成功率。

MinIO 存储桶指标仪表板

请从 Grafana 上的 MinIO 组织仪表板目录选择与部署所暴露指标版本兼容的存储桶仪表板。

存储桶指标可以通过 GitHub 上的 bucket JSON 文件 在 Grafana 仪表板中查看。

MinIO 节点指标仪表板

节点指标可以通过 GitHub 上的 node JSON 文件 在 Grafana 仪表板中查看。

MinIO 复制指标仪表板

请从 Grafana 上的 MinIO 组织仪表板目录选择与部署所暴露指标版本兼容的复制仪表板。

集群复制指标可以通过 GitHub 上的 cluster replication JSON 文件 在 Grafana 仪表板中查看。