Linux용 v2rayN 설치 방법: Debian/Ubuntu deb·Fedora rpm 설치 및 자동 실행 설정

1. 배포판, 아키텍처, 데스크톱 세션 확인

클라이언트 다운로드 페이지에서 Linux 설치 패키지를 선택하세요. Debian, Ubuntu 및 파생 배포판에는 보통 deb 패키지를, Fedora에는 rpm 패키지를 사용합니다. 패키지 형식과 프로세서 아키텍처가 모두 일치해야 합니다. x86_64는 x64, aarch64는 ARM64에 해당합니다. 컴퓨터 브랜드만으로 아키텍처를 판단하지 마세요.

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

아래 내용은 GNOME, KDE 등 그래픽 데스크톱에 로그인한 상황을 기준으로 합니다. 순수 CLI 서버에는 데스크톱 세션이 없으므로 데스크톱 자동 실행 방법을 그대로 적용할 수 없습니다. v2rayN은 그래픽 클라이언트이며, 실제 연결과 트래픽 전달은 프록시 코어가 담당합니다. 클라이언트를 설치했다고 프록시가 자동으로 활성화되는 것은 아닙니다.

2. Debian / Ubuntu: deb 설치 및 의존성 해결

파일 관리자에서 다운로드 폴더를 연 뒤 ‘터미널에서 열기’를 선택하세요. 이번에 사용할 deb 파일만 별도 디렉터리에 넣어 명령이 이전 버전이나 다른 패키지를 선택하지 않도록 합니다. 아래 명령은 Bash에서 실행합니다. 현재 디렉터리에 deb 파일이 정확히 하나 있는지 확인한 다음 패키지 정보를 읽고 설치합니다. 변수는 현재 터미널에서만 사용됩니다.

mapfile -d '' packages < <(find . -maxdepth 1 -type f -name '*.deb' -print0)
if [ "${#packages[@]}" -eq 1 ]; then
  deb_file="${packages[0]}"
  dpkg-deb -f "$deb_file" Package Version Architecture
  sudo apt update
  sudo apt install "$deb_file"
else
  printf '현재 디렉터리에는 설치할 deb 패키지 하나만 남겨 두세요.\n'
fi

출력에 표시된 패키지 이름, 버전, 아키텍처를 확인한 뒤 설치를 진행하세요. 경로가 ./로 시작하면 로컬 파일을 가리킵니다. 경로를 생략하면 apt가 인수를 저장소의 패키지 이름으로 처리할 수 있습니다. 아키텍처가 맞지 않는다는 메시지가 나오면 설치 패키지를 다시 선택하고 강제 옵션으로 검사를 우회하지 마세요.

1. 패키지 정보 확인

   dpkg-deb -f의 출력을 확인해 다운로드한 패키지가 v2rayN용인지, 아키텍처가 시스템과 일치하는지 확인하세요.

2. 설치 및 의존성 보완

   sudo apt install "$deb_file"을 실행하세요. 이전에 dpkg를 사용해 설치가 완료되지 않았다면 sudo apt --fix-broken install을 실행하고, 복구 계획을 확인한 뒤 진행하세요.

3. 데스크톱 실행 항목 확인

   설치가 끝나면 애플리케이션 메뉴에서 v2rayN을 검색하세요. 프로그램 디렉터리에 먼저 재귀적으로 쓰기 권한을 부여하지 마세요.

4. 일반 사용자로 실행

   현재 로그인한 사용자로 v2rayN을 실행해 메인 창과 로그가 정상인지 확인한 다음, 구독 설정과 로그인 시 자동 실행을 진행하세요.

3. Fedora: dnf로 rpm 설치

이번 설치 패키지만 들어 있는 디렉터리에서 Bash를 여세요. 먼저 rpm -qp로 메타데이터를 조회한 뒤 dnf로 설치합니다. 로컬 패키지 조회는 설치 작업이 아니므로 관리자 권한이 필요하지 않습니다.

mapfile -d '' packages < <(find . -maxdepth 1 -type f -name '*.rpm' -print0)
if [ "${#packages[@]}" -eq 1 ]; then
  rpm_file="${packages[0]}"
  rpm -qp --queryformat '%{NAME} %{VERSION}-%{RELEASE} %{ARCH}\n' "$rpm_file"
  sudo dnf install "$rpm_file"
else
  printf '현재 디렉터리에는 설치할 rpm 패키지 하나만 남겨 두세요.\n'
fi

