V2Ray 설정 파일 JSON 구조 해설: inbounds·outbounds·routing 이해하기

V2Ray 설정 파일의 log, inbounds, outbounds, routing, dns 구조와 tag 연결, 규칙 우선순위, 주요 필드 작성법을 예제와 함께 살펴봅니다.

이 글의 핵심 내용

클라이언트가 생성한 JSON을 받았다면 먼저 어느 부분이 요청을 받고, 어느 부분이 경로를 선택하며, 어느 부분이 연결을 만드는지 알아야 합니다. 이 글에서는 로컬 SOCKS와 HTTP 인바운드 예제로 tag가 규칙을 연결하는 방식을 살펴보고, 라우팅 단계의 도메인 해석과 아웃바운드 해석, 앱 자체의 해석을 구분합니다. 예시 포트는 설명용이며 클라이언트 기본값이 아닙니다.

log: 로그와 설정 구조

최상위에는 JSON 객체가 하나 있습니다. 이 글에서 log, routing, dns는 객체이고, inbounds와 outbounds는 배열입니다. 항목이 하나뿐이어도 대괄호를 유지합니다. 최상위 키의 순서는 요청 경로를 결정하지 않지만 배열 안의 순서는 영향을 줄 수 있습니다. 규칙은 배열 순서대로 검사하며, 일치하는 규칙이 없으면 일반적으로 첫 번째 아웃바운드가 사용됩니다.

앱 요청로컬 인바운드규칙 검사아웃바운드 선택대상 연결
{
  "log": {
    "loglevel": "warning"
  }
}

이 코드는 로그 설정 예시입니다. 문제를 진단할 때는 loglevel을 잠시 info로 바꾸고 설정을 다시 불러온 뒤 같은 앱에서 한 번 재현해 보세요. 필요한 기록을 확보한 다음에는 warning으로 되돌립니다. access와 error에는 각 로그를 저장할 파일을 지정할 수 있지만, 설정을 읽을 수 있다고 해서 로그 디렉터리에 쓰기까지 가능한 것은 아닙니다. 시작 단계에서 문제가 발생했다면 액세스 로그만 기다리지 말고 클라이언트나 실행 프로세스의 안내를 먼저 확인하세요. 로그를 공유하기 전에는 구독 주소, 인증 정보, 공개하기 곤란한 연결 기록을 가리세요.

inbounds: 리슨 주소, 로컬 포트와 tag

인바운드의 listen과 port는 리슨 주소와 포트를 지정하고, protocol은 앱에서 사용해야 하는 프록시 프로토콜을 결정합니다. settings는 해당 프로토콜에 따라 해석됩니다. 앱의 HTTP 프록시 설정에 SOCKS 포트를 입력하면 포트가 열려 있어도 올바른 프로토콜 핸드셰이크를 완료할 수 없습니다. 아래 두 항목은 모두 로컬 루프백 주소에서만 수신하며, 로컬 네트워크에는 공개되지 않습니다.

10808
예시 SOCKS 리슨 포트
10809
예시 HTTP 리슨 포트

SOCKS 인바운드

listen
127.0.0.1
port
10808
protocol
socks
tag
local-socks

앱의 SOCKS 프록시 설정에 이 포트를 입력하세요.

HTTP 인바운드

listen
127.0.0.1
port
10809
protocol
http
tag
local-http

앱의 HTTP 프록시 설정에 이 포트를 입력하세요.

리슨 상태를 먼저 확인한 뒤 라우팅을 수정하세요

로컬 포트에 연결하자마자 거부된다면 먼저 코어가 실행 중인지, 다른 프로세스가 포트를 사용 중인지, 앱에 입력한 주소가 실제 리슨 주소와 일치하는지 확인하세요. 요청이 코어에 도달하기도 전이므로 라우팅 규칙의 우선순위를 높여도 해결되지 않습니다.

outbounds: 아웃바운드 프로토콜과 기본 경로

아웃바운드의 protocol은 수신한 대상 연결을 처리하는 방식을 결정합니다. freedom은 직접 연결할 때, blackhole은 연결을 차단할 때 사용합니다. tag는 설정 안에서 참조하는 이름이지 프로토콜명이 아닙니다. tag를 direct라고 지정해도 자동으로 직접 연결되는 것은 아니며, 동작을 결정하는 것은 같은 항목의 protocol입니다.

{
  "outbounds": [
    {"tag": "direct", "protocol": "freedom", "settings": {}},
    {"tag": "blocked", "protocol": "blackhole", "settings": {}}
  ]
}

routing: tag 연결과 규칙 검사 순서

