v2rayN Linux 데스크톱 설치 가이드: deb/rpm 패키지 선택과 로그인 시 자동 실행 설정

설치 패키지 선택: deb, rpm 및 프로세서 아키텍처

Linux 설치 실패의 가장 흔한 원인은 의존성보다 패키지 형식이나 프로세서 아키텍처를 잘못 선택하는 것입니다. Ubuntu, Debian, Linux Mint 등 Debian 계열 배포판은 deb를 사용하고, Fedora, Rocky Linux, AlmaLinux 등 RPM 패키지 관리 체계를 사용하는 배포판은 rpm을 사용합니다. 패키지 형식은 데스크톱 환경만으로 판단할 수 없습니다. GNOME, KDE Plasma 등 어떤 데스크톱도 여러 배포판에서 실행될 수 있습니다.

먼저 터미널에서 시스템 확인 명령어를 실행합니다. 첫 번째 명령어는 배포판 식별 정보를 읽고, 두 번째 명령어는 프로세서 아키텍처를 반환합니다. 일반적으로 x86_64는 64비트 x86 플랫폼, aarch64 또는 arm64는 64비트 ARM 플랫폼을 뜻합니다. 다운로드 페이지의 아키텍처는 명령어 결과와 일치해야 하며, 파일 이름을 바꾼다고 변환되지는 않습니다.

cat /etc/os-release
uname -m

deb 및 rpm 설치 명령어

먼저 이 사이트의 다운로드 센터에서 시스템 아키텍처에 맞는 Linux 설치 패키지를 받은 다음 다운로드 디렉터리를 엽니다. 아래 명령어는 특정 버전의 파일명을 고정하지 않고 현재 디렉터리의 후보 파일을 표시합니다. 대상 설치 패키지가 하나뿐인지 확인한 뒤 터미널에 표시된 전체 파일명을 설치 명령어에 복사하세요. 이렇게 하면 문서에 남은 이전 버전 파일명이 새 패키지를 가리는 일을 피할 수 있습니다.

cd ~/Downloads
find . -maxdepth 1 -type f \( -name "*.deb" -o -name "*.rpm" \) -print

Debian, Ubuntu 및 파생 배포판

APT로 로컬 deb를 설치할 때는 파일명 앞의 ./를 반드시 유지해야 합니다. apt install 파일명.deb를 직접 실행하면 APT가 저장소의 패키지 이름으로 인식할 수 있습니다. 설치 전에 저수준 도구로 패키지를 풀 필요는 없습니다. APT가 패키지 내부의 의존성을 확인하고 현재 소프트웨어 저장소에서 필요한 항목을 보완합니다.

cd ~/Downloads
sudo apt update
sudo apt install ./v2rayN-linux-64.deb

예시 파일명은 명령어 구조만 보여 주는 것입니다. 실행할 때는 다운로드 디렉터리에 실제로 표시된 파일명을 사용해야 합니다. 설치가 끝나면 패키지 관리자로 설치된 내용을 조회하고 명령어 경로를 확인하세요. command -v가 절대 경로를 반환하면 현재 계정의 PATH에서 프로그램을 찾을 수 있다는 뜻입니다.

command -v v2rayN
dpkg -l | grep -i v2rayn
dpkg -L v2rayn | grep -E '(/bin/|\.desktop$)'

Fedora 및 RPM 계열 배포판

DNF로 로컬 rpm을 설치할 때도 ./ 경로를 사용합니다. rpm -i를 직접 호출하는 것과 달리 DNF는 소프트웨어 저장소에서 충족할 수 있는 의존성을 처리하므로 데스크톱에서 처음 설치할 때 더 적합합니다. 활성화된 저장소에서 특정 의존성을 제공하지 못하면 DNF가 누락된 패키지 이름을 명확히 표시합니다.

cd ~/Downloads
sudo dnf install ./v2rayN-linux-64.rpm

• 명령어 경로 확인: command -v v2rayN
• 설치된 패키지 확인: rpm -qa | grep -i v2rayn
• 패키지 내부 파일 확인: rpm -ql v2rayN | grep -E '(/bin/|\.desktop$)'
• 제거해야 한다면 먼저 조회 결과로 실제 패키지 이름을 확인한 뒤 sudo dnf remove 패키지명을 실행하세요.

