Linux에서 v2rayN 설치 단계:deb/rpm 패키지 설치, 데스크톱 통합 및 로그인 시 자동 실행 설정

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

Linux용 v2rayN은 Avalonia 데스크톱 인터페이스를 사용하며 Windows의 WPF 배포 라인과는 별개입니다. Linux 그래픽 세션에서 구독, 노드, 라우팅 규칙과 로컬 프록시를 관리할 수 있지만 설치 패키지는 배포판의 패키지 관리 체계와 CPU 아키텍처에 맞아야 합니다. Debian, Ubuntu 및 파생 시스템은 일반적으로 deb 패키지를 사용하고, Fedora, Rocky Linux 등 RPM 체계를 사용하는 시스템은 rpm 패키지를 선택합니다.

먼저 터미널에서 시스템 정보를 확인하세요. 데스크톱 외관만 보고 배포판을 판단해서는 안 됩니다. `amd64` 또는 `x86_64`는 일반적인 64비트 Intel/AMD 장치에 해당하고, `arm64` 또는 `aarch64`는 64비트 ARM 장치에 해당합니다. 다운로드 페이지에서 플랫폼은 Linux를 선택한 뒤 실제 아키텍처에 맞는 설치 패키지를 받으세요.

cat /etc/os-release
uname -m
echo "$XDG_CURRENT_DESKTOP"
echo "$XDG_SESSION_TYPE"

deb 또는 rpm 패키지로 설치하기

다운로드가 끝나면 먼저 설치 패키지가 있는 디렉터리로 이동한 다음 배포판의 패키지 관리자를 사용하세요. 저수준 도구로 강제 압축 해제만 하면 그래픽 라이브러리, 트레이 지원 또는 데스크톱 통합에 필요한 의존성이 자동으로 설치되지 않을 수 있습니다. 아래 명령의 파일명은 다운로드 페이지에 표시된 실제 파일명으로 바꾸세요.

1. 설치 패키지 확인

   ls -lh *.deb *.rpm 2>/dev/null을 실행해 패키지 형식과 장치 아키텍처를 확인하세요. x86_64 장치에는 aarch64 빌드를 설치하지 마세요.

2. 패키지 설치

   Debian/Ubuntu에서는 sudo apt install ./v2rayN-linux-x64.deb을 사용하고, Fedora에서는 sudo dnf install ./v2rayN-linux-x64.rpm을 사용하세요.

3. 클라이언트 실행

   애플리케이션 메뉴에서 v2rayN을 검색하세요. 데스크톱 데이터베이스가 아직 갱신되지 않았다면 로그아웃 후 다시 로그인하거나 터미널에서 v2rayN을 실행해 시작 출력을 확인하세요.

4. 코어 선택

   「설정」→「매개변수 설정」→「Core 유형」을 열고 VLESS, VMess 등의 노드를 사용할 때는 Xray를 선택한 뒤 설정을 저장하세요.

5. 구독 가져오기

   「구독 그룹」에서 구독 주소를 추가하고 그룹을 갱신한 다음 노드를 선택하세요. 이후 코어 로그에서 리스닝이 정상적으로 완료되었는지 확인합니다.

# Debian / Ubuntu
cd ~/Downloads
sudo apt install ./v2rayN-linux-x64.deb

# Fedora
cd ~/Downloads
sudo dnf install ./v2rayN-linux-x64.rpm

APT 또는 DNF로 설치하면 패키지 관리자가 파일 소유 정보를 기록합니다. 이후 새 설치 패키지를 받으면 같은 방식의 설치 명령을 다시 실행해 덮어쓰기 업그레이드를 진행할 수 있습니다. 설정 데이터는 일반적으로 현재 사용자 디렉터리에 저장되므로 root 권한으로 그래픽 클라이언트를 직접 실행하지 마세요. root 소유의 설정 파일이 생성되어 일반 사용자 세션에서 기존 구독을 읽지 못할 수 있습니다.

의존성, 권한 및 실행 실패 해결

설치 실패는 보통 패키지 아키텍처 불일치, 시스템 저장소의 의존성 부족, 그래픽 세션 구성 요소 누락의 세 가지로 나뉩니다. 터미널에 “wrong architecture” 또는 “not supported architecture”가 표시되면 `uname -m`을 다시 확인하세요. APT가 충족할 수 없는 의존성을 보고하면 먼저 시스템 패키지 저장소를 갱신한 뒤 APT로 의존성 해결을 진행합니다.

# Debian / Ubuntu 인덱스 갱신 및 완료되지 않은 의존성 해결
sudo apt update
sudo apt --fix-broken install

# Fedora 캐시 갱신 후 로컬 패키지 재시도
sudo dnf makecache
sudo dnf install ./v2rayN-linux-x64.rpm

# 프로그램이 PATH에 등록되었는지 확인
command -v v2rayN

