설정 가이드 / JSON

V2Ray 설정 파일:JSON 필드 가이드

하나의 연결을 따라 설정을 살펴봅니다. 애플리케이션이 어떤 인바운드로 들어오고, 라우팅이 어떤 아웃바운드를 선택하며, DNS 조회와 시간 제한은 어디서 처리되는지 확인하세요.

처음 설치하거나 구독을 가져오는 경우 빠른 시작 가이드를 따라 먼저 연결을 설정하세요. 이 페이지는 설정을 변경할 때 필드별로 참고할 수 있도록 구성했습니다. 로컬 리스닝 및 직접 연결 예제를 통해 코어의 동작과 클라이언트의 트래픽 처리 방식을 구분해 살펴봅니다.

JSON 구조 한눈에 보기

루트 객체, 배열, 프로토콜 매개변수 구분하기

일반적인 V2Ray 호환 JSON 설정은 객체 하나를 루트로 사용합니다. inbounds와 outbounds는 배열입니다. 하나의 설정에 여러 인바운드와 아웃바운드를 둘 수 있기 때문입니다. routing, dns, policy, log는 보통 객체이며, 각각 전달 경로 선택, 도메인 조회, 연결 정책, 로그를 설정합니다. 객체 안의 필드도 유형을 확인해야 합니다. 예를 들어 routing.rules는 배열이지만, policy.levels는 레벨 번호를 키로 사용하는 객체입니다. 들여쓰기는 사람이 읽기 쉽게 도울 뿐, 서로 인접한 필드를 같은 계층으로 묶어 주지는 않습니다.

settings를 보면 먼저 같은 수준의 protocol을 확인하세요. 이 이름은 여러 인바운드와 아웃바운드에서 쓰이지만, 모든 경우에 통하는 공통 매개변수 표는 없습니다. SOCKS 인바운드의 인증 옵션을 HTTP 인바운드에 옮길 수 없고, 아웃바운드의 대상 주소를 인바운드의 리스닝 주소로 대신할 수도 없습니다. 설정을 살펴볼 때는 '첫 번째 인바운드의 리스닝 포트' 또는 '두 번째 라우팅 규칙의 대상 태그'처럼 전체 경로를 기록하세요. 필드 이름 하나만 기억하는 것보다 어느 계층에서 변경해야 하는지 파악하기 쉽습니다.

단독 실행 가능한 로컬 기준 설정

전체 예제 · 루프백 HTTP 인바운드와 직접 연결 아웃바운드
{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "http-local",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ]
}

이 예제는 지원되는 필드로 구성된 완전한 단일 파일 설정으로, 해당 필드를 지원하는 코어에서 불러올 수 있습니다. 인바운드는 로컬 주소 127.0.0.1:10809에서만 수신합니다. 프록시를 설정할 수 있는 애플리케이션은 이 HTTP 프록시를 직접 지정해 사용할 수 있습니다. 아웃바운드는 하나뿐이며 별도의 라우팅 규칙이 없으므로, 코어에 전달된 일반 요청은 기본 경로를 통해 직접 연결됩니다. 원격 서버 정보는 없으며 시스템 프록시를 설정하거나 가상 네트워크 인터페이스를 자동으로 만들지 않습니다. 데스크톱 클라이언트가 이미 이 포트를 사용 중이면 사용 가능한 포트로 바꾸고 테스트 애플리케이션에서도 같은 포트로 변경하세요.

기준 설정이 정상인지 확인하려면 두 단계로 나눠 살펴보세요. 시작할 때 설정 오류가 없다는 것은 코어가 설정을 받아들여 리스너를 만들려고 했다는 뜻일 뿐입니다. 애플리케이션과 인바운드, 아웃바운드가 연결에 모두 관여하는지 확인하려면 대상이 명확한 요청을 보내야 합니다. 먼저 같은 애플리케이션에서 대상에 직접 접속한 다음, 같은 대상에 프록시를 명시해 접속하세요. 직접 연결부터 실패한다면 기준 설정도 실패할 수 있습니다. 그렇다고 인바운드 설정이 잘못됐다는 뜻은 아닙니다. 테스트 중에 시스템 프록시까지 함께 바꾸지 마세요. 다른 애플리케이션의 요청이 결과에 섞일 수 있습니다.

독립 파일과 섹션별 예제 병합하기

아래에서 '필드 교체' 또는 '루트 객체에 추가'라고 표시한 설정 창은 일부만 보여 주는 예제입니다. 바깥쪽 중괄호는 설정의 위치를 보여 주기 위한 것으로, 별도 파일을 만들어 실행하라는 뜻이 아닙니다. 두 번째 루트 객체를 파일 끝에 붙여 넣어서도 안 됩니다. 같은 이름의 루트 필드가 이미 있다면 해당 필드를 예제로 교체하거나 필요한 데이터를 합치세요. 라우팅을 합친 뒤에는 규칙 순서를 다시 확인하고, 인바운드를 합친 뒤에는 포트를 재확인해야 합니다. 편집기에서 오류가 표시되지 않는다고 병합 결과가 실행 조건을 만족한다고 단정할 수는 없습니다.

