설정 파일 레퍼런스

V2Ray JSON 설정 가이드

설치와 가져오기, 첫 연결을 아직 완료하지 않았다면 빠른 시작 가이드를 먼저 읽고 그래픽 인터페이스를 따라 설정해 보세요. 특정 옵션이 어떤 필드를 생성하는지 확인하거나 연결이 어느 단계에서 실패했는지 찾아야 할 때 이 핸드북을 참고하면 됩니다. 여기서는 로컬 리스너, 직접 연결, 차단을 예로 들어 클라이언트가 코어에 전달하는 설정을 단계별로 설명합니다.

JSON 구조: 인바운드부터 아웃바운드까지

설정의 최상위 요소는 객체입니다. 코어가 시작할 때 읽는 연결 안내서라고 생각하면 됩니다. 클라이언트 인터페이스의 항목을 그대로 복사한 파일은 아닙니다. inbounds와 outbounds는 배열이므로 하나의 프로세스에 여러 인바운드와 아웃바운드를 등록할 수 있습니다. routing, dns, policy는 각각 다른 역할을 맡는 객체입니다. 클라이언트에 저장된 구독 이름, 인터페이스 설정, 이전 속도 측정 결과는 이 안내서에 포함되지 않습니다. 설정을 내보내기 전에 내보내려는 것이 클라이언트 설정인지, 단일 노드인지, 아니면 특정 실행에서 코어에 전달한 전체 파일인지 확인하세요.

전체 기본 설정과 부분 예제의 차이

아래는 로컬에서 실행할 수 있는 전체 기본 설정입니다. 앱은 SOCKS 요청을 루프백 주소로 보내고, 코어는 freedom 아웃바운드를 통해 목적지에 직접 연결합니다. 원격 노드 설정이 아니므로 서버 주소나 계정 정보가 필요하지 않습니다. 클라이언트에서 지원하는 사용자 지정 설정 메뉴를 통해 복사본을 불러오세요. 같은 포트를 사용 중인 프로세스가 있으면 해당 프로세스를 종료하거나 복사본에서 사용 가능한 포트로 바꾸고, 테스트 앱의 프록시 주소도 함께 수정하세요. 이후 장의 코드는 대부분 일부 필드만 보여 주므로 이 파일 끝에 차례로 붙여 넣으면 안 됩니다.

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

세 가지를 비교해 보세요. 첫째, port는 숫자이고 udp는 불리언이므로 보기 좋게 맞춘다고 둘 다 따옴표로 감싸면 안 됩니다. 둘째, 인바운드와 아웃바운드 모두 protocol과 settings를 사용하지만, 설정을 해석하는 방식은 각 프로토콜에 따라 다릅니다. SOCKS 인바운드의 인증 필드를 직접 연결 아웃바운드에 옮겨 쓸 수는 없습니다. 셋째, tag는 파일 안에서 사용하는 식별자입니다. 이름은 직접 정할 수 있지만 이후 참조할 때 철자가 정확히 일치해야 합니다. direct를 다른 이름으로 바꿔도 직접 연결 동작 자체는 달라지지 않지만, 이전 이름을 참조하는 규칙은 작동하지 않을 수 있습니다.

읽는 순서와 필드 배치 순서는 다릅니다

문제를 해결할 때는 먼저 연결 흐름을 따라가세요. 앱이 요청을 인바운드로 전달하면 코어가 목적지 정보를 확인하고 규칙에 따라 아웃바운드를 선택합니다. 아웃바운드는 자체 프로토콜과 이름 해석 정책에 따라 다음 연결을 설정합니다. DNS가 모든 연결의 한가운데 정해진 단계로 들어가는 것은 아닙니다. 요청에 처음부터 숫자 주소가 들어 있으면 코어가 DNS 조회를 하지 않을 수 있습니다. 앱이 로컬에서 먼저 이름을 해석한 뒤 SOCKS로 전달하면 코어는 원래 도메인을 보지 못할 수도 있습니다. 연결 정책은 특정 단계의 대기 시간과 통계 동작을 제어할 뿐, 경로를 선택하지는 않습니다.

일반적으로 최상위 객체의 필드 순서는 의미에 영향을 주지 않습니다. 예를 들어 로그 블록을 파일 끝으로 옮겨도 로그가 적용되는 연결 범위는 바뀌지 않습니다. 반면 배열의 순서는 결과를 좌우할 수 있습니다. 라우팅 규칙은 위에서부터 검사하고, 기본 아웃바운드는 아웃바운드 배열의 첫 항목을 사용합니다. 설정을 병합할 때 객체와 배열을 구분해 처리하세요. 최상위 요소에 이미 outbounds가 있다면 기존 배열을 수정하고 같은 이름의 키를 추가하지 마세요. 많은 파서는 중복 키를 오류 없이 읽고 뒤에 있는 값을 남기므로, 실행 후 기존 아웃바운드가 사라질 수 있습니다.

클라이언트와 코어 중 수정할 위치 찾기

