v2rayN Linux 데스크톱 설치: deb/rpm 패키지 설치와 로그인 시 자동 시작 설정

설치 패키지와 시스템 아키텍처 확인

Linux 설치의 첫 단계는 파일을 바로 더블클릭하는 것이 아니라 배포판의 패키지 형식과 프로세서 아키텍처를 확인하는 것입니다. Ubuntu, Debian, Linux Mint 등 Debian 계열 배포판은 deb 패키지를 사용하고, Fedora, Rocky Linux 등 RPM 계열 배포판은 rpm 패키지를 사용합니다. 패키지 형식을 잘못 선택하면 그래픽 소프트웨어 센터에 설치할 수 없거나 지원되지 않는 형식이라는 안내가 표시됩니다.

프로세서 아키텍처도 반드시 일치해야 합니다. 일반적인 데스크톱 컴퓨터에서 uname -m을 실행하면 보통 x86_64가 반환되며, 다운로드 항목의 x64 또는 64에 해당합니다. 일부 ARM 데스크톱 장치는 aarch64를 반환하며 arm64를 선택해야 합니다. 시스템 이름만 보고 아키텍처를 추측하지 말고, Android 설치 패키지를 Linux 데스크톱에 사용하지 마세요.

cat /etc/os-release를 실행해 배포판 이름과 버전도 확인할 수 있습니다. 여러 호스트에 원격으로 연결할 때는 데스크톱 외관에 의존하는 것보다 이 명령이 더 정확합니다. v2rayN은 데스크톱 클라이언트이므로, 이 글의 자동 시작 설정도 그래픽 세션에 로그인한 일반 사용자를 기준으로 합니다. 그래픽 프로그램을 root 수준의 시스템 서비스로 설정해서는 안 됩니다.

uname -m
cat /etc/os-release
printf '데스크톱 세션: %s\n' "$XDG_CURRENT_DESKTOP"
printf '세션 유형: %s\n' "$XDG_SESSION_TYPE"

deb 및 rpm 로컬 설치 절차

다운로드가 끝나면 하위 수준의 dpkg -i나 rpm -i를 직접 사용하는 대신 터미널에서 시스템 패키지 관리자로 설치하는 것이 좋습니다. APT와 DNF는 패키지의 의존성 선언을 읽고 현재 활성화된 저장소에서 누락된 공유 라이브러리를 보완합니다. 설치 명령은 패키지가 있는 디렉터리에서 실행해야 하며, 파일 와일드카드가 v2rayN 패키지 하나만 가리키는지 확인하세요.

1. 아키텍처 확인

   uname -m을 실행합니다. x86_64가 반환되면 x64 패키지를, aarch64가 반환되면 arm64 패키지를 선택합니다.

2. 패키지 형식 선택

   Ubuntu와 Debian은 deb를, Fedora는 rpm을 선택합니다. 설치 패키지는 이 사이트의 클라이언트 페이지에서 Linux 플랫폼용으로만 받으세요.

3. 설치 실행

   다운로드 디렉터리에서 sudo apt install ./v2rayN-linux-*.deb를 실행하거나, Fedora에서는 sudo dnf install ./v2rayN-linux-*.rpm을 실행합니다.

4. 프로그램 위치 확인

   command -v v2rayN을 실행해 실제 실행 파일 경로를 기록합니다. 일반적인 결과는 /usr/bin/v2rayN입니다.

5. 첫 실행 완료

   애플리케이션 메뉴에서 v2rayN을 실행한 뒤 「설정」→「매개변수 설정」→「Core 유형」으로 이동해 Xray 코어를 사용하는지 확인하고 저장합니다.

Ubuntu와 Debian에서는 sudo apt install ./v2rayN-linux-*.deb 명령을 권장합니다. 명령의 ./는 현재 디렉터리의 로컬 파일을 설치한다는 뜻입니다. 이 부분이 없으면 APT가 이름을 저장소 패키지로 조회합니다. 이전에 dpkg -i를 사용한 뒤 의존성이 설정되지 않았다면 sudo apt --fix-broken install을 실행해 복구한 다음 로컬 설치 명령을 다시 실행하세요.