프로그램은 실행되지만 트레이 아이콘이 나타나지 않는다고 해서 코어가 실행되지 않은 것은 아닙니다. GNOME, KDE Plasma 및 기타 데스크톱 환경은 상태 트레이를 서로 다르게 구현하므로 주 창, 프로세스와 코어 로그를 함께 확인해야 합니다. Wayland 세션에서는 시스템 프록시를 데스크톱 설정 또는 환경 변수가 계속 관리하며, 창이 Wayland로 렌더링되는지 XWayland로 렌더링되는지는 별개의 문제입니다.

데스크톱 항목 및 애플리케이션 메뉴 통합

정식 deb/rpm 패키지는 일반적으로 `.desktop` 파일을 설치해 v2rayN을 애플리케이션 메뉴에 표시합니다. 데스크톱 항목은 단순한 바로가기가 아니라 프로그램 이름, 실행 명령, 아이콘과 분류 정보를 포함합니다. 시스템 항목은 보통 `/usr/share/applications/`에, 현재 사용자용 항목은 `~/.local/share/applications/`에 저장됩니다.

애플리케이션 메뉴에 바로 표시되지 않으면 먼저 실제 항목 파일을 찾은 다음 데스크톱 데이터베이스를 갱신하세요. 잘못된 실행 경로를 추측해 만들지 말고 `command -v v2rayN` 또는 패키지 파일 목록을 조회해 패키지가 프로그램을 설치한 위치를 확인해야 합니다.

# 패키지로 설치된 데스크톱 항목 찾기
find /usr/share/applications ~/.local/share/applications \
  -maxdepth 1 -iname '*v2rayn*.desktop' 2>/dev/null

# Debian / Ubuntu 패키지 내부 파일 조회
dpkg -L v2rayn | grep -E 'applications|/bin/'

# Fedora 패키지 내부 파일 조회
rpm -ql v2rayN | grep -E 'applications|/bin/'

# 현재 사용자 데스크톱 항목 데이터베이스 갱신
update-desktop-database ~/.local/share/applications 2>/dev/null || true

항목은 존재하지만 아이콘이 여전히 나타나지 않으면 먼저 데스크톱 세션에서 로그아웃한 뒤 다시 로그인하세요. 일부 데스크톱 환경은 애플리케이션 목록을 캐시하므로 데이터베이스만 갱신해서는 메뉴가 즉시 재구성되지 않을 수 있습니다. `.desktop` 파일을 직접 편집할 때는 `Exec` 필드가 이미 이동한 압축 파일 디렉터리를 가리키지 않는지도 확인하세요. 파일은 UTF-8 텍스트로 저장하고 `Type=Application`을 유지해야 합니다.

로그인 세션에서 자동 실행되도록 설정

데스크톱 클라이언트에서 말하는 “시작 시 자동 실행”은 정확히는 “사용자가 그래픽 세션에 로그인한 뒤 자동 실행”을 뜻합니다. 이는 XDG Autostart 규격에 의존하며 root의 systemd 시스템 서비스로 설정해서는 안 됩니다. v2rayN은 현재 사용자의 디스플레이 서버, 트레이, 설정 디렉터리와 데스크톱 프록시 환경이 필요하므로 로그인 전에 실행하면 이러한 조건을 확보하지 못하는 경우가 많습니다.

가장 안정적인 방법은 패키지가 이미 제공하는 `.desktop` 항목을 현재 사용자의 `~/.config/autostart/`로 복사하는 것입니다. 이렇게 하면 실행 명령과 아이콘 경로가 애플리케이션 메뉴와 일치하고 프로그램 경로를 다시 입력할 필요도 없습니다.

mkdir -p ~/.config/autostart

desktop_file="$(find /usr/share/applications \
  -maxdepth 1 -iname '*v2rayn*.desktop' -print -quit)"

cp "$desktop_file" ~/.config/autostart/v2rayN.desktop
chmod 644 ~/.config/autostart/v2rayN.desktop

grep -E '^(Name|Exec|Type|Hidden)=' \
  ~/.config/autostart/v2rayN.desktop

• GNOME: “시작 애플리케이션”에서 사용자 범위 자동 실행 항목을 관리할 수 있습니다. 시스템에 해당 화면이 없다면 XDG 항목을 복사하는 방법도 동일하게 작동합니다.
• KDE Plasma: “시스템 설정”→“자동 시작”에서 애플리케이션을 추가하거나 `~/.config/autostart/`를 직접 사용할 수 있습니다.
• 다중 사용자 장치: 각 사용자가 자신의 자동 실행 항목을 별도로 관리해야 하며 개인 구독 설정을 시스템 범위 디렉터리에 넣어서는 안 됩니다.
• 임시 비활성화: 항목의 `Hidden=false`를 `Hidden=true`로 변경하거나 사용자 범위 `.desktop` 파일을 다른 위치로 옮기세요.

코어, 시스템 프록시 및 라우팅 분기 설정

설치가 완료되었다고 해서 클라이언트가 실제로 실행되는 트래픽을 프록시로 보낸다는 뜻은 아닙니다. v2rayN은 설정을 관리하고 코어를 실행하며, Xray는 VLESS, VMess 등의 프로토콜 연결을 처리합니다. 시스템 프록시는 데스크톱 프록시 설정을 지원하는 애플리케이션의 트래픽을 로컬 리스닝 포트로 전달합니다. 이 세 계층을 각각 점검해야 합니다.