데스크톱 클라이언트로는 v2rayN을 권장합니다. 운영체제와 프로세서 아키텍처에 맞는 패키지는 클라이언트 다운로드 페이지에서 선택하세요. Android에서는 필요한 코어에 따라 v2rayNG 또는 v2flyNG를 사용하면 됩니다. 그래픽 클라이언트는 노드 전환, 서비스 재시작, 구독 업데이트 때 기본 템플릿으로 파일을 다시 생성할 수 있습니다. 임시 파일을 직접 편집해 일시적으로 적용되더라도 변경 사항이 저장되었다는 뜻은 아닙니다. 현재 그래픽 설정을 쓰는지 사용자 지정 설정을 쓰는지 확인하고, 해당 메뉴에서 저장한 다음 다시 열거나 내보내 변경 사항을 확인하세요.

수정 전에 원래 상태로 복원할 수 있는 복사본을 만들고 클라이언트가 사용하는 코어를 기록하세요. 같은 이름의 필드라도 코어와 설정 형식에 따라 사용할 수 있는 옵션이 다를 수 있습니다. 가져온 조각이 텍스트 편집기에서 열린다고 해서 현재 코어가 지원한다는 뜻은 아닙니다. 엄격한 JSON에서는 큰따옴표를 사용하며 주석, 끝에 붙는 쉼표, 작은따옴표에 의존하지 마세요. 먼저 문법을 확인하고 필드 형식과 로컬 리스너를 점검한 뒤 실제 요청을 테스트하세요. 이렇게 하면 파일을 읽지 못하는 문제, 서비스가 시작되지 않는 문제, 연결 동작이 예상과 다른 문제를 구분할 수 있습니다.

inbounds: 리스너 주소·포트·프로토콜

인바운드는 코어가 연결을 받는 방법을 설명하며, 원격 서버의 위치를 나타내지 않습니다. 인바운드가 정상 작동하는지 확인하려면 리스너 주소, 포트, 프로토콜이 모두 맞아야 합니다. 클라이언트에 ‘연결됨’이라고 표시되어도 앱의 설정까지 자동으로 맞춰 주지는 않습니다. 앱이 이전 프록시 포트를 계속 사용하거나 HTTP 프록시 주소에 SOCKS 핸드셰이크를 보낼 수 있습니다. 이런 상황을 구분하려면 먼저 운영체제에서 해당 포트로 연결할 수 있는지 확인하고, 그다음 코어가 예상한 프록시 요청을 받았는지 살펴보세요.

SOCKS와 HTTP 인바운드 각각 설정하기

아래 코드는 기본 설정의 inbounds 배열을 대체할 수 있습니다. 두 가지 프록시에 서로 다른 포트를 할당해 앱이 실제로 어느 인바운드를 사용하는지 확인하기 쉽게 했습니다. local-socks는 SOCKS를 지원하는 앱에, local-http는 HTTP 프록시를 지원하는 앱에 사용하세요. 두 인바운드가 같은 아웃바운드를 사용해도 되고, 인바운드 태그를 이용해 라우팅에서 다르게 처리해도 됩니다. 포트 번호 자체에는 프로토콜 의미가 없습니다. 핸드셰이크 형식은 protocol이 결정합니다.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false,
        "userLevel": 0
      }
    },
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {
        "userLevel": 0
      }
    }
  ]
}
필드기능확인할 항목
listen리스너가 바인딩되는 로컬 주소를 제한합니다.프록시 주소의 호스트 부분입니다.
port인바운드 포트를 지정합니다.앱의 프록시 포트 및 포트 사용 여부.
protocol인바운드가 허용하는 프록시 핸드셰이크 종류를 결정합니다.앱에서 선택한 프록시 유형.
tag라우팅 규칙에 트래픽 출처를 표시합니다.규칙의 inboundTag.

루프백 주소, 접근 범위, 주소 계열

127.0.0.1은 이 컴퓨터의 IPv4 루프백 주소입니다. 예제에는 계정 인증이 없지만 리스너를 로컬로 제한해 다른 기기가 인바운드에 직접 접근하지 못하게 했습니다. 같은 컴퓨터의 브라우저를 연결하려고 모든 네트워크 인터페이스에서 수신하도록 바꾸지 마세요. 접근 범위만 넓어질 뿐 프록시 유형이 잘못 설정된 문제는 해결되지 않습니다. 앱이 가상 머신이나 별도의 네트워크 네임스페이스에서 실행되면 앱에서 보이는 루프백 주소는 자체 환경을 가리킬 수 있습니다. 호스트 컴퓨터의 프록시 주소를 그대로 사용하면 안 됩니다.

로컬 앱에서 localhost를 지정하면 시스템이 IPv6 루프백 주소를 먼저 시도할 수 있습니다. 예제는 IPv4에만 바인딩되어 있으므로 일부 앱은 IPv4로 전환하지 못해 로컬 연결도 실패할 수 있습니다. 문제를 확인할 때는 먼저 127.0.0.1을 직접 지정해 이름 해석과 주소 계열 선택 문제를 배제한 뒤, 다른 주소 계열의 리스너가 정말 필요한지 판단하세요. 시작 단계에서 포트가 사용 중이라는 로그가 나오면 어떤 프로세스가 포트를 점유했는지 먼저 확인하세요. 일반적인 해결책으로 리스너 주소를 바꾸는 것은 적절하지 않습니다. 클라이언트가 시작한 이전 프로세스가 다른 앱의 연결을 처리하고 있을 수도 있습니다.