Fedora에서는 sudo dnf install ./v2rayN-linux-*.rpm을 사용합니다. DNF 5는 추가로 필요한 패키지, 다운로드 용량과 설치 결과를 표시합니다. 시스템에서 엄격한 저장소 정책을 사용한다면 먼저 sudo dnf makecache를 실행해 메타데이터를 갱신한 뒤 설치를 반복하세요. 의존성을 건너뛰고 rpm 데이터베이스에 강제로 기록하지 마세요.

cd "$HOME/Downloads"

# Ubuntu / Debian
sudo apt update
sudo apt install ./v2rayN-linux-*.deb

# Fedora
sudo dnf makecache
sudo dnf install ./v2rayN-linux-*.rpm

# 설치 후 확인
command -v v2rayN
v2rayN --version

첫 실행, 구독과 코어 포트 대기

프로그램이 정상적으로 열렸다는 것은 그래픽 인터페이스가 실행된다는 뜻일 뿐, 프록시 연결이 구축되었다는 의미는 아닙니다. 완전한 상태에는 최소한 구독 업데이트, 노드 선택, Xray 코어 프로세스 정상 실행, 데스크톱 애플리케이션 트래픽의 로컬 포트 유입이라는 네 가지 항목이 포함됩니다. 초기 설정은 이 순서대로 진행해 시스템 프록시가 켜지기 전에 노드를 사용할 수 없다고 잘못 판단하지 않도록 하세요.

v2rayN 기본 화면에서 구독을 추가한 뒤 먼저 현재 구독 그룹을 업데이트하고 노드를 선택해 시작합니다. VLESS, VMess 등의 프로토콜 매개변수는 보통 구독에서 가져옵니다. 주소, 포트, UUID, 전송 방식 또는 TLS 항목을 직접 수정하면 설정과 서버가 일치하지 않을 수 있습니다. 구독은 설정을 배포할 뿐이며, 클라이언트 자체가 노드 주소를 제공하는 것은 아닙니다.

v2rayN의 일반적인 로컬 SOCKS 수신 포트는 10808, HTTP 수신 포트는 10809입니다. 실제 값은 「설정」→「매개변수 설정」의 로컬 수신 설정을 기준으로 해야 합니다. 기존 설정 이전, 포트 충돌 또는 사용자 변경으로 최종 포트가 달라질 수 있기 때문입니다. ss -lntp를 실행하면 해당 포트가 LISTEN 상태인지 바로 확인할 수 있습니다.

포트가 존재하면 SOCKS와 HTTP 경로를 각각 테스트할 수 있습니다. SOCKS 테스트에는 socks5h를 사용하는 것이 좋습니다. 여기서 h는 도메인 이름 확인도 프록시를 통해 처리한다는 뜻입니다. 테스트 결과 HTTP 응답 헤더가 반환되면 로컬 클라이언트, 선택한 노드와 대상 사이트 사이에 기본 연결이 형성된 것입니다. 브라우저에서만 실패한다면 데스크톱 프록시와 브라우저 프록시 설정을 중점적으로 확인하세요.

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

curl -I --proxy socks5h://127.0.0.1:10808 https://v2rayair.com/
curl -I --proxy http://127.0.0.1:10809 https://v2rayair.com/

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

Linux 데스크톱 프로그램에는 /etc/systemd/system에 시스템 서비스를 작성하는 방식보다 systemd 사용자 서비스가 적합합니다. 사용자 서비스는 데스크톱 계정이 로그인한 뒤 실행되어 사용자 디렉터리, D-Bus 세션과 그래픽 환경 정보를 상속할 수 있습니다. 반면 시스템 서비스는 로그인 화면이 나타나기 전에 시작될 수 있어 그래픽 세션이 없으며, v2rayN 창과 트레이 상태가 정상적으로 생성되지 않을 수 있습니다.

서비스를 만들기 전에 command -v v2rayN을 실행하세요. 아래 예시는 일반적인 경로인 /usr/bin/v2rayN을 사용하므로, 명령이 다른 경로를 반환하면 ExecStart를 반드시 수정해야 합니다. 서비스 파일은 현재 사용자의 ~/.config/systemd/user/에 저장하며, 전체 과정에서 sudo를 사용하지 않습니다.

