Project V 생태계 · 클라이언트 가이드

V2Ray 오픈소스 가이드클라이언트 및 라우팅 가이드

운영체제에 맞는 오픈소스 클라이언트를 선택하고, 구독 가져오기부터 라우팅 설정까지 단계별로 확인하세요.

01 생태계 개요

GUI 클라이언트와 코어

클라이언트는 설정을 편집하고 관리하며, 코어는 연결을 수립하고 요청을 처리해 라우팅 규칙을 적용합니다. 화면이 열렸다고 해서 코어가 정상적으로 실행 중인 것은 아닙니다.

  • Project VV2Ray는 Project V에서 시작됐습니다. 인바운드, 라우팅, 아웃바운드는 각각 별도의 설정으로 관리합니다. 코어 로그를 읽을 때 문제 위치를 구분하는 기준이 됩니다.
  • V2Fly커뮤니티에서 V2Ray 코어를 이어서 유지보수합니다. v2flyNG를 사용한다면 실제로 쓰는 코어에 맞춰 프로토콜과 규칙 필드를 확인하세요.
  • XrayV2Ray 생태계에서 갈라져 나온 프로젝트입니다. REALITY 등의 설정은 Xray 문서를 기준으로 매개변수를 확인하세요.
  • MPL-2.0V2Fly의 V2Ray 코어와 Xray-core가 사용하는 오픈소스 라이선스입니다. 각 클라이언트에는 별도의 라이선스 고지가 있을 수 있습니다.

02 설정 흐름

구독, 프록시 모드와 라우팅 규칙

설정 출처부터 트래픽 처리, 규칙 적용까지 각 단계별로 확인하세요. 문제가 생기면 먼저 어느 단계에서 발생했는지 파악한 뒤 설정을 조정합니다.

예외 규칙을 먼저 배치하고 기본 아웃바운드를 정하세요

v2rayN의 라우팅 설정에서 현재 적용 중인 규칙 세트를 확인한 뒤, 규칙 순서에 따라 아웃바운드를 점검하세요. 코어는 보통 처음 일치하는 규칙을 적용하므로 LAN 직접 연결이나 특정 도메인 차단 규칙은 범위가 넓은 규칙보다 앞에 두어야 합니다. 도메인 조건과 주소 조건은 각각 확인해야 합니다. 한 규칙에 두 조건을 모두 입력했다고 해서 둘 중 하나만 일치해도 적용되는 것은 아닙니다. 수정한 뒤 요청을 다시 보내고 로그에서 아웃바운드를 확인하세요. 페이지가 열리는지만으로 라우팅 적용 여부를 판단하지 마세요.

아웃바운드 매핑 예시. 기본 아웃바운드는 실제 설정에 따라 달라집니다.
geoip:private             → direct
geosite:category-ads-all  → block
geosite:cn                → direct

03 설치 파일 선택

운영체제와 아키텍처에 맞게 다운로드

먼저 운영체제를 고르고 프로세서 아키텍처를 확인하세요. 데스크톱에서는 v2rayN을 사용하고, Android에서는 필요한 코어에 따라 v2rayNG 또는 v2flyNG를 선택합니다.

Windows

v2rayN Desktop / WPF

처음 설치한다면 Desktop 버전을 권장합니다. 기존 WPF 인터페이스에 익숙하다면 클래식 WPF 버전을 선택할 수 있습니다. 두 버전의 주요 차이는 인터페이스와 패키징 방식이며, 프록시 프로토콜이 서로 다른 것은 아닙니다. 시스템 정보에서 운영체제 유형을 확인한 다음 다운로드 페이지의 안내에 따라 실행 환경을 준비하세요.

압축을 푼 뒤에는 전체 폴더에서 실행하세요. 실행 파일만 바탕 화면으로 옮겨 단독으로 실행하면 안 됩니다. 이전 버전에서 옮길 때는 먼저 기존 폴더의 사용자 데이터를 백업한 뒤 새 프로그램이 그룹과 노드를 읽을 수 있는지 확인하세요. 더블 클릭해도 화면이 나타나지 않으면 구독을 다시 가져오기보다 런타임, 폴더 쓰기 권한, 보안 프로그램 기록부터 점검하세요.