UDP 지원과 도메인 식별은 별개의 문제입니다

SOCKS 인바운드에서 UDP를 허용해도 모든 UDP 데이터그램이 코어로 전달되는 것은 아닙니다. 앱이 SOCKS UDP 릴레이를 지원해야 하고 아웃바운드도 해당 트래픽을 처리할 수 있어야 합니다. 일반 HTTP 프록시가 시스템의 UDP 트래픽까지 대신 처리해 주지는 않습니다. 연결을 확인할 때는 먼저 TCP를 테스트하세요. 어떤 앱에서 어떤 프로토콜에 UDP가 필요한지 분명한 경우에만 통제된 환경에서 별도로 검증하세요. 웹 페이지가 열린다는 사실만으로 실시간 통화, 게임, 일반 DNS 요청도 같은 경로를 사용한다고 판단할 수는 없습니다.

일부 인바운드는 다음 연결을 설정하기 전에 트래픽에서 목적지 정보를 식별할 수 있습니다. 이런 설정에는 흔히 sniffing이 사용됩니다. 앱이 직접 제공하지 않은 도메인을 알아내는 데 도움이 될 수 있지만, 모든 숫자 주소를 특정 웹사이트로 복원할 수 있는 것은 아닙니다. 식별할 수 있는지는 트래픽 자체에 달려 있고, 식별한 이름으로 목적지를 바꿀지는 별도의 설정입니다. 디버깅할 때는 애초에 도메인을 프록시에 전달하는 앱으로 일반 도메인 규칙부터 확인하세요. 여러 옵션을 한꺼번에 켜고 무엇이 작동했는지 추측하지 말고, 식별 기능이 필요한지 그다음 판단하세요.

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

아웃바운드는 코어가 요청을 받은 뒤 어떻게 처리할지를 설명합니다. 가장 쉽게 비교할 수 있는 아웃바운드는 freedom과 blackhole입니다. 전자는 코어가 실행되는 컴퓨터에서 목적지에 직접 연결하고, 후자는 전달된 트래픽을 종료합니다. 아웃바운드 이름을 direct나 blocked로 지정해도 기능이 생기는 것은 아닙니다. 실제 동작은 protocol이 결정합니다. 결과가 뚜렷이 다른 두 아웃바운드로 라우팅부터 확인한 뒤 원격 서버가 필요한 연결을 추가하면 라우팅 오류와 노드 핸드셰이크 오류를 구분하기 쉽습니다.

두 아웃바운드로 결과 비교하기

{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "AsIs"
      }
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {
        "response": {
          "type": "none"
        }
      }
    }
  ]
}

이 코드는 기본 설정의 outbounds 배열을 대체할 수 있습니다. 직접 연결이 첫 번째 항목이므로 어떤 규칙에도 일치하지 않는 연결은 직접 연결됩니다. 차단 아웃바운드가 배열에 있어도 도메인 트래픽을 자동으로 처리하지 않습니다. 규칙이 요청을 해당 아웃바운드로 보내거나 기본 아웃바운드로 지정해야 합니다. response.type이 none이면 프로토콜 응답을 생성하지 않습니다. 앱에는 차단 이유를 설명하는 페이지 대신 연결 종료, 로딩 실패, 재시도로 표시될 수 있습니다. 실패했다는 사실만으로 차단 규칙이 작동했다고 단정하지 말고 로그에서 실제 선택된 아웃바운드를 확인하세요.

첫 번째 항목이 기본 아웃바운드이므로 목록 순서를 바꾸면 규칙에 명시되지 않은 여러 서비스의 연결도 달라질 수 있습니다. 테스트 중에는 기본 아웃바운드를 명확히 정하고, 규칙을 추가할 때는 테스트 대상 하나만 지정하세요. 차단을 기본값으로 바꾼다면 허용할 대상도 별도로 관리해야 합니다. 배열의 두 번째 항목이 첫 번째 항목의 실패를 자동으로 처리한다고 생각하면 안 됩니다. 백업 노드와 장애 조치에는 명시적인 선택 방식이 필요합니다. 일반 아웃바운드 배열만으로 재시도 순서가 정해지지는 않습니다.

프로토콜 설정과 전송 설정 구분하기

원격 서버로 연결하는 아웃바운드에는 보통 settings와 streamSettings가 있습니다. 전자는 프록시 프로토콜이 정의하는 매개변수를 담고, 후자는 일반적으로 서버에 연결하는 데 사용할 전송 방식과 보안 계층을 설명합니다. 서버 주소, 포트, 프로토콜, 인증 정보는 서버 설정과 일치해야 합니다. 전송 유형, 경로, 호스트 이름, 보안 계층 요구 사항도 하나의 묶음으로 확인하세요. 프로토콜 이름만 같다고 설정이 호환되는 것은 아닙니다. 같은 도메인에 여러 서비스를 운영할 수 있고, 인증서의 이름이 실제 접속 주소와 다를 수도 있습니다.

