v2rayN Linux 데스크톱 설치: deb·rpm 패키지 설치와 로그인 시 자동 실행 설정

1. 배포판, 프로세서 아키텍처, 설치 방식 확인

v2rayN은 그래픽 데스크톱 클라이언트이며, 실제 연결 처리는 V2Ray, Xray 등의 코어가 담당합니다. 클라이언트 설치, 코어 실행, 애플리케이션의 프록시 사용은 서로 다른 단계입니다. 이 글에서는 설치와 데스크톱 세션을 다루며, Android 클라이언트인 v2rayNG나 v2flyNG의 사용 방법을 Linux에 적용하지 않습니다.

터미널을 열고 배포판 정보와 시스템 아키텍처를 확인합니다. Debian과 Ubuntu에서는 보통 deb를, Fedora에서는 rpm을 선택합니다. rpm을 사용하는 다른 배포판이라도 패키지의 의존성을 현재 배포판에서 충족할 수 있는지 먼저 확인해야 합니다. 확장자만 보고 호환된다고 판단해서는 안 됩니다.

cat /etc/os-release
uname -m

클라이언트 다운로드 페이지에서 Linux와 해당 아키텍처를 선택합니다. 아래 설치 명령을 사용하려면 파일 관리자에서 다운로드한 파일의 이름을 v2rayn-linux.deb 또는 v2rayn-linux.rpm으로 바꾼 다음, 해당 파일이 있는 폴더에서 터미널을 엽니다. 파일 이름 변경은 명령을 간단히 하기 위한 것으로, 패키지 내부의 버전·패키지명·아키텍처에는 영향을 주지 않습니다.

2. deb·rpm 설치 및 오류에 따른 의존성 해결

로컬 패키지는 하위 수준 설치 명령만 실행하기보다 apt 또는 dnf로 설치하는 것이 좋습니다. 패키지 관리자는 활성화된 저장소에서 의존성을 해결할 수 있습니다. 현재 저장소를 사용할 수 없으면 설치가 실패하므로, 이때는 의존성 확인을 건너뛰지 말고 네트워크나 저장소 문제부터 해결하세요.

Debian / Ubuntu: apt로 로컬 deb 설치

# deb 파일이 있는 디렉터리에서 실행
dpkg-deb -f ./v2rayn-linux.deb Package Version Architecture
sudo apt update
sudo apt install ./v2rayn-linux.deb

./는 현재 디렉터리의 파일을 뜻합니다. 이를 생략하면 apt가 입력값을 저장소의 패키지명으로 처리할 수 있습니다. 이전에 dpkg -i로 설치한 뒤 의존성 설정이 완료되지 않았다면 아래 복구 명령을 실행할 수 있습니다. apt가 제안하는 설치·삭제 항목이 예상과 일치하는지 확인한 뒤 진행하고, 이어서 로컬 패키지 설치 명령을 다시 실행하세요.

sudo apt --fix-broken install

Fedora: dnf로 로컬 rpm 설치

# rpm 파일이 있는 디렉터리에서 실행
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' ./v2rayn-linux.rpm
sudo dnf install ./v2rayn-linux.rpm

• 아키텍처 오류가 표시되면: uname -m 결과를 다시 확인하고, 다른 아키텍처 패키지를 강제로 설치하지 마세요.
• 의존성 누락이 표시되면: 패키지명이나 라이브러리명을 빠짐없이 기록하고, 저장소가 활성화되어 있으며 현재 시스템 버전을 지원하는지 확인하세요.
• 파일 충돌이 표시되면: 기존 파일이 설치된 경로와 출처를 먼저 확인하고, 시스템 디렉터리의 파일을 바로 덮어쓰지 마세요.
• 라이브러리 버전이 낮다고 표시되면: 클라이언트가 지원하는 시스템 요구 사항부터 확인하세요. 다른 배포판의 기본 라이브러리를 시스템 디렉터리에 복사하지 마세요.

3. 첫 실행: 구독, 리스닝 포트, 시스템 프록시 확인

설치가 끝나면 데스크톱 애플리케이션 메뉴에서 v2rayN을 검색합니다. 먼저 메인 창이 열리는지 확인한 후 연결 설정을 가져옵니다. 메뉴 이름은 버전에 따라 달라질 수 있습니다. 아래에서는 데스크톱 버전에서 흔히 사용하는 ‘구독 그룹’, ‘설정’, ‘매개변수 설정’이라는 이름으로 설명합니다. 현재 버전에서 메뉴명이 다르면 기능에 맞춰 찾고, Android 버전의 메뉴 위치를 찾지 마세요.

1. 클라이언트 실행

   애플리케이션 메뉴에서 v2rayN을 실행합니다. 창이 나타나지 않으면 먼저 터미널에서 데스크톱 실행기의 Exec=에 지정된 프로그램을 실행해 누락된 라이브러리나 디스플레이 세션 오류를 확인합니다.

2. 구독 가져오기

   ‘구독 그룹’ → ‘구독 그룹 설정’으로 이동해 그룹을 추가하고, 메모와 구독 주소를 입력한 뒤 저장합니다. 그런 다음 ‘구독 그룹’ 메뉴에서 업데이트를 실행합니다. 공유 링크는 메인 화면의 클립보드 가져오기 기능을 사용하세요.

