Linux 설치 및 자동 실행

먼저 배포판과 아키텍처 확인하기

v2rayN은 노드, 구독 및 코어 프로세스를 관리하는 데스크톱 클라이언트입니다. deb와 rpm은 패키지 형식일 뿐 노드의 프로토콜을 결정하지 않습니다. VMess 또는 VLESS 노드를 사용할 수 있는지는 선택한 코어, 전송 설정 및 서버 구성에 따라 달라집니다. 설치 전에 시스템 환경을 확인하고, 프로토콜 오류를 해결하려고 패키지 형식을 바꾸지 마세요.

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

클라이언트 다운로드 페이지에서 Linux 설치 안내와 시스템 아키텍처에 맞는 패키지를 선택하세요. 버전 번호와 패키지 파일명을 고정하지 않았으므로 업데이트 후 오래된 파일을 가리키는 명령을 실행할 염려가 없습니다. 아래 명령은 Bash 기준입니다. 실행할 때 이미 다운로드한 파일의 실제 경로를 입력하세요. 경로에 공백이 있어도 사용할 수 있지만, 입력값을 따옴표로 감쌀 필요는 없습니다.

패키지 관리자로 deb 또는 rpm 설치하기

로컬 패키지를 설치할 때는 배포판의 패키지 관리자로 의존성을 해결하는 것이 좋습니다. Ubuntu와 Debian에서는 apt install, Fedora에서는 dnf install을 사용합니다. 저장소에 접근할 수 없으면 의존성 해결도 실패할 수 있습니다. 이 경우 의존성을 무시하고 강제로 설치하기보다 먼저 저장소 연결 문제를 해결하세요.

1. 패키지 경로 확인

   파일 관리자에서 다운로드한 파일을 찾아 전체 경로를 복사하세요. 터미널에 경로를 입력한 다음 아래 명령으로 패키지 이름, 버전, 아키텍처를 확인해 현재 배포판에 맞는 파일인지 점검합니다.

2. 설치 실행

   사용 중인 배포판에 해당하는 명령만 실행하세요. 패키지 관리자가 표시하는 의존성 변경 사항을 읽고 설치를 진행하세요. 데스크톱 구성 요소를 대량으로 제거하는 계획이 표시되면 취소하고 저장소가 혼용되고 있지 않은지 확인하세요.

3. 처음 실행하기

   데스크톱 앱 메뉴에서 v2rayN을 실행하세요. 설치에는 관리자 권한을 사용하더라도 평소 실행은 일반 사용자 계정으로 해야 합니다. 두 작업을 혼동하지 마세요. 창을 열어 둔 채 코어 실행 오류가 없는지 확인한 뒤 로그인 시 자동 실행을 설정하세요.

Ubuntu / Debian: deb 설치

read -r -p 'deb 파일의 전체 경로를 입력하세요: ' pkg
pkg="$(realpath -- "$pkg")"
dpkg-deb -f "$pkg" Package Version Architecture
sudo apt install "$pkg"

로컬 절대 경로를 지정하면 apt가 저장소에서 이름으로 패키지를 검색하는 대신 디스크에 있는 파일을 설치합니다. 이전에 dpkg -i를 사용해 설정이 완료되지 않은 패키지가 있다면 sudo apt --fix-broken install을 먼저 실행하고, 복구 계획을 확인한 다음 진행하세요. 의존성을 무시하고 강제 설치하는 방법은 일반적인 설치 절차로 사용하지 마세요.

Fedora: rpm 설치

read -r -p 'rpm 파일의 전체 경로를 입력하세요: ' pkg
pkg="$(realpath -- "$pkg")"
rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$pkg"
sudo dnf install "$pkg"

연결을 확인한 뒤 자동 실행 설정하기

설치가 완료됐다는 것은 프로그램 파일이 배포됐다는 뜻일 뿐입니다. 처음 실행한 뒤 구독을 추가하거나 노드를 가져오고, 노드를 선택해 연결을 테스트하세요. 버전에 따라 메뉴 구성이 달라질 수 있습니다. 일반적으로는 「구독 그룹」→「구독 그룹 설정」에서 설정한 다음 「구독 그룹」 메뉴에서 업데이트를 실행합니다. 현재 화면의 메뉴 문구가 다르면 사용 중인 버전의 실제 메뉴를 따르세요. 다른 플랫폼용 클라이언트에서 같은 이름의 버튼을 찾을 필요는 없습니다.

