설정 파일 참고서

V2Ray JSON 설정 가이드

처음 설치하거나 구독을 가져오고 연결을 확인하려면 먼저 시작 가이드를 따라가세요. 연결은 되지만 필드의 의미를 확인하거나 트래픽이 어디로 들어오는지 파악하고 규칙을 수정하려면 이 가이드를 참고하면 됩니다. 예제는 로컬 루프백 인바운드와 일반 직접 연결을 기준으로 합니다. 용어를 확인하려면 개념 빠른 참조도 함께 살펴보세요.

01 기본 파일 구조

JSON 구조 개요

하나의 연결 흐름을 따라 설정 읽기

앱이 로컬 수신 포트로 요청을 보내면 인바운드가 프로토콜에 따라 대상 주소를 읽습니다. 라우팅은 확인 가능한 대상 정보, 인바운드 태그 및 기타 조건을 바탕으로 아웃바운드를 선택합니다. 아웃바운드는 실제 연결을 담당하며, 직접 연결하거나 노드 설정에 따라 원격 서버와 통신할 수 있습니다. 특정 필드가 어디에 영향을 주는지 판단하려면 먼저 이 연결 흐름의 어느 단계에 해당하는지 살펴보세요. 수신 주소를 바꿔도 노드가 바뀌는 것은 아니며, 아웃바운드 주소를 바꿔도 원래 프록시를 사용하지 않던 앱이 인바운드로 연결되는 것은 아닙니다.

최상위에는 객체 하나가 있어야 하며, 인바운드와 아웃바운드, 규칙을 하나의 목록에 나란히 넣는 구조가 아닙니다. inbounds와 outbounds는 각각 여러 인바운드와 아웃바운드를 담는 배열이고, routing, dns, policy는 각각 내부 구조를 갖는 객체입니다. 필드 이름은 대소문자를 구분하며 배열 순서도 동작에 영향을 줄 수 있습니다. 특히 아웃바운드 배열의 첫 항목과 규칙 배열의 첫 규칙은 다릅니다. 전자는 기본 아웃바운드이고, 후자는 가장 먼저 일치 여부를 확인하는 후보 규칙입니다.

실행 가능한 직접 연결 기준 만들기

아래는 완전한 네이티브 설정 파일입니다. 로컬 루프백 주소에서 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", "settings": {} }
  ]
}

기준 설정에는 라우팅을 넣지 않았습니다. 아웃바운드가 하나뿐이므로 어떤 규칙에도 일치하지 않는 요청의 목적지가 이미 정해져 있기 때문입니다. 첫 테스트에서 시스템 DNS, 코어 DNS, 대기 시간 초과를 한꺼번에 섞지 않도록 내장 DNS와 연결 정책도 제외했습니다. 실행에 성공하면 트레이 아이콘이나 화면 상태만 보는 대신, SOCKS를 지원하는 앱에서 예시 주소를 지정해 테스트하세요. 웹사이트를 열기 전, 로컬에서만 제공되고 현재 사용자에게 접근이 허용된 서비스를 확인해 로컬 연결 경로를 먼저 점검할 수도 있습니다.

예제를 올바른 계층에 병합하기

이후에 최상위 조각으로 표시된 코드는 유효한 JSON이지만, 단독으로 실행할 수 있다는 뜻은 아닙니다. 최상위 필드를 추가할 때는 해당 키와 값을 기준 설정의 같은 객체에 병합하세요. 기존 필드를 수정할 때는 해당 값을 바꾸거나 배열에 객체를 추가하면 됩니다. 바깥 중괄호가 있는 파일 두 개를 그대로 이어 붙이지 말고, 같은 객체에 동일한 키를 두 번 쓰지 마세요. 파서마다 중복 키 처리 방식이 다를 수 있으며, 읽기에 성공하더라도 뒤에 나온 부분만 적용될 수 있습니다.

최상위 필드구조수정 후 가장 먼저 확인할 항목
inbounds객체 배열앱에서 사용하는 프로토콜, 주소, 포트가 모두 일치하는지 확인합니다.
outbounds객체 배열기본 아웃바운드 위치와 규칙에서 참조하는 태그가 여전히 올바른지 확인합니다.
routing객체규칙이 예상한 순서로 평가되는지, 대상이 예상한 첫 규칙에 일치하는지 확인합니다.
dns객체앱, 라우팅 판단, 아웃바운드 연결 중 어느 단계에서 이름을 해석하는지 확인합니다.
policy객체테스트 연결에 실제 적용되는 레벨이 수정한 항목과 일치하는지 확인합니다.

기준 설정과 편집 중인 사본을 각각 저장하고, 같은 요청으로 수정 전후 결과를 비교하세요. 표준 JSON은 큰따옴표를 사용하고 마지막 항목 뒤에 쉼표를 붙이지 않으며, 불리언은 문자열이 아닌 소문자 리터럴로 작성합니다. 형식 검사는 파일을 파싱할 수 있는지만 확인할 뿐, 현재 코어가 필드를 지원하는지 또는 참조한 태그가 존재하는지는 보장하지 않습니다. 형식 검사에 통과한 뒤에는 실행 결과를 확인하고, 다음으로 개별 연결의 실제 동작을 살펴보세요. 이 세 가지 판단을 구분해야 문제 발생 시 확인할 계층을 좁힐 수 있습니다.

이 가이드의 최소 파일은 독립 실행용입니다. 클라이언트가 같은 포트를 관리 중이라면 기존 인스턴스를 먼저 중지하거나 비어 있는 포트를 사용하세요. 두 프로세스의 수신 포트 충돌을 설정 문법 오류로 오해하지 않도록 합니다.

02 로컬 인바운드

inbounds 인바운드

수신 주소와 앱 프로토콜을 함께 확인