다운로드 페이지로 이동

macOS

v2rayN Apple Silicon / Intel

‘이 Mac에 관하여’에서 칩 또는 프로세서 항목을 확인하세요. Apple Silicon은 arm64, Intel은 x64를 선택합니다. 제품 외관이나 구매 연도로 아키텍처를 추측하지 마세요. 같은 제품군이라도 세대에 따라 칩이 다를 수 있습니다.

설치한 뒤에는 정상 작동이 확인된 설정 하나로 클라이언트가 코어를 시작하는지 확인하세요. 브라우저에서는 접속되는데 특정 프로그램에서 연결되지 않는다면 해당 프로그램이 시스템 프록시를 사용하는지 살펴보세요. 별도 프록시 설정이 있는 앱은 로컬 주소, 리스닝 포트, 프록시 유형을 따로 확인해 다른 클라이언트에서 남은 설정을 그대로 사용하지 않도록 합니다.

다운로드 페이지로 이동

Android

v2rayNG / v2flyNG

v2rayNG는 Xray 코어를 사용합니다. V2Fly 코어가 필요한 경우에만 v2flyNG를 선택하세요. 기기가 arm64-v8a를 지원한다면 arm64 패키지를 사용할 수 있습니다. 지원 아키텍처를 모른다면 범용 패키지를 선택하되 시스템 요구 사항을 충족해야 합니다.

프록시 서비스를 처음 시작할 때 시스템 안내에 따라 VPN 연결 권한을 허용하세요. 기기에서 VPN 슬롯을 사용하는 다른 앱이 있다면 기존 연결을 중지한 뒤 테스트합니다. 화면을 잠근 뒤 연결이 끊긴다면 VPN 상태, 백그라운드 제한, 네트워크 전환 기록을 각각 확인하세요. 이 현상만으로 원격 노드가 사용할 수 없다고 판단하지 마세요.

다운로드 페이지로 이동

Linux

v2rayN deb / rpm

Debian 및 Ubuntu 계열은 deb 패키지를, Fedora 등 RPM 패키지 관리자를 사용하는 배포판은 rpm 패키지를 확인하세요. 패키지 형식과 프로세서 아키텍처는 별개의 조건입니다. x86_64는 x64, aarch64는 arm64에 해당합니다. 패키지 형식만 바꿔서는 아키텍처 불일치를 해결할 수 없습니다.

설치 후에는 데스크톱 앱과 터미널 프로그램에서 각각 테스트하세요. 데스크톱 환경의 시스템 프록시가 터미널 프로그램에 적용되지 않을 수 있으며, 일부 도구는 자체 프록시 설정이나 환경 변수를 사용합니다. 터미널에서만 실패한다면 실제로 어떤 설정을 읽는지 먼저 확인하세요. 둘 다 실패한다면 클라이언트의 코어 실행 여부와 로컬 리스너를 확인합니다.

다운로드 페이지로 이동

04 오픈소스 생태계

Project V, V2Fly, Xray의 관계

설정을 옮길 수 있는지 판단할 때는 노드 이름이나 가져오기 결과만 보지 말고 클라이언트, 코어, 규칙 데이터를 각각 확인해야 합니다.

코어에서 요청이 처리되는 순서

inbound → routing → outbound

클라이언트가 설정을 생성하거나 불러옵니다. 코어에 들어온 요청은 라우팅 규칙에 따라 아웃바운드를 선택합니다.

코어 및 라우팅 용어 보기

