Linux용 v2rayN 설치: deb/rpm 패키지 설치와 로그인 시 자동 실행 설정

설치 전 확인: 배포판, 아키텍처, 데스크톱 세션

v2rayN은 노드를 관리하고 코어를 실행하며 프록시를 설정하는 데스크톱 클라이언트입니다. deb/rpm 패키지는 프로그램을 설치할 뿐 노드나 구독 정보를 제공하지 않습니다. 터미널만 있고 그래픽 데스크톱이 없는 서버는 이 안내의 설치 환경에 해당하지 않습니다. 데스크톱 클라이언트를 부팅 시 실행되는 시스템 서비스로 취급해서도 안 됩니다.

먼저 터미널에서 시스템 정보를 확인합니다. Ubuntu와 Debian은 보통 deb, Fedora는 보통 rpm 패키지를 선택합니다. CPU 이름의 x86_64는 x64, aarch64는 arm64에 해당합니다. 패키지 형식이 같아도 배포판이나 아키텍처가 다르면 그대로 사용할 수 있는 것은 아닙니다.

cat /etc/os-release
uname -m
printf '데스크톱: %s\n세션: %s\n' "$XDG_CURRENT_DESKTOP" "$XDG_SESSION_TYPE"

다운로드 센터에서 Linux 설치 패키지를 선택합니다. 명령을 복사하기 쉽도록, 다운로드한 deb 파일의 이름을 v2rayN.deb로, rpm 파일의 이름을 v2rayN.rpm으로 바꾼 뒤 해당 파일이 있는 디렉터리에서 터미널을 엽니다. 이는 로컬 파일 이름을 정한 것일 뿐, 패키지 버전·아키텍처·소프트웨어 패키지 이름은 바뀌지 않습니다.

deb/rpm 설치: 패키지 관리자로 의존성 처리

먼저 패키지 정보를 확인한 다음 설치합니다. 설치 전에 아키텍처를 잘못 선택했거나 파일 형식이 맞지 않는 문제를 발견할 수 있습니다. 웹 페이지에서 받은 내용을 설치 패키지로 취급하지 말고, 의존성 무시 옵션으로 오류를 강제로 넘기지 마세요.

Debian / Ubuntu: apt로 로컬 deb 설치

dpkg-deb -f ./v2rayN.deb Package Version Architecture
sudo apt update
sudo apt install ./v2rayN.deb

./는 현재 디렉터리의 파일을 가리키므로 저장소 패키지 이름처럼 생략할 수 없습니다. dpkg -i만 실행하는 것과 달리 apt는 활성화된 소프트웨어 저장소를 통해 의존성을 해결할 수 있습니다. 앞서 설치가 의존성 오류로 중단됐다면 sudo apt --fix-broken install의 처리 계획을 먼저 확인하고, 필요한 소프트웨어가 제거되지 않는지 검토한 뒤 진행하세요.

Fedora: dnf로 로컬 rpm 설치

rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' ./v2rayN.rpm
sudo dnf install ./v2rayN.rpm

dnf에서 의존성이 없다는 메시지가 나오면 배포판 버전, 저장소 상태, 패키지의 지원 환경을 확인하세요. Debian의 라이브러리 파일을 Fedora에 복사하거나, 의존성이 충족된 것처럼 보이도록 공유 라이브러리 심볼릭 링크를 임의로 만들지 마세요. 패키지 압축을 풀 수 있다고 프로그램이 정상 실행되는 것은 아닙니다.

1. 패키지 정보 확인

   패키지의 Version과 Architecture를 확인하세요. Debian의 amd64와 RPM에서 흔히 쓰는 x86_64는 모두 x64 아키텍처를 가리킵니다.

2. 설치 완료

   해당하는 apt 또는 dnf 명령을 실행하고, 터미널에 표시된 구체적인 오류를 보관하세요. 단순히 “설치 실패”라고만 기록하지 마세요.

3. 클라이언트 실행

   데스크톱 앱 메뉴에서 v2rayN을 검색한 뒤 현재 사용자로 실행하세요. sudo로 그래픽 인터페이스를 실행하지 마세요.

4. 가져오기 및 테스트

   공유 링크를 복사한 다음 메인 창의 노드 목록에서 마우스 오른쪽 버튼을 클릭하고 「클립보드에서 공유 링크 가져오기」를 선택합니다. 노드를 선택하고 「활성 서버로 설정」을 실행하세요. 메뉴 문구는 버전에 따라 조금 다를 수 있습니다.

프록시 설정: 먼저 리스닝을 확인하고 데스크톱 프록시 설정

