v2rayN Linux 설치 가이드: deb/rpm 설치 및 로그인 시 자동 시작

이 글의 핵심

먼저 배포판과 CPU 아키텍처를 확인하고, 시스템 패키지 관리자에 맞는 Linux 데스크톱 패키지를 설치합니다. 구독을 가져온 뒤 로컬 수신 포트를 확인하고 시스템 프록시를 테스트하세요. 마지막으로 데스크톱 세션의 자동 시작 기능을 설정하면 로그인 후 앱을 실행할 수 있습니다. 컴퓨터 전원을 켠 뒤 로그인하기 전에 백그라운드 서비스를 실행하는 것과는 다릅니다. 이 가이드는 일반 사용자 데스크톱 세션을 대상으로 하며, TUN을 미리 활성화할 필요는 없습니다.

1. 다운로드 전 배포판·아키텍처·패키지 형식 확인

v2rayN은 서버, 구독, 코어 설정을 관리하는 데스크톱 클라이언트입니다. Linux 설치 패키지는 배포판의 패키지 관리 방식과 CPU 아키텍처 모두에 맞아야 합니다. Ubuntu와 Debian은 보통 deb, Fedora는 보통 rpm을 사용합니다. 같은 확장자를 사용하더라도 모든 배포판에서 쓸 수 있는 것은 아니므로 다운로드 안내에서 시스템 요구 사항을 확인하세요.

# 배포판과 CPU 아키텍처 확인
cat /etc/os-release
uname -m

# Debian / Ubuntu 패키지 아키텍처
dpkg --print-architecture

# Fedora 패키지 아키텍처
rpm --eval '%{_arch}'

사용 중인 배포판에 해당하는 명령만 실행하면 됩니다. x86_64는 다운로드 페이지의 x64에 해당하는 경우가 많고, Debian 패키지에서는 amd64로 표기하기도 합니다. aarch64는 보통 ARM64를 뜻합니다. Windows 패키지를 Linux 데스크톱용으로 착각하지 말고, 컴퓨터 브랜드만으로 아키텍처를 판단하지 마세요. 다운로드 센터에서 Linux 플랫폼을 선택한 다음, 해당 시점에 제공되는 패키지 형식을 확인하세요.

Ubuntu / Debian

패키지 형식: deb
로컬 설치: apt install
패키지 정보: dpkg-deb -f
설치된 파일: dpkg -L

의존성은 apt로 처리하고, 패키지를 풀어 놓는 것만으로 설치가 끝났다고 판단하지 마세요.

Fedora

패키지 형식: rpm
로컬 설치: dnf install
패키지 정보: rpm -qip
설치된 파일: rpm -ql

현재 배포판에 맞는 빌드를 사용하고, 의존성 오류가 나면 먼저 구체적인 오류 내용을 확인하세요.

2. apt 또는 dnf로 로컬 패키지 설치

아래 명령은 Bash 터미널에서 실행합니다. 이미 다운로드한 설치 패키지의 전체 경로를 입력하세요. 다운로드 페이지 주소를 붙여 넣으면 안 됩니다. 경로에 공백이 있어도 처리할 수 있습니다. 예시에는 고정된 패키지 이름을 사용하지 않으므로 새 버전이 나와도 예전 파일명을 그대로 따라 할 염려가 없습니다. 설치에는 관리자 권한이 필요하지만, 평소 클라이언트를 실행할 때는 일반 사용자 계정을 사용하세요.

Ubuntu / Debian: deb 설치

read -r -e -p "deb 파일의 전체 경로를 입력하세요: " package_file
package_file="$(realpath -- "$package_file")"

if [ -f "$package_file" ]; then
  dpkg-deb -f "$package_file" Package Version Architecture
  sudo apt update
  sudo apt install "$package_file"
else
  printf '%s\n' "파일이 없습니다. 경로를 확인한 뒤 다시 시도하세요."
fi

