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

이 글의 핵심 내용

Linux 데스크톱에 v2rayN을 설치할 때는 먼저 배포판과 CPU 아키텍처에 맞는 패키지를 고르고, 패키지 관리자로 의존성을 처리하세요. 일반 사용자 계정으로 처음 실행해 로컬 프록시를 확인한 뒤 로그인 시 자동 시작을 설정하면 됩니다. 이 글은 데스크톱 실행 항목과 백그라운드 서비스를 구분해 설명하며, Debian, Ubuntu, Fedora 또는 openSUSE에서 데스크톱 클라이언트를 계속 사용할 때 참고할 수 있습니다.

설치 전 확인: 배포판, 아키텍처, 실행 방식

v2rayN은 Avalonia 기반의 Linux 데스크톱 클라이언트입니다. 설정 관리와 코어 실행, 로그 표시는 클라이언트가 담당하며 실제 프록시 연결은 선택한 코어가 처리합니다. 데스크톱 패키지를 설치해도 부팅 시 실행되는 시스템 서비스가 자동으로 설치되는 것은 아니며, 모든 앱이 프록시를 사용하게 되는 것도 아닙니다.

먼저 아래 두 명령을 실행하세요. uname -m 결과가 x86_64이면 x64 패키지를, aarch64이면 arm64 패키지를 선택합니다. deb와 rpm 중 어느 형식을 사용할지는 배포판 정보로 확인하세요. 컴퓨터 브랜드만 보고 아키텍처를 판단하면 안 됩니다.

cat /etc/os-release
uname -m

Debian / Ubuntu

패키지 형식: deb
x64 아키텍처 이름: amd64
ARM 아키텍처 이름: arm64
설치 도구: apt

dpkg-deb로 패키지 내부의 아키텍처를 확인한 뒤, 이 시스템의 dpkg 아키텍처와 비교할 수도 있습니다.

Fedora / openSUSE

패키지 형식: rpm
x64 아키텍처 이름: x86_64
ARM 아키텍처 이름: aarch64
설치 도구: dnf / zypper

둘 다 rpm 패키지를 사용하지만, 저장소와 의존성 패키지 이름은 다를 수 있습니다.

이 글에서는 다운로드한 패키지의 이름을 v2rayN.deb 또는 v2rayN.rpm으로 바꾸고 ~/Downloads에 저장했다고 가정합니다. 이는 로컬에서 사용할 파일명일 뿐 서버의 실제 파일명과는 다릅니다. 다운로드 위치가 다르면 해당 디렉터리로 먼저 이동하세요. 설치 패키지는 클라이언트 다운로드 페이지에서 선택하고, 다른 아키텍처용 패키지를 억지로 설치하지 마세요.

Debian 및 Ubuntu: 로컬 deb 패키지를 apt로 설치

apt install ./파일명을 사용하는 것이 좋습니다. 경로 앞의 ./는 로컬 파일임을 나타내며, apt는 활성화된 저장소를 이용해 패키지에 선언된 의존성도 함께 처리합니다. dpkg -i로 설치할 수도 있지만 누락된 의존성을 자동으로 다운로드하지 않으므로 첫 설치 단계로만 사용하기에는 적합하지 않습니다.

cd ~/Downloads
dpkg --print-architecture
dpkg-deb -f ./v2rayN.deb Package Version Architecture
sudo apt update
sudo apt install ./v2rayN.deb

패키지 정보 확인

시스템 아키텍처와 패키지의 Architecture 필드를 비교하세요. Version 필드도 기록해 두면 문제를 문의할 때 클라이언트와 시스템 버전을 함께 전달할 수 있습니다.
의존성 설치 완료

apt가 제안하는 설치 계획을 확인하세요. 데스크톱 구성 요소를 대량으로 제거하겠다고 표시되면 먼저 취소하고, 강제 옵션으로 충돌을 무시하지 마세요.
처음에는 직접 실행

데스크톱 앱 메뉴에서 v2rayN을 찾아 현재 로그인한 사용자 계정으로 실행하세요. 설치 명령에는 sudo가 필요하지만 그래픽 앱을 실행할 때는 필요하지 않습니다.
오류 출력 확인

창이 열리지 않으면 데스크톱 실행 파일의 Exec 항목을 확인한 다음, 터미널에서 지정된 프로그램을 실행해 오류 메시지 전체를 보관하세요.

dpkg로 설치한 뒤 패키지가 '미설정' 상태로 남았다면 아래 복구 명령을 실행할 수 있습니다. 의존성을 설치하거나 의존성을 충족할 수 없는 패키지를 제거하겠다고 제안할 수 있으니, 계획을 확인한 뒤 진행하세요. 저장소에 연결할 수 없다면 네트워크나 저장소 설정부터 해결해야 합니다. 반복해서 압축을 풀어도 다운로드 실패는 해결되지 않습니다.