첫 실행 및 데스크톱 메뉴 복구

설치가 끝나면 먼저 터미널에서 한 번 실행합니다. 터미널 출력에는 그래픽 라이브러리, 권한, 설정 디렉터리, 핵심 프로세스와 관련된 정보가 남습니다. 프로그램이 정상적으로 열리면 창을 닫고 애플리케이션 메뉴에 v2rayN이 등록되었는지 확인하세요. 메뉴 항목은 로그아웃 후 다시 로그인해야 갱신될 수 있습니다.

v2rayN

터미널에서는 실행되지만 애플리케이션 메뉴에 항목이 없다면 먼저 설치 패키지에 desktop 파일이 포함되어 있는지 확인하세요. deb 계열은 dpkg -L, rpm 계열은 rpm -ql을 사용합니다. 파일을 찾았다면 데스크톱 데이터베이스를 갱신하세요. 명령어가 없다고 빈 파일을 따로 만들 필요는 없으며, 그래픽 세션에 다시 로그인하면 보통 갱신됩니다.

find /usr/share/applications ~/.local/share/applications \
  -maxdepth 1 -type f -iname "*v2rayn*.desktop" -print

update-desktop-database ~/.local/share/applications 2>/dev/null || true

패키지에 desktop 파일이 실제로 없다면 현재 계정에 메뉴 항목을 만들 수 있습니다. 먼저 command -v v2rayN을 실행해 출력이 /usr/bin/v2rayN인지 확인한 뒤 아래 내용을 사용하세요. 실제 경로가 다르면 Exec를 명령어가 반환한 절대 경로로 바꿔야 합니다. 데스크톱 파일은 사용자 디렉터리에 저장되므로 시스템 패키지의 파일을 덮어쓰지 않습니다.

mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/v2rayn.desktop <<'EOF'
[Desktop Entry]
Type=Application
Name=v2rayN
Comment=V2Ray desktop client
Exec=/usr/bin/v2rayN
Terminal=false
Categories=Network;
StartupNotify=true
EOF
chmod 644 ~/.local/share/applications/v2rayn.desktop
update-desktop-database ~/.local/share/applications 2>/dev/null || true

구독 가져오기, 코어 실행 및 연결 확인

창이 열렸다는 것은 그래픽 프로그램이 실행되었다는 뜻일 뿐, 노드·코어·시스템 프록시가 작동한다는 의미는 아닙니다. 처음 사용할 때는 구독 가져오기, 구독 업데이트, 노드 선택, 코어 실행을 순서대로 완료해야 합니다. 구독 주소는 여러 노드를 일괄 관리하는 데 사용되며, 개별 vmess:// 또는 vless:// 링크는 하나의 노드만 설명하므로 구독의 이후 변경 사항을 자동으로 반영하지 않습니다.

1. 구독 관리 화면을 열고 실제로 보유한 구독 주소를 추가한 다음, 그룹에 알아보기 쉬운 메모를 입력합니다.
2. 구독을 업데이트해 기본 목록에 노드가 표시되는지 확인하세요. 목록이 비어 있으면 먼저 업데이트 로그를 확인하고 시스템 프록시를 반복해서 전환하지 마세요.
3. 노드 하나를 선택해 활성 서버로 지정한 뒤 상태 표시줄이나 로그에서 코어 실행 결과를 확인합니다.
4. 「설정」→「매개변수 설정」으로 이동해 SOCKS, HTTP 또는 혼합 수신 포트의 실제 값을 기록합니다.
5. 데스크톱 환경에 맞게 시스템 프록시를 활성화한 뒤 도메인 확인과 웹 페이지 접속을 각각 테스트합니다.

수신 포트를 확인할 때는 ss를 사용할 수 있습니다. 아래 명령어는 일반적인 10808 및 10809 포트를 필터링합니다. 설정 페이지에 다른 포트가 표시되면 필터 숫자도 실제 값으로 바꾸세요. 정상 결과에는 LISTEN이 포함되며, 보통 127.0.0.1 또는 로컬 루프백 주소에 바인딩됩니다.

