이 글 한눈에 보기

Linux 그래픽 데스크톱에 진입한 뒤 v2rayN을 설치하려는 사용자에게 적합합니다. 배포판에 맞는 deb 또는 rpm 패키지를 선택하고 프로그램 경로와 Xray Core를 확인한 다음 트레이 구성 요소, 10808 로컬 프록시 포트와 systemd 로그인 시 자동 시작을 설정합니다. 완료 후 로그와 포트 리스닝 결과로 정상 시작 여부를 확인할 수 있습니다.

설치 전 아키텍처와 데스크톱 환경 확인

v2rayN Linux 데스크톱 버전은 그래픽 세션에서 실행해야 합니다. Debian, Ubuntu, Linux Mint 등은 deb 패키지를 사용하고 Fedora, Rocky Linux, AlmaLinux 등은 rpm 패키지를 사용합니다. 패키지 형식은 배포판과 일치해야 하며 프로세서 아키텍처도 맞아야 합니다. 일반적인 PC는 x64를 선택하고 ARM 프로세서 기기는 arm64를 선택하세요. 운영체제가 64비트라는 이유만으로 x64를 선택해서는 안 됩니다.

먼저 터미널에서 다음 명령을 실행합니다. 첫 번째 명령은 프로세서 아키텍처를 확인하고, 두 번째는 배포판 식별자를 표시하며, 세 번째는 현재 데스크톱 세션 유형을 확인합니다. 출력이 x86_64이면 x64 패키지를, aarch64이면 arm64 패키지를 선택하세요. XDG_SESSION_TYPE에는 일반적으로 wayland 또는 x11이 표시됩니다.

uname -m
cat /etc/os-release
printf '%s\n' "$XDG_SESSION_TYPE"

이 글은 v2rayN 7.15.2의 화면과 패키지 관리 절차를 기준으로 합니다. 이후 버전에서는 버튼 위치가 조금 달라질 수 있지만 설치 명령, 사용자 서비스 디렉터리와 포트 점검 방법은 동일합니다. 기존 버전을 업그레이드하기 전에 실행 중인 v2rayN을 먼저 종료하여 이전 프로세스가 설정 파일이나 로컬 리스닝 포트를 계속 점유하지 않도록 하세요.

7.15.2
이 글의 기준 버전
10808
일반 SOCKS 포트
10809
일반 HTTP 포트
15초
시작 관찰 시간

deb 또는 rpm 설치 방식 선택

deb와 rpm은 모두 시스템 패키지입니다. 프로그램, 데스크톱 실행 항목과 아이콘을 배포판이 정한 위치에 설치하고 패키지 관리자에 등록합니다. 직접 압축을 푸는 방식보다 시스템 패키지가 파일 위치를 확인하고 제거하기 편하며, 설치 과정에서 누락된 의존성도 명확히 안내받을 수 있습니다.

시스템 기본 패키지

권장

Debian과 Ubuntu는 deb를, Fedora 계열은 rpm을 선택합니다. 프로그램 실행 항목과 데스크톱 파일은 패키지 관리자가 통합 관리합니다.

적합한 경우: 장기 사용, 메뉴 항목과 버전 관리가 필요한 경우

수동 압축 해제

사용자 디렉터리에 프로그램을 보관하고 업그레이드할 때 직접 파일을 교체하며 systemd 서비스의 실행 파일 경로도 직접 입력합니다.

적합한 경우: 시스템 설치 권한이 없거나 임시로 테스트할 때

기존 버전 유지

먼저 설정을 내보낸 다음 새 패키지를 설치해 프로그램을 덮어씁니다. 10808 또는 10809 포트가 충돌할 수 있으므로 두 버전을 동시에 실행하지 마세요.

적합한 경우: 업그레이드 전에 잠시 되돌릴 가능성이 있을 때

Debian 및 Ubuntu에 deb 설치

다운로드한 deb 파일을 “다운로드” 디렉터리에 넣고 해당 디렉터리로 이동한 뒤 apt install로 로컬 패키지를 설치합니다. 명령의 파일명은 실제 이름으로 바꿔야 하며, 입력하기 전에 ls *.deb로 확인할 수 있습니다. dpkg를 직접 실행하는 것과 달리 apt는 저장소에서 제공되는 의존성도 함께 처리합니다.