sudo apt --fix-broken install
sudo dpkg --configure -a

Fedora 및 openSUSE: 배포판 도구로 rpm 설치

rpm은 패키지 형식일 뿐, 모든 배포판과 호환된다는 의미는 아닙니다. Fedora에서는 dnf, openSUSE에서는 zypper를 사용하며, 의존성은 각 시스템의 패키지 관리자로 처리해야 합니다. 설치 전에 패키지 정보에서 아키텍처와 버전을 확인한 뒤 해당 배포판의 설치 명령 하나를 실행하세요.

cd ~/Downloads
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' ./v2rayN.rpm

# Fedora
sudo dnf install ./v2rayN.rpm

# openSUSE: 이 명령만 사용하세요. 위의 dnf 명령을 다시 실행할 필요는 없습니다
sudo zypper install ./v2rayN.rpm

메시지 유형	우선 확인할 항목	주의 사항
아키텍처 불일치	패키지의 ARCH와 uname 출력	x64 또는 arm64 패키지를 다시 선택하고 아키텍처 검사를 강제로 건너뛰지 마세요
의존성 패키지를 찾을 수 없음	배포판 버전과 활성화된 저장소	다른 배포판의 기본 런타임 라이브러리를 섞어 설치하지 마세요
런타임 라이브러리 버전이 너무 낮음	터미널에 표시된 GLIBC 또는 기타 버전 요구 사항	시스템 업그레이드를 검토하고 시스템 libc를 직접 교체하지 마세요
패키지 출처 확인 메시지	다운로드 출처와 패키지 관리자의 안내	출처를 확인한 뒤 판단하고, 보안 검사를 전역적으로 끄지 마세요

설치에는 성공했지만 실행되지 않는다면 '패키지 의존성이 충족됨'과 '그래픽 환경을 사용할 수 있음'을 구분하세요. 그래픽 세션이 없거나 디스플레이 환경 변수가 설정되지 않았거나, 원격 터미널이 데스크톱에 연결되지 않은 경우 GUI가 열리지 않을 수 있습니다. 이런 문제를 가리려고 sudo로 실행하지 마세요.

첫 실행: 로컬 리스너를 확인한 다음 시스템 프록시 설정

먼저 보유한 노드나 구독을 가져오고 사용 가능한 노드를 선택한 뒤 코어가 리스닝하는지 확인하세요. 구독에는 서버 연결 정보가 포함되어 있으므로 임의로 입력한 주소로 테스트할 수 없습니다. 프로토콜과 전송 방식의 조합은 현재 코어가 실제로 지원하는 범위를 기준으로 확인하고, 코어를 바꾼 뒤에는 로그도 다시 살펴보세요.

해당 메뉴가 있는 버전에서는 '설정' → '매개변수 설정' → '기본 설정'에서 로컬 리스닝 포트를 확인할 수 있습니다. 포트 번호와 메뉴 구성은 버전에 따라 달라질 수 있으므로 실제 화면에 표시된 값을 기준으로 하세요. 아래 예시는 HTTP 프록시가 127.0.0.1:10808에서 리스닝하는 경우를 점검하는 방법이며, 기존 설정을 덮어쓰라는 의미는 아닙니다.

10808

이 문서의 HTTP 프록시 포트 예시

127.0.0.1

로컬에서만 접속할 수 있는 리스닝 주소

15초

아래 curl 요청의 시간 초과 한도

ss -lntp 'sport = :10808'
curl --proxy http://127.0.0.1:10808 --max-time 15 -I https://example.com/

첫 번째 명령으로 TCP 리스닝을 확인하고, 두 번째 명령은 HTTP 프록시를 명시해 테스트 사이트에 접속합니다. 포트에서 SOCKS만 제공한다면 socks5h://127.0.0.1:10808로 바꾸세요. 이 경우 도메인 조회도 프록시 측에서 처리합니다. 리스너가 없으면 먼저 코어 시작 오류를 확인하세요. 이를 곧바로 회선 속도 문제로 판단해서는 안 됩니다.