가져오기 경로마다 해석이 달라지지 않도록 엄격한 JSON 문법을 지키세요. 키와 문자열은 반각 큰따옴표로 감싸고, 숫자 포트에는 따옴표를 쓰지 않습니다. 객체나 배열의 마지막 항목 뒤에는 쉼표를 붙이지 말고, 코드 안에 주석으로 설명을 적지 마세요. 중복 키는 특히 발견하기 어렵습니다. 파서에 따라 오류로 거부되거나 뒤에 나온 값만 남을 수 있어 앞선 설정이 적용되지 않은 것처럼 보입니다. 파일은 UTF-8로 저장하고 실행용 사본과 수정 초안을 분리하세요. 클라이언트가 생성한 설정은 다음에 설정을 전환할 때 다시 생성될 수 있으므로 클라이언트에서 제공하는 설정 화면을 통해 수정하는 편이 좋습니다.

inbounds 인바운드

리스닝 주소, 포트, 프로토콜이 모두 일치해야 합니다

인바운드는 코어가 어느 주소에서 연결을 받고 애플리케이션이 보낸 데이터를 어떤 프로토콜로 해석할지 정의합니다. listen은 실행 중인 기기에 바인딩하는 주소이지 원격 서버 주소가 아닙니다. port는 애플리케이션이 연결할 로컬 포트이지 상대 서버의 포트가 아닙니다. 루프백 주소를 사용하면 로컬 테스트와 LAN 접속을 분리할 수 있습니다. 두 주소가 결국 같은 컴퓨터를 가리키더라도 루프백에 바인딩된 인바운드는 네트워크 인터페이스 주소로 들어오는 요청을 받지 않습니다.

애플리케이션에서 선택하는 프록시 유형도 반드시 맞아야 합니다. HTTP 프록시를 선택했다면 HTTP 인바운드에 연결하고, SOCKS 프록시를 선택했다면 SOCKS 인바운드에 연결해야 합니다. 주소와 포트가 맞더라도 프로토콜이 다르면 소켓 연결은 성공한 뒤 프록시 협상 단계에서 실패할 수 있습니다. 애플리케이션이 기본값으로 입력하는 localhost도 확인하세요. 먼저 IPv6 루프백 주소로 연결하려는데 설정은 IPv4에만 바인딩되어 있다면 애플리케이션 주소를 임시로 127.0.0.1로 바꿔 주소 계열 차이인지 확인할 수 있습니다.

두 인바운드에 각각 구분되는 태그 지정