cd ~/다운로드
ls *.deb
sudo apt install ./v2rayN-linux-64.deb

시스템 디렉터리 이름이 영어라면 경로는 보통 ~/Downloads입니다. 앞서 dpkg -i로 설치한 뒤 의존성 부족 메시지가 표시되었다면 sudo apt -f install을 실행해 해결한 다음 설치 명령을 다시 실행하세요. 동일한 패키지 이름으로 업그레이드하면 apt는 사용자 디렉터리의 설정 데이터를 유지합니다.

Fedora 계열에 rpm 설치

Fedora에서는 로컬 rpm을 처리할 때 dnf install을 사용하는 것이 좋습니다. 명령 앞의 ./은 현재 디렉터리의 파일임을 나타내므로 저장소 패키지 이름처럼 생략할 수 없습니다. 설치가 끝나면 대소문자를 구분하지 않는 조회 명령으로 패키지 등록 정보를 확인할 수 있습니다.

cd ~/Downloads
ls *.rpm
sudo dnf install ./v2rayN-linux-64.rpm
rpm -qa | grep -i '^v2rayn'

Debian / Ubuntu

패키지 형식
deb
설치 명령
apt install ./파일명.deb
의존성 해결
apt -f install
제거 및 조회
dpkg -l | grep -i v2rayn

로컬 패키지와 저장소 의존성은 우선 apt가 처리하도록 하세요.

Fedora 계열

패키지 형식
rpm
설치 명령
dnf install ./파일명.rpm
의존성 처리
dnf가 해결
설치 조회
rpm -qa | grep -i v2rayn

로컬 파일을 설치할 때 경로 접두사 ./를 유지하세요.

첫 실행과 코어 설정 확인

설치가 끝나면 먼저 애플리케이션 메뉴에서 v2rayN을 실행하고 백그라운드 자동 시작은 바로 설정하지 마세요. 첫 실행에서는 주 창이 열리는지, 코어가 시작되는지, 설정 디렉터리에 쓰기 가능한지를 확인해야 합니다. 애플리케이션 메뉴가 아직 갱신되지 않았다면 로그아웃한 뒤 데스크톱에 다시 로그인하거나 터미널에서 command -v v2rayN을 실행해 시작 명령을 찾으세요.

주 화면에서 「설정」→「매개변수 설정」→「Core 유형」을 엽니다. VLESS, Reality 또는 최신 Xray 기능이 필요한 노드를 사용할 때는 Xray를 선택하세요. 기존 VMess 노드도 Xray로 처리할 수 있습니다. 노드 프로토콜, 주소, 포트, 사용자 식별자, 전송 방식, TLS 및 Reality 매개변수는 서버와 하나씩 일치해야 합니다. 클라이언트 설치가 성공했다고 해서 노드 설정까지 올바른 것은 아닙니다.

  1. 주 프로그램 시작

    데스크톱 애플리케이션 메뉴에서 v2rayN을 열고 주 창이 완전히 표시될 때까지 기다립니다. 터미널에서 시작하는 경우 누락된 구성 요소를 확인할 수 있도록 터미널 출력을 유지하세요.

  2. 코어 선택

    「설정」→「매개변수 설정」→「Core 유형」으로 이동해 평소 VLESS, Reality 또는 VMess를 사용할 때 Xray를 선택한 다음 설정을 저장합니다.

  3. 구독 가져오기

    「구독 그룹」에서 전체 구독 주소를 추가하고 저장한 뒤 구독 업데이트를 실행합니다. 업데이트에 실패하면 먼저 시스템 시간, DNS와 현재 네트워크 연결을 확인하세요.

  4. 노드 선택

    노드 목록에서 설정 하나를 선택해 활성 서버로 지정한 다음 코어를 시작합니다. 동일한 로컬 포트를 사용하는 다른 프록시 프로그램을 동시에 실행하지 마세요.

  5. 프록시 확인

    로컬 SOCKS 포트 10808과 HTTP 포트 10809를 확인한 뒤 필요에 따라 시스템 프록시를 활성화합니다. 포트는 현재 매개변수 설정 화면에 표시된 값을 기준으로 하세요.

