v2rayN Linux 설치: deb·rpm 패키지 설치와 자동 시작 설정

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

v2rayN은 데스크톱 설정 관리 프로그램이며 실제 연결은 호출되는 프록시 코어가 처리합니다. 이 글에서 설치하는 것은 그래픽 클라이언트이므로 사용 가능한 데스크톱 세션이 필요합니다. 터미널만 있는 서버에는 이 설치 방법을 그대로 적용하기 어렵습니다. 일반 사용자 터미널에서 아래 명령을 실행해 배포판, 프로세서 아키텍처, 데스크톱 환경을 확인하세요.

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

클라이언트 다운로드 페이지에서 Linux와 해당 아키텍처를 선택하세요. Windows용 파일을 Linux 패키지로 사용하거나 파일 확장자만 바꿔 패키지 형식을 변환하지 마세요. 아래 명령은 Bash에서 실행하며, 파일 경로를 직접 입력하므로 고정된 버전 번호나 파일 이름이 필요하지 않습니다.

deb 설치: apt로 의존성 처리

Debian 또는 Ubuntu에서는 로컬 deb 파일을 apt로 설치하는 방법을 권장합니다. 설정된 저장소를 이용해 의존성을 해결하기 때문입니다. 저수준 설치 명령만 실행하면 압축 해제만 끝나고 의존성이 충족되지 않을 수 있습니다. 파일 경로를 입력할 때는 절대 경로를 그대로 붙여 넣고 따옴표를 추가하지 마세요. 이후 명령에서 변수는 이미 올바르게 인용 처리됩니다.

read -r -p 'deb 파일의 절대 경로를 입력하세요: ' package_file
dpkg-deb -f "$package_file" Package Version Architecture
sudo apt install "$package_file"

1. 패키지 정보 확인

   표시된 패키지 이름, 버전, 아키텍처를 확인해 이번에 다운로드한 파일이 맞는지 점검하세요. 아키텍처가 맞지 않으면 올바른 패키지를 다시 다운로드하고, 아키텍처 검사를 무시하는 옵션은 사용하지 마세요.

2. 설치 결과 확인

   apt가 오류 없이 완료됐는지 확인하세요. 사용할 수 없는 의존성이 표시되면 먼저 배포판 저장소와 지원 버전을 확인하세요. 다른 배포판의 시스템 라이브러리를 섞어 설치하지 마세요.

3. 앱 메뉴에서 실행

   데스크톱 앱 메뉴를 열고 v2rayN을 검색한 뒤 현재 로그인한 사용자로 실행하세요. 그래픽 창을 sudo로 실행하면 설정 파일의 소유자가 관리자 계정으로 바뀔 수 있습니다.

4. 가져오기 및 테스트

   메인 화면에서 「구독 그룹」→「구독 그룹 설정」으로 이동해 신뢰할 수 있는 출처의 링크를 추가한 다음 구독을 업데이트하세요. 빌드에 따라 버튼 이름이 조금 다를 수 있으니 현재 창에 표시되는 항목을 기준으로 진행하세요.

설치는 성공했지만 메뉴에 실행 항목이 없다면 패키지에 데스크톱 파일이 포함되어 있는지 확인하세요. 아래 명령은 package_file 변수가 남아 있는 동일한 터미널에서 실행해야 합니다. 새 터미널을 열었다면 먼저 파일 경로를 다시 입력하세요.

package_name=$(dpkg-deb -f "$package_file" Package)
dpkg-query -W "$package_name"
dpkg-query -L "$package_name" | grep -E '/applications/[^/]+\.desktop$'

rpm 설치: Fedora와 openSUSE 명령 구분

rpm은 패키지 형식일 뿐, 같은 형식을 쓰는 모든 배포판의 실행 환경이 같다는 뜻은 아닙니다. 먼저 패키지 정보를 확인한 뒤 배포판에 맞는 설치 명령을 선택하세요. dnf와 zypper를 함께 실행하지 말고, 의존성 검사를 건너뛰어 런타임 라이브러리 누락을 숨기지도 마세요.

read -r -p 'rpm 파일의 절대 경로를 입력하세요: ' package_file
rpm -qp --queryformat '%{NAME}\n%{VERSION}-%{RELEASE}\n%{ARCH}\n' "$package_file"

# Fedora에서 이 명령 실행
sudo dnf install "$package_file"

# openSUSE에서는 이 명령으로 바꿔 실행
sudo zypper install "$package_file"

• 의존성을 해결할 수 없음: 누락된 패키지 이름을 기록하고 현재 배포판 저장소에서 제공하는지 확인하세요. 시스템 그래픽 라이브러리나 암호화 라이브러리를 임의로 바꾸지 마세요.
• 출처 신뢰 안내: 패키지 관리자의 안내를 읽고 파일 출처를 확인하세요. 전체 검증을 끄는 방법을 일반적인 설치 절차로 사용하지 마세요.
• 설치 직후 종료됨: 앱 데스크톱 파일에서 실제 실행 명령을 확인한 뒤 터미널에서 실행해 오류를 확인하세요. 기존 옵션은 유지하고 실행 파일이 특정 고정 경로에 있다고 가정하지 마세요.