필드 교체 · HTTP는 유지하고 SOCKS 인바운드 추가
{
  "inbounds": [
    {
      "tag": "socks-local",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    },
    {
      "tag": "http-local",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

두 인바운드 예제는 프로토콜을 서로 다른 포트로 분리해 비교하기 쉽게 합니다. tag는 설정 내부에서 사용하는 식별자이며, 애플리케이션에는 주소와 포트를 입력하면 됩니다. 태그는 중복 없이 일관되게 지정하세요. 서로 다른 애플리케이션의 요청을 나눠 테스트하려면 먼저 각각 다른 인바운드를 사용하게 한 뒤 routing.rules의 inboundTag로 구분하세요. 애플리케이션 이름만으로 라우팅을 추측해서는 안 됩니다. 인바운드 이름과 아웃바운드 이름을 같게 할 필요는 없습니다. 이름을 다르게 지정하면 로그에 연결이 들어온 위치와 나간 위치가 더 잘 드러납니다.

예제의 SOCKS 인바운드는 인증을 사용하지 않으며 로컬 주소에서만 수신합니다. SOCKS의 UDP 전달은 비활성화되어 있어 일반 웹 요청처럼 TCP 트래픽을 먼저 확인하기에 적합합니다. 주로 UDP를 사용하는 소프트웨어라면 SOCKS의 TCP 테스트가 성공해도 정상 동작을 보장할 수 없습니다. 애플리케이션이 해당 프록시 전달을 지원하는지, 인바운드에서 허용하는지, 이후 아웃바운드가 그 트래픽을 처리할 수 있는지 모두 확인해야 합니다. 연결을 확인하려고 리스닝 범위를 넓히지 마세요. 로컬 검증에는 다른 기기의 프록시 접속이 필요하지 않습니다.

연결 실패 단계로 인바운드 문제 찾기

코어 시작 중 바인딩 실패가 보고되면 먼저 리스닝 주소가 이 기기에 속하는지 확인하고, 이전 인스턴스나 클라이언트 내장 인바운드 또는 다른 프로그램이 포트를 사용 중인지 살펴보세요. 새 포트를 정했다면 파일만 바꾸면 안 됩니다. 브라우저의 수동 프록시 설정, 시스템 프록시 기록, 테스트 명령도 이전 포트를 가리키고 있을 수 있습니다. 새 설정과 기존 설정이 일치하지 않으면 요청이 거부되는 대신 테스트 프로그램이 여전히 실행 중인 다른 프록시에 연결될 수 있습니다. 이 경우 변경 사항이 전혀 적용되지 않은 것처럼 보입니다.

포트 연결은 되는데 예상한 인바운드 태그가 로그에 없다면 애플리케이션이 자체 프록시 설정을 사용하는지, 대상 예외가 설정되어 있는지, 이번 요청이 기존 연결을 재사용했는지 먼저 확인하세요. 인바운드 태그가 확인된 뒤에 아웃바운드와 도메인 매칭을 살펴보면 됩니다. 인바운드가 받은 대상이 도메인인지 애플리케이션이 미리 조회한 주소인지도 구분해야 합니다. 애플리케이션이 먼저 주소를 조회했다면 도메인 규칙에 사용할 정보가 없을 수 있습니다. 문제의 원인이 리스닝 프로토콜이 아닐 수도 있습니다. 입력 조건을 그대로 유지하고 애플리케이션이 실제로 어떤 대상을 전달했는지 기록한 다음 이후 규칙을 확인하세요.

outbounds 아웃바운드

첫 항목이 기본 아웃바운드이며 태그는 라우팅에서 참조합니다

인바운드가 요청을 받으면 코어는 다음으로 대상에 연결할 방법을 결정합니다. outbounds의 각 항목에서 protocol은 실제 동작을 정의하고 tag는 라우팅에서 참조하는 식별자일 뿐입니다. 태그를 direct라고 붙여도 어떤 프로토콜이든 직접 연결로 바뀌지 않으며, blocked라고 붙여도 자동으로 차단되지 않습니다. 라우팅 규칙과 일치하지 않는 일반 요청은 배열의 첫 번째 항목을 기본 아웃바운드로 사용합니다. 항목을 두 개 나란히 둔다고 동시에 시도하거나 실패 후 자동 전환되는 것은 아닙니다.

직접 연결을 기본 아웃바운드로 설정하면 서버에 의존하지 않아 이 페이지의 로컬 실험에 적합합니다. 하지만 실제 사용에서도 무조건 기본값으로 적용할 수 있는 것은 아닙니다. 규칙 목록에 없는 대상이 직접 연결되어도 되는지 먼저 판단한 뒤 기본 아웃바운드를 정하세요. 분류 규칙이 빠짐없이 적용되는지 살펴보려면 독립 테스트 설정에서 차단 아웃바운드를 기본값으로 두고 알려진 대상을 명시적으로 허용할 수 있습니다. 이는 규칙에 걸리지 않은 대상을 확인하기 위한 방법입니다. 여러 애플리케이션이 사용하는 기존 설정을 그대로 대체하는 용도로는 적합하지 않습니다.

직접 연결과 차단의 최소 동작

필드 교체 · 기본값은 직접 연결, 라우팅에서 참조할 차단 아웃바운드 추가
{
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {
        "response": {
          "type": "none"
        }
      }
    }
  ]
}

freedom은 대상에 직접 연결합니다. 실제로 사용하는 로컬 네트워크와 DNS 조회 방식은 실행 환경과 아웃바운드 설정에 따라 다릅니다. 요청이 프록시 인바운드를 거쳤다고 해서 원격 프록시 서버로 전달되지는 않습니다. blackhole은 대상에 연결하지 않습니다. 예제에서는 응답 유형을 none으로 설정했으므로 애플리케이션에는 연결 종료나 일반적인 프록시 오류가 표시될 수 있으며, 차단 사유를 설명하는 페이지가 제공되지는 않습니다. 의도적인 차단과 대상 서버 장애를 구분하려면 애플리케이션의 오류 창만 보지 말고 선택된 아웃바운드와 대상 서비스의 접속 로그도 확인하세요.

이 예제의 두 번째 항목은 라우팅 규칙을 추가하기 전까지 일반 요청을 처리하지 않습니다. 배열 순서는 그대로 두고 범위가 좁은 규칙을 추가해 차단 동작을 확인할 수 있습니다. 테스트가 실패하면 먼저 앞선 규칙이 해당 요청을 가로채지 않았는지 살펴보세요. 아웃바운드 이름을 바꾸면 기존 태그를 참조하는 모든 규칙도 함께 수정하고 대소문자까지 확인해야 합니다. 존재하지 않는 아웃바운드 태그는 사용할 수 있는 대체 경로가 아닙니다. 코어가 파일을 정상적으로 불러왔다고 해서 요청이 첫 번째 항목으로 자동 전환된다고 볼 수 없습니다.

원격 연결은 서비스 매개변수와 하나씩 대조하세요

원격 아웃바운드를 설정할 때는 프록시 프로토콜, 연결을 전달하는 전송 방식, 전송 보안 계층을 구분하세요. 서로 연관되어 있지만 서로를 대신할 수는 없습니다. 같은 프록시 프로토콜도 여러 전송 방식으로 사용할 수 있으며, 주소와 포트가 같다고 양쪽 설정이 일치하는 것은 아닙니다. 공유 링크를 가져온 뒤에는 클라이언트에서 변환된 프로토콜, 전송 방식, 보안 설정이 제공자의 안내와 일치하는지 먼저 확인하세요. 코어 종류에 따라 지원하지 않는 필드나 값이 있을 수 있습니다. 다른 예제에서 설정 몇 줄을 가져와 그대로 합치지 마세요.

원격 설정을 변경할 때는 정상 동작하는 로컬 인바운드를 유지하고 테스트 애플리케이션과 대상을 고정한 채 한 번에 조건 하나만 바꾸세요. 인바운드 로그는 나타나는데 원격 연결이 시간 초과되면 원격 주소를 조회할 수 있는지, 포트에 연결할 수 있는지, 연결 수립과 핸드셰이크 중 어느 단계에서 실패하는지 따로 확인하세요. 같은 기기에서 이 페이지의 직접 연결 기준 설정으로 테스트 대상에 접속할 수 있다는 것은 로컬 인바운드에서 해당 대상으로 직접 연결되는 경로가 작동한다는 뜻일 뿐, 원격 서비스 매개변수가 올바르다는 뜻은 아닙니다. 프로토콜 필드는 프록시 프로토콜 비교를 참고한 다음 실제 설정에서 차이를 찾아보세요.

routing 라우팅 규칙

구체적인 규칙을 일반 규칙보다 먼저 배치하세요

routing.rules는 배열 순서대로 검사합니다. 아래와 같은 필드 기반 규칙은 앞쪽 규칙과 일치하면 지정된 아웃바운드를 선택하고 뒤에 있는 규칙을 더 이상 비교하지 않습니다. 예를 들어 특정 네트워크 범위 전체를 직접 연결하는 규칙을 먼저 두고 그 범위 안의 특정 기기를 차단하는 규칙을 나중에 두면, 뒤의 규칙은 보통 실행되지 않습니다. 예외를 적용하려면 범위가 좁은 규칙을 더 넓은 규칙보다 앞에 두세요. 문제를 해결할 때는 마지막으로 수정한 규칙만 보지 말고 목록 첫 부분부터 일치할 가능성이 있는 규칙을 찾으세요.

하나의 필드 기반 규칙에 inboundTag와 ip를 함께 지정하면 예제에서는 인바운드와 대상 주소 조건이 모두 맞아야 합니다. 개별 필드의 목록에는 여러 후보 값을 넣을 수 있습니다. '지정한 인바운드에서 온 요청 또는 지정한 네트워크 범위의 대상'을 뜻하게 하려면 보통 같은 아웃바운드를 선택하는 규칙을 각각 작성합니다. 두 방식을 혼동하면 예제의 대상 하나는 우연히 일치하지만 다른 애플리케이션이나 주소에서는 기본 아웃바운드로 나가는 일이 생길 수 있습니다.

로컬 요청으로 규칙 순서와 범위 확인하기

루트 객체에 추가 · 인바운드 두 개 및 아웃바운드 두 개 설정과 함께 테스트
{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["socks-local"],
        "ip": ["127.0.0.1/32"],
        "outboundTag": "blocked"
      },
      {
        "type": "field",
        "ip": ["127.0.0.0/8"],
        "outboundTag": "direct"
      }
    ]
  }
}