프록시를 명시한 요청이 성공했다는 것은 해당 요청의 프록시 경로를 사용할 수 있다는 뜻일 뿐, 모든 앱이 프록시를 사용한다는 뜻은 아닙니다.
데스크톱 앱에서 프록시를 사용하려면 클라이언트의 '시스템 프록시' → '시스템 프록시 자동 구성'을 선택하세요. 실제 적용 범위는 데스크톱 환경과 앱에 따라 다릅니다.
명령줄 프로그램은 데스크톱 프록시 설정을 읽지 않을 수 있습니다. 프로그램 자체의 프록시 옵션이나 환경 변수를 사용하세요.
처음 설치할 때는 일반 프록시 모드부터 확인하세요. TUN 권한과 라우팅 변경은 별도로 설정해 변수를 한꺼번에 늘리지 않는 편이 좋습니다.

데스크톱 자동 시작: 사용자 로그인 시작 항목 권장

데스크톱 클라이언트에서 '부팅 시 자동 시작'은 보통 그래픽 데스크톱에 로그인한 뒤 자동으로 실행된다는 뜻입니다. XDG Autostart 사용을 권장합니다. 설치 패키지가 제공하는 desktop 파일을 재사용하면 올바른 Exec, 아이콘, 실행 옵션을 유지할 수 있습니다. 이렇게 하면 실행 파일 위치를 추측할 필요가 없고 클라이언트 전체를 root 권한으로 실행하지 않아도 됩니다.

XDG 로그인 시 자동 시작

권장

현재 사용자의 그래픽 세션에서 실행되므로 데스크톱 환경과 사용자 설정을 그대로 사용할 수 있습니다. 트레이와 창이 필요한 데스크톱 환경에 적합합니다.

적합한 경우: 개인용 Linux 데스크톱에서 로그인 후 자동 연결

systemd 서비스

서비스는 환경, 권한, 수명 주기를 별도로 설계해야 합니다. 시스템 서비스는 그래픽 세션을 자동으로 사용할 수 없으므로 데스크톱 GUI에 그대로 적용하는 방식은 적합하지 않습니다.

적합한 경우: 코어를 독립적으로 실행해야 하는 백그라운드 환경

먼저 클라이언트의 '설정' → '매개변수 설정'에 '부팅 시 자동 시작' 옵션이 있는지 확인하세요. 현재 버전에서 사용자 시작 항목을 올바르게 생성한다면 그대로 사용하면 됩니다. 로그인할 때 두 번 실행될 수 있으니 같은 항목을 다시 복사하지 마세요. 직접 설정해야 한다면 먼저 설치 패키지가 제공하는 데스크톱 파일을 찾으세요.

find /usr/share/applications -maxdepth 1 -type f -iname '*v2rayn*.desktop' -print

해당하는 파일이 하나만 확인된 경우에 아래 복사 작업을 실행하세요. 스크립트가 일치하는 파일 수를 확인하므로 여러 데스크톱 항목 중 하나를 임의로 선택하는 일을 막을 수 있습니다. 일치하는 파일이 없다면 deb 패키지는 dpkg-deb -c, rpm 패키지는 rpm -qlp로 내부 파일 목록을 확인해 데스크톱 파일의 실제 이름과 위치를 찾으세요.

bash <<'BASH'
mapfile -t entries < <(find /usr/share/applications -maxdepth 1 -type f -iname '*v2rayn*.desktop')
if [ "${#entries[@]}" -ne 1 ]; then
  printf '데스크톱 항목이 정확히 하나여야 합니다. 현재 %s개를 찾았습니다.\n' "${#entries[@]}"
  exit 1
fi
target="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
mkdir -p "$target"
cp -- "${entries[0]}" "$target/v2rayN.desktop"
chmod 644 "$target/v2rayN.desktop"
grep -E '^(Type|Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' "$target/v2rayN.desktop"
BASH

Type은 Application이어야 합니다. Exec에 지정된 프로그램이 실제로 존재하는지도 확인하세요.
Hidden=true 또는 X-GNOME-Autostart-enabled=false가 있으면 텍스트 편집기로 수정한 뒤 다시 테스트하세요.
OnlyShowIn 및 NotShowIn 설정이 데스크톱 환경을 제한할 수 있으므로 복사한 뒤 함께 확인하세요.
Exec에 ~, 파이프 또는 셸 리디렉션을 직접 넣지 마세요. desktop 파일은 일반 대화형 셸처럼 이러한 내용을 해석하지 않습니다.

저장한 뒤 로그아웃하고 다시 로그인해 클라이언트 프로세스가 하나만 실행되는지, 예시 포트가 다시 리스닝하는지 확인하세요. 창을 닫았다가 다시 여는 것만으로는 로그인 시 자동 시작이 작동하는지 확인할 수 없습니다. 클라이언트 업데이트로 설치 경로나 실행 옵션이 바뀌면 직접 복사한 desktop 파일도 함께 수정해야 합니다.

권한, 트레이, 재시작 후 자주 발생하는 문제