apt install에 로컬 파일 경로를 지정하면 설정된 저장소를 바탕으로 의존성을 해결합니다. 의존성을 충족할 수 없다는 메시지가 나오면 배포판 버전, 아키텍처, 저장소 상태부터 확인하세요. 강제 설치를 반복해도 실행 환경이 갖춰지는 것은 아닙니다. apt update는 저장소 인덱스만 갱신하며, 시스템 전체를 업그레이드하는 명령이 아닙니다.

Fedora: rpm 설치

read -r -e -p "rpm 파일의 전체 경로를 입력하세요: " package_file
package_file="$(realpath -- "$package_file")"

if [ -f "$package_file" ]; then
  rpm -qip "$package_file"
  sudo dnf install "$package_file"
else
  printf '%s\n' "파일이 없습니다. 경로를 확인한 뒤 다시 시도하세요."
fi

3. 첫 실행: 구독을 가져온 다음 코어 확인

설치가 끝나면 데스크톱 앱 메뉴에서 v2rayN을 검색해 실행하세요. 처음 실행할 때는 기본 권한과 일반 프록시 모드를 유지하는 것이 좋습니다. TUN은 가상 네트워크 인터페이스, 라우팅, 추가 권한이 필요하므로 첫 설치 문제와 함께 점검하지 않는 편이 좋습니다. 메뉴 이름은 버전에 따라 달라질 수 있습니다. 아래에서는 중국어 UI에서 흔히 쓰는 메뉴 이름을 안내하므로, 같은 이름을 찾을 수 없다면 현재 버전에서 동일한 기능을 제공하는 설정을 선택하세요.

클라이언트 실행

앱 메뉴에서 v2rayN을 실행하세요. 트레이 아이콘만 보이면 아이콘을 눌러 기본 창을 열어 보세요. 여러 인스턴스를 연속해서 실행하지 마세요.
구독 추가

「구독 그룹」→「구독 그룹 설정」으로 이동해 그룹을 추가하고 구독 주소와 메모를 입력한 뒤 저장합니다. 저장 후 기본 화면으로 돌아오세요.
구독 갱신

「구독 그룹」 메뉴에서 「모든 구독 업데이트(프록시 사용 안 함)」를 실행하세요. 아직 사용할 수 있는 노드가 없다면 먼저 직접 업데이트를 시도하고, 실패하면 네트워크와 구독 주소를 확인하세요.
활성 항목으로 지정

서버 목록에서 유효한 설정을 선택한 다음, 마우스 오른쪽 버튼 메뉴에서 「활성 서버로 설정」을 선택하세요. 구독 업데이트에 성공해도 사용할 노드가 자동으로 선택되는 것은 아닙니다.
수신 포트 확인

「설정」→「매개변수 설정」에서 로컬 수신 주소와 포트, 코어 관련 설정을 확인한 다음 실행 로그를 살펴보세요. 코어가 정상적으로 시작됐고 포트 충돌이 없는지 확인해야 합니다.

구독에는 보통 노드의 프로토콜과 전송 매개변수가 포함됩니다. Linux 버전을 설치한다고 VMess를 VLESS로 바꿀 필요는 없으며, TLS, 서버 이름, 전송 경로를 임의로 변경해서도 안 됩니다. 로그에 코어 파일이 없다는 메시지가 나오면 선택한 설치 패키지에 필요한 코어가 포함되어 있는지, 클라이언트 설정이 실제 파일을 가리키는지 확인하세요. 이 문제는 시스템 프록시 설정과는 별도로 점검해야 합니다.

4. Linux 시스템 프록시: 수신 포트와 데스크톱 설정 맞추기

시스템 프록시는 해당 설정을 읽는 앱에만 적용되며 모든 프로세스의 트래픽을 자동으로 전달하지 않습니다. 먼저 클라이언트의 로컬 프록시가 작동하는지 확인한 다음 데스크톱 환경의 프록시를 설정하세요. 아래에서는 설명을 위해 127.0.0.1:10808을 예시로 사용합니다. 모든 버전의 기본값이라는 뜻은 아니므로 실제 값은 매개변수 설정과 로그에서 확인하세요.