각 인바운드에서는 세 가지를 확인해야 합니다. 연결을 받는 주소, 수신 포트, 데이터를 읽는 프로토콜입니다. listen은 바인딩 주소이지 클라이언트가 접속할 대상 사이트가 아닙니다. port는 로컬 진입점이며 원격 노드의 포트가 아닙니다. protocol은 앱에서 선택할 프록시 유형을 결정합니다. HTTP 프록시 요청을 SOCKS 포트로 보내거나 SOCKS 요청을 일반 HTTP 서버로 보내면 포트 연결은 되지만 실제 요청은 실패할 수 있습니다.

로컬 앱에서 사용할 때는 먼저 127.0.0.1을 사용하세요. 수신을 로컬로 제한하지만 로컬의 다른 프로세스는 해당 인바운드에 접근할 수 있습니다. 연결 실패를 해결하려고 인증이 없는 예제를 모든 인터페이스에서 수신하도록 바꾸지 마세요. 앱과 코어가 IPv4 루프백을 사용하기로 했다면 같은 주소를 계속 지정하세요. 앱이 localhost를 IPv6 루프백으로 먼저 해석하고 코어는 IPv4에서만 수신하는 상황을 피할 수 있습니다. 컨테이너나 가상 머신의 루프백은 각자의 네트워크 환경에 속하므로 호스트 주소를 대신할 수 없습니다.

SOCKS와 HTTP를 별도 인바운드로 분리하기

아래 최상위 조각으로 기준 파일의 기존 inbounds를 바꿀 수 있습니다. SOCKS와 HTTP 프록시를 서로 다른 포트에 배치하고 각 인바운드에 별도 태그를 지정합니다. 브라우저에서 어떤 유형을 지원하는지, 터미널 도구에서는 어떤 매개변수를 써야 하는지는 해당 도구의 프록시 설정을 확인하세요. HTTP 인바운드는 HTTP 프록시를 지원하는 앱의 요청을 받을 수 있으며 CONNECT를 통한 전달도 가능합니다. 임의의 브라우저 페이지 요청을 받는 웹사이트 서비스가 아닙니다.

{
  "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": {}
    }
  ]
}

태그는 설정 내부에서 인바운드를 식별하는 용도입니다. 앱에서 지정하는 것은 유형, 주소, 포트이며 태그가 코어로 전달되지는 않습니다. 라우팅은 inboundTag를 통해 이 식별자를 확인할 수 있습니다. 따라서 앱 A가 SOCKS를, 앱 B가 HTTP를 고정해서 사용하면 서로 다른 인바운드로 경로를 구분할 수 있습니다. 두 앱이 같은 인바운드를 사용하면 태그로 구분할 수 없습니다. 태그를 변경할 때는 참조하는 모든 곳도 검색하세요. 인바운드 객체만 바꾸면 기존 규칙은 더 이상 일치하지 않을 수 있습니다.

UDP와 대상 식별은 서로 다른 설정

예제에서는 기준 설정이 일반적인 웹 연결을 확인하는 용도이므로 SOCKS의 UDP 지원을 끕니다. SOCKS UDP를 지원하는 앱을 점검하려면 앱이 실제로 UDP 전달을 요청하는지, 해당 SOCKS 인바운드에서 UDP를 허용하는지, 이후 아웃바운드가 해당 트래픽을 전달할 수 있는지 모두 확인해야 합니다. 인바운드 옵션만 켜서는 나머지 두 단계가 해결되지 않습니다. 반대로 TCP를 사용하는 요청을 테스트한다면 UDP 옵션을 바꿔도 진단에 도움이 되지 않습니다. 먼저 연결 유형을 확인한 뒤 필요한 테스트를 추가하세요.

앱은 도메인 이름을 SOCKS에 직접 전달할 수도 있고, 로컬에서 먼저 해석한 뒤 IP 주소만 코어로 보낼 수도 있습니다. 후자의 경우 도메인 라우팅 조건만으로는 원래 입력한 도메인을 확인하지 못할 수 있습니다. 일부 인바운드는 sniffing을 통해 지원되는 상위 계층 트래픽에서 대상 정보를 식별할 수 있지만, 결과는 프로토콜과 확인 가능한 데이터, 현재 코어 구현에 따라 달라집니다. 명확한 앱 프록시 설정을 대신할 수는 없습니다. 문제를 확인할 때는 먼저 추가 식별 기능을 끄고 도메인과 IP를 각각 프록시에 전달한 결과를 비교한 다음, 필요한 경우에만 사용하세요.

로컬 수신에 실패하면 주소를 바인딩할 수 없는 문제와 포트가 이미 사용 중인 문제를 먼저 구분하세요. 전자는 입력한 주소를 로컬에서 사용할 수 있는지 확인하고, 후자는 어떤 프로세스가 포트를 점유했는지 확인한 뒤 기존 인스턴스를 중지하거나 포트를 바꾸세요. 포트를 바꾼 뒤에는 브라우저, 터미널, 시스템 프록시 등 해당 인바운드를 가리키는 모든 설정도 함께 변경해야 합니다. 그렇지 않으면 새 인스턴스는 정상이어도 앱은 이전 포트에 계속 접속합니다. 로컬 포트 충돌 문제 해결을 참고하세요. 수신 프로세스가 보인다는 이유만으로 종료하지 마세요.

03 연결 아웃바운드

outbounds 아웃바운드

첫 항목은 기본 아웃바운드, 태그는 참조 이름

아웃바운드는 코어가 대상을 확인한 뒤 연결을 처리하는 방식을 정의합니다. freedom은 대상에 직접 접속하고, blackhole은 해당 아웃바운드로 전달된 트래픽을 버립니다. 둘 다 원격 계정이 필요 없으므로 규칙을 점검할 때 비교 대상으로 쓰기 좋습니다. 태그는 용도에 따라 이름을 정할 수 있지만, direct라는 이름을 붙였다고 자동으로 직접 연결되는 것은 아닙니다. 실제 동작은 protocol 등의 필드로 결정됩니다. 규칙에는 태그를 적으며 프로토콜 이름이나 구독 목록에 표시된 노드 이름을 적는 것이 아닙니다.