구독을 가져온 뒤에는 구독 가져오기 가이드를 참고해 클라이언트가 인식한 프로토콜과 전송 설정을 먼저 확인하세요. 여러 노드에서 익숙해 보이는 필드를 섞어 쓰지 마세요. 현재 코어가 특정 옵션을 지원하는지 확인하려면 Xray와 V2Fly 코어의 차이를 참고할 수 있습니다. 그래픽 인터페이스에서 코어를 바꾼 뒤에는 실제 연결을 다시 시작하고 시작 정보를 확인하세요. 드롭다운의 이름만 바꿨다고 프로세스가 전환된 것은 아닙니다.

목적지 주소와 서버 주소 구분하기

앱이 요청하는 목적지는 앱이 접속하려는 서비스입니다. 원격 아웃바운드의 서버 주소는 코어가 먼저 연결해야 하는 별도의 주소입니다. 둘 다 도메인으로 표시될 수 있지만 한 번의 DNS 조회를 공유하는 것은 아닙니다. 직접 연결 아웃바운드에서 AsIs는 연결 단계에서 처리할 수 있도록 주소 형식을 유지한다는 뜻이지, 내장 DNS가 모든 목적지를 해석해야 한다는 뜻은 아닙니다. 원격 아웃바운드를 사용할 때는 이 컴퓨터에서 서버에 연결할 수 있는지와 원격 서버에서 최종 목적지에 접근할 수 있는지를 각각 확인하세요. 웹사이트가 열리지 않는다고 서버 주소가 틀렸다고 단정할 수 없으며, 아웃바운드 선택 로그만으로 목적지에서 데이터가 돌아왔다고 볼 수도 없습니다.

시간 초과가 발생하면 ‘선택된 아웃바운드, 아웃바운드가 연결하는 대상, 연결이 멈춘 단계’를 기록하세요. 기본 직접 연결도 실패한다면 로컬 네트워크와 목적지 서비스를 먼저 확인하세요. 특정 원격 아웃바운드만 실패한다면 전송 설정과 핸드셰이크를 살펴보세요. v2rayN 노드 시간 초과 점검 순서를 참고할 때도 같은 목적지를 반복 테스트하세요. 매번 목적지, 코어, 노드를 동시에 바꾸면 어떤 항목이 차이를 만들었는지 알 수 없습니다.

routing: 일치 순서와 목적지 정보

라우팅 규칙은 ‘이 요청을 정의된 아웃바운드 중 어디로 보낼지’를 정합니다. 요청의 프록시 프로토콜을 바꾸는 기능은 아닙니다. 규칙은 순서대로 확인하며 조건에 먼저 맞는 규칙이 선택됩니다. 뒤에 있는 같은 유형의 규칙은 추가로 검사하지 않습니다. 정확한 예외 규칙을 더 넓은 범위의 규칙보다 앞에 두세요. 모든 요청에 맞는 규칙을 맨 위에 두면 도메인 목록이 아무리 상세해도 적용되지 않습니다. 설계 단계에서 기본 아웃바운드도 정해야 합니다. 어떤 규칙에도 일치하지 않으면 결과가 없는 것이 아니라 아웃바운드 배열의 첫 항목으로 돌아갑니다.

독립적으로 검증할 수 있는 규칙 작성하기

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

direct와 blocked가 정의되어 있고 local-socks 인바운드가 있는 설정에 이 조각을 추가하세요. 첫 번째 규칙은 해당 인바운드에서 들어온 요청이면서 목적지 도메인이 example.org와 정확히 일치해야 합니다. 두 번째 규칙은 이 인바운드의 나머지 트래픽을 처리합니다. HTTP 인바운드가 추가로 있다면 출처 조건에 맞지 않으므로 기본 아웃바운드로 돌아갑니다. 두 규칙의 순서를 바꾸면 SOCKS 인바운드의 요청이 모두 두 번째 규칙의 넓은 조건에 먼저 걸려 정확한 규칙이 실행되지 않습니다.

한 규칙 안에서 서로 다른 조건 필드는 모두 충족해야 합니다. 반면 같은 필드의 여러 후보 값은 선택 가능한 일치 항목입니다. 예를 들어 network를 추가해 TCP로 제한하면 네트워크 유형 조건도 충족해야 한다는 뜻이지, ‘이 인바운드에서 들어오거나 TCP를 사용하는 요청’이라는 뜻이 아닙니다. 두 상황 중 하나만 맞아도 처리하려면 보통 같은 아웃바운드를 참조하는 규칙을 각각 작성합니다. 파일을 짧게 만들려고 서로 독립적인 두 규칙을 억지로 합치면 일치 범위가 합집합에서 교집합으로 바뀔 수 있습니다.

도메인 기준과 IP 주소 기준으로 일치시키기

full:은 정확한 도메인 일치이며 하위 도메인에는 적용되지 않습니다. 루트 도메인과 하위 도메인을 함께 처리하려면 일반적으로 domain:을 사용하고, 비슷하지만 일치하면 안 되는 경계 사례의 이름도 테스트하세요. 접두어나 부분 문자열만 지정하면 생각보다 넓은 범위에 일치할 수 있으므로 특정 도메인만 허용하는 용도로 적합하지 않습니다. 정규식도 꼭 필요한 경우에만 사용하고, 지나치게 넓은 패턴으로 비슷한 이름까지 포함하지 않도록 하세요. IP 규칙에는 숫자 주소나 네트워크 대역을 써야 하며 도메인으로 대신할 수 없습니다. 규칙에서 도메인 집합이나 IP 집합을 참조한다면 현재 코어가 해당 리소스를 찾을 수 있고 필요한 분류가 실제로 포함되어 있는지 확인하세요.

