설정 가이드 · 커널과 클라이언트
V2Ray 설정 파일 가이드
로컬 인바운드부터 아웃바운드 선택까지, 연결 단계별 설정과 문제 해결 단서를 살펴봅니다.
처음 설치하거나 구독을 가져오고 연결을 확인하려면 v2rayN 빠른 시작 가이드를 참고하세요. 이 문서는 특정 필드를 확인할 때 찾아보는 안내서입니다. 앞의 여섯 장에서는 커널이 읽는 JSON을, 마지막 두 장에서는 GUI 클라이언트의 커널 선택, 구독 관리, 트래픽 처리 방식을 다룹니다. 예시는 V2Fly와 Xray에서 흔히 공통으로 쓰이는 필드를 중심으로 구성했습니다. 각 기능의 지원 여부는 현재 실행 중인 커널을 기준으로 확인하세요.
JSON 구조와 연결 처리 순서
먼저 커널이 읽은 설정 파일을 확인하세요
v2rayN에서 서버 항목, 구독 정보, 인터페이스 환경설정은 클라이언트가 관리합니다. 반면 커널이 실제로 읽는 것은 시작할 때 전달된 설정입니다. 항목을 인터페이스에 저장할 수 있다고 해서 클라이언트가 입력을 받아들였다는 뜻일 뿐, 커널이 생성된 설정을 받아들였다는 의미는 아닙니다. 문제를 확인할 때는 현재 선택한 항목과 실행 중인 커널, 로그의 시작 시각이 서로 일치하는지 먼저 살펴보세요. 임시 생성 파일을 수정했다면 항목을 다시 선택하거나 재시작할 때 파일이 다시 만들어질 수 있습니다. 변경 사항을 유지하려면 클라이언트가 지원하는 설정 위치를 사용하거나 직접 관리하는 설정 사본에 저장하세요.
최소 설정: 로컬 접속과 직접 연결
{
"log": { "loglevel": "warning" },
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": { "auth": "noauth", "udp": false }
}
],
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
}
다음은 설정을 비교하기 위한 독립 예시입니다. 앱이 로컬 SOCKS 리스너에 연결을 보내면 커널은 freedom 아웃바운드로 원격 서버를 거치지 않고 목적지에 직접 연결합니다. 테스트 전에는 예시 포트가 비어 있는지 확인하세요. 실행 중인 v2rayN이 이미 해당 포트를 사용한다면 프로세스를 추가로 실행할 때 충돌이 발생합니다. 테스트 앱이 실제로 이 SOCKS 주소를 사용하는지도 확인해야 합니다. 웹페이지가 열린다는 사실만으로 설정이 유효하다고 단정할 수는 없습니다. 앱이 프록시를 전혀 사용하지 않았을 수도 있기 때문입니다. 반대로 기존 프로세스가 리스너 포트를 사용 중이라면 연결에 성공해도 방금 실행한 프로세스에 연결된 것이라고 볼 수 없습니다.
필드의 위치와 값 유형 구분하기
최상위는 객체이며 inbounds와 outbounds는 각각 인바운드와 아웃바운드를 정의하는 항목들의 배열입니다. routing, dns, policy는 객체로, 내부에 배열이나 이름별 하위 객체를 포함할 수 있습니다. settings의 해석은 해당 항목의 protocol에 따라 달라집니다. 이름이 같은 settings라도 SOCKS 인바운드의 인증 구조를 다른 프로토콜에 그대로 옮겨 쓸 수는 없습니다. 포트는 숫자로, 스위치는 따옴표 없는 불리언 값으로, 태그는 문자열로 입력합니다. 설정을 직접 합칠 때는 최상위에 같은 이름의 배열을 새로 만들지 말고 기존 배열에 항목을 추가하세요. 키가 중복되면 뒤에 나온 값이 앞의 값을 덮어써 설정 앞부분이 있어도 적용되지 않을 수 있습니다.
설정은 표준 JSON 형식으로 저장하는 것이 좋습니다. 키와 문자열은 큰따옴표로 묶고, 배열이나 객체의 마지막 항목 뒤에는 쉼표를 붙이지 않으며, 주석도 넣지 마세요. 엄격한 검사를 지원하는 편집기를 사용하면 이런 오류를 미리 찾을 수 있지만, 문법 검사를 통과했다고 해서 텍스트를 파싱할 수 있다는 뜻일 뿐입니다. 프로토콜 지원 여부, 태그 해석, 포트 바인딩은 커널을 불러오고 실제 연결해 확인해야 합니다. 오류가 연이어 나타나면 최초 시작 실패 시점의 첫 오류부터 살펴보세요. 이후의 연결 실패, 재시도, 종료 메시지는 앞선 오류의 연쇄 반응일 수 있습니다.
변경 사항을 다시 확인할 수 있도록 하나의 실험으로 기록해 두세요. 인바운드 포트, 테스트 앱, 대상 도메인, 예상 아웃바운드, 실제 결과를 적으면 됩니다. 변경 후 실패하면 해당 항목만 원래대로 돌리고 같은 대상으로 재시도하세요. 그래야 대상 서비스의 일시적인 문제를 설정 변경의 영향으로 오해하지 않습니다. ‘실행 중’ 아이콘을 전체 연결 경로가 정상이라는 증거로 보아서는 안 됩니다. 아이콘만으로는 요청이 커널에 들어갔는지, 예상한 라우팅을 거쳤는지 알 수 없습니다.
inbounds 인바운드: 리스너와 앱 연결
수신 주소에 따라 연결 가능한 범위가 달라집니다
listen은 커널이 연결을 받을 로컬 주소를 지정합니다. 이 컴퓨터의 앱만 연결해야 한다면 127.0.0.1에 명시적으로 바인딩할 수 있습니다. 이는 모든 IPv4 인터페이스에 바인딩하는 것과 다르며 IPv6 루프백 주소에 바인딩하는 것과도 다릅니다. 앱이 localhost를 IPv6 주소로 해석하고 커널은 IPv4만 수신 대기한다면 앱에 연결 거부 오류가 나타날 수 있습니다. 먼저 앱 주소를 리스너와 같은 루프백 주소로 지정해 비교하세요. 로컬 테스트를 통과시키려고 수신 범위를 넓히지 마세요. 관리되는 LAN 연결이 꼭 필요하다면 인터페이스 범위, 접근 제한, 인증을 별도로 검토해야 하며 아래 로컬 예시를 그대로 사용해서는 안 됩니다.
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": { "auth": "noauth", "udp": false }
},
{
"tag": "local-http",
"listen": "127.0.0.1",
"port": 10809,
"protocol": "http",
"settings": {}
}
]
이 코드는 개요 예시의 inbounds 필드를 바꿔 넣어 사용할 수 있습니다. 두 숫자는 비교를 위한 예시일 뿐 현재 클라이언트가 반드시 사용하는 포트는 아닙니다. 실제 포트는 설정과 시작 로그를 기준으로 확인하세요. 같은 주소에서 두 종류의 리스너를 제공해야 한다면 포트를 각각 지정하고 서로 다른 tag를 사용하세요. 앱은 포트 번호만으로 프록시 프로토콜을 구분할 수 없습니다. HTTP 프록시를 SOCKS 포트로 지정하면 하위 연결이 만들어지더라도 이후 핸드셰이크는 실패합니다.
| 필드 | 예시 | 확인할 사항 |
|---|---|---|
| listen | 127.0.0.1 | 주소가 테스트 앱의 프록시 대상과 일치하는지 확인합니다. |
| port | 10808 | 다른 프로세스가 포트를 사용 중이지 않은지 확인합니다. |
| protocol | socks | 앱에서 선택한 프록시 유형과 일치하는지 확인합니다. |
| tag | local-socks | 로그에서 식별하고 라우팅 규칙에서 참조할 때 사용합니다. |
시스템 프록시와 UDP를 각각 확인해야 하는 이유
시스템 프록시는 운영체제가 앱에 제공하는 설정일 뿐, 운영체제가 모든 트래픽을 강제로 전달한다는 뜻은 아닙니다. 자동 설정을 켠 뒤에도 대상 앱이 시스템 프록시를 따르는지, 시스템 예외 목록에서 제외되지 않았는지 확인하세요. 일부 도구는 자체 프록시 설정이나 환경 변수를 우선 사용하며, 브라우저 설정은 확장 프로그램이나 관리 정책에 따라 달라질 수 있습니다. ‘한 앱은 되는데 다른 앱은 안 된다’면 서버 설정부터 바꾸기보다 프록시 유형과 포트를 직접 지정할 수 있는 앱으로 리스너를 확인한 뒤, 문제가 있는 앱이 실제로 어떤 설정을 사용하는지 살펴보세요.
위 SOCKS 예시는 UDP를 명시적으로 비활성화합니다. 적용 가능한 환경에서 SOCKS의 UDP 기능을 켜더라도 앱이 해당 SOCKS 연관 방식을 사용해야 하며 이후의 아웃바운드와 연결 경로도 해당 트래픽을 지원해야 합니다. 일반 HTTP 프록시 테스트는 테스트한 HTTP 요청이나 TCP 터널이 동작한다는 점만 보여줍니다. 실시간 통화나 기타 비연결형 트래픽까지 정상이라는 뜻은 아닙니다. 앱, 프로토콜, 인바운드별로 테스트 결과를 기록하면 한 가지 성공 사례로 모든 증상을 설명하는 일을 피할 수 있습니다.
종료 전에 시스템 프록시를 수동으로 설정한 적이 있다면 예상대로 원래 설정이 복구됐는지 확인하세요. 남아 있는 루프백 주소는 유효한 프록시처럼 보이지만 실제로는 연결을 받을 프로세스가 없을 수 있습니다. 클라이언트를 종료한 뒤 브라우저가 인터넷에 연결되지 않는다면 문제 해결 FAQ에서 시스템 프록시와 로컬 리스너 관련 항목을 먼저 확인해 앱이 인바운드에 연결하지 못한 것인지, 인바운드 이후의 경로에 문제가 있는지 구분하세요.
outbounds 아웃바운드: 프로토콜, 태그, 전송 방식
검증 가능한 아웃바운드로 기준 상태 만들기
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} },
{ "tag": "block", "protocol": "blackhole", "settings": {} }
]
freedom은 외부에 직접 연결할 때 사용하고, blackhole은 지정된 규칙에 일치하는 요청을 차단할 때 사용할 수 있습니다. 두 단어는 프로토콜 값입니다. 반면 direct와 block은 규칙에서 참조하는 사용자 지정 태그이며 클라이언트에 내장된 동작 스위치가 아닙니다. 아웃바운드 배열에 block을 넣는 것만으로 모든 요청이 차단되지는 않습니다. 특정 트래픽에 적용하려면 해당 아웃바운드를 지정하는 라우팅 규칙도 필요합니다. 일치하는 규칙이 없으면 일반적으로 첫 번째 아웃바운드가 사용됩니다. 목록 순서를 바꾸면 기본 동작이 달라질 수 있으므로 기본 아웃바운드를 쉽게 확인할 수 있는 위치에 두세요.
원격 아웃바운드는 세 가지 매개변수 층으로 나눠 확인하세요
사용 권한이 있는 연결 정보를 가져온 뒤 생성된 설정을 세 층으로 나눠 살펴보세요. 첫째는 원격 주소, 포트, 프로토콜에 필요한 인증 정보를 포함하는 애플리케이션 프로토콜입니다. 둘째는 프로토콜 데이터를 전달하는 전송 방식입니다. 셋째는 선택한 전송 방식에 적용되는 보안 설정입니다. 원격 주소는 실제 연결 대상이고, 보안 핸드셰이크의 서버 이름은 상대편이 요구하는 이름을 확인하는 데 쓰입니다. 두 값은 같을 수도, 다를 수도 있습니다. 구독에 표시된 이름은 식별용 메모일 수 있으므로 서버 주소나 핸드셰이크 이름으로 그대로 사용하지 마세요.
protocol과 settings는 아웃바운드 프로토콜 자체를 설명하고, 해당되는 전송 및 보안 매개변수는 보통 streamSettings에 들어갑니다. 예를 들어 인터페이스에서 연결이 특정 전송 방식을 사용한다고 표시되더라도 다른 연결의 경로를 그대로 복사할 수 있다는 뜻은 아닙니다. 경로, 이름, 핸드셰이크 방식은 실제 서비스의 요구사항을 따라야 합니다. 인증서 오류를 피하려고 검증을 끄지 마세요. 먼저 시스템 시간, 상대편 이름, 인증서 체인을 확인한 뒤 클라이언트가 올바른 전송 방식을 선택했는지 살펴보세요. 두 커널에서 프로토콜 필드나 전송 유형 이름이 비슷해도 모든 조합을 서로 바꿔 쓸 수 있는 것은 아닙니다.
로그와 테스트 결과를 실패 단계에 맞춰 확인하기
로컬 인바운드에 요청이 도착했는데 로그에 아웃바운드를 찾을 수 없다고 표시된다면 라우팅에 적힌 태그를 확인하세요. 대소문자, 앞뒤 공백, 중복 이름, 업데이트 전 태그를 참조하는 규칙을 특히 주의해야 합니다. 원격 주소로 연결을 시도한 로그가 있다면 도메인 확인 실패, 연결 시간 초과, 핸드셰이크 실패를 구분하세요. 도메인 확인 실패는 연결 가능한 주소를 얻기 전 발생합니다. 연결 시간 초과는 경로, 네트워크 상태, 상대편 리스너와 관련될 수 있습니다. 핸드셰이크 실패라면 프로토콜 매개변수가 서비스와 일치하는지 확인하는 것이 좋습니다. 일반적인 ‘연결 실패’ 메시지만으로는 어느 단계에 문제가 생겼는지 판단하기 어렵습니다.
원격 아웃바운드를 테스트할 때는 동일한 요청으로 먼저 인바운드를 확인한 다음 전체 연결 테스트와 비교하세요. 포트 연결 성공은 테스트 시점에 해당 연결이 만들어졌다는 뜻일 뿐, 이후 프로토콜 핸드셰이크나 다운로드 속도를 보장하지 않습니다. Tcping, 실제 연결 지연 시간, 속도 테스트 결과의 차이에서 테스트마다 확인할 수 있는 범위를 설명합니다. 테스트 대상이 불안정하다면 성격이 비슷한 대상을 추가해 비교할 수 있습니다. 다만 대상을 바꾸는 동시에 아웃바운드 매개변수까지 변경하면 결과의 원인을 파악하기 어렵습니다.
아웃바운드가 여러 개라면 각 항목에 안정적이고 중복되지 않는 태그를 지정하고, 일회성 속도 측정 결과가 아니라 용도를 태그에 담으세요. 아웃바운드 정보를 업데이트한 뒤에는 모든 참조를 다시 확인해야 합니다. 특히 직접 작성한 라우팅 규칙을 주의 깊게 살펴보세요. 로그를 동료에게 전달해 문제를 확인할 때는 원격 인증 정보, 구독 주소, 요청 세부 정보를 먼저 삭제하세요. 오류 유형과 인바운드·아웃바운드 태그만으로도 다음에 확인할 설정 층을 찾을 수 있는 경우가 많습니다.
routing 라우팅: 일치 순서와 대상 유형
위에서 아래로 확인하고 처음 일치한 규칙에서 멈춥니다
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-http"],
"domain": ["full:example.org"],
"outboundTag": "block"
},
{
"type": "field",
"domain": ["domain:example.org"],
"outboundTag": "direct"
}
]
}
이 코드는 앞의 두 장에서 다룬 인바운드 및 아웃바운드 예시와 함께 사용하며, 순서를 설명하기 위해 예시 도메인을 사용합니다. 첫 번째 규칙은 요청이 local-http에서 들어오고 라우팅 대상 이름이 정확히 example.org일 때만 일치합니다. 두 조건이 모두 충족되면 block으로 보냅니다. 같은 도메인에 대한 요청이 local-socks에서 들어오면 첫 번째 규칙은 일치하지 않고 두 번째 규칙이 적용될 수 있습니다. 하위 도메인 요청도 두 번째 규칙에 일치합니다. 두 규칙의 순서를 바꾸면 더 넓은 도메인 규칙이 정확한 도메인 규칙보다 먼저 적용되어 결과가 달라집니다.
정확한 도메인, 도메인 접미사, IP 대역 구분하기
full:은 도메인 전체가 정확히 일치하는지 확인하고, domain:은 지정한 도메인과 하위 도메인에 일치합니다. 문자열의 임의 위치에 포함되는지 확인하는 기능은 아닙니다. 정규식이 필요하면 regexp:를 사용할 수 있지만, 먼저 일치해야 하는 예시와 일치하면 안 되는 예시를 정리하세요. 백슬래시 일부는 JSON 문자열에서 이스케이프해야 합니다. geosite:는 도메인 데이터 집합을, geoip:는 IP 데이터 집합을 참조합니다. 사용 가능 여부는 실행 환경에 해당 데이터와 관련 태그가 있는지에 따라 달라집니다. 규칙을 복사하기 전에 데이터 출처를 확인해 데이터 로딩 실패를 일치 순서 문제로 오해하지 않도록 하세요.
ip는 평문 대상 IP나 CIDR 주소 대역과 일치시킬 수 있습니다. IP 규칙을 작성하기 전에 앱이 인바운드에 도메인을 전달하는지, 이미 해석된 주소를 전달하는지 확인하세요. 앱이 먼저 주소를 해석했다면 라우팅에서 원래 도메인을 확인할 수 없을 수도 있습니다. 하나의 IP 주소를 여러 도메인이 공유할 수 있으므로 접속한 사이트를 정확히 역추적하기는 어렵습니다. 반대로 인바운드가 도메인을 받았다면 해당 도메인의 해석 결과를 IP 규칙에 사용할 수 있는지는 domainStrategy와 커널 DNS가 정상인지에 따라 달라집니다.
domainStrategy가 도메인 확인 시점에 미치는 영향
AsIs는 라우팅을 위해 대상 도메인을 추가로 확인하지 않습니다. IPIfNonMatch는 현재 대상으로 규칙이 일치하지 않을 때 도메인을 확인한 뒤 다시 일치 여부를 판단할 수 있습니다. 따라서 앞쪽 규칙이 먼저 일치하거나 모든 트래픽을 잡는 기본 규칙이 첫 검사에서 일치하면 예상한 IP 규칙을 확인할 기회가 없을 수 있습니다. IPOnDemand는 일치 여부를 판단하는 데 IP 정보가 필요한 규칙을 확인할 때 도메인을 조회합니다. 정책을 고르기 전에 해석된 IP 주소를 실제로 판단에 사용할 필요가 있는지 먼저 확인하세요. 불필요한 조회는 시간 초과가 발생할 수 있는 단계를 추가할 뿐이며 기존 도메인 규칙이 일치하지 않는 이유를 설명하지 못할 수도 있습니다.
규칙을 조합할 때 같은 필드의 후보 값은 보통 그중 하나와 일치하면 됩니다. 반면 같은 규칙 안의 서로 다른 조건은 모두 충족해야 합니다. 특정 도메인과 IP 대역을 같은 아웃바운드로 보내려면 각각의 규칙에서 해당 아웃바운드를 지정하는 편이 명확합니다. 도메인과 IP 조건을 한 규칙에 함께 적으면 ‘또는’으로 처리된다고 가정하지 마세요. 수정 후에는 설정을 다시 불러오고 실제 아웃바운드를 확인해야 합니다. 문법은 사용자 지정 라우팅 규칙의 일치 문법과 우선순위에서 더 자세히 살펴볼 수 있습니다.
dns 설정: 조회 경로, 정적 매핑, 대체 동작
브라우저, 커널, 시스템의 도메인 확인은 서로 다릅니다
시스템 DNS는 일반적으로 시스템 DNS API를 사용하는 프로그램에 조회 결과를 제공합니다. 브라우저나 다른 앱은 자체 캐시를 사용하거나 별도의 조회 서비스를 이용할 수도 있습니다. 커널의 dns 설정은 커널이 직접 이름을 확인해야 하는 상황에 사용됩니다. 예를 들어 일부 라우팅 정책은 도메인 확인 결과의 IP를 기준으로 IP 규칙을 판단합니다. 설정 파일에 DNS가 있다고 해서 컴퓨터 전체의 조회를 가로채는 것은 아닙니다. 테스트 앱이 마지막에 IP 주소만 인바운드에 전달한다면 앞선 조회는 이미 앱이나 시스템에서 끝났을 수 있습니다. 이 경우 커널 DNS를 수정해도 같은 요청의 대상이 도메인으로 바뀌지는 않습니다.
"dns": {
"hosts": {
"example.org": "192.0.2.10"
},
"servers": ["localhost"],
"queryStrategy": "UseIP"
}
다음은 최상위 dns 필드의 독립 예시입니다. hosts는 커널 내부의 정적 매핑을 보여주며, 예시 주소는 문서용 주소 대역이므로 실제 연결 테스트에 사용할 수 없습니다. 이 매핑을 유지하면 해당 이름에 대한 커널 조회에서 실제 서비스 주소가 반환될 것으로 기대해서는 안 됩니다. 일반 테스트에서는 매핑을 삭제할 수 있습니다. 여기서 localhost는 로컬 시스템의 이름 확인 기능을 사용하는 특수 값이지 DNS 패킷을 루프백 주소로 보내는 축약 표현이 아닙니다. UseIP는 한 주소 계열로 조회를 제한하지 않으며 두 주소 유형을 모두 받는다고 보장하지도 않습니다. 결과는 상위 DNS 응답과 대상 레코드에 따라 달라집니다.
사용되는 조회 경로는 상황별로 확인하세요
라우팅 판단을 위해 얻은 IP 주소와 최종 아웃바운드가 연결에 사용하는 주소는 서로 다를 수 있습니다. 라우팅에서는 IP 규칙을 판단할 목적으로만 주소를 조회하고, 아웃바운드는 원래 도메인을 사용해 직접 조회하거나 상대편에서 처리하도록 할 수 있습니다. 예를 들어 freedom의 도메인 처리 옵션과 routing.domainStrategy는 서로 다른 단계에 속합니다. 두 설정을 전역 스위치 하나처럼 취급하지 마세요. 어느 단계에서 이름을 확인했는지 알아보려면 다른 테스트 트래픽을 끈 뒤 인바운드에 들어온 대상, 일치한 규칙, 아웃바운드 로그를 함께 확인하세요.
여러 조회 경로를 사용하더라도 배열 순서에 따라 차례대로 다시 시도하는 목록으로 단순하게 보아서는 안 됩니다. 일부 설정은 DNS 서버마다 적용할 도메인을 지정하거나 대체 조회에 사용할지 제한할 수 있습니다. 예상한 DNS 서버에 도메인이 일치하지 않는 경우, 서버가 시간 초과되는 경우, 빈 결과를 반환하는 경우는 서로 다릅니다. 세부 옵션을 조정할 때는 현재 커널이 인식하는 필드를 기준으로 동작을 확인하세요. 다른 커널의 설정을 그대로 가져오지 마세요. 정상 작동이 확인된 조회 서버 하나로 시작해 기본 조회부터 확인한 다음, 도메인 조건을 추가하고 일치하는 경우와 일치하지 않는 경우를 각각 비교하세요.
캐시, 주소 계열, 시작 단계의 의존성 확인하기
설정을 바꿨는데도 결과가 그대로라면 테스트 앱이나 커널에 이전 캐시가 남아 있거나 기존 연결을 재사용하는지 먼저 확인하세요. 같은 도메인을 다시 테스트할 때는 앱 연결을 새로 만들고 조회와 연결 시각을 기록하세요. IPv6 주소를 받았는데 연결할 수 없다고 해서 DNS가 잘못된 것은 아닙니다. 아웃바운드에 해당 IPv6 네트워크로 연결할 경로가 없을 수도 있습니다. 주소 조회 여부, 라우팅 선택, 해당 주소에 실제로 연결할 수 있는지를 각각 확인한 뒤 조회할 주소 계열을 제한할지 판단하세요.
시작 단계에서 막히는 경우도 흔합니다. 상위 서버나 원격 엔드포인트를 도메인으로 지정했는데, 해당 이름을 확인하려면 아직 연결되지 않은 연결이 필요한 상황입니다. 이런 경우 DNS 서버 주소를 몇 개 더 추가하는 것만으로 해결되지 않습니다. 의존 관계를 정리해 어떤 조회가 연결 전에 완료되어야 하는지, 해당 조회에 독립적으로 사용할 수 있는 경로가 있는지 확인하세요. Tun 모드를 켜면 조회가 사용하는 인터페이스가 달라질 수 있으므로 이 부분도 다시 검증해야 합니다. 시스템 인터페이스에 어떤 DNS 주소가 입력되어 있는지만으로는 충분하지 않습니다.
policy 정책: 시간 초과, 사용자 레벨, 통계
레벨별 연결 수명 설정
"policy": {
"levels": {
"0": {
"handshake": 4,
"connIdle": 300,
"uplinkOnly": 2,
"downlinkOnly": 5
}
}
}
다음은 최상위 policy 예시이며 특정 아웃바운드의 settings가 아닙니다. levels는 문자열 키로 레벨을 표시합니다. 여기서는 필드의 의미를 보여주기 위해 레벨 0을 사용하고 시간 단위는 초로 표시했습니다. 모든 환경에 권장하는 조정값은 아닙니다. 프로토콜마다 설정에서 사용자 레벨을 지정하는 위치가 다를 수 있습니다. 특정 레벨을 바꿨는데 변화가 없다면 테스트 중인 연결이 실제로 해당 레벨을 사용하는지, 실행 중인 커널이 관련 단계에 해당 정책을 적용하는지 먼저 확인하세요. 정책은 주로 연결 수명과 통계 동작을 제어하며 아웃바운드를 선택하거나 사용자에게 접근 권한을 부여하지는 않습니다.
| 필드 | 적용되는 단계 | 자주 하는 오해 |
|---|---|---|
handshake | 해당 프로토콜의 핸드셰이크 단계입니다. | 도메인 조회, 연결, 웹페이지 로드를 모두 포함하는 전체 제한 시간이 아닙니다. |
connIdle | 연결에 데이터가 오가지 않는 상태입니다. | 연결을 유지할 수 있는 전체 시간이 아닙니다. |
uplinkOnly | 다운로드가 끝나고 업로드만 남은 상태입니다. | 업로드 속도 제한이 아닙니다. |
downlinkOnly | 업로드가 끝나고 다운로드만 남은 상태입니다. | 다운로드 버퍼 크기가 아닙니다. |
핸드셰이크 실패, 유휴 종료, 한쪽 방향 종료 구분하기
처음 연결할 때 가끔 실패하는 문제와 한동안 정상 작동하다 끊기는 연결 문제는 서로 다를 수 있습니다. 데이터가 끊긴 시점과 업로드 또는 다운로드가 계속되는지, 재연결이 즉시 복구되는지를 기록하세요. 일정한 유휴 시간에 가까워질 때마다 문제가 발생한다면 커널의 유휴 정책뿐 아니라 앱, 원격 서비스, 중간 네트워크 장비가 연결을 종료했을 가능성도 있습니다. 로컬 정책의 시간을 늘려도 상대편이나 네트워크 장비의 시간 초과 동작은 바뀌지 않습니다. 반대로 시간을 줄였을 때 연결이 더 일찍 끊기는 현상은 단서가 될 수 있지만, 테스트 중 네트워크를 바꾸거나 설정을 업데이트하지 않았는지도 확인해야 합니다.
오랫동안 데이터를 보내지 않는 앱이라면 정책을 바꾸기 전에 자체 연결 유지 기능이 있는지 확인하세요. 유휴 연결을 유지하면 리소스를 소비하고 시간 초과 값을 무조건 크게 설정하면 이미 끊어진 연결을 늦게 발견할 수도 있습니다. 다른 사람의 설정을 그대로 가져오기보다 같은 네트워크에서 같은 앱으로 새 연결을 만들어 기준 결과를 확인한 뒤 증상과 관련된 필드 하나만 조정하세요. 기존 연결은 이전 설정을 유지할 수 있으므로 비교하기 전에 설정을 다시 불러오고 새 세션을 만들어야 합니다.
통계 활성화와 통계 조회는 별도로 설정합니다
전송 방향을 진단하려면 policy.levels에서 사용자 레벨별로 제어하는 통계 옵션과 policy.system에서 인바운드 또는 아웃바운드 방향별로 제어하는 시스템 통계 옵션을 구분할 수 있습니다. 통계 옵션을 설정해도 GUI에 수치가 표시된다는 보장은 없습니다. 관련 기능을 지원하는 커널에서 통계를 활성화해야 하고 클라이언트도 호환되는 방식으로 읽어야 합니다. 태그가 비어 있거나 관찰 대상을 잘못 선택했거나 재시작 후 카운터가 초기화되면 예상과 다른 값이 나올 수 있습니다. 일부 인터페이스는 여러 연결을 합산하므로 수치가 증가했다는 사실만으로 특정 앱 요청이 어떤 아웃바운드를 사용했는지 확인할 수는 없습니다.
통계와 로그를 사용할 때는 실제 진단에 필요한 범위만 수집하세요. 하나의 연결을 확인하려고 상세 액세스 로그를 장시간 남기면 불필요한 대상 주소와 접속 시각이 쌓일 수 있습니다. 관리 인터페이스에서 통계를 조회할 때는 제대로 격리되지 않은 관리용 포트를 외부 네트워크에 공개하지 마세요. 문제를 찾은 뒤에는 평소 로그 수준으로 되돌리고 임시 통계 설정을 해제하세요. 증상, 변경 사항, 결론만 적은 간단한 기록을 남겨 두면 다음에 같은 문제가 발생했을 때 더 쉽게 확인할 수 있습니다.
커널 선택과 구독 설정의 차이
클라이언트 이름보다 실제 실행 중인 커널을 먼저 확인하세요
데스크톱에서는 v2rayN 설치 패키지부터 시작해 운영체제와 프로세서 아키텍처에 맞는 항목을 선택하세요. 클라이언트는 인터페이스, 구독 관리, 설정 저장을 담당하고 커널은 불러온 프로토콜 설정과 연결을 처리합니다. Android의 v2rayNG는 Xray 커널을 사용하며, v2flyNG는 V2Fly 커널을 사용하는 대안 클라이언트입니다. Project V는 이 생태계를 이해하는 출발점입니다. V2Fly는 V2Ray 커뮤니티 유지보수 흐름을 이어가고, Xray는 관련 코드에서 발전해 독립 프로젝트가 되었습니다. 필드 이름이 같아도 커널마다 지원하는 프로토콜 조합, 전송 방식, 추가 옵션이 항상 일치하지는 않습니다.
인터페이스 선택 문제인지 커널 로딩 문제인지 판단하려면 이번 실행의 시작 기록이 가장 유용합니다. 로그가 현재 선택한 설정에 해당하는지 확인한 다음 예상한 커널이 실행 중인지 살펴보세요. 커널을 바꾼 뒤 알 수 없는 프로토콜이나 전송 방식, 필드 유형 오류가 나타나더라도 해당 필드를 바로 삭제하지 마세요. 원격 서비스에 연결하는 데 필요한 필드일 수 있으며, 이를 지우면 시작 실패가 이후 핸드셰이크 실패로 바뀔 뿐입니다. 이미 작동이 확인된 커널과 항목으로 먼저 되돌린 뒤 호환성을 하나씩 확인하는 편이 안전합니다.
공통 필드로 로컬 비교하기
"log": { "loglevel": "warning" },
"outbounds": [
{ "tag": "direct", "protocol": "freedom", "settings": {} }
]
다음 예시는 커널 최상위 설정의 일부로 로그와 직접 연결만 설명합니다. 완전히 테스트하려면 개요에 있는 로컬 인바운드와 함께 사용해야 합니다. 독립 테스트 설정에서 공통 필드와 로컬 리스너가 정상인지 확인한 다음 실제 항목으로 돌아가 차이를 비교할 때 적합합니다. 기존 설정 끝에 붙여 중복 필드를 만들거나 GUI 클라이언트가 생성한 실제 아웃바운드 목록을 덮어쓰지 마세요. 데스크톱 인터페이스 선택은 v2rayN 데스크톱판과 WPF판 선택 가이드를 참고하세요. 인터페이스 프레임워크 선택과 커널의 프로토콜 지원은 서로 다른 기준입니다.
구독 그룹, 새로고침, 로컬 변경 사항
구독 그룹은 클라이언트에서 출처와 항목을 정리하는 기능이며 커널 설정의 최상위 필드가 아닙니다. 구독을 새로고침하면 클라이언트가 사용 권한이 있는 출처에서 내용을 가져와 가져오기를 시도합니다. 새로고침은 콘텐츠 가져오기, 항목 파싱, 인터페이스의 목록 업데이트 단계로 나눠 볼 수 있으며, 어느 단계에서든 오류가 나면 목록이 바뀌지 않은 것처럼 보일 수 있습니다. 새로고침이 성공했다는 것은 가져오기와 등록 경로가 작동한다는 뜻일 뿐 모든 항목의 연결 성공을 의미하지 않습니다. 반대로 이미 가져온 항목으로 일시적으로 연결할 수 있어도 현재 구독 주소에서 계속 새로고침할 수 있다는 보장은 없습니다.
구독 항목을 직접 수정하면 다음 새로고침 때 출처의 데이터가 로컬 변경 사항을 덮어쓸 수 있습니다. 구체적인 동작은 클라이언트의 병합 방식에 따라 달라집니다. 비교 테스트가 필요하다면 사용 권한이 있는 항목을 명확히 구분되는 로컬 테스트 사본에 복사하고 변경 내용을 기록하세요. ‘업데이트 후 잘못된 항목으로 연결된다’면 메모 이름만 믿지 말고 그룹, 선택 상태, 실제 시작 기록을 확인하세요. 서로 다른 출처가 같은 메모 이름을 사용할 수 있습니다. 문제 해결을 위해 스크린샷을 공유할 때는 전체 구독 주소, 인증 정보, 각 항목의 원격 정보를 가리세요.
처음 가져올 때는 빠른 시작 가이드의 가져오기 절차를 따르면 됩니다. 프로토콜 필드를 직접 작성할 필요는 없습니다. 새 구독에 문제가 있고 기존 구독은 정상이라면 라우팅과 커널을 동시에 수정하지 말고 출처에 접속할 수 있는지, 클라이언트가 내용을 인식하는지 따로 확인하세요. 문제 원인이 정보 가져오기, 파싱 및 등록, 설정 생성, 연결 수립 중 어디에 있는지 파악한 뒤 이 가이드의 해당 장을 살펴보세요.
Tun 모드: 가상 인터페이스, 시스템 라우팅, 검증
인터페이스 트래픽 처리와 커널 라우팅 구분하기
시스템 프록시는 앱이 운영체제에서 제공하는 프록시 설정을 사용해야 작동합니다. Tun 모드는 가상 네트워크 인터페이스와 시스템 라우팅을 사용해 선택한 트래픽을 처리 경로로 보냅니다. 먼저 운영체제가 패킷을 어느 인터페이스로 보낼지 결정하고, 트래픽이 해당 구성 요소에 들어온 뒤에야 커널이 규칙에 따라 아웃바운드를 선택할 수 있습니다. 이 두 단계는 서로 대체할 수 없습니다. 커널 규칙을 직접 연결로 바꿔도 패킷이 가상 인터페이스를 먼저 지나는 것을 막지는 못합니다. 반대로 시스템 계층에서 트래픽을 가상 인터페이스로 보내지 않으면 커널 규칙을 바꿔도 해당 트래픽에 영향을 주지 못할 수 있습니다.
확인된 인바운드로 트래픽 처리 문제 구분하기
"routing": {
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
이 코드는 커널 라우팅 예시로, 앞에서 정의한 local-socks와 direct를 참조합니다. Tun 설정이 아닙니다. 독립 설정에 넣고 제어 가능한 로컬 인바운드로 라우팅 인식을 확인한 뒤 가상 인터페이스를 통한 연결 테스트와 비교할 수 있습니다. 두 방식 모두 같은 기본 아웃바운드로 연결된다면 대상에 접속할 수 있는지만으로 규칙이 실제로 일치했는지 알 수 없습니다. 로그에서 인바운드와 아웃바운드를 함께 확인하세요. 가상 인터페이스가 트래픽을 처리한 뒤에도 인바운드가 local-socks일 것이라고 가정하지 마세요. 클라이언트가 생성한 설정과 기록을 바탕으로 실제 처리 경로를 확인해야 합니다.
켜기 전, 켠 뒤, 끈 뒤 세 번 확인하세요
기능을 켜기 전에 같은 테스트에 영향을 줄 수 있는 다른 트래픽 처리 도구를 종료하고, 평소 연결 상태를 기록하세요. 새 모드를 끌 수 있는지도 확인해야 합니다. 활성화 과정에서 권한 오류나 가상 인터페이스 생성 오류가 발생하면 현재 사용자 권한, 시스템 제한, 클라이언트 시작 기록을 먼저 확인하세요. 스위치가 켜져 있다는 것은 인터페이스 상태만 나타냅니다. 가상 인터페이스가 실제로 생성됐는지, 필요한 라우팅이 설정됐는지도 확인해야 합니다. 기존 시스템 프록시가 켜져 있으면 테스트 앱이 시스템 라우팅에 직접 전달하는 대신 루프백 프록시에 연결할 수 있습니다. 이 상태에서 테스트에 성공해도 Tun 경로가 적용됐다는 증거가 되지는 않습니다.
활성화 후에는 테스트를 두 그룹으로 나눌 수 있습니다. 하나는 새 인터페이스로 처리해야 하는 요청이고, 다른 하나는 계속 접근 가능해야 하는 LAN 또는 업무 네트워크 리소스입니다. 첫 번째 그룹이 실패하면 클라이언트의 아웃바운드가 물리 네트워크를 통해 연결되는지 확인하고, 아웃바운드 연결 트래픽이 처리 경로에 다시 잡히지 않는지 살펴보세요. 두 번째 그룹이 실패하면 인터페이스 우선순위, 중복된 네트워크 대역, 기존 네트워크 정책을 확인하세요. 주소로는 접속되지만 이름으로는 실패한다면 DNS 장을 다시 살펴보세요. 이름 조회를 실제로 누가 시작하는지, 그 요청도 트래픽 처리 대상인지, 아직 연결되지 않은 경로에 조회가 의존하는지 확인해야 합니다.
기능을 끈 뒤에는 가상 인터페이스 관련 라우팅과 프록시 설정이 예상대로 복구됐는지 확인하세요. 네트워크를 바꾸거나 절전 모드에서 다시 깬 뒤, 또는 클라이언트를 업데이트한 뒤 문제가 나타나면 이전 결과를 그대로 믿지 말고 실제 인터페이스와 라우팅을 다시 확인해야 합니다. 중앙에서 관리하는 업무용 기기라면 권한을 높이거나 시스템 라우팅을 변경해 제한을 우회하지 마세요. 먼저 승인된 앱 프록시 방식으로 테스트하고 필요한 경우 담당 관리자에게 정책 확인을 요청하세요.
Android 클라이언트의 트래픽 처리는 시스템 VPN 권한으로 관리됩니다. 앱별 처리 방식은 데스크톱 설정에 하나씩 대응되지 않으므로 그대로 적용하지 마세요. 권한, 백그라운드 제한, 앱별 적용 범위를 확인하려면 Android 빠른 시작 가이드에서 기본 절차를 살펴본 뒤 v2rayNG의 VPN 권한, 배터리 최적화, 앱별 프록시 설정을 참고하세요. 어느 플랫폼에서든 문제를 확인할 때는 요청이 예상한 인터페이스에 들어갔는지, 들어간 뒤 어떤 아웃바운드를 선택했는지 먼저 확인해야 합니다.