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

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

Linux에서는 v2rayN의 Avalonia 데스크톱 버전을 사용해야 합니다. WPF 버전은 Windows용입니다. deb와 rpm은 배포판별 패키지 형식이며 프록시 프로토콜이나 코어 종류를 뜻하지 않습니다. 먼저 터미널에서 아래 명령을 실행해 시스템 정보를 확인하세요. 데스크톱 환경에 따라 시스템 프록시 설정과 자동 실행 방식도 달라집니다.

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

uname -m의 결과가 x86_64이면 일반적으로 x64, aarch64이면 arm64 아키텍처입니다. Debian 패키지의 아키텍처는 amd64로 표시될 수 있습니다. 표기만 다를 뿐 같은 CPU 아키텍처 계열입니다. 다운로드 페이지에서 현재 제공되는 Linux 파일을 확인하세요. 이 설치 절차는 이미 내려받은 해당 형식의 패키지를 대상으로 하며, 모든 버전이 두 형식을 모두 제공한다고 보장하지 않습니다.

Debian·Ubuntu: apt로 deb 패키지 설치

이번에 사용할 설치 패키지를 별도 디렉터리에 모아 둔 다음, 해당 디렉터리에서 터미널을 여는 것이 좋습니다. 먼저 현재 디렉터리에 있는 deb 파일을 확인하고, 아래와 같이 실제 파일 경로를 입력하세요. 터미널에 파일을 끌어다 놓아 경로를 입력할 수도 있습니다. 변수를 사용하면 파일명에 공백이 있어도 처리할 수 있습니다. 이전 버전 여러 개를 한꺼번에 선택하지 마세요.

find "$PWD" -maxdepth 1 -type f -name '*.deb' -print
read -r -p 'deb 파일의 전체 경로를 입력하세요: ' pkg
if [ -f "$pkg" ]; then
  dpkg-deb -f "$pkg" Package Version Architecture
  dpkg --print-architecture
else
  printf '파일이 없습니다. 다시 선택하세요.\n'
fi

패키지 아키텍처가 시스템과 일치하는지 확인한 뒤 설치하세요. apt install은 로컬 패키지에 선언된 의존성을 처리하므로 단순히 압축을 푸는 것보다 일반적인 데스크톱 사용자에게 적합합니다. 처음 설치할 때는 관리자 권한이 필요하지만, 클라이언트를 사용할 때까지 관리자 계정으로 실행할 필요는 없습니다.

if [ -f "$pkg" ]; then
  pkg="$(realpath "$pkg")"
  sudo apt update
  sudo apt install "$pkg"
fi

• 의존성 다운로드에 실패하면 먼저 패키지 저장소에 접근할 수 있는지 확인한 다음 다시 설치하세요. 의존성을 무시하는 옵션으로 설치를 강행하지 마세요.
• 아키텍처가 맞지 않는다는 오류가 나오면 다운로드 페이지에서 올바른 파일을 다시 선택하세요. 강제 설치 옵션으로 검사를 건너뛰지 마세요.
• 설치가 끝나면 데스크톱 앱 목록에서 v2rayN을 검색하세요. 실행 항목이 보이지 않는다면 dpkg -L "$(dpkg-deb -f "$pkg" Package)"로 패키지가 실제 설치한 파일을 확인할 수 있습니다.
• 같은 패키지를 업데이트할 때는 로컬 패키지 설치 명령을 다시 실행하면 됩니다. 프로그램 파일을 덮어써도 구독과 라우팅 설정은 백업되지 않으므로, 업데이트 전에 중요한 설정을 따로 저장하세요.

Fedora: dnf로 rpm 패키지 설치

Fedora에서는 dnf로 로컬 rpm 패키지를 설치합니다. 설치 전에 패키지 이름, 버전, 아키텍처를 확인하세요. 앱의 표시 이름이 패키지 관리자가 사용하는 정확한 이름과 같다고 단정할 수 없습니다. 아래 명령은 실제 파일을 읽어 패키지 메타데이터에 포함된 이름을 사용하므로 설명에 패키지명을 고정하지 않습니다.

