Linux 그래픽 데스크톱에 v2rayN을 설치하려는 사용자를 위한 안내입니다. 먼저 배포판과 CPU 아키텍처에 맞는 패키지를 고르고, 시스템 패키지 관리자로 설치한 다음 일반 사용자 계정으로 앱 메뉴에서 v2rayN을 실행하세요. 직접 실행해 정상 작동을 확인한 뒤 설치 패키지의 데스크톱 항목을 재사용해 로그인 시 자동 실행을 설정하고, 클라이언트 프로세스와 프록시 트래픽을 각각 확인합니다.
패키지 선택: 배포판과 CPU 아키텍처 확인
v2rayN을 실행할 시스템에서 아래 두 명령을 실행하세요. 첫 번째 명령은 배포판 정보를, 두 번째 명령은 시스템 아키텍처를 확인합니다. 가상 머신에서 실행할 예정이라면 호스트가 아닌 가상 머신 안에서 확인해 패키지를 선택하세요.
cat /etc/os-release
uname -m
Debian / Ubuntu
- 설치 패키지
.deb- 패키지 관리 도구
apt- 아키텍처 확인
dpkg --print-architecture
패키지 메타데이터의 amd64는 x86_64에, arm64는 aarch64에 해당합니다.
Fedora / openSUSE
- 설치 패키지
.rpm- 패키지 관리 도구
- Fedora는
dnf, openSUSE는zypper를 사용합니다 - 아키텍처 이름
x86_64또는aarch64
확장자가 같아도 의존성이 같다는 뜻은 아닙니다. 릴리스 노트에서 지원 배포판과 버전을 확인하세요.
deb 또는 rpm 설치: 패키지 관리자로 의존성 처리
터미널에서 설치 패키지가 있는 디렉터리로 이동하세요. 아래 예시의 ./v2rayN.deb와 ./v2rayN.rpm은 로컬 파일명입니다. 실행할 때 실제 파일명으로 바꾸세요. 현재 디렉터리의 파일을 설치하도록 ./는 그대로 둡니다. 아래 세 명령 중 현재 배포판에 맞는 하나만 실행하세요.
# Debian / Ubuntu
sudo apt install ./v2rayN.deb
# Fedora
sudo dnf install ./v2rayN.rpm
# openSUSE
sudo zypper install ./v2rayN.rpm
배포판별 패키지 관리자
권장로컬 패키지에서 의존성을 확인하고 활성화된 저장소에서 조건에 맞는 버전을 찾습니다. 작업을 확정하기 전에 어떤 패키지가 추가·업그레이드·삭제되는지 확인할 수 있습니다.
적합한 경우: 최초 설치, 기존 설치 업그레이드
저수준 패키지 도구
dpkg-deb -I ./v2rayN.deb 또는 rpm -qpR ./v2rayN.rpm으로 패키지 메타데이터나 의존성을 확인할 수 있습니다. 저수준 도구로 직접 설치하면 앞서 설명한 패키지 관리자처럼 저장소에서 의존성을 자동으로 해결하지 않습니다.
적합한 경우: 패키지 정보 확인, 누락된 의존성 파악
Debian 또는 Ubuntu에서 의존성을 찾을 수 없다는 메시지가 나오면 먼저 sudo apt update를 실행한 뒤 설치 명령을 다시 실행하세요. 특정 라이브러리 버전이 맞지 않는다는 오류가 나오면 라이브러리 이름과 필요한 최소 버전을 기록하고, 사용 중인 배포판 버전이 지원 대상인지 확인하세요. 의존성을 강제로 무시해 설치하지 마세요. 이전에 dpkg로 설치한 패키지가 설정되지 않은 상태라면 sudo apt --fix-broken install 실행 전 작업 요약을 확인하세요. 저장소에서 의존성을 해결할 수 없으면 복구 과정에서 해당 패키지가 설치되는 대신 제거될 수 있습니다.
앱 메뉴에서 실행: 항목 찾기와 문제 해결
앱 검색
설치 후 GNOME 앱 검색이나 KDE Plasma 앱 실행기에서 「v2rayN」을 검색하세요. 먼저 현재 데스크톱 사용자 계정으로 한 번 실행합니다. 설치 명령에는 관리자 권한이 필요하지만 그래픽 클라이언트를 실행할 때는 관리자 권한을 사용할 필요가 없습니다.
패키지 파일 목록 확인
메뉴에 항목이 없으면 Debian 계열은 설치된 패키지명을 넣어
dpkg-query -L을, RPM 계열은 설치된 패키지명과 함께rpm -ql을 사용하세요. 패키지명은dpkg-deb -f ./v2rayN.deb Package또는rpm -qp --qf '%{NAME}\n' ./v2rayN.rpm으로 확인할 수 있습니다. 파일 목록에서 찾아야 할 실행 항목은.desktop파일입니다. 설치 패키지의 파일명을 실행 명령으로 착각하지 마세요.데스크톱 항목의 필드 확인
데스크톱 항목 파일을 열어
Name과Exec을 확인하세요.NoDisplay=true가 있으면 항목 파일은 존재해도 앱 메뉴에는 표시되지 않을 수 있습니다.TryExec이 있다면 지정된 프로그램이 존재하고 실행 가능한지도 확인하세요. 시스템 디렉터리의 항목을 직접 수정하지 마세요. 패키지를 업그레이드하면 수정 사항이 덮어써질 수 있습니다.실행 오류 확인
아이콘은 보이는데 클릭해도 창이 열리지 않으면 먼저 시스템 트레이에 이미 실행 중인 인스턴스가 있는지 확인하세요. 그런 다음 그래픽 세션의 터미널에서 일반 사용자로 항목이 가리키는 프로그램을 실행합니다. 항목에 필요한 인수는 유지하되
%U,%F같은 데스크톱 항목 필드 코드를 프로그램에 그대로 전달하지 마세요. 처음 발생한 실행 오류를 기록해 동적 라이브러리 누락, 잘못된 경로, 클라이언트 중복 실행을 구분하세요.
XDG 자동 시작: 데스크톱 로그인 후 v2rayN 실행
XDG 자동 시작은 그래픽 데스크톱 세션에서 처리됩니다. 사용자 로그인 후 실행되며, 시스템 전원이 켜진 뒤 로그인하기 전에 서비스로 실행되는 것과는 다릅니다. 먼저 클라이언트 자체의 자동 시작 설정이나 데스크톱 환경의 자동 시작 목록에 v2rayN이 이미 등록되어 있는지 확인하세요. 같은 계정에는 항목을 하나만 남겨 중복 실행을 방지합니다.
- 아래 명령으로 현재 사용자용 자동 시작 디렉터리를 만드세요.
XDG_CONFIG_HOME이 설정되어 있으면 그 디렉터리 아래의autostart를 사용합니다. 기본 경로는 보통~/.config/autostart입니다. - 파일 관리자에서 앞 절의 패키지 파일 목록으로 찾은
.desktop파일을 해당 디렉터리에 복사하세요. 실제 파일명과 원래Exec값은 유지합니다. 설치 패키지 파일을 복사하지 말고, 사용자 항목을 만들 때sudo를 사용하지 마세요. - 텍스트 편집기로 복사한 파일의
[Desktop Entry]섹션을 확인하세요.Hidden=true가 있으면 해당 줄을 삭제하거나Hidden=false로 바꾸세요.OnlyShowIn과NotShowIn이 현재 데스크톱 세션을 허용하는지,TryExec경로가 유효한지도 확인합니다. - 현재 그래픽 세션에서 로그아웃한 뒤 다시 로그인하세요. 창, 시스템 트레이 또는 시스템 모니터를 확인합니다. 프로세스만 보이고 창이 나타나지 않으면 최소화 실행이 설정되어 있는지 먼저 확인한 다음 실제 실행 실패 여부를 살펴보세요.
autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$autostart_dir"
printf '%s\n' "$autostart_dir"
직접 설정한 자동 시작을 끄려면 사용자 디렉터리에 복사한 항목만 삭제하고 시스템 디렉터리의 원본은 그대로 두세요. 데스크톱 환경에 같은 이름의 시스템 자동 시작 항목이 있으면 사용자 복사본을 삭제한 뒤 시스템 항목이 다시 활성화될 수 있습니다. 이 경우 데스크톱의 자동 시작 설정에서 비활성화하거나 같은 이름의 사용자 항목에 Hidden=true를 설정해 덮어쓸 수 있습니다. 업그레이드 후 시스템 항목의 Exec 값이 바뀌었다면 사용자 복사본도 다시 확인하세요.
로그인 후 문제 해결: 프로그램·포트·프록시 설정 점검
메뉴에서는 열리는데 다시 로그인하면 실행되지 않나요?
터미널에 표시된 자동 시작 디렉터리와 대조해 실제 .desktop 파일을 넣었는지 확인하세요. 텍스트 편집기가 .txt 확장자를 덧붙인 파일은 아닌지도 살펴봅니다. 그런 다음 항목 제한 설정과 실행 경로를 확인하세요. 항목을 직접 실행해도 실패한다면 먼저 실행 오류를 해결하세요. 지연 실행으로 문제를 감추지 마세요.
프로세스는 실행 중인데 브라우저가 프록시를 사용하지 않나요?
v2rayN의 「설정」→「매개변수 설정」에서 로컬 수신 포트를 확인한 뒤, 시스템 트레이의 「시스템 프록시」가 설정 상태인지 해제 상태인지 살펴보세요. ss -ltnp로 TCP 수신 포트를 확인하고 클라이언트에 표시된 실제 포트와 대조할 수 있습니다. 포트가 수신 중이라는 것은 로컬 프로세스가 연결을 받고 있다는 뜻일 뿐입니다. 브라우저의 프록시 설정 출처, 활성 노드, 클라이언트 로그도 확인해야 합니다.
로그인 후 구독이 업데이트되지 않는데 자동 시작 문제인가요?
먼저 클라이언트가 실행 중인지 확인한 다음 네트워크가 연결될 때까지 기다렸다가 구독을 직접 업데이트하세요. 이때 업데이트에 성공한다면 로그인 시 무선 네트워크 연결이 아직 완료되지 않았는지, 클라이언트의 구독 업데이트 설정은 어떤지 확인합니다. 데스크톱 프로그램 실행, 네트워크 연결 준비, 구독 업데이트는 각각 별개의 단계이므로 따로 점검해야 합니다.