v2rayN Linux 설치 가이드: Ubuntu·Debian deb 패키지, Fedora rpm 패키지 및 자동 시작

이 글 미리보기

먼저 배포판과 프로세서 아키텍처를 확인한 뒤 apt 또는 dnf로 로컬 패키지를 설치합니다. 설치 후 앱 메뉴에서 v2rayN을 실행하고 로컬 포트와 서버 연결을 확인한 다음, 설치된 데스크톱 실행 항목을 현재 사용자 로그인 시 자동 시작하도록 설정합니다. 그래픽 데스크톱이 있는 Linux PC를 대상으로 하며, GUI 클라이언트를 시스템 백그라운드 서비스로 구성하지 않습니다.

배포판·아키텍처·데스크톱 환경 확인

‘패키지 아키텍처가 일치하지 않음’이라는 오류가 뜨거나 설치 파일을 두 번 클릭해도 반응이 없다면, 먼저 커널을 바꾸지 마세요. deb와 rpm은 배포판별 패키지 형식이지 프록시 프로토콜이 아닙니다. Ubuntu와 Debian은 deb를, Fedora는 rpm을 사용합니다. v2rayN은 노드를 관리하고 설정을 생성한 뒤 코어를 호출하는 GUI 클라이언트입니다. 따라서 Linux 데스크톱용 설치 패키지를 GUI가 없는 서버용 서비스 패키지처럼 취급하면 안 됩니다.

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, arm64라고 표기하기도 합니다. 이름만 다를 뿐 같은 아키텍처입니다. 압축을 풀거나 강제 설치 옵션을 사용해 아키텍처 검사를 우회하지 마세요.

배포판 기본 패키지

권장

Ubuntu와 Debian에서는 deb를, Fedora에서는 rpm을 선택하세요. 패키지 관리자가 파일을 등록하고 의존성을 해결하며, 설치된 파일 목록을 통해 데스크톱 실행 항목도 확인할 수 있습니다.

추천 대상: 앱 메뉴에서 실행하고 업데이트·삭제 기록을 관리하려는 데스크톱 사용자

Linux 압축 파일

다운로드 페이지에 해당 아키텍처용 압축 파일이 있을 때만 고려하세요. 디렉터리 구조와 실행 권한, 데스크톱 실행 항목을 직접 관리해야 하며, 아래 패키지 조회 명령은 사용할 수 없습니다.

추천 대상: 수동 설치 경험이 있거나 제공된 패키지를 현재 시스템에 설치하기 어려운 사용자

클라이언트 다운로드 페이지에서 Linux 설치 패키지를 선택하세요. 아래에서는 특정 버전이나 파일명을 지정하지 않고, 실제로 다운로드한 파일의 메타데이터를 확인합니다. 오래된 안내서의 버전 번호를 현재 제공되는 버전으로 착각하지 않도록 하기 위해서입니다.

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

Bash 터미널에서 작업하는 것을 권장합니다. 아래 명령은 설치 패키지의 전체 경로를 입력받은 뒤 패키지 이름, 버전, 아키텍처를 확인합니다. 경로를 입력할 때 따옴표를 덧붙이거나 공백을 백슬래시로 이스케이프하지 마세요. 명령에서 경로를 알아서 인용 처리합니다. 파일 출처와 메타데이터를 확인한 뒤에만 설치를 진행하세요.

read -r -e -p "deb 파일 전체 경로: " package
package="$(realpath -- "$package")"
dpkg-deb -f "$package" Package Version Architecture
pkg_name="$(dpkg-deb -f "$package" Package)"

sudo apt update
sudo apt install "$package"

apt install에 로컬 패키지의 절대 경로를 지정하면, 설정된 저장소에서 필요한 의존성을 가져옵니다. dpkg -i만 실행하고 설치가 끝났다고 판단하지 마세요. 패키지를 등록할 수는 있지만 누락된 의존성을 자동으로 다운로드하지는 않습니다. 설치 명령이 정상적으로 끝난 뒤 설치 상태를 확인하세요.

dpkg-query -W -f='${Package} ${Version} ${Status}\n' "$pkg_name"
dpkg -L "$pkg_name" | grep '/applications/.*\.desktop$'