설치가 끝나면 패키지에 포함된 앱 실행 항목을 확인할 수 있습니다. 여기서 확인하는 것은 설치된 파일 목록입니다. 설치 작업이 실패했다면 먼저 문제를 해결하고 자동 시작 설정은 나중에 진행하세요.

package_name=$(rpm -qp --queryformat '%{NAME}' "$package_file")
rpm -q "$package_name"
rpm -ql "$package_name" | grep -E '/applications/[^/]+\.desktop$'

첫 연결: 리스닝 확인 후 시스템 프록시 설정

구독 가져오기, 코어 실행, 앱의 프록시 사용은 서로 별개의 단계입니다. 먼저 사용할 권한이 있는 서버를 선택한 뒤 로그에서 코어가 정상적으로 시작됐는지 확인하세요. 「설정」→「매개변수 설정」에서 로컬 리스닝 주소와 포트, 프로토콜 유형을 찾으세요. 설정 항목의 분류는 클라이언트 버전에 따라 달라질 수 있으므로 실제 설정과 리스닝 상태를 기준으로 판단하세요.

위 포트는 설정 설명을 위한 예시이며 모든 버전의 기본값을 뜻하지 않습니다. 하나의 혼합 리스닝 포트를 쓰는 설정도 있고 HTTP와 SOCKS 포트를 따로 제공하는 설정도 있습니다. 실제로 해당 포트에서 리스닝 중일 때만 입력하세요. 로컬 데스크톱에서 사용할 때는 보통 루프백 주소를 유지하면 되며 모든 네트워크 인터페이스에 개방할 필요가 없습니다.

# 실제 포트에 맞게 조건을 조정
ss -lntp | grep -E ':(10808|10809)[[:space:]]'

# 해당 프록시 프로토콜과 포트를 확인한 뒤에만 테스트
curl --proxy http://127.0.0.1:10809 --head --max-time 15 https://example.com/
curl --proxy socks5h://127.0.0.1:10808 --head --max-time 15 https://example.com/

socks5h는 대상 도메인의 이름 해석을 프록시 쪽에서 처리한다는 뜻입니다. HTTP 응답을 받으면 이번 요청이 대상에 도달했다는 근거가 되지만, 모든 라우팅 규칙과 도메인 이름 해석 경로가 올바르다는 뜻은 아닙니다. 연결이 거부되면 리스닝 상태와 코어 로그부터 확인하세요. 로컬 연결은 성립했지만 요청 시간이 초과되면 서버, 전송 매개변수, 네트워크를 점검하세요.

GNOME·KDE 시스템 프록시 적용 범위

데스크톱 시스템 프록시는 앱이 읽어 사용하는 설정이지, 모든 네트워크 트래픽을 투명하게 가로채는 기능은 아닙니다. 브라우저, 데스크톱 구성 요소, 터미널 프로그램마다 프록시를 읽는 방식이 다를 수 있습니다. 먼저 프록시를 지원하는 앱 하나로 테스트한 뒤 다른 앱으로 범위를 넓히세요. 시스템 설정, 브라우저 설정, 환경 변수를 한꺼번에 바꾸면 문제 원인을 찾기 어려워집니다.

GNOME 수동 프록시

「설정」→「네트워크」→「네트워크 프록시」로 이동해 「수동」을 선택하세요. HTTP와 HTTPS에는 HTTP CONNECT를 처리할 수 있는 로컬 HTTP 프록시를 입력하고, SOCKS에는 SOCKS 리스닝 포트를 입력합니다. HTTPS 항목이 있다고 해서 로컬 프록시 연결에 TLS가 필요하다는 뜻은 아닙니다. 배포판에 따라 설정 위치가 다를 수 있으며 아래 명령으로 설정할 수도 있습니다.

# 원래 값을 기록해 복구할 수 있도록 합니다. 현재 데스크톱 사용자 터미널에서 실행
gsettings get org.gnome.system.proxy mode
gsettings list-recursively org.gnome.system.proxy.http
gsettings list-recursively org.gnome.system.proxy.https
gsettings list-recursively org.gnome.system.proxy.socks

# 예시 포트와 실제 리스닝 포트가 일치할 때만 실행
gsettings set org.gnome.system.proxy.http host '127.0.0.1'
gsettings set org.gnome.system.proxy.http port 10809
gsettings set org.gnome.system.proxy.https host '127.0.0.1'
gsettings set org.gnome.system.proxy.https port 10809
gsettings set org.gnome.system.proxy.socks host '127.0.0.1'
gsettings set org.gnome.system.proxy.socks port 10808
gsettings set org.gnome.system.proxy mode 'manual'

# 수동 시스템 프록시 사용 중지
gsettings set org.gnome.system.proxy mode 'none'

KDE Plasma 수동 프록시