직접 연결이 가능한 로컬 HTTP 테스트 서비스를 준비하세요. 대상 주소에는 127.0.0.1과 서비스 포트를 사용하고, 프록시 리스닝 포트를 대상 포트로 입력하지 마세요. SOCKS 인바운드로 들어온 연결은 첫 번째 규칙과 일치해 차단 아웃바운드로 갑니다. 같은 대상에 HTTP 인바운드로 연결하면 첫 번째 규칙과 일치하지 않아 다음 규칙을 검사하고 두 번째 규칙에 해당합니다. 두 규칙의 순서를 바꾸고 새 연결을 만들면 범위가 넓은 주소 규칙이 인바운드 예외보다 먼저 적용되는 것을 확인할 수 있습니다. 여기서 IP 주소를 그대로 쓰는 이유는 DNS 조회 차이가 라우팅 실험에 섞이지 않도록 하기 위해서입니다.

실제 설정에서는 세 가지를 구분하세요. 일치한 규칙, 규칙과 일치하지 않았을 때의 기본 아웃바운드, 일치한 뒤 아웃바운드 실행이 실패한 경우입니다. 명시적인 기본 규칙이 없더라도 첫 번째 아웃바운드는 계속 사용됩니다. 범위가 넓은 기본 규칙을 추가하면 이후 규칙에 도달하지 못할 수 있습니다. 로그에 예상한 아웃바운드가 표시되는데도 연결이 실패한다면 라우팅 순서를 계속 바꾸지 말고 해당 아웃바운드와 대상 서비스를 확인하세요. 기존 규칙에 예외를 넣을 때는 영향을 받지 않아야 하는 대상도 함께 비교하면 새로 추가한 경우만 테스트하는 일을 피할 수 있습니다.

도메인 규칙과 주소 규칙은 서로 다른 입력을 사용합니다

정확히 일치시키려면 full:example.test를 사용할 수 있습니다. 해당 도메인과 하위 도메인까지 포함하려면 domain:example.test를 사용하세요. 문자열 포함 여부에 기대기보다 분명한 접두어를 사용하면 규칙을 검토하기 쉽습니다. geosite:cn과 같은 형식은 도메인 데이터의 분류를 참조합니다. 코어가 해당 리소스를 찾아야 하며 실제 분류 결과는 불러온 데이터에 따라 달라집니다. 이는 위치를 감지하는 기능이 아니며 특정 서비스의 모든 관련 도메인을 포함한다고 보장하지도 않습니다. 실제 요청의 대상을 확인해 도메인 목록이 일치하는지 살펴보세요.

AsIs는 라우팅 매칭을 위해 도메인을 추가로 주소로 조회하지 않습니다. IPIfNonMatch는 첫 번째 매칭에 실패한 경우 조회한 주소로 다시 매칭을 시도할 수 있습니다. 후자를 선택하기 전에 조회 지연, 조회 결과와 이후 실제 연결 대상의 관계, 기존 기본 규칙이 첫 번째 검사에서 이미 일치하는지 고려하세요. 두 전략 모두 애플리케이션이 전달한 임의의 IP 주소를 도메인으로 복원하지는 않습니다. 도메인 규칙을 테스트하려면 먼저 애플리케이션이 대상 도메인을 인바운드에 전달하도록 한 뒤 예상한 매칭 경로를 거치는지 확인하세요.

dns 도메인 조회