일치하는 규칙이 없으면 연결은 아웃바운드 배열의 첫 항목으로 전달됩니다. 따라서 ‘객체를 추가하는 것’과 ‘객체를 첫 항목으로 옮기는 것’은 다른 작업입니다. 첫 항목이 직접 연결이었는데 트래픽 폐기 아웃바운드를 맨 앞으로 옮기면 어떤 규칙에도 처리되지 않은 일반 요청도 폐기됩니다. 반대로 원격 노드를 사용해야 하는 트래픽이 규칙 설정을 빠뜨렸을 때 첫 항목이 직접 연결이면 해당 트래픽은 직접 연결로 돌아갑니다. 기본 동작을 정한 다음 아웃바운드 순서를 정하고, 화면에 노드가 먼저 표시된다는 이유만으로 순서를 결정하지 마세요.

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

위 조각으로 기준 파일의 outbounds를 바꾼 뒤에도 규칙을 추가하지 않았다면 요청이 자동으로 blocked에 들어가지는 않습니다. 이 조각은 다음 장의 라우팅 조각과 함께 사용합니다. 보조 아웃바운드에는 서로 다른 태그를 지정하고 첫 항목은 그대로 두면, 모든 일반 요청에 영향을 주지 않고 규칙의 테스트 범위를 좁힐 수 있습니다. 기준 설정으로 되돌리려면 삭제할 태그를 참조하는 규칙이 남아 있지 않은지 먼저 확인하세요.

프로토콜·전송·보안 설정을 각각 확인

원격 노드를 사용할 때는 아웃바운드의 프로토콜, 노드 주소와 포트, 인증 정보, 하위 전송 방식, 보안 설정이 서버와 일치해야 합니다. 프로토콜 필드는 세션 구성 방식을 설명하고, settings에는 해당 프로토콜에 필요한 대상과 인증 정보를 넣습니다. 일반적으로 streamSettings는 원격 연결에 사용하는 전송 및 보안 매개변수를 설명합니다. 프록시 요청으로 접속할 웹사이트와 아웃바운드가 연결하는 원격 노드는 서로 다른 대상입니다. 두 대상 모두 도메인 이름 해석이 필요할 수도 있습니다.

문제를 해결할 때 설정 전체를 바로 다시 작성할 필요는 없습니다. 먼저 현재 노드의 호스트 이름과 포트를 비교하고, 다음으로 전송 유형과 관련 매개변수를 확인한 뒤, 마지막으로 보안 협상이 서버와 일치하는지 살펴보세요. TCP 연결은 되지만 협상 단계에서 실패한다면 로컬 수신 포트만 바꿔서는 대개 해결되지 않습니다. 호스트 이름, 인증서, 시간 설정 오류를 가리려고 보안 검증을 끄지 마세요. 현재 보안 요구사항은 유지하면서 노드 제공자가 안내한 연결 매개변수와 설정을 대조하세요.

클라이언트 목록의 구독 주소, 표시 이름, 네이티브 아웃바운드는 서로 다른 종류의 항목입니다. 구독은 노드 목록을 제공하고, 클라이언트는 선택한 노드와 코어에 따라 실행에 필요한 아웃바운드를 생성합니다. 구독 주소를 원격 노드 주소 필드에 입력해도 같은 결과가 나오지 않으며, 화면에 표시된 메모를 규칙의 outboundTag에 복사해도 유효하지 않을 수 있습니다. 생성된 설정을 확인하려면 이전에 내보낸 예제가 아니라 현재 인스턴스가 실제로 불러온 설정을 살펴보세요. 구독의 노드 선택 조건은 노드 선택 안내를 참고하세요.

비교 요청으로 문제 범위 좁히기

같은 테스트 대상을 선택해 정상적인 직접 연결 아웃바운드와 확인하려는 원격 아웃바운드로 각각 새 요청을 보내세요. 직접 연결은 정상이고 원격 연결만 실패한다면 이번 테스트에서 앱 프록시, 수신, 직접 연결 경로는 정상이라는 뜻입니다. 다음으로 원격 매개변수와 핸드셰이크 단계를 확인하세요. 두 경로 모두 실패하면 공통 인바운드와 대상 접근성, 이름 해석 과정부터 확인합니다. 전환한 뒤에는 새 연결을 만들어야 합니다. 브라우저에 남은 이전 세션이 기존 연결을 계속 재사용하면 새 설정의 결과처럼 보일 수 있습니다.

04 매칭 순서

routing 라우팅 규칙

먼저 일치한 규칙 적용, 미일치 시 기본 아웃바운드 사용

routing.rules는 앞에서부터 확인하며 한 규칙이 일치하면 같은 요청에 대해 뒤의 규칙으로 아웃바운드를 다시 선택하지 않습니다. 하나의 규칙에 도메인 조건과 인바운드 조건을 함께 넣으면 두 조건이 모두 충족되어야 일치합니다. 같은 도메인 조건 배열에 선택 가능한 값을 여러 개 넣으면 일반적으로 그중 하나만 일치해도 됩니다. ‘특정 인바운드에서 들어온 지정 도메인’을 표현하려면 한 규칙에 함께 넣고, ‘어느 인바운드에서 왔든 해당 조건 또는 별도의 대상 조건’을 표현하려면 보통 규칙을 나눠야 합니다.