시작이 완료되면 ss로 리스닝 상태를 확인합니다. 127.0.0.1:10808 또는 설정 화면에서 지정한 로컬 주소가 보이면 코어가 로컬 진입점을 만든 것입니다. 주 화면에는 시작됨으로 표시되지만 리스닝 기록이 없다면 v2rayN 로그에서 코어가 종료된 원인을 확인하세요.

ss -lntp | grep -E '10808|10809'
ps -ef | grep -E 'v2rayN|xray' | grep -v grep

데스크톱 트레이 아이콘이 표시되지 않을 때

v2rayN은 주 창을 닫은 뒤에도 보통 트레이에 상주하므로 트레이 아이콘 표시 여부는 종료, 노드 전환과 창 복원에 직접 영향을 줍니다. 아이콘이 사라졌다고 해서 반드시 코어가 중지된 것은 아닙니다. 먼저 ps와 ss로 프로세스와 포트를 확인한 뒤 데스크톱 환경이 상태 아이콘을 지원하는지 점검하세요.

Ubuntu와 일부 GNOME 데스크톱은 일반적으로 Ayatana AppIndicator 구성 요소에 의존합니다. 먼저 런타임 라이브러리를 설치한 뒤 데스크톱에서 로그아웃하고 다시 로그인하세요. Fedora의 구체적인 패키지 이름은 버전과 활성화된 저장소에 따라 달라지므로 dnf search appindicator로 먼저 검색하고 다른 배포판의 deb 패키지를 섞어 설치하지 마세요.

sudo apt update
sudo apt install libayatana-appindicator3-1

dnf search appindicator

Wayland 세션에서 주 창은 정상적으로 표시되지만 트레이 메뉴가 나타나지 않는다면 먼저 데스크톱 패널에서 애플리케이션 상태 아이콘을 표시하도록 허용했는지 확인하세요. 그다음 v2rayN을 완전히 종료하고 다시 시작합니다. 애플리케이션 메뉴를 반복해서 클릭하기만 하면 단일 인스턴스 제한이 작동해 새 창은 나타나지 않고 기존 백그라운드 프로세스만 남을 수 있습니다.

아이콘을 눌러도 주 창이 열리지 않나요?

pgrep -a v2rayN을 실행해 기존 프로세스를 확인하세요. 프로세스가 있으면 먼저 트레이에서 종료를 선택합니다. 트레이가 보이지 않으면 해당 프로세스를 종료한 뒤 터미널에서 다시 시작하고 출력을 확인하세요.

트레이 아이콘이 빈칸으로 표시되나요?

AppIndicator 런타임 라이브러리를 다시 설치하고 데스크톱 세션에서 로그아웃한 뒤 다시 로그인하세요. v2rayN만 재시작해서는 데스크톱 패널이 아이콘 지원을 다시 불러오지 못할 수 있습니다.

코어가 시작됐는데도 웹 페이지가 열리지 않나요?

먼저 ss -lntp를 실행해 10808과 10809를 확인한 다음 시스템 프록시에 SOCKS 포트와 HTTP 포트 중 무엇을 입력했는지 점검하세요. 프로토콜과 포트를 서로 바꿔 입력하면 안 됩니다.

구독 업데이트가 계속 시간 초과되나요?

먼저 시스템 시간을 조정한 다음 DNS와 구독 주소가 완전한지 확인하세요. 사용 가능한 노드가 있다면 구독 설정에서 프록시를 통한 업데이트를 활성화한 뒤 다시 시도할 수 있습니다.

업그레이드 후 기존 노드가 사라졌나요?

시스템에 설치된 버전이 아니라 이전 디렉터리에서 압축을 푼 버전이 실행되고 있지 않은지 확인하세요. 두 프로그램이 서로 다른 설정 디렉터리를 읽을 수 있으므로 기존 프로세스를 종료한 뒤 현재 설정 경로를 점검하세요.

systemd 사용자 서비스 설정

