zhengxiongzhao/blackbox-exporter-http3 repository overview

⁠Blackbox Exporter for HTTP/3

这是一个基于 Prometheus Blackbox Exporter⁠ 的增强版本，增加了对 HTTP/3 (QUIC) 协议 的支持。你可以用它来：

• 检查你的网站是否成功开启了 HTTP/3。
• 持续监控 HTTP/3 服务的响应时间和成功率。
• 在你的服务不支持 HTTP/3 时收到告警。

⁠它是如何工作的？

blackbox-exporter-http3 会像一个外部用户一样，尝试使用 HTTP/3 协议访问你的目标服务。然后，它会生成详细的监控指标（如探测是否成功、响应时间、TLS 版本等），这些指标可以被 Prometheus 收集和展示。

⁠快速开始：5分钟内监控你的网站

你只需要一个正在运行的 Prometheus 服务，就可以快速开始。

⁠第1步：运行 Blackbox Exporter for HTTP/3

使用以下命令在你的服务器上运行 blackbox-exporter-http3 容器：

docker run -d \
  --name blackbox-exporter-http3 \
  -p 9115:9115 \
  --restart=always \
  zhengxiongzhao/blackbox-exporter-http3:latest

现在，你可以通过访问 http://<你的服务器IP>:9115 来查看 exporter 的状态页面。

⁠第2步：配置 Prometheus

接下来，在你的 prometheus.yml 配置文件中添加一个新的 scrape_configs 任务，来让 Prometheus 通过这个 exporter 探测你的网站。

请将 targets 中的 https://your-website.com 替换成你想要监控的网站地址。

# prometheus.yml

scrape_configs:
  - job_name: 'blackbox_http3'
    metrics_path: /probe
    params:
      module: [http_3xx]  # 使用内置的 http_3xx 模块
    static_configs:
      - targets:
        - https://your-website.com  # <-- 修改这里
        - https://cloudflare-quic.com
        - https://www.google.com
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox-exporter-http3:9115 # Exporter 的地址

重要提示:

• 如果你的 Prometheus 和 blackbox-exporter-http3 运行在同一台机器上，replacement 可以使用 localhost:9115。
• 如果它们在不同的机器上，请确保 Prometheus 可以访问到 blackbox-exporter-http3 的 9115 端口。
• 如果你使用 Docker Compose 或者 Kubernetes，请使用相应的服务名，例如 blackbox-exporter-http3:9115。

⁠第3步：重启 Prometheus 并查看结果

重启你的 Prometheus 服务以加载新的配置。几分钟后，你就可以在 Prometheus 的查询界面中查看监控指标了。

试试查询以下指标：

• probe_success: 值为 1 表示探测成功，0 表示失败。
• probe_duration_seconds: 探测的总耗时。
• probe_http_version: 返回探测到的 HTTP 版本号，检查是否为 3。

⁠监控指标详解

blackbox-exporter-http3 提供了一系列有用的监控指标：

⁠高级用法

⁠使用 Docker Compose

如果你想同时管理 Prometheus 和 blackbox-exporter-http3，使用 docker-compose 是一个好方法。

创建一个 docker-compose.yml 文件：

version: '3.8'

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - '9090:9090'
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'

  blackbox_exporter_http3:
    image: zhengxiongzhao/blackbox-exporter-http3:latest
    container_name: blackbox-exporter-http3
    ports:
      - '9115:9115'
    restart: always

确保你的 prometheus.yml 中的 replacement 地址是 blackbox_exporter_http3:9115。

⁠自定义探测模块

blackbox-exporter-http3 内置了一个名为 http_3xx 的模块，专门用于 HTTP/3 探测。如果你需要更复杂的配置（例如，自定义请求头、请求体等），你可以提供自己的 blackbox.yml 配置文件。

1. 创建你自己的 blackbox.yml 文件：

   # blackbox.yml
   modules:
     http_3xx:
       prober: http
       http:
         preferred_ip_protocol: "ip4"
         enable_http3: true
         enable_http2: false
         valid_http_versions: ["HTTP/3.0"]
   

   Copy

2. 在运行容器时挂载你的配置文件：

   docker run -d \
     -p 9115:9115 \
     -v $(pwd)/blackbox.yml:/config/blackbox.yml \
     --name blackbox-exporter-http3 \
     zhengxiongzhao/blackbox-exporter-http3:latest
   

   Copy

3. 在 Prometheus 配置中，使用你的自定义模块名：module: [http_3_custom]。

⁠常见问题 (FAQ)

1. 如何确认我的网站是否真的支持 HTTP/3？

你可以使用 curl 命令来快速验证（需要新版本的 curl）：

# 如果命令返回的头部信息中有 "HTTP/3" 字样，就表示支持
curl --http3-only -I https://your-website.com

2. 探测失败了（probe_success 为 0），如何排查？

• 检查网络：确保运行 exporter 的服务器可以访问外网，特别是 UDP 443 端口没有被防火墙阻止。
• 检查目标服务：确认你的网站服务器已经正确配置并开启了 HTTP/3 支持。
• 查看 Exporter 日志：运行 docker logs blackbox-exporter-http3 查看详细的错误日志，可能会有类似 "QUIC connect error" 的提示。
• 使用调试模式：访问 http://<exporter_ip>:9115/probe?target=<your_target>&module=http_3xx&debug=true 查看详细的探测过程和日志。

⁠许可证

本项目采用 MIT 许可证⁠。