v2rayN Linux 설치 가이드: deb/rpm 패키지 설치, 데스크톱 아이콘 및 부팅 시 자동 실행 설정

설치 전 시스템 아키텍처와 데스크톱 세션 확인

먼저 터미널에서 프로세서 아키텍처를 확인하세요. 배포판 이름만 보고 패키지를 선택하면 안 됩니다. 일반적인 데스크톱 PC는 x86_64를 출력하며 다운로드 페이지의 64비트 또는 x64 패키지에 해당합니다. 일부 ARM 장치는 aarch64를 출력하므로 arm64 패키지를 선택해야 합니다. 두 패키지는 함께 사용할 수 없으며, 아키텍처를 잘못 고르면 보통 “패키지 아키텍처가 일치하지 않음” 또는 “바이너리 파일을 실행할 수 없음” 오류가 바로 발생합니다.

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

/etc/os-release는 패키지 체계를 확인하는 데 사용합니다. Ubuntu, Debian, Linux Mint 등은 deb를 우선 사용하고, Fedora, Rocky Linux, openSUSE 등 rpm 계열 배포판은 rpm을 사용합니다. 데스크톱 세션은 트레이와 자동 시작 동작에도 영향을 줍니다. GNOME, KDE Plasma, Xfce의 상태 영역 구현은 완전히 같지 않습니다.

이 글의 명령은 64비트 테스트 환경을 기준으로 합니다: Ubuntu 24.04·GNOME·Wayland 및 Fedora 42·KDE Plasma·Wayland입니다. 버전에 따라 설치 패키지 파일명이 달라질 수 있으므로 설치 명령을 실행하기 전에 ls -lh ~/Downloads로 실제 파일명을 확인하세요.

Ubuntu 및 Debian에 deb 패키지 설치

이 사이트의 클라이언트 페이지에서 Linux 플랫폼을 선택하고 아키텍처에 맞는 v2rayN deb 패키지를 다운로드하세요. 다운로드 후 파일 형식을 확인한 다음 APT로 로컬 패키지를 설치합니다. 하위 수준의 압축 해제 명령을 직접 실행하지 말고 apt install을 사용하면 패키지 관리자가 저장소에서 이용 가능한 의존성까지 함께 해결합니다.

1. 아키텍처 확인

   uname -m을 실행합니다. x86_64가 출력되면 64비트 패키지를, aarch64가 출력되면 arm64 패키지를 선택하세요.

2. 설치 패키지 받기

   클라이언트 페이지의 Linux 탭을 열고 deb 파일을 다운로드해 현재 사용자의 Downloads 디렉터리에 저장하세요.

3. 패키지 설치

   다운로드 디렉터리에서 로컬 설치 명령을 실행합니다. APT가 패키지 정보를 읽고 설정된 소프트웨어 저장소에서 필요한 의존성을 보충합니다.

4. 코어 선택

   실행 후 「설정」→「매개변수 설정」→「Core 유형」을 열고 Xray를 선택한 다음 저장하고 코어를 재시작하세요.

5. 프록시 확인

   구독을 가져와 노드를 선택하고 시스템 프록시를 켠 뒤 로컬 수신 포트와 코어 로그가 정상인지 확인하세요.

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

arm64 패키지를 다운로드했다면 명령의 파일명을 터미널에 표시된 arm64 파일명으로 바꾸세요. 파일명은 대소문자를 구분하며 로컬 경로 앞의 ./도 생략할 수 없습니다. 설치가 끝나면 애플리케이션 메뉴에서 v2rayN을 검색하거나 command -v v2rayN을 실행해 실행 파일을 찾을 수 있습니다.

충족되지 않은 의존성이 나타나면 먼저 시스템 소프트웨어 저장소를 업데이트한 뒤 복구 설치를 실행하세요. 패키지를 계속 더블클릭하지 마세요. 그래픽 소프트웨어 센터는 “설치 실패”만 표시하고 어떤 라이브러리가 없는지는 알려주지 않을 수 있습니다.

sudo apt --fix-broken install
sudo apt install ./v2rayN-linux-64.deb
apt-cache policy libicu-dev

터미널에 특정 런타임 라이브러리가 없다고 명확히 표시되면 오류 메시지의 패키지명을 기준으로 현재 배포판 저장소에서 설치하세요. 다른 배포판의 공유 라이브러리 하나를 복사하면 버전 의존성이 어긋날 수 있으므로 장기적인 해결 방법으로 적합하지 않습니다.

Fedora 및 rpm 계열 배포판에 rpm 패키지 설치

Fedora에서는 DNF로 로컬 rpm 패키지를 설치합니다. DNF가 아키텍처, 서명 메타데이터, 의존성을 확인하고 설치 기록을 시스템 패키지 데이터베이스에 등록합니다. 명령의 ./는 현재 디렉터리의 로컬 파일을 뜻합니다.

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

최신 DNF 명령 구현이 활성화된 시스템에서도 설치 문법은 동일합니다. 새 버전으로 업그레이드할 때는 새로 다운로드한 rpm 파일에 로컬 설치 명령을 다시 실행하면 됩니다. 패키지 관리자가 버전 번호에 따라 기존 버전을 교체하며, 사용자 설정은 보통 홈 디렉터리에 그대로 보존됩니다.

