v2rayN Linux 데스크톱 설치: deb/rpm 패키지 설치 및 로그인 시 자동 실행

1. 배포판·아키텍처·설치 방식 확인

Ubuntu와 Debian에서는 보통 deb 패키지를, Fedora에서는 rpm 패키지를 사용합니다. 패키지 형식과 프로세서 아키텍처는 별도로 확인해야 합니다. deb 패키지도 x86_64용과 ARM64용이 나뉠 수 있습니다. 먼저 아래 명령을 실행한 다음 설치 패키지 페이지에서 Linux용 파일을 선택하세요. 이 글에서는 버전을 고정하지 않으며, 실제로 사용할 수 있는 패키지는 다운로드 페이지를 기준으로 합니다.

cat /etc/os-release
uname -m

x86_64는 보통 다운로드 항목에서 x64 또는 amd64에 해당하고, aarch64는 보통 arm64에 해당합니다. 파일 이름을 바꿔 다른 아키텍처용 패키지를 설치하려고 하지 마세요. 이 안내를 따라 하려면 그래픽 데스크톱과 일반 사용자 계정이 필요합니다. SSH만 사용할 수 있는 서버 환경에는 데스크톱 자동 실행 설정을 그대로 적용하기 어렵습니다.

2. Ubuntu·Debian에 deb 패키지 설치

다운로드한 deb 파일을 전용 디렉터리에 넣으세요. 해당 디렉터리에는 설치할 deb 파일 하나만 있어야 합니다. 파일 관리자에서 ‘터미널에서 열기’를 선택한 뒤 아래 명령을 실행합니다. Bash에서 사용할 수 있으며, 다운로드 파일 이름 규칙에 의존하지 않고 패키지 메타데이터에서 실제 패키지 이름을 확인합니다.

# 현재 디렉터리에는 설치할 deb 파일 하나만 있어야 합니다
set -- ./*.deb
if [ "$#" -eq 1 ] && [ -f "$1" ]; then
  pkg=$(dpkg-deb -f "$1" Package)
  dpkg-deb -f "$1" Package Version Architecture
  sudo apt update
  sudo apt install "$1"
else
  printf '%s\n' '설치할 deb 파일 하나만 있는 디렉터리에서 실행하세요.'
fi

sudo apt install ./文件名.deb에서 상대 경로는 중요합니다. apt에 저장소의 패키지명이 아니라 로컬 파일임을 알려 주기 때문입니다. apt는 설정된 저장소에서 명시된 의존성을 충족하려고 합니다. “의존성을 충족할 수 없음”이라는 메시지가 나오면 배포판 버전, 패키지 아키텍처, 저장소 상태를 먼저 확인하고, 의존성 검사를 강제로 건너뛰는 옵션은 사용하지 마세요.

1. 패키지 정보 확인

   위 출력에서 Package, Version, Architecture 항목을 확인해 이번에 다운로드한 패키지인지, 아키텍처가 맞는지 점검하세요. Package 값을 기록해 두면 이후 조회하거나 제거할 때 사용할 수 있습니다.

2. 설치 완료

   apt의 작업 요약을 확인하고 설치가 끝날 때까지 기다리세요. apt update가 실패하면 저장소 또는 네트워크 오류를 먼저 해결한 뒤 설치를 진행합니다.

3. 실행 항목 찾기

   같은 터미널에서 아래 조회 명령을 실행해 패키지에 포함된 데스크톱 항목과 실행 파일을 찾으세요. 프로그램이 특정 경로에 설치된다고 미리 단정하지 마세요.

4. 처음 실행하기

   데스크톱 앱 메뉴에서 v2rayN을 검색해 일반 사용자 계정으로 실행하세요. 설치에 관리자 권한이 필요하더라도 평소 실행까지 sudo를 사용해야 하는 것은 아닙니다.

# 앞 단계에서 가져온 pkg 변수를 계속 사용합니다
dpkg -L "$pkg" | grep -E '/applications/.*\.desktop$|/bin/'

3. Fedora에 rpm 패키지 설치 및 의존성 확인

Fedora에서는 dnf로 로컬 rpm 패키지를 설치합니다. deb 설치와 마찬가지로 설치할 rpm 파일 하나만 별도 디렉터리에 넣고, 해당 디렉터리에서 Bash 터미널을 여세요. 잘못된 파일을 고르지 않도록 여러 버전이나 아키텍처의 rpm을 한곳에 함께 두지 마세요.

# 현재 디렉터리에는 설치할 rpm 파일 하나만 있어야 합니다
set -- ./*.rpm
if [ "$#" -eq 1 ] && [ -f "$1" ]; then
  pkg=$(rpm -qp --queryformat '%{NAME}' "$1")
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$1"
  sudo dnf install "$1"
else
  printf '%s\n' '설치할 rpm 파일 하나만 있는 디렉터리에서 실행하세요.'
fi

# 설치가 끝나면 같은 터미널에서 실행 항목을 확인합니다
rpm -ql "$pkg" | grep -E '/applications/.*\.desktop$|/bin/'

설치는 성공했지만 클릭해도 창이 열리지 않으면 패키지에 포함된 .desktop 파일의 Exec= 행을 확인한 뒤, 터미널에서 실제 프로그램 경로를 실행해 오류 출력을 살펴보세요. 해당 행에 %U, %F 같은 데스크톱 항목 필드 코드가 있으면 터미널에서 직접 테스트할 때 그대로 전달하지 마세요.

• 공유 라이브러리 누락 오류가 표시되는 경우: 오류에 나온 라이브러리 이름을 정확히 기록하세요. Fedora에서는 dnf provides '*/libX11.so.6'와 같은 조회 명령으로 제공 패키지를 찾을 수 있습니다. 예시 라이브러리 이름은 실제 오류 항목으로 바꿔야 합니다.
• ICU 또는 런타임 오류가 표시되는 경우: 패키지에 런타임이 포함되어 있는지 먼저 확인한 다음, 해당 배포판의 지원 범위를 점검하세요. 배포판마다 ICU 패키지 이름과 버전이 다르므로 오래된 의존성을 무작정 설치하지 마세요.
• 디스플레이 서비스에 연결할 수 없다는 오류가 표시되는 경우: 일반 SSH 세션이나 시스템 부팅 작업이 아니라, 로그인된 그래픽 세션에서 실행하고 있는지 확인하세요.
• 창은 열리지만 트레이 아이콘이 보이지 않는 경우: 데스크톱 환경의 트레이 지원 여부를 먼저 확인하세요. 트레이 아이콘이 없다고 프로그램 설치가 실패했거나 프록시 코어가 종료된 것은 아닙니다.