먼저 어떤 구성 요소가 조회를 보내는지 확인하세요

루트 객체의 dns 설정은 코어의 도메인 조회 로직에 적용됩니다. 운영체제의 DNS 설정과 같지 않으며 애플리케이션이 직접 보내는 모든 조회를 가로채지도 않습니다. 애플리케이션은 도메인을 먼저 조회한 뒤 주소를 프록시에 전달할 수도 있고, 도메인을 프록시 요청에 그대로 넣을 수도 있습니다. 자체 조회 옵션을 제공하는 애플리케이션도 있습니다. 설정이 적용되는지 판단하기 전에 이번 요청의 대상이 어떤 형태인지, 코어의 라우팅 또는 아웃바운드가 내장 DNS를 호출하는지 확인하세요. 브라우저에 도메인이 표시된다고 해서 같은 문자열이 반드시 코어에 전달되는 것은 아닙니다.

라우팅을 위한 DNS 조회와 아웃바운드 연결을 위한 DNS 조회도 구분해야 합니다. 전자는 대상이 주소 규칙에 맞는지 판단하고, 후자는 실제 연결을 수립하는 데 쓰입니다. 라우팅에서 주소를 조회했다고 해서 모든 프로토콜, 아웃바운드, 애플리케이션이 같은 결과를 사용하는 것은 아닙니다. 경로마다 별도의 캐시를 사용할 수 있고 주소 계열 선택에 따라 다른 결과를 얻을 수도 있습니다. 문제를 해결할 때 '도메인을 조회할 수 있다'와 '현재 연결이 실제로 이 주소를 사용한다'를 같은 의미로 보지 마세요. 필요한 경우 대상과 아웃바운드에서 관찰한 결과를 함께 기록하세요.

정적 매핑으로 내장 DNS 경로부터 확인하기

관련 설정 변경 · dns 추가 및 기준 설정의 outbounds 교체
{
  "dns": {
    "hosts": {
      "example.test": "127.0.0.1"
    },
    "servers": ["localhost"]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {
        "domainStrategy": "UseIP"
      }
    }
  ]
}

단일 인바운드 기준 설정에 이 dns 객체를 추가하고 기존 아웃바운드도 교체하세요. 직접 연결 아웃바운드에 UseIP를 설정하면 도메인으로 유지된 테스트 대상이 내장 DNS를 통해 주소를 얻을 수 있습니다. hosts는 테스트 이름을 루프백 주소에 매핑하며 시스템의 호스트 이름 매핑은 수정하지 않습니다. servers의 localhost는 로컬 DNS 조회 기능을 사용한다는 뜻이지, 루프백 주소에 조회 가능한 서비스가 이미 실행 중이라고 선언하는 것이 아닙니다. 테스트 이름에는 예약된 도메인 접미사를 사용하세요. 프록시를 통해 실행 중인 로컬 테스트 서비스에 접속해야 하며 공개 웹사이트로 취급해서는 안 됩니다.

이 예제는 원본 기준 설정에서 테스트하세요. 이전 장의 설정에는 아직 blocked를 참조하는 규칙이 있으므로 그 설정에 덮어쓰면 참조 대상 아웃바운드가 삭제됩니다. 애플리케이션이 테스트 이름을 프록시에서 제외하거나 자체 DNS로 먼저 조회하려 하면 정적 매핑은 코어를 거치지 않습니다. 반대로 직접 연결 아웃바운드의 기본 도메인 처리 방식으로 되돌리면 같은 이름을 시스템에서 조회하려고 할 수 있습니다. 아웃바운드의 DNS 처리 방식만 다른 설정 두 개를 비교하고 매번 새 연결을 만들어 내장 매핑과 시스템 조회 결과를 구분하세요.

그룹별 업스트림, 주소 계열, 캐시

도메인마다 다른 업스트림을 사용해야 한다면 사용하는 코어가 servers 객체 항목을 어떻게 지원하는지 확인하세요. 예를 들어 address로 DNS 서버 주소를 지정하고 domains로 매칭 범위를 설정할 수 있습니다. 전용 업스트림을 나열한다고 다른 서버가 전혀 사용되지 않는 것은 아닙니다. 해당 코어의 후보 순서, 실패 시 재시도, 결과 필터링 규칙을 확인하세요. HTTPS 기반 DNS 서버를 사용할 때는 서버 주소를 어떻게 조회하고 연결하는지도 점검해야 합니다. 서버 도메인을 조회할 때 반드시 그 서버 자신을 먼저 사용해야 한다면 안정적인 시작 경로가 없습니다.

IP 주소로는 연결되는데 도메인으로 연결되지 않는다면 실제 조회를 담당하는 계층을 먼저 테스트하고 결과에 어떤 주소 계열이 포함되는지 확인하세요. IPv4 또는 IPv6만 사용하도록 설정하면 일부 대상에 적합한 주소가 없을 수 있습니다. 문제 범위를 좁히는 용도로는 쓸 수 있지만 모든 네트워크 문제의 해결책은 아닙니다. 설정을 바꾼 뒤에는 애플리케이션의 DNS 캐시, 시스템 캐시, 기존 연결의 갱신 시점이 서로 다르다는 점도 고려하세요. 기존 연결을 닫고 대상이 명확한 새 요청을 보내 어느 계층에서 이전 주소가 계속 반환되는지 확인한 다음 해당 캐시를 비울지 결정하세요.

policy 연결 정책