패키지 정보 확인
명령 출력에 표시된 버전과 Architecture를 확인하세요. 이 정보를 기록해 두면 나중에 업데이트 문제를 해결할 때 ‘최신 버전 설치’라는 기억보다 훨씬 유용합니다.
의존성 설치 완료
apt가 정상적으로 종료될 때까지 기다리세요. 저장소에 연결할 수 없다는 메시지가 나오면 설치 파일을 반복해서 두 번 클릭하지 말고, 네트워크나 저장소 설정부터 해결하세요.
앱 메뉴에서 실행 항목 확인
앱 메뉴에서 v2rayN을 검색하세요. 메뉴가 아직 갱신되지 않았다면 로그아웃한 뒤 다시 로그인하면 됩니다. 이 문제만으로 재설치할 필요는 없습니다.
일반 사용자로 실행
데스크톱 실행 항목에서 클라이언트를 시작하세요. 설치 작업에 관리자 권한이 필요하더라도 평소 클라이언트 실행에 sudo를 사용할 필요는 없습니다.

dnf로 Fedora에 rpm 패키지 설치

Fedora에서도 먼저 메타데이터를 확인한 다음 패키지 관리자에 설치를 맡깁니다. 아래 명령은 deb 설치 절차와 둘 중 하나만 선택하세요. 한 컴퓨터에서 두 패키지 형식을 섞어 사용하지 마세요. 터미널을 그대로 열어 두세요. 뒤에서 데스크톱 실행 항목을 조회할 때 pkg_name 변수를 계속 사용합니다.

read -r -e -p "rpm 파일 전체 경로: " package
package="$(realpath -- "$package")"
rpm -qpi "$package"
pkg_name="$(rpm -qp --queryformat '%{NAME}' "$package")"

sudo dnf install "$package"
rpm -q "$pkg_name"
rpm -ql "$pkg_name" | grep '/applications/.*\.desktop$'

dnf install은 활성화된 저장소를 확인해 의존성을 해결합니다. 공유 라이브러리가 없거나 버전 조건을 충족할 수 없다는 오류가 나오면 전체 오류 메시지를 저장하고 설치 패키지가 현재 Fedora 버전에 맞는지 확인하세요. 의존성 검사를 건너뛰어 오류를 프로그램 실행 단계로 미루지 마세요. 출처가 불분명한 곳에서 같은 이름의 공유 라이브러리를 내려받아 시스템 파일을 덮어쓰는 것도 피해야 합니다.

프로그램이 열리지 않을 때는 오류 유형별로 확인

‘설치는 됐는데 창이 나타나지 않음’이 반드시 의존성 문제인 것은 아닙니다. 창이 시스템 트레이로 최소화됐거나 시작 중 종료됐을 수 있습니다. 먼저 트레이와 프로세스를 확인한 다음 패키지가 제공하는 데스크톱 파일에서 실행 명령을 확인하세요. 경험만으로 실행 파일의 대소문자나 설치 경로를 추측하지 마세요.

증상	먼저 확인할 항목	해결 방법
아키텍처 불일치	uname 출력과 패키지 메타데이터	x64 또는 ARM64 패키지를 다시 선택하고 강제 설치는 하지 마세요.
deb 의존성 설치 미완료	apt 전체 오류 메시지와 저장소 상태	apt --fix-broken install을 실행하고, 제안된 작업을 확인한 뒤 계속 진행하세요.
공유 라이브러리가 없다는 오류	터미널에 표시된 누락 라이브러리의 전체 이름	배포판 저장소에서 해당 패키지를 찾고 시스템 버전과 호환되는지 확인하세요.
앱 메뉴에 실행 항목이 없음	설치된 파일에 .desktop 파일이 있는지	패키지 내용과 메뉴 캐시를 확인하고, 필요하면 로그아웃한 뒤 다시 로그인하세요.
실행 직후 종료됨	Exec 명령 출력과 디렉터리 쓰기 권한	구체적인 오류를 기준으로 해결하고, 설정을 전부 삭제하는 것부터 시작하지 마세요.

Debian에서 sudo apt --fix-broken install을 실행하면 의존성 설치를 제안할 수도 있고, 설정할 수 없는 패키지의 삭제를 제안할 수도 있습니다. 작업 목록을 읽은 뒤 진행 여부를 결정하세요. GUI 클라이언트를 sudo로 실행한 적이 있다면 실제 설정 디렉터리의 소유권을 확인하세요. 문제가 있는 것으로 확인된 앱 디렉터리만 수정하고, 홈 디렉터리 전체의 권한을 재귀적으로 변경하지 마세요.

데스크톱 파일의 Exec=은 실행 규칙이지 터미널에 그대로 붙여 넣어도 되는 스크립트가 아닙니다. %U, %F 같은 데스크톱 필드 코드가 있으면 수동으로 디버깅할 때 해당 코드를 제거하고 실제 명령, 인수, 경로 인용은 유지하세요. 읽어 온 한 줄 전체를 eval로 실행하지 마세요.

리스닝과 프록시를 먼저 확인한 뒤 자동 시작 설정