find "$PWD" -maxdepth 1 -type f -name '*.rpm' -print
read -r -p 'rpm 파일의 전체 경로를 입력하세요: ' pkg
if [ -f "$pkg" ]; then
  pkg="$(realpath "$pkg")"
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$pkg"
  uname -m
  sudo dnf install "$pkg"
else
  printf '파일이 없습니다. 다시 선택하세요.\n'
fi

설치가 끝난 뒤 rpm -ql "$(rpm -qp --queryformat '%{NAME}' "$pkg")"를 실행하면 프로그램과 데스크톱 실행 항목의 위치를 확인할 수 있습니다. 앱 목록에서 v2rayN을 찾았지만 실행 직후 종료된다면, 데스크톱 실행 항목에 기록된 프로그램 경로를 터미널에서 실행해 누락된 라이브러리나 코어 실행 오류를 확인하세요. 아키텍처가 다른 패키지를 번갈아 설치할 필요는 없습니다.

첫 연결 설정: 구독, 리스닝 포트, 시스템 프록시

설치가 끝났다고 해서 원격 서버에 연결할 준비까지 완료된 것은 아닙니다. v2rayN은 노드와 설정을 관리하고, 실제 연결은 선택한 코어가 담당합니다. VMess와 VLESS는 프로토콜 이름입니다. 구독 URL로 노드 목록을 가져오며, 이는 로컬 HTTP 또는 SOCKS 프록시 주소와 별개입니다.

1. 구독 추가

   ‘구독 그룹’ → ‘구독 그룹 설정’을 열어 새 그룹을 추가하고 신뢰할 수 있는 구독 URL을 입력하세요. 버전에 따라 버튼 위치가 다를 수 있으므로 현재 화면에서 구독 그룹 관리 메뉴를 찾으세요.

2. 목록 업데이트

   ‘구독 그룹’ 메뉴에서 업데이트를 실행하세요. 첫 연결을 아직 설정하지 않았다면 프록시를 거치지 않는 업데이트 방식을 선택하세요. 주소에 직접 연결할 수 없다면 먼저 사용할 수 있는 연결을 준비해야 합니다. 같은 버튼을 반복해서 눌러도 해결되지 않습니다.

3. 노드 선택

   노드 목록에서 사용할 노드를 선택해 활성 서버로 지정하세요. 프로토콜과 전송 설정이 서버 요구사항과 일치하는지 확인한 뒤 로그에서 코어가 정상적으로 시작했는지 확인합니다.

4. 포트 확인

   ‘설정’ → ‘매개변수 설정’으로 이동해 로컬 리스닝 주소와 포트를 확인하세요. 이 글에서는 혼합 프록시 주소 127.0.0.1:10808을 예로 사용합니다. 화면에 다른 포트가 표시되면 뒤에 나오는 테스트에서 실제 값을 사용하세요.

5. 프록시 설정

   먼저 명시적으로 프록시를 지정해 연결을 테스트한 다음, 클라이언트의 ‘시스템 프록시’ → ‘시스템 프록시 자동 설정’을 시도하세요. Linux에서는 데스크톱 환경과 각 앱의 설정 지원 여부에 따라 적용 범위가 달라집니다.

이 값들은 설정 예시일 뿐 성능 측정 결과나 모든 버전의 기본값이 아닙니다. 프록시가 HTTP와 SOCKS를 모두 지원하는지 확인한 뒤 두 방식으로 테스트하세요. socks5h를 사용하면 curl이 대상 도메인 처리를 프록시에 맡기므로, 로컬 DNS 문제와 프록시 연결 문제를 구분하는 데 도움이 됩니다.

ss -ltnp 'sport = :10808'
curl --noproxy "" --proxy http://127.0.0.1:10808 \
  --max-time 15 --head https://example.com
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 \
  --max-time 15 --head https://example.com

데스크톱 로그인 시 자동 실행: 설치된 desktop 항목 활용