1. 「설정」→「매개변수 설정」→「Core 유형」에서 Xray를 선택하고 저장한 뒤 코어를 다시 시작하세요.
2. 구독 그룹을 추가하고 구독을 갱신한 다음 지연 시간과 사용 가능 상태가 정상인 노드를 선택하세요. 구독 주소를 단일 노드 링크로 직접 가져오지 마세요.
3. 로컬 SOCKS 및 HTTP 리스닝 설정을 확인하세요. 일반적인 조합은 `127.0.0.1:10808` 및 `127.0.0.1:10809`입니다.
4. 시스템 프록시를 활성화한 뒤 일반 브라우저로 확인하세요. 명령줄에서만 연결되지 않는다면 터미널 프로그램이 데스크톱 프록시 설정을 읽는지 점검해야 합니다.
5. 필요에 따라 전역 모드 또는 라우팅 분기를 선택하세요. 규칙은 순서대로 매칭되므로 도메인 규칙, IP 규칙과 최종 출구가 서로 덮어쓰지 않도록 구성해야 합니다.

점검 계층	확인 위치	정상적인 상태	문제 발생 시 우선 조치
클라이언트	v2rayN 주 창	구독 그룹과 노드 목록이 표시됨	구독을 다시 갱신하고 그룹 상태 확인
코어	코어 로그	포트 충돌과 설정 구문 오류가 없음	Core 유형, 포트 및 라우팅 규칙 확인
로컬 리스닝	127.0.0.1	10808/10809 등 설정된 포트가 리스닝 중	포트를 점유한 이전 프로세스를 종료하거나 포트 변경
데스크톱 프록시	시스템 네트워크 설정	HTTP/SOCKS가 로컬 리스닝 주소를 가리킴	시스템 프록시 설정을 다시 적용
라우팅	라우팅 설정	대상 도메인이 규칙에 따라 지정된 출구로 전달됨	배열 순서와 최종 매칭 규칙 확인

터미널의 `curl`, 패키지 관리자 또는 기타 명령줄 도구에는 데스크톱 시스템 프록시가 자동으로 적용되지 않을 수 있습니다. 필요하면 현재 터미널 세션에서 `http_proxy`, `https_proxy` 또는 `all_proxy`를 설정하고 포트는 v2rayN의 로컬 리스닝 포트와 맞추세요. 테스트가 끝나면 `unset`으로 변수를 제거해 클라이언트를 종료한 뒤에도 명령이 로컬 포트에 연결을 시도하지 않도록 하세요.

export http_proxy=http://127.0.0.1:10809
export https_proxy=http://127.0.0.1:10809
export all_proxy=socks5://127.0.0.1:10808

# 테스트 완료 후 제거
unset http_proxy https_proxy all_proxy

업그레이드, 제거 및 일상적인 관리

deb/rpm 설치의 주요 장점은 프로그램 파일을 시스템 패키지 관리자가 계속 추적할 수 있다는 점입니다. 업그레이드하기 전에 v2rayN을 정상적으로 종료한 다음 같은 아키텍처의 새 패키지를 설치하세요. 업그레이드 후 「설정」→「매개변수 설정」→「Core 유형」, 로컬 포트와 자동 실행 항목을 확인해 기존 설정을 현재 사용자가 계속 읽는지 점검합니다.

프로그램을 제거하면 APT와 DNF가 시스템에 등록된 프로그램과 데스크톱 항목을 삭제하지만 사용자 디렉터리의 구독, 로그와 자동 실행 사본은 남을 수 있습니다. 재설치할 예정이라면 개인 설정을 성급하게 삭제하지 마세요. 더 이상 사용하지 않기로 했다면 보관할 라우팅 규칙을 먼저 백업한 뒤 사용자 범위 자동 실행 항목을 정리하세요.

# Debian / Ubuntu 제거
sudo apt remove v2rayn

# Fedora 제거
sudo dnf remove v2rayN

# 현재 사용자의 자동 실행 항목 제거
rm -f ~/.config/autostart/v2rayN.desktop

• 업그레이드할 때마다 클라이언트를 한 번 실행해 코어 로그에 설정 마이그레이션 안내가 표시되는지 확인하세요.
• 포트를 변경한 뒤에는 시스템 프록시와 터미널 환경 변수도 함께 갱신하세요. 클라이언트 한 곳만 수정해서는 안 됩니다.
• 구독 갱신에 실패하면 먼저 네트워크 시간 초과, 만료된 주소와 인증서 시간 오류를 구분한 뒤 프록시를 통한 갱신 여부를 결정하세요.
• 라우팅 규칙이 변경되면 구체적인 도메인으로 매칭 결과를 확인하세요. 노드가 “연결됨”으로 표시되는 것만으로 분기 라우팅이 정상이라고 판단하지 마세요.
• 자동 실행에 문제가 생기면 클라이언트를 시스템 서비스로 바꾸기보다 먼저 `.desktop`의 `Exec` 경로를 확인하세요.