quyxishi/whitebox

这是什么？

核心功能

• 01支持通过 VMESS、VLESS、Trojan、WireGuard、AmneziaWG、Shadowsocks 和 Hysteria2 建立隧道进行探测。
• 02以 Prometheus 指标输出探测结果，包括成功状态、HTTP 状态码和分阶段耗时。
• 03提供 REST 的 /probe 接口，可按需或定时调用。
• 04支持 YAML 配置的 scope，可设置超时、请求体、请求头和响应校验规则。
• 05收到 SIGHUP 信号后可热加载配置，无需重启。
• 06跨探测复用 xray 实例，并暴露缓存相关指标。

适用场景

• 在 Prometheus 和 Grafana 中监控自建或第三方 VPN 节点的可用性。
• 对一批 VPN 连接 URI 定时执行连通性检查。
• 临时测试某个 VPN 连接能否访问指定网址。

快速上手

1. 1

   运行预构建的 Docker 镜像

   docker run --rm -d --name whitebox -p 9116:9116 rxyvea/whitebox:latest
2. 2

   通过 VPN 连接 URI 探测目标

   curl -sG http://localhost:9116/probe --data-urlencode 'ctx=vless://c9f5228c-8870-47bd-a92f-9b38c7c02b08@1.2.3.4:443?type=tcp&encryption=none&security=reality&pbk=DF-3KL2W4RuNB2HgsEDmLqHLvvTTN4_QfwUCUn8Uhy0&fp=firefox&sni=ce-cdn.icloud-content.com&sid=620352b7&spx=%2F&flow=xtls-rprx-vision' --data-urlencode 'target=https://google.com'

使用前须知

• !探测需要每个目标提供可用的 VPN 连接 URI，因此必须自备 VPN 服务器信息。
• !若未启用 xray 实例缓存或未为容器设置内存上限，内存占用可能无限增长。

标签

常见问题

whitebox 是什么？

一个 Prometheus 导出器，通过多种 VPN 协议探测外部服务的可用性并输出指标。 whitebox 是一个 Prometheus 导出器，用于检测外部 VPN 服务是否可以连通、能否正常工作。传入一个 VPN 连接 URI 和目标地址后，它会通过该 VPN 建立隧道访问目标，并以 Prometheus 指标的形式返回成功与否、HTTP 状态码、分阶段耗时和响应大小等结果。

whitebox 可以免费使用吗？用的什么许可证？

whitebox 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

whitebox 还在维护吗？

活跃维护中。whitebox 最近一次提交是在 2026年10月14日。

whitebox 适合用来做什么？

在 Prometheus 和 Grafana 中监控自建或第三方 VPN 节点的可用性。 对一批 VPN 连接 URI 定时执行连通性检查。 临时测试某个 VPN 连接能否访问指定网址。

whitebox 怎么安装和运行？

运行预构建的 Docker 镜像: docker run --rm -d --name whitebox -p 9116:9116 rxyvea/whitebox:latest 通过 VPN 连接 URI 探测目标: curl -sG http://localhost:9116/probe --data-urlencode 'ctx=vless://c9f5228c-8870-47bd-a92f-9b38c7c02b08@1.2.3.4:443?type=tcp&encryption=none&security=reality&pbk=DF-3KL2W4RuNB2HgsEDmLqHLvvTTN4_QfwUCUn8Uhy0&fp=firefox&sni=ce-cdn.icloud-content.com&sid=620352b7&spx=%2F&flow=xtls-rprx-vision' --data-urlencode 'target=https://google.com'

在哪里获取 whitebox？

源代码和安装说明在 GitHub 上：https://github.com/quyxishi/whitebox