레벨 정책은 연결 동작을 제어하며 전달 경로는 선택하지 않습니다

policy는 연결 유지 시간, 버퍼, 통계 등 코어의 동작 방식을 설정하며 도메인을 아웃바운드별로 분배하지 않습니다. policy.levels는 "0"처럼 레벨 번호를 문자열 키로 사용하는 객체입니다. 연결에 적용되는 레벨은 해당 프로토콜과 인바운드의 사용자 레벨 설정에 따라 달라집니다. 설정에 새 레벨을 정의해도 요청이 자동으로 그 레벨에 배정되지는 않습니다. 매개변수를 확인하기 전에 현재 프로토콜이 레벨을 선택하는 방식을 검증하고 기본 레벨과 명시적으로 지정한 레벨을 따로 테스트하세요.

정책 설정은 앞 단계의 설정 오류를 가리는 용도로 쓰이기 쉽습니다. 인바운드 포트에 연결할 수 없거나 원격 전송 매개변수가 일치하지 않거나 DNS 조회가 예상치 못한 경로를 거치는 문제는 시간 제한을 늘려도 해결되지 않습니다. 오류를 클라이언트에 표시하는 시점만 늦출 수 있습니다. 먼저 최소한의 설정으로 경로가 올바른지 확인한 다음 구체적인 애플리케이션 동작을 근거로 정책을 조정하세요. 요청 활동이 전혀 없을 때 연결이 끊기는 경우와 데이터가 계속 오가는데 전송이 느린 경우는 같은 시간 초과 설정으로 설명할 수 없습니다.

핸드셰이크, 유휴 시간, 한쪽 방향 종료 구분하기

루트 객체에 추가 · 레벨 0의 연결 시간 제한을 초 단위로 설정
{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 180,
        "uplinkOnly": 4,
        "downlinkOnly": 12
      }
    }
  }
}

handshake는 지원되는 프로토콜에서 초기 핸드셰이크 대기 시간을 제한합니다. 모든 네트워크 호출에 적용되는 공통 연결 시간 제한이 아니며 원격 프로그램 자체의 시간 제한도 덮어쓰지 않습니다. connIdle은 연결이 유휴 상태로 유지되는 시간을 뜻하며, 연결 시작부터 계산하는 최대 온라인 시간과는 다릅니다. 예제 값은 서로 다른 시간 측정 대상을 구분하기 위한 것으로 어떤 클라이언트의 기본값을 의미하지 않습니다. 애플리케이션 자체의 시간 제한이 더 짧다면 애플리케이션이 먼저 요청을 끝낼 수 있습니다.

uplinkOnly는 하향 전송이 끝난 뒤 상향 전송만 남아 있는 상태에서 얼마나 더 유지할지 나타냅니다. downlinkOnly는 하향 전송만 남은 상태를 뜻합니다. 업로드나 다운로드 속도 제한이 아닙니다. 한 방향이 끝나자마자 나머지 방향까지 종료하면 아직 받지 못한 응답이 중간에 끊길 수 있고, 너무 오래 유지하면 쓸모없는 연결이 리소스를 계속 차지할 수 있습니다. 이 설정을 테스트할 때는 읽기와 쓰기의 종료 시점을 분명하게 관찰할 수 있는 애플리케이션을 선택하세요. 일반적인 짧은 요청이 성공했다고 해서 장시간 연결이나 한쪽 방향 종료 상황까지 검증된 것은 아닙니다.

사용자 레벨, 시스템 통계, 클라이언트 화면 구분하기

policy.system은 코어의 시스템 수준 정책을 설정합니다. 일부 구현은 이 수준에서 인바운드 또는 아웃바운드 트래픽 계수를 활성화할 수 있으며, 사용자별 계수는 해당 레벨 설정에 속합니다. 계수가 실제로 수집되는지, 클라이언트에서 읽을 수 있는지, 화면의 통계 숫자로 표시되는지는 각각 별개의 조건입니다. 관련 통계 모듈과 조회 기능이 활성화되어 있는지도 확인해야 합니다. 정책 필드를 추가해도 화면에 데이터가 바로 표시된다고 보장할 수 없으며, 통계를 확인하려고 관리 인터페이스를 다른 기기에 공개해서도 안 됩니다.

정책을 조정할 때는 애플리케이션, 인바운드, 아웃바운드, 대상을 고정하고 검증할 레벨 매개변수만 바꿔 비교하세요. 새 연결을 사용하고 오류가 요청 직후, 유휴 상태에서 다시 전송할 때, 일부 응답을 받은 뒤 중 언제 발생했는지 기록한 다음 관련 타이머를 판단하세요. 다른 애플리케이션은 같은 인바운드와 아웃바운드에서 정상인데 하나만 문제가 있다면 해당 애플리케이션의 재시도와 연결 풀 설정도 확인해야 합니다. 차이가 반복해서 확인된 뒤 변경 사항을 유지하고 나머지 실험 설정은 기준값으로 되돌리세요. 여러 시간 제한을 동시에 바꾸면 다음 변경의 원인을 찾기 어렵습니다.

클라이언트 설정과 적용 범위

구독, 개별 공유 링크, 코어 설정 파일 구분하기