mkdir -p "$HOME/.config/systemd/user"

cat > "$HOME/.config/systemd/user/v2rayn.service" <<'EOF'
[Unit]
Description=v2rayN Linux 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

Restart=on-failure는 프로세스가 비정상 종료된 경우에만 다시 시작하므로 클라이언트를 정상적으로 종료해도 지속적인 재시작 루프가 발생하지 않습니다. RestartSec=5는 5초의 간격을 두어 설정 오류 시 빠른 반복 실행을 방지합니다. PartOf=graphical-session.target은 그래픽 세션이 끝날 때 서비스도 함께 종료되도록 하며, 창과 트레이 상호작용이 필요한 클라이언트에 적합합니다.

일부 데스크톱 환경은 graphical-session.target을 자동으로 시작하지 않거나, 사용자 관리자가 Wayland, X11과 D-Bus 환경 변수를 제때 받지 못할 수 있습니다. 먼저 환경을 가져온 다음 서비스를 다시 시작하세요. 서비스 상태가 성공으로 표시되지만 화면이 나타나지 않으면 systemctl --user show-environment에 DISPLAY, WAYLAND_DISPLAY와 DBUS_SESSION_BUS_ADDRESS가 있는지 확인할 수 있습니다.

systemctl --user import-environment DISPLAY WAYLAND_DISPLAY XDG_CURRENT_DESKTOP DBUS_SESSION_BUS_ADDRESS
dbus-update-activation-environment --systemd DISPLAY WAYLAND_DISPLAY XDG_CURRENT_DESKTOP DBUS_SESSION_BUS_ADDRESS

systemctl --user restart v2rayn.service
systemctl --user status v2rayn.service
journalctl --user -u v2rayn.service -b --no-pager

• Loaded가 loaded인 경우: systemd가 서비스 파일을 읽었으며, 문법과 경로를 최소한 해석할 수 있다는 뜻입니다.
• Active가 active (running)인 경우: v2rayN 기본 프로세스가 실행 중이라는 뜻이지만, Xray 코어와 수신 포트도 추가로 확인해야 합니다.
• 상태가 203/EXEC인 경우: ExecStart 경로가 잘못되었거나 파일이 없거나 실행할 수 없는 상태입니다.
• 짧은 시간 동안 반복 재시작되는 경우: 마지막 30줄의 로그를 확인하고 설정 손상, 포트 사용 중 여부와 그래픽 환경 변수를 점검하세요.
• 수동 실행은 정상인데 자동 시작이 실패하는 경우: 로그인한 터미널과 systemd 사용자 관리자의 환경 변수를 중점적으로 비교하세요.

데스크톱 환경에서 graphical-session.target을 사용하지 않는다면 서비스 설치 대상을 default.target으로 바꿀 수 있지만, 그래픽 환경 가져오기는 그대로 유지해야 합니다. 수정 후 systemctl --user disable v2rayn.service를 실행하고 서비스 파일을 편집한 다음 systemctl --user daemon-reload와 systemctl --user enable --now v2rayn.service를 실행하세요. systemd 서비스와 데스크톱 환경 자동 시작 항목을 동시에 설정하지 마세요. 로그인할 때 두 번의 시작 요청이 발생할 수 있습니다.

시스템 프록시 적용과 라우팅 확인

자동 시작이 성공한 뒤에도 ‘클라이언트 시작’과 ‘시스템 프록시가 트래픽을 인계함’은 구분해야 합니다. v2rayN은 시작 후 코어를 실행할 수 있지만, 시스템 프록시 스위치가 자동으로 복원되는지는 클라이언트 매개변수, 데스크톱 환경과 마지막 종료 상태에 따라 달라집니다. 로그인 후 먼저 트레이 상태를 확인하고 「설정」→「매개변수 설정」에서 시작 동작과 시스템 프록시 관련 옵션을 점검하세요.