ss -lntp | grep -E '10808|10809'

노드가 연결됨으로 표시되지만 웹 페이지가 열리지 않는다면 먼저 ‘코어가 수신 대기하지 않는 문제’와 ‘데스크톱 애플리케이션이 프록시를 사용하지 않는 문제’를 구분하세요. 전자는 ss에서 포트가 보이지 않으며 코어 로그, 노드 매개변수 또는 포트 충돌을 확인해야 합니다. 후자는 시스템 프록시 상태와 브라우저의 독립 프록시 설정을 확인해야 합니다.

systemd 사용자 서비스로 로그인 시 자동 실행

v2rayN은 데스크톱 프로그램이므로 자동 실행은 시스템 수준의 root 서비스가 아니라 현재 계정의 그래픽 로그인 세션에 연결해야 합니다. systemd 사용자 서비스는 계정 로그인 후 실행되며 설정 파일은 ~/.config/systemd/user/에 있습니다. 활성화와 로그 확인에도 sudo가 필요하지 않습니다. 또한 다른 계정에서 같은 설정이 자동으로 실행되지 않습니다.

먼저 command -v v2rayN이 경로를 반환하는지 확인한 다음 사용자 서비스를 만듭니다. 아래에서는 /usr/bin/env v2rayN을 사용해 사용자 서비스 환경에서 프로그램을 찾고, 그래픽 세션 초기화 시간을 확보하도록 3초간 기다립니다. Restart=on-failure는 비정상 종료 때만 다시 시작하며, 창을 정상적으로 닫았을 때는 계속 실행하지 않습니다.

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/v2rayn.service <<'EOF'
[Unit]
Description=v2rayN desktop client
After=graphical-session.target
Wants=graphical-session.target

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

[Install]
WantedBy=default.target
EOF

서비스 파일을 작성한 뒤 사용자 설정을 다시 불러오고 즉시 활성화합니다. enable --now는 ‘다음 로그인 시 자동 실행’과 ‘현재 세션에서 즉시 실행’을 동시에 수행합니다. v2rayN을 이미 수동으로 실행 중이라면 먼저 기존 프로세스를 종료해 동일한 설정 디렉터리나 로컬 포트를 두 인스턴스가 동시에 사용하지 않도록 하세요.

systemctl --user daemon-reload
systemctl --user enable --now v2rayn.service
systemctl --user status v2rayn.service --no-pager

설정을 완료한 뒤 현재 계정에서 로그아웃했다가 다시 로그인하고 최소 3초 기다린 다음 상태를 확인합니다. 서비스 상태가 active (running)이고 v2rayN 창이나 트레이 항목이 나타나면 로그인 자동 실행 과정이 정상적으로 연결된 것입니다. 사용자 서비스는 그래픽 데스크톱에 로그인하기 전에는 표시 가능한 창을 미리 만들지 않으며, 이는 데스크톱 애플리케이션의 정상적인 실행 조건입니다.

systemctl --user is-enabled v2rayn.service
systemctl --user is-active v2rayn.service
journalctl --user -u v2rayn.service -b --no-pager -n 80

문제 원인 확인 및 되돌리기

문제를 해결할 때는 먼저 설치, 프로그램 경로, 코어 연결, 자동 실행 중 어느 단계의 문제인지 구분하세요. 클라이언트를 동시에 재설치하고 설정을 삭제하며 systemd 서비스까지 수정하면 원래 오류가 덮어써질 수 있습니다. 가장 효과적인 순서는 패키지 관리자 기록 확인, 수동 실행, 포트 점검, 사용자 서비스 로그 확인입니다.

서비스를 다시 확인해야 한다면 먼저 systemctl --user reset-failed v2rayn.service로 이전 실패 상태를 지운 다음 수동으로 한 번 시작하세요. 로그의 첫 번째 오류가 이후 반복되는 재시작 메시지보다 대개 더 중요하므로 상태 페이지의 마지막 한 줄만 보지 말고 이번 시작 전후 80줄을 우선 확인해야 합니다.

systemctl --user reset-failed v2rayn.service
systemctl --user restart v2rayn.service
journalctl --user -u v2rayn.service -b --no-pager -n 80