「설정」→「매개변수 설정」에서 로컬 수신 포트와 수신 유형을 확인하세요. 여기서 사용하는 10808은 테스트용 예시일 뿐이며 모든 버전의 기본값은 아닙니다. 아래 명령은 해당 포트에서 SOCKS 또는 혼합 수신을 제공한다고 가정합니다. 실행 전에 실제 설정과 일치하는지 확인하세요. 먼저 포트가 수신 중인지 확인한 다음, 데스크톱 시스템 프록시 설정을 거치지 않고 프록시 요청을 직접 보내 보세요.

ss -ltnp 'sport = :10808'
curl --proxy socks5h://127.0.0.1:10808 \
  --connect-timeout 5 --max-time 15 \
  --head https://example.com/

• 수신 중인 포트가 없음: 코어 로그, 노드 선택 여부, 시작 오류를 확인하세요. 데스크톱 프록시 설정부터 바꾸지는 마세요.
• 포트 사용 중: 해당 포트를 사용하는 프로세스가 다른 클라이언트 인스턴스인지 확인하세요. 중복 인스턴스를 종료하거나 수신 포트를 변경하고 테스트 명령에도 새 포트를 반영하세요.
• 요청에서 HTTP 응답을 받음: 해당 프록시 요청이 정상적으로 전달됐다는 뜻입니다. 응답 상태 코드가 반드시 200일 필요는 없으며, 대상 사이트의 상태도 함께 확인해야 합니다.
• 명령은 성공하지만 브라우저는 실패: 브라우저와 데스크톱의 프록시 설정을 확인하세요. Linux에서는 모든 프로그램이 동일한 시스템 프록시 설정을 사용하는 것은 아닙니다.

socks5h는 대상 도메인의 처리를 프록시 측에 맡긴다는 뜻입니다. 이 설정은 이번 테스트에서 애플리케이션이 로컬에서 도메인을 조회하는 상황을 줄여 줍니다. 하지만 요청 한 번만으로 시스템 전체의 DNS 설정이나 모든 앱의 트래픽이 예상대로 분기된다고 단정할 수는 없습니다.

로그인 시 자동 실행 방식 선택

데스크톱 클라이언트는 사용자 세션에 의존합니다. 일반적인 데스크톱 사용에는 시스템 서비스보다 XDG 자동 실행 파일을 설정하는 편이 적합합니다. 이 설정은 그래픽 데스크톱에 로그인할 때 적용되며, 로그인 화면이 나오기 전에 클라이언트를 실행하지는 않습니다. 아래 두 방법 중 하나만 선택해 로그인 후 인스턴스가 중복 실행되지 않도록 하세요.

현재 v2rayN 버전에 자동 실행 옵션이 있고 활성화되어 있다면, 먼저 실제로 생성된 시작 항목을 확인한 뒤 이 문서의 수동 설정을 사용할지 결정하세요. 클라이언트가 만든 항목, 데스크톱 설정에서 추가한 항목, 직접 복사한 항목을 동시에 남겨 두지 마세요. 창을 닫은 뒤에도 트레이에서 실행 중이라는 사실만으로 다음 로그인 때 자동 실행되도록 설정된 것은 아닙니다.

확인 가능한 자동 실행 파일 만들기

프로그램이 특정 경로에 설치됐다고 단정하지 말고, 설치 패키지에 포함된 .desktop 파일부터 찾으세요. 아래 조회 명령은 deb와 rpm에 각각 사용할 수 있습니다. 설치 과정에서 확인한 패키지 이름을 입력하세요. 결과에서는 /usr/share/applications/ 아래에 있는 v2rayN의 기본 실행 파일을 우선 선택하세요.

데스크톱 실행 항목 조회

# Ubuntu / Debian
read -r -p 'deb의 Package 필드를 입력하세요: ' package
dpkg -L "$package" | grep -E '/applications/[^/]+\.desktop$'

# Fedora: 이 명령 묶음은 Fedora에서만 실행
read -r -p 'rpm의 NAME 필드를 입력하세요: ' package
rpm -ql "$package" | grep -E '/applications/[^/]+\.desktop$'

desktop-file-edit로 항목 값을 편집합니다. Ubuntu와 Debian에서는 sudo apt install desktop-file-utils, Fedora에서는 sudo dnf install desktop-file-utils를 실행해 필요한 도구를 설치할 수 있습니다. 그다음 일반 사용자로 복사 명령을 실행하세요. 아래 명령 묶음에 sudo를 붙이지 마세요.