설치만으로 모든 준비가 끝나는 것은 아닙니다. 활성 노드가 작동하는지, 코어가 실행 중인지, 로컬 인바운드가 리스닝 중인지 확인해야 합니다. 「설정」→「매개변수 설정」에서 로컬 리스닝 포트와 관련 인바운드 설정을 확인하고, 클라이언트 로그에서 실제 실행 결과를 살펴보세요. 버전에 따라 설정이 다른 탭에 있을 수 있으므로 예전 스크린샷의 위치만 믿고 찾지 마세요.

아래 예시는 클라이언트가 127.0.0.1:10808에서 HTTP 프록시 또는 혼합 인바운드를 제공한다고 가정합니다. 실제 포트가 다르면 데스크톱 설정과 테스트 명령을 모두 수정하세요. 해당 포트가 SOCKS만 지원한다면 HTTP 프록시 항목에 입력할 수 없습니다. 특별한 이유가 없다면 리스닝 주소를 0.0.0.0으로 바꾸지 마세요. 다른 기기에도 프록시 포트가 노출될 수 있습니다.

HTTPS 프록시 항목은 “HTTPS 웹사이트에 접속할 때 사용할 프록시”를 뜻하며, 로컬에서 TLS 프록시 서버를 직접 실행해야 한다는 의미는 아닙니다. HTTP 프록시는 CONNECT를 통해 HTTPS 요청을 전달할 수 있습니다. 시스템 프록시가 모든 트래픽을 처리하는 것도 아닙니다. 일부 터미널 프로그램, 독립적인 네트워크 구성 요소, 자체 프록시를 설정한 앱은 데스크톱 설정을 따르지 않습니다.

• 프록시 설정 방식은 하나를 우선 사용하세요. 클라이언트가 데스크톱 프록시를 올바르게 설정할 수 있으면 클라이언트의 설정 기능을 사용하고, 그렇지 않으면 데스크톱 설정에 직접 입력하세요.
• 수동으로 설정할 때는 localhost,127.0.0.1,::1처럼 로컬 주소를 제외 목록에 추가하세요. 구분 기호는 데스크톱 환경의 안내를 따릅니다.
• 먼저 일반 시스템 프록시로 연결을 확인한 다음, 추가 권한과 라우팅 설정이 필요한 TUN 모드를 고려하세요.

연결 확인: 포트, 요청, 브라우저를 따로 점검

노드 목록의 지연 시간만으로 연결 상태를 모두 확인할 수는 없습니다. TCP 연결은 대상 포트에 도달할 수 있다는 점만 보여 줍니다. 실제 프록시 요청을 이용한 연결 테스트를 진행하고, 브라우저에서도 접속해 확인하세요. 먼저 리스닝 상태를 확인하고, 프록시를 명시한 명령으로 요청한 뒤, 데스크톱 앱이 프록시 설정을 읽는지 점검합니다.

# 예시 포트의 리스닝 여부 확인
ss -lntp 'sport = :10808'

# HTTP 프록시를 명시해 데스크톱 설정 적용 여부와 무관하게 테스트
curl --noproxy "" --proxy http://127.0.0.1:10808 \
  --connect-timeout 5 --max-time 15 \
  -I https://example.com/

example.com은 공개된 예시 사이트입니다. 이 명령은 요청 경로를 테스트하기 위한 것으로, 구독 주소가 아닙니다. HTTP 응답 헤더가 반환되면 해당 요청이 지정한 프록시를 거쳐 응답을 받았다는 뜻입니다. 그렇다고 모든 웹사이트나 모든 라우팅 규칙이 정상이라고 단정할 수는 없습니다. curl이 설치되어 있지 않으면 Debian/Ubuntu에서는 sudo apt install curl, Fedora에서는 sudo dnf install curl을 실행하세요.

브라우저가 “시스템 프록시 사용”으로 설정되어 있다면 보통 새 연결을 시작해야 설정이 적용됩니다. 그래도 해결되지 않으면 브라우저를 완전히 종료한 뒤 다시 실행하세요. DNS, 라우팅, 노드, 리스닝 포트를 한꺼번에 바꾸면 원인을 파악하기 어렵습니다. 매번 한 항목씩 변경하고 요청 시간과 관련 로그를 기록하세요.

자동 실행: 데스크톱 로그인 항목 사용, GUI 프로그램을 시스템 서비스로 등록하지 않기

여기서 말하는 “부팅 시 자동 실행”은 정확히는 “사용자가 그래픽 데스크톱에 로그인한 뒤 실행”하는 것입니다. 로그인 화면에 머물러 있는 동안에는 사용자 데스크톱 세션이 아직 시작되지 않았습니다. v2rayN은 그래픽 세션과 사용자 설정에 의존합니다. 시스템 서비스로 등록해도 데스크톱 로그인 항목을 대신할 수 없으며, 디스플레이 환경·권한·설정 디렉터리가 일치하지 않는 문제가 생길 수 있습니다.