「시스템 설정」을 열고 「프록시」를 검색한 뒤 프록시 설정에서 「수동으로 지정한 프록시 설정 사용」을 선택하세요. 실제 HTTP, HTTPS, SOCKS 주소를 입력하고 적용합니다. KDE 설정은 주로 해당 데스크톱 프록시 방식을 따르는 소프트웨어에서 사용됩니다. 일부 브라우저는 별도의 설정이 필요하고 터미널 도구도 보통 따로 설정해야 합니다. 클라이언트를 종료하기 전에 프록시를 사용하지 않도록 되돌려 앱이 이미 닫힌 로컬 포트에 계속 연결하지 않게 하세요.

• 브라우저에서 시스템 프록시를 선택해도 적용되지 않는다면 확장 프로그램이나 별도의 프록시 설정이 덮어쓰고 있는지 확인하세요.
• curl에서 프록시를 명시한 테스트는 성공하지만 일반 요청이 실패한다면 클라이언트를 다시 설치하기보다 앱의 프록시 설정 출처부터 확인하세요.
• 클라이언트와 수동 스크립트가 시스템 프록시 설정을 반복해서 바꾸지 않도록 하세요. 한 가지 관리 방법을 선택한 다음 확인하세요.

자동 시작 설정: 그래픽 로그인 후 실행, 시스템 서비스 아님

데스크톱 클라이언트의 자동 시작은 보통 사용자가 그래픽 데스크톱에 로그인한 뒤 실행된다는 뜻입니다. 로그인 전부터 프록시 서비스를 제공한다는 의미는 아닙니다. 데스크톱 세션의 XDG Autostart 방식을 사용하고 설치 패키지가 제공한 데스크톱 실행 항목을 활용하세요. 실행 파일 경로와 옵션은 그대로 유지하고, 경험에 의존해 Exec 행을 임의로 작성하지 마세요.

1. 중복 실행 항목 먼저 끄기

   클라이언트의 「설정」→「매개변수 설정」에서 자동 시작 옵션이 있는지 확인하세요. 아래의 수동 설정을 사용할 예정이라면 두 경로에서 동시에 실행되지 않도록 해당 옵션을 먼저 끄세요.

2. 데스크톱 파일 위치 찾기

   앞서 사용한 패키지 파일 목록 명령으로 실제 .desktop 경로를 찾으세요. 먼저 앱 메뉴에서 정상 실행되는지 확인한 뒤 해당 경로를 아래 복사 명령에 입력하세요.

3. 사용자 실행 항목 복사

   데스크톱 파일을 현재 사용자의 autostart 디렉터리에 복사하고 시스템 전체 실행 항목은 수정하지 마세요. 아래 작업에는 sudo가 필요하지 않습니다.

4. 다시 로그인해 확인

   클라이언트를 종료하고 데스크톱에서 로그아웃한 뒤 다시 로그인해 창 또는 백그라운드 프로세스, 포트 리스닝, 시스템 프록시를 확인하세요. 트레이 아이콘만 보고 코어가 실행 중이라고 판단하지 마세요.

read -r -p '설치된 .desktop 파일의 절대 경로를 입력하세요: ' desktop_file
grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"

autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$autostart_dir"
cp -- "$desktop_file" "$autostart_dir/v2rayn-login.desktop"

복사 전후에 Type=Application과 Exec=을 확인하세요. Hidden=true가 있거나 OnlyShowIn, NotShowIn에서 현재 데스크톱이 제외되어 있다면 텍스트 편집기로 사용자 디렉터리에 복사한 파일을 수정하세요. 시스템 원본 파일은 변경하지 마세요. GNOME에서는 트레이 아이콘이 표시되지 않을 수 있으므로 프로세스, 로그, 리스닝 상태를 기준으로 판단하세요.

KDE에서는 「시스템 설정」에서 「자동 시작」을 검색한 다음 「프로그램 추가」를 선택해 v2rayN을 등록할 수도 있습니다. 이 방법과 수동 복사 중 하나만 사용하세요. 그래픽 프로그램을 시스템 서비스에 직접 등록하지 마세요. 서비스에는 완전한 데스크톱 세션 환경이 없는 경우가 많아 창이나 사용자 설정 경로에 문제가 생길 수 있습니다.

# 이 글에서 직접 만든 로그인 자동 시작 항목 제거
autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
rm -f -- "$autostart_dir/v2rayn-login.desktop"

자주 묻는 문제: 업그레이드, 실행 실패, 프록시 설정 잔류

정해진 순서대로 설치를 확인하세요. 패키지 관리자가 설치 완료를 표시하는지 확인하고, 앱 메뉴에서 실행한 뒤, 구독과 코어 로그를 점검하고, 로컬 프록시 테스트와 대상 앱의 프록시 사용을 확인한 다음, 마지막으로 로그아웃해 자동 시작을 검증합니다. 업그레이드 전에는 클라이언트에서 제공하는 백업 기능이나 실제 데이터 디렉터리를 이용해 설정을 저장하세요. 구독 링크와 설정에는 접속 인증 정보가 포함될 수 있으므로 문제 해결 화면을 공개하지 마세요.