read -r -p '설치된 desktop 파일의 전체 경로를 입력하세요: ' source
test -f "$source" && grep -E '^(Name|Exec|TryExec|DBusActivatable)=' "$source"

autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
target="$autostart_dir/v2rayn-login.desktop"

mkdir -p "$autostart_dir"
cp -- "$source" "$target"

desktop-file-edit \
  --remove-key=Hidden \
  --remove-key=OnlyShowIn \
  --remove-key=NotShowIn \
  --remove-key=DBusActivatable \
  --set-key=X-GNOME-Autostart-enabled --set-value=true \
  "$target"

desktop-file-validate "$target"

복사하기 전에 조회 결과가 실제 대상 프로그램을 가리키는지, Exec=에 유효한 실행 명령이 있는지 확인하세요. 여기서는 패키지에 포함된 Exec을 그대로 사용하고, 데스크톱 환경 표시 제한을 제거하며, D-Bus 활성화에 의존하지 않고 명령으로 실행되도록 합니다. 원본 파일에 TryExec이 있다면 해당 프로그램도 실제로 존재해야 합니다. 그렇지 않으면 데스크톱 환경에서 시작 항목을 건너뛸 수 있습니다.

• 사용자 디렉터리: XDG_CONFIG_HOME이 설정되지 않은 경우 대상 경로는 ~/.config/autostart/v2rayn-login.desktop입니다.
• 경로 규칙: Exec=은 대화형 셸이 아닙니다. 원래 실행 항목을 대신해 ~, $HOME 또는 파이프가 포함된 명령을 직접 입력하지 마세요.
• 실행 권한: XDG 자동 실행에는 일반적으로 데스크톱 파일의 실행 권한이 필요하지 않습니다. 데스크톱 파일 관리자가 표시하는 「실행 허용」 안내는 별도의 상호작용입니다.
• 업데이트 관리: 사용자 디렉터리에 복사한 파일은 패키지 업데이트 시 자동으로 갱신되지 않습니다. 업그레이드 후 실행 경로가 변경됐다면 새 패키지에서 다시 복사하고 내용을 확인하세요.

검사 도구에서 아무 출력도 나오지 않으면 형식 검사를 통과한 경우가 많지만, 프로그램이 반드시 실행된다는 뜻은 아닙니다. 저장한 뒤 클라이언트를 정상적으로 종료하고 데스크톱에서 로그아웃한 다음 다시 로그인하세요. 터미널만 다시 여는 것으로는 로그인 자동 실행을 확인할 수 없습니다. 로그인 후 데스크톱이 로드될 때까지 기다린 뒤 창, 트레이, 로컬 포트를 확인해 인스턴스가 하나만 실행됐는지 점검하세요.

의존성·권한·로그인 문제 해결

업그레이드 및 자동 실행 해제

업그레이드할 때도 해당 배포판의 로컬 설치 명령을 사용하고, 실행 중인 클라이언트를 먼저 종료하세요. 새 버전을 설치해도 사용자 설정이 보통 삭제되지는 않지만, 업그레이드 전에 실제 데이터 디렉터리를 백업하는 것이 좋습니다. 특히 구독 그룹, 라우팅 및 사용자 지정 설정을 확인하세요. 디렉터리 위치는 현재 버전의 설정이나 로그에서 확인하고, 프로그램 설치 디렉터리만 데이터 저장 위치라고 단정하지 마세요.

로그인 시 자동 실행만 중단하려는 경우 v2rayN을 삭제할 필요는 없습니다. 이 문서에서 만든 시작 파일을 삭제하면 됩니다. 데스크톱 설정이나 클라이언트가 별도의 항목을 만들었다면 해당 위치에서도 비활성화하세요. 자동 실행 설정을 해제해도 이미 실행 중인 프로세스가 자동으로 종료되지는 않습니다.

autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
rm -f -- "$autostart_dir/v2rayn-login.desktop"

• 업그레이드가 끝나면 데스크톱 메뉴에서 한 번 직접 실행해 설정을 읽고 코어를 시작할 수 있는지 확인하세요.
• 이전 프로세스가 포트를 점유해 새 버전의 오류로 오인하지 않도록 수신 포트를 다시 확인하세요.
• 자동 실행을 유지한다면 새 패키지의 데스크톱 실행 항목이 변경됐는지 확인하고 필요한 경우 사용자 복사본을 다시 만드세요.
• 마지막으로 로그아웃한 뒤 다시 로그인해 자동 실행을 확인하고, 브라우저 프록시 설정도 별도로 테스트하세요.