routing.domainStrategy는 라우팅 일치 과정에서 도메인을 주소로 추가 해석할지 결정합니다. AsIs는 이미 확보한 목적지 정보만 사용하므로 IP 규칙을 위해 도메인을 직접 조회하지 않습니다. IPIfNonMatch는 기존 규칙에 일치하지 않을 때 주소를 추가로 조회할 수 있습니다. 따라서 먼저 일치한 넓은 도메인 규칙 때문에 IP 규칙이 검사되지 않을 수도 있습니다. IPOnDemand는 IP 조건을 확인하는 시점에 조회를 시작할 수 있습니다. 이 정책을 성능 설정처럼 고르지 마세요. 도메인으로 분류하려는지, 해석된 주소를 기준으로 분류해야 하는지 먼저 결정하세요.

일치하는 경우보다 일치하지 않아야 할 경우를 테스트하세요

순서를 바꾼 뒤에는 차단되어야 할 호스트, 직접 연결되어야 할 무관한 호스트, 규칙에 쓰인 이름과 비슷하지만 제외되어야 할 하위 도메인을 각각 다시 테스트하세요. 앱이 도메인을 먼저 IP로 해석한 뒤 그 IP를 프록시에 전달한다면 추가 식별 정보가 없는 한 정확한 도메인 규칙은 일치하지 않습니다. 브라우저가 기존 연결을 재사용하거나 페이지 스크립트가 여러 호스트에 요청을 보낼 수 있다는 점도 고려하세요. 페이지 전체의 로딩 결과보다 개별 요청 하나를 기준으로 삼는 편이 해석하기 쉽습니다.

아웃바운드가 예상대로 선택되었는데도 실패한다면 라우팅 규칙은 그대로 두고 아웃바운드, DNS, 목적지 서비스를 점검하세요. 아웃바운드 태그를 잘못 입력했다면 정의와 규칙을 확인하세요. 오타에 맞추려고 배열에 같은 아웃바운드를 하나 더 만들지 마세요. 장기간 관리할 설정이라면 맨 위에 정확한 예외 몇 개를 두고, 그 아래에 역할별 규칙을 그룹화한 뒤 기본 경로를 명시하세요. 변경할 때마다 영향을 받아야 하는 대상과 영향을 받지 않아야 하는 대상을 분명히 정하세요.

V2Ray DNS 설정: 누가 어디서 이름을 해석하나요?

도메인 이름 해석에 실패하면 가장 먼저 누가 조회를 시작했는지 확인하세요. 브라우저나 운영체제가 프록시 연결 전에 해석할 수도 있고, 코어가 라우팅 일치나 아웃바운드 연결을 위해 내장 리졸버를 사용할 수도 있습니다. 마지막 조회를 원격 서버가 맡는 경우도 있습니다. 설정의 dns 객체는 코어 자체의 DNS 설정을 설명합니다. 운영체제의 DNS를 자동으로 대체하거나 모든 앱이 자체 이름 해석을 중단하도록 강제하지 않습니다. 여기만 수정했는데 클라이언트 로그에 관련 조회가 없다면 테스트 요청이 이 단계까지 도달하지 않았을 가능성이 큽니다.

고정 매핑으로 코어의 DNS 조회 경로 검증하기

아래 예제는 로컬 검증용이며 일반적인 인터넷 연결 설정이 아닙니다. 127.0.0.1에 바인딩하고 프록시 인바운드와 다른 포트(예: 8000)를 사용하는 로컬 HTTP 서비스를 준비하세요. 앞의 구조 개요에 나온 전체 기본 설정을 바탕으로 여기에 있는 dns를 최상위 객체에 추가하고 outbounds를 바꾸세요. SOCKS를 통해 demo.test를 원래 도메인 그대로 코어에 전달한 뒤 http://demo.test:8000/에 접속합니다. 서비스가 이 호스트 이름을 받아들이거나 최소한 로그에 요청을 기록해야 합니다. 이 예제는 테스트용 예약 도메인을 루프백으로 연결하므로 외부 DNS 서버가 해당 이름에 응답할 필요가 없습니다.

{
  "dns": {
    "hosts": {
      "demo.test": "127.0.0.1"
    },
    "servers": ["localhost"]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      }
    }
  ]
}

hosts는 코어 리졸버의 정적 매핑입니다. servers의 localhost는 조회가 필요한 이름을 로컬 시스템의 이름 해석 기능으로 처리한다는 뜻이지, 루프백 주소에서 수신하는 DNS 서버가 있어야 한다는 뜻은 아닙니다. 여기서는 직접 연결 아웃바운드에 UseIP를 사용해 먼저 도메인의 IP 주소를 얻도록 하므로 앞서 설정한 정적 매핑을 확인할 수 있습니다. 테스트 앱이 직접 먼저 이름을 해석하면 도메인이 없다고 표시될 수 있습니다. 반대로 코어에 이미 IP 주소를 전달했다면 접속에 성공해도 정적 매핑을 검증한 것은 아닙니다.

