---
title: "blackbox_exporter"
type: entity
aliases: [Blackbox Exporter, Prometheus Blackbox Exporter]
tags: [monitoring, probing, http, tls, prometheus, network]
date: 2025-11-11
---

# blackbox_exporter

## Overview
blackbox_exporter 是 Prometheus 官方的黑盒探测 exporter，允许通过 HTTP、HTTPS、DNS、TCP、ICMP 等协议探测端点的可用性和响应质量。它不依赖目标系统的内部指标，而是从外部视角模拟真实请求，检测服务是否可达、响应是否正常、TLS 证书是否即将到期。

## Key Characteristics
- **黑盒探测**：不依赖目标内部指标，从外部检测服务健康状态
- **多协议支持**：HTTP、HTTPS、DNS、TCP、ICMP、SSH
- **TLS 证书监控**：检测证书到期时间，支持提前告警
- **Prometheus 集成**：通过 `probe_success`、`probe_duration_seconds` 等指标暴露探测结果

## Key Metrics
| 指标 | 说明 | 用例 |
|------|------|------|
| `probe_success` | 探测是否成功（0/1） | HTTP 可用性告警 |
| `probe_duration_seconds` | 探测耗时（秒） | 响应时间告警 |
| `probe_http_status_code` | HTTP 响应码 | 4xx/5xx 检测 |
| `probe_ssl_earliest_cert_expiry` | TLS 证书最早到期时间（Unix 时间戳） | 证书到期告警 |
| `probe_dns_lookup_duration_seconds` | DNS 解析耗时 | DNS 健康检测 |

## Prometheus scrape_config
```yaml
- job_name: 'blackbox_http'
  metrics_path: /probe              # 关键：不是 /metrics，而是 /probe
  params:
    module: [http_2xx]             # 使用 http_2xx 模块
  static_configs:
    - targets:
      - "https://pq2435887bh.vicp.fun"
      - "http://shenwei-nas.vip.cpolar.cn"
  relabel_configs:
    - source_labels: [__address__]
      target_label: __param_target
    - target_label: __address__
      replacement: blackbox:9115     # 指向 blackbox_exporter
```

## Home Server Deployment
```yaml
# docker-compose.yml 片段
blackbox:
  image: prom/blackbox-exporter:latest
  container_name: blackbox
  restart: always
  ports:
    - "9115:9115"
```

## Key Alerts (PromQL)
```yaml
# HTTP 探测失败告警
- alert: HTTPProbeFailed
  expr: probe_success == 0
  for: 2m
  labels:
    severity: critical

# TLS 证书即将到期（14天）
- alert: TLSCertExpiring
  expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 14
  for: 1h
  labels:
    severity: warning
```

## Related Sources
- [[家庭监控方案-prometheus-grafana-node-exporter-cadvisor-blackbox]]

## Related Entities
- [[Prometheus]] — 数据消费者
- [[Uptime Kuma]] — 互补的合成监控工具

## Related Concepts
- [[Exporter]] — Prometheus 生态组件
- [[合成监控]]（Synthetic Monitoring）— 黑盒探测的核心应用场景
- [[System Monitoring]] — 应用领域