데스크톱 프로그램이 정상적으로 실행된 뒤 네트워크 설정을 진행하세요. 시작 오류 하나를 없애려고 SELinux를 끄거나 설치 디렉터리 전체의 권한을 완화하거나, 클라이언트를 계속 root로 실행하지 마세요.

4. 데스크톱 메뉴 등록 및 프록시 설정 확인

deb/rpm 패키지에는 보통 앱 메뉴 항목이 포함되어 있습니다. 패키지에 있는 .desktop 파일을 우선 사용하세요. 이 파일에는 올바른 실행 경로, 작업 디렉터리 또는 실행 인수가 설정되어 있습니다. 앱 메뉴에 항목이 보이지 않으면 먼저 로그아웃한 뒤 다시 로그인해 보세요. 패키지에 메뉴 항목이 없을 때만 직접 만드는 방법을 고려하세요.

직접 메뉴 항목을 만들려면 텍스트 편집기로 위 항목을 입력해 ~/.local/share/applications/v2rayN.desktop에 저장하세요. Exec이 가리키는 파일을 실제로 실행할 수 있는지 먼저 확인해야 합니다. 경로에 공백이 있으면 데스크톱 항목 규격에 따라 큰따옴표로 묶으세요. 다운로드 디렉터리에서 임시로 압축을 푼 경로를 계속 사용할 실행 경로로 지정하지 마세요.

1. 메인 화면에서 ‘구독 그룹’ → ‘구독 그룹 설정’을 열고 서비스 제공자가 안내한 구독 주소를 추가한 뒤 저장하세요. 버전에 따라 메뉴 이름이 조금 다를 수 있습니다.
2. ‘구독 그룹’ 메뉴로 돌아가 ‘모든 구독 업데이트’를 실행하세요. 노드가 표시되면 하나를 선택해 활성 서버로 지정합니다.
3. ‘설정’ → ‘매개변수 설정’에서 로컬 리스닝 포트와 인바운드 프로토콜을 확인하세요. 처음 테스트할 때는 일반 로컬 프록시를 유지하고 TUN은 사용하지 마세요.
4. 실행 로그에서 코어가 정상적으로 시작됐는지 확인한 다음, 명시적 프록시와 데스크톱 시스템 프록시를 각각 테스트하세요. 두 종류의 문제를 한꺼번에 진단하지 않는 것이 좋습니다.