범위가 좁은 예외 규칙을 범위가 넓은 규칙보다 앞에 두세요. 예를 들어 ‘로컬 SOCKS에서 들어온 특정 전체 도메인’을 먼저 확인하고, 다음으로 ‘로컬 SOCKS에서 들어온 모든 요청’을 확인합니다. 뒤의 규칙을 먼저 쓰면 앞의 규칙은 일치할 기회가 없습니다. 어떤 규칙에도 일치하지 않는 요청은 목록의 마지막 규칙에 지정된 아웃바운드로 자동 전달되지 않고, 첫 번째 아웃바운드로 전달됩니다. 따라서 규칙 목록과 아웃바운드 순서를 함께 확인해야 합니다. 특히 클라이언트가 생성한 설정에서 일부 규칙만 가져올 때 주의하세요.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "domain": ["full:example.com"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "inboundTag": ["local-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}

이 조각을 기준 설정에 병합하고 이전 장의 blocked가 포함된 아웃바운드 배열을 사용하면 두 도메인을 비교해 확인할 수 있습니다. SOCKS를 통해 도메인 이름을 프록시에 전달하면 정확히 example.com과 일치하는 첫 번째 규칙이 적용되고, 다른 도메인은 두 번째 규칙으로 넘어갑니다. 로컬 HTTP 인바운드에서 들어온 요청은 두 규칙의 인바운드 조건에 해당하지 않으므로 기본 아웃바운드를 사용합니다. 앱이 대상을 미리 IP 주소로 해석했다면 첫 번째 규칙은 일치하지 않을 수 있습니다. 이때는 규칙 순서를 의심하기 전에 대상이 어떤 형식으로 전달됐는지 확인하세요.

도메인 매칭과 주소 매칭을 각각 검증

full:은 도메인 전체가 일치하는 경우를 뜻합니다. 도메인과 그 하위 도메인까지 매칭하려면 domain: 형식을 사용하세요. 접두사가 없는 일반 문자열은 부분 문자열로 매칭되므로 너무 짧게 쓰면 관련 없는 이름까지 포함할 수 있습니다. 같은 규칙 대상을 도메인이나 IP로 지정할 수 있지만, 각각 서로 다른 형식의 입력을 대상으로 합니다. 같은 IP 주소를 공유하는 사이트는 일반적으로 IP 규칙만으로 도메인을 구분할 수 없습니다. 앱이 이미 주소를 해석한 경우에도 도메인 규칙이 원래 이름을 자동으로 복구하지 못합니다.

domainStrategy는 라우팅에서 어떤 경우에 DNS 해석 결과를 사용해 IP 규칙을 판단할지 제어합니다. 아웃바운드가 같은 방식으로 연결한다는 뜻은 아닙니다. AsIs는 라우팅 매칭을 위해 도메인을 IP로 변환하지 않습니다. IPIfNonMatch는 원래 정보로 일치하는 규칙이 없을 때 도메인을 해석한 뒤 다시 매칭을 시도합니다. IPOnDemand는 IP가 필요한 규칙을 확인할 때 도메인을 해석할 수 있습니다. 앞의 넓은 범위 규칙이 먼저 일치하면 뒤의 규칙은 확인되지 않으며, DNS 서버를 추가해도 달라지지 않습니다.

새 규칙에 긍정 사례와 부정 사례 준비하기

새 규칙을 추가할 때는 규칙과 일치해야 하는 요청 하나, 이름은 비슷하지만 일치하면 안 되는 요청 하나, 전혀 관련 없는 대상 하나를 준비하세요. 각 요청의 인바운드 태그, 코어에 전달되는 대상 형식, 실제 아웃바운드를 기록합니다. geoip: 또는 geosite:를 사용하려면 코어에서 해당 데이터를 읽을 수 있고 지정한 카테고리가 실제로 있는지도 확인해야 합니다. 규칙 문법이 올바르더라도 로컬에 필요한 데이터가 설치되어 있다는 뜻은 아닙니다. 매칭 순서를 빠르게 확인하려면 데이터 파일에 의존하지 않는 정확한 도메인이나 명시적인 주소 범위를 먼저 사용하세요.

마지막으로 ‘트래픽이 코어에 들어왔는지’와 ‘들어온 뒤 어떻게 분기되는지’를 구분하세요. 시스템 프록시는 일부 앱의 요청을 로컬 인바운드로 보내는 방법 중 하나입니다. 라우팅 규칙은 이미 코어에 들어온 요청에만 적용됩니다. 분기 설정을 바꿔도 프록시를 사용하지 않는 터미널 연결이 자동으로 전달되지는 않으며, 시스템 프록시 설정을 대신하지도 않습니다. 화면의 전역 모드와 분기 옵션을 비교하려면 먼저 시스템 프록시와 라우팅 모드 안내를 읽고, 실제 생성된 규칙을 확인하세요.

05 이름 해석

DNS 설정

먼저 이름을 해석하는 주체 확인

최상위 dns 설정은 코어의 DNS 해석 기능을 구성하며, 시스템의 모든 DNS 요청을 대체하지 않습니다. 앱은 연결 전에 시스템 리졸버를 사용하거나 앱 자체에 설정된 DNS 서비스를 사용할 수 있습니다. 앱이 IP 주소만 SOCKS 인바운드로 전달하면 코어는 해당 대상의 도메인을 다시 해석할 필요가 없습니다. 반대로 앱이 도메인을 그대로 인바운드에 전달하면 라우팅이 주소 규칙을 판단할 때 내장 DNS를 사용할 수 있고, 아웃바운드도 연결을 위해 이름을 해석할 수 있습니다. 먼저 어느 단계에서 해석이 일어나는지 확인한 다음 수정할 계층을 결정하세요.

아래 조각은 로컬 시스템 리졸버를 코어 DNS 서버 옵션으로 지정하고, hosts를 통해 예약된 테스트 이름 두 개에 고정 매핑을 설정합니다. 기준 설정에 병합해도 관련 상황에서 코어가 조회하는 방식만 정의할 뿐, 기본적으로 로컬 DNS 포트를 수신하지는 않습니다. 테스트 주소는 문서용 예약 대역에 속합니다. 목적은 매핑 과정을 확인하는 것이지 실제 웹서비스를 제공하는 것이 아닙니다. 접속에 실패했다는 사실만으로 매핑 적용 여부를 판단할 수는 없습니다.

{
  "dns": {
    "hosts": {
      "test.example": "192.0.2.10",
      "control.example": "198.51.100.10"
    },
    "servers": ["localhost"]
  }
}

주소 라우팅으로 코어 DNS 해석 확인

위의 두 매핑을 실제로 구분하려면 직접 연결과 트래픽 폐기 아웃바운드를 유지하고, 라우팅을 아래 조각으로 바꾸세요. 도메인을 프록시에 전달할 수 있는 SOCKS 앱에서 요청을 보냅니다. 라우팅이 IP 조건을 확인할 때 대상 해석을 시도하므로 test.example은 트래픽 폐기 아웃바운드로 전달됩니다. control.example의 주소는 해당 규칙 범위에 포함되지 않으므로 기본 아웃바운드로 전달됩니다. 현재 인스턴스에서 사용할 수 있는 라우팅 또는 접속 로그로 경로를 확인하세요. 두 예약 주소 모두 페이지를 제공하지 않는다는 이유로 결과가 같다고 판단하면 안 됩니다.

{
  "routing": {
    "domainStrategy": "IPOnDemand",
    "rules": [
      {
        "type": "field",
        "ip": ["192.0.2.0/24"],
        "outboundTag": "blocked"
      }
    ]
  }
}

라우팅에 사용할 해석 결과와 실제 연결에 사용할 대상은 서로 다릅니다. 직접 연결 아웃바운드에서 내장 DNS가 제공한 주소를 명시적으로 사용하려면 해당 아웃바운드의 도메인 정책도 확인해야 합니다. 원격 프록시 아웃바운드에서는 로컬에서 해석하는 원격 노드 호스트 이름과 원격에서 처리하는 웹사이트 이름을 구분해야 합니다. 두 도메인이 같은 로그에 함께 표시될 수도 있습니다. routing.domainStrategy를 수정해도 원격에서 확인하는 대상 형식이 바뀐다고 보장할 수 없으며, 브라우저가 코어를 통해 이름을 조회하게 되는 것도 아닙니다.

서버 선택·주소 계열·캐시 문제를 따로 확인

dns.servers에는 간단한 서버 항목이나 도메인 매칭 조건이 있는 서버 객체를 넣을 수 있습니다. 도메인에 따라 특정 DNS 서비스를 우선 조회하도록 설정해도 시스템 전체가 해당 서버를 사용하도록 강제하는 것은 아닙니다. 대체 규칙과 사용 가능한 필드는 실행 중인 코어의 문서를 확인하세요. 실제 적용에서는 먼저 접근 가능한 서버 하나로 시작하고, 전용 리졸버를 사용해야 하는 도메인 하나와 일반 해석을 사용해야 하는 도메인 하나를 기록합니다. 도메인별 설정이 필요할 때 목록을 확장하고 주소, 도메인 매칭, 대체 동작을 한꺼번에 바꾸지 마세요.

일부 이름은 해석되지만 연결이 오래 걸리는 경우, 반환된 레코드의 주소 계열과 해당 주소까지 로컬에서 연결할 수 있는지를 따로 확인하세요. IPv6 레코드를 받았다고 해서 현재 네트워크에 사용 가능한 IPv6 경로가 있다는 뜻은 아닙니다. 반대로 IPv6 연결 한 번이 실패했다고 해당 주소 계열을 영구적으로 끌 필요도 없습니다. 통제된 비교 테스트를 먼저 진행해 어떤 주소 유형에서 실패가 발생하는지 확인한 뒤 조회 정책이나 네트워크 환경을 조정하세요. DNS 조회 실패와 해석 성공 후 연결 시간 초과는 서로 다른 문제이며, 로그의 발생 시각으로 구분할 수 있습니다.

매핑이나 리졸버를 바꿔도 브라우저, 시스템, 코어 캐시에 이전 결과가 남아 있을 수 있습니다. 한 계층을 재시작해도 다른 계층의 캐시까지 반드시 삭제되는 것은 아니며, 기존 연결은 새로 해석하지 않을 수 있습니다. 테스트할 때는 새 연결을 사용하고, 필요하다면 이전에 조회한 적 없는 직접 관리하는 테스트 이름을 사용하세요. 일반 앱과 SOCKS 앱의 결과가 다르면 두 앱의 DNS 설정을 즉시 통일하지 말고 그 차이를 근거로 남겨두세요.

06 연결 동작

policy 연결 정책

먼저 연결이 속한 레벨 확인

policy는 핸드셰이크 대기, 유휴 시간, 일부 통계 옵션 등 코어의 연결 정책을 설정합니다. 아웃바운드를 선택하거나 라우팅 규칙을 대신하지 않습니다. policy.levels는 객체이며 키는 사용자 레벨을 나타내는 문자열입니다. 예를 들어 "0"과 같습니다. 프로토콜이 연결에 특정 레벨을 지정할 때 필드 값은 일반적으로 숫자입니다. 사용자 지정 레벨이 levels에 이름으로 등록되어 있다고 해서 모든 연결에 적용되는 것은 아니므로, 사용하는 프로토콜이 연결의 레벨을 지정하는 방식도 확인해야 합니다.

기준 인바운드에서는 사용자 레벨을 명시적으로 높이지 않으므로 여기서는 레벨 0을 비교 대상으로 사용합니다. 아래는 대기 시간을 초 단위로 지정한 예제이며, 대기 구간을 바꿨을 때 어떤 차이가 생기는지 확인하는 용도입니다. 모든 네트워크에서 그대로 사용하라는 의미는 아닙니다. 기준 설정에 병합한 뒤 현재 연결이 해당 인바운드를 통과하는지 확인하고 정책을 검증하세요. 클라이언트가 다른 인바운드를 생성했거나 다른 프로토콜이 사용자에게 다른 레벨을 지정했다면 레벨 0을 수정해도 그 연결의 동작을 설명할 수 없습니다.

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 180,
        "uplinkOnly": 10,
        "downlinkOnly": 10
      }
    }
  }
}