이름이 같은 두 정책을 하나의 옵션으로 보지 마세요

라우팅 객체의 domainStrategy는 일치 단계에서 목적지 정보를 어떻게 보완할지 제어합니다. 아웃바운드 설정의 같은 이름 필드는 해당 아웃바운드가 연결 전에 목적지 도메인을 어떻게 처리할지 정합니다. 아웃바운드 정책만 바꿔도 앞서 일치하지 않은 라우팅 규칙이 다시 평가되지는 않습니다. 반대로 라우팅 일치를 위해 IP를 조회했다고 해서 이후 연결이 반드시 방금 조회한 주소를 사용하는 것도 아닙니다. 실제 동작은 아웃바운드 구현과 설정에 따라 달라집니다. 문제를 찾을 때는 한 번에 한 계층만 바꾸고 아웃바운드 이름과 최종 목적지를 확인해, 두 변경 사항을 하나의 옵션 탓으로 돌리지 않도록 하세요.

특정 DNS 서버를 사용한다면 먼저 현재 네트워크에서 코어가 해당 서버에 접근할 수 있는지 확인한 뒤 도메인별 조회와 대체 서버를 설정하세요. 도메인별 서버 지정은 조회를 보낼 곳을 정하는 것이며 앱 연결의 아웃바운드를 지정하는 것과 다릅니다. 두 설정에는 서로 다른 규칙이 적용될 수 있습니다. DNS 서버 주소를 도메인으로 적었다면 서버 이름을 처음에 어떻게 해석할지도 생각해야 합니다. 아직 연결되지 않은 같은 서버에 그 조회를 의존하면 순환이 발생해 여러 도메인의 조회가 동시에 시간 초과될 수 있습니다.

오류 유형으로 다음 점검 항목 찾기

도메인이 존재하지 않는 오류와 요청 시간 초과는 서로 다릅니다. 전자는 해석 가능한 부정 응답을 받았다는 뜻으로, 도메인 오타, 내부 도메인을 알지 못하는 DNS 서버에 조회를 보낸 경우, 호출되지 않은 정적 매핑 등이 원인일 수 있습니다. 시간 초과는 대기 중 유효한 응답을 받지 못했다는 뜻이므로 조회 경로, 네트워크 접근성, 서버 응답을 확인해야 합니다. 주소를 얻은 뒤에도 연결에 실패한다면 반환된 주소가 IPv4인지 IPv6인지, 네트워크에서 해당 주소에 접근할 수 있는지, 규칙에 따라 요청이 다른 아웃바운드로 전달되었는지도 확인하세요.

테스트 결과가 가끔 달라진다면 앱 캐시, 시스템 캐시, 코어 캐시, 이미 설정된 연결을 따로 살펴보세요. 페이지를 닫아도 브라우저가 연결을 계속 유지할 수 있고, 코어 설정을 바꿔도 앱의 도메인 캐시가 지워지지 않을 수 있습니다. 새로 시작한 독립 요청으로 다시 테스트하고 기록된 목적지와 결과를 비교하세요. 새로고침 횟수로 판단하지 마세요. 시스템 프록시가 얽힌 경우에는 연결 후 인터넷이 되지 않을 때 점검 목록을 참고해 먼저 인바운드 문제를 분리한 다음 DNS 점검 범위를 좁히세요.

policy: 핸드셰이크·유휴 시간·통계

정책은 접속할 도메인이나 선택할 노드를 결정하지 않으며 시스템 방화벽과도 다릅니다. policy.levels는 코어가 인식하는 사용자 수준에 따라 연결 설정을 제공하고, policy.system은 시스템 범위 통계 옵션을 포함합니다. 여기서 수준은 운영체제 계정 권한이나 구독 요금제를 뜻하지 않습니다. 인바운드 또는 프로토콜의 사용자 매개변수가 사용할 수준을 지정하고 정책 블록은 해당 수준의 동작을 정합니다. 특정 수준이 적용되지 않는다면 먼저 현재 연결의 인바운드와 프로토콜에서 해당 수준을 실제로 사용하고 있는지 확인하세요.

테스트 인바운드에 명확한 대기 시간 설정하기

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 300,
        "uplinkOnly": 5,
        "downlinkOnly": 5
      }
    },
    "system": {
      "statsInboundUplink": true,
      "statsInboundDownlink": true
    }
  },
  "stats": {}
}

이 최상위 필드 두 개를 설정에 추가하고 앞에서 userLevel: 0으로 지정한 SOCKS 인바운드로 테스트하세요. levels의 키는 수준 번호를 문자열로 나타내고, 시간 값은 초 단위 숫자로 입력합니다. 이 값은 설명을 위한 예시일 뿐 모든 네트워크에 권장되는 고정값이 아닙니다. 실제로 적용되는 설정은 프로토콜 구현에 따라 다릅니다. 코어가 인바운드를 처리하는 중 연결을 끊었는지, 원격 서버·앱·네트워크 장비가 먼저 종료했는지도 구분해야 합니다.