# 이 포트에서 실제로 클라이언트가 리스닝 중인지 먼저 확인합니다
ss -lntp | grep ':10808'

# 해당 인바운드가 SOCKS를 지원하는 경우에만 사용합니다
curl --proxy socks5h://127.0.0.1:10808 --connect-timeout 10 -I https://example.com/

socks5h는 대상 도메인의 이름 확인을 프록시 측에 맡깁니다. 이 명령으로 현재 SOCKS 인바운드와 노드 연결을 확인할 수 있습니다. 로컬에서 HTTP 인바운드만 사용하는 경우 실제 HTTP 포트와 http://127.0.0.1:포트를 사용하세요. 명시적 프록시 테스트에 성공해도 해당 접속 경로를 사용할 수 있다는 뜻일 뿐, 모든 데스크톱 앱이 시스템 프록시를 자동으로 따른다는 의미는 아닙니다.

5. 로그인 후 자동 실행 설정

Linux 데스크톱 클라이언트는 사용자의 그래픽 세션이 필요합니다. 관리하기 쉬운 방법은 데스크톱 환경의 ‘시작 프로그램’ 설정을 이용하거나, 검증된 데스크톱 항목을 ~/.config/autostart/에 복사하는 것입니다. 둘 중 하나만 선택하세요. 클라이언트 자체 자동 실행 옵션과 별도의 사용자 서비스를 함께 추가하지 마세요.

아래는 Debian/Ubuntu 기준입니다. 설치 단계에서 사용한 pkg 변수를 계속 사용합니다. 터미널을 닫았다면 패키지 관리자에서 실제 패키지 이름을 조회한 후 변수에 다시 지정하세요. 먼저 메뉴 항목 목록을 확인하고 대상 데스크톱 파일이 하나뿐인지 점검한 뒤 복사하세요. 여러 후보 중 첫 번째 항목을 임의로 고르지 마세요.

dpkg -L "$pkg" | grep -E '/applications/.*\.desktop$'

조회한 데스크톱 파일을 텍스트 편집기로 열고 Exec=을 확인하세요. Hidden=true가 있거나 현재 데스크톱을 제외하는 OnlyShowIn= 설정이 없는지도 확인합니다. 이후 실제 파일을 자동 시작 디렉터리에 복사하세요. 아래 대화형 명령을 사용해 전체 경로를 붙여 넣어도 됩니다.

read -r -p "확인된 .desktop 파일의 절대 경로를 입력하세요: " desktop
if [ -f "$desktop" ]; then
  mkdir -p "$HOME/.config/autostart"
  cp -- "$desktop" "$HOME/.config/autostart/v2rayN.desktop"
else
  printf '%s\n' '파일을 찾을 수 없습니다. 경로를 다시 확인하세요.'
fi

Fedora에서는 조회 명령을 rpm -ql "$pkg"로 바꾸고, 이후 확인과 복사 방법은 동일하게 진행하면 됩니다. v2rayN을 정상 종료한 뒤 로그아웃하고 다시 로그인해 인스턴스가 하나만 실행되는지 확인하세요. 데스크톱 트레이를 사용할 수 없다면 첫 테스트에서는 ‘시작 시 최소화’를 켜지 마세요. 프로그램이 실행되지 않은 것으로 착각할 수 있습니다.

6. 자동 실행은 되지만 프록시가 작동하지 않을 때

‘프로그램이 실행됨’과 ‘앱이 프록시를 사용함’은 서로 다른 결과입니다. 데스크톱에 로그인한 직후에는 네트워크 연결이 아직 완료되지 않았거나 구독 업데이트가 실패할 수 있습니다. 그렇다고 바로 소프트웨어를 다시 설치할 필요는 없습니다. 아래 순서대로 문제 지점을 좁혀 보세요.

