Ubuntu와 Debian에서는 deb, Fedora에서는 rpm 패키지를 선택하세요. 관리자 권한은 설치할 때만 필요합니다. 처음 실행할 때는 일반 데스크톱 계정으로 로그인하고, 로컬 프록시가 작동하는지 확인한 뒤 시스템 프록시와 로그인 시 자동 실행을 설정하세요. 아래에서 설치 명령, 포트 확인 방법, 앱 메뉴에서는 실행되지만 로그인 후에는 실행되지 않을 때의 해결 방법을 살펴봅니다.
Linux 설치 패키지 선택: 배포판과 CPU 아키텍처
먼저 배포판을 확인한 다음 아키텍처를 확인하세요. 터미널에서 아래 두 명령을 실행합니다. 첫 번째 명령은 배포판과 버전을, 두 번째 명령은 시스템 아키텍처를 확인합니다. Ubuntu와 Debian의 패키지 메타데이터에서는 x86_64를 amd64로, aarch64를 arm64로 표기하는 경우가 많습니다. Fedora 패키지는 주로 x86_64와 aarch64를 사용합니다. 다운로드 페이지의 x64는 첫 번째 아키텍처를 뜻합니다.
cat /etc/os-release
uname -m
Debian 계열 패키지
- 대상 배포판
- Ubuntu、Debian
- 파일 확장자
.deb- 패키지 아키텍처 필드
amd64또는arm64- 설치 도구
apt
apt로 로컬 패키지를 설치하면 저장소에서 이용할 수 있는 의존성도 함께 처리합니다.
Fedora 패키지
- 대상 배포판
- Fedora
- 파일 확장자
.rpm- 패키지 아키텍처 필드
x86_64또는aarch64- 설치 도구
dnf
rpm 형식이 같아도 의존성까지 같은 것은 아닙니다. 다른 배포판에서는 패키지 호환성을 별도로 확인하세요.
오류에 아키텍처가 맞지 않는다고 명시되어 있으면 다운로드 페이지로 돌아가 알맞은 패키지를 받으세요. 강제로 설치하지 마세요. 아키텍처는 맞지만 라이브러리가 없다는 메시지가 표시되면 해결되지 않은 첫 번째 의존성과 버전을 기록한 다음, 현재 배포판과 버전에 맞는 저장소를 확인하세요. 다른 배포판에서 같은 이름의 라이브러리만 따로 가져오지 마세요.
deb·rpm 설치 명령
아래 두 명령 중 사용 중인 배포판에 해당하는 것만 실행하세요. 입력 안내가 나오면 방금 다운로드한 설치 패키지의 절대 경로를 붙여 넣습니다. 경로를 따옴표로 감싸지 마세요. 설치 명령의 큰따옴표가 경로에 포함된 공백을 처리합니다. 먼저 패키지 메타데이터에서 이름, 버전, 아키텍처를 확인한 뒤 sudo를 사용하는 설치 명령을 실행하세요.
Ubuntu·Debian: apt로 deb 설치
printf 'deb 설치 패키지의 절대 경로를 입력하세요: '
IFS= read -r pkg
dpkg-deb -f "$pkg" Package Version Architecture
sudo apt install "$pkg"
터미널에서 의존성을 다운로드하지 못했다는 메시지가 나오면, 먼저 프록시를 끈 상태에서 시스템이 저장소에 접속할 수 있는지 확인한 다음 sudo apt update를 실행하고 다시 시도하세요. 설치 계획에 기존 데스크톱 구성요소를 제거한다고 표시되면 먼저 취소하고, 배포판이나 버전이 다른 저장소를 함께 사용하고 있지 않은지 확인하세요.
Fedora: dnf로 rpm 설치
printf 'rpm 설치 패키지의 절대 경로를 입력하세요: '
IFS= read -r pkg
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"
설치가 끝나면 데스크톱 앱 메뉴에서 「v2rayN」을 검색하세요. 터미널에 패키지가 설치되었다고 표시되어도 파일이 배포된 것만 확인된 것이며, 그래픽 인터페이스와 코어가 실행 중이라는 뜻은 아닙니다. 메뉴에 앱 항목이 없으면 위에서 확인한 패키지 이름을 기록하세요. Ubuntu와 Debian에서는 dpkg -L 뒤에 패키지 이름을 붙이고, Fedora에서는 rpm -ql 뒤에 패키지 이름을 붙여 패키지에 포함된 .desktop 파일과 설치 경로를 확인할 수 있습니다.
첫 실행 권한 및 시스템 프록시 확인
일반 데스크톱 계정으로 v2rayN을 실행하고, 처음에는 TUN을 켜지 마세요. sudo로 인터페이스를 열지 마세요. 설치에는 관리자 권한이 필요하지만, 개인 설정 파일을 읽고 쓰거나 로컬 프록시를 실행하는 데는 보통 필요하지 않습니다. 시작 로그에 Permission denied가 표시되면 오류가 사용자 설정 파일을 가리키는지 코어 실행 파일 경로를 가리키는지 먼저 확인하세요. 설치 디렉터리 전체에 재귀적으로 권한을 부여하지 마세요.
현재 노드 선택
설정이 이미 있다면 메인 화면의 노드 목록에서 사용할 노드를 선택하고 마우스 오른쪽 버튼을 눌러 「활성 서버로 설정」을 선택하세요. 새로 설치해 목록이 비어 있다면 먼저 「구독 그룹」에서 구독을 추가하고 업데이트하세요. 이어서 메인 화면 로그에서 코어 시작 오류가 없는지 확인합니다.
수신 포트 확인
「설정」→「매개변수 설정」을 열고 「로컬 수신 포트」와 로컬 인바운드 설정을 확인하세요. 버전에 따라 항목 이름이 조금 다를 수 있습니다. 화면에 표시된 실제 포트를 사용하고, 노드 서버의 원격 포트를 로컬 앱에 입력하지 마세요.
로컬 프록시 테스트
먼저 터미널 요청이 로컬 프록시를 명시적으로 거치도록 설정해 코어 연결 문제와 데스크톱 프록시 설정 문제를 구분하세요. 아래 명령은 혼합 인바운드 포트
10808을 예로 듭니다. 버전에서 HTTP와 SOCKS 포트를 따로 사용하는 경우 인바운드 프로토콜과 실제 포트에 맞게 바꾸세요.시스템 프록시 설정
v2rayN 메인 화면 하단이나 시스템 트레이에서 「시스템 프록시」를 열고 「시스템 프록시 자동 설정」을 선택하세요. GNOME에서는 「설정」→「네트워크」→「네트워크 프록시」에서 적용 여부를 확인할 수 있습니다. 데스크톱 설정이 바뀌지 않았다면 대상 앱에서 자체 프록시 설정을 사용하고, 코어를 반복해서 재시작하지 마세요.
ss -ltn 'sport = :10808'
curl --max-time 15 -I --proxy socks5h://127.0.0.1:10808 https://example.com/
첫 번째 명령은 로컬 TCP 포트가 수신 대기 중인지 확인합니다. 두 번째 명령으로 대상 사이트의 HTTP 응답 헤더를 받아야 지정한 프록시를 통해 요청이 처리된 것입니다. 로컬 포트에 연결할 수 없다는 메시지가 바로 나오면 포트와 코어 로그를 확인하세요. 포트가 수신 대기 중인데 요청 시간이 초과되면 현재 노드, 네트워크, 라우팅을 확인하세요. 브라우저에서는 되지만 터미널에서는 안 된다고 설치가 실패한 것은 아닙니다. 많은 터미널 프로그램은 데스크톱 프록시 설정을 읽지 않으므로 앱별로 프록시를 지정할 수 있습니다.
로그인 시 자동 실행: 데스크톱 로그인 후 v2rayN 실행
데스크톱 앱의 자동 실행은 보통 그래픽 세션에 로그인한 뒤 시작된다는 뜻이며, 로그인 화면이 나타나기 전부터 실행된다는 의미는 아닙니다. 먼저 앱 메뉴에서 v2rayN이 정상적으로 열리는지 확인한 뒤 아래 두 방법 중 하나를 선택하세요. 자동 실행을 중복으로 설정하면 로그인할 때마다 여러 번 실행될 수 있고, 비활성화하거나 문제를 해결하기도 어려워집니다.
데스크톱 세션에서 자동 실행 설정
권장KDE Plasma에서는 「시스템 설정」을 열고 「자동 시작」을 검색한 다음, 「추가」→「애플리케이션 추가」를 선택해 목록에서 v2rayN을 고르세요. Ubuntu 앱 메뉴에 「시작 애플리케이션(Startup Applications)」이 있다면 여기서 「추가」를 선택하고, 실행이 확인된 실제 프로그램 명령을 입력할 수 있습니다. 메뉴 이름은 데스크톱 버전에 따라 다를 수 있습니다.
권장 대상: 데스크톱에 자동 실행 관리 기능이 있고 그래픽 인터페이스에서 간편하게 켜고 끄고 싶은 경우
사용자별 XDG 자동 실행 항목
설치된 패키지의 파일 목록에서 앱 메뉴에 연결된 .desktop 파일을 찾아 현재 사용자의 자동 실행 디렉터리에 복사하세요. 다른 컴퓨터의 설치 경로를 참고해 직접 작성하는 것보다 기존 Exec= 실행 명령을 그대로 유지하는 편이 안전합니다.
권장 대상: 데스크톱이 XDG 자동 실행 규격을 따르지만 편리한 그래픽 설정 화면을 제공하지 않는 경우
파일 방식으로 설정하려면 터미널에서 아래 명령을 실행하고, 안내에 따라 확인해 둔 .desktop 파일의 절대 경로를 입력하세요. sudo를 추가하지 마세요. XDG_CONFIG_HOME을 따로 지정하지 않았다면 자동 실행 디렉터리는 ~/.config/autostart입니다.
printf '설치된 .desktop 파일의 절대 경로를 입력하세요: '
IFS= read -r desktop_file
autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$autostart_dir"
cp -i -- "$desktop_file" "$autostart_dir/"
v2rayN을 직접 열지 말고 로그아웃한 다음 다시 로그인하세요. 데스크톱이 로드되면 시스템 트레이, 창 또는 로컬 수신 포트를 확인합니다. 창은 나타났지만 웹페이지가 프록시를 거치지 않는다면 시스템 프록시 상태를 다시 확인하세요. 프로그램을 시작하는 것과 프록시 설정을 적용하는 것은 별개의 작업입니다. 파일 방식의 자동 실행을 해제하려면 현재 사용자 자동 실행 디렉터리에 있는 복사본만 옮기거나 삭제하면 됩니다. 앱 메뉴 항목은 그대로 유지됩니다.
Linux 설치 및 자동 실행 FAQ
설치는 끝났는데 메뉴를 눌러도 실행되지 않나요?
패키지의 .desktop 파일에서 Exec=가 어떤 경로를 가리키는지 확인하세요. command -v v2rayN을 실행해 해당 이름이 검색 경로에 있는지도 확인할 수 있습니다. 검색 경로에 없으면 패키지 파일 목록에서 실제 실행 파일을 찾아 일반 계정으로 터미널에서 실행한 뒤 오류 메시지를 확인하세요. 공유 라이브러리를 찾을 수 없다는 메시지가 나오면 관리자 권한으로 다시 실행하지 말고 라이브러리 이름과 배포판 버전에 맞춰 의존성을 확인하세요.
직접 실행하면 되지만 다시 로그인한 뒤에는 실행되지 않나요?
먼저 자동 실행 항목을 추가했던 계정으로 로그인했는지 확인하세요. 그런 다음 사용자 디렉터리에 있는 .desktop 파일을 열고 Hidden=true, OnlyShowIn, NotShowIn 설정이 있는지 살펴보세요. 패키지를 최근에 업그레이드했다면 앱 메뉴에서 현재 사용하는 파일과 자동 실행용 복사본을 비교해 Exec=가 여전히 올바른 경로를 가리키는지 확인하세요.
로그에 포트가 이미 사용 중이라고 나오면 어떻게 하나요?
ss -ltnp 'sport = :10808'을 실행해 예시 포트를 확인하세요. 실제 포트가 다르면 숫자를 바꾸면 됩니다. 먼저 v2rayN이 중복 실행 중인지 확인하고 종료하세요. 다른 정상 프로그램이 해당 포트를 사용 중이라면 「설정」→「매개변수 설정」에서 로컬 수신 포트를 바꾸고, 브라우저나 터미널에 수동으로 설정한 프록시 포트도 함께 수정하세요.
프로그램을 종료한 뒤 브라우저에서 웹페이지가 열리지 않나요?
자동 설정을 사용했다면 종료 전에 「시스템 프록시」에서 「시스템 프록시 지우기」를 선택할 수 있습니다. 이미 종료했다면 데스크톱의 네트워크 프록시 설정에서 사용 전 상태로 되돌리세요. 브라우저에 프록시를 직접 지정했다면 브라우저 설정도 복구해야 합니다. 그렇지 않으면 더 이상 수신 대기하지 않는 로컬 포트에 계속 연결을 시도할 수 있습니다.