nexcore-x-ui 설치 및 운영 튜토리얼 (Xray 노드 패널)
Astrenix/nexcore-x-ui 완벽 가이드: 원클릭 설치 스크립트, 정적 Go 바이너리, systemd 보안 강화, /api/v1 REST API, CLI 계정 조회 및 문제 해결.
- 정적 Go 바이너리와 Vue 3 + Element Plus SPA, Xray-core를 결합해 호스트 GLIBC 버전 의존성을 제거했습니다.
- 외부 컨트롤러, 자동화 스크립트, 다중 노드 오케스트레이션에 맞는 /api/v1 REST API를 제공합니다.
- systemd 샌드박스 강화(ProtectSystem=strict, NoNewPrivileges=true 등), 0700 데이터 디렉터리, 0600 DB 권한, SHA256 해시 API Token 저장을 기본 적용합니다.
- VLESS: XTLS-Reality, TCP, WebSocket, gRPC 전송을 지원해 낮은 오버헤드와 안정적인 연결을 제공합니다.
아키텍처와 핵심 기능
vaxilu/x-ui를 현대 클라우드 자동화와 운영 보안에 맞춰 전면 재설계한 nexcore-x-ui의 특징은 다음과 같습니다.
- 정적 Go 바이너리와 Vue 3 + Element Plus SPA, Xray-core를 결합해 호스트 GLIBC 버전 의존성을 제거했습니다.
- 외부 컨트롤러, 자동화 스크립트, 다중 노드 오케스트레이션에 맞는 /api/v1 REST API를 제공합니다.
- systemd 샌드박스 강화(ProtectSystem=strict, NoNewPrivileges=true 등), 0700 데이터 디렉터리, 0600 DB 권한, SHA256 해시 API Token 저장을 기본 적용합니다.
- 설치 경로, 서비스명, CLI(nexcore-x-ui)가 원본 x-ui와 분리되어 같은 서버에서도 충돌하지 않습니다.
시스템 요구 사항
- 운영체제 — systemd가 포함된 64비트 Linux(깨끗한 Ubuntu 22.04 / 24.04 LTS 또는 Debian 12 권장).
- 실행 권한 — systemd 서비스 등록, 포트 설정, 보호 디렉터리 생성을 위해 root 권한이 필요합니다.
- 네트워크 환경 — 공용 IP와 GitHub Releases 다운로드 연결이 필요하며 방화벽에서 패널과 프로토콜 포트를 열어야 합니다.
- 권장 서버 — Tovanix 네이티브 IP VPS, 듀얼 ISP VPS, 주거용 IP VPS 또는 물리 서버와 잘 맞습니다.
원클릭 설치 및 자동화 배포
root 권한으로 SSH 접속 후 공식 설치 스크립트를 실행하면 정적 바이너리 다운로드, 서비스 초기화, 랜덤 보안 계정 생성이 자동으로 끝납니다.
bash <(curl -fsSL https://raw.githubusercontent.com/Astrenix/nexcore-x-ui/main/install.sh)
클라우드 초기화 스크립트나 자체 컨트롤러로 대량 배포할 때는 보안 진입 경로와 Webhook 콜백 환경 변수를 함께 전달할 수 있습니다.
REPORT_URL=https://your-controller.example/callback \
REPORT_KEY=your_secret \
SECURE_ENTRY=1 \
bash <(curl -fsSL https://raw.githubusercontent.com/Astrenix/nexcore-x-ui/main/install.sh)
v2.1.3부터 보안상 초기 랜덤 계정과 비밀번호는 디스크의 install-info.txt에 평문 저장되지 않으며 터미널 배너와 systemd journal에만 기록됩니다.
초기 로그인 정보 조회 및 복구
설치 후 터미널을 닫았더라도 내장 CLI나 systemd journal 조회로 최초 배너와 접속 정보를 확인할 수 있습니다.
nexcore-x-ui creds
journalctl -u nexcore-x-ui --no-pager --since "1 day ago"
최초 로그인 후 패널 설정 또는 nexcore-x-ui passwd로 기본 비밀번호를 변경하고, 방화벽에서 패널 포트 접근을 제한하세요.
nexcore-x-ui CLI 명령 요약
설치 시 전역 nexcore-x-ui 명령이 등록되어 서비스 제어, 로그 확인, 비밀번호 변경, 업그레이드, 제거를 간편하게 처리할 수 있습니다.
- nexcore-x-ui — 번호 선택 방식의 대화형 관리 메뉴를 엽니다.
- nexcore-x-ui start | stop | restart | status — 패널 서비스를 시작, 중지, 재시작하거나 상태를 확인합니다.
- nexcore-x-ui creds / info — 현재 패널 포트, 진입 경로 및 초기 접속 정보를 표시합니다.
- nexcore-x-ui reset — 관리자 사용자명, 비밀번호, 패널 포트를 무작위로 다시 생성합니다.
- nexcore-x-ui passwd <user> <new_password> — 지정한 관리자 계정의 비밀번호를 새 비밀번호로 직접 변경합니다.
- nexcore-x-ui log / log-tail — 최근 200줄 로그를 출력하거나 실시간 로그 스트림을 추적합니다.
- nexcore-x-ui update — GitHub Releases 최신 버전으로 매끄럽게 업그레이드하고 서비스를 재시작합니다.
- nexcore-x-ui uninstall — 바이너리, systemd 서비스, 데이터 디렉터리를 완전히 제거합니다(실행 전 백업 필수).
지원 프로토콜 및 전송 방식
Xray-core 기반으로 사용자별 인증 정보, 트래픽 한도, 만료일 제어를 지원합니다.
- VLESS: XTLS-Reality, TCP, WebSocket, gRPC 전송을 지원해 낮은 오버헤드와 안정적인 연결을 제공합니다.
- VMess 및 Trojan: 기존 클라이언트 호환과 TLS 도메인 구성에 적합합니다.
- Shadowsocks 및 Shadowsocks-2022: 가볍고 빨라 일반 클라이언트와 중계 구간에 알맞습니다.
- SOCKS, HTTP, Dokodemo-door: 앱 프록시, 포트 포워딩, 다단 체인 아웃바운드에 활용됩니다.
인바운드 연결을 테스트한 뒤 무료 IP 품질 조회로 출구 IP의 네이티브 및 통신사 분류를 확인해 두세요.
자주 나는 문제 가리기
- 브라우저에서 패널 로그인 페이지가 열리지 않음 — 랜덤 패널 포트가 방화벽이나 보안 그룹에서 막혀 있거나 보안 진입 경로를 빠뜨렸습니다. — nexcore-x-ui status와 nexcore-x-ui info로 포트·경로를 확인하고 콘솔 방화벽에서 해당 TCP 포트를 여세요.
- 초기 랜덤 비밀번호를 분실함 — v2.1.3 이상 버전은 평문 파일을 남기지 않아 창을 닫으면 확인하기 어렵습니다. — nexcore-x-ui creds로 journal을 조회하거나 nexcore-x-ui passwd <user> <new_password>로 재설정하세요.
- 인바운드는 활성인데 클라이언트가 연결되지 않음 — 프로토콜 포트 미개방, Reality 대상 도메인 핸드셰이크 실패 또는 서버 시각 오차가 원인입니다. — TCP / UDP 방화벽과 NTP 시각 동기화를 확인하고 nexcore-x-ui log-tail로 Xray 오류를 점검하세요.
- 패널 내 업그레이드가 적용되지 않음 — GitHub Releases 다운로드 시간 초과나 이전 프로세스 잔류 때문입니다. — SSH에서 nexcore-x-ui update를 직접 실행해 출력 로그를 확인한 뒤 nexcore-x-ui status를 점검하세요.
자주 묻는 질문
원본 vaxilu/x-ui와 한 서버에 함께 설치할 수 있나요?
네. 바이너리, 데이터 디렉터리, systemd 서비스명, CLI가 모두 분리되어 있어 포트만 겹치지 않으면 공존할 수 있습니다.
nexcore-x-ui를 업그레이드하면 기존 인바운드와 사용자가 지워지나요?
아니요. 패널 업그레이드나 nexcore-x-ui update는 바이너리만 교체하며 데이터베이스와 설정을 유지합니다.
/api/v1로 노드 관리를 자동화하려면 어떻게 하나요?
패널 설정에서 API Token을 발급(서버에는 SHA256 해시만 저장)한 뒤 표준 REST 요청으로 인바운드·사용자·트래픽을 관리하면 됩니다.
관련 페이지: nexcore-s-ui 설치 및 구성 튜토리얼 (sing-box 노드 패널) · 자체 노드 패널 선택 가이드: nexcore-x-ui, nexcore-s-ui, 전용 프록시 · 전용 네트워크 구축 솔루션 · 네이티브 IP·주거용 IP VPS
불러오는 중…