설치 후 다음 명령으로 패키지 기록과 프로그램 실행 경로를 확인할 수 있습니다. rpm -qa에서 패키지가 검색되지만 command -v에 아무것도 출력되지 않으면 rpm -ql로 패키지가 실제로 설치한 파일을 확인하세요.

rpm -qa | grep -i v2rayn
command -v v2rayN
rpm -ql v2rayN | grep -E '/bin/|applications'

첫 실행, 코어 및 프록시 포트 설정

처음 실행한 뒤 먼저 코어를 확인하고 시스템 프록시는 바로 켜지 마세요. 「설정」→「매개변수 설정」→「Core 유형」에서 구독 노드에 필요한 Xray 코어를 선택한 후 저장하고 코어를 한 번 재시작하세요. VLESS, VMess 등의 노드 매개변수는 일반적으로 구독에서 가져옵니다. 전송 방식, 보안 또는 서버 주소를 임의로 수정하면 연결에 실패할 수 있습니다.

다음으로 「구독 그룹」에서 구독 주소를 추가하고 구독을 업데이트한 뒤 노드를 하나 선택하세요. 기본 연결성을 테스트하려면 먼저 메인 화면의 지연 시간 테스트를 실행한 다음 실행 로그를 확인하면 됩니다. 지연 시간 결과가 표시된다는 것은 탐색 과정이 완료되었다는 뜻일 뿐이며, 웹페이지 접속 여부는 시스템 프록시, DNS 및 라우팅 설정에도 좌우됩니다.

시스템 프록시를 켠 뒤 ss로 로컬 수신 상태를 확인하세요. 아래 명령은 일반적인 포트 10808만 확인합니다. 매개변수 설정에서 다른 포트를 사용한다면 조회 조건도 그에 맞게 바꾸세요.

ss -lntp | grep 10808
curl --proxy http://127.0.0.1:10808 https://example.com/ -I

ss에 결과가 없으면 먼저 v2rayN 로그에서 코어 시작 오류를 확인하세요. 흔한 원인은 포트 점유, 실행할 수 없는 코어 경로, 설정 생성 실패 또는 불완전한 노드 정보입니다. 수신은 정상인데 브라우저가 계속 직접 연결된다면 데스크톱 시스템의 네트워크 프록시가 v2rayN이 제공하는 로컬 주소로 전환되었는지 확인하세요.

• 이 컴퓨터에서만 사용할 때는 수신 주소를 127.0.0.1로 유지해 프록시 포트가 LAN에 노출되지 않도록 하세요.
• 포트를 변경하면 시스템 프록시 설정도 함께 업데이트하세요. 이전 포트는 자동으로 따라 바뀌지 않습니다.
• 노드를 바꾼 뒤 로그에 새로운 아웃바운드 연결이 나타나는지 확인하세요. 화면에서 선택된 상태만 보아서는 안 됩니다.
• 라우팅이 필요하다면 먼저 기본 제공 규칙을 사용한 뒤 도메인 또는 IP 규칙을 하나씩 추가하세요.

데스크톱 아이콘 및 트레이 아이콘 문제 해결

패키지 설치가 끝났는데 애플리케이션 메뉴에 아이콘이 없다면 먼저 데스크톱 실행 항목 파일이 존재하는지 확인하세요. 표준 실행 항목은 보통 /usr/share/applications에 있습니다. 현재 사용자도 ~/.local/share/applications에 자신의 실행 항목을 둘 수 있습니다. 데스크톱 데이터베이스가 아직 갱신되지 않았다면 반복해서 재설치하는 것보다 로그아웃 후 다시 로그인하는 편이 보통 더 빠릅니다.

find /usr/share/applications ~/.local/share/applications \
  -iname '*v2rayn*.desktop' 2>/dev/null
update-desktop-database ~/.local/share/applications 2>/dev/null || true

패키지가 사용할 수 있는 실행 항목을 만들지 않았다면 사용자 수준 데스크톱 파일을 생성할 수 있습니다. 실행 전에 command -v v2rayN으로 실행 경로를 확인하세요. 결과가 /usr/bin/v2rayN이 아니라면 파일에는 터미널에 실제로 반환된 경로를 사용해야 합니다.

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

트레이 문제는 보통 코어 실행을 막지 않습니다. 먼저 pgrep -af v2rayN과 ss -lntp로 프로세스와 포트가 정상인지 확인한 뒤 데스크톱 상태 영역을 별도로 수정하세요. 이렇게 하면 “인터페이스 실행 항목이 없음”과 “프록시 코어가 시작되지 않음”을 구분할 수 있습니다.

데스크톱 자동 시작 또는 systemd 사용자 서비스 설정

Linux 데스크톱에서는 일반적으로 두 가지 자동 시작 방식을 사용합니다. XDG 데스크톱 자동 시작은 그래픽 세션을 따라 실행되며 Wayland, DBus 및 트레이에 필요한 환경을 바로 전달하므로 대부분의 사용자에게 적합합니다. systemd 사용자 서비스는 재시작 정책과 로그 조회를 제공해 프로세스 상태를 명확히 관리해야 하는 환경에 적합합니다.