핸드셰이크·유휴·단방향 종료를 구분

handshake는 해당 프록시 프로토콜의 핸드셰이크 단계에서 허용하는 대기 시간입니다. 웹페이지 접속 전체에 걸리는 시간이나 모든 하위 연결의 시간 초과를 제어하는 단일 옵션은 아닙니다. connIdle은 연결이 설정된 뒤 일정 시간 데이터가 전송되지 않은 상태를 다룹니다. 연결은 성립하지만 매번 비슷한 유휴 시간 후 끊기는 경우에 우선 확인할 항목입니다. 연결이 한 번도 성립하지 않는다면 먼저 수신, 원격 주소, 노드 협상, 네트워크 오류를 살펴보세요.

uplinkOnly와 downlinkOnly는 연결이 단방향 종료 단계로 넘어갔을 때 남은 방향의 대기 시간을 관리합니다. 업로드나 다운로드 속도를 제한하는 옵션이 아닙니다. 예를 들어 앱이 전송을 끝냈지만 서버의 마지막 응답 데이터를 기다리는 동안에는 하향 전송만 남을 수 있습니다. 이 단계의 대기 시간을 너무 짧게 설정하면 늦게 도착한 응답을 받기 전에 연결이 끝날 수 있습니다. 파일 업로드 후 결과가 늦게 반환되는 문제를 살펴볼 때는 처리 서버의 실제 지연, 중간 장비의 연결 종료, 코어의 조기 종료를 구분해야 합니다.

