Repolode
제출하기
quyxishi

quyxishi/whitebox

VMESS, VLESS 등으로 외부 VPN 서비스를 확인하는 Prometheus exporter

GitHub에서 보기웹사이트
스타
162
포크
14
열린 이슈
1
마지막 커밋
6일 전

어떤 프로젝트인가요?

whitebox는 외부 VPN 서비스에 연결할 수 있고 정상적으로 작동하는지 확인하는 Prometheus exporter입니다. VPN 연결 URI와 대상 URL을 전달하면 해당 VPN을 통해 터널을 구성하고 대상에 요청을 보낸 뒤, 성공 여부, HTTP 상태 코드, 단계별 소요 시간, 응답 크기를 포함한 결과를 Prometheus 메트릭으로 반환합니다.

VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks, Hysteria2 프로토콜을 지원합니다. REST endpoint에서 즉시 프로브를 실행하거나, multi-target exporter 패턴을 사용해 Prometheus에서 스케줄링하거나, cron job에서 curl로 호출할 수 있습니다. YAML 설정 파일로 이름이 지정된 scope, timeout, 요청 본문, 사용자 지정 헤더, fail_if 검증 규칙을 설정할 수 있으며, SIGHUP을 받으면 설정을 다시 불러옵니다.

프로브 간에 시작된 xray 인스턴스를 재사용해 메모리 사용량을 제한하며, /metrics에서 자체 캐시 통계도 제공합니다. Docker 이미지로 배포되며 Prometheus, blackbox_exporter, Grafana가 포함된 예제 스택도 제공됩니다.

핵심 기능

  • 01VMESS, VLESS, Trojan, WireGuard, AmneziaWG, Shadowsocks, Hysteria2를 통한 터널을 프로브합니다.
  • 02성공 여부, 상태 코드, 단계별 소요 시간을 포함한 프로브 결과를 Prometheus 메트릭으로 제공합니다.
  • 03즉시 실행하거나 예약할 수 있는 REST /probe endpoint를 제공합니다.
  • 04timeout, 요청 본문, 헤더, 응답 검증 규칙을 포함하는 YAML scope를 지원합니다.
  • 05재시작 없이 SIGHUP을 받아 설정을 다시 불러옵니다.
  • 06프로브 간에 xray 인스턴스를 재사용하고 캐시 메트릭을 제공합니다.

활용 사례

  • Prometheus와 Grafana에서 자체 호스팅 또는 타사 VPN 노드의 가용성을 모니터링합니다.
  • 여러 VPN 연결 URI를 대상으로 정기적인 연결 가능 여부 확인을 실행합니다.
  • VPN 연결로 특정 URL에 접속할 수 있는지 빠르게 일회성 테스트를 수행합니다.

빠른 시작

  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 인스턴스 캐시를 활성화하거나 컨테이너의 메모리 한도를 설정하지 않으면 메모리 사용량이 제한 없이 증가할 수 있습니다.

토픽

#prometheus#exporter#monitoring#vpn#uptime#wireguard#xray#probe#amnezia-wg#checker

자주 묻는 질문

whitebox은(는) 무엇인가요?
VMESS, VLESS 등으로 외부 VPN 서비스를 확인하는 Prometheus exporter whitebox는 외부 VPN 서비스에 연결할 수 있고 정상적으로 작동하는지 확인하는 Prometheus exporter입니다. VPN 연결 URI와 대상 URL을 전달하면 해당 VPN을 통해 터널을 구성하고 대상에 요청을 보낸 뒤, 성공 여부, HTTP 상태 코드, 단계별 소요 시간, 응답 크기를 포함한 결과를 Prometheus 메트릭으로 반환합니다.
whitebox은(는) 무료로 사용할 수 있나요? 라이선스는 무엇인가요?
whitebox은(는) MIT 라이선스의 오픈소스입니다. 상업용 제품에 사용하기 전에 라이선스 조건을 확인하세요.
whitebox은(는) 아직 유지보수되고 있나요?
활발히 유지보수 중. whitebox의 마지막 커밋은 2026년 10월 14일입니다.
whitebox은(는) 어디에 사용할 수 있나요?
Prometheus와 Grafana에서 자체 호스팅 또는 타사 VPN 노드의 가용성을 모니터링합니다. 여러 VPN 연결 URI를 대상으로 정기적인 연결 가능 여부 확인을 실행합니다. VPN 연결로 특정 URL에 접속할 수 있는지 빠르게 일회성 테스트를 수행합니다.
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

요약은 프로젝트 README를 바탕으로 AI가 작성했습니다. GitHub 통계는 매일 갱신됩니다.

관련 프로젝트