데스크톱에서는 v2rayN을 우선 사용할 수 있고, Android에서는 필요한 코어에 따라 v2rayNG 또는 v2flyNG를 선택할 수 있습니다. 설치 경로는 설치 파일 페이지에서 확인하세요. 클라이언트가 관리하는 연결 기록 형식과 코어가 실행하는 설정 파일 형식은 서로 다릅니다. 구독 주소는 보통 여러 연결 정보를 가져오는 데 쓰이고, 개별 공유 링크는 연결 하나를 설명합니다. 전체 코어 설정 파일은 인바운드, 아웃바운드, DNS, 라우팅을 함께 정의할 수 있습니다. 한 종류의 자료를 성공적으로 가져왔다고 해서 다른 종류의 자료를 같은 위치에 붙여 넣을 수 있는 것은 아닙니다.

구독을 이미 사용 중이고 연결 하나만 추가하려는 경우 클라이언트의 연결 기록 관리 및 업데이트 기능을 계속 사용하세요. 이 페이지에서 다루는 루트 객체 필드를 수정하려면 먼저 클라이언트에 해당 설정이 있는지 또는 그 형식의 사용자 지정 설정을 가져올 수 있는지 확인하세요. 가져오기 방식이 확실하지 않다면 구독 가져오기와 공유 형식 안내를 먼저 읽어 보세요. 클라이언트의 내부 파일에는 화면 설정과 연결 기록 인덱스가 들어 있을 수 있습니다. 이를 수정하는 것은 코어 JSON을 변경하는 것과 다릅니다. 클라이언트 데이터 파일을 코어 설정 파일로 취급하면 시작 단계에서 실패하는 경우가 많습니다.

같은 설정 필드라도 트래픽 처리 방식은 다를 수 있습니다

플랫폼 클라이언트 설정 검증 시 우선 확인할 항목
Windows v2rayN 시스템 프록시가 현재 인바운드를 가리키는지, 테스트 애플리케이션이 시스템 설정을 따르는지 확인하세요.
macOS v2rayN 현재 사용 중인 네트워크 서비스에서 해당 프록시를 활성화했는지 확인하고, 비교할 때는 네트워크 서비스를 고정하세요.
Android v2rayNG / v2flyNG 연결 권한과 애플리케이션 범위에 테스트 대상이 포함되는지, 가져온 형식이 코어에 맞는지 확인하세요.
Linux v2rayN 데스크톱 프록시 설정과 개별 프로세스의 프록시 설정이 일치하는지, 터미널 도구에 별도 환경 설정이 있는지 확인하세요.

시스템 프록시는 보통 애플리케이션이 시스템 설정을 읽고 따르는 방식으로 동작합니다. JSON을 저장한다고 동작이 저절로 바뀌지는 않습니다. 데스크톱에서 특정 인바운드를 테스트할 때는 모든 트래픽 처리 방식을 동시에 켜기보다 애플리케이션에서 프록시를 직접 지정하세요. 수동으로 지정한 프록시는 작동하지만 시스템 프록시로 바꾸면 실패하는 경우, 애플리케이션이 시스템 설정을 읽는 방식과 예외 항목, 클라이언트가 지정한 포트를 확인하세요. 이때 아웃바운드 프로토콜까지 바꾸면 확인해야 할 변수가 더 늘어날 뿐입니다.

TUN 모드는 가상 네트워크 인터페이스를 통해 트래픽을 받으며 라우팅 범위, 애플리케이션 범위, 시스템 권한 등의 조건을 따릅니다. SOCKS 인바운드의 프로토콜 이름을 TUN으로 바꾸는 기능이 아니며 모든 애플리케이션 제한을 우회하는 간편한 대안도 아닙니다. Android에서는 시스템 권한과 클라이언트 설정을 함께 확인해야 합니다. 데스크톱에서 작동한 단일 포트 테스트 파일만으로 모바일 기기의 트래픽도 같은 방식으로 처리된다고 볼 수 없습니다. 플랫폼 간에 설정을 옮길 때는 프로토콜에 관련된 부분부터 재사용하고, 각 플랫폼에서 트래픽을 코어로 전달하는 방식은 따로 검증하세요.

실제로 불러온 설정과 코어 확인하기

클라이언트의 그래픽 설정은 연결을 시작하거나 전환할 때 실행용 설정을 생성하는 경우가 많습니다. 실행 폴더의 임시 파일을 직접 편집해도 다음 시작 때 정상적으로 덮어써질 수 있습니다. 변경 사항은 클라이언트에서 지원하는 설정 화면이나 지원되는 별도 설정 파일에 저장하세요. 변경 사항이 현재 인스턴스에 적용됐는지 확인하려면 구분하기 쉬운 로컬 테스트 포트를 바꾸고 연결을 다시 시작한 뒤 애플리케이션에서 새 포트에 직접 접속해 이전 포트와 비교할 수 있습니다. 화면에 '저장됨'이라고 표시되는 것을 코어가 파일을 다시 읽었다는 증거로 보지 마세요.

클라이언트마다 선택한 코어가 같은 확장 필드를 다르게 해석하거나 지원하지 않을 수 있습니다. 설정을 옮길 때는 루트 객체와 프로토콜의 기본 호환성부터 확인하고 선택 기능을 하나씩 복원하세요. 특정 부분을 추가한 뒤에만 오류가 발생하면 기존에 시작 가능했던 설정을 보존하고 실패한 부분의 전체 경로를 기록하세요. 다른 사람에게 도움을 요청할 때는 관련 구조와 오류 주변 내용만 발췌하고 구독 주소, 인증 정보, 불필요한 네트워크 정보는 제거하세요. 설정 파일 전체보다 재현 조건을 제공하는 편이 도움이 됩니다.