이 사이트의 문서 범위 알아보기

  1. Project V: 인바운드부터 아웃바운드까지의 설정 모델

    Project V는 V2Ray 생태계의 출발점입니다. 일상적인 사용에서 특히 유용한 부분은 설정 모델입니다. 인바운드가 요청을 받고, 라우팅이 트래픽을 어느 아웃바운드로 보낼지 결정하며, 아웃바운드는 직접 연결하거나 전달하거나 설정에 따라 거부합니다. GUI 클라이언트의 노드 목록은 설정의 일부일 뿐, 모든 앱의 요청이 코어에 들어간다는 뜻은 아닙니다. 예를 들어 브라우저와 같은 기기의 명령줄 도구는 각자 다른 프록시 설정을 사용할 수 있으므로 같은 주소에 접속해도 실제 트래픽 경로가 달라질 수 있습니다.

    따라서 데스크톱 화면에서 노드를 선택한 것을 확인했더라도 두 가지를 구분해야 합니다. 코어가 정상적으로 리스닝 중인지, 대상 앱이 실제로 요청을 해당 리스너에 보내는지 확인하세요. 로그에 대상 요청이 나타나지 않는다면 먼저 앱의 연결 방식을 점검해야 합니다. 코어에 도달하지 않은 트래픽은 원격 전송 매개변수를 반복해서 바꿔도 경로가 달라지지 않습니다.

  2. V2Fly와 Xray: 공통된 설정 개념, 서로 다른 구현

    V2Fly는 커뮤니티에서 V2Ray 코어를 이어서 유지보수하는 프로젝트입니다. Xray는 같은 기술 흐름에서 갈라져 독립 프로젝트로 발전했습니다. 두 프로젝트는 인바운드, 라우팅, 아웃바운드 등 기본 개념을 공유하지만 프로토콜, 전송 방식, 보안 필드는 각 구현에 따라 발전합니다. 클라이언트가 공유 링크를 파싱했다는 것은 링크를 인식했다는 뜻일 뿐입니다. 선택한 코어가 모든 매개변수를 지원하거나 원격 서버가 같은 조합을 사용한다는 보장은 없습니다.

    설정을 옮길 때는 프로토콜, 전송 방식, 보안 계층을 먼저 확인한 뒤 사용할 클라이언트와 코어를 선택하세요. 예를 들어 REALITY 설정은 Xray 관련 문서를 기준으로 보안 계층을 점검해야 합니다. 공유 링크에 표시된 프로토콜 이름만으로 전체 설정을 판단하지 마세요. 일반 설정은 연결되는데 특정 노드에서 지원되지 않는다는 오류가 발생한다면 오류 유형을 그대로 확인하고 해당 노드의 필드와 코어 구현을 우선 점검하세요.

  3. 세 오픈소스 클라이언트의 기능

    v2rayN은 구독, 서비스 설정, 프록시 모드, 라우팅을 관리하는 데스크톱 GUI 클라이언트입니다. 사용할 수 있는 코어는 배포 패키지와 설정에 따라 다릅니다. v2rayNG는 Android용으로 주로 Xray 설정을 제공하며, v2flyNG도 Android용이지만 V2Fly 코어를 사용합니다. 세 클라이언트 모두 노드를 관리할 수 있지만 상대 클라이언트의 메뉴, 가져오기 형식, 기본 라우팅이 같다고 가정해서는 안 됩니다.

    처음 설정할 때 Android 클라이언트 두 개를 모두 설치할 필요는 없습니다. 노드 요구 사항에 맞춰 코어를 선택하고 설정 하나를 가져와 기본 연결을 테스트하세요. 두 클라이언트를 비교한다면 네트워크와 접속 대상을 동일하게 유지하고, 매 테스트마다 테스트 대상 클라이언트의 VPN 서비스만 실행 중인지 확인하세요. 그래야 차이가 클라이언트, 코어, 트래픽 처리 방식 중 어디에서 비롯됐는지 구분할 수 있습니다.

  4. 오픈소스 라이선스와 커뮤니티 배포판

    V2Fly의 V2Ray 코어와 Xray-core는 MPL-2.0을 사용합니다. 파일 단위 오픈소스 라이선스로, 적용 대상 코드를 수정해 배포할 때는 라이선스에 따른 소스 코드 공개 의무를 이행해야 합니다. 클라이언트와 코어는 별개의 프로젝트이며 패키지에 포함된 다른 구성 요소도 각자 다른 라이선스를 적용받을 수 있습니다. 이용하거나 재배포할 때는 프로젝트와 배포 패키지에 포함된 구성 요소의 라이선스 고지를 각각 확인하세요. 특정 코어의 라이선스로 클라이언트 전체의 라이선스를 단정해서는 안 됩니다.

    커뮤니티에서는 인터페이스, 코어 구현, 규칙 데이터를 각각 유지보수합니다. 문서에 나온 설정 이름은 기능을 찾기 위한 것으로, 모든 인터페이스의 배치가 같거나 클라이언트 업데이트만으로 구독과 규칙 데이터까지 자동 갱신된다는 뜻은 아닙니다. 패키지를 고를 때는 운영체제, 아키텍처, 코어 기능을 확인하고, 문제를 진단할 때는 로컬 설정과 실제 로그를 기준으로 판단하세요.

  5. 구독, 규칙 데이터, 클라이언트는 각각 따로 업데이트하세요

    클라이언트 업데이트는 프로그램을 바꾸고, 구독 새로고침은 노드 목록을 바꾸며, 규칙 데이터 업데이트는 매칭 데이터를 바꿉니다. 세 가지 작업은 나눠서 진행하는 것이 좋습니다. 업데이트 전에는 작동하는 설정을 백업하고 현재 규칙 세트와 로컬 리스닝 포트를 기록하세요. 업데이트 후에는 같은 대상으로 다시 테스트하고, 로컬 서비스의 직접 연결과 프록시가 필요한 요청이 예상한 경로로 연결되는지 확인합니다.

    구독 업데이트 후 일부 설정만 실패한다면 해당 설정의 전송 매개변수를 비교하세요. 규칙 데이터 업데이트 후 특정 도메인만 잘못 연결된다면 분류가 바뀌었는지, 앞선 규칙이 먼저 적용됐는지 확인합니다. 클라이언트 업데이트 후 모든 요청이 실패한다면 코어 시작 및 리스닝 오류부터 살펴보세요. 재설치, 구독 새로고침, DNS 변경을 한꺼번에 하는 것보다 변경 범위에 맞춰 점검하는 편이 원인을 찾기 쉽습니다.