일반적으로 말하는 ‘부팅 시 자동 실행’은 여기서 사용자가 그래픽 데스크톱에 로그인한 뒤 프로그램을 실행하는 것을 뜻합니다. 시스템 부팅 때 백그라운드 서비스로 실행하는 것과는 다르며, 로그인 화면에서 프록시를 제공하지도 않습니다. 먼저 프로그램을 직접 실행해 정상 작동을 확인한 다음 자동 실행 항목을 만들면, 로그인할 때마다 같은 오류가 반복되는 일을 막을 수 있습니다.

설치 패키지가 제공하는 desktop 파일을 우선 사용하세요. 보통 올바른 Exec 경로와 필요한 인수가 이미 들어 있어 실행 파일 위치를 추측하는 것보다 안전합니다. 아래 명령으로 표준 앱 디렉터리에서 후보 항목을 찾으세요. 파일이 여러 개라면 하나씩 확인해 이번 설치에 해당하는 항목만 선택합니다.

find /usr/share/applications "$HOME/.local/share/applications" \
  -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print 2>/dev/null

read -r -p '확인한 desktop 파일의 전체 경로를 입력하세요: ' desktop_file
if [ -f "$desktop_file" ]; then
  grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"
fi

Type=Application인지, Exec이 설치된 프로그램을 가리키는지, 현재 데스크톱 실행을 막는 제한이 없는지 확인한 뒤 아래 명령으로 복사하세요. 대상은 현재 사용자의 XDG 자동 실행 디렉터리이므로 sudo가 필요하지 않습니다. 기존 파일에 Hidden=true가 있으면 비활성화된 이유를 먼저 확인하고 그대로 복사하지 마세요.

if [ -f "$desktop_file" ]; then
  autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
  mkdir -p "$autostart_dir"
  cp -- "$desktop_file" "$autostart_dir/v2rayN.desktop"
fi

• 로그아웃한 뒤 다시 로그인해 v2rayN이 실행되는지, 코어가 작동하는지, 로컬 포트가 리스닝 중인지 확인하세요.
• 클라이언트 내장 자동 실행 기능을 켰다면 같은 역할의 자동 실행 항목을 추가로 남기지 마세요. 프로그램이 중복 실행될 수 있습니다.
• 로그인 후 네트워크 연결이 아직 준비되지 않았다면 클라이언트 창이 열려도 구독 업데이트나 노드 연결이 바로 성공하지 않을 수 있습니다. 네트워크가 연결된 뒤 로그를 확인하세요.
• 이 글에서 만든 자동 실행 항목을 비활성화하려면 rm -- "${XDG_CONFIG_HOME:-$HOME/.config}/autostart/v2rayN.desktop"을 실행하세요. 이 명령은 자동 실행 파일만 삭제합니다.

권한과 시스템 프록시: 증상별 점검

로컬 프록시, 데스크톱 시스템 프록시, TUN은 서로 다른 계층입니다. 일반 앱은 HTTP나 SOCKS로 로컬 포트에 연결할 수 있습니다. 데스크톱 프록시 설정은 해당 설정을 읽는 앱에만 프록시 정보를 제공합니다. TUN은 가상 네트워크 장치와 라우팅을 사용하므로 추가 권한이 필요합니다. 먼저 로컬 프록시를 확인한 뒤 적용 범위를 넓히면 문제를 더 쉽게 찾을 수 있습니다.

GNOME 데스크톱에서는 ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’에서 수동 프록시를 확인할 수 있습니다. HTTP와 HTTPS 프록시는 HTTP를 지원하는 로컬 프록시 주소를, SOCKS는 SOCKS를 지원하는 주소를 사용하세요. 여기서 HTTPS 프록시 항목은 보통 로컬 HTTP 프록시의 호스트와 포트를 입력하는 곳이며, 로컬 프록시가 별도의 TLS를 제공해야 한다는 뜻은 아닙니다. 다른 데스크톱 환경에서는 해당 환경의 설정 메뉴를 이용하고 GNOME 전용 명령을 그대로 따라 하지 마세요.

# 현재 터미널과 여기서 실행한 하위 프로세스에만 적용
export http_proxy=http://127.0.0.1:10808
export https_proxy=http://127.0.0.1:10808
export all_proxy=socks5h://127.0.0.1:10808

# 테스트가 끝나면 이번에 설정한 값을 삭제
unset http_proxy https_proxy all_proxy