10808

이 문서에서 사용하는 로컬 프록시 포트 예시

127.0.0.1

로컬 루프백 수신 주소

15초

아래 요청의 최대 대기 시간

GNOME 데스크톱에서는 「설정」→「네트워크」→「네트워크 프록시」→「수동」에서 설정을 확인할 수 있습니다. HTTP와 HTTPS 입력란에는 로컬 HTTP 프록시의 호스트와 포트를 입력합니다. HTTPS 입력란이 프록시 서버에 HTTPS로 연결해야 한다는 뜻은 아닙니다. 코어가 SOCKS 수신 포트를 제공한다면 SOCKS 입력란에 지정하세요. SOCKS 전용 포트를 HTTP 포트로 입력하면 안 됩니다. 혼합 수신 포트에서 지원하는 프로토콜은 현재 코어 설정을 확인하세요.

# 예시 포트에서 연결을 수신 중인지 확인
ss -ltnp 'sport = :10808'

# 해당 포트가 HTTP 프록시를 지원하는 경우
curl --connect-timeout 5 --max-time 15 \
  --proxy http://127.0.0.1:10808 \
  -I https://example.com

# 해당 포트가 SOCKS5를 지원하는 경우: 목적지 도메인 확인을 프록시에 맡김
curl --connect-timeout 5 --max-time 15 \
  --proxy socks5h://127.0.0.1:10808 \
  -I https://example.com

아래 두 curl 명령은 수신 유형에 맞는 것만 사용하면 되며, 둘 다 성공할 필요는 없습니다. --proxy를 명시하는 이유는 데스크톱 프록시 설정을 거치지 않고 “로컬 수신→코어→노드→대상 웹사이트” 경로가 작동하는지 먼저 확인하기 위해서입니다. HTTP 응답을 받았다는 것은 해당 요청이 대상에 도달했다는 뜻일 뿐, 모든 웹사이트나 UDP, 전체 라우팅이 검증됐다는 의미는 아닙니다.

로컬 연결이 거부됨: 코어가 실행 중인지, 포트 번호를 잘못 입력하지 않았는지 먼저 확인하세요.
로컬 연결은 되지만 요청이 시간 초과됨: 활성 노드, 코어 로그, 대상 도메인 확인, 라우팅 규칙 적용 여부를 점검하세요.
curl은 성공하지만 브라우저는 실패함: 브라우저가 시스템 프록시를 사용하는지, 별도의 프록시 설정이나 재시작이 필요한 이전 세션이 있는지 확인하세요.
데스크톱 설정이 바뀌지 않음: 일부 데스크톱 환경은 클라이언트의 시스템 프록시 설정을 반영하지 않습니다. 클라이언트 버튼 상태만 보지 말고 데스크톱 설정에서 직접 확인하세요.

5. 자동 시작의 의미: 로그인 후 데스크톱 앱 실행

이 가이드에서 권장하는 방식은 그래픽 데스크톱에 로그인한 뒤 v2rayN을 자동으로 실행하는 것입니다. 로그인 화면이 나오기 전에 GUI를 실행하는 방식이 아닙니다. 로그인 전에는 사용자 세션, 디스플레이 서비스, 데스크톱 설정 환경이 없으므로 시스템 서비스로 등록하면 창이 표시되지 않거나 다른 사용자의 프록시 설정을 바꾸는 문제가 생길 수 있습니다. 먼저 수동 실행이 정상적으로 되는지 확인한 뒤 자동 시작을 설정하면 점검할 변수를 줄일 수 있습니다.

데스크톱 세션 자동 시작

권장

데스크톱 환경의 자동 시작 메뉴를 사용하거나 설치 패키지에서 제공하는 desktop 항목을 복사하세요. 앱에 실제로 적용되는 실행 명령을 사용하면 사용자 로그인 후 그래픽 세션에서 앱이 실행됩니다.