v2rayN을 처음 실행하면 먼저 사용할 수 있는 설정을 가져오고 서버 하나를 선택하세요. 구독을 추가하려면 메인 화면에서 ‘구독 그룹’ → ‘구독 그룹 설정’을 열어 그룹과 주소를 입력한 뒤, ‘구독 그룹’ 메뉴에서 해당 업데이트 작업을 실행합니다. 버전에 따라 버튼 배치는 달라질 수 있으므로 현재 화면에 표시된 문구를 기준으로 하세요. 구독 업데이트에 성공해도 노드 정보만 가져온 것이며 서버 연결까지 확인된 것은 아닙니다.

‘설정’ → ‘매개변수 설정’에서 로컬 리스닝 옵션을 확인하세요. 아래 예시에서는 혼합 프록시 주소로 127.0.0.1:10808을 사용하지만, 실제 주소는 클라이언트 설정과 일치해야 합니다. 안내서에 10808이라고 적혀 있다는 이유로 기존 포트를 덮어쓰거나, 이 컴퓨터의 연결 문제를 해결하려고 리스닝 주소를 모든 네트워크 인터페이스로 변경하지 마세요.

10808

이 문서의 로컬 프록시 포트 예시

127.0.0.1

로컬 루프백 주소

15초

아래 요청의 제한 시간

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

위 요청은 해당 프로토콜을 지원하는 리스너가 활성화된 경우에만 의미가 있습니다. socks5h는 대상 도메인 이름을 프록시 쪽에서 처리하므로 로컬 DNS 경로와 구분할 때 사용할 수 있습니다. HTTP 응답을 받았다는 것은 이번 요청이 완료됐다는 뜻일 뿐, 모든 웹사이트나 프로그램이 프록시를 사용한다는 의미는 아닙니다. 로그에서 트래픽이 직접 연결된 것으로 표시되면 예상한 라우팅에 맞는 테스트 대상을 선택하세요.

프록시를 지정해 연결 확인

프록시 주소: 127.0.0.1
포트 예시: 10808
요청 방식: curl --proxy
제한 시간: 15초

데스크톱 시스템 프록시 설정을 거치지 않고 클라이언트의 리스닝과 외부 연결을 먼저 확인합니다.

데스크톱 프록시 확인

GNOME 설정 경로: ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’
확인할 항목: HTTP, HTTPS, SOCKS의 주소와 포트
브라우저 설정: 확장 프로그램 및 브라우저 자체 프록시 설정
터미널 변수: http_proxy、https_proxy、all_proxy

데스크톱 프록시가 모든 터미널 프로그램에 자동 적용되는 것은 아닙니다. 같은 테스트 주소를 사용해 단계별로 확인하세요.

데스크톱 로그인 후 자동 시작 설정

데스크톱 사용자들이 흔히 ‘부팅 시 자동 시작’이라고 부르는 기능은 실제로 현재 사용자가 그래픽 세션에 로그인한 뒤 프로그램을 실행하는 방식입니다. 이때 데스크톱 세션, 사용자 설정, 트레이 환경이 준비되어 있습니다. 창 프로그램을 root로 실행하는 시스템 서비스를 바로 만들지 마세요. 디스플레이 서버, 세션 버스, 설정 소유권 문제가 발생하기 쉽습니다.

자동 시작 방법은 하나만 선택하세요

클라이언트 내장 옵션

‘설정’ → ‘매개변수 설정’에 ‘부팅 시 자동 시작’ 옵션이 있는지 확인하세요.
현재 Linux 버전에서 해당 옵션을 실제로 제공하고 사용할 수 있을 때만 켜세요.
활성화한 뒤 로그아웃해 테스트하고, 데스크톱 실행 항목을 별도로 복사하지 마세요.

XDG 로그인 자동 시작

설치 패키지가 제공하는 .desktop 파일을 사용하세요.
현재 사용자의 ~/.config/autostart/ 디렉터리에 복사하세요.
XDG 자동 시작 규칙을 따르는 데스크톱 세션에 적합합니다.

두 방법 중 하나만 선택하세요. 전체 데스크톱 세션 없이 창 관리자만 사용하는 환경이라면 해당 세션의 시작 방식을 따로 확인해야 합니다.

XDG 방식으로 설정하려면 먼저 데스크톱 파일을 찾으세요. 아래 두 조회 명령 중 배포판에 맞는 하나를 실행합니다. 설치 터미널을 이미 닫았다면 패키지 관리자에서 실제 패키지 이름을 확인하고 pkg_name을 다시 설정해야 합니다. 이전 변수가 그대로 남아 있다고 가정하지 마세요.

# Ubuntu / Debian
dpkg -L "$pkg_name" | grep '/applications/.*\.desktop$'

