설정 레퍼런스 config.json
V2Ray 설정 파일 레퍼런스
요청이 로컬 포트에 들어오는 시점부터 태그, 규칙, 연결 정책을 따라가며 코어가 실제로 선택한 아웃바운드를 확인합니다.
필드별 설정을 확인하는 페이지입니다. 아직 클라이언트를 설치하지 않았거나 가져오기와 첫 연결만 진행하려면 빠른 시작 가이드를 먼저 따라 한 뒤, 이 페이지에서 클라이언트가 생성한 설정을 확인하세요.
JSON 구조 한눈에 보기
클라이언트 설정과 코어 설정
클라이언트에는 노드, 구독, UI 옵션, 실행 모드가 저장되고, 코어는 시작할 때 불러온 설정을 읽습니다. 서로 연관은 있지만 같은 파일은 아닙니다. 예를 들어 클라이언트의 ‘시스템 프록시’ 설정은 앱이 요청을 로컬 프록시에 전달할지 결정하고, 코어의 routing은 이미 전달받은 요청을 어떻게 처리할지 정합니다. 라우팅을 수정해도 원래 프록시를 사용하지 않던 앱이 프록시 요청을 보내게 되지는 않습니다.
데스크톱에서는 클라이언트 다운로드 페이지에서 v2rayN을 선택할 수 있습니다. Android에서는 v2rayNG 또는 v2flyNG를 사용할 수 있습니다. 설정을 살펴볼 때는 먼저 실제로 실행 중인 코어를 확인한 다음 각 필드를 확인하세요. Xray와 V2Fly는 구조를 상당 부분 공유하지만, 프로토콜 옵션과 전송 매개변수, 리소스 파일이 모두 호환되는 것은 아닙니다. 코어가 설정 파일을 읽을 수 있다고 해서 클라이언트에서도 같은 방식으로 가져오거나 보존한다는 뜻은 아닙니다.
먼저 현재 파일이 노드 내보내기인지, 전체 설정 파일인지, 클라이언트 자체의 설정 백업인지 구분하세요. 노드 내보내기에는 원격 노드 정보가 담기며 로컬 리스닝 포트는 지정하지 않습니다. 클라이언트 백업에는 UI 설정과 여러 노드가 함께 들어 있을 수 있어 코어에 그대로 전달할 수 없습니다. 문제를 해결할 때는 이번 실행에서 실제로 사용된 설정 파일을 확인하세요. 클라이언트가 파일을 다시 생성한다면 UI에서 해당 설정을 바꾸거나 클라이언트가 지원하는 사용자 지정 설정 기능을 사용해야 합니다.
최상위 객체, 배열, 태그 참조
루트 노드는 객체입니다. inbounds와 outbounds는 프로세스가 여러 리스너와 출구를 가질 수 있어 배열로 구성됩니다. routing은 객체이며 규칙 배열은 그 안의 rules에 들어갑니다. dns와 policy도 객체입니다. 각 항목이 중괄호를 사용한다고 해서 같은 레벨의 필드를 앞 항목의 settings 안에 넣지 마세요.
| 필드 | 구조 | 역할 |
|---|---|---|
inbounds | 배열 | 리스닝 주소, 포트, 수신 프로토콜을 지정합니다. |
outbounds | 배열 | 직접 연결, 차단 또는 원격 프록시를 지정합니다. 첫 번째 항목이 기본 아웃바운드입니다. |
routing | 객체 | 요청을 순서대로 매칭해 결과를 아웃바운드 또는 밸런서로 전달합니다. |
dns | 객체 | 내장 DNS 조회가 필요한 곳에 정적 레코드와 리졸버를 제공합니다. |
policy | 객체 | 레벨별 세션 제약을 설정하고 필요에 따라 통계를 활성화합니다. |
태그는 유형명도 배열 인덱스도 아닙니다. 아웃바운드 이름을 direct로 지정한다고 자동으로 직접 연결되는 것은 아닙니다. 실제 직접 연결을 수행하는 것은 freedom입니다. 라우팅은 문자열을 기준으로 태그를 찾습니다. 아웃바운드 이름을 바꿀 때는 모든 참조를 찾아 함께 수정하세요. 정의만 바꾸고 참조를 그대로 두면 설정 검사나 요청 전달에 오류가 생길 수 있습니다. 인바운드와 아웃바운드에 서로 다른 접두사를 사용하면 로그에서 방향을 구분하기도 쉽습니다.
객체 속성의 작성 순서는 보통 동작에 영향을 주지 않지만, 배열 순서는 실제 동작을 바꿀 수 있습니다. 라우팅 규칙 순서를 바꾸면 먼저 매칭되는 규칙이 달라지고, 첫 번째 아웃바운드를 바꾸면 규칙에 매칭되지 않은 트래픽의 경로가 달라집니다. 파일을 정리할 때 들여쓰기를 통일해도 배열 항목을 전부 알파벳순으로 정렬해서는 안 됩니다. 두 파일을 비교할 때는 먼저 배열 순서를 확인하고 필드가 추가되거나 삭제됐는지 살펴보세요.
독립 실행을 위한 시작점
아래는 별도 파일로 저장해 실행할 수 있는 기본 설정입니다. 로컬 SOCKS 요청을 받아 같은 기기에서 직접 연결하며, 원격 노드나 규칙 리소스가 필요하지 않습니다. 테스트하기 전에 같은 포트를 사용하는 클라이언트를 종료하거나 예제 포트와 테스트 도구의 프록시 포트를 모두 바꾸세요. 별도 설명이 없는 한 이후 코드 예제는 모두 같은 루트 객체에 적용하는 독립된 조각입니다. 루트 괄호가 있는 여러 텍스트를 그대로 이어 붙이지 마세요.
{
"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" }
]
}
예제는 엄격한 JSON 형식을 사용합니다. 키와 문자열은 큰따옴표로 묶고, 배열과 객체의 마지막 항목 뒤에는 쉼표를 붙이지 않으며, 같은 레벨에 같은 키를 중복해서 쓰지 마세요. 포트는 정수, 스위치는 불리언 값으로 작성하고 열거형 값은 코어가 허용하는 표기를 사용하세요. 두 최상위 설정에 모두 routing이 있다면 규칙을 하나씩 합치고 순서를 정해야 합니다. 같은 이름의 키를 두 개 남겨두면 안 됩니다. 중복 키는 문법 오류가 발생하지 않을 수도 있지만 일부 파서는 앞의 값을 덮어씁니다. 파일이 멀쩡해 보여도 실행 중에는 뒤쪽 설정만 남을 수 있습니다.
inbounds 인바운드 리스닝
바인딩 주소와 연결 엔드포인트
인바운드는 앱의 요청이 코어로 들어오는 첫 번째 연결입니다. listen은 바인딩할 로컬 주소, port는 포트, protocol은 클라이언트가 보내는 데이터 형식을 지정합니다. 세 항목이 모두 일치해야 합니다. 앱은 기기의 LAN 주소로 프록시를 연결하지만 프로세스는 루프백 주소에만 바인딩된 경우, 포트가 같아도 연결되지 않습니다. 프로토콜이 잘못되면 소켓 연결은 성립한 뒤 프록시 핸드셰이크에서 끊길 수 있습니다.
로컬에서 사용할 때는 127.0.0.1에 명시적으로 바인딩하고 앱에서도 같은 주소를 입력하세요. 앱에서 localhost를 입력하면 IPv6 루프백 주소를 먼저 시도할 수 있지만, 이 예제는 IPv4만 리스닝하므로 문제를 비교할 때 두 주소를 섞어 쓰지 않는 것이 좋습니다. 다른 리스닝 주소를 테스트하려면 해당 주소가 기기에 속하는지, 포트를 바인딩할 수 있는지, 누가 접근할 수 있는지 확인하세요. 연결 실패의 원인을 찾기 위해 모든 인터페이스에서 리스닝하도록 설정하지 마세요.
두 프로세스가 같은 주소와 포트에 바인딩하면 충돌할 수 있습니다. 클라이언트에 내장된 코어와 수동으로 실행한 테스트 프로세스도 예외가 아닙니다. 포트가 이미 사용 중이라면 먼저 기존에 정상 작동하던 인스턴스가 점유하고 있는지 확인하세요. 어떤 프로세스인지 모른 채 바로 종료하지 마세요. 다른 테스트 포트를 선택했다면 앱 프록시, 코어 리스너, 테스트 명령의 포트를 모두 바꿔야 합니다. 포트만 바꾸고 이전 포트로 계속 요청을 보내면 새 설정이 적용된 것으로 착각할 수 있습니다.
SOCKS와 HTTP 인바운드 별도 설정
아래 조각은 기본 설정의 inbounds 배열을 대체할 수 있습니다. 두 리스너는 같은 아웃바운드 설정을 사용하지만 포트와 수신 프로토콜은 서로 다릅니다. HTTP 프록시를 사용하는 앱에는 두 번째 주소와 포트를, SOCKS5를 지원하는 앱에는 첫 번째를 입력하세요. 인바운드의 tag는 라우팅에서 요청 출처를 구분할 때 사용할 수 있습니다. 앱이 시스템 프록시를 사용하는지는 해당 앱과 실행 환경에 따라 달라집니다. 두 번째 리스너를 켰다고 해서 시스템 프록시가 적용된다고 볼 수는 없습니다.
{
"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"
}
]
}
HTTP 프록시는 클라이언트가 보내는 HTTP 프록시 요청을 처리하고, 터널을 지원하는 클라이언트는 CONNECT 요청도 보낼 수 있습니다. 그렇다고 리스닝 프로세스가 임의의 데이터 형식을 받을 수 있다는 뜻은 아닙니다. SOCKS를 사용하는 앱은 SOCKS 핸드셰이크를 직접 보내므로 HTTP 프록시 포트를 SOCKS 포트로 사용할 수 없습니다. 먼저 한 앱에 프록시를 명시적으로 설정한 다음 시스템 프록시 설정을 확인하면 운영체제의 전달 문제와 리스너 문제를 구분할 수 있습니다.
SOCKS 인바운드의 udp는 SOCKS UDP 릴레이 허용 여부를 설정합니다. 앱에서 보내는 일반 UDP 데이터그램을 이 포트로 자동 전달하지는 않습니다. 앱 자체가 SOCKS UDP 연동을 구현해야 하며, 이후 아웃바운드도 실제 프로토콜에 맞게 처리해야 합니다. 웹 요청 성공은 보통 테스트한 TCP 경로가 작동한다는 점만 보여줍니다. UDP를 사용하는 기능이 작동하지 않는다면 해당 기능의 인바운드, 라우팅, 아웃바운드를 각각 확인하세요. 같은 기기에서 웹페이지가 열린다는 이유만으로 정상이라고 판단하지 마세요.
대상 식별과 트래픽 가로채기 범위
인바운드가 받은 대상은 도메인일 수도 있고 IP일 수도 있습니다. 앱이 먼저 이름을 조회해 IP를 보낸 경우 라우팅은 해당 IP를 원래 도메인과 직접 비교할 수 없습니다. 일부 코어는 인바운드의 sniffing 설정으로 특정 프로토콜에 포함된 대상 이름을 식별할 수 있지만, 실제 트래픽 형식과 확인 가능한 정보에 따라 결과가 달라집니다. 식별 기능을 켜기 전에 라우팅 조건을 보완하려는 것인지, 연결 대상을 실제로 대체하려는 것인지 확인하세요. 두 동작은 같지 않습니다.
대상 식별을 모든 분기 문제를 해결하는 만능 스위치로 여기지 마세요. 도메인을 명시적으로 전달하는 프록시 요청으로 먼저 도메인 규칙이 매칭되는지 확인하세요. 여기서도 매칭되지 않으면 규칙 문법과 순서를 살펴봐야 합니다. 도메인 요청은 정상인데 앱의 실제 요청에 IP만 포함된 경우에만 대상 식별이나 앱의 프록시 설정을 추가로 확인하세요. 테스트할 때는 추가 옵션을 하나씩만 켜서 라우팅 입력과 실제 연결 대상이 동시에 바뀌지 않도록 하세요.
시스템 프록시, 앱 내부 프록시, TUN은 서로 다른 진입 경로입니다. 시스템 프록시는 관련 설정을 사용하는 앱에 프록시 주소를 제공하고, TUN은 가상 네트워크 어댑터로 선택된 트래픽을 가로채며 시스템 라우팅과 권한이 필요합니다. 앱의 요청이 일반 인바운드로 들어오지 않는다면 아웃바운드를 반복해서 바꾸지 말고 진입 경로부터 확인하세요. 가상 네트워크 어댑터를 이미 활성화했고 일반 프록시 테스트에 문제가 있다면 TUN 모드 안내에서 설정을 확인한 다음 진입 경로를 하나만 활성화해 다시 테스트하세요.
outbounds 아웃바운드 프로토콜
기본 출구와 명시적 차단
아웃바운드는 요청을 어디로 보낼지, 다음 연결을 어떤 프로토콜로 시작할지 정의합니다. freedom은 현재 요청의 대상에 직접 연결하며, 코어가 실행되는 기기의 네트워크 경로를 사용합니다. 원격 노드가 아니며 시스템 게이트웨이를 바꾸지도 않습니다. blackhole은 매칭된 요청을 명시적으로 버릴 때 사용합니다. 둘 다 라우팅을 확인하는 데 활용할 수 있지만, 대상 서비스로 실제 연결을 시도하는 것은 앞의 경우뿐입니다.
아래 예제는 기본 설정의 아웃바운드에 차단 옵션을 추가합니다. 어떤 라우팅도 deny를 참조하지 않으면 해당 항목은 트래픽을 자동으로 차단하지 않습니다. 예제에서는 direct를 첫 번째에 두므로 어떤 규칙에도 매칭되지 않은 요청은 직접 연결됩니다. deny를 첫 번째로 옮기면 매칭되지 않은 트래픽이 차단됩니다. 이는 일부 설정의 변경이 아니라 기본 경로가 바뀌는 것입니다. 순서를 바꾸기 전에 관리 트래픽과 일반 앱이 기존 기본 경로에 의존하는지 확인하세요.
{
"outbounds": [
{ "tag": "direct", "protocol": "freedom" },
{ "tag": "deny", "protocol": "blackhole" }
]
}
직접 연결의 의미는 진입 경로와 함께 살펴봐야 합니다. 앱이 먼저 코어에 연결되고 아웃바운드가 대상에 연결되는 경로는 앱이 프록시를 완전히 우회하는 것과 다릅니다. 두 경로는 서로 다른 리졸버와 주소 체계, 시간 제한을 사용할 수 있습니다. 비교 테스트에서는 ‘코어에 들어오지 않은 요청’과 ‘코어에 들어온 뒤 직접 연결된 요청’을 구분해 기록하세요. 후자만 실패한다면 코어가 받은 대상과 실행 환경을 확인해야 합니다. 시스템에서 같은 웹사이트가 열리는지만 확인해서는 부족합니다.
원격 주소, 프록시 프로토콜, 전송 방식
원격 프록시는 최소한 세 가지 층으로 나뉩니다. 어느 서버 주소와 포트에 연결할지, 해당 연결에서 어떤 프록시 프로토콜을 사용할지, 기반 전송과 보안 설정을 어떻게 할지 정해야 합니다. 주소와 포트는 서버에 도달하는 데 사용하고, 프록시 프로토콜 필드는 인증 등의 의미를 결정하며, 전송 필드는 데이터를 전달하는 방식을 정합니다. 한 단계가 작동한다고 다음 단계도 정상이라는 뜻은 아닙니다. 서버 포트에 연결되더라도 프로토콜이나 전송 방식이 맞지 않으면 세션을 완료할 수 없습니다.
VLESS 등의 아웃바운드를 살펴볼 때 프로토콜 전용 settings와 공통 streamSettings를 나눠 확인하세요. 노드 주소는 클라이언트가 처음 연결하는 대상입니다. TLS를 사용하는 경우 핸드셰이크 이름은 해당 연결의 보안 검증에 사용되므로 웹페이지의 도메인으로 무조건 바꾸면 안 됩니다. 프록시 프로토콜 식별 정보, 전송 유형, 보안 유형, 서버 측 설정을 하나씩 대조하세요. 다른 종류의 노드에서 전송 설정 전체를 복사하지 마세요.
공유 설정을 받으면 먼저 원격 노드 항목 하나를 가져온 것인지 전체 실행 설정을 받은 것인지 확인하세요. 원격 노드 항목이 완전하더라도 클라이언트가 리스너와 라우팅을 생성해야 합니다. 전체 파일에는 로컬 포트와 기본 아웃바운드가 이미 정의되어 있을 수 있습니다. 첫 테스트에서는 사용 가능한 것으로 확인된 원격 노드 하나만 활성화하고 고급 라우팅은 변경하지 마세요. 같은 요청이 해당 아웃바운드를 통해 안정적으로 처리된 다음 여러 아웃바운드 규칙에 추가해야 이후 문제가 노드 때문인지 선택 로직 때문인지 구분할 수 있습니다.
원격 노드 항목의 인증 정보와 구독 주소는 관리용 데이터입니다. 클라이언트에서 내보낸 원본 내용을 공개 게시판에 붙여 넣지 마세요. 핸드셰이크 실패를 논의할 때는 코어 종류, 프록시 프로토콜, 전송 유형, 아웃바운드 태그, 식별 정보가 제거된 로그만 제공해도 됩니다. 프로토콜 간 차이를 비교하려면 VMess와 VLESS의 필드 차이를 먼저 확인하고, 한 프로토콜의 옵션을 다른 프로토콜의 동의어로 취급하지 마세요.
태그 변경은 장애 조치가 아닙니다
같은 설정 파일에서는 아웃바운드 태그를 고유하고 알아보기 쉽게 지정하세요. 새 원격 노드를 배열에 추가한다고 자동으로 주·보조 구성이 되는 것은 아닙니다. 라우팅은 여전히 선택된 아웃바운드로만 요청을 전달합니다. 선택한 아웃바운드에 연결할 수 없더라도 뒤에 직접 연결 항목이 있다는 이유로 코어가 자동 전환하지 않습니다. 장애 조치가 필요하면 실제 코어에서 지원하는 밸런싱 기능과 후보 항목, 상태 확인 조건을 살펴보세요. 마지막에 항목 하나를 더 추가하는 것으로 대체할 수 없습니다.
아웃바운드를 교체한 뒤에는 명시적 매칭과 기본 매칭을 각각 다시 테스트하세요. 하나는 새 태그를 명시적으로 지정한 규칙에 매칭되는 요청, 다른 하나는 어떤 규칙에도 매칭되지 않는 요청으로 확인합니다. 이렇게 하면 ‘첫 번째 아웃바운드를 바꿨지만 이전 규칙은 여전히 옛 출구를 참조하는 경우’와 ‘규칙을 바꾸면서 기본 출구까지 의도치 않게 바뀐 경우’를 찾을 수 있습니다. 출구를 바꾼 뒤에는 새 연결을 만들어 테스트하세요. 브라우저 연결 풀에 남은 이전 세션이 변경 전 경로를 계속 사용할 수 있습니다.
routing 라우팅 규칙
첫 매칭과 조건 조합
routing.rules는 순서가 있는 목록입니다. 요청은 위에서 아래로 확인하며 매칭되는 규칙이 있으면 그 규칙이 지정한 출구로 전달됩니다. 코어가 모든 후보를 모은 뒤 가장 세밀한 규칙을 선택하는 방식이 아닙니다. 모든 웹 요청을 인바운드 태그로 매칭하는 규칙이 맨 앞에 있으면 뒤에 있는 도메인 예외가 적용되지 않을 수 있습니다. 먼저 처리해야 하는 조건을 앞에 배치하고, 어떤 규칙에도 매칭되지 않는 요청으로 기본 아웃바운드를 확인하세요.
일반적인 필드 규칙에서는 한 규칙 안에 서로 다른 조건이 있으면 모두 충족해야 합니다. 하나의 필드 목록에 후보가 여러 개 있으면 보통 그중 하나만 매칭돼도 됩니다. 인바운드 태그와 도메인을 한 규칙에 넣으면 해당 인바운드에서 들어오면서 대상 이름도 조건에 맞아야 한다는 뜻입니다. ‘어떤 인바운드에서 왔거나 지정 도메인 중 하나에 해당하는 경우’를 표현하려면 규칙을 두 개로 나누세요. 인접한 규칙을 합치면 줄 수는 줄어도 기존의 합집합 조건이 교집합 조건으로 바뀔 수 있습니다.
아래 조각은 이 페이지의 이중 아웃바운드 설정과 함께 사용하며, local-socks를 거쳐 예약된 예제 도메인으로 향하는 요청만 차단합니다. domain:은 도메인 경계를 기준으로 해당 이름과 하위 도메인을 매칭합니다. 완전히 같은 호스트명만 대상으로 하려면 full:을 사용하세요. 도메인 필드에는 호스트명 조건을 입력해야 합니다. 프로토콜, 경로, 쿼리 문자열이 포함된 웹 주소를 넣으면 안 됩니다. 라우팅은 브라우저 주소창의 전체 문자열을 비교하지 않습니다.
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"domain": ["domain:blocked.example"],
"outboundTag": "deny"
}
]
}
}
예약된 도메인을 입력값으로 사용하고 로그에서 deny에 매칭됐는지 확인할 수 있습니다. 이 예제 도메인은 정상적인 접속에 사용되지 않으므로 연결이 실패했다는 사실만으로 차단 규칙이 적용됐다고 볼 수 없습니다. 비교 테스트에서는 두 요청에 같은 도메인을 사용하고, 하나는 SOCKS 인바운드로, 다른 하나는 설정된 HTTP 인바운드로 보내세요. 첫 요청은 차단 아웃바운드를 선택하고 두 번째는 기본 직접 연결로 이어져야 합니다. 두 요청 모두 웹 응답이 없더라도 선택된 출구는 달라야 합니다.
도메인 정책 및 규칙 리소스
AsIs는 현재 대상 정보를 기준으로 매칭하며 도메인을 IP로 변환하려고 직접 조회하지 않습니다. IPIfNonMatch는 도메인 대상이 처음 매칭되지 않으면 이후 조회를 허용하고 적용할 수 있는 IP 규칙을 확인합니다. 앞에서 도메인 규칙이나 포괄적인 규칙이 먼저 매칭되면 추가 확인이 이뤄지지 않을 수 있습니다. IPOnDemand는 매칭 과정에서 필요할 때 조회를 허용합니다. 세 설정은 매칭 과정에서 언제 주소가 필요한지를 바꾸는 것이며, 시스템 전체의 DNS 정책을 설정하는 것은 아닙니다.
geosite:는 도메인 분류 항목을, geoip:는 IP 주소 분류 항목을 참조합니다. 사용할 수 있는 분류와 위치는 실행 환경의 리소스 파일에 따라 달라집니다. 분류명은 코어에 고정 내장된 문자열 목록이 아닙니다. 시작 로그에 리소스나 항목을 찾을 수 없다고 표시되면 코어가 어떤 데이터 파일을 불러오는지 확인한 다음, 확실한 도메인 하나나 주소 대역으로 비교하세요. 데이터가 없는 상태에서 규칙 범위를 넓히면 리소스 로딩 문제를 알아차리기 어려운 오매칭 문제로 바꿀 수 있습니다.
주소 관련 규칙은 먼저 대상 유형이 맞는지 확인하세요. 클라이언트가 IP를 보내면 도메인 분류 규칙에 매칭할 입력이 없습니다. 도메인을 보낸 경우에도 AsIs에서는 라우팅이 자동으로 조회한 뒤 주소 분류에 매칭될 것이라고 기대할 수 없습니다. 내장 리졸버가 여러 주소를 반환하면 주소 유형도 고려해야 합니다. 테스트할 때는 입력이 도메인, IPv4, IPv6 중 무엇인지 기록하고 한 번에 입력 조건 하나만 바꾸세요.
매칭 및 미매칭 경로 확인
목록을 관리할 때는 핵심 규칙마다 매칭되어야 하는 요청 하나와 조건 하나만 다른 요청 하나를 기록해 두세요. 잘못된 매칭을 조사할 때는 대상 정보, 인바운드 출처, 실제 출구를 먼저 확인한 뒤 목록에서 더 앞에 있는 후보 규칙을 찾으세요. 비교를 위해 규칙 하나를 임시로 앞에 옮길 수 있지만, 최종 수정 후에는 다른 예외도 다시 확인해야 합니다. 특히 좁은 조건으로 보호하던 요청이 있는지 살펴보세요. 규칙 하나를 옮겼을 뿐인데 여러 트래픽의 경로가 바뀔 수 있습니다.
라우팅은 선택한 아웃바운드의 연결 문제를 자동으로 해결하지 않습니다. 로그에 예상한 아웃바운드가 표시되는데 요청이 실패한다면 해당 아웃바운드의 주소 조회, 연결 시도, 핸드셰이크를 확인하세요. 선택된 태그가 예상과 다를 때만 매칭 조건을 계속 수정하는 것이 적절합니다. 클라이언트 UI의 전역 프록시나 규칙 모드는 다른 단계의 설정입니다. 프록시 모드 설정 안내를 참고해 현재 모드에서 확인 중인 규칙 집합이 실제로 적용됐는지 확인하세요.
dns 도메인 조회
어느 쪽에서 조회하는지
같은 도메인도 앱, 코어가 실행되는 기기, 원격 출구 중 한 곳에서 조회될 수 있습니다. 앱이 먼저 주소를 조회하면 인바운드는 IP만 받을 수 있습니다. 앱이 호스트명을 코어에 전달하면 라우팅이 먼저 도메인 기준으로 판단할 수 있습니다. 아웃바운드가 대상 이름을 원격으로 전달하는 경우, 최종 연결을 만들 때 원격 측에서 다시 조회할 수도 있습니다. 결과가 다르다고 특정 리졸버가 잘못된 답을 줬다고 단정하지 말고, 어느 연결 단계에서 어떤 이름을 조회하는지 먼저 확인하세요.
원격 노드 주소와 접속하려는 사이트 주소는 서로 다른 조회 대상입니다. 코어는 먼저 원격 노드 주소를 확인한 뒤 연결을 시도해야 합니다. 원격 연결이 준비된 다음에야 대상 이름을 원격 측에서 처리할 수 있습니다. 로그에 노드 도메인 조회 실패가 표시된다면 대상 웹사이트의 분류 규칙을 수정해도 노드 연결 문제는 해결되지 않습니다. 반대로 원격 노드 연결에 성공했다고 해서 사용자가 지정한 대상의 조회와 연결까지 가능하다는 뜻은 아닙니다.
이 절의 dns는 코어 자체의 설정입니다. 시스템 리졸버를 대체하지 않으며 브라우저, 다른 앱, 가상 네트워크 어댑터의 모든 DNS 요청을 자동으로 가로채지도 않습니다. 앱이 자체 조회 기능을 사용하면 시스템 설정과 코어 설정이 모두 첫 조회에 관여하지 않을 수 있습니다. 비교할 때는 진입 경로, 대상, 출구를 그대로 유지하고 조회 위치만 바꾸세요. 그래야 DNS 변경과 라우팅 변경이 뒤섞이지 않습니다.
정적 매핑, 시스템 리졸버, 조회 시점
아래 예제는 내장 DNS 처리에서 테스트 호스트를 정적 매핑하고, 그 밖에 조회가 필요한 이름은 localhost에 맡겨 실행 환경의 로컬 시스템 조회 기능을 사용합니다. 예제 주소는 문서용 예약 대역에 있으며 실제 서비스를 제공하는 테스트 서버가 아닙니다. 도메인이 어떤 주소로 매핑되는지 확인하는 용도이지, 웹페이지 접속을 테스트하는 용도는 아닙니다. 확인이 끝나면 테스트 레코드를 삭제하고 일상 설정에 남기지 마세요.
{
"dns": {
"hosts": {
"reference.test": "192.0.2.10"
},
"servers": ["localhost"]
}
}
위 설정만 추가했다고 reference.test에 접속하는 모든 요청이 내장 DNS를 반드시 사용하는 것은 아닙니다. 라우팅이 이 설정을 사용하도록 확인하려면 별도 테스트 파일에서 IPIfNonMatch를 사용하고, 앞에서 포괄적인 규칙이 매칭되지 않는지 확인한 다음 192.0.2.10/32에 매칭해 deny로 보내는 주소 규칙을 추가하세요. 프록시에서 호스트명을 전달하는 요청에 예약 도메인을 사용하고 로그에서 주소 규칙이 매칭됐는지 확인하세요. 이 테스트의 목적은 라우팅 판단을 확인하는 것이며 예제 주소에 실제로 연결할 필요는 없습니다.
라우팅이 IP 조건과 비교하기 위해 주소를 조회했다고 해서 아웃바운드가 반드시 같은 주소로 연결한다고 단정할 수는 없습니다. 아웃바운드가 도메인 이름을 유지할 수도 있고, 자체 주소 정책에 따라 다시 조회할 수도 있습니다. 조회 결과가 일치하지 않는 문제를 확인할 때는 ‘라우팅이 왜 매칭됐는지’와 ‘최종적으로 어디에 연결했는지’를 나눠 기록하세요. 두 단계에서 사용한 주소가 다르다면 각 단계의 입력과 리졸버를 확인해야 합니다. 조건표에 있는 IP를 최종 연결 주소로 간주해서는 안 됩니다.
주소 유형, 캐시, 조회 의존성
주소 조회 결과가 있는데도 연결이 실패한다면 반환된 값이 IPv4인지 IPv6인지 또는 둘 다인지 확인한 뒤 해당 네트워크에 연결할 수 있는지 살펴보세요. 사용할 수 있는 IPv6 경로가 없는 경우와 IPv6 레코드가 반환되지 않은 경우는 서로 다른 문제입니다. 주소 유형을 비교할 때는 같은 대상과 같은 출구를 사용하세요. 다른 사이트의 성공 사례로 원래 사이트의 문제를 증명할 수는 없습니다. 특정 주소 유형만 사용하도록 정책을 제한하기 전에 그 설정이 매칭, 조회, 연결 중 어느 단계에 영향을 주는지 확인하세요.
조회 설정을 바꾼 뒤에도 앱, 시스템, 코어가 각각 이전 결과를 캐시하거나 기존 연결을 재사용할 수 있습니다. 다시 테스트할 때는 먼저 새 연결을 만들고 필요하면 각 구성 요소의 캐시를 따로 처리하세요. 모든 구성 요소의 캐시를 지우면서 여러 정책을 동시에 바꾸지 마세요. 사용자 지정 조회 서비스의 주소를 도메인으로 지정했다면 해당 서비스가 처음 사용할 주소를 어떻게 얻는지, 아직 연결할 수 없는 원격 아웃바운드에 조회가 의존하는지도 확인해야 합니다. 의존성이 순환하는 경우 대기 시간을 늘려도 시작 조건이 갖춰지지 않습니다.
오류는 레코드 없음, 거부 응답, 조회 시간 초과, 조회 후 연결 시간 초과를 구분해야 합니다. 앞의 세 가지는 조회 대상과 리졸버에 접근할 수 있는지 확인해야 합니다. 마지막 경우에는 실제 연결 경로를 살펴봐야 합니다. 기기에서 수행한 시스템 조회는 비교 자료가 될 수 있지만 코어의 접근 로그를 대체하지는 않습니다. 어느 단계까지는 대상 이름만 보였고 어느 단계부터 주소가 확인됐는지 기록하면 문제 범위를 특정 지점으로 좁히는 데 도움이 됩니다.
policy 세션 정책
사용자 레벨과 적용 범위
policy.levels는 사용자 레벨별로 세션 매개변수를 구성합니다. 객체 키는 "0"처럼 문자열로 작성하지만, 프로토콜에서 연결에 사용하는 레벨 값은 보통 정수입니다. 세션에 별도 레벨을 지정하지 않으면 일반적으로 0레벨을 사용하지만 실제 동작은 프로토콜과 코어 구현에 따라 다릅니다. 레벨은 매개변수를 찾기 위한 인덱스일 뿐 숫자가 높다고 권한이나 우선순위, 속도가 높아지는 것은 아닙니다. 여러 레벨을 설정하기 전에 프로토콜의 어느 객체에서 해당 값을 읽는지 확인하세요.
라우팅은 출구를 선택하고 세션 정책은 적용 대상 세션이 특정 단계에서 기다리는 방식을 제어합니다. inboundTag와 사용자 레벨은 서로 다른 기능입니다. 전자는 리스너를 구분하고 규칙 매칭에 사용되며, 후자는 세션 매개변수를 선택합니다. 인바운드마다 시간 제한을 다르게 설정하려면 인바운드 프로토콜이 해당 세션 레벨을 설정할 수 있는지 확인하세요. 인바운드 태그만 바꾸거나 라우팅에서 레벨 이름을 참조하는 것으로는 연결이 만들어지지 않습니다.
{
"policy": {
"levels": {
"0": {
"handshake": 8,
"connIdle": 180,
"uplinkOnly": 5,
"downlinkOnly": 10
}
}
}
}
아래 값은 동작을 보여주기 위한 초 단위 예시이며 기본값이나 일반적인 권장값이 아닙니다. handshake는 해당 인바운드의 프로토콜 핸드셰이크 단계에 시간 제한을 적용하며 전체 접속 시간을 제한하지 않습니다. 앱이 리스너에 연결하지 못한 경우 이 값을 바꿔도 포트 접근 문제가 해결되지 않습니다. 원격 서버에서 보낸 보안 핸드셰이크 오류도 곧바로 이 설정 탓이라고 볼 수 없습니다. 로그에 표시된 단계가 인바운드 프로토콜 핸드셰이크인지, 원격 연결 시도인지, 원격 핸드셰이크인지 확인한 뒤 관련 매개변수를 살펴보세요.
유휴 연결 및 한쪽 방향 종료 대기
connIdle은 연결이 유휴 상태일 때 기다리는 시간입니다. 데이터가 계속 오가는데 전체 소요 시간이 긴 경우와 오랫동안 활동이 없는 경우는 다릅니다. 간헐적으로 데이터를 보내는 앱은 일정 시간 동안 조용해도 정상일 수 있습니다. 장시간 연결이 비슷한 유휴 시간 뒤에 끊긴다면 출구와 앱을 고정하고 마지막으로 유효한 데이터가 전송된 시점부터 연결이 끊길 때까지의 간격을 기록한 뒤 매개변수 하나만 바꿔 다시 테스트하세요. 짧은 연결 실패를 모두 유휴 시간 제한 탓으로 돌리지 마세요.
uplinkOnly와 downlinkOnly는 세션에서 한 방향으로만 데이터가 오가는 상태가 된 뒤 기다리는 시간을 제어합니다. 업로드와 다운로드 속도를 제한하는 설정이 아닙니다. 하향 전송이 끝난 뒤 상향 전송만 남으면 전자를, 상향 전송이 끝난 뒤 하향 전송만 남으면 후자를 확인하세요. 일부 앱은 요청을 보낸 뒤 상향 전송을 끝내고 남은 응답을 기다립니다. 종료 대기 시간이 너무 짧으면 일반적인 웹페이지 테스트보다 이런 상황에서 문제가 먼저 나타날 수 있습니다. 같은 연결 끊김을 재현하려면 요청 본문과 응답 동작을 동일하게 유지하세요.
연결 종료는 앱, 서버, 중간 장비에서 발생할 수도 있습니다. 코어의 유휴 시간 설정을 바꿔도 끊기는 시점이 달라지지 않는다면 대기 시간을 계속 늘리지 말고 다른 관련 구성 요소를 확인하세요. 핸드셰이크 실패, 유휴 상태 이후 종료, 한쪽 방향 종료 이후 중단을 각각 나눠 기록하세요. 변경 전후를 비교할 수 있도록 대상, 전송 방식, 출구, 앱 버전, 진입 모드를 가능한 한 동일하게 유지하세요.
통계 활성화와 확인 방법
통계 설정과 시간 제한은 같은 정책 영역에 있지만 서로 독립적입니다. 일반적으로 최상위 stats 모듈을 활성화한 다음 해당 정책에서 필요한 카운터를 켜야 합니다. 예를 들어 policy.system.statsInboundUplink로 인바운드 업로드 통계를 활성화할 수 있습니다. 사용자별로 집계하려면 사용자 레벨 설정과 프로토콜이 사용자 식별자를 제공하는지도 확인해야 합니다. 이름이 비슷한 옵션을 설정했다고 해서 클라이언트의 모든 화면에 통계가 표시되는 것은 아닙니다.
통계는 이를 지원하는 구성 요소가 읽어야 하며 자동으로 사용량 보고서가 생성되거나 지연 시간과 연결 가능성을 검사하는 기능은 아닙니다. 클라이언트에 통계 화면이 이미 있다면 기존 기능으로 집계 대상을 확인하세요. 로그를 보는 용도로 별도의 관리용 리스너를 열 필요는 없습니다. 카운터가 0으로 표시되면 모듈 활성화 여부, 대상에 필요한 태그나 식별자가 있는지, 현재 프로세스의 값인지, 테스트 요청이 실제로 해당 대상을 거쳤는지 차례대로 확인하세요.
정책 설정을 조정하기 전에 변경하지 않은 기준 설정과 다시 실행할 수 있는 요청을 보관하세요. 비교할 때는 웹페이지가 열렸는지만 기록하지 말고 시작 시각, 마지막 활동 시각, 연결 종료 이유를 함께 기록하세요. 클라이언트가 파일을 다시 생성했다면 설정이 현재 불러온 설정에 포함됐는지 확인하세요. 실행 파일에 해당 정책이 없다면 테스트 결과로 설정값의 효과를 판단할 수 없습니다. 동일한 변화가 안정적으로 관찰될 때만 설정을 확정하세요.
설정 검증 및 단계별 문제 해결
파일 확인부터 프록시 요청까지
검증은 세 단계로 나뉩니다. 파일을 파싱할 수 있는지, 프로세스가 정상적으로 시작되는지, 실제 요청이 예상한 경로를 거치는지 확인해야 합니다. 한 단계의 성공이 다음 단계까지 보장하지는 않습니다. 파일을 비교하기 전에 시작 명령이 가리키는 경로를 확인하세요. UI에서 재시작할 때도 현재 설정의 출처와 활성화된 코어를 확인해야 합니다. 테스트 디렉터리와 클라이언트 작업 디렉터리가 모두 있다면 파일 이름이 config.json으로 같다는 것만으로 실행 중인 파일을 확인할 수 없습니다.
코어를 직접 실행할 때는 코어 종류에 맞는 아래 설정 검사 명령을 선택하세요. 명령은 설정 파일이 있는 디렉터리에서 실행하거나 파일 인수를 실제 경로로 바꾸면 됩니다. 실행 프로그램이 다른 명령행 인수를 사용한다면 로컬 코어의 도움말을 확인하세요. 설정 검사가 성공했다는 것은 코어가 설정 입력을 받아들였다는 뜻일 뿐, 실제 리스너를 바인딩할 수 있거나 원격 서버에 연결할 수 있다는 뜻은 아닙니다. 검사가 끝나면 프로세스를 시작하고 시작 로그를 확인하세요.
xray run -test -config config.json
v2ray test -c config.json
먼저 JSON 구조 한눈에 보기의 최소 설정을 실행한 다음 SOCKS5를 지원하는 앱에서 프록시 요청을 한 번 보내세요. 아래 명령은 curl이 설치된 환경에서 사용할 수 있습니다. socks5h는 대상 도메인을 프록시 요청에 포함합니다. 그렇다고 최종적으로 내장 DNS가 조회한다는 뜻은 아닙니다. 테스트 도구가 도메인을 IP로 바꾼 뒤 전달하는 상황을 피할 수 있다는 의미입니다. 외부 대상에 연결되지 않을 수도 있으므로 직접 연결이 가능하다고 확인된 테스트 사이트를 사용할 수 있습니다.
curl --verbose --max-time 12 --noproxy "" --proxy socks5h://127.0.0.1:10808 https://example.com/
처음에는 시스템 프록시나 가상 네트워크 어댑터를 동시에 켤 필요가 없습니다. 프록시 요청을 명시적으로 보내면 앱이 시스템 설정을 따르는지 여부를 분리해서 확인할 수 있습니다. 직접 연결 아웃바운드로 왕복이 되는지 먼저 확인한 뒤 차단 아웃바운드와 라우팅 규칙을 추가하고 태그가 바뀌는지 살펴보세요. 알려진 원격 서버는 마지막에 연결하세요. 기본 연결 경로부터 실패한다면 분기 리소스, 조회 정책, 여러 노드를 추가할수록 문제 범위만 커집니다.
처음 실패한 지점부터 확인
| 증상 | 먼저 확인할 항목 | 비교 방법 |
|---|---|---|
| 설정 검사 오류 | JSON 구조, 필드 값, 규칙 리소스 | 첫 번째 오류부터 확인하고 실행 가능한 기준 설정으로 되돌린 뒤 항목을 하나씩 추가하세요. |
| 인바운드 연결 실패 | 실행 중인 인스턴스, 바인딩 주소와 포트 | 리스너 하나만 남기고 앱에서 프록시를 명시적으로 설정해 테스트하세요. |
| 선택된 아웃바운드가 예상과 다름 | 요청 대상, 인바운드 태그, 규칙 순서 | 매칭되어야 하는 요청과 매칭되지 않아야 하는 요청을 각각 새로 보내세요. |
| 아웃바운드는 맞지만 연결 실패 | 조회, 연결 시도, 전송, 핸드셰이크 | 같은 인바운드에서 직접 연결과 지정한 원격 노드를 비교하고 실패 단계를 확인하세요. |
| 한동안 사용한 뒤 연결이 끊김 | 마지막 활동 시각과 종료된 방향 | 앱과 연결 경로를 고정한 뒤 유휴 상태와 한쪽 방향 종료를 따로 확인하세요. |
로그를 읽을 때는 한 요청의 시간 범위에 해당하는 연속 기록을 우선 수집하세요. 시작 과정의 경고는 요청 실패와 관련이 없을 수 있고, 이후 재시도 기록이 첫 번째 단서를 덮을 수도 있습니다. 이번 요청과 관련된 첫 실패를 찾은 뒤 앞부분을 확인해 인바운드와 아웃바운드가 확인됐는지 살펴보세요. 필요한 단계를 확인할 수 있을 정도로 로그 수준을 잠시 높인 뒤에는 원래 설정으로 되돌리세요. 접근 대상과 실행 정보가 장기간 더 많이 저장되지 않도록 해야 합니다.
UI에 실행 중이라고 표시되는 것은 클라이언트가 시작 절차가 진행됐다고 판단했다는 뜻일 뿐, 앱이 올바른 인바운드로 들어왔다는 뜻은 아닙니다. 로그에 테스트 요청조차 나타나지 않으면 먼저 앱에 입력한 프로토콜과 주소를 확인하고 시스템 기본 경로만 사용하고 있지는 않은지 살펴보세요. 요청이 로그에 나타났지만 예상한 아웃바운드로 전달되지 않았다면 현재 활성 설정과 규칙 순서를 다시 확인하세요. 원격 핸드셰이크 오류가 표시되면 전체 라우팅을 바꾸기 전에 해당 아웃바운드와 서버 설정이 일치하는지 확인하세요.
최소 재현 및 복구 순서
문제를 되돌릴 때는 마지막으로 작동했던 파일을 복구하고 해당 인스턴스를 다시 시작한 다음 같은 프록시 포트와 대상에 새 요청을 보내세요. 기준 설정이 여전히 작동하는지 확인한 뒤 변경 사항을 하나씩 추가하고 각 단계에서 예상 태그와 실제 결과를 기록하세요. 기준 설정조차 작동하지 않으면 환경 변화부터 확인하세요. 프로세스가 계속 실행 중인지, 새 앱이 포트를 사용하고 있는지, 시스템 라우팅이 바뀌었는지, 원래 대상에 여전히 연결할 수 있는지 살펴보세요. 이 단계에서는 검증되지 않은 변경을 계속 쌓지 마세요.
도움을 요청할 때는 운영체제, 클라이언트와 코어 이름, 문제가 발생한 단계, 최소화한 설정 파일, 동일한 요청의 로그 일부를 제공하세요. 구독 주소, 인증 정보, 내부 도메인, 관련 없는 연결 기록은 삭제하고 오류 유형과 필드 간 참조 관계는 남기세요. 오류 문구로 원인을 찾으려면 실행 로그 확인 방법을 참고하세요. 구독을 가져오거나 시스템 프록시를 전환할 때 발생한 문제라면 자주 묻는 질문도 함께 확인해 클라이언트 단계부터 점검한 뒤 코어 필드를 살펴보세요.