要回答的是“用户入口能否访问”

进程存活、应用 /metrics 能被抓取,并不能证明 HTTP 入口正常。反向代理转发错误、入口返回 503、DNS 解析异常,都可能发生在进程指标仍然正常的时候。

本文搭建一个独立的 HTTP 探测实验:Prometheus 定时调用 Blackbox Exporter,Exporter 请求演示站点,Prometheus 再根据探测结果产生告警。重点是配置部署与验收,不对应某次生产事故,也不提供虚构的可用率或延迟数据。

环境要求是 Linux 容器模式的 Docker Engine 与 Compose v2;命令以 Bash 为例。在空目录保存下面五个文件。本文固定使用 Prometheus v3.5.0、Blackbox Exporter v0.27.0 与 Nginx 1.28.0 作为实验版本,不代表最新版本或生产选型建议;生产部署需要另行评估漏洞、兼容性并锁定镜像摘要。

先区分两段链路

链路为:Prometheus → Exporter 的 /probe → HTTP 目标。

指标 判断对象 典型失败
up{job="blackbox_http"} Prometheus 能否抓取探测接口 Exporter 停止、抓取超时、返回无效指标
probe_success{job="blackbox_http"} Exporter 本次探测是否满足模块条件 目标拒绝连接、状态码错误、DNS 或 TLS 失败

当站点返回 503,但 Exporter 正常返回指标时,可能出现 up=1、probe_success=0。如果只对 up == 0 告警,就会漏掉这种入口故障。Exporter 不可达时,也不能期待同一轮仍有新的 probe_success=0,因此两段链路需要独立告警。这是官方说明的多目标 Exporter 模式。

一、建立可控的探测目标

保存 nginx.conf。专用路径只返回固定状态,不包含业务数据,也不检查数据库;它适合验证整条监控链路,不能代替业务交易探测。

events {}
http {
    server {
        listen 80;
        location = /healthz {
            default_type text/plain;
            return 200 "ok\n";
        }
        location / {
            return 404;
        }
    }
}

保存 blackbox.yml:

modules:
  http_ok:
    prober: http
    timeout: 5s
    http:
      method: GET
      valid_status_codes: [200]
      follow_redirects: false
      preferred_ip_protocol: ip4
      ip_protocol_fallback: false

这里只接受 200,且不跟随跳转,避免健康路径被重定向到登录页后仍被判定成功。强制 IPv4 是为了让本实验的容器网络条件明确;生产有 IPv6 服务目标时,应增加独立模块与探测任务,不能据此宣布双栈可用。状态码、跳转和协议族的字段含义见官方配置定义。

二、让目标 URL 保留在标签里

保存 prometheus.yml:

global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  - /etc/prometheus/alerts.yml

scrape_configs:
  - job_name: blackbox_http
    metrics_path: /probe
    scrape_timeout: 8s
    params:
      module: [http_ok]
    static_configs:
      - targets:
          - http://demo/healthz
        labels:
          service: demo
          vantage: lab
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: blackbox:9115

三条重标签规则必须按这个顺序读:把原始 URL 写入请求参数 target,复制为最终 instance 标签,最后将真正的抓取地址改成 Exporter。否则常见结果是 Prometheus 直接抓业务站点,或所有指标的 instance 都只剩 Exporter 地址。

这里形成的请求相当于 http://blackbox:9115/probe?module=http_ok&target=http%3A%2F%2Fdemo%2Fhealthz。blackbox 与 demo 是 Compose 网络里的服务名,不能在容器内把宿主机的 localhost 当作业务地址。

模块超时 5 秒小于抓取超时 8 秒,抓取超时又小于周期 15 秒,为结果编码与传输预留余量;这些值是实验预算,不是通过压力测试得出的生产参数。

三、分别标识入口故障与采集故障

保存 alerts.yml:

groups:
  - name: http_probe
    rules:
      - alert: HttpProbeFailed
        expr: probe_success{job="blackbox_http"} == 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "HTTP 入口探测失败"
          description: "探测点 {{ $labels.vantage }} 无法正常访问 {{ $labels.instance }}"
      - alert: ProbeScrapeFailed
        expr: up{job="blackbox_http"} == 0
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "HTTP 探测采集链路失败"
          description: "检查 Exporter、网络与抓取超时,目标为 {{ $labels.instance }}"

for 表示表达式持续成立才进入 firing,短暂失败可能只进入 pending。目标失效或恢复后,要留出抓取和规则评估的时间,不能按点击停止容器的瞬间计算精确告警时刻。

本实验只有规则计算,没有配置 Alertmanager 或通知渠道。Alerts 页出现 firing 不等于值班人员已经收到通知;生产上线前必须另外验收通知路由、接收人、静默和恢复通知。固定目标被配置误删也不在这两条规则的覆盖范围内,应单独维护预期目标清单。

四、启动前先检查配置

保存 compose.yml:

services:
  demo:
    image: nginx:1.28.0-alpine
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
  blackbox:
    image: quay.io/prometheus/blackbox-exporter:v0.27.0
    command: ["--config.file=/etc/blackbox_exporter/blackbox.yml"]
    volumes:
      - ./blackbox.yml:/etc/blackbox_exporter/blackbox.yml:ro
    ports:
      - "127.0.0.1:9115:9115"
  prometheus:
    image: prom/prometheus:v3.5.0
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.path=/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./alerts.yml:/etc/prometheus/alerts.yml:ro
      - prometheus_data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
volumes:
  prometheus_data:

在这五个文件所在目录执行,每一步退出码必须为 0 才继续。promtool check config 会同时检查引用的规则文件,不能只看 YAML 缩进正确。

docker compose config --quiet
docker compose run --rm demo nginx -t
docker compose run --rm --no-deps --entrypoint /bin/promtool prometheus check config /etc/prometheus/prometheus.yml
docker compose up -d
docker compose ps
docker compose logs --tail=60 blackbox prometheus

日志中应没有配置解析失败;再用浏览器打开 http://127.0.0.1:9115/probe?module=http_ok&target=http%3A%2F%2Fdemo%2Fhealthz&debug=true,检查探测日志、最终 probe_success 与 HTTP 状态码。Debug 输出可能包含目标地址或响应细节,只在受控环境排障使用。

打开 http://127.0.0.1:9090,在查询页面分别执行:

up{job="blackbox_http"}
probe_success{job="blackbox_http"}

预期两者都为 1,且标签包含 instance="http://demo/healthz"、service="demo"、vantage="lab"。若 up=0,先修采集链路;若 up=1 且探测失败,再检查目标响应与模块约束。不要遇到超时就直接调大阈值。

五、用三次演练完成验收

下表是执行时应核对的预期结果,不是本文环境已经观测到的数据。

操作 预期指标与告警 排查入口
正常启动 up=1、probe_success=1,无活动告警 查询标签是否对应目标 URL
停止 demo up=1、probe_success=0,持续失败后入口告警 firing Exporter debug 的连接错误
恢复 demo,再停止 blackbox up=0,持续失败后采集告警 firing Targets 页 Last Error

先测试入口故障:

docker compose stop demo

等待至少 3 分钟并观察查询页与 Alerts 页,记录指标值、标签、pending 和 firing 状态。完成后恢复:

docker compose start demo

确认新一轮探测成功且入口告警恢复,再演练采集故障:

docker compose stop blackbox

等待至少 2 分钟,确认 ProbeScrapeFailed 触发。此时不要把旧的 probe_success 样本或暂时空结果解释为站点恢复。最后执行:

docker compose start blackbox

重新核对两项指标为 1、告警恢复。为了进一步验证状态码约束,可以将 nginx.conf 的 /healthz 改为返回 503,先运行 docker compose exec demo nginx -t,成功后运行 docker compose exec demo nginx -s reload;预期仍是采集成功、探测失败。演练后恢复原配置并重复检查与 reload。

接入真实入口之前的取舍

实验中的探测从容器网络发起,不能证明公网 DNS、CDN、TLS 和真实用户地区的链路可用。接入生产时,把 URL 换成真实 HTTPS 入口,并将 Exporter 部署到所需观测位置;通过稳定的 vantage 标签区分机房或地域。TLS 校验保持开启,证书错误应修证书链或信任配置,不能通过关闭验证让告警消失。

对于可能跳登录页的入口,应明确是否允许重定向、接受哪些状态码、是否检查响应正文。返回 200 的错误页仍可能通过当前模块,业务可用性应增加稳定内容校验或专用合成交易。不要把带令牌的 URL 放入 instance,它会进入时序库和告警;鉴权信息应由受控配置注入,并限制读取权限。

Exporter 的探测接口可以让服务端请求指定地址,不能暴露给不可信调用者;限制入口和出口权限,防止它被用来访问内部敏感地址。本文端口仅绑定回环地址,业务目标甚至没有发布宿主机端口。

实验结束执行 docker compose down,停止并移除实验容器与网络,保留命名数据卷;再次启动可复用数据。生产配置修改前保留上一版本,检查通过后再应用,回滚时恢复配置并重新验收探测与告警。

验证记录与边界

本文编写时已核对 Prometheus 多目标模式和 Blackbox 配置文档,并检查本地稿件的编码、代码围栏及重标签映射。当前发布环境访问 Docker API 返回权限拒绝,因此没有执行容器启动、promtool 配置检查、DNS/HTTP 探测或告警时序演练;上述部署命令与验收表需要在具备 Docker 权限的实验环境执行,不应视作已通过的集成测试。

上线门槛是:配置检查通过、正常探测通过、入口失败可告警、采集失败可告警、恢复可观察、通知链路单独验收完成。保留这些证据,才能判断监控究竟覆盖了什么。