# Fedora
rpm -ql "$pkg_name" | grep '/applications/.*\.desktop$'

실행 항목이 여러 개 표시되면 메인 화면을 여는 항목을 선택하세요. 제거용 항목이나 보조 항목은 선택하지 않습니다. 그런 다음 전체 경로를 입력해 주요 필드를 확인하고 원본 파일을 복사하세요. 이렇게 하면 설치 패키지가 제공한 Exec, Icon, 작업 디렉터리 설정을 그대로 유지할 수 있어 프로그램 위치를 추측할 필요가 없습니다.

read -r -e -p "메인 화면 desktop 파일 전체 경로: " desktop
desktop="$(realpath -- "$desktop")"
grep -E '^(Type|Name|Exec|TryExec|Path|Hidden|OnlyShowIn|NotShowIn|X-GNOME-Autostart-enabled)=' "$desktop"

mkdir -p "$HOME/.config/autostart"
install -m 644 "$desktop" "$HOME/.config/autostart/v2rayn.desktop"

복사하기 전에 실행 항목이 Type=Application인지, Hidden=true나 자동 시작을 비활성화하는 필드가 없는지 확인하세요. OnlyShowIn 또는 NotShowIn이 있다면 현재 데스크톱 환경이 제외되지 않는지도 확인해야 합니다. 이러한 제한이 있으면 용도를 확인한 뒤 사용자 복사본을 수정하세요. 패키지 관리자가 관리하는 원본 파일은 수정하지 마세요.

로그아웃 후 재확인, 업데이트 및 설정 취소

자동 시작 설정을 마치면 먼저 클라이언트를 정상 종료한 뒤 로그아웃하고 다시 로그인하세요. 창을 닫았다고 프로세스까지 종료된 것은 아닐 수 있습니다. 일부 설정에서는 닫기 동작이 시스템 트레이로 최소화되도록 되어 있습니다. 다시 로그인한 뒤 프로세스, 리스닝 포트, 요청 결과를 확인하세요. 세 항목을 모두 통과해야 설정이 완료된 것입니다.

중복 실행 여부 확인: 데스크톱의 ‘시작 프로그램’, 클라이언트 내장 옵션, 사용자 autostart 디렉터리를 확인하고 중복된 시작 항목을 제거하세요.
설정 파일 확인: 서버 목록, 구독 그룹, 선택된 노드가 그대로 있어야 합니다. 관리자 권한으로 실행했을 때 사용하던 설정과 다른 설정이 나타나면 안 됩니다.
네트워크 연결 확인: 로그인 직후 Wi-Fi 연결이 아직 완료되지 않았다면 구독 업데이트가 실패할 수 있습니다. 네트워크에 연결될 때까지 기다렸다가 직접 다시 시도하세요. 이 문제만으로 자동 시작이 실패했다고 판단하지 마세요.
프록시 복구 확인: 포트와 curl 테스트를 다시 실행한 다음 브라우저를 확인하세요. 창이 나타났다고 해서 시스템 프록시 설정까지 적용된 것은 아닙니다.

업데이트할 때는 클라이언트를 종료한 뒤 같은 패키지 관리자를 사용해 동일한 아키텍처의 새 버전을 설치하세요. 사용자가 복사한 데스크톱 파일은 원본이 업데이트되어도 자동으로 갱신되지 않습니다. 새 버전에서 Exec이나 설치 경로가 바뀌었다면 실행 항목을 다시 확인하고 복사하세요. 마이그레이션 전에 클라이언트가 실제로 사용하는 데이터 디렉터리를 백업하세요. 프로그램 업데이트로 덮어쓸 수 있는 설치 디렉터리에 백업 파일을 두지 마세요.

이 문서에서 설정한 XDG 자동 시작을 취소하려면 직접 만든 사용자 복사본만 삭제하면 됩니다. 클라이언트 내장 옵션을 사용했다면 원래 설정 화면에서 끄세요. 제거하기 전에 더 이상 사용하지 않는 데스크톱 프록시 설정을 지우세요. 그렇지 않으면 브라우저가 이미 리스닝을 중단한 포트에 계속 연결할 수 있습니다.

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

문제 해결 순서는 마지막까지 동일하게 유지하세요. 패키지가 올바르게 설치됐는지 확인하고, 메인 프로그램이 실행되는지 확인한 다음, 로컬 포트와 서버 연결을 점검하고, 마지막으로 데스크톱 프록시와 로그인 자동 시작을 확인합니다. 의존성, 포트, 권한, 시작 방식을 한꺼번에 바꾸는 것보다 각 단계를 따로 확인하는 편이 원인을 찾기 쉽습니다.