적합한 경우: 일반 데스크톱 사용자, 트레이와 창 관리가 필요한 설치 환경

클라이언트 내장 자동 시작

현재 Linux 버전에 이 기능이 있다면 먼저 켠 뒤 다시 로그인해 동작을 확인하세요. 빌드와 데스크톱 환경에 따라 구현이 다를 수 있으므로 다른 자동 시작 방식과 중복으로 활성화하지 마세요.

적합한 경우: 현재 버전에서 기능을 명확히 제공하고 정상적으로 작동하는 환경

서비스 유닛 직접 작성

사용자 서비스와 시스템 서비스를 구분하고 그래픽 세션 환경과 종료 동작을 처리해야 합니다. 이 가이드에서는 GUI 클라이언트를 로그인 전 백그라운드 서비스로 구성하지 않습니다.

적합한 경우: 세션 수명 주기를 이해하고 서비스 의존성을 별도로 설계해야 하는 관리자

데스크톱 자동 시작을 사용한다면 실행 파일이 어디에 있는지 추측하는 대신 패키지가 설치한 .desktop 파일을 재사용하세요. 아래 명령은 앞서 설치할 때 입력한 package_file 변수를 사용해 패키지 이름을 확인하고 시작 항목을 찾습니다. 터미널을 닫았다면 설치 패키지 경로를 다시 입력한 후 해당 명령을 실행하세요.

# Ubuntu / Debian: deb에서 실제 패키지 이름을 확인하고 시작 항목 찾기
package_name="$(dpkg-deb -f "$package_file" Package)"
dpkg -L "$package_name" | grep '/applications/.*\.desktop$'

# Fedora: rpm에서 실제 패키지 이름을 확인하고 시작 항목 찾기
package_name="$(rpm -qp --queryformat '%{NAME}' "$package_file")"
rpm -ql "$package_name" | grep '/applications/.*\.desktop$'

위 두 명령 중 현재 시스템에 해당하는 한 가지만 실행하세요. 출력된 파일이 v2rayN 본 프로그램의 시작 항목인지 확인한 뒤 아래 명령으로 복사합니다. 검색 결과가 없다면 다른 앱의 시작 항목을 복사하지 말고, 현재 데스크톱 환경의 '자동 시작' 설정에서 실제 실행 명령을 추가하세요.

read -r -e -p "검색한 desktop 파일의 전체 경로를 입력하세요: " desktop_file

if [ -f "$desktop_file" ]; then
  grep -E '^(Name|Exec|TryExec|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"
  mkdir -p "$HOME/.config/autostart"
  install -m 644 -- "$desktop_file" \
    "$HOME/.config/autostart/v2rayn.desktop"
else
  printf '%s\n' "시작 항목 파일이 없습니다. 자동 시작을 설정하지 않았습니다."
fi

6. 재로그인 후 확인 및 자주 발생하는 문제

설정을 마친 뒤 로그아웃했다가 다시 로그인하세요. 보통 컴퓨터 전체를 재부팅할 필요는 없습니다. 클라이언트가 한 번만 실행됐는지, 활성 서버가 유지됐는지, 로컬 포트에서 수신 중인지 확인한 다음 앞서 사용한 프록시 요청을 다시 실행하세요. 창 표시, 코어 실행, 데스크톱 프록시 적용은 서로 별개의 점검 항목입니다. 트레이 아이콘만 보인다고 네트워크 연결이 복구된 것은 아닙니다.

로그인 후 창이 두 개 뜨는 이유는 무엇인가요?

클라이언트 내장 자동 시작, 데스크톱의 '자동 시작' 목록, ~/.config/autostart/를 확인하고 한 가지 방식만 남기세요. 이 문서에서 만든 복사본은 rm -f "$HOME/.config/autostart/v2rayn.desktop"으로 삭제할 수 있습니다. 이 명령은 클라이언트를 제거하지 않습니다.

포트가 이미 사용 중이라고 나오면 어떻게 하나요?