rpm --nodeps로 의존성 검사를 건너뛰지 마세요. 패키지가 설치된 것으로 표시되더라도 실행 시 공유 라이브러리가 없어 작동하지 않을 수 있습니다. 의존성 오류가 발생하면 dnf가 표시한 패키지 이름과 버전 조건을 먼저 확인하세요. 저장소에 필요한 버전이 없다면 시스템 버전과 패키지의 호환성을 점검해야 합니다.

• 이미 설치된 패키지라는 메시지가 표시됨: 현재 버전을 먼저 확인하세요. 다시 설치할 필요는 없습니다. 업데이트하려면 아키텍처에 맞는 패키지를 새로 다운로드해 dnf로 설치하세요.
• 파일을 읽을 수 없다는 메시지가 표시됨: 터미널의 현재 디렉터리와 파일 이름을 확인하세요. 다운로드 폴더 전체에 chmod -R 777을 실행하지 마세요.
• 보안 정책 차단이 의심됨: 실제 오류와 감사 로그를 확인하세요. 창을 열기 위해 SELinux를 바로 비활성화하지 마세요.

로컬 deb 또는 rpm을 설치해도 지속적으로 업데이트되는 저장소가 자동 등록되는 것은 아닙니다. 이후 시스템 업데이트에 따라 새 버전이 설치되는지는 패키지에 저장소가 설정되어 있는지에 따라 달라집니다. 저장소가 설정되지 않았다면 새 패키지를 다운로드해 다시 설치해야 합니다.

4. 첫 실행: 수신 대기부터 프록시까지 확인

애플리케이션 메뉴에서 v2rayN을 실행하고 직접 보유한 구독 또는 노드 설정을 가져온 뒤, 사용할 수 있는 노드를 선택하세요. 이어서 ‘설정’ → ‘매개변수 설정’에서 로컬 수신 대기 관련 항목을 확인합니다. 버전에 따라 설정 메뉴 위치가 달라질 수 있으므로 현재 화면에 표시된 포트와 프로토콜을 기준으로 하세요.

아래 예시는 로컬 SOCKS 또는 혼합 수신 대기 포트가 10808이라고 가정합니다. 확인을 위한 예시일 뿐, 모든 버전의 기본값을 보장하지는 않습니다. 실제 포트가 다르면 실행 전에 명령의 숫자를 바꾸세요. socks5h는 대상 도메인의 이름 확인을 프록시 측에 맡겨 이번 테스트에 로컬 DNS가 개입하는 것을 줄여 줍니다.

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

• 수신 대기 기록이 없음: 코어가 실행 중인지, 포트가 올바른지, 로그에 설정 파일 해석 오류가 있는지 먼저 확인하세요.
• 연결이 거부됨: 해당 주소와 포트에서 수신 대기 중인 서비스가 없다는 뜻인 경우가 많습니다. 먼저 로컬 연결 지점을 점검하세요.
• HTTP 응답이 반환됨: 이번에 지정한 프록시 요청에 대상 서버 또는 중간 서비스가 응답했다는 뜻입니다. 접속 결과는 상태 코드와 함께 판단해야 합니다.

브라우저에서 접속된다고 터미널도 시스템 프록시를 자동으로 사용한다는 뜻은 아닙니다. 위 curl 명령은 프록시를 명시하므로 데스크톱 프록시 설정에 의존하지 않습니다. 처음 설치할 때는 먼저 이처럼 단일 요청으로 확인한 다음 필요에 따라 시스템 프록시나 TUN을 활성화하세요. 일반적인 로컬 프록시를 사용하려고 그래픽 클라이언트를 계속 root 권한으로 실행할 필요는 없습니다.

5. 로그인 시 자동 실행: 패키지의 데스크톱 실행 항목 활용

여기서 ‘부팅 시 자동 실행’은 사용자가 그래픽 데스크톱에 로그인한 뒤 v2rayN을 실행한다는 뜻입니다. 컴퓨터 전원이 켜진 직후, 로그인 전에 실행하는 방식이 아닙니다. 일반적인 데스크톱 사용에는 XDG 자동 실행 항목을 권장합니다. 패키지에서 관리하는 실행 경로를 재사용하므로 업데이트 후 실행 항목이 작동하지 않을 가능성을 줄일 수 있습니다.

설치된 desktop 파일 찾기

일반 사용자 터미널에서 아래 검색 명령을 실행하세요. 스크립트는 파일을 하나 찾았을 때만 복사합니다. 여러 개를 찾으면 후보를 표시하고 중단합니다. 설치 위치를 미리 가정할 필요가 없고, 설치 패키지의 파일 이름을 프로그램 실행 명령으로 잘못 사용하는 일도 방지할 수 있습니다.