05 최신 정보 및 문제 해결

최신 설정 및 문제 해결 가이드

시작에 실패하면 로컬 리스너부터 확인하고, 설치에 실패하면 패키지를 점검하세요. 트래픽 경로가 예상과 다르면 라우팅과 규칙 데이터를 확인합니다.

V2Ray 로컬 포트 충돌 해결: 충돌 프로세스 찾기 및 리스닝 포트 변경

시스템 기본 명령으로 10808 및 10809 포트를 사용 중인 프로세스를 찾는 방법, v2rayN에서 로컬 SOCKS 및 HTTP 리스닝 포트를 변경하는 단계, 변경 후 함께 조정해야 하는 설정을 설명합니다.

포트를 바꾸기 전에 해당 포트를 사용 중인 프로그램이 이미 실행된 클라이언트인지 확인하세요. 이전 인스턴스라면 설정을 바꾸기보다 종료한 뒤 다시 실행하는 편이 간단합니다. 두 프로그램을 함께 사용해야 할 때만 각각 다른 포트를 지정하세요. 변경 후에는 같은 앱에서 다시 테스트하고 앱이 이전 프록시 주소를 계속 사용하는지 확인합니다.

v2rayN Windows 설치 및 설정 전체 과정: WPF 버전과 Desktop 버전 선택하기

패키지 선택, 압축 해제, 첫 실행, 구독 가져오기까지 단계별로 안내합니다. WPF 버전과 Desktop 버전의 차이를 비교하고 런타임 누락, 백신 차단, 경로에 한글이 포함된 경우 등 자주 발생하는 문제도 정리합니다.

첫 실행을 기준으로 문제를 나눠 확인하세요. 화면이 나타나지 않으면 실행 환경부터 살펴보고, 화면은 나오지만 노드가 없다면 가져오기와 구독 업데이트를 점검합니다. 두 문제는 확인해야 할 안내 메시지가 서로 다릅니다.

GeoIP 및 GeoSite 규칙 데이터 업데이트와 라우팅 규칙 작성법

geoip.dat와 geosite.dat의 용도, 클라이언트에서 규칙 데이터를 업데이트하는 위치, geosite:cn 및 geoip:private 등 자주 쓰는 규칙을 라우팅에서 조합하는 방법을 소개합니다.

규칙을 검증할 때는 도메인 요청과 IP 주소를 직접 사용하는 요청을 각각 준비하세요. 둘 중 한쪽만 예상과 다르게 연결된다면 매칭 대상과 규칙 유형이 일치하는지 먼저 확인합니다.

클라이언트 다운로드