ss -ltnp 'sport = :10808'을 실행해 이전 인스턴스가 계속 실행 중인지 먼저 확인하세요. 수신 포트를 변경하려면 「설정」→「매개변수 설정」에서 저장한 다음 데스크톱 프록시와 터미널 테스트 명령도 함께 바꿔 두 곳의 설정이 일치하게 하세요.

업데이트 후 자동 시작이 작동하지 않나요?

새 패키지의 desktop 파일을 다시 검색하고 Exec=과 TryExec=을 비교하세요. 사용자 디렉터리에 복사한 파일은 시스템 파일이 업데이트되어도 자동으로 바뀌지 않습니다. 경로가 변경됐다면 다시 복사한 뒤 로그아웃하고 로그인해 확인하세요.

클라이언트를 닫은 뒤 웹페이지가 열리지 않는 이유는 무엇인가요?

데스크톱 프록시가 종료된 로컬 포트를 계속 가리키는지 확인하세요. GNOME에서는 「설정」→「네트워크」→「네트워크 프록시」로 이동해 '사용 안 함'으로 바꾼 다음 직접 연결을 다시 시도하세요. 프록시를 계속 사용하려면 먼저 코어를 다시 시작하세요.

터미널 프로그램이 시스템 프록시를 사용하지 않는 이유는 무엇인가요?

많은 명령줄 도구는 GNOME 프록시 설정을 읽지 않습니다. 먼저 명시적으로 curl --proxy를 지정해 확인한 뒤, 도구 설명에 따라 프록시 옵션이나 환경 변수를 설정하세요. 데스크톱 프록시가 작동한다고 모든 명령이 자동으로 프록시를 사용하는 것은 아닙니다.

7. 업그레이드 및 되돌리기 전에 저장할 설정

이후 업그레이드에도 같은 배포판과 아키텍처에 맞는 패키지를 사용하고 apt 또는 dnf로 설치하세요. 설치 패키지는 프로그램 파일을 관리하지만 구독, 라우팅, 화면 설정과 같은 사용자 데이터는 별도의 설정 디렉터리에 저장될 수 있습니다. 저장 위치는 버전과 실행 방식에 따라 달라지므로 현재 클라이언트의 설정 디렉터리 메뉴나 로그에서 확인하세요. 온라인에서 찾은 특정 경로를 그대로 적용하지 마세요.

먼저 클라이언트를 종료하세요: 설정을 복사하는 동안 백그라운드에서 파일이 계속 기록되지 않도록 합니다. 창만 닫고 트레이 프로세스를 남겨 두지 마세요.
사용자 설정을 저장하세요: 확인된 설정 디렉터리를 백업하고 활성 노드, 라우팅 프리셋, 수신 포트, 자동 시작 방식을 기록하세요. 구독 주소에 인증 정보가 포함될 수 있으므로 공개 로그에 붙여 넣지 마세요.
업그레이드 후 먼저 수동으로 실행하세요: 코어 로그와 로컬 수신을 확인하고, HTTP 또는 SOCKS 요청을 테스트한 다음 자동 시작을 점검하세요.
되돌릴 때는 데이터 형식에 유의하세요: 새 버전에서 기록한 데이터를 이전 버전이 읽을 수 있다고 보장할 수 없습니다. 되돌려야 한다면 프로그램을 반복해서 덮어쓰기보다 업그레이드 전 설정 백업을 함께 사용하세요.

이 과정을 마치면 Linux용 v2rayN 설치와 실행을 네 단계로 나눠 점검할 수 있습니다. 패키지 설치, 클라이언트와 코어 실행, 앱 요청의 프록시 경유 여부, 로그인 후 자동 실행입니다. 문제가 생기면 노드, 라우팅, TUN을 한꺼번에 바꾸기보다 단계별로 확인하는 편이 원인을 찾기 쉽습니다. 모드 차이는 시스템 프록시 및 프록시 모드 안내에서, 라우팅 설정은 라우팅 설정 참고에서 확인하세요.