docker_blackbox_exporter 镜像文档

镜像概述

docker_blackbox_exporter是基于Prometheus Blackbox Exporter的Docker镜像，特别集成了自定义根证书支持。Blackbox Exporter是Prometheus生态中的核心探针工具，通过模拟HTTP、HTTPS、DNS、TCP、ICMP等网络请求，采集目标端点的可用性、响应时间、状态码等监控指标。本镜像在原生功能基础上增强了证书配置能力，可便捷集成私有CA证书，适用于企业私有环境或需要自定义证书链的监控场景。

核心功能与特性

多协议探测支持

• 支持HTTP/HTTPS协议：探测端点响应状态码、响应时间、SSL证书有效期等指标
• 支持DNS协议：解析域名记录类型（A、AAAA、CNAME等）、解析耗时、权威服务器响应等
• 支持TCP协议：检测端口连通性、建立连接耗时、自定义发送/接收字符串验证
• 支持ICMP协议：通过ping检测主机可达性（需容器具备网络原始套接字权限）

自定义根证书集成

• 内置证书目录，支持挂载外部CA证书文件（如自签名证书、私有CA根证书）
• 可在探测配置中指定自定义证书路径，解决私有环境中HTTPS端点证书不信任问题

灵活的配置管理

• 支持通过挂载外部配置文件（config.yml）定义探测规则（模块）
• 模块配置支持自定义超时时间、重试策略、TLS参数、HTTP头信息等细节

原生Prometheus集成

• 暴露标准/metrics端点，可直接被Prometheus服务器抓取指标
• 输出指标符合Prometheus数据模型，支持与Grafana等可视化工具联动

使用场景与适用范围

企业私有环境监控

• 监控使用私有CA证书签名的内部HTTPS服务（如内部API、私有Web应用）
• 探测跨网络区域的服务端点（如跨数据中心的数据库、消息队列端口）

多协议端点监控

• 统一监控异构服务：同时覆盖Web服务（HTTP/HTTPS）、数据库（TCP）、域名解析（DNS）等
• 混合云环境探测：同时监控公有云服务（如AWS S3）和私有数据中心服务

自定义证书需求场景

• 自签名证书环境：解决浏览器/系统默认不信任的自签名证书端点探测问题
• 证书链自定义场景：支持多级CA证书链（如根CA+中间CA）的信任配置

使用方法与配置说明

基本使用（docker run）

bash
docker run -d \
  --name blackbox-exporter \
  --restart=always \
  -p 9115:9115 \  # 默认暴露端口
  -v /path/to/your/config.yml:/etc/blackbox_exporter/config.yml \  # 挂载自定义配置文件
  -v /path/to/rootca:/etc/blackbox_exporter/rootca \  # 挂载自定义根证书目录
  docker_blackbox_exporter

关键参数说明

配置文件示例（config.yml）

yaml
modules:
  # HTTP端点探测模块（基础2xx状态码检测）
  http_2xx:
    prober: http
    timeout: 10s  # 超时时间
    http:
      valid_status_codes: [200, 201, 204]  # 允许的状态码
      method: GET  # 请求方法
      headers:
        Host: "example.com"  # 自定义HTTP头
      no_follow_redirects: false  # 是否跟随重定向

  # HTTPS端点探测模块（带自定义根证书）
  https_custom_ca:
    prober: http
    timeout: 15s
    http:
      valid_status_codes: [200]
      tls_config:
        ca_file: /etc/blackbox_exporter/rootca/internal_ca.crt  # 引用自定义根证书
        insecure_skip_verify: false  # 禁用跳过证书验证（依赖自定义CA）

  # TCP端口探测模块（数据库端口示例）
  tcp_mysql:
    prober: tcp
    timeout: 5s
    tcp:
      query_response:
        - send: "SELECT 1;"  # 发送测试命令
        - expect: "1"  # 预期响应内容

  # ICMP协议探测模块（主机存活检测）
  icmp_ping:
    prober: icmp
    timeout: 5s
    icmp:
      preferred_ip_protocol: "ip4"  # 优先IPv4
      ttl: 64  # 生存时间（跳数）

Prometheus集成配置

在Prometheus的prometheus.yml中添加如下配置，抓取Blackbox Exporter指标：

yaml
scrape_configs:
  - job_name: 'blackbox'
    metrics_path: /probe  # Blackbox Exporter探测端点
    params:
      module: [https_custom_ca]  # 默认使用的探测模块（对应config.yml中的模块名）
    static_configs:
      - targets:
        - [***]  # 私有HTTPS服务（使用自定义CA）
        - tcp://mysql.example.com:3306     # MySQL数据库端口
        - icmp://server.example.com        # 主机ICMP探测（需Blackbox启用NET_RAW权限）
    relabel_configs:
      # 将目标地址作为探测参数
      - source_labels: [__address__]
        target_label: __param_target
      # 将目标地址作为实例标签
      - source_labels: [__param_target]
        target_label: instance
      # 指向Blackbox Exporter地址（容器名或IP:端口）
      - target_label: __address__
        replacement: blackbox-exporter:9115

部署注意事项

1. ICMP协议权限：使用ICMP探测时，需在docker run命令中添加--cap-add=NET_RAW，或在Kubernetes中配置securityContext.capabilities.add: ["NET_RAW"]。

2. 配置文件更新：修改config.yml后需重启容器或发送SIGHUP信号（docker kill -s SIGHUP <container_id>）使配置生效。

3. 证书文件权限：挂载的证书文件需确保容器内用户（默认nobody）有读取权限，建议设置文件权限为644。

4. 资源限制：根据探测目标数量调整容器CPU/内存资源，大量并发探测（如1000+目标）建议分配至少1CPU核心和512MB内存。