문제는 '프로그램이 실행되는가, 코어가 리스닝하는가, 요청이 프록시를 통과하는가, 로그인 시 자동 시작이 적용되는가' 순서로 확인하세요. 창이 숨겨진 문제, 포트 충돌, 네트워크 장애를 혼동하지 않는 데 도움이 됩니다. 처음 설치할 때 특히 자주 겪는 네 가지 상황을 살펴보겠습니다.

설치했는데 메뉴에서 v2rayN을 찾을 수 없나요?

먼저 위의 find 명령으로 desktop 파일을 확인한 다음 패키지 파일 목록도 살펴보세요. 파일이 있다면 로그아웃한 뒤 다시 로그인해 앱 메뉴를 새로 고칠 수 있습니다. 파일이 없다면 실행 경로를 임의로 추측하기보다 예상한 데스크톱 패키지를 다운로드했는지 확인하세요.

sudo로는 실행되는데 일반 사용자에게 권한 오류가 표시되나요?

먼저 root 권한으로 실행한 인스턴스를 종료하세요. 터미널에서 오류에 표시된 설정 디렉터리를 확인하고 ls -ld로 소유자를 살펴보세요. 현재 사용자의 소유임을 확인한 앱 설정 디렉터리만 수정하세요. 홈 디렉터리나 설치 디렉터리 전체의 권한을 재귀적으로 변경하거나 모두에게 쓰기 권한을 부여하지 마세요.

로그인 후 창이 보이지 않으면 실행되지 않은 건가요?

먼저 시스템 프로세스 조회 도구에서 v2rayN을 검색하고 로컬 리스너도 확인하세요. 프로그램이 트레이로 최소화되었을 수 있으며, 일부 데스크톱 환경에서는 트레이 지원을 따로 활성화해야 합니다. 처음 확인할 때는 클라이언트의 시작 후 숨기기 옵션을 끄고 창이 나타나는지 확인한 다음 다시 설정하세요.

로그에 address already in use가 표시되면 어떻게 하나요?

ss -lntp 'sport = :10808'를 실행해 포트를 사용 중인 프로세스를 확인하세요. 권한 오류가 나면 이 진단 명령에만 sudo를 사용하세요. 먼저 자동 시작 중복 여부를 확인한 뒤 기존 인스턴스를 종료할지 리스닝 포트를 변경할지 결정하세요. 포트를 바꾸면 시스템 프록시와 명령줄 옵션도 함께 수정해야 합니다.

업데이트와 롤백: 패키지 관리와 시작 항목 일관성 유지

이후 업데이트도 같은 패키지 관리 방식으로 새 패키지를 설치하세요. 업데이트 전에 클라이언트 설정을 백업하고 구독 주소와 노드 인증 정보는 안전하게 보관하세요. 이 정보에는 접근 권한이 포함될 수 있으므로 공개 오류 화면에 첨부하면 안 됩니다. 업데이트 후에는 클라이언트 및 코어 버전, 리스닝 포트, 자동 시작 항목을 다시 확인하세요.

클라이언트를 종료하고 기존 프로세스와 코어가 멈췄는지 확인한 다음, 아키텍처에 맞는 새 패키지를 설치하세요.
먼저 직접 실행해 프록시를 명시한 요청이 한 번 성공하는지 확인한 뒤 로그아웃하여 로그인 시 자동 시작을 테스트하세요.
새 버전에서 문제가 발생하면 구체적인 오류를 보관하고 시스템 런타임 라이브러리 요구 사항이 바뀌었는지 확인하세요. 사용자 설정을 전부 삭제하는 것부터 시작하지 마세요.
롤백이 필요하면 패키지 관리자가 지원하는 버전 변경 방법을 사용하세요. 이전 버전과 설정이 호환되는지는 별도로 확인해야 하며, 양방향 호환을 전제해서는 안 됩니다.
로그인 시 수동으로 시작하도록 설정한 항목을 취소하려면 사용자의 autostart 디렉터리에서 해당 desktop 파일을 삭제하세요. 시스템 패키지를 제거해도 사용자가 복사한 파일은 삭제되지 않을 수 있습니다.

설치 완료 여부는 '창이 열린다'만으로 판단할 수 없습니다. 일반 사용자로 실행할 수 있는지, 프록시 요청이 통과하는지, 로그인 후 한 번만 실행되는지, 종료 후 앱의 네트워크 상태가 복구되는지를 확인하세요. 네 가지를 차례로 점검하면 설치, 코어, 프록시 연결, 데스크톱 세션 중 어느 계층에서 문제가 발생했는지 빠르게 찾을 수 있습니다.