mapfile -d '' entries < <(
  find /usr/share/applications /usr/local/share/applications \
    -maxdepth 1 -type f -iname '*v2rayn*.desktop' \
    -print0 2>/dev/null
)
if [ "${#entries[@]}" -eq 1 ]; then
  desktop_file="${entries[0]}"
  grep -E '^(Name|Exec|TryExec|Path|Hidden|OnlyShowIn|NotShowIn)=' "$desktop_file"
  autostart_dir="${XDG_CONFIG_HOME:-$HOME/.config}/autostart"
  mkdir -p "$autostart_dir"
  cp -- "$desktop_file" "$autostart_dir/v2rayn.desktop"
  printf '복사 위치: %s\n' "$autostart_dir/v2rayn.desktop"
else
  printf '실행 항목 %s개를 찾았습니다. 먼저 직접 확인하세요:\n' "${#entries[@]}"
  printf '%s\n' "${entries[@]}"
fi

실행 항목을 찾지 못했다면 이전에 설치 명령을 실행한 터미널로 돌아가 dpkg-deb -f "$deb_file" Package 또는 rpm -qp --queryformat '%{NAME}\n' "$rpm_file"로 패키지 이름을 확인하세요. 그런 다음 dpkg -L 또는 rpm -ql로 해당 패키지의 파일 목록을 확인합니다. 실제 실행 항목을 확인한 뒤 진행하고, /opt 아래 프로그램 경로를 추측하지 마세요.

비활성화 여부 확인

복사한 파일을 텍스트 편집기로 열고 [Desktop Entry] 섹션을 확인하세요. Hidden=true가 있으면 Hidden=false로 바꾸고, X-GNOME-Autostart-enabled=false가 있으면 true로 바꾸세요. 비활성화 항목이 없다면 보통 추가로 설정할 필요가 없습니다. OnlyShowIn 또는 NotShowIn이 있다면 현재 데스크톱 환경이 제외되어 있지 않은지도 확인하세요.

• 기존 Exec, TryExec, Path의 유효한 값을 유지하세요. 실행 명령을 함부로 sudo로 바꾸지 마세요.
• Exec은 대화형 셸이 아니므로 터미널처럼 ~, 파이프, 리디렉션을 자동으로 해석하지 않습니다.
• 사용자 자동 실행 디렉터리에 파일을 작성할 때 sudo는 필요하지 않습니다. sudo를 사용하면 root 소유의 설정 파일이 생길 수 있습니다.
• 클라이언트 자체 자동 실행을 이미 활성화했다면 실행 방식이 중복되지 않도록 둘 중 하나를 먼저 비활성화하세요.

6. 로그아웃 후 확인 및 복구 방법 유지

현재 작업을 저장하고 v2rayN을 정상 종료한 뒤 데스크톱에서 로그아웃하고 다시 로그인하세요. 터미널만 닫아서는 로그인 시 자동 실행을 테스트할 수 없습니다. 로그인 후 창이나 프로세스가 실행됐는지 먼저 확인하고 수신 대기 포트를 점검하세요. 일부 데스크톱은 시스템 트레이 아이콘을 지원하지 않으므로 아이콘 표시 여부만으로 성공 여부를 판단하지 마세요.

pgrep -af '[vV]2ray[Nn]'
ss -lntp 'sport = :10808'
journalctl --user -b --no-pager -n 100

사용자 로그에 시작 정보가 남는지는 데스크톱 환경에 따라 다릅니다. 로그에 기록이 없다는 이유만으로 시작 실패라고 단정하지 마세요. 클라이언트는 실행 중인데 노드 연결이 시간 초과된다면 네트워크가 연결될 때까지 기다린 다음 구독, 노드, 코어 로그를 확인하세요. 네트워크 문제를 해결하려고 자동 실행 항목을 반복해서 추가하지 마세요.

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

7. 설치 및 권한 오류 해결

최종 점검은 세 가지입니다. 시스템 패키지 관리자로 패키지를 조회할 수 있는지, 일반 사용자로 직접 실행한 뒤 프록시 요청이 성공하는지, 데스크톱에 다시 로그인했을 때 수신 대기 서비스가 자동으로 복구되는지 확인하세요. 세 항목을 모두 통과해야 설치, 연결, 자동 실행이 완료된 것입니다. 이후 포트를 변경하거나 설치 경로를 업데이트해도 같은 순서로 다시 점검하세요.