3. 서버 선택

   목록에서 사용할 수 있는 설정을 선택해 활성 서버로 지정합니다. VMess, VLESS 등의 연결 매개변수는 구독이나 공유 링크에 포함되어 있습니다. 문제 해결을 위해 전송 방식, TLS, 서버 주소를 임의로 변경하지 마세요.

4. 리스닝 상태 확인

   ‘설정’ → ‘매개변수 설정’에서 기본 설정의 로컬 리스닝 포트를 확인하고, 로그에서 코어 실행 실패나 포트 충돌이 있는지 살펴봅니다. 설정을 저장한 다음 클라이언트 안내에 따라 관련 서비스를 다시 시작하세요.

5. 시스템 프록시 설정

   메인 화면이나 트레이의 ‘시스템 프록시’ 메뉴에서 ‘시스템 프록시 자동 설정’을 선택합니다. 그런 다음 데스크톱 환경의 네트워크 프록시 설정을 확인하세요. 애플리케이션이 이 설정을 따르는지는 별도로 검증해야 합니다.

아래 두 포트는 설명을 위한 일반적인 설정 예시일 뿐이며, 모든 버전의 기본값을 보장하지 않습니다. 실제 로컬 설정을 기준으로 확인하세요. 클라이언트가 단일 혼합 포트를 사용한다면 해당 인바운드에서 지원하는 프로토콜을 테스트하면 됩니다. 별도의 두 번째 리스너를 만들 필요는 없습니다.

# 해당 TCP 리스너가 있는지 확인합니다. 포트는 로컬 설정에 맞게 조정하세요
ss -lntp | grep -E ':(10808|10809)\b'

# 해당 프로토콜을 지원하는 리스너인지 확인한 경우에만 테스트하세요. curl이 설치되어 있어야 합니다
curl --connect-timeout 10 --max-time 20 \
  --proxy socks5h://127.0.0.1:10808 https://example.com/

curl --connect-timeout 10 --max-time 20 \
  --proxy http://127.0.0.1:10809 https://example.com/

프록시를 명시한 curl 요청으로 ‘프록시 서비스가 작동하지 않는 경우’와 ‘애플리케이션이 프록시를 사용하지 않는 경우’를 구분할 수 있습니다. socks5h는 대상 도메인 조회를 프록시 쪽에 맡깁니다. 요청에 성공해도 모든 애플리케이션이 프록시에 연결되었다는 뜻은 아닙니다. 시스템 프록시 설정과 라우팅 모드는 서로 다릅니다. ‘전역’ 또는 ‘중국 본토 우회’ 규칙은 코어에 전달된 요청의 경로를 정할 뿐, 시스템 프록시를 무시하는 애플리케이션을 자동으로 연결하지는 않습니다.

4. 트레이 아이콘이 보이지 않을 때: 데스크톱 환경부터 확인

Linux에서 트레이 아이콘이 표시되는지는 데스크톱 환경이 제공하는 상태 아이콘 기능에 따라 달라집니다. 메인 창과 코어는 정상인데 트레이 아이콘만 없다면 클라이언트를 다시 설치하기보다 데스크톱 통합부터 확인하세요. 특히 GNOME은 애플리케이션 표시기 지원이 기본적으로 활성화되어 있지 않을 수 있습니다.

• GNOME: 시스템의 확장 관리 도구를 열어 AppIndicator / KStatusNotifierItem 지원 확장이 있는지 확인하고 활성화하세요. Debian·Ubuntu에서는 먼저 apt search appindicator로 현재 저장소에서 제공하는 확장을 검색할 수 있습니다. Fedora에서는 dnf search appindicator를 사용하세요. 패키지명과 사용 가능한 버전은 현재 배포판을 기준으로 확인해야 합니다.
• KDE Plasma: 시스템 트레이를 마우스 오른쪽 버튼으로 클릭해 설정을 열고, ‘항목’에서 애플리케이션 상태가 숨김으로 지정되어 있는지 확인합니다. 접힌 영역도 살펴보세요.
• Xfce: 패널에 상태 알림을 지원하는 트레이 플러그인이 추가되어 있는지 확인하세요. 아이콘을 표시할 패널이 없다면 클라이언트 설정만으로 트레이를 만들 수 없습니다.
• 원격 또는 최소 구성 데스크톱: 창 관리자만 실행 중인 것이 아니라 현재 세션에서 패널과 트레이 구성 요소도 실제로 작동하는지 확인하세요.

데스크톱 확장을 설치하거나 활성화한 뒤에는 작업을 저장하고 로그아웃했다가 다시 로그인하는 편이 클라이언트 프로세스를 반복해서 종료하는 것보다 문제를 파악하는 데 도움이 됩니다. Wayland 세션에서는 다른 세션의 데스크톱 재시작 단축 동작을 그대로 따라 하지 마세요. 메인 창도 열리지 않는다면 터미널에서 실행 오류를 확인하세요. 트레이 확장으로 누락된 런타임 라이브러리를 해결할 수는 없습니다.