필드확인할 단계설명하기 어려운 현상
handshake관련 프로토콜이 세션을 설정하는 단계핸드셰이크 성공 후 오랫동안 전송 속도가 느린 현상
connIdle연결 설정 후 데이터가 전송되지 않는 시간앱이 로컬 포트에 한 번도 연결하지 못한 현상
uplinkOnly、downlinkOnly남은 단방향 전송 단계더 앞에 있는 라우팅 규칙에 도메인이 매칭된 현상

시간 초과와 통계의 적용 범위 확인

시간 초과를 테스트할 때는 안정적으로 연결되는 것으로 확인된 연결 하나를 선택하고 시작 시각, 마지막으로 데이터가 전송된 시각, 종료 시각을 기록하세요. 매번 필드 하나만 바꾸고 새 연결을 만드세요. 앱의 요청 제한, 시스템 및 중간 장비의 유휴 제한, 서버 자체의 대기 정책이 코어보다 먼저 만료될 수 있습니다. 코어 값을 바꿔도 연결이 항상 앱의 제한 시간에 맞춰 끊긴다면 앱이나 원격 서버를 확인해야 합니다. 서로 관련 없는 정책 필드를 계속 늘리지 마세요.

통계도 계층별로 확인해야 합니다. 레벨별 사용자의 업로드·다운로드 통계와 시스템에서 인바운드나 아웃바운드별로 집계하는 통계는 기준이 다릅니다. 해당 기능이 활성화되어 있고 현재 프로토콜과 연결에서 필요한 통계 항목을 제공해야 읽을 데이터가 생깁니다. 정책 옵션을 켠다고 클라이언트 화면에 숫자가 바로 표시되는 것은 아니며 트래픽 할당량이 설정되는 것도 아닙니다. 코어를 처음 실행해 점검할 때 규칙 일치 여부를 판단하려고 통계 인터페이스를 먼저 연결할 필요는 없습니다. 인바운드 하나와 대상 하나의 접속 결과를 확인하는 편이 더 직접적입니다.

오류를 없애려고 시간 초과를 무조건 크게 설정하지 마세요. 대기 시간을 늘리면 오류 표시가 늦어질 뿐, 완료될 수 없는 연결이 리소스를 계속 점유할 수 있습니다. 먼저 제한이 어느 계층에서 발생하는지 확인한 다음, 해당 단계에 적용되는 설정만 바꾸세요.

진단을 위해 대기 시간을 일시적으로 늘렸다면 원인을 확인한 뒤 원래 설정으로 되돌리거나 근거가 있는 변경만 남기세요. 대상, 코어, 인바운드 태그, 연결 레벨, 발생 시각을 기록해두면 다음에 같은 오류가 발생했을 때 비교할 수 있습니다. 이런 정보가 없으면 ‘시간 초과’가 표시된 화면만으로 프록시 핸드셰이크가 끝나지 않은 것인지, 이미 성립한 연결이 데이터를 기다리는 중인지 판단하기 어렵습니다.

07 설정 편집 범위

클라이언트 설정과 네이티브 JSON

UI 입력·생성 결과·실행 파일 구분

평소에는 클라이언트 UI에서 프록시를 설정하는 것이 좋습니다. 데스크톱에서는 v2rayN을 우선 권장하며, Android에서는 코어 요구사항에 따라 v2rayNG 또는 v2flyNG를 선택할 수 있습니다. 클라이언트 다운로드 페이지에서 운영체제와 아키텍처에 맞는 항목을 확인하세요. 이 가이드는 코어가 읽는 설정만 설명합니다. 클라이언트에는 노드, 구독, 분기 방식, 프로그램 상태를 저장할 수 있지만, 이 정보가 네이티브 코어 설정 파일 형식으로 저장되는 것은 아닙니다. 확장자가 JSON인 파일이라고 해서 코어에 바로 전달해 실행할 수 있는 것은 아닙니다.