필드적용되는 단계관찰할 수 있는 현상
handshake해당 프로토콜의 초기 핸드셰이크.연결은 되었지만 핸드셰이크가 끝나지 않습니다.
connIdle연결이 설정된 뒤 일정 시간 동안 데이터가 오가지 않습니다.사용 중에는 정상인데 오래 유휴 상태로 두면 끊깁니다.
uplinkOnly다운로드가 끝난 뒤에도 업로드를 계속할 수 있는 시간.클라이언트에서 대상 방향으로 데이터만 전송합니다.
downlinkOnly업로드가 끝난 뒤에도 다운로드를 계속할 수 있는 시간.전송을 마쳤지만 남은 응답을 읽기 위해 대기합니다.

연결 단계에 따라 시간 설정 변경 여부 판단하기

핸드셰이크 제한 시간이 너무 짧으면 느린 연결이 협상을 마치기 전에 종료될 수 있습니다. 그렇다고 시간을 늘려도 포트 오타, 목적지의 연결 거부, 프로토콜 매개변수 불일치는 해결되지 않습니다. 유휴 시간은 연결의 전체 수명이 아닙니다. 데이터가 주기적으로 오가는 세션은 ‘연결을 연 지 몇 초가 지났는지’만으로 유휴 기준에 도달했는지 판단할 수 없습니다. 확인이 필요하면 마지막 데이터가 오간 시각을 기록하고 설정한 간격에 가까워졌을 때 종료되는지 관찰한 뒤 앱과 서버의 자체 유휴 시간 제한도 비교하세요.

한 방향의 종료 후 대기 시간을 업로드·다운로드 속도 제한으로 오해하기 쉽습니다. 실제로는 한쪽 방향이 끝난 뒤 반대쪽 데이터를 처리할 수 있도록 얼마나 오래 연결을 유지할지 제어합니다. 예를 들어 테스트 프로그램이 요청을 보낸 뒤 전송 방향을 닫아도 서버가 마지막 응답을 준비하는 데 시간이 더 걸릴 수 있습니다. 대기 시간이 짧으면 응답을 끝까지 받지 못할 수 있습니다. 하지만 테스트 프로그램이 연결 전체를 바로 닫았다면 시간을 늘려도 앱이 데이터를 다시 읽지는 않습니다. 한 번에 필드 하나만 바꾸고 연결이 끊기는 요청을 재현해 확인하세요.

통계 옵션, 조회 방법, 적용 범위

stats는 통계 구성 요소를 활성화하고, policy.system의 두 옵션은 인바운드별 업로드·다운로드 누계를 허용합니다. 예제에는 통계를 외부에서 읽을 인터페이스가 설정되어 있지 않으며 클라이언트 화면에 그래프가 자동으로 추가되지도 않습니다. 그래픽 클라이언트에서 해당 데이터를 표시하는지, 어떻게 읽고 언제 초기화하는지는 통합 방식에 따라 다릅니다. 사용자별 통계에는 별도의 수준 설정이 필요하고 프로토콜이 사용자를 식별할 수 있어야 합니다. 인증 없는 인바운드의 전체 트래픽을 로컬 앱별 사용량으로 나눌 수는 없습니다.

문제 해결 시에는 같은 기준의 값을 비교하세요. 누계와 속도는 다르고 인바운드와 아웃바운드의 트래픽도 반드시 일치하지 않습니다. 프로세스 재시작 전후의 수치를 연속된 기록으로 볼 수 없으며, 클라이언트가 설정을 전환할 때 새 프로세스를 시작할 수도 있습니다. 특정 테스트가 인바운드에 들어왔는지만 확인하려면 해당 연결의 태그와 로그를 먼저 보세요. 디버깅을 위해 상세 통계나 접근 로그를 잠시 켰다면 작업 후 평소 설정으로 되돌리세요. 통계를 읽기 위해 네트워크 리스너를 추가로 열지 마세요.

설정 검증 및 문제 해결

효율적인 문제 해결은 의심스러운 옵션을 전부 초기화하는 것이 아니라 현재 증상을 기록하고 범위를 최소화해 비교하는 데서 시작합니다. 사용 중인 코어, 설정을 불러온 경로, 프록시 인바운드, 재현할 목적지를 기록하세요. 클라이언트나 프로세스가 여러 개라면 어느 프로세스가 로그를 작성하는지도 확인해야 합니다. ‘설정을 읽을 수 있는가, 포트에 연결되는가, 요청이 코어에 도달하는가, 예상한 아웃바운드를 선택하는가, 목적지에서 응답이 오는가’ 순서로 검증하세요. 앞 단계가 성립하지 않았다면 뒤 단계의 이상 징후가 이번 테스트와 관련 없을 수도 있습니다.

설정 읽기 오류부터 확인한 다음 리스너 실패 점검하기