XDG 데스크톱 자동 시작

앞에서 ~/.local/share/applications/v2rayN.desktop을 만들었다면 현재 사용자의 autostart 디렉터리에 복사하면 됩니다. 로그인 후 데스크톱 환경이 이 파일을 읽고 프로그램을 시작합니다.

mkdir -p ~/.config/autostart
cp ~/.local/share/applications/v2rayN.desktop \
  ~/.config/autostart/v2rayN.desktop

시스템 패키지에 포함된 데스크톱 파일을 사용한다면 먼저 find로 실제 파일명을 찾은 뒤 autostart 디렉터리에 복사하세요. 취소할 때는 사용자 디렉터리의 자동 시작 복사본만 삭제하면 되며 v2rayN을 제거할 필요는 없습니다.

rm ~/.config/autostart/v2rayN.desktop

systemd 사용자 서비스

서비스를 만들기 전에 XDG 자동 시작을 비활성화해 두 프로세스가 10808 등의 로컬 포트를 동시에 점유하지 않도록 하세요. 서비스 파일은 현재 사용자 디렉터리에 두고 sudo systemctl enable을 사용하지 마세요. 그렇지 않으면 시스템 수준 서비스로 잘못 설정됩니다.

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

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

[Install]
WantedBy=graphical-session.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now v2rayn.service

command -v v2rayN이 다른 경로를 반환하면 ExecStart도 함께 수정해야 합니다. Wayland 또는 DBus 환경이 사용자 서비스에 상속되지 않으면 프로그램은 실행되어도 창과 트레이 아이콘이 나타나지 않을 수 있습니다. 데스크톱에 로그인한 뒤 세션 변수를 먼저 가져오고 서비스를 재시작하세요.

systemctl --user import-environment \
  DISPLAY WAYLAND_DISPLAY XAUTHORITY DBUS_SESSION_BUS_ADDRESS
systemctl --user restart v2rayn.service
systemctl --user status v2rayn.service
journalctl --user -u v2rayn.service -n 80 --no-pager

실행 실패, 포트 점유 및 제거 문제 해결

프로그램이 시작되지 않으면 터미널에서 직접 실행하고 전체 오류 출력을 보존하세요. 데스크톱 아이콘을 더블클릭했을 때의 오류는 창이 닫히면 사라지는 경우가 많지만, 터미널 출력으로 공유 라이브러리, 권한, 코어 파일 및 그래픽 세션 문제를 구분할 수 있습니다.

command -v v2rayN
v2rayN
pgrep -af 'v2rayN|xray'
ss -lntp | grep -E '10808|10809'

로그에 주소가 이미 사용 중이라고 표시되면 먼저 ss 출력에서 해당 포트를 점유한 프로세스를 찾으세요. 흔한 원인은 이전 버전 v2rayN, 자동 시작 서비스와 수동 실행이 동시에 작동하는 경우입니다. 불필요한 인스턴스를 중지한 뒤 코어를 다시 시작하고, 용도를 확인하지 못한 시스템 프로세스는 함부로 종료하지 마세요.

• 데스크톱 자동 시작과 systemd 서비스 중 하나만 선택해 중복 실행을 피하세요.
• 로컬 프록시 포트를 변경한 뒤에는 브라우저와 데스크톱 시스템 프록시가 같은 포트를 사용해야 합니다.
• 코어 시작에 실패하면 「설정」→「매개변수 설정」→「Core 유형」으로 이동해 Xray를 다시 확인하세요.
• 구독 업데이트에 실패하면 먼저 네트워크와 구독 주소를 확인한 뒤 프록시를 통한 업데이트를 활성화할지 결정하세요.
• 업그레이드 후 문제가 생기면 먼저 프로그램을 종료하고 설정을 백업한 다음 현재 아키텍처에 맞는 패키지를 다시 설치하세요.

제거할 때는 해당 배포판의 패키지 관리자를 사용하세요. 패키지를 제거해도 사용자 설정까지 자동으로 삭제되지는 않습니다. 새 설정으로 다시 테스트하려면 먼저 홈 디렉터리의 v2rayN 설정을 백업한 뒤 실제 경로에 맞게 처리하세요. 구독과 사용자 지정 라우팅 규칙을 백업하지 않은 상태에서 사용자 디렉터리를 바로 정리하지 마세요.

# Ubuntu 또는 Debian
sudo apt remove v2rayn

# Fedora 또는 유사한 rpm 계열 배포판
sudo dnf remove v2rayN

# 사용자 서비스 비활성화
systemctl --user disable --now v2rayn.service
rm ~/.config/systemd/user/v2rayn.service
systemctl --user daemon-reload

패키지 이름의 대소문자와 실제 등록 이름이 다를 수 있습니다. 제거 명령에서 패키지를 찾지 못하면 deb 계열은 dpkg -l | grep -i v2ray, rpm 계열은 rpm -qa | grep -i v2ray를 실행한 뒤 조회 결과의 정확한 이름을 사용하세요.