如何用Nginx配合blackbox_exporter实现黑盒探测？

Nginx 作为反向代理或负载均衡时，单看进程状态和连接数常常无法发现上游服务已经异常。黑盒探测让监控系统模拟真实客户端请求，绕过内部指标，直接判断对外服务是否可用。本文以 blackbox_exporter 为核心，说明如何把 Nginx 的 HTTP 探测结果接入 Prometheus，并建立可用性与延迟告警。

一、Nginx 黑盒探测解决的问题

Nginx 自身能提供连接数、请求数、上游响应时间等指标，但这些指标依赖 Nginx 存活且配置正确。如果 Nginx 配置错误导致 502，或上游服务不可达但 Nginx 进程正常，内部指标可能显示为健康。黑盒探测从外部发起请求，观察最终响应，能发现用户真正感受到的故障。

blackbox_exporter 作为 Prometheus 生态的黑盒探针，支持 HTTP、HTTPS、TCP、DNS、ICMP 等协议。对 Nginx 最常用的是 HTTP 探针，可以校验状态码、响应体、TLS 证书有效期、首字节时间等。它不关心 Nginx 内部实现，只回答这个地址现在能不能正常访问。

把这种外部视角和白盒指标结合，可以快速区分是 Nginx 自身问题还是上游业务故障。例如 probe_success 为 0 但 Nginx 进程指标正常，说明问题出在 Nginx 配置或上游；如果两者都异常，则优先排查主机与网络。

二、安装 blackbox_exporter 并定义 HTTP 探针

从 Prometheus 官方发布页下载对应平台的二进制文件，解压后可以得到 blackbox_exporter 可执行文件。默认监听 9115 端口，对外提供 /probe 接口。为了让探针知道如何探测目标，需要准备一份 blackbox.yml 配置文件，定义探测模块。

下面是一个最小可用的 HTTP 探测模块配置。它定义了 http_2xx 模块，使用 HTTP 协议，超时时间为 5 秒，只把 200、301、302 状态码视为成功，并使用 IPv4 优先策略。

modules:
  http_2xx:
    prober: http
    timeout: 5s
    http:
      valid_status_codes: [200, 301, 302]
      method: GET
      preferred_ip_protocol: "ip4"
  tcp_connect:
    prober: tcp
    timeout: 5s
    tcp:
      preferred_ip_protocol: "ip4"

如果还需要监控 HTTPS 证书过期时间，可以在 http 配置中增加 fail_if_not_expiring_soon 等参数。对于非 HTTP 场景，可以使用 tcp_connect 模块直接测试 Nginx 的 443 端口是否可连接，避免证书或 HTTP 层以外的网络问题影响判断。

启动 blackbox_exporter 的命令如下。生产环境建议使用 systemd 或容器方式托管，并限制公网访问 9115 端口。

./blackbox_exporter --config.file=/etc/blackbox_exporter/blackbox.yml --web.listen-address=:9115

三、Prometheus 抓取配置与标签重写

blackbox_exporter 的 /probe 接口需要 target 参数指定探测目标，使用 module 参数指定探测模块。Prometheus 不能直接抓取一个地址列表并自动传参，需要通过 relabel_configs 把静态配置中的目标地址改写为参数，然后把请求转发到 blackbox_exporter。

完整抓取配置如下。核心思路是先把 __address__ 的值赋给 __param_target，同时保留原始目标作为 instance 标签，最后把实际抓取地址替换为本地 blackbox_exporter 的 9115 端口。

scrape_configs:
  - job_name: 'blackbox-nginx'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://www.ipipp.com
          - http://127.0.0.1:8080
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9115

抓取后得到的指标中，probe_success 最核心，值为 1 或 0；probe_http_status_code 表示实际状态码；probe_duration_seconds 为总耗时；probe_http_duration_seconds 可以按阶段拆分，例如 connect、tls、processing 等。这些指标足以支撑可用性、性能和证书监控。

如果 Nginx 后面有多个域名，建议使用 file_sd_configs 或 http_sd_configs 动态维护目标列表，而不是全部写死在 static_configs 中。这样可以避免每次新增站点都要重启 Prometheus 或修改主配置文件。

四、告警规则与看板设计

针对 Nginx 黑盒探测，最直接的告警规则是判断 probe_success 是否连续为 0。下面示例表示如果某个实例探测失败持续 2 分钟，就触发 critical 级别告警。

groups:
  - name: nginx_blackbox
    rules:
      - alert: NginxProbeFailed
        expr: probe_success{job="blackbox-nginx"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: 'Nginx endpoint {{ $labels.instance }} probe failed'
          description: 'The blackbox probe failed for {{ $labels.instance }} during the last 2 minutes.'

除了失败告警，还可以针对响应状态码异常、响应时间升高以及 TLS 证书即将过期设置规则。例如使用 probe_http_duration_seconds 的分位数来判断 P99 延迟是否超过阈值，或者用 probe_ssl_earliest_cert_expiry 判断证书剩余天数。

在 Grafana 看板中，建议以 instance 维度展示 probe_success，使用类似 UP 状态的面板；用 probe_duration_seconds 展示响应延迟分位数；用证书剩余时间指标展示 TLS 风险。阈值设置时需要注意单位，延迟指标通常以秒为单位，证书剩余时间以秒或天为单位。

最后，黑盒探测的日志和指标可以配合 Alertmanager 路由到不同接收者。故障复盘时，黑盒探测提供的外部视角时间线能帮助定位是网络抖动、DNS 解析失败、Nginx 配置错误还是上游超时。公网探测时避免直接暴露带有敏感信息的内部接口地址。

Nginxblackbox_exporter黑盒监控修改时间：2026-10-04 05:05:39