TL;DR

이 레포지토리는 Railway처럼 외부에서 단일 포트만 제공되는 환경에서 nginx 리버스 프록시와 Docker 설정을 결합해 Heimdall(3x-ui 계열) 패널, 서브스크립션, VLESS over WebSocket 인바운드를 하나의 포트로 노출하도록 구성한다. Dockerfile 단계에서 Heimdall을 빌드 시 자동으로 내려받아 이미지를 생성하고 nginx가 포트 3000에서 청취해 내부의 x-ui 서비스(Listen Port 8080)로 경로별 트래픽을 분기한다. 기본 데이터베이스는 SQLite여서 별도 DB 없이 즉시 운영이 가능하며 컨테이너 재배포로 인한 설정 손실을 막기 위해 /etc/x-ui로 Volume 마운트를 권장한다. 기본 로그인은 admin/admin이며 Postgres로 전환하려면 Dockerfile과 start.sh를 수동으로 수정해야 한다.

주요 기능

• 하나의 외부 포트로 관리 패널, 구독 경로, VLESS/WebSocket 인바운드를 경로 기반으로 분기해 노출한다. nginx reverse proxy가 수신한 요청의 경로를 판별해 내부 서비스로 전달하며 Railway의 Target Port 제한을 회피한다. 이 구조는 별도 포트 할당이 불가능한 호스팅 환경에서 여러 엔드포인트를 운영할 수 있게 한다.
• Dockerfile 기반 자동 빌드를 통해 배포 시 최신 Heimdall 릴리스를 빌드 단계에서 다운로드해 실행 이미지를 생성한다. Railway에서 GitHub 연동으로 Deploy from GitHub repo를 선택하면 Dockerfile을 자동으로 인식해 빌드가 진행된다. 이 과정은 수동으로 바이너리를 내려받아 빌드하는 절차를 줄인다.
• SQLite를 기본 DB로 사용해 별도 데이터베이스 설치 없이 즉시 운영 가능하다. 컨테이너 내부의 파일시스템에 설정이 저장되며 재배포로 인한 데이터 손실을 방지하려면 볼륨을 마운트해 /etc/x-ui를 영속화해야 한다. 대규모 사용자 환경에서는 Postgres 전환을 위해 Dockerfile과 start.sh를 수정해야 한다.

어떻게 동작하는가

이 레포지토리는 nginx를 리버스 프록시로 두고 단일 외부 포트로 들어온 요청을 패널 경로, 서브스크립션 경로, WebSocket 기반 VLESS 인바운드로 라우팅한다. Dockerfile 빌드 시점에 최신 Heimdall을 GitHub에서 내려받아 컨테이너에 포함시키며 Railway에서 해당 이미지를 자동으로 빌드·배포하도록 설계되어 있다. nginx는 포트 3000에서 청취하고 내부적으로 x-ui 계열의 서비스는 Listen Port 8080으로 동작하도록 구성되어 있어 외부 포트와 내부 서비스 포트 매핑을 통해 단일 포트 운영을 실현한다.

해결 문제

이 레포지토리는 Railway같이 외부에서 단일 포트만 할당되는 플랫폼에서 Heimdall(x-ui 계열) 패널과 VLESS/WebSocket 인바운드를 동시에 운영할 수 없는 문제를 해결한다. nginx 역프록시를 통해 단일 포트에 들어온 트래픽을 경로별로 분기하고 Dockerfile 기반 자동 빌드로 배포 과정을 단순화한다. 또한 기본적으로 SQLite를 사용해 별도 데이터베이스 구성 없이 바로 패널을 운영할 수 있도록 하며 재배포 시 설정 보존을 위해 볼륨 마운트를 권장한다.

차별점

• Railway의 단일 포트 제한을 고려해 패널, 서브스크립션, VLESS/WebSocket을 모두 하나의 포트에서 경로 기반으로 라우팅하는 아키텍처를 제공한다.
• Dockerfile 단계에서 Heimdall을 자동으로 내려받아 이미지를 빌드하도록 구성되어 있어 수동 설치·업데이트 과정을 줄인다.
• 기본 설정으로 SQLite를 사용해 초기 배포와 테스트 환경에서 별도 DB 구성 없이 빠르게 운영할 수 있도록 설계되었으며 필요 시 Postgres로 전환할 수 있다는 점을 명시한다.

사용 사례

• Railway 같은 PaaS에서 포트 제한 때문에 별도 포트로 서비스 노출이 불가능한 상황에서 Heimdall 패널과 VLESS 인바운드를 동시에 운영할 때 유용하다.
• 개인용 또는 소규모 서버에서 Postgres나 복잡한 DB 없이 빠르게 x-ui/Heimdall 기반 패널을 배포·테스트해야 할 때 적합하다.
• 서비스 재배포 시 설정 유실을 방지하기 위해 컨테이너 볼륨을 사용하여 설정을 영속화해야 하는 운영 시나리오에 적용할 수 있다.

시작하기

새 GitHub 리포지토리를 생성하고 루트에 Dockerfile, nginx.conf.template, start.sh 세 파일을 업로드한다. Railway에서 New Project → Deploy from GitHub repo로 해당 리포지토리를 선택하면 Railway가 Dockerfile을 감지해 자동으로 빌드 및 배포를 진행한다. 배포 완료 후 Railway의 Settings → Networking에서 Generate Domain을 클릭하고 Target Port를 3000으로 설정한 뒤 https://{도메인}/managepanel/로 접속해 기본 계정 admin/admin으로 로그인한 다음 즉시 비밀번호를 변경한다.

요구사항

• Railway 플랫폼 계정과 GitHub 연동을 통한 Deploy from GitHub 사용 권한.
• 프로젝트 루트에 Dockerfile, nginx.conf.template, start.sh 세 파일이 존재해야 한다.
• 외부 접속을 위해 Railway의 Networking에서 Target Port를 3000으로 설정해야 하며 영속적 설정 보존을 위해 /etc/x-ui에 마운트할 Volume 권장.