코어가 파일을 읽지 못하면 시작 로그에서 관련된 첫 번째 오류를 먼저 확인하세요. 줄 번호가 표시되더라도 해당 줄뿐 아니라 이전 항목의 쉼표와 바깥 괄호도 살펴봐야 합니다. 파서는 대개 더 이상 읽을 수 없는 첫 문자를 보고하지만 그 문자가 원래 오류가 발생한 위치라고 보장하지는 않습니다. JSON으로 파싱된다는 것은 문법 구조가 완전하다는 뜻일 뿐 프로토콜 지원 여부, 포트 사용 가능 여부, 태그 참조의 정확성을 보장하지 않습니다. 설정을 바꾸자마자 클라이언트가 연결 끊김 상태로 돌아간다면 구독을 새로고침하거나 속도를 다시 측정하기 전에 시작 오류부터 확인하세요.

시작에 성공한 뒤에도 같은 이름의 프로세스가 있는지만 확인하지 마세요. 실제 프로세스가 바인딩한 주소와 포트를 확인해 테스트 요청에 입력한 값과 비교하세요. 연결 거부가 표시되면 리스너가 없는지, 프록시 주소가 틀렸는지, 주소 계열이 다른지, 프로세스의 시작·종료 시각이 맞지 않는지 먼저 점검하세요. 로컬 포트에는 연결되지만 프록시 핸드셰이크가 실패한다면 해당 포트가 SOCKS와 HTTP 중 무엇을 제공하는지 확인하세요. 다른 프로그램이 포트를 사용하고 있어도 클라이언트 인터페이스에는 올바른 옵션처럼 표시될 수 있습니다. 시작 로그와 실제 요청만이 연결을 처리하는 프로그램을 알려 줍니다.

요청 하나로 재현해 범위 좁히기

시스템에 curl이 설치되어 있다면 명령줄에서 아래 요청을 실행해 전체 기본 설정을 검증할 수 있습니다. socks5h는 도메인을 SOCKS 프록시에 전달한다는 뜻입니다. --noproxy ""는 환경의 프록시 예외 때문에 테스트가 명시적 프록시를 우회하지 않도록 합니다. example.org를 차단 아웃바운드로 보내는 라우팅 예제에서는 첫 번째 요청이 실패해야 합니다. 두 번째 요청은 해당 도메인 규칙에 일치하지 않는 경우를 비교하는 테스트지만, 로컬 네트워크에서 대상 서비스에 접근할 수 있어야 합니다. 세 번째 요청은 DNS 절의 로컬 매핑 테스트이므로 해당 설정을 불러오고 로컬 서비스를 먼저 준비해야 합니다. 세 요청이 같은 설정에서 모두 성공할 필요는 없습니다.

curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 https://example.org/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 https://example.com/
curl --noproxy "" --proxy socks5h://127.0.0.1:10808 --max-time 15 http://demo.test:8000/

독립 요청은 성공하지만 브라우저가 실패한다면 브라우저 자체의 프록시 모드, 연결 재사용, 이름 해석 설정, 시스템 프록시 예외를 집중적으로 확인하세요. 둘 다 실패한다면 로그에서 이번 테스트의 인바운드 태그와 아웃바운드 경로를 먼저 찾으세요. 요청이 보이지 않는다고 코어에 도달하지 않은 것은 아닙니다. 현재 로그 수준이나 클라이언트가 표시하는 범위에서 접근 세부 정보가 기록되지 않을 수도 있습니다. 기본 설정의 loglevel을 info로 잠시 바꾸고 재시도한 뒤 필요하면 클라이언트에서 코어 접근 로그를 확인하고, 작업이 끝나면 평소 수준으로 되돌리세요.

변경 사항을 다시 테스트하고 되돌릴 수 있게 관리하기

복잡한 문제는 인바운드 하나와 직접 연결 아웃바운드 하나만 있는 복사본에서 시작하세요. 앱이 로컬 프록시를 통해 실제로 목적지에 접근하는지 확인한 다음 결과를 구분할 라우팅 규칙을 추가하고, 필요한 경우 DNS나 연결 정책을 넣은 뒤 마지막으로 원격 아웃바운드를 검증하세요. 변경할 때마다 같은 프로토콜, 포트, 목적지로 재테스트하고 변경의 영향을 받지 않아야 하는 요청도 하나 남겨 두세요. 새로운 오류가 생기면 방금 변경한 내용만 되돌려 정상으로 돌아오는지 확인하세요. 이렇게 해야 우연히 한 번 성공한 연결이 아니라 원인을 파악할 수 있는 단서를 얻을 수 있습니다.

기록은 인바운드, 목적지, 아웃바운드, 단계, 결과의 다섯 항목으로 간단히 정리할 수 있습니다. 다른 사람에게 문제를 설명할 때는 오류 유형, 관련 태그, 필요한 필드 구조만 남기고 내보낸 설정 전체를 그대로 공유하지 마세요. 구독 주소, 계정 정보, 내부 주소, 상세 접근 기록은 삭제해야 합니다. 설정 조각을 편집했다면 테스트용으로 바꾼 이름이 무엇인지도 알려 주세요. 원격 전송 단계에서 오류가 발생했다면 노드 시간 초과 문제 해결을 참고하세요. 처음 인바운드와 연결 방식을 설정하는 중이라면 빠른 시작 가이드로 돌아가는 편이 더 빠릅니다.