설치된 패키지에서 데스크톱 실행 항목 찾기

설치 패키지마다 프로그램 경로와 데스크톱 파일 이름이 다를 수 있으므로 Exec 값을 임의로 고정하지 마세요. 아래 명령 두 개 중 설치 형식에 맞는 하나를 선택해 설치 패키지가 있는 디렉터리에서 실행하면, 패키지 메타데이터를 통해 실제 데스크톱 실행 항목을 찾을 수 있습니다.

# Debian / Ubuntu
pkg=$(dpkg-deb -f ./v2rayN.deb Package)
dpkg -L "$pkg" | grep -E '/applications/[^/]+\.desktop$'

# Fedora
pkg=$(rpm -qp --queryformat '%{NAME}' ./v2rayN.rpm)
rpm -ql "$pkg" | grep -E '/applications/[^/]+\.desktop$'

파일 관리자에서 찾은 v2rayN 데스크톱 파일을 복사해 현재 사용자의 ~/.config/autostart/에 넣으세요. 디렉터리가 없다면 먼저 만듭니다. XDG_CONFIG_HOME을 설정했다면 기본 경로가 아니라 해당 디렉터리 아래의 autostart/를 사용하세요.

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/autostart"

• 복사하기 전에 데스크톱 파일을 열어 Exec=가 설치된 프로그램을 가리키는지 확인하세요. 기존 인수는 유지하고 경로를 추측해 바꾸지 마세요.
• Hidden=true가 있거나 데스크톱 환경을 제한하는 항목이 있는지 확인하세요. 기존에 비활성화된 항목 때문에 로그인 후 실행되지 않을 수 있습니다.
• GNOME에서는 설치된 시작 앱 관리 도구로 추가할 수 있습니다. KDE Plasma에서는 「시스템 설정」→「자동 시작」에서 앱을 추가하세요. 메뉴 분류는 버전에 따라 다를 수 있습니다.
• 데스크톱 설정과 파일 복사 중 한 가지 방법만 사용하세요. 로그인 항목을 두 개 만들면 중복 실행이나 포트 충돌이 발생할 수 있습니다.

설정을 마친 뒤에는 창만 닫는 것보다 로그아웃 후 다시 로그인해 확인하는 편이 좋습니다. 클라이언트가 하나만 실행 중인지 확인한 다음 리스닝 포트와 프록시 상태를 점검하세요. 로그인 항목은 프로그램 실행만 보장합니다. 활성 노드에 자동 연결할지, 시스템 프록시를 자동으로 설정할지는 현재 버전의 별도 옵션에서 확인해야 합니다.

자주 발생하는 문제: 의존성, 데스크톱 실행 항목, 포트 충돌

문제를 해결할 때는 배포판 버전, 아키텍처, 패키지 버전, 오류 메시지 전체를 기록하세요. 계속 재설치하는 것보다 효과적입니다. 권한 문제를 피하려고 관리자 권한으로 클라이언트를 실행하지 마세요. 사용자 설정 파일이 root 소유로 저장되어 다음 일반 실행 때 설정을 저장하지 못할 수 있습니다.

업그레이드 및 이전 버전으로 되돌리기: 사용자 설정을 유지하고 로그인 항목 확인

이후 업그레이드도 같은 패키지 관리자로 새 deb/rpm 파일을 설치하면 됩니다. 업그레이드 전에 클라이언트를 종료하고, 클라이언트의 백업 기능을 사용하거나 실제 설정 위치를 확인해 사용자 데이터를 백업하세요. 설정 경로는 버전과 패키징 방식에 따라 달라질 수 있으므로 프로그램 디렉터리를 설정 디렉터리로 단정하지 마세요. 백업 파일에 구독 인증 정보가 포함될 수 있으니 현재 사용자가 관리할 수 있는 위치에 보관하세요.

1. 새 패키지가 지원하는 배포판과 CPU 아키텍처를 확인하세요.
2. 클라이언트를 종료한 다음 앞에서 안내한 로컬 패키지 설치 명령을 실행하세요.
3. 클라이언트를 한 번 수동으로 실행해 활성 노드, 리스닝 포트, 요청 결과를 확인하세요.
4. 사용자 로그인 항목의 실행 경로를 확인한 뒤 로그아웃과 재로그인으로 최종 점검하세요.

일시적으로 사용을 중지하려면 시스템 프록시를 끄고, 클라이언트를 종료한 다음 데스크톱 로그인 항목을 비활성화하세요. 제거할 때는 앞에서 확인한 실제 소프트웨어 패키지 이름을 사용해 apt 또는 dnf로 삭제합니다. 사용자 디렉터리의 로그인 항목 사본과 설정은 남아 있을 수 있으므로 별도로 확인하세요. 프로그램 제거와 데스크톱 프록시 복원은 별개의 작업입니다.