• 프로세스나 창이 없음: 데스크톱 항목의 실제 Exec 명령을 직접 실행해 업그레이드 후 경로가 바뀌지 않았는지 확인하세요. 데스크톱 설정에서 자동 실행 항목이 비활성화되지 않았는지도 점검합니다.
• 창은 정상적으로 열리지만 포트가 리스닝하지 않음: 실행 로그에서 코어 시작 오류를 확인하고, 활성 노드와 포트 충돌 여부, 코어 파일의 실행 가능 여부를 점검하세요.
• curl의 명시적 프록시 연결 실패: 먼저 프로토콜과 포트를 확인한 다음 노드 연결, 시스템 시간, 서비스 제공자의 요구 사항을 점검하세요. VMess 등의 연결은 시간 오차로 인증에 실패할 수 있습니다.
• curl은 성공하지만 브라우저는 실패: 브라우저 자체의 프록시 설정과 확장 기능을 확인한 다음 데스크톱의 ‘설정’ → ‘네트워크’ → ‘네트워크 프록시’를 점검하세요. 메뉴 위치는 데스크톱 환경에 따라 다릅니다.
• 브라우저는 되지만 터미널은 실패: 터미널 도구에 환경 변수나 자체 프록시 인수가 필요할 수 있습니다. 데스크톱 시스템 프록시가 모든 명령줄 프로그램에 자동으로 적용되지는 않습니다.
• 프로그램이 두 번 실행됨: 데스크톱 자동 실행 목록, 클라이언트 자체 설정, 직접 만든 사용자 서비스를 하나씩 확인하고 한 가지 방식만 남기세요.

Linux의 시스템 프록시는 보통 데스크톱 환경에서 제공하는 설정 인터페이스이며, 모든 트래픽을 강제로 가로채는 기능은 아닙니다. 라우팅 규칙은 트래픽이 코어에 들어온 뒤 프록시로 보낼지 직접 연결할지 결정합니다. 두 기능은 서로 다른 단계에서 작동합니다. 기본 연결을 확인한 뒤 TUN을 설정하면 권한, DNS, 라우팅 문제가 동시에 발생할 가능성을 줄일 수 있습니다. 추가 진단은 문제 해결 안내를 참고하세요.

7. 업그레이드·자동 실행 해제·삭제

업그레이드하기 전에 클라이언트를 종료하고 현재 설치된 패키지 이름을 기록한 뒤, 클라이언트가 실제로 사용하는 사용자 설정 디렉터리를 백업하세요. 프로그램에서 제공하는 디렉터리 메뉴나 실행 로그를 통해 위치를 확인할 수 있습니다. 모든 버전이 같은 디렉터리에 데이터를 저장한다고 가정하지 마세요. 설정에는 구독 인증 정보가 포함될 수 있으므로 현재 사용자만 접근할 수 있는 위치에 백업하세요.

1. 같은 아키텍처용 새 패키지를 다운로드한 다음 apt install ./파일명.deb 또는 dnf install ./파일명.rpm으로 업그레이드하세요.
2. 한 번 직접 실행해 구독, 활성 노드, 로컬 포트를 확인한 뒤 자동 실행 항목의 Exec 경로도 여전히 유효한지 점검하세요.
3. 설치 방식이나 프로그램 디렉터리를 바꿨다면 데스크톱 항목을 새로 만드세요. 이전 디렉터리 경로를 계속 사용하지 마세요.

# 이 글에서 만든 로그인 자동 실행만 해제하며 프로그램은 제거하지 않습니다
rm -f "$HOME/.config/autostart/v2rayN.desktop"

# 제거 방법은 둘 중 하나를 선택합니다. pkg에는 확인된 실제 패키지 이름을 지정하세요
# Debian / Ubuntu:
sudo apt remove "$pkg"

# Fedora:
sudo dnf remove "$pkg"

제거하기 전에 데스크톱 네트워크 프록시 설정을 원래대로 돌리고 프로그램을 종료하세요. 프로그램이 더는 리스닝하지 않는 로컬 포트를 시스템이 계속 가리키는 상황을 방지할 수 있습니다. 패키지를 제거해도 사용자 디렉터리의 설정이 모두 자동 삭제되지는 않습니다. 정리하려면 디렉터리 내용과 백업 범위를 먼저 확인하세요. 이 과정을 따르면 설치부터 데스크톱 실행, 프록시 확인, 로그인 시 자동 실행까지 반복해서 점검할 수 있습니다.