데스크톱 프로그램은 시스템 수준의 root 서비스보다 systemd 사용자 서비스를 사용하는 것이 적합합니다. 사용자 서비스는 현재 계정의 사용자 관리자에서 실행되므로 해당 계정의 설정 디렉터리를 읽을 수 있고 journalctl --user로 로그를 확인하기도 편합니다. 여기서 말하는 로그인 시 자동 시작은 해당 사용자가 그래픽 데스크톱에 로그인한 뒤 자동으로 실행된다는 뜻입니다. v2rayN은 트레이와 디스플레이 세션이 필요하므로 로그인하지 않은 상태에서 강제로 시작하는 방식에는 적합하지 않습니다.

먼저 command -v v2rayN을 실행해 실제 경로를 확인합니다. 시스템 패키지의 일반적인 출력은 /usr/bin/v2rayN이지만 반드시 현재 컴퓨터의 결과를 기준으로 하세요. 그런 다음 사용자 서비스 디렉터리와 서비스 파일을 만듭니다.

command -v v2rayN
mkdir -p ~/.config/systemd/user
nano ~/.config/systemd/user/v2rayn.service

아래 내용을 파일에 작성합니다. 첫 번째 명령이 반환한 경로가 /usr/bin/v2rayN이 아니라면 ExecStart도 반드시 함께 수정해야 합니다. 서비스는 비정상 종료 후 5초 기다렸다가 재시작하며 그래픽 세션과 네트워크 대상이 준비된 뒤 시작되도록 설정합니다.

[Unit]
Description=v2rayN desktop client
After=graphical-session.target network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/v2rayN
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

서비스 파일

위치
~/.config/systemd/user/v2rayn.service
서비스 유형
Type=simple
재시작 정책
on-failure
대기 시간
5초

서비스는 현재 데스크톱 사용자에 속하므로 sudo로 만들지 않습니다.

실행 조건

프로그램 경로
command -v v2rayN
시작 대상
default.target
세션 요구 사항
그래픽 데스크톱 로그인 완료
로그 범위
systemd 사용자 로그

그래픽 클라이언트를 root 시스템 서비스로 설정하지 마세요.

저장한 뒤 사용자 서비스를 다시 불러오고 활성화한 다음 즉시 시작합니다. 약 15초 기다린 후 서비스 상태를 확인하세요. 상태가 active (running)이고 로컬 포트가 존재하면 자동 시작 경로가 구축된 것입니다.

systemctl --user daemon-reload
systemctl --user enable --now v2rayn.service
systemctl --user status v2rayn.service
ss -lntp | grep -E '10808|10809'

로그 확인, 비활성화와 업그레이드 후 관리

서비스가 시작되지 않으면 먼저 최근 사용자 로그 50줄을 확인하세요. 일반적인 원인은 ExecStart 경로 오류, 이미 실행 중인 다른 v2rayN 인스턴스, 10808 포트 점유, 그래픽 세션 환경 미준비입니다. 로그를 확인하지 않은 채 패키지를 반복해서 재설치하지 마세요. 설정 오류와 포트 충돌은 재설치만으로 해결되지 않습니다.

journalctl --user -u v2rayn.service -n 50 --no-pager
systemctl --user restart v2rayn.service
systemctl --user is-enabled v2rayn.service
systemctl --user is-active v2rayn.service

로그에 Address already in use가 표시되면 다음 명령으로 포트를 점유한 프로세스를 찾습니다. 프로세스의 용도를 확인한 뒤 충돌하는 프로그램을 종료하거나 v2rayN의 「설정」→「매개변수 설정」에서 로컬 리스닝 포트를 변경할 수 있습니다. 변경 후에는 브라우저, 터미널 환경 변수와 시스템 프록시에 설정된 포트도 함께 업데이트해야 합니다.

ss -lntp | grep ':10808'
lsof -iTCP:10808 -sTCP:LISTEN

로그인 시 자동 시작이 당분간 필요하지 않다면 비활성화와 중지를 함께 실행하세요. 서비스 파일을 수정했다면 다시 불러온 뒤 재시작합니다. deb 또는 rpm으로 업그레이드한 후에는 command -v v2rayN도 다시 실행해 프로그램 경로가 바뀌지 않았는지 확인하세요.

systemctl --user disable --now v2rayn.service

systemctl --user daemon-reload
systemctl --user restart v2rayn.service