구독 업데이트는 노드 항목에 영향을 주고, 그래픽 설정은 다음 실행 설정 생성에 영향을 줍니다. 코어에서 실제 적용되는 것은 현재 인스턴스가 불러온 파일입니다. 클라이언트가 임시로 생성한 파일을 직접 수정하면 노드 전환, 코어 재시작, 설정 재적용 후 덮어써질 수 있습니다. 변경을 계속 유지하려면 클라이언트에 해당 설정이 있는지 먼저 확인하세요. 네이티브 파일이 꼭 필요하다면 사용자 지정 설정을 지원하는 모드에서 별도 사본을 저장하고, 클라이언트가 관리하는 변경과 직접 추적할 변경을 구분하세요.

플랫폼클라이언트먼저 확인할 실행 조건
Windowsv2rayN앱이 사용하는 시스템 프록시와 코어 수신 주소를 각각 확인합니다.
macOSv2rayN시스템 프록시 설정, 앱 자체 네트워크 옵션, 실제로 실행된 코어를 구분합니다.
Androidv2rayNG、v2flyNG시스템 VPN의 트래픽 처리 상태, 포함된 앱, 코어 라우팅 결과를 구분합니다.
Linuxv2rayN데스크톱 네트워크 설정과 터미널 프로세스가 상속한 프록시 매개변수를 구분합니다.

코어를 바꿀 때는 전체 파일을 그대로 복사하지 말고 유효한 필드를 비교

Xray와 V2Fly는 공통 설정 개념을 갖지만, 특정 프로토콜, 전송 방식, 보안 옵션, 전용 필드가 모두 호환되는 것은 아닙니다. 설정을 옮길 때는 로컬 인바운드와 직접 연결 아웃바운드만 남기고 최소 파일이 실행되는지 확인한 다음, 기존 파일의 규칙과 DNS 설정, 원격 아웃바운드를 단계적으로 추가하세요. 오류가 알 수 없는 필드, 유효하지 않은 필드 값, 리소스 파일 누락 중 무엇을 가리키는지 살펴보세요. 한 클라이언트에서 동작하는 설정이 다른 클라이언트나 코어에서도 그대로 실행된다는 보장은 없습니다.

아래 최상위 조각에는 로컬 루프백 HTTP 인바운드 하나와 직접 연결 아웃바운드 하나만 포함되어 있습니다. 두 기본 객체를 코어 간 비교 진단할 때 사용할 수 있습니다. 첫 장의 SOCKS 기준 설정과는 별개의 인바운드 방식이므로 앱에서 HTTP 프록시와 이 예제의 포트를 명시해야 합니다. 두 코어를 비교하려면 같은 파일을 각 코어에서 차례로 실행하고 기존 프로세스가 종료되었는지 확인하세요. 두 설정을 동시에 실행해 같은 포트를 사용하면 호환성 결과가 아니라 수신 충돌이 발생합니다.

{
  "inbounds": [
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    { "tag": "direct", "protocol": "freedom", "settings": {} }
  ]
}

네이티브 파일은 실행되고 명시적인 프록시 테스트도 성공하는데 클라이언트가 실행한 인스턴스에서 동작이 다르다면, 노드 이름만 확인하지 말고 실행 파일의 아웃바운드 순서, 인바운드 포트, 라우팅 태그, DNS 정책을 비교하세요. 시스템 프록시나 가상 네트워크 모드를 켠 뒤에만 차이가 발생한다면 트래픽을 가져오는 방식도 확인해야 합니다. 트래픽 전달은 클라이언트와 시스템 사이의 문제입니다. 네이티브 JSON에 아웃바운드를 작성해도 앱에서 원래 사용하지 않던 프록시 경로가 자동으로 활성화되지는 않습니다.

공유 설정 조각에는 재현에 필요한 데이터만 남기기

다른 사람에게 문제 해결을 요청할 때는 먼저 임시 설정 사본을 만들고 구독 주소, 원격 인증 정보, 실제 노드 주소, 개인 디렉터리, 사용자를 식별할 수 있는 접속 기록을 삭제하세요. 필요한 키와 값의 유형, 배열 순서, 태그 간 참조 관계는 보존해야 합니다. 한쪽 태그만 바꾸면 원래 없던 오류가 생길 수 있습니다. 원격 연결이 필요한 증상이라면 실패한 단계와 관련 오류를 설명하고 실행 파일 전체를 올리지 마세요. 첫 실행과 노드 가져오기 화면 조작은 v2rayN 초기 설정을 참고하세요.

설정을 계속 유지할 변경을 적용하기 전에 어떤 요청의 동작을 바꾸려는지, 취소하려면 어떻게 해야 하는지 먼저 기록하세요. 예를 들어 분기 변경은 기존 규칙 순서로 되돌리고, 시스템 프록시는 앱 또는 시스템 설정에서 복구해야 합니다. 두 변경의 기록은 각각 남기는 편이 좋습니다. 클라이언트를 종료한 뒤에도 프록시 설정이 로컬의 이전 포트를 가리키면 코어 설정과 관계없는 접속 실패가 발생할 수 있습니다. 이때는 먼저 이전 트래픽 전달 방식을 복구한 다음 파일 차이를 비교하세요.

08 검증과 복구

단계별 검증과 복구

먼저 설정이 읽히는지 확인하고 요청이 코어에 들어오는지 확인

문제 해결을 시작하기 전에 현재 클라이언트, 실제 코어, 수신 주소, 포트, 기본 아웃바운드, 테스트 대상을 기록하세요. 동작하는 설정을 복사해 보관한 뒤 후보 파일을 편집합니다. 코어가 실행을 거부하면 필드를 명확히 가리키는 가장 이른 오류를 먼저 확인하세요. 형식 오류, 유형 불일치, 미지원 프로토콜, 규칙 데이터 누락, 포트 점유는 서로 다른 문제입니다. 뒤에 나온 오류는 첫 번째 문제의 결과일 수 있으므로 가장 먼저 발생한 원인을 해결하고 시작 로그를 다시 확인하세요. 여러 모듈을 한꺼번에 바꾸지 마세요.