시스템 프록시는 주로 데스크톱 프록시 설정을 읽는 애플리케이션에 영향을 줍니다. 터미널의 curl, 패키지 관리자와 개발 도구는 데스크톱 설정을 무시하거나 http_proxy, https_proxy와 all_proxy 환경 변수만 읽을 수 있습니다. 따라서 ‘브라우저는 접속되지만 터미널은 연결되지 않음’은 대개 라우팅 규칙이 잘못된 것이 아니라 두 프로그램이 서로 다른 프록시 진입점을 사용하기 때문입니다.

라우팅을 확인할 때는 먼저 v2rayN을 전역 프록시 모드로 전환해 노드와 전송 경로가 정상인지 확인한 다음 규칙 모드로 되돌릴 수 있습니다. 전역 모드는 작동하지만 규칙 모드가 작동하지 않는다면 문제는 도메인, IP, geosite, geoip 또는 아웃바운드 태그 매칭에 있을 가능성이 큽니다. 두 모드 모두 작동하지 않으면 먼저 노드 매개변수, 시간 동기화, DNS와 코어 로그를 확인해야 합니다.

VMess는 시스템 시간 오차에 민감하며, VLESS Reality도 올바른 도메인, 포트, 서버 이름, 지문과 공개 키 매개변수에 의존합니다. timedatectl status를 실행해 System clock synchronized가 yes인지 확인하세요. 시간이 동기화되지 않았다면 시스템 네트워크 시간 서비스를 활성화한 뒤 연결을 다시 테스트합니다.

1. systemctl --user status v2rayn.service를 실행해 데스크톱 클라이언트 프로세스가 실행 중인지 확인합니다.
2. ss -lntp를 실행해 설정된 SOCKS 또는 HTTP 포트가 대기 중인지 확인합니다.
3. 명시적인 curl --proxy 명령으로 로컬 프록시 진입점을 확인하여 데스크톱 환경에 의존하지 않도록 합니다.
4. 데스크톱 네트워크 프록시 페이지를 열어 주소가 127.0.0.1이고 포트가 일치하는지 확인합니다.
5. 전역 모드와 규칙 모드를 각각 테스트해 문제가 기본 연결에 있는지 라우팅 매칭에 있는지 판단합니다.
6. journalctl --user -u v2rayn.service -b를 실행해 이번 부팅 주기의 로그 단서를 보관합니다.

timedatectl status
systemctl --user status v2rayn.service
ss -lntp | grep -E '10808|10809'
journalctl --user -u v2rayn.service -b -n 30 --no-pager

일반적인 설치 및 자동 시작 문제

Linux 데스크톱 배포 중 발생하는 대부분의 문제는 패키지 불일치, 실행 파일 경로 변경, 그래픽 세션 환경 미가져오기, 로컬 포트 사용 중이라는 네 가지 유형으로 나눌 수 있습니다. 설치 계층, 프로세스 계층, 코어 계층, 시스템 프록시 계층을 순서대로 확인하는 편이 반복적인 삭제와 재설치보다 실제 원인을 찾기 쉽습니다.

v2rayN을 업그레이드한 뒤 command -v v2rayN을 다시 실행해 패키지 관리자가 시작 경로를 변경하지 않았는지 확인하세요. 그런 다음 사용자 서비스를 다시 시작하고 로그를 점검합니다. 구독 업데이트에 실패하면 먼저 구독 주소가 완전한지, 시스템 시간이 정확한지, 현재 네트워크에서 구독 서비스에 접속할 수 있는지 확인하세요. 기존 노드를 통해 구독을 업데이트해야 한다면 구독 설정에서 해당 프록시 업데이트 옵션을 활성화합니다.

삭제하기 전에 systemd 사용자 서비스를 만들었다면 먼저 systemctl --user disable --now v2rayn.service를 실행한 다음 ~/.config/systemd/user/v2rayn.service를 삭제하고 사용자 서비스를 다시 불러오세요. 이렇게 하면 패키지를 삭제한 뒤에도 사용자 관리자가 존재하지 않는 실행 파일을 계속 호출하는 일을 방지할 수 있습니다.

systemctl --user disable --now v2rayn.service
rm "$HOME/.config/systemd/user/v2rayn.service"
systemctl --user daemon-reload
systemctl --user reset-failed