5. 데스크톱 자동 시작 항목으로 로그인 후 실행

그래픽 클라이언트는 사용자 데스크톱 세션과 함께 실행하는 것이 좋습니다. XDG 자동 시작 디렉터리인 ~/.config/autostart/가 이 용도에 적합합니다. 로그인 화면이 나타나기 전에 실행되는 것은 아니며, /etc/rc.local을 수정하거나 root 권한의 예약 작업을 만들 필요도 없습니다. 먼저 수동 실행이 정상적으로 되는지 확인한 뒤 자동 시작을 추가하면 문제 범위를 좁히기 쉽습니다.

패키지가 설치한 데스크톱 실행기 찾기

원래 패키지의 파일 목록을 조회하면 배포자가 설정한 실행 경로와 인수, 아이콘을 그대로 유지할 수 있습니다. 아래 명령은 현재 시스템의 패키지 형식에 맞는 한 가지 명령만 실행하세요. 패키지 파일을 옮겼다면 먼저 현재 파일이 있는 디렉터리로 이동합니다.

# Debian / Ubuntu
pkg_name=$(dpkg-deb -f ./v2rayn-linux.deb Package)
dpkg -L "$pkg_name" | grep -E '/applications/.*\.desktop$'

# Fedora
pkg_name=$(rpm -qp --queryformat '%{NAME}' ./v2rayn-linux.rpm)
rpm -ql "$pkg_name" | grep -E '/applications/.*\.desktop$'

출력에서 메인 화면을 실행하는 .desktop 파일을 선택합니다. 패키지에 실행기가 여러 개 있으면 먼저 Name=과 Exec= 내용을 확인하세요. 제거 항목이나 보조 도구를 복사하면 안 됩니다. 그런 다음 Bash 터미널에서 아래 명령을 실행하고, 안내가 나오면 앞 단계에서 확인한 전체 경로를 따옴표 없이 붙여 넣습니다.

read -r -p "메인 화면 .desktop 파일의 전체 경로를 붙여 넣으세요: " desktop_file

if [ -f "$desktop_file" ]; then
  mkdir -p "$HOME/.config/autostart"
  install -m 644 "$desktop_file" \
    "$HOME/.config/autostart/v2rayn.desktop"
  sed -i '/^Hidden=/d; /^X-GNOME-Autostart-enabled=/d' \
    "$HOME/.config/autostart/v2rayn.desktop"
  grep -E '^(Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' \
    "$HOME/.config/autostart/v2rayn.desktop"
else
  printf '%s\n' "파일이 없습니다. 자동 시작 항목을 만들지 않았습니다."
fi

이 작업은 기존 실행 명령을 유지하면서 자동 시작을 막을 수 있는 두 가지 옵션을 제거합니다. OnlyShowIn= 또는 NotShowIn=이 남아 있다면 현재 데스크톱 환경을 제한하는 설정인지 확인하세요. Exec=를 프로그램 파일명으로 바꾸어 경로를 추측하지 마세요. 여기에 ~, 파이프 또는 &를 넣어도 안 됩니다. 데스크톱 실행기는 일반 셸 스크립트처럼 해석되지 않습니다.

자동 시작 테스트, 비활성화 및 업그레이드 후 확인

1. 클라이언트에서 완전히 종료한 뒤 창이나 중복 실행 인스턴스가 남아 있지 않은지 확인합니다.
2. 작업을 저장하고 로그아웃한 다음 다시 로그인해 v2rayN이 실행되는지, 로컬 리스닝이 복구되는지 확인합니다.
3. 시스템 프록시 설정이 예상한 상태인지 확인하세요. 프로그램이 자동으로 시작되더라도 서버가 자동으로 선택되거나 모든 프록시 상태가 복구되는 것은 아닙니다.
4. 자동 시작을 비활성화하려면 아래 삭제 명령을 실행하세요. 사용자 자동 시작 복사본만 삭제되며 클라이언트는 제거되지 않습니다.

rm -f "$HOME/.config/autostart/v2rayn.desktop"

클라이언트에 자체 자동 시작 옵션이 있다면 내장 옵션과 수동으로 만든 항목 중 하나만 사용해 중복 실행을 방지하세요. 업그레이드 후 설치 경로나 실행 인수가 바뀌면 새 패키지의 실행기를 다시 복사해야 합니다. 자동 시작 디렉터리에 있는 이전 복사본은 시스템 디렉터리의 변경 사항을 자동으로 반영하지 않습니다.

6. 설치 및 자동 시작 관련 자주 묻는 질문

안정적으로 설치하려면 패키지 설치 성공, 일반 사용자로 수동 실행 성공, 프록시 연결 확인, 로그인 시 자동 시작 확인 순서로 진행하세요. 각 단계가 끝난 뒤 다음 단계로 넘어가면 의존성 문제와 데스크톱 트레이 문제, 원격 연결 문제를 구분하기 쉽습니다. 초기 설정 방법은 입문 가이드에서, 프로토콜 항목과 라우팅 개념은 프로토콜 안내서에서 확인할 수 있습니다.