실행 후에는 프록시를 명시적으로 설정한 프로그램에서 짧은 요청을 먼저 보내세요. 아래 명령은 기준 설정 파일을 사용하고 curl이 설치되어 있으며 예시 사이트에 직접 접속할 수 있는 환경을 위한 것입니다. 같은 환경에서 이 프록시를 거치지 않은 요청과 결과를 비교하세요. 두 SOCKS 매개변수의 주요 차이는 대상 도메인을 어느 쪽에서 처리하는지이며, 라우팅과 DNS를 비교할 때 특히 유용합니다. 다른 수신 포트를 사용한다면 대상을 바꾸는 동시에 프록시 주소도 바꾸지 말고 두 명령에서 같은 포트를 사용하세요.

curl --socks5 127.0.0.1:10808 --max-time 12 https://example.org/
curl --socks5-hostname 127.0.0.1:10808 --max-time 12 https://example.org/

명령에서 로컬 포트에 연결할 수 없다고 나오면 코어 실행 여부와 바인딩 주소가 일치하는지 먼저 확인하세요. 로컬 포트 연결은 되지만 프록시 프로토콜 통신에 실패한다면 앱에서 선택한 프록시 유형을 다시 확인합니다. 명시적 프록시 테스트는 성공하지만 브라우저나 터미널의 평소 작업이 실패한다면 앱의 트래픽 전달 설정을 살펴보세요. 브라우저 확장, 시스템 프록시, 터미널 환경 변수는 각각 적용 범위가 다를 수 있습니다. 시스템 프록시 문제 해결을 참고해 브라우저와 터미널을 별도로 확인하세요.

짧은 로그로 특정 요청의 흐름 추적

요청이 코어에 도달했는데 경로를 알 수 없다면 잠시 로그 상세도를 높여 확인하세요. 아래 조각은 기준 설정 사본의 최상위 log 객체 전체를 대체하며, 짧게 관찰하는 용도입니다. 로그를 저장할 경로는 지정하지 않습니다. 클라이언트가 코어 출력을 받아 표시하는 방식은 실행 환경에 따라 다르며, 로그 레벨을 높여도 화면에서 모든 규칙의 전체 판단 과정이 표시되는 것은 아닙니다. 요청 시각과 대상, 인바운드부터 아웃바운드까지의 기록, 오류 발생 단계를 연결해 전체 흐름을 확인하세요.

{
  "log": {
    "loglevel": "info"
  }
}

대상을 명확하게 기록하고 한 번만 재현하세요. 대상이 IP 주소로 표시된다면 먼저 도메인 매칭 표현식을 수정하지 마세요. 기본 아웃바운드로 들어간 로그가 보인다면 일치하는 규칙이 있었는지, 태그가 존재하는지, 첫 번째 아웃바운드가 예상한 항목인지 확인하세요. 아웃바운드는 맞는데 연결이 실패한다면 DNS 또는 연결 과정을 점검합니다. 도메인 해석 오류, 연결 거부, 연결 시간 초과는 서로 다른 문제입니다. 각각 주소 확인, 대상의 수신 상태, 대기 단계와 관련되므로 다음에 확인할 모듈도 다릅니다.

새 설정과 이전 설정을 테스트할 때는 대상, 앱, 인바운드 프로토콜, 네트워크, 선택한 노드를 그대로 두고 테스트할 파일만 바꾸세요. 매 테스트마다 연결을 새로 만들어 브라우저 연결 풀과 클라이언트의 이전 세션이 결과에 섞이지 않도록 합니다. 장시간 유휴 상태 후에만 문제가 생긴다면 비교 테스트도 같은 시간 동안 기다리세요. 특정 이름에서만 문제가 생긴다면 정상 작동이 확인된 이름 하나를 비교 대상으로 유지하세요. 재현이 안정적이지 않을 때는 목적 없이 클라이언트를 다시 설치하는 것보다 발생 조건을 기록하는 편이 문제 해결에 도움이 됩니다.

설정 복구와 트래픽 전달 복구를 각각 수행

후보 파일이 실행 또는 기본 연결 테스트에 실패하면 후보 인스턴스를 중지하고 이전 설정 사본과 앱에서 지정한 로컬 포트를 복구한 뒤, 정상 작동이 확인된 대상을 테스트하세요. 검증 중 시스템 프록시나 가상 네트워크 모드를 임시로 켰다면 원래 상태로 돌려야 합니다. 이는 JSON 파일 교체와 별개의 작업입니다. 앱이 원래 경로로 돌아왔는지 확인한 다음 일반 로그 레벨을 복구하고 테스트용 추가 수신, 고정 호스트 매핑, 전용 규칙을 제거하세요.

마지막으로 세 가지 결과를 남기세요. 앱의 요청이 지정한 인바운드로 들어왔는지, 라우팅이 예상한 아웃바운드를 선택했는지, 아웃바운드가 대상에 성공적으로 접속했는지 기록합니다. 각 항목에는 관찰 가능한 사실만 적으세요. 기록을 공유하기 전에 공개할 필요가 없는 대상 세부 정보를 삭제합니다.

복구 후에도 실패한다면 후보 파일에 계속 변경을 덧붙이지 마세요. 기준 설정으로 다시 테스트해 로컬 포트, 트래픽 전달 상태, 네트워크 환경이 실제로 원래대로 돌아왔는지 확인한 뒤, 새 프로세스가 포트를 점유하거나 이전 파일을 사용 중인지 살펴보세요. 일상적인 사용을 먼저 복구하려면 시작 가이드로 돌아가 가져오기, 모드 선택, 연결 확인을 차례로 진행하세요. 기본 경로가 복구되면 이 가이드의 해당 장에서 필드 하나씩 확인하면 됩니다.