TL;DR

이 프로젝트는 VLESS 터널을 WebSocket과 XHTTP 전송으로 제공하면서 내장 HTTP 프록시, 관리용 웹 대시보드, Telegram 관리봇, 링크별 트래픽·속도·동시 IP 제한과 그룹형 서브 페이지 기능을 결합한 게이트웨이 솔루션이다. 각 링크는 Fingerprint(uTLS), ALPN, 포트와 같은 전송 메타데이터를 통해 접속 특성을 제어하며 대시보드에서는 시간별 트래픽과 실시간 연결 상태를 확인할 수 있다. 서비스 설정과 통계는 x4g_state.json에 디스크에 저장되며 컨테이너 교체 시 보존하려면 DATA_DIR에 외부 Volume을 반드시 마운트해야 한다. Railway 같은 PaaS에 포크 후 Deploy로 빠르게 올릴 수 있고 Telegram 봇을 통해 GUI 접근 없이 원격 관리가 가능한 점이 운영 편의성을 높인다.

주요 기능

• VLESS 터널을 WebSocket과 XHTTP(xhttp-packet-up, xhttp-stream-up) 전송 모드로 구축할 수 있다.
• 내장 HTTP Proxy를 통해 터널 트래픽을 내부에서 라우팅하고 관리할 수 있다.
• 대시보드에서 시간별 트래픽 그래프, 실시간 연결 상태, 로그와 활동 내역을 확인하고 개별 링크를 활성화·비활성화할 수 있다.
• 링크 단위로 트래픽 용량, 속도(Mbps), 동시 IP 수, 만료일을 설정하여 세분화된 접속 제어가 가능하다.
• 옵션으로 Telegram 관리봇을 통해 패널 접근 없이 채팅에서 채널·그룹·링크 관리를 수행할 수 있다.

어떻게 동작하는가

이 레포는 VLESS 프로토콜을 WebSocket 또는 XHTTP 전송 위에서 종단 간 터널을 생성하는 방식으로 동작한다. 각 링크는 Fingerprint(uTLS), ALPN, 포트, 속도 제한, 트래픽 한도, 동시 IP 제한과 같은 메타데이터를 갖고 대시보드와 API로 관리되며 링크 생성 시 해당 규칙에 따라 트래픽을 미들웨어에서 제어한다. 상태 데이터는 x4g_state.json 파일로 DATA_DIR 경로에 디스크에 저장되어 서비스 재시작에도 구성과 통계가 유지되도록 설계되었으나 이를 위해 외부 Volume 마운트가 필요하다.

해결 문제

이 프로젝트는 VLESS 기반 터널을 손쉽게 배포하고 운영하는 데 필요한 관리 인터페이스와 자동화 수단의 부족 문제를 해결한다. 사용자는 대시보드와 Telegram 봇으로 링크 생성, 제한 설정, QR 코드 출력, 그룹형 서브 페이지 생성 같은 운영 업무를 GUI나 채팅으로 처리할 수 있어 반복적인 콘솔 작업을 줄일 수 있다. 또한 상태를 디스크에 영구 저장하도록 설계하여 컨테이너 교체 시 구성 손실을 방지할 수 있게 했다.

차별점

• WebSocket과 두 가지 XHTTP 모드(xhttp-packet-up, xhttp-stream-up)를 동시에 지원하여 다양한 네트워크 환경에 대응하도록 설계되어 있다.
• 대시보드에서 시간별 트래픽 차트와 실시간 연결 모니터링을 제공하며 Telegram 봇으로 대시보드 접근 없이 구성 관리를 가능하게 한다.
• 링크별로 트래픽, 속도, 동시 IP 제한과 만료일을 설정할 수 있어 구독형 또는 임시 접근 제어를 프로덕션 수준으로 구현할 수 있다.
• 서비스 상태를 x4g_state.json 파일에 저장하고 외부 Volume 연동을 권장하여 컨테이너 기반 배포에서 구성 지속성을 제공한다.

사용 사례

• 개인 또는 소규모 팀이 Railway 등 PaaS에 빠르게 배포하여 VLESS 기반 접속 포인트를 호스팅하고 사용자별 트래픽·속도 제한을 적용하는 상황에서 유용하다.
• 운영자가 웹 대시보드와 Telegram 봇을 통해 원격으로 링크 관리, QR 코드 배포, 그룹형 서브 페이지 관리를 수행하며 재다설정·모니터링 비용을 낮추는 용도로 활용할 수 있다.
• 방화벽 회피나 트래픽 모방이 필요한 환경에서 WebSocket 혹은 XHTTP 전송 모드를 선택하여 호환성과 탐지 회피 전략을 조정하는 경우에 적합하다.

시작하기

먼저 GitHub에서 리포지토리를 포크한 뒤 Railway 같은 PaaS에서 GitHub 연동을 통해 Deploy를 진행하면 자동으로 배포가 시작된다. 배포 후 서비스 도메인을 Railway 설정에서 활성화하여 RAILWAY_PUBLIC_DOMAIN 환경변수를 정확히 설정해야 정상적으로 도메인이 할당된다. 영구 상태 보존을 위해 서비스의 DATA_DIR(`/data` 기본값) 경로에 외부 Volume을 연결하고 필요한 환경변수(ADMIN_PASSWORD, TELEGRAM_BOT_TOKEN, TELEGRAM_ADMIN_IDS 등)를 설정한 뒤 애플리케이션을 재시작하면 준비가 완료된다.

요구사항

• Railway 또는 컨테이너 호스팅을 통한 배포 환경으로 public domain과 포트 접근성이 필요하다.
• 서비스 상태 영구화용으로 DATA_DIR(`/data`)에 연결된 외부 Volume이 필요하다.
• 필요 시 Telegram 통합을 위해 TELEGRAM_BOT_TOKEN과 TELEGRAM_ADMIN_IDS 환경변수를 설정해야 한다.
• 도메인에서 지정한 포트가 실제로 열려 있어야 하며 포트 접근성은 구성한 연결 방식(WebSocket/XHTTP)과 일치해야 한다.