설정 검증 및 로그 문제 해결

파싱, 리스닝, 전달 단계별로 확인하기

시작하자마자 종료되면 현재 실행 중인 코어가 파일을 파싱할 수 있는지 먼저 확인하세요. 오류 위치를 기준으로 앞줄의 쉼표, 따옴표, 괄호를 살펴보고 필드 유형과 올바른 가져오기 경로를 통해 불러온 파일인지도 확인하세요. 문법이 올바르다는 것은 객체를 읽을 수 있다는 뜻일 뿐, 필드 값까지 유효하다는 뜻은 아닙니다. 처음으로 명확하게 표시된 오류부터 해결한 뒤 다시 시작하세요. 괄호 하나가 어긋나면 뒤의 여러 줄에서 연쇄 오류가 발생할 수 있습니다. 파생 오류를 하나씩 고치다 보면 원래 올바르던 내용까지 손상될 수 있습니다.

파싱이 끝난 뒤에는 주소 바인딩 실패나 포트 충돌이 로그에 있는지 살펴보고, 고정된 대상에 연결해 요청이 지정한 인바운드로 들어오는지 확인하세요. 아래 예제는 로컬 127.0.0.1:8000에서 접속 가능한 HTTP 테스트 서비스를 사용하며, 첫 번째 장의 기준 설정을 전제로 합니다. 차단 규칙이 포함된 실험 설정은 사용하지 마세요. 첫 번째 명령은 프록시를 우회하고 두 번째 명령은 HTTP 프록시를 명시하며 이번 요청의 프록시 예외를 비웁니다. Windows에서 명령 이름이 셸 별칭과 겹치면 curl.exe라고 입력할 수 있습니다.

요청 비교 · 직접 접속 후 로컬 HTTP 인바운드 이용
curl --noproxy "*" --max-time 5 http://127.0.0.1:8000/
curl --noproxy "" --proxy http://127.0.0.1:10809 --max-time 5 http://127.0.0.1:8000/

두 테스트는 같은 대상과 경로를 사용하고, 두 번째 요청의 프록시 포트는 설정과 일치해야 합니다. 첫 번째는 정상인데 두 번째에서 프록시에 연결할 수 없다고 나오면 리스닝 설정을 확인하세요. 프록시에 연결되지만 오류가 반환되면 예상치 못한 아웃바운드가 선택됐는지 또는 대상이 연결을 거부하는지 살펴보세요. 두 요청이 모두 성공해도 이 로컬 HTTP 경로 하나가 정상이라는 뜻일 뿐, 다른 대상이나 프로토콜, 시스템 프록시 처리까지 정상이라는 의미는 아닙니다. 이후 인바운드, 라우팅, 원격 아웃바운드를 하나씩 추가하고 차이가 발생하기 시작한 단계의 입력과 출력을 확인하세요.

로그 단계로 문제 범위 좁히기

로그는 재현 가능한 동작과 함께 살펴보세요. 동작한 시각을 기록하고 관련 없는 테스트 창을 닫은 다음 새 요청을 보내 같은 시간대의 인바운드, 대상, 아웃바운드, 실패 원인을 확인하세요. 기본 기준 설정은 warning을 사용하므로 전달이 성공해도 자세한 기록이 남지 않을 수 있습니다. 정보가 더 필요하면 일시적으로 상세도를 높이고 클라이언트에서 제공하는 접속 기록이나 로그 확인 기능을 사용하세요. 코어마다 로그 문구는 다를 수 있습니다. 완전히 같은 오류 문구를 찾기보다 연결이 어느 단계에서 발생했는지를 기준으로 판단하세요.

로그에 올바른 아웃바운드가 표시되지만 원격 핸드셰이크가 실패한다면 서버에서 요구하는 전송 및 보안 매개변수를 먼저 확인하고 기기 시간과 로컬 인증서 환경도 살펴보세요. 도메인 요청에서만 문제가 생기면 DNS 장으로 돌아가 어느 구성 요소가 조회하는지 확인하세요. 일정 시간 유휴 상태가 된 뒤에만 연결이 끊긴다면 연결 정책 장의 시간 측정 상황과 비교하세요. 자세한 예제는 v2rayN 로그 및 오류 확인 가이드를 참고하세요. 클라이언트 선택과 연결 실패 확인 순서는 V2Ray 초보자 자주 묻는 질문 10가지에서도 살펴볼 수 있습니다.

테스트 설정을 복구하고 재현 가능한 기록 남기기

검증을 마친 뒤 임시로 설정한 시스템 또는 애플리케이션 프록시를 복구하고 더 이상 사용하지 않는 테스트 인바운드를 중지한 다음 로그 레벨을 평소 값으로 되돌리세요. 최종 파일은 이전 기준 설정과 함께 보관하고 변경한 필드 경로, 검증에 사용한 대상과 인바운드, 예상한 아웃바운드를 기록하세요. 다음에 연결 문제가 생기면 같은 테스트를 다시 실행한 뒤 문제가 있는 항목만 되돌리세요. 전체 설정 파일을 통째로 교체하지 마세요. 필드의 맥락을 더 확인하려면 이 페이지의 목차에서 해당 섹션으로 이동하세요. 용어가 어느 계층을 가리키는지 확실하지 않다면 V2Ray 용어집을 참고하세요.

클라이언트 다운로드