2393 字
12 分钟
监控与可观测性:blackbox_exporter 黑盒探测——站在用户的位置看你的服务

一个经典场景:监控全绿,用户说打不开#

服务器 CPU 正常、内存充足、Nginx 进程活着,Prometheus 仪表盘上一片绿色。然后用户发来截图:网站打不开。

问题出在哪?出在你站的位置不对。node_exporter、进程探活这类白盒监控站在服务器内部往外看,看到的是「进程还活着」;而用户站在互联网另一端,他经历的是 DNS 解析、TCP 建连、TLS 握手、HTTP 响应这一整条链路——任何一环断了,他看到的都是打不开。证书过期、DNS 解析被改错、防火墙误封、运营商线路故障,这些事故在白盒视角里全是隐形的。

黑盒探测补的就是这个视角:不关心服务内部怎么实现,只从外部模拟一次真实访问,记录成没成、花了多久。Prometheus 生态里干这件事的标准工具就是 blackbox_exporter。本篇把它和Prometheus 本体接起来,再顺手解决证书到期告警这个高频刚需。

项目地址:https://github.com/prometheus/blackbox_exporter

blackbox_exporter 是怎么工作的#

它的模型很简单:自己不主动探测任何目标,而是等 Prometheus 来问。Prometheus 通过 relabel 把「要探测的目标」作为参数传给它,它按指定的模块(module)对目标发起一次探测,把结果翻译成指标返回。一次探测产出的核心指标有:

指标含义
probe_success探测成功为 1,失败为 0,最重要的告警依据
probe_duration_seconds整个探测过程的总耗时
probe_http_status_codeHTTP 探测实际拿到的状态码
probe_ssl_earliest_cert_expiry目标证书的最早到期时间(Unix 时间戳),证书告警靠它
probe_dns_lookup_time_secondsDNS 解析耗时
probe_http_duration_secondsHTTP 各阶段耗时(解析、建连、TLS、处理、传输分段)

探测器(prober)内置四种:http、tcp、dns、icmp,再加上 grpc。用哪种、什么参数算成功,都写在它自己的配置文件里,这就是模块。

Docker 部署#

官方镜像 prom/blackbox-exporter,默认端口 9115。先写好配置文件再启动,配置目录只读挂载:

Terminal window
mkdir -p /opt/blackbox && cd /opt/blackbox

把下面的 blackbox.yml 放进去,然后用 Docker Compose 拉起:

services:
blackbox:
image: prom/blackbox-exporter:latest
container_name: blackbox
restart: unless-stopped
command:
- --config.file=/config/blackbox.yml
ports:
- "127.0.0.1:9115:9115"
volumes:
- ./blackbox.yml:/config/blackbox.yml:ro
cap_add:
- NET_RAW

cap_add: NET_RAW 是给 ICMP 探测用的——ping 探测需要原始套接字能力,普通容器权限不够,不加这一段 ICMP 模块永远失败。用不到 ping 可以去掉。

配置模块:blackbox.yml#

模块就是「一类目标的探测配方」。下面这份覆盖最常见的四种场景:

modules:
http_2xx:
prober: http
timeout: 10s
http:
valid_status_codes: [200]
method: GET
follow_redirects: true
preferred_ip_protocol: "ip4"
tls_config:
insecure_skip_verify: false
http_post_2xx:
prober: http
timeout: 10s
http:
valid_status_codes: [200, 204]
method: POST
tcp_connect:
prober: tcp
timeout: 10s
dns_query:
prober: dns
timeout: 10s
dns:
query_name: "example.com"
query_type: "A"
valid_rcodes:
- NOERROR
icmp_ping:
prober: icmp
timeout: 10s
icmp:
preferred_ip_protocol: "ip4"

几个要点:

  • http_2xx 是最常用的模块。valid_status_codes 不写时默认 2xx 算成功;写死 [200] 可以把「返回 301 去了别处」也判为异常,视你的预期取舍。preferred_ip_protocol 建议明确写 ip4 或 ip6,否则双栈环境下解析到哪个协议带有随机性,探测结果会飘。
  • 需要带请求头的场景(比如绕过 CDN 的回源检查、带 Host 访问)在模块里加 headers 字段即可,一个模块对应一类目标,不要把所有目标塞进一个模块硬凑。
  • DNS 模块的 query_name 和 query_type 写在模块里,这意味着不同域名要配不同模块,或者在 Prometheus 侧用参数覆盖——目标不多时按域名建模块最直白。
  • TCP 模块只验证端口能不能建连,适合探测 MySQL、Redis 这类没有 HTTP 接口的服务「还活着」。
WARNING

blackbox_exporter 的 9115 端口不要裸奔公网。它没有任何鉴权,任何人都能拿它当跳板去探测任意地址,等于在你的服务器上开了一个公开的 SSRF 入口。像上面那样只绑 127.0.0.1、只让同机的 Prometheus 访问,是最稳妥的做法;跨机器部署时也要用防火墙或内网隔离。同理,探测目标清单里不要写内网敏感端口再把结果页暴露出去。

Prometheus 侧:经典 relabel 写法#

这是全篇最核心的一段。blackbox 的接法初看有点绕:Prometheus 把目标写进 __param_target 参数,再把抓取地址 __address__ 改写成 blackbox 的地址,于是 Prometheus 实际抓的是 blackbox,探测的却是目标:

scrape_configs:
- job_name: "blackbox-http"
metrics_path: /probe
params:
module: [http_2xx]
static_configs:
- targets:
- https://blog.example.com
- https://www.example.com
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
- job_name: "blackbox-tcp"
metrics_path: /probe
params:
module: [tcp_connect]
static_configs:
- targets:
- 127.0.0.1:3306
- 127.0.0.1:6379
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

三条 relabel 各司其职:第一条把原始目标抄进 __param_target,Prometheus 会自动把它拼成 /probe?target=... 的查询参数;第二条把目标地址留一份到 instance 标签,方便在仪表盘和告警里认出是哪个目标;第三条把真正的抓取地址换成 blackbox 的 9115。少了任何一条都跑不通,这是官方范式,照抄即可。

目标多起来之后不要把 targets 列表写死在 Prometheus 配置里,改用 file_sd_configs 把目标放进独立的 JSON/YAML 文件,改目标不用重启 Prometheus,配合告警链路做变更管理也更干净。轻量场景如果只需要「活没活」的状态页,也可以看看更简单的 Gatus;但要把探测结果沉淀成指标、做趋势和证书告警,还是 blackbox 这套更合适。和 Uptime Kuma 的分工也是同理:Kuma 看状态,blackbox 出数据。

先手动验活,再接 Prometheus#

接配置之前,先用 curl 直接问 blackbox 一次,能省掉大量来回猜的时间:

Terminal window
curl 'http://localhost:9115/probe?target=https://blog.example.com&module=http_2xx'

返回一堆 probe_* 指标就说明模块和目标都通。重点看 probe_success 1——是 1 再去改 Prometheus 配置,是 0 就先在这一层把问题定位掉。

证书到期告警#

这是黑盒探测最有价值的副产品:只要目标走 HTTPS,probe_ssl_earliest_cert_expiry 就会带回证书到期时间戳,不需要任何额外的证书管理工具。在 Prometheus 的告警规则里加两条:

groups:
- name: blackbox
rules:
- alert: CertExpiringSoon
expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 15
for: 1h
labels:
severity: warning
annotations:
summary: "证书将在 15 天内到期:{{ $labels.instance }}"
- alert: ProbeFailed
expr: probe_success == 0
for: 5m
labels:
severity: critical
annotations:
summary: "黑盒探测失败:{{ $labels.instance }}(job {{ $labels.job }})"

第一条把时间戳换算成剩余天数,小于 15 天开始提醒——Let’s Encrypt 这类 90 天短证书靠自动续期,续期任务悄悄挂掉是真实发生过的事故,证书过期当天网站直接不可访问,且白盒监控往往毫无察觉,这条规则就是专门兜这种底的。第二条是最基础的可用性告警,for: 5m 避免网络抖动一闪就报警。规则触发后经 Alertmanager 分发到 Telegram 或邮件,本系列的告警篇有完整链路。

有了指标,Grafana 侧可以顺手做两个面板:各目标 probe_duration_seconds 的时序图看响应趋势,probe_http_duration_seconds 按 phase 标签拆开看 DNS、TLS、服务端处理各占多少——慢在哪一段,一目了然。

排障#

probe_success 一直是 0。 别先怀疑 Prometheus。按上面的方法手动 curl 一次 probe 接口:curl 通、Prometheus 里不通,是 relabel 写错了(最常见是漏了第三条改写 __address__);curl 也不通,问题在 blackbox 侧,接着看下面几条。

HTTP 目标明明能打开却报失败。 查 probe_http_status_code 的实际值:可能是目标返回了非预期的状态码(比如强制跳转、需要特定 Host 头),调整模块的 valid_status_codes 或补 headers;也可能是双栈解析飘到了 IPv6,先把 preferred_ip_protocol 写死再看。

DNS 模块不通。 先确认模块里的 query_type 和目标场景对得上(查 A 记录写 A、查邮件记录写 MX),再确认 query_name 没拼错;还不行就把 target 换成具体的 DNS 服务器地址单独验,区分是模块配置问题还是目标 DNS 本身不响应。

ICMP 探测全灭。 几乎都是权限问题:Docker 部署确认 cap_add 里有 NET_RAW;宿主机直接运行确认二进制有相应的 capability。另外有些云厂商和目标侧防火墙默认禁 ping,ICMP 不通不等于主机宕机,别拿它当唯一的存活判据。

证书指标缺失。 probe_ssl_earliest_cert_expiry 只在目标真正走了 TLS 时才有。如果目标是纯 HTTP、或者 HTTPS 探测因为证书校验失败根本没握上手,这个指标就不会出现。想单独盯证书校验问题,可以另建一个 insecure_skip_verify: false 的严格模块和宽松模块对照着看。

探测超时。 模块的 timeout 和 Prometheus 的 scrape_timeout 要对齐,前者大于后者时 Prometheus 会先一步掐断并报 context deadline exceeded,看起来像目标故障,其实是配置打架。

小结#

黑盒探测的价值在于换一个站位:从用户的网络位置出发,把 DNS、建连、TLS、响应整条链路验一遍,这是任何内部指标都替代不了的视角。落地路径很短:一个容器、一份 blackbox.yml、一段照抄即可的 relabel 配置,再加两条告警规则,就能把可用性探测和证书到期预警一起补齐。它和白盒指标不是二选一——白盒告诉你服务内部健不健康,黑盒告诉你用户到底能不能用得上,两边都绿,才是真的没问题。

监控与可观测性:blackbox_exporter 黑盒探测——站在用户的位置看你的服务
https://www.anexns.cloudns.org/posts/monitoring-blackbox/
作者
Anexns
发布于
2026-11-16
许可协议
CC BY-NC-SA 4.0