routing.rules는 위에서 아래로 검사하며, 처음 일치한 규칙이 연결 경로를 결정합니다. 규칙의 inboundTag는 인바운드 tag 배열이고, outboundTag는 아웃바운드 tag 문자열 하나입니다. 여러 조건이 함께 지정되면 요청은 해당 조건을 모두 만족해야 합니다. 아래 첫 번째 규칙은 SOCKS 인바운드로 들어왔고 대상 도메인이 정확히 example.org인 요청만 차단합니다. 두 번째 규칙은 나머지 SOCKS 요청을 직접 연결합니다.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "domain": ["full:example.org"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}
유입 경로코어가 받은 대상예상 아웃바운드
SOCKSexample.org첫 번째 규칙: blocked
SOCKSwww.example.org두 번째 규칙: direct
HTTPexample.org일치하는 규칙 없음: 첫 번째 아웃바운드 direct

두 규칙의 순서를 바꾸면 이전 두 번째 규칙이 모든 SOCKS 요청을 먼저 처리하므로, 정확한 도메인 규칙은 적용되지 않습니다. 아웃바운드 두 항목의 순서만 바꾸고 규칙 순서는 유지하면 tag를 명시한 요청은 기존 경로를 따르지만, 어떤 규칙에도 일치하지 않는 HTTP 요청은 새 첫 번째 아웃바운드로 향합니다. 잘못된 라우팅을 진단할 때는 두 배열의 순서를 각각 확인하고, 기본 아웃바운드를 마지막 라우팅 규칙으로 착각하지 마세요.

dns: 라우팅 단계의 해석과 앱의 해석 구분

최상위 dns는 코어에 내장된 DNS를 설정하며, 운영체제의 전역 DNS 설정과는 다릅니다. dns.servers만 추가해도 모든 앱의 DNS 요청을 자동으로 처리하지는 않습니다. 앱이 먼저 도메인을 해석한 뒤 대상 IP만 프록시에 전달하면 라우팅 단계에서 그 IP만으로 원래 도메인을 복원할 수 없습니다. 다른 도메인 정보가 없다면 위의 정확한 도메인 조건은 일치하지 않습니다.

{
  "dns": {
    "servers": ["localhost"]
  }
}

여기서는 localhost를 사용해 로컬의 이름 해석 기능을 호출하므로 시스템에 설정된 해석 구성을 그대로 활용할 수 있습니다. 이는 로컬 포트에서 DNS 서비스를 시작한다는 뜻도, 최종 연결의 아웃바운드를 결정한다는 뜻도 아닙니다. 도메인 규칙을 확인하려면 테스트 요청이 도메인 형태로 인바운드에 전달되는지, 앱에서 이미 IP로 바뀌었는지 먼저 살펴보세요.

설정 문제 해결: 시작, 인바운드, 라우팅, 아웃바운드 순으로 확인

  1. 실제로 불러온 파일부터 확인하세요. 엄격한 JSON에서는 큰따옴표를 사용하고 마지막 항목 뒤에는 쉼표를 붙이지 않습니다. 위 코드 블록은 서로 다른 최상위 필드를 각각 보여 주므로 여러 루트 객체를 그대로 이어 붙일 수 없습니다. 오류가 특정 필드를 가리킨다면 파일이 유효한 JSON이어도 해당 필드의 자료형과 코어 지원 여부를 확인해야 합니다.
  2. 코어 설정과 클라이언트 설정의 범위를 구분하세요. 데스크톱 v2rayN에서는 「설정」→「매개변수 설정」에서 로컬 리슨 구성을 확인할 수 있으며, 메뉴 구성은 버전에 따라 다를 수 있습니다. Android의 v2rayNG는 Xray 코어를, v2flyNG는 V2Fly 코어를 사용합니다. 기본 필드가 비슷해도 확장 필드까지 서로 호환되는 것은 아닙니다. Android에서 VPN으로 트래픽을 처리하는 범위도 데스크톱 시스템 프록시 설정만으로 판단할 수 없습니다.
  3. 같은 테스트 앱에서 한 번에 한 항목만 바꾸세요. 먼저 올바른 포트로 일반 요청을 확인한 다음 차단 대상도 테스트합니다. 앱을 HTTP 프록시로 바꿨을 때 결과가 달라지면 인바운드 tag를 비교하세요. 같은 인바운드에서 도메인 요청과 IP 요청의 결과가 다르면 앱이 어떤 형태의 대상을 코어에 전달했는지 확인합니다.
  4. 마지막으로 아웃바운드 연결을 확인하세요. 예상한 tag가 선택됐다고 해서 대상에 반드시 연결되는 것은 아닙니다. 직접 연결이 실패하면 로컬 이름 해석과 대상에 도달할 수 있는지 확인하세요. 원격 아웃바운드가 실패하면 원격 포트, 프로토콜 매개변수, 전송 설정을 점검합니다. 한 번에 한 곳만 수정하고 설정을 다시 불러온 뒤 같은 테스트를 반복해야 어떤 변경이 결과에 영향을 줬는지 파악할 수 있습니다.
클라이언트 다운로드플랫폼에 맞는 v2rayN / v2rayNG 선택