코어 설정 · 필드 가이드
V2Ray 설정 파일 가이드
JSON 구조에 따라 인바운드, 아웃바운드, 라우팅, DNS, 연결 정책을 살펴보고 최소 설정 예제로 각 항목이 어떻게 연동되는지 확인하세요.
처음 구독을 가져오거나 시스템 프록시를 설정한다면 빠른 시작 가이드부터 확인하세요. 가이드에서는 조작 순서를, 이 문서에서는 코어가 실제로 읽는 필드를 다룹니다. 포트, 아웃바운드 태그, DNS 결과가 예상과 다르면 목차에서 해당 항목으로 바로 이동할 수 있습니다.
01 설정 구조
V2Ray 설정 파일의 JSON 구조
클라이언트에 저장된 설정이 곧 코어 설정은 아닙니다
데스크톱에서는 v2rayN을, Android에서는 필요한 코어에 따라 v2rayNG 또는 v2flyNG를 사용할 수 있습니다. 자세한 내용은 클라이언트 다운로드 페이지를 참조하세요. 그래픽 인터페이스를 사용할 때 구독 주소, 선택한 항목, 시스템 프록시, 인터페이스 환경설정은 대개 클라이언트가 관리합니다. 클라이언트는 선택된 항목과 전역 설정을 바탕으로 코어 설정을 생성하거나 불러옵니다. 인터페이스에 표시된 항목 이름이 JSON의 태그와 다를 수 있으며, 클라이언트 데이터 파일을 코어에서 직접 읽을 수 있는 것도 아닙니다. 필드를 대조하기 전에 현재 실행 중인 코어와 실제로 전달된 설정 파일부터 확인하세요.
일반적인 연결에는 JSON 전체를 직접 작성할 필요가 없습니다. 인터페이스 설정으로 원하는 동작을 구현할 수 없거나 문제 범위를 좁혀야 할 때만 별도의 설정 파일을 복사해 사용하는 것이 좋습니다. 클라이언트가 생성한 파일을 직접 수정하면 다시 연결하거나 항목을 전환하거나 구독을 업데이트할 때 변경 내용이 덮어써질 수 있습니다. 반대로 불러오지 않는 사본을 수정해도 연결에는 영향이 없습니다. 변경 사항이 적용됐는지 확인할 때 파일 저장 시간만 보지 말고 시작 결과와 리스닝, 아웃바운드 등 관찰 가능한 동작을 살펴보세요.
최상위 객체, 객체 배열, 프로토콜 매개변수
루트 노드는 객체입니다. 하나의 프로세스가 여러 연결을 받을 수도, 여러 대상으로 연결할 수도 있으므로 인바운드와 아웃바운드는 각각 배열로 표현하며 배열의 각 항목이 개별 객체입니다. 라우팅, DNS, 정책, 로그도 각각 별도의 루트 수준 객체를 사용합니다. 필드가 잘못된 계층에 있으면 JSON 문법 검사에 통과하더라도 코어에서 사용되지 않을 수 있습니다. 예를 들어 리스닝 포트는 인바운드 객체의 속성이고 인증 방식은 SOCKS 인바운드의 settings 객체에 들어갑니다. 설정 창에서 같은 화면에 보인다고 두 항목을 같은 계층에 넣지 마세요.
{
"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 요청만 받아 목적지에 직접 연결합니다. 원격 서버는 사용하지 않습니다. 라우팅 규칙이 없으므로 규칙에 매칭되지 않은 요청은 배열의 첫 번째 아웃바운드로 전달됩니다. JSON 작성 순서는 두 가지로 나눠 생각하세요. 같은 객체 안에서 log와 inbounds 중 무엇을 먼저 쓰는지는 동작에 영향을 주지 않지만, 배열은 기본 아웃바운드 위치와 규칙 순서처럼 순서가 중요할 수 있습니다. 코드를 복사할 때 바깥 구조는 유지하고 필요한 항목을 해당 배열에 추가하세요. 완성된 루트 객체 두 개를 이어 붙이면 안 됩니다.
| 필드 | 형식 | 기능 |
|---|---|---|
inbounds | 객체 배열 | 연결을 받고 인바운드에 이름을 지정합니다 |
outbounds | 객체 배열 | 대상 연결 또는 차단 동작을 정의합니다 |
routing | 객체 | 사용할 아웃바운드를 선택하고 규칙 배열을 포함합니다 |
dns | 객체 | 코어가 수행하는 도메인 조회를 설정합니다 |
policy | 객체 | 연결 시간 제한과 통계 기능을 설정합니다 |
log | 객체 | 로그 수준과 관련 출력을 제어합니다 |
문법을 확인한 다음 필드 간 관계를 점검하세요
표준 JSON으로 저장할 때는 키와 문자열에 반각 큰따옴표를 사용하고 주석이나 마지막 쉼표를 넣지 마세요. 포트는 숫자로, 인증 방식은 문자열로, 스위치는 따옴표 없는 true 또는 false로 작성합니다. 같은 객체에서 동일한 키를 중복 사용하지 마세요. 일부 리더는 마지막 값을 사용하므로 설정을 하나 더 추가한 것처럼 보여도 기존 규칙이 통째로 덮어써질 수 있습니다. 오류가 다음 줄을 가리키더라도 앞 항목의 쉼표가 빠졌는지, 배열이 너무 일찍 닫혔는지 확인하세요.
문법 검사를 통과했다는 것은 파일을 구조화된 데이터로 읽을 수 있다는 뜻일 뿐입니다. 이어서 세 가지 관계를 확인하세요. 프로토콜과 settings가 서로 맞는지, 규칙에서 참조하는 태그가 존재하는지, 설정에서 지정한 파일을 실행 환경에서 읽을 수 있는지 점검합니다. 그다음 포트 바인딩이나 원격 연결 같은 실행 문제를 확인하세요. 코어에 따라 알 수 없는 필드가 있어도 오류를 명확히 표시하지 않을 수 있습니다. 이 문서는 두 종류의 코어에서 공통으로 볼 수 있는 기본 구조와 설정 관계를 설명합니다. 특정 코어의 확장 기능은 해당 파일을 실제로 불러오는 코어가 지원하는 필드를 기준으로 확인하세요.
02 연결 수신
inbounds: 리스닝 주소, 포트, 인바운드 프로토콜
리스닝 주소에 따라 인바운드에 연결할 수 있는 기기가 달라집니다
로컬에서 사용할 때는 listen을 127.0.0.1로 명시해 같은 네트워크의 다른 기기에 인바운드가 노출되지 않게 하세요. 애플리케이션은 코어가 실행 중인 기기에 연결해야 합니다. 휴대폰에 이 주소를 입력하면 데스크톱이 아니라 휴대폰 자신을 가리킵니다. IPv4 루프백 주소만 리스닝할 경우 IPv6 루프백 주소로는 같은 리스너에 연결할 수 없습니다. 클라이언트 인터페이스의 프록시 주소를 확인할 때는 localhost의 해석 결과가 변수가 되지 않도록 명시적인 주소를 사용하는 편이 좋습니다.
port는 코어가 실제로 연결을 기다리는 로컬 포트이며 구독에 포함된 서버 포트가 아닙니다. 주소와 포트 조합은 운영체제의 바인딩 규칙을 따릅니다. 이미 다른 프로세스가 사용 중이면 새 인바운드가 시작되지 않을 수 있고, 모든 IPv4 인터페이스에 바인딩된 리스너가 특정 주소의 리스너와 충돌할 수도 있습니다. 포트를 바꾸면 애플리케이션이나 시스템 프록시에 입력한 포트도 함께 변경하세요. 한쪽만 바꾸면 클라이언트가 정상 실행되는 것처럼 보여도 앱은 이전 인바운드에 계속 연결하거나 이전 포트를 차지한 다른 프로그램에 잘못 연결할 수 있습니다.
{
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": {
"auth": "noauth",
"udp": false
}
}
]
}
라우팅 규칙보다 먼저 프로토콜이 맞아야 합니다
예제는 SOCKS 인바운드를 사용하므로 애플리케이션에서 SOCKS5 프록시를 선택해야 합니다. 브라우저가 웹페이지를 요청한다고 해서 프록시 핸드셰이크도 HTTP를 사용해야 하는 것은 아닙니다. HTTP 프록시 설정만 제공하는 앱에는 별도의 HTTP 인바운드나 클라이언트가 생성한 해당 인바운드를 사용하고, 실제 설정에 맞는 포트를 입력하세요. SOCKS 포트에 HTTP 프록시 요청을 보내면 포트 연결은 되더라도 코어가 인바운드 프로토콜에 맞게 요청 대상을 읽지 못합니다. 따라서 이후 라우팅 규칙까지 진행되지 않습니다. 포트 응답만으로 요청이 라우팅 단계에 도달했는지 판단할 수 없습니다.
auth가 noauth이면 계정 인증을 요구하지 않으므로 이 예제처럼 루프백 주소로 제한한 테스트에 적합합니다. udp가 false이면 이 인바운드는 SOCKS UDP 전달을 제공하지 않습니다. 기능을 켜더라도 앱이 SOCKS5 UDP ASSOCIATE를 지원해야 하며 이후 아웃바운드도 해당 트래픽을 처리할 수 있어야 합니다. 웹페이지가 열린다는 사실은 해당 웹 요청이 성공했음을 보여줄 뿐, 실시간 통신이나 UDP에 의존하는 다른 앱도 같은 인바운드를 사용할 수 있다는 뜻은 아닙니다. 문제가 발생한 앱, 프록시 프로토콜, 실제 전송 방식을 각각 기록하세요.
인바운드 태그, 대상 주소, 스니핑은 서로 다른 설정입니다
tag는 인바운드에 이름을 붙입니다. 라우팅은 inboundTag로 리스너마다 요청을 구분할 수 있습니다. 예를 들어 로컬 인바운드 두 개에 서로 다른 이름을 지정하면 테스트 앱의 규칙만 테스트용 인바운드에 적용하고 평소 사용하는 인바운드에는 영향을 주지 않을 수 있습니다. 인바운드 태그는 앱의 프록시 프로토콜에 따라 자동으로 바뀌지 않습니다. 태그를 변경하면 라우팅에서 참조하는 이름도 함께 바꾸세요. 인바운드마다 동작이 다르면 앱이 어느 포트에 연결하는지 확인하고 관련 규칙의 조건에 다른 인바운드 이름이 들어 있지 않은지 살펴보세요.
인바운드 요청에 도메인이 항상 포함되는 것은 아닙니다. 앱이 도메인을 코어에 전달할 수도 있고, 로컬에서 먼저 조회한 다음 IP만 전달할 수도 있습니다. sniffing을 활성화하면 코어가 지원되는 트래픽에서 도메인을 식별할 수 있습니다. 예를 들어 HTTP 요청의 호스트명이나 일부 TLS 핸드셰이크의 서버명을 확인할 수 있지만 모든 연결에서 식별되는 것은 아니며 앱 트래픽을 복호화하지도 않습니다. 설정에 따라 식별 결과를 라우팅에만 사용할지 실제 대상을 변경할지도 달라집니다. 검증하기 쉽도록 먼저 도메인을 명시적으로 전달하는 앱으로 테스트하고, 기본 분기가 동작하는지 확인한 뒤 스니핑을 고려하세요.
03 연결 시작
outbounds: 아웃바운드 프로토콜, 태그, 기본 출구
태그는 참조에 쓰이고 실제 동작은 프로토콜이 결정합니다
outbounds는 요청을 어떤 처리기로 전달할지 정의합니다. 항목 이름을 direct로 지정하는 것은 사람이 읽기 쉽게 하기 위한 것이며, 실제 직접 연결 동작은 freedom이 수행합니다. 마찬가지로 차단 항목은 보통 block이라고 이름 붙이지만 실제 처리는 blackhole이 담당합니다. 이름만으로 아웃바운드 동작이 바뀌지는 않습니다. 설정을 복사하면서 라우팅 규칙만 가져오고 같은 이름의 아웃바운드는 복사하지 않으면 참조 대상이 빠집니다. 반대로 차단 항목을 정의해도 규칙에서 선택하지 않으면 특정 요청을 차단하지 않습니다.
{
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
},
{
"tag": "block",
"protocol": "blackhole",
"settings": {
"response": { "type": "none" }
}
}
]
}
별도의 기본 출구를 지정하지 않은 일반적인 설정에서는 규칙에 매칭되지 않은 요청이 첫 번째 항목으로 전달됩니다. 차단 항목을 첫 번째로 옮기면 규칙을 하나도 바꾸지 않아도 매칭되지 않은 모든 트래픽의 결과가 달라집니다. 기본 항목과 명시적인 최종 규칙은 다릅니다. 기본 항목은 어떤 규칙에도 매칭되지 않을 때 적용되지만, 범위가 넓은 최종 규칙은 뒤에 있는 더 구체적인 규칙을 가로막을 수 있습니다. 설정을 검토할 때는 먼저 알 수 없는 대상에 사용할 아웃바운드를 정한 다음, 첫 번째 항목에 맡길지 마지막에 일반 규칙을 명시할지 결정하세요.
원격 서비스 매개변수는 프로토콜과 전송의 두 계층으로 나뉩니다
원격 아웃바운드에는 보통 프로토콜 매개변수와 연결 매개변수가 모두 필요합니다. protocol은 코어에서 사용할 프로토콜을 선택하고, settings는 해당 프로토콜에 맞는 원격 주소, 서버 포트, 인증 정보를 지정합니다. streamSettings는 연결에 사용할 전송 및 보안 계층을 설정합니다. 두 부분 모두 원격 서비스 설정과 일치해야 합니다. 한 항목의 전송 설정만 다른 항목에 그대로 옮기면 프로토콜 인증 정보는 맞아도 경로나 핸드셰이크 조건이 맞지 않을 수 있습니다. 문제를 진단할 때는 필드가 속한 계층을 기준으로 비교하고 모든 핸드셰이크 실패를 구독 업데이트 탓으로 돌리지 마세요.
주소처럼 보이는 필드가 여러 개라면 먼저 각 필드가 어느 단계에 쓰이는지 확인하세요. 원격 연결을 만들 때는 접속 주소가 필요하고, 보안 핸드셰이크에는 서버명이 필요할 수 있으며, 일부 전송 방식은 별도의 경로나 호스트명을 요구합니다. 특정 서비스에서 값이 같을 수는 있지만 서로 바꿔 쓸 수 있는 동의어는 아닙니다. 접속 도메인을 IP로 바꿔도 나머지 이름까지 모두 바꿔야 하는 것은 아닙니다. 단일 노드 매개변수가 공유 링크에 전달되는 방식은 공유 링크와 구독 주소의 차이를 참조하세요. 링크 전체를 JSON 주소 필드에 붙여 넣으면 안 됩니다.
규칙에 매칭된 것과 아웃바운드 연결이 되는 것은 다릅니다
라우팅 규칙에 매칭되면 처리기가 선택될 뿐, 연결이 성립한다는 보장은 없습니다. 직접 연결이 실패하면 로컬에서 대상을 조회할 수 있는지, 대상까지 네트워크 경로가 있는지, 대상 포트를 사용할 수 있는지 확인하세요. 원격 아웃바운드가 실패하면 먼저 원격 주소에 연결할 수 있는지와 프로토콜 핸드셰이크를 완료할 수 있는지를 구분하고, 모든 대상이 실패하는지 특정 대상만 실패하는지도 확인하세요. 차단은 의도적으로 요청을 전달하지 않는 동작입니다. 예제의 none은 설명이 표시되는 차단 페이지를 제공하지 않으므로 앱에서 연결 실패로 보이는 것은 자연스럽습니다.
다른 노드를 선택했는데도 직접 연결되는 것처럼 보이더라도 웹페이지가 열리는지만 보고 판단하지 마세요. 직접 연결과 원격 전달 모두 같은 페이지를 성공적으로 불러올 수 있고, 기존 장기 연결은 전환 후에도 잠시 유지될 수 있습니다. 더 확실한 방법은 새 요청이 지정한 인바운드로 들어왔는지 확인한 뒤 로그나 비교 테스트로 선택된 아웃바운드를 확인하는 것입니다. 두 아웃바운드가 모두 실패하는 것 같다면 직접 연결 아웃바운드 하나만 남긴 최소 설정으로 테스트하세요. 그러면 앱에서 로컬 인바운드까지의 구간과 원격 서비스에 의존하는 연결을 나눠 확인할 수 있습니다.
04 라우팅 규칙 매칭
routing: 규칙 순서, 대상 유형, 아웃바운드 참조
위에서부터 확인하고 한 규칙에 매칭되면 중단합니다
routing.rules는 후보 규칙에 점수를 매기는 목록이 아니라 순서가 있는 목록입니다. 범위가 넓은 규칙을 앞에 두면 뒤에 있는 더 구체적인 조건은 적용되지 않을 수 있습니다. 예를 들어 테스트 인바운드의 모든 요청을 직접 연결하는 규칙을 먼저 쓰고 같은 인바운드에서 특정 도메인을 차단하는 규칙을 나중에 쓰면, 첫 번째 규칙이 먼저 매칭되어 도메인 규칙에 도달하지 않습니다. 이런 문제를 확인할 때는 예상한 규칙만 보지 말고 맨 위부터 각 규칙의 조건이 충족되는지 하나씩 살펴보세요.
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"domain": ["full:example.org"],
"outboundTag": "block"
},
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
}
첫 번째 규칙은 요청이 local-socks에서 왔고 대상의 전체 도메인이 example.org인 경우에만 매칭됩니다. 서로 다른 조건 필드는 모두 충족해야 하지만, 같은 목록 안의 후보는 대개 하나만 맞아도 됩니다. 예를 들어 도메인 목록의 패턴 중 하나가 일치하면 됩니다. 도메인 조건 또는 대상 네트워크 조건 중 하나만 만족해도 적용하려면 보통 규칙을 두 개로 나눠야 합니다. domain과 ip를 같은 객체에 넣어도 OR 조건이 되지 않습니다. 여러 규칙을 합친 뒤 오히려 매칭률이 떨어지는 흔한 이유입니다.
도메인 규칙은 웹페이지 경로를 대상으로 하지 않습니다
full:은 도메인 전체를 정확히 지정하고, domain:은 해당 도메인과 하위 도메인을 매칭합니다. 전자는 하위 도메인을 포함하지 않으며, 후자는 전체 URL에서 임의의 문자열을 찾지 않습니다. 설정에는 호스트명만 입력하고 URL 스킴, 경로, 쿼리 매개변수, 페이지 내 앵커는 넣지 마세요. 웹페이지를 열 때 다른 도메인으로 리디렉션되거나 세 번째 도메인에서 정적 파일을 불러올 수 있습니다. 페이지 일부가 열렸다고 모든 요청이 같은 규칙에 매칭된 것은 아닙니다. 테스트할 때는 호스트명을 하나 명확히 지정하고 기본 문서와 후속 리소스 중 무엇이 실패했는지 확인하세요.
IP 규칙은 대상 주소에 적용되며 단일 주소나 CIDR 네트워크를 사용할 수 있습니다. 포트 조건은 연결 대상의 포트이며 로컬 SOCKS 리스닝 포트가 아닙니다. 앱이 IP를 전달하면 코어가 트래픽에서 사용할 수 있는 도메인을 식별하지 않는 한 도메인 규칙은 보통 매칭되지 않습니다. 반대로 앱이 도메인을 전달했을 때 라우팅 단계에서 IP 규칙에 사용할 주소로 변환되는지는 라우팅의 domainStrategy에 따라 달라집니다. 라우팅에 사용할 주소를 찾지 못한 상황을 아웃바운드에서 이미 DNS 조회를 마친 뒤 연결에 실패한 것으로 착각하지 마세요.
도메인 변환 전략과 규칙 데이터베이스
라우팅의 AsIs는 IP 규칙 매칭을 위한 추가 도메인 조회를 하지 않습니다. IPIfNonMatch는 첫 검색에서 매칭되지 않으면 주소를 조회한 뒤 다시 검색합니다. 따라서 첫 검색에서 매칭될 수 있는 광범위한 기본 규칙이 있으면 추가 조회가 일어나지 않을 수 있습니다. IPOnDemand는 IP 조건이 필요한 규칙을 매칭할 때 조회를 수행할 수 있습니다. 설정하기 전에 도메인 조회 결과로 주소 범위를 매칭해야 하는지 먼저 확인하고 적절한 방식을 선택하세요. 호스트명으로만 분기한다면 추가 조회와 그에 따른 실패 가능성을 굳이 도입할 필요가 없습니다.
geosite:와 geoip:는 실제로 불러온 리소스 파일과 분류 이름에 따라 동작합니다. 같은 이름의 분류도 항상 동일한 것은 아니며 특정 도메인이나 네트워크가 포함되는지는 사용 중인 리소스를 기준으로 확인해야 합니다. 코어가 리소스를 찾지 못하거나 분류가 없다고 보고하는 문제와 리소스는 정상적으로 불러왔지만 주소가 목록에 없는 문제는 서로 다릅니다. 먼저 명시적인 도메인이나 범위를 아는 작은 네트워크로 매칭을 확인한 뒤 분류를 사용하세요. 같은 테스트가 실패해야 규칙 데이터베이스나 업데이트 결과로 문제 범위를 좁힐 수 있습니다.
05 도메인 조회
dns: 내장 DNS 리졸버, 정적 매핑, 조회 경로
먼저 누가 도메인을 조회하는지 확인하세요
앱이 직접 도메인을 조회한 뒤 IP를 인바운드에 전달할 수도 있고, 도메인을 프록시 요청에 포함해 코어에 넘길 수도 있습니다. 후자의 경우에도 코어가 원격 측에 도메인 처리를 맡기거나 라우팅 매칭 또는 직접 연결 단계에서 자체 조회를 수행할 수 있습니다. 최상위 dns 설정은 코어 내장 리졸버가 수행하는 조회를 제어하며 앱이나 운영체제의 모든 조회를 자동으로 가로채지는 않습니다. 브라우저가 별도의 DNS 기능을 사용하면 운영체제 조회 도구의 결과와 브라우저의 결과가 다를 수 있습니다. 어느 쪽도 코어가 어떤 설정을 사용하는지 단독으로 증명하지는 못합니다.
먼저 연결 하나를 기준으로 전체 경로를 정리하세요. 앱이 도메인과 IP 중 무엇을 전달하는지, 라우팅이 주소 매칭을 위해 조회하는지, 최종 아웃바운드가 직접 조회하는지 아니면 원격에 대상을 넘기는지 확인합니다. 여러 단계에서 같은 도메인을 조회할 수도 있고 아무 단계에서도 조회하지 않을 수도 있습니다. 예를 들어 앱이 IP를 코어에 전달하고 직접 연결 아웃바운드가 해당 주소로 연결하기만 한다면 원래 도메인에 대한 정적 매핑을 추가해도 결과가 바뀌지 않습니다. 매핑을 검증하려면 테스트 요청에 도메인이 유지되어야 하고 선택한 아웃바운드가 실제로 코어의 DNS 리졸버를 사용해야 합니다.
{
"dns": {
"hosts": {
"sample.test": "127.0.0.1"
},
"servers": ["localhost"]
},
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": { "domainStrategy": "UseIP" }
}
]
}
hosts, servers, 아웃바운드 domainStrategy 이해하기
예제의 hosts는 테스트 도메인을 루프백 주소에 연결하며 이 설정을 사용하는 코어에만 적용됩니다. servers의 localhost는 로컬 시스템의 DNS 기능을 사용한다는 뜻이지, 루프백 주소에서 DNS 서버를 새로 실행하라는 의미가 아닙니다. 127.0.0.1을 DNS 서버 주소로 직접 입력하는 것은 이 특수값을 사용하는 것과 다릅니다. 전자는 해당 주소와 포트에서 실제로 응답하는 서비스가 필요합니다. 정적 매핑은 주소만 반환하므로 애플리케이션 프로토콜의 핸드셰이크를 대신하거나 대상 도메인의 인증서를 제공하지 않습니다.
freedom.settings.domainStrategy는 직접 연결 아웃바운드가 도메인 대상을 처리하는 방법을 정하며 routing.domainStrategy와는 역할이 다릅니다. 이 예제에서는 UseIP를 사용해 직접 연결 아웃바운드가 도메인을 조회한 뒤 연결을 시도합니다. 라우팅 전략만 바꿨다고 해서 최종 연결에 어떤 주소가 사용됐는지 단정할 수는 없습니다. 테스트할 때는 루프백 주소에서 리스닝하는 정상 작동 중인 로컬 HTTP 서버를 사용하고, 도메인을 전달할 수 있는 SOCKS 앱으로 테스트 도메인과 서버의 실제 포트에 접속하세요. 서버가 요청 호스트명으로 사이트를 구분한다면 해당 테스트 호스트명도 허용하는지 확인해야 합니다.
업스트림에는 간단한 서버 항목을 사용할 수 있으며 일부 코어는 객체를 이용해 특정 도메인 범위에 서버를 지정할 수도 있습니다. 도메인에 따라 업스트림을 나눌 때 우선 어떤 서버를 선택하는지와 실패 후 다른 서버로 전환하는지는 별개의 문제입니다. 빈 응답, 조회 시간 초과, 예상과 다른 주소 반환도 구분해야 합니다. 여러 조회 방식을 한꺼번에 켜면 결과에 문제가 있다는 사실만 드러나고 어느 업스트림에서 오류가 났는지 알기 어렵습니다. 먼저 정상 작동이 확인된 조회 경로 하나만 남긴 다음 도메인 범위와 대체 경로를 추가해 하나씩 검증하세요.
주소 계열, 캐시, FakeDNS
하나의 도메인에 IPv4와 IPv6 주소가 모두 있을 수 있지만 현재 네트워크에서 두 주소 계열 모두 연결할 수 있는 것은 아닙니다. 먼저 조회 결과와 실제 접속 주소를 대조한 뒤 조회 또는 아웃바운드에서 주소 유형을 제한할지 판단하세요. 한쪽 조회 결과만 제외해도 해당 주소 계열의 네트워크 연결 문제가 해결되는 것은 아닙니다. 정적 레코드를 바꾼 뒤에도 앱, 운영체제, 코어, 업스트림에 남아 있는 캐시 때문에 이전 주소가 보일 수 있습니다. 검증할 때는 새 연결을 만들고 어느 계층의 캐시를 갱신했는지 확인하세요. 웹페이지 새로고침만 반복하지 마세요.
FakeDNS는 프록시 처리 과정에서 사용할 가상 주소를 반환합니다. 같은 경로에 있는 코어가 해당 주소와 연결된 도메인을 복원해야 하며, 실제 주소의 캐시를 일반적으로 대체하는 기능은 아닙니다. 앱이 가상 주소를 받은 뒤 코어를 우회하거나 주소 매핑이 사라지면 이후 연결에서 원래 도메인에 맞게 처리하기 어렵습니다. 일반적인 SOCKS 예제에서는 사용할 필요가 없습니다. 투명 프록시에서 주소가 전달되는 방식을 살펴보려면 FakeDNS 원리와 사용 사례를 확인하세요. 먼저 일반 DNS 조회를 정상화해야 가상 주소가 어느 단계에서 사용되는지 비교할 수 있습니다.
06 연결 관리
policy: 연결 시간 제한, 사용자 레벨, 통계 설정
레벨은 정책을 찾는 인덱스이지 권한 순서가 아닙니다
policy.levels는 사용자 레벨에 매개변수 묶음을 연결합니다. JSON 객체에서 레벨 키는 "0"처럼 문자열로 작성하지만 프로토콜 설정에서 사용자 레벨을 지정하는 필드는 보통 숫자를 사용합니다. 레벨은 요금제 이름도 아니며 숫자가 클수록 권한이 높은 것도 아닙니다. 어떤 연결이 어느 레벨을 사용하는지는 관련 인바운드 프로토콜과 사용자 레벨 필드에 따라 달라집니다. 처음 문제를 확인할 때는 기본 레벨부터 살펴보세요. policy에 실제로 참조되지 않는 새 레벨을 만들고 정책이 적용되지 않는다고 오해하지 마세요.
{
"policy": {
"levels": {
"0": {
"handshake": 8,
"connIdle": 300,
"uplinkOnly": 3,
"downlinkOnly": 10
}
},
"system": {
"statsInboundUplink": true,
"statsInboundDownlink": true
}
},
"stats": {}
}
이 조각은 루트 객체에 합쳐 넣을 설정이며 단독 실행용 전체 설정이 아닙니다. 수치는 필드의 의미를 설명하기 위한 예시이지 모든 네트워크에 권장되는 공통값이 아닙니다. 정책은 라우팅 대신 아웃바운드를 선택하지 않으며 인바운드의 리스닝 범위를 바꾸지도 않습니다. 인바운드 접속이 거부되거나 특정 항목의 연결이 실패할 때는 먼저 어느 단계에서 오류가 발생했는지 확인하세요. 핸드셰이크가 시작되지도 않았다면 세션 시간 제한을 늘려도 단서를 얻기 어렵습니다. 반대로 핸드셰이크는 항상 완료되지만 일정 시간 유휴 상태인 뒤 연결이 끊긴다면 정책 매개변수를 비교해 볼 수 있습니다.
네 가지 시간 제한이 각각 적용되는 단계
handshake는 초 단위로 설정하며 인바운드 프로토콜이 핸드셰이크를 완료할 때까지 기다리는 시간입니다. 모든 네트워크 작업에 적용되는 전체 타이머가 아닙니다. 브라우저가 첫 바이트를 기다리는 시간이나 원격 서비스 연결의 제한 시간과도 다릅니다. 이 설정을 확인할 때는 클라이언트가 포트에 연결했지만 핸드셰이크를 끝내지 못하는 경우와 핸드셰이크 후 상대가 데이터를 보내지 않는 경우를 구분하세요. 앱에 ‘연결 시간 초과’가 표시된다는 사실만으로 인바운드 핸드셰이크와 이후 연결 중 어느 설정을 조정해야 할지 알 수 없습니다.
connIdle은 연결이 시작된 뒤의 고정 수명이 아니라 데이터가 오가지 않은 시간을 측정합니다. 데이터를 계속 주고받는 연결은 이 시간이 지났다고 유휴 상태로 처리되지 않아야 합니다. uplinkOnly와 downlinkOnly는 한쪽 전송이 끝난 뒤 다른 쪽은 계속 전송할 수 있는 단계를 처리합니다. 상행만 남았을 때와 하행만 남았을 때 각각 적용됩니다. 앱이 전송 방향을 먼저 닫는지, 긴 응답을 계속 받아야 하는지 확인한 뒤 해당 시간 제한이 적절한지 판단하세요.
유휴 시간을 짧게 설정하면 장기간 사용하지 않은 연결을 빨리 정리할 수 있지만 가끔 데이터가 오가는 세션은 다시 연결해야 할 수 있습니다. 시간을 늘리면 당장 필요하지 않은 연결이 더 오래 유지됩니다. 연결이 끊기는 주기가 설정값과 비슷하더라도 앱, 원격 서버, 중간 네트워크 장비도 자체 시간 제한을 적용할 수 있으므로 단서로만 활용하세요. 지속 전송, 완전한 유휴 상태, 한쪽 전송 종료 상황을 나눠 비교하세요. 현상에 해당하는 설정 하나만 바꾸고 나머지는 그대로 두어야 코어 정책과 다른 연결 요소 중 무엇이 먼저 연결을 종료하는지 구분할 수 있습니다.
통계 설정만으로 인터페이스에 보고서가 생성되지는 않습니다
예제의 최상위 stats는 통계 모듈을 활성화하고 policy.system의 두 스위치는 인바운드별 업로드와 다운로드 기록을 요청합니다. 구분해야 하는 인바운드에는 변경하지 않을 태그를 지정하세요. 이름을 바꾸면 통계를 읽는 쪽에서도 새 이름을 사용해야 합니다. 다른 스위치는 사용자별 통계에 사용합니다. 사용자와 연결할 수 있는지는 프로토콜이 사용자 식별 정보를 제공하는지에 달려 있습니다. 시스템 수준의 인바운드 수치를 앱별 또는 구독 항목별 사용량으로 보면 안 됩니다. 두 기기가 같은 리스너를 사용하면 인바운드 통계에 두 기기의 요청이 모두 포함될 수 있습니다.
통계 설정은 코어가 관련 지표를 기록하도록 할 뿐입니다. 값을 볼 수 있는지는 클라이언트가 통계 조회 기능을 지원하는지와 어느 실행 인스턴스의 값을 읽는지에 따라 달라집니다. 조회 경로가 없다면 스위치를 켜도 설정 파일에 보고서가 기록되지 않습니다. 재시작 후 이전 프로세스의 통계가 새 프로세스에 자동으로 합산되는 것도 아닙니다. 인바운드 하나에서 구분하기 쉬운 트래픽을 조금 발생시킨 뒤 같은 인스턴스의 통계가 바뀌는지 확인하세요. 통계를 확인하려고 관리 인터페이스를 다른 기기에 공개하지 마세요.
07 설정 조합 검증
전체 설정 예제: 로컬 SOCKS, 직접 연결, 단일 도메인 차단
별도의 테스트 설정에서 진행하세요
아래 설정에는 원격 아웃바운드가 없으므로 구독이나 계정이 필요하지 않습니다. 로컬에서만 접속할 수 있는 SOCKS 인바운드 하나와 전체 도메인을 대상으로 하는 차단 규칙을 사용하고, 나머지 요청은 첫 번째 직접 연결 항목으로 보냅니다. 직접 연결 아웃바운드는 내장 DNS 리졸버에 도메인 처리를 요청하고, 리졸버는 로컬 시스템을 통해 결과를 얻습니다. 이 구성은 규칙 데이터베이스, 스니핑, 원격 연결을 의도적으로 제외했습니다. 앱에서 올바른 프록시 유형만 선택하면 인바운드, 대상 형식, 아웃바운드 참조를 먼저 확인할 수 있습니다. 구독을 정상적으로 가져오려면 구독 가져오기 가이드를 따르세요.
시작하기 전에 현재 사용 가능한 클라이언트 설정을 보관하고 사용자 지정 설정을 불러올 수 있는 테스트 환경에서 별도 파일을 선택하세요. 현재 실행 중인 코어가 전체 JSON 형식을 읽을 수 있는지, 예제 포트를 클라이언트가 이미 사용 중은 아닌지 확인합니다. 포트를 바꾸려면 예제의 인바운드 포트와 테스트 앱의 프록시 포트를 함께 바꾸면 됩니다. 도메인 매칭 항목은 수정하지 마세요. 테스트할 앱 하나의 프록시 설정만 바꾸고 기기 전체 트래픽을 대상으로 할 필요는 없습니다. 테스트가 끝나면 해당 앱 설정만 원래대로 돌리면 되므로 요청 출처도 쉽게 확인할 수 있습니다.
{
"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": {
"domainStrategy": "UseIP"
}
},
{
"tag": "block",
"protocol": "blackhole",
"settings": {
"response": { "type": "none" }
}
}
],
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"domain": ["full:example.org"],
"outboundTag": "block"
}
]
},
"dns": {
"servers": ["localhost"]
},
"policy": {
"levels": {
"0": { "connIdle": 300 }
}
}
}
웹페이지가 열리는지만 보지 말고 관찰 가능한 결과로 확인하세요
먼저 시작에 성공했는지 확인하세요. 설정 파싱이나 리스닝에 실패했다면 브라우저에서 반복 테스트할 필요가 없습니다. 시작한 뒤 테스트 앱에서 SOCKS5를 명시적으로 선택하고 로컬 리스닝 주소와 포트를 입력한 다음 도메인을 프록시에 전달하도록 설정합니다. 로컬에서 직접 연결할 수 있다고 확인된 테스트 호스트에 접속한 뒤 새 연결로 example.org에 접속하세요. 첫 요청은 직접 연결되고 두 번째는 차단되는 것이 예상 결과입니다. 첫 요청의 성공 여부는 로컬 환경과 대상의 연결 가능성에 달려 있으므로 원래 연결할 수 없던 대상을 성공 기준으로 사용하지 마세요.
차단도 기준 상태와 비교해야 검증할 수 있습니다. 유일한 규칙을 임시로 제거하고 rules를 빈 배열로 둔 상태에서 다시 불러와 테스트 도메인에 접속할 수 있는지 확인하세요. 그런 다음 규칙을 복원하고 새 요청을 보냅니다. 규칙이 있을 때 실패하고 제거한 뒤 성공해야 해당 규칙이 차이에 영향을 줬다고 볼 수 있습니다. 두 상태 모두 실패하면 차단에 성공했다고 단정할 수 없습니다. 둘 다 성공한다면 요청이 해당 인바운드를 통과하지 않았거나 앱이 먼저 도메인을 IP로 바꿨거나 설정 변경 전에 만든 연결을 사용했을 가능성을 확인하세요.
역방향으로도 확인하세요. 같은 인바운드에서 차단 대상과 다른, 연결 가능성이 확인된 호스트에 접속하고 규칙을 제거하거나 복원해도 동일한 영향이 없는지 확인합니다. 이렇게 하면 로컬 프록시 설정 오류로 모든 요청이 실패하는 상황과 특정 항목만 규칙에 의해 차단되는 상황을 구분할 수 있습니다. 대상과 인바운드 정보를 함께 기록하는 로그도 유용하지만 코어와 클라이언트마다 형식이 다릅니다. 현재 시점의 새 요청, 대상 형식, 선택된 아웃바운드를 확인하는 것이 중요하며 특정 가이드의 스크린샷과 로그 문구가 정확히 같을 필요는 없습니다.
설정을 확장할 때는 되돌릴 수 있는 기준 구성을 유지하세요
원격 아웃바운드를 추가하려면 현재 직접 연결 항목을 첫 번째로 유지하고 차단 규칙도 남겨 둔 채 새 아웃바운드를 뒤에 하나만 추가하세요. 그런 다음 확인된 대상에만 적용할 규칙을 만들어 새 아웃바운드를 지정합니다. 설정을 불러온 뒤 기존 대상과 새 대상을 각각 확인하세요. 기존 대상이 이전과 동일하게 동작해야 변경으로 기본 경로가 의도치 않게 바뀌지 않았다고 볼 수 있습니다. 예제를 클라이언트의 일상 설정에 복사할 때 기존 아웃바운드 배열이나 DNS 객체를 통째로 덮어쓰지 마세요. 항목을 하나씩 합치고 태그 참조를 확인하세요. 새 태그가 기존 객체 이름과 겹치지 않는지도 살펴봐야 합니다.
08 문제 진단 및 유지 관리
V2Ray 설정 문제: 파일 로드부터 대상 연결까지 단계별 진단
시작되지 않을 때: 읽기, 검증, 바인딩 오류를 구분하세요
아예 시작되지 않으면 첫 번째 오류를 기록해 두세요. 파싱 위치 오류라면 괄호, 쉼표, 복사 과정에서 들어간 전각 문자를 확인합니다. 필드 형식이나 프로토콜 이름 오류라면 필드 계층과 선택한 코어를 확인하세요. 주소 바인딩 오류라면 로컬 인터페이스와 포트 사용 여부를 살펴봅니다. 세 가지 오류는 해결 방법이 서로 다릅니다. 클라이언트에 일반적인 시작 실패만 표시될 수도 있으므로 클라이언트가 제공하는 코어 로그에서 처음 실패한 위치를 찾으세요. 뒤이어 발생하는 연결 오류는 인바운드가 시작되지 않은 결과일 수 있으니 첫 오류와 같은 방식으로 처리할 필요는 없습니다.
같은 파일이 다른 환경에서 불러와진다면 먼저 비교 대상이 같은 설정 형식인지 확인하세요. 한 클라이언트는 항목을 가져왔고 다른 클라이언트는 전체 JSON을 직접 읽은 상황일 수 있습니다. 규칙 데이터베이스 경로, 로그 디렉터리, 포트 사용 가능 여부도 실행 환경에 따라 달라집니다. 상대 경로의 기준 위치가 설정 파일이 있는 디렉터리라는 보장은 없습니다. 파일 탐색기에서 두 파일이 같은 폴더에 보인다는 이유만으로 경로가 올바르다고 판단하지 마세요. 외부 리소스를 참조하지 않는 설정으로 먼저 실행을 확인한 다음 파일 참조를 하나씩 복원하는 편이 모든 경로를 새 디렉터리에 한꺼번에 복사하는 것보다 차이를 찾기 쉽습니다.
시작은 되지만 동작이 예상과 다를 때: 처음 어긋나는 단계부터 찾으세요
| 증상 | 먼저 확인할 항목 | 다음 단계 |
|---|---|---|
| 앱이 로컬 프록시에 연결하지 못함 | 리스닝 주소와 포트 | 프로세스 실행 여부와 주소 계열 일치 여부 확인 |
| 핸드셰이크 실패 | 앱에서 선택한 프록시 프로토콜 | 인바운드 프로토콜과 인증 방식 확인 |
| 잘못된 아웃바운드에 매칭됨 | 대상 형식과 규칙 순서 | 인바운드 조건, 태그, 기본 항목 확인 |
| 아웃바운드는 맞지만 연결되지 않음 | DNS 조회와 아웃바운드 연결 | 주소에 연결할 수 없는 경우와 원격 핸드셰이크 실패 구분 |
| 유휴 상태가 된 뒤에만 연결이 끊김 | 연결 단계와 유지 시간 | 앱, 정책, 원격 측 시간 제한 비교 |
‘모든 앱이 안 됨’과 ‘특정 앱만 안 됨’을 구분하면 원인을 찾기 쉽습니다. 모든 요청이 인바운드에 도달하지 않는다면 시스템 프록시나 테스트 앱의 개별 설정부터 확인하세요. 일부 앱은 시스템 프록시를 따르지 않습니다. 특정 앱만 실패한다면 프록시에 도메인을 전달하는지, 다른 전송 방식을 사용하는지, 기존 연결을 계속 사용하는지 살펴보세요. 도메인 규칙 하나를 확인하려고 기기의 프록시 모드, 앱의 DNS 방식, 코어의 라우팅 전략을 한꺼번에 바꾸지 마세요. 정상으로 돌아와도 어느 설정이 영향을 줬는지 알 수 없게 됩니다.
인바운드에 요청이 들어오고 규칙도 예상한 아웃바운드를 가리킨다면 다음 단계는 라우팅 순서를 바꾸는 것이 아닙니다. 직접 연결과 원격 연결 경로를 각각 확인해 오류가 발생한 지점을 찾으세요. 로컬 주소 조회 실패, 원격 주소 연결 불가, 아웃바운드 핸드셰이크 중단, 대상 서비스 연결 실패를 구분합니다. 특정 대상 하나에 연결됐다고 다른 모든 대상도 연결 가능하다는 뜻은 아닙니다. 비교할 때는 테스트 앱과 대상을 그대로 유지하고 한 항목을 바꾼 뒤 새 요청을 보내세요. 간헐적인 문제라면 발생 전후 시간과 네트워크 전환 또는 절전 여부를 기록하면 설정 문제와 일시적인 연결 변화를 구분하는 데 도움이 됩니다.
임시 로그와 작은 변경으로 진단 근거를 남기세요
{
"log": {
"loglevel": "info"
}
}
단서가 더 필요하면 기존 log 객체에 조각의 loglevel을 합쳐 로그 상세 수준을 잠시 높일 수 있습니다. 클라이언트가 로그 표시 위치와 필터를 별도로 제어할 수 있으므로 창에 기록이 보이지 않는다고 코어에 요청이 전달되지 않았다고 단정할 수는 없습니다. 동작 하나만 재현하고 시간을 기록한 뒤 예상한 인스턴스의 로그에 남았는지 확인하세요. 진단이 끝나면 평소 로그 수준으로 되돌립니다. 진단 정보를 공유하기 전에 구독 주소, 인증 정보, 개인 식별이 가능한 대상 기록을 삭제하세요. 전체 설정을 그대로 전달하지 마세요.
일상적인 유지 관리를 위해 용도가 다른 사본 두 개를 보관할 수 있습니다. 하나는 시작이 확인된 최소 예제이고 다른 하나는 최근에 정상 작동을 확인한 실제 설정입니다. 클라이언트를 업데이트하거나 코어를 바꾼 뒤에는 새 기능을 켜기 전에 일상 설정으로 고정된 인바운드 및 분기 테스트를 실행하세요. 문제가 다시 발생하면 최소 예제로 기본 구조가 여전히 동작하는지 확인하고, 원래 설정의 DNS, 라우팅, 원격 아웃바운드를 차례로 추가합니다. 마지막으로 어떤 항목이 클라이언트에서 생성됐는지, 외부 리소스에서 왔는지, 직접 관리하는지 기록해 두세요. 다음에 설정을 덮어쓰거나 옮길 때 유지해야 할 계층을 쉽게 확인할 수 있습니다.