V2Ray 설정 파일 종합 가이드

JSON 구조 개요: 객체, 배열, 참조 관계

데이터 흐름을 먼저 파악한 뒤 필드를 살펴보세요

설정은 노드 매개변수를 나열한 목록이 아니라 요청이 처리되는 경로를 설명합니다. 애플리케이션은 요청을 인바운드에 전달하고, 라우팅 모듈은 요청 속성에 따라 아웃바운드를 선택합니다. 아웃바운드는 대상 서버나 프록시 서버에 연결합니다. DNS는 도메인 조회가 필요한 단계에 주소를 제공하고, 정책은 연결 수명과 통계 동작을 제어합니다. 각 필드를 한 줄씩 추측하기보다 이 흐름을 먼저 파악하면 모듈 간 관계를 더 쉽게 확인할 수 있습니다.

최상위에는 보통 객체 하나가 오고, 중괄호 안에 이름별 모듈이 들어갑니다. inbounds와 outbounds는 배열입니다. 하나의 프로세스가 여러 진입점을 수신하거나 여러 출구를 가질 수 있기 때문입니다. routing, dns, policy는 대개 객체입니다. 배열 요소는 쉼표로 구분하며 마지막 요소 뒤에는 쉼표를 붙이지 않습니다. 불리언 값은 true 또는 false, 포트는 보통 숫자로 씁니다. 프로토콜 이름과 태그는 문자열이지만, 화면에 보이는 모든 문구를 그대로 따옴표로 감싸 입력해서는 안 됩니다.

아래는 로컬에서 구조를 검증하기 위한 완전한 직접 연결 설정입니다. 루프백 주소에서 SOCKS 인바운드만 제공하며 원격 프록시 노드는 포함하지 않습니다. 모든 요청은 로컬 네트워크를 통해 전송됩니다. 코어가 설정을 불러오는지, 애플리케이션이 수신 포트에 연결되는지, 로그에 요청이 기록되는지 확인하는 용도입니다. 원격 프록시 연결이 이루어진 것은 아니며, 직접 연결에 성공했다고 구독 매개변수가 올바르다고 판단할 수도 없습니다. 테스트가 끝나면 계속 사용할 클라이언트 설정을 명확히 선택하세요.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": []
  }
}

태그는 설정 내부의 연결 지점입니다

tag는 내부 식별자이며 표시 이름을 반드시 번역해야 하는 것은 아닙니다. 라우팅의 outboundTag는 대상 아웃바운드의 태그와 대소문자까지 정확히 일치해야 합니다. inboundTag는 규칙을 적용할 인바운드를 지정합니다. 태그는 짧고 명확하게 정하고, 같은 종류의 객체에서는 중복되지 않게 하세요. 아웃바운드 태그 이름을 바꾸면 해당 태그를 참조하는 라우팅도 함께 수정해야 합니다. 그렇지 않으면 파일 구문 검사는 통과해도 실행 중이나 요청 전달 단계에서 대상을 찾지 못할 수 있습니다.

설정 필드가 생략된 경우와 빈 값으로 명시한 경우는 다릅니다. 선택 필드를 생략하면 코어는 대개 해당 구현의 기본 동작을 사용하지만, null, 빈 문자열, 빈 객체를 입력해도 같은 결과가 보장되지는 않습니다. 예제를 복사할 때 필드의 계층을 확인하세요. streamSettings를 프로토콜 계정 객체 안에 넣거나 rules를 최상위에 두면 안 됩니다. JSON 구문 검사를 통과했다는 것은 괄호와 데이터 형식이 기본적으로 유효하다는 뜻일 뿐, 코어가 해당 필드를 인식한다는 의미는 아닙니다.

클라이언트 생성 설정과 수동 설정의 경계

GUI 클라이언트는 노드, 라우팅 템플릿, DNS 옵션을 바탕으로 실행 설정을 다시 생성하는 경우가 많습니다. 임시 파일을 직접 수정하면 노드를 바꾸거나 재시작할 때 덮어써질 수 있습니다. 계속 유지해야 할 옵션은 클라이언트의 해당 설정에서 변경하는 것이 우선입니다. 사용자 지정 설정을 가져오는 절차를 명확히 사용하는 경우에만 전체 JSON을 주된 관리 대상으로 삼으세요. 내보낸 설정에는 서버 주소와 계정 정보가 들어 있을 수 있습니다. 문제 해결 자료를 공유하기 전에는 이런 정보를 지우고 필드 구조와 필요한 오류 맥락만 남기세요.

Xray와 V2Fly는 과거의 설정 구조를 상당 부분 공유하지만, 새 기능과 별칭, 기본값이 항상 같은 것은 아닙니다. 이 페이지의 클래식 구조는 데이터 흐름을 설명하기 위한 것이며 코어 간 호환성을 보장하지 않습니다. ‘알 수 없는 필드’ 또는 ‘알 수 없는 전송 유형’ 오류가 나면 현재 실행 중인 코어를 확인하고 해당 코어의 설정 형식을 살펴보세요. 특히 다른 형식의 필드 이름을 한 파일에 섞지 마세요. 용어집에서 프로토콜, 전송 방식, 보안 계층, 클라이언트를 구분하면 잘못된 계층에서 설정을 찾는 일을 줄일 수 있습니다.

inbounds 인바운드: 수신 주소, 포트, 트래픽 감지

수신 주소가 접속 가능한 범위를 결정합니다

인바운드는 클라이언트가 애플리케이션 요청을 어디서 수신할지 정의합니다. 데스크톱에서 흔히 사용하는 SOCKS 인바운드는 SOCKS 프록시를 지원하는 프로그램의 트래픽을 받고, HTTP 인바운드는 HTTP 프록시 프로토콜로 전달된 요청을 받습니다. 여기서 말하는 프로토콜은 로컬 애플리케이션과 클라이언트 사이의 통신 방식이지, 원격 노드의 VMess나 VLESS가 아닙니다. 애플리케이션에 설정한 프록시 유형은 인바운드와 일치해야 합니다. SOCKS 포트를 HTTP 프록시만 지원하는 설정란에 입력해도 포트 연결만으로 프로토콜이 자동 변환되지는 않습니다.

listen이 127.0.0.1이면 로컬 IPv4 루프백 연결만 수신합니다. 0.0.0.0으로 바꾸면 모든 로컬 IPv4 인터페이스에서 수신한다는 뜻이며, 가정 내 네트워크만 허용한다는 의미는 아닙니다. 기기가 다른 네트워크에도 연결되어 있으면 해당 인터페이스에서도 서비스가 열릴 수 있습니다. LAN에서 공유하려면 시스템 방화벽, 접속 허용 대상, 인바운드 인증을 함께 검토하세요. 클라이언트에서 스위치 하나만 켰다고 접속 범위가 제한되는 것은 아닙니다.

port는 로컬 수신 포트이며 노드 서버 포트와 별개입니다. 로컬 포트를 바꾸면 브라우저, 개발 도구, 프록시를 수동 설정한 다른 애플리케이션도 함께 변경해야 합니다. 포트가 이미 사용 중이라면 다른 클라이언트 인스턴스나 프로그램이 수신 중인지 먼저 확인하세요. 노드를 계속 바꾸는 것으로 해결되지 않습니다. 로그의 바인딩 실패는 로컬 인바운드를 만드는 단계에서 발생한 오류이며 원격 프로토콜 협상까지 진행되지 않은 상태입니다. 이때 서버 UUID, TLS, 라우팅을 바꿔도 포트 충돌은 해결되지 않습니다.

{
  "inbounds": [
    {
      "tag": "socks-in",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": ["http", "tls"],
        "routeOnly": true
      }
    }
  ]
}

SOCKS, UDP, 시스템 프록시는 서로 다른 설정입니다

예제의 udp는 SOCKS 인바운드가 UDP 요청을 처리하도록 허용하지만, 원래 SOCKS를 사용하지 않는 애플리케이션을 자동으로 프록시로 보내지는 않습니다. 이후의 아웃바운드와 원격 서비스가 해당 트래픽을 지원한다는 보장도 없습니다. 전체 경로에는 애플리케이션의 SOCKS UDP 연결 요청, 시스템 네트워크의 전송 허용 여부, 원격 프로토콜 조합의 지원 여부가 모두 영향을 줍니다. 문제를 확인할 때는 먼저 해당 방식을 명시적으로 지원하는 앱으로 테스트하세요. 브라우저에서 웹 페이지가 열린다는 이유로 모든 UDP 사용 사례가 검증된 것은 아닙니다.

시스템 프록시는 보통 해당 설정을 따르는 애플리케이션에만 적용되며 기기의 모든 연결을 가로채지는 않습니다. 시스템 설정을 무시하거나 대상 주소에 직접 연결하는 앱의 요청은 클라이언트가 실행 중이라고 해서 반드시 인바운드에 도달하지 않습니다. 클라이언트의 가상 네트워크 어댑터나 투명 프록시는 별도의 접속 방식이며 라우팅, 권한, DNS 설정도 필요합니다. 이 문서는 명시적 프록시를 기준으로 설명합니다. 실제로 어떤 인바운드를 사용하는지 확인한 뒤 해당 로그에서 요청이 코어에 도달했는지 살펴보세요.

sniffing으로 얻은 정보는 어디에 사용되나요?

sniffing은 인바운드 트래픽의 프로토콜 특성에서 HTTP 호스트명이나 TLS 핸드셰이크의 서버 이름 같은 대상 정보를 추출합니다. 애플리케이션 콘텐츠 전체를 복호화하는 기능도, 모든 연결에서 도메인을 복원하는 기능도 아닙니다. 앱이 대상 IP만 전달하고 트래픽 특성에서도 이름을 찾을 수 없다면 도메인 라우팅에 사용할 정보가 없을 수 있습니다. 따라서 감지를 켜도 라우팅 기준을 일부 보완할 뿐, 올바른 앱 프록시 설정이나 완전한 DNS 설계를 대신하지는 못합니다.

destOverride는 감지를 시도할 유형을 지정하고, routeOnly는 감지 결과를 라우팅에만 사용하고 원래 대상을 유지하려는 동작을 나타냅니다. 이 옵션을 사용하기 전에 현재 코어의 지원 여부를 확인하세요. 클라이언트 화면에 같은 이름의 옵션이 있다고 해서 모든 구현에서 똑같이 동작하는 것은 아닙니다. 도메인 규칙을 진단할 때는 옵션을 켜기 전후의 대상 기록과 아웃바운드를 비교해 이름을 추출하지 못한 것인지, 이름이 규칙과 일치하지 않은 것인지, 앞선 규칙이 먼저 처리한 것인지 구분하세요.

공유 인바운드가 꼭 필요하다면 로컬 전용 기본 설정부터 검증한 다음 수신 범위와 접근 권한을 단계적으로 확장하세요. 수신 주소, 인증, 시스템 프록시, 노드 설정을 한꺼번에 바꾸면 접속 실패가 로컬 접근 차단 때문인지 업스트림 핸드셰이크 실패 때문인지 구분하기 어렵습니다. 설정을 마친 뒤 신뢰할 수 있는 다른 기기에서 허용된 접속 경로를 테스트하고, 열려 있으면 안 되는 인터페이스도 확인하세요. GUI에서 연결하는 방법은 사용 가이드로 돌아가 순서대로 점검할 수 있습니다.

outbounds 아웃바운드: 프로토콜 계정, 기본 출구, 태그

아웃바운드 객체는 다음 연결 지점을 설명합니다

아웃바운드는 코어가 요청을 받은 뒤 어떤 방식으로 다음 연결을 시작할지 결정합니다. freedom은 대상에 직접 연결하고, blackhole은 요청을 차단합니다. VMess, VLESS 같은 프로토콜 아웃바운드는 지정한 프록시 서버로 요청을 보냅니다. 원격 노드 주소는 다음 연결 지점이지 사용자가 최종 접속하려는 웹사이트가 아닙니다. 설정을 살펴볼 때 서버 주소, 사용자 대상, DNS 서버를 각각 기록하세요. 셋 다 도메인과 포트가 포함될 수 있지만 데이터 흐름에서 역할은 서로 다릅니다.

클래식 설정에서는 라우팅 규칙에 일치하지 않은 요청이 보통 outbounds 배열의 첫 번째 아웃바운드로 전달됩니다. 따라서 아웃바운드 순서는 표시 순서에 그치지 않습니다. direct를 첫 번째 항목으로 옮기면 규칙에 일치하지 않은 트래픽의 경로가 바뀝니다. 오해를 줄이려면 기본 출구를 명확히 정하고, 라우팅 마지막에 의도한 대로 동작하는 기본 처리 규칙도 추가하세요. 변경 후에는 새 연결로 검증해야 합니다. 이미 연결된 세션은 설정 변경 즉시 경로가 바뀌지 않을 수 있습니다.

아래는 VLESS 아웃바운드 구조 예제입니다. 서버와 계정 필드만 보여 주므로 전송 보안까지 갖춘 연결 가능한 노드 설정은 아닙니다. example.com은 설명용 주소이고, 모두 0인 UUID는 예시 값입니다. 실제 배포에서는 서버가 제공한 매개변수를 사용해야 합니다. 특히 포트가 443이라고 TLS가 활성화된 것으로 판단해서는 안 됩니다. 포트 번호는 접속 위치를 정할 뿐이며 보안 계층을 설정하는지는 전송 설정과 서버 구성에 따라 달라집니다.

{
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "example.com",
            "port": 443,
            "users": [
              {
                "id": "00000000-0000-0000-0000-000000000000",
                "encryption": "none"
              }
            ]
          }
        ]
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ]
}

계정 필드는 프로토콜 간에 그대로 옮길 수 없습니다

VLESS의 encryption을 none으로 설정하는 것은 해당 프로토콜 계층의 설정을 뜻하며, 연결 전체에 보호 기능이 없다는 의미는 아닙니다. 실제 보안 계층은 streamSettings에서 확인해야 합니다. VMess 계정 설정에는 다른 필드와 협상 방식이 있으므로 두 프로토콜의 사용자 객체를 서로 바꿔 쓸 수 없습니다. 노드 공유 링크의 매개변수는 축약되거나 다른 이름을 사용할 수도 있습니다. 가져온 뒤에는 링크의 쿼리 매개변수를 JSON에 하나씩 붙여 넣기보다 클라이언트가 파악한 프로토콜 유형부터 확인하세요.

계정 정보, 전송 방식, 서버 지원 여부가 모두 맞아야 설정이 제대로 작동합니다. UUID가 올바르더라도 전송 방식이 다르면 계정 인증 전에 연결이 끊길 수 있습니다. 보안 계층이 정상적으로 연결되어도 계정 필드가 틀리면 프록시 요청은 완료되지 않습니다. 로그에 서버 도달이 기록됐다고 계정 인증까지 성공한 것은 아닙니다. 두 프로토콜의 차이를 알아보려면 VMess와 VLESS 차이 비교를 읽고, 해당 노드의 필드를 다시 확인하세요.

직접 연결과 차단도 명확히 태그를 지정해야 합니다

direct, proxy, block은 이 문서에서 사용하는 태그이며 코어가 자동으로 만드는 고정 객체가 아닙니다. 규칙에 outboundTag: "block"을 쓰면 해당 태그를 가진 아웃바운드가 실제로 있어야 합니다. 직접 연결에도 도메인 조회, IPv4·IPv6 선택, 시스템 라우팅, 로컬 방화벽이 영향을 줍니다. 모든 네트워크 설정을 우회하는 것은 아닙니다. 특정 대상에 직접 연결이 실패하더라도 프록시 아웃바운드가 고장 났다고 단정할 수 없습니다. 두 경로를 각각 테스트하세요.

클라이언트가 여러 노드를 지원한다고 해서 실행 설정의 모든 아웃바운드가 같은 방식으로 배치되는 것은 아닙니다. 일부 모드는 현재 노드만 생성하고, 다른 모드는 추가 아웃바운드나 내부 연결을 생성합니다. 노드를 바꾼 뒤 수동 규칙이 더 이상 존재하지 않는 태그를 참조하면 동작하지 않을 수 있습니다. 설정을 장기적으로 관리할 때는 클라이언트에서 고정 라우팅 대상을 지정할 수 있는지 확인하고 최종 적용 설정을 살펴보세요. 한 번 내보낸 파일에서 본 임시 이름에 의존하지 않는 것이 좋습니다. 아웃바운드 태그가 중복되면 참조 대상을 구분하기 어려우므로 피하세요.

구독을 업데이트하면 서버 주소, 포트, 전송 매개변수, 노드 식별자가 바뀔 수 있습니다. 이전 주소에 새 계정 필드만 붙이거나 서로 다른 노드의 보안 계층 매개변수를 섞지 마세요. 먼저 작동하는 클라이언트 설정을 저장한 뒤 업데이트를 가져오고 노드 하나를 따로 테스트하세요. 공유 링크와 네이티브 설정의 관계는 구독 형식과 공유 링크 비교에서 확인할 수 있습니다. 구독 컨테이너, 노드 설명, 최종 실행 설정을 구분하세요.

routing 라우팅: 규칙 순서, 매칭 조건, 기본 처리

위에서부터 확인해 처음 일치하는 규칙을 적용합니다

라우팅 모듈은 코어에 전달된 요청의 속성을 바탕으로 출구를 선택합니다. 아직 코어에 들어오지 않은 애플리케이션 트래픽을 자동으로 가져오지는 않습니다. 클래식 설정의 규칙은 보통 배열 순서대로 확인하며, 처음 조건에 맞는 규칙이 결과를 결정합니다. 앞에 있는 규칙일수록 우선순위가 높습니다. 따라서 먼저 확인할 것은 목록에 ‘그 규칙이 있는지’가 아니라, 요청이 해당 규칙에 도달하기 전에 다른 규칙에 처리되었는지입니다. 광범위한 전체 트래픽 규칙을 뒤에 두지 않으면 세부 규칙이 평가되지 않을 수 있습니다.

하나의 규칙에 서로 다른 범주의 조건이 있으면 보통 모든 조건을 충족해야 합니다. 같은 배열 안의 여러 후보 값은 대개 그중 하나와 일치하면 됩니다. 예를 들어 규칙에 inboundTag와 domain이 함께 있으면 지정된 인바운드에서 들어온 요청 중 도메인 조건도 만족하는 경우를 뜻합니다. 둘 중 하나만 충족하면 된다는 의미가 아닙니다. 서로 독립적인 두 상황을 표현하려면 한 규칙에 필드를 모두 넣기보다 규칙을 나누는 편이 명확하고 로그로 확인하기도 쉽습니다.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["socks-in"],
        "domain": ["full:example.com"],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "ip": [
          "10.0.0.0/8",
          "172.16.0.0/12",
          "192.168.0.0/16",
          "127.0.0.0/8",
          "::1/128",
          "fc00::/7",
          "fe80::/10"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

도메인 규칙과 IP 규칙의 적용 범위

full:example.com은 도메인과 정확히 일치할 때 적용되고, domain:example.com은 해당 도메인과 하위 도메인에 적용됩니다. 일반 문자열과 정규식은 각각 의미가 다르므로 겉보기에 비슷하다고 적용 범위가 같다고 볼 수 없습니다. 특정 사이트 예외를 처리할 때는 정확히 일치하는 규칙부터 검증한 다음 필요에 따라 범위를 넓히세요. 정규식은 JSON 문자열 이스케이프도 필요합니다. 백슬래시 처리가 잘못되면 파일을 정상적으로 불러와도 규칙의 의미가 달라질 수 있습니다.

IP 규칙은 대상 주소나 라우팅 과정에서 얻은 IP 주소와 비교합니다. 브라우저 주소창의 도메인을 IP 주소처럼 직접 비교하는 것은 아닙니다. 앱이 IP만 전달하고 사용 가능한 도메인 정보가 없으면 도메인 규칙이 적용되지 않을 수 있습니다. 반대로 앱이 도메인을 전달했을 때 추가 조회를 하는지는 domainStrategy에 따라 달라집니다. 도메인 목록을 아무리 꼼꼼히 작성해도 인바운드에 요청이 도달하지 않거나 대상 정보가 누락되거나 규칙 순서가 잘못된 문제는 해결되지 않습니다.

IPIfNonMatch가 모든 요청을 먼저 조회한 뒤 규칙별로 검사한다는 뜻은 아닙니다. 도메인 단계에서 범위가 넓은 규칙이 이미 적용되면 기대한 IP 매칭 과정으로 넘어가지 않을 수 있습니다. 예제 끝에 있는 network 규칙은 명시적인 프록시 기본 처리 규칙입니다. 사용할 때는 DNS 조회 정책과의 조합에 주의하세요. 도메인 요청을 조회한 IP 주소로 판별한 뒤 사설 IP 규칙을 적용하려면 규칙을 다시 설계하거나 적절한 조회 정책을 선택해야 합니다. 앞쪽에 사설 IP 목록이 있다는 이유만으로 모든 도메인이 먼저 처리된다고 가정하지 마세요.

리소스 파일과 규칙 결과를 따로 검증하세요

geosite: 및 geoip: 형식은 클라이언트나 코어에서 해당 분류 데이터를 읽을 수 있어야 합니다. 분류 이름의 존재 여부, 데이터 사용 가능 여부, 업데이트 내용은 실제 환경에서 확인해야 합니다. 리소스 누락은 설정 의존성 문제이고 도메인 분류가 예상과 다른 것은 데이터 범위 문제입니다. 두 문제를 혼동하지 마세요. 처음 디버깅할 때는 명확한 도메인과 IP 대역으로 라우팅 로직을 검증한 뒤 분류 목록을 추가하면 미확인 요소를 한꺼번에 다룰 필요가 없습니다.

규칙을 검증할 때는 인바운드 태그, 요청 대상, 전송 유형, 최종 아웃바운드를 먼저 기록한 다음 조건 하나만 변경하세요. 기존 웹 연결, 백그라운드 연결 풀, 앱 캐시가 이전 경로를 계속 사용할 수 있으므로 기존 연결을 닫고 새 요청을 보내는 편이 좋습니다. 규칙이 적용됐다는 것은 코어가 출구를 선택했다는 뜻이지 원격 대상에 도달했다는 뜻은 아닙니다. 올바른 아웃바운드를 선택했는데 요청이 실패한다면 규칙 순서를 계속 바꾸기보다 아웃바운드 핸드셰이크, DNS, 대상 서비스를 확인하세요.

dns 설정: 조회 서버, 적용 범위, 연결 의존성

먼저 도메인을 누가 조회하는지 확인하세요

하나의 요청에서 애플리케이션 자체 DNS, 시스템 리졸버, 코어 내장 DNS, 원격 프록시 환경의 DNS가 각각 사용될 수 있습니다. 최상위 dns를 설정해도 기기의 모든 앱이 수행하는 도메인 조회를 가로채는 것은 아닙니다. 명시적 프록시에서는 앱이 도메인을 프록시에 전달할 수도 있고, 먼저 IP를 조회한 뒤 IP만 전달할 수도 있습니다. 이 두 방식은 라우팅에 제공하는 정보가 다릅니다. 문제를 살펴보기 전에 클라이언트 DNS 화면에 어떤 서버가 입력되었는지만 볼 것이 아니라 앱이 어떤 형태로 대상을 전달하는지 확인하세요.

내장 DNS는 라우팅 정책에 따라 IP가 필요하거나, 일부 아웃바운드가 대상을 조회해야 하거나, 특정 도메인 연결 과정에서 주소가 필요한 경우처럼 코어 내부의 조회를 지원합니다. 실제로 내장 DNS를 사용하는지는 해당 모듈과 옵션에 따라 달라집니다. 시스템 프록시 설정은 보통 시스템 DNS를 바꾸지 않습니다. 웹 페이지는 열리는데 다른 앱에서 문제가 생긴다면 앱마다 다른 조회 경로를 사용하는 것일 수 있습니다. 앱의 프록시 연결과 DNS 조회 경로를 각각 확인하고, 모든 오류를 불안정한 DNS 서버 탓으로 돌리지 마세요.

아래의 부분 설정은 공개 DNS 주소를 사용해 서버 목록과 정적 매핑 구조를 보여 줍니다. hosts의 테스트 이름은 문서 예시용 IP 주소를 가리키며, 매핑 동작을 살펴보기 위한 것일 뿐 실제 웹 서비스를 제공하지 않습니다. 실제로 사용할 때는 이 예시 매핑을 삭제하고 네트워크 접근성, 조회 요구, 개인정보 보호 기준에 따라 DNS 서비스를 선택하세요. 모든 환경에서 예시 주소를 고정으로 사용해야 하는 것은 아니며, 이 설정만으로 현재 네트워크에 적합한 접속 결과가 보장되는 것도 아닙니다.

{
  "dns": {
    "hosts": {
      "full:resolver-test.example": "192.0.2.10"
    },
    "servers": [
      "1.1.1.1",
      "8.8.8.8"
    ],
    "queryStrategy": "UseIP"
  }
}

도메인 범위와 대체 동작을 함께 고려하세요

서버 객체에는 DNS 서버 주소, 우선 적용할 도메인 범위, 예상 결과 등을 지정하는 address, domains, expectIPs 같은 필드가 들어갈 수 있습니다. 도메인 범위는 단순한 접속 규칙이 아닙니다. DNS 요청을 특정 서버에 보내도록 설정했다고 해서 실제 웹사이트 연결도 같은 아웃바운드를 사용하는 것은 아닙니다. DNS 경로와 서비스 연결 경로를 별도로 설정한 뒤 둘 다 의도대로 작동하는지 확인하세요. DNS 서버 그룹을 라우팅의 프록시·직접 연결 그룹과 동일하게 취급하지 마세요.

이 필드를 지원하는 클래식 설정에서 expectIPs는 조회 결과가 예상 범위에 맞는지 판단하는 데 쓰이고, skipFallback 및 관련 대체 옵션은 일치하지 않거나 결과가 예상과 다를 때의 동작에 영향을 줍니다. 대체 처리의 세부 방식은 코어마다 다를 수 있으므로 실제 구현을 확인하세요. 서버 목록을 적힌 순서대로 항상 하나씩 시도한다고 생각하거나, 대체 서버 하나만 설정하면 모든 실패를 해결할 수 있다고 가정하지 마세요. 로그에서 실제 조회와 응답을 확인한 뒤 필요하면 매칭 범위를 조정하세요.

queryStrategy는 내장 DNS에서 조회할 IP 주소 계열을 지정하며, 흔히 사용하는 값으로 UseIP, UseIPv4, UseIPv6가 있습니다. IPv4만 반환하면 일부 IPv6 경로 문제를 피할 수 있지만, 시스템 전체에서 IPv6를 사용하지 않게 하거나 모든 연결 오류를 장기적으로 해결하는 방법은 아닙니다. 시스템의 IPv6 라우팅 자체에 문제가 있다면 먼저 원인을 확인하세요. 앱 내장 리졸버는 여기 설정한 조회 정책을 따르지 않을 수도 있습니다.

DNS 서버까지 연결할 경로도 필요합니다

암호화 DNS를 사용할 때는 조회 내용뿐 아니라 DNS 서버에 어떻게 연결할지, 서버의 도메인을 누가 조회할지도 고려해야 합니다. 프록시 서버 주소에 DNS 조회가 필요한데 DNS 연결도 아직 연결되지 않은 동일한 프록시에 의존하면 시작 단계에서 순환 의존성이 생길 수 있습니다. 설계할 때 필요한 초기 DNS 조회 경로를 명확히 마련하고 현재 코어가 해당 DNS 프로토콜을 지원하는 방식을 확인하세요. 서버 목록에 HTTPS 주소 하나를 입력하는 것만으로 연결 의존성이 해결되는 것은 아닙니다.

hosts는 일부 이름을 명시적으로 매핑할 수 있지만, 웹사이트 주소를 장기간 고정하면 부하 분산, 주소 변경, 인증서 사용 방식과 충돌할 수 있습니다. 문제 해결에 사용할 때는 원래 조회 결과, 매핑 전후의 변화, 설정을 되돌리는 방법을 기록하세요. DNS를 바꾼 뒤에도 시스템, 앱, 코어가 캐시를 보유할 수 있으므로 새 요청으로 검증하고 필요한 경우 클라이언트에서 제공하는 방법으로 캐시를 지우거나 관련 프로세스를 재시작하세요. 페이지 새로고침만으로 새 DNS 조회가 이루어진다고 보장할 수 없습니다.

결과를 비교할 때 ‘열리는지’만 기록하지 말고 조회 시간 초과, 빈 응답, IP 주소 계열에 따른 연결 불가, 이후 연결 실패를 구분하세요. 도메인 조회는 성공했지만 대상 포트에서 연결을 거부하면 문제는 연결 계층에 있습니다. IP로 직접 연결되지만 도메인 요청은 실패한다면 보안 계층에서 요구하는 서버 이름도 확인해야 합니다. 관련 개념은 라우팅 및 DNS 용어에서 더 살펴보고 이 페이지의 검증 절차에 따라 문제 범위를 단계별로 좁혀 보세요.

policy 정책: 사용자 레벨, 시간 제한, 통계

정책은 아웃바운드 선택 규칙이 아닙니다

policy는 연결 처리와 통계 관련 동작을 관리하며 도메인에 따라 프록시 출구를 선택하지 않습니다. 라우팅의 domainStrategy, DNS 조회 정책, 사용자 레벨 정책은 서로 다른 계층입니다. 화면에 모두 ‘정책’이라는 표현이 들어갈 수 있어도 서로 대체할 수 없습니다. 웹사이트를 직접 연결할지 프록시로 보낼지 바꾸려면 라우팅을 확인하세요. 연결이 일정 시간 유휴 상태인 뒤 종료되는 이유를 알아보려면 시간 제한, 앱 동작, 서버 제한을 살펴보면 됩니다.

levels는 레벨 번호를 키로 사용하는 객체입니다. 키는 JSON에서 "0"처럼 문자열로 작성하지만 계정 객체의 level은 보통 숫자로 지정합니다. 레벨은 사용자나 관련 처리 과정을 정책 집합에 연결하는 용도이지 노드 속도 점수나 화면의 노드 우선순위가 아닙니다. 레벨을 명시하지 않으면 많은 설정에서 기본 레벨을 사용하지만, 적용되는 모듈과 기본 동작은 현재 코어를 기준으로 확인하세요.

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 300,
        "uplinkOnly": 2,
        "downlinkOnly": 5,
        "statsUserUplink": false,
        "statsUserDownlink": false
      }
    },
    "system": {
      "statsInboundUplink": false,
      "statsInboundDownlink": false,
      "statsOutboundUplink": false,
      "statsOutboundDownlink": false
    }
  }
}

시간 제한이 적용되는 단계를 구분하세요

handshake는 해당 정책을 지원하는 프로토콜 처리에서 핸드셰이크가 완료될 때까지 기다리는 시간을 제한합니다. 모든 네트워크 연결 단계에 공통으로 적용되는 전체 시간 제한은 아닙니다. 서버 연결, TLS 협상, 프록시 프로토콜 인증, 애플리케이션 요청은 각각 별도의 맥락을 가집니다. 예시 값은 단위와 구조를 설명하기 위한 출발점이지 모든 네트워크에 권장되는 최적값이 아닙니다. 네트워크가 불안정할 때 값을 조금 늘리면 도움이 될 수 있지만, 인증 정보가 틀린 문제는 오래 기다려도 해결되지 않습니다.

connIdle은 데이터 활동이 없는 연결을 유지할 수 있는 시간입니다. 너무 짧게 설정하면 한동안 조용한 세션을 다시 사용할 때 문제가 생길 수 있고, 지나치게 길면 유휴 연결이 더 많은 리소스를 차지할 수 있습니다. 연결 유지 여부는 앱, 원격 서비스, 중간 네트워크 장비의 영향도 받으므로 장시간 연결이 한 번 끊겼다는 이유만으로 이 필드가 적용됐다고 단정하지 마세요. 끊기기 전에 실제 트래픽이 있었는지 확인하고 클라이언트와 서버 로그를 함께 살펴 어느 쪽에서 연결을 종료했는지 판단하세요.

uplinkOnly와 downlinkOnly는 한쪽의 데이터 전송이 끝난 뒤 다른 쪽이 계속 전송할 수 있는 대기 시간을 설정합니다. 여기서 업링크와 다운링크는 연결 처리 방향을 뜻하며 대역폭 상한이 아닙니다. 다운로드가 끝난 뒤 업로드 방향이 닫히거나 앱이 연결을 절반만 종료하면 이 정책이 연결 마무리 과정에 영향을 줄 수 있습니다. 다운로드 속도를 제어하는 데 사용할 수 없으며 ‘속도 향상’을 위해 임의로 0으로 설정해서도 안 됩니다. 연결 설정, 데이터 전송, 연결 종료 중 어느 단계에서 문제가 발생하는지 먼저 확인하세요.

통계 수집과 표시 기능을 구분하세요

사용자 통계를 켜려면 최상위 통계 모듈, 식별 가능한 사용자 정보, 통계를 읽는 인터페이스나 클라이언트 기능도 필요한 경우가 많습니다. statsUserUplink만 true로 바꿔도 트래픽 그래프가 자동으로 나타나지는 않습니다. 프로토콜마다 지원하는 사용자 식별자와 통계 항목도 다를 수 있습니다. 통계가 비어 있다면 먼저 실제 트래픽이 어떤 인바운드와 계정을 통과하는지 확인하고 해당 카운터가 활성화되었는지 살펴보세요. 곧바로 프록시 연결이 실패했다고 의심할 필요는 없습니다.

시스템 수준의 인바운드·아웃바운드 통계는 해당 객체별로 집계하고 사용자 통계는 계정별로 처리합니다. 집계 위치, 재연결, 연결 재사용, 카운터 초기화에 따라 결과가 다를 수 있으므로 모든 시점의 수치가 완전히 일치해야 하는 것은 아닙니다. 클라이언트에 표시되는 속도는 설정에 고정된 값이 아니라 주기적으로 측정한 차이일 수 있습니다. 통계 설정을 바꿀 때 라우팅과 노드까지 함께 수정하면 데이터 수집 차이를 실제 전달 경로 변화로 오해할 수 있습니다.

대부분의 개인 데스크톱 환경에서는 클라이언트가 만든 정책을 그대로 사용하고, 유휴 연결 종료, 핸드셰이크 대기, 통계 요구가 분명할 때만 조정하는 것으로 충분합니다. 변경할 때마다 기존 값, 변경 이유, 검증 조건을 기록하고 원복 방법을 남기세요. 코어 정책은 운영체제 절전, 모바일 네트워크 전환, 원격 시간 제한, 앱 자체의 연결 풀 관리를 제어하지 못합니다. 모든 시간 제한을 크게 늘리면 오류가 늦게 드러날 뿐 실제 연결 품질이 좋아지지 않을 수 있습니다. 근거를 바탕으로 수정하는 편이 일괄 최적화 값을 적용하는 것보다 효과적입니다.

전송 및 보안 계층: streamSettings, TLS, flow

프로토콜, 전송 방식, 보안 계층을 나눠 확인하세요

노드 설정에는 최소한 프록시 프로토콜, 전송 방식, 연결 보안이라는 세 가지 요소가 있습니다. VLESS와 VMess는 프록시 프로토콜을, TCP와 WebSocket은 데이터 전달 방식을, TLS와 REALITY는 관련 보안 기능을 나타냅니다. 화면에서 같은 표에 보인다고 해서 이 이름들을 같은 필드에 입력할 수 있는 것은 아닙니다. 연결이 실패하면 ‘프로토콜 유형’만 반복해서 바꾸기보다 세 요소를 각각 서버 안내와 비교하고 추가 매개변수를 확인하세요.

streamSettings는 보통 아웃바운드의 settings와 같은 계층에 둡니다. 앞 필드는 전송 연결을 설정하는 방법을, 뒤 필드는 프록시 프로토콜 자체의 서버와 계정 정보를 나타냅니다. 아래에는 필드 위치를 보여 주기 위해 클래식 WebSocket 및 TLS 구조의 일부를 제공합니다. 실제 아웃바운드에 병합해야 하며 서버도 해당 서비스를 제공해야 합니다. 네트워크 이름과 전송 설정은 코어 업데이트에 따라 별칭이나 구조가 달라질 수 있으므로 복사하기 전에 현재 실행 중인 구현을 확인하세요.

{
  "streamSettings": {
    "network": "ws",
    "security": "tls",
    "tlsSettings": {
      "serverName": "example.com",
      "allowInsecure": false
    },
    "wsSettings": {
      "path": "/proxy",
      "headers": {
        "Host": "example.com"
      }
    }
  }
}

주소, serverName, Host는 각각 역할이 다릅니다

아웃바운드의 address는 실제로 연결할 다음 홉 주소이고, serverName은 TLS 서버 이름 처리에 사용됩니다. WebSocket의 Host는 HTTP 요청 정보입니다. 올바르게 구성된 서버에서는 세 값이 서로 다를 수 있으므로 모두 도메인처럼 보인다는 이유만으로 바꿔 쓰면 안 됩니다. 서버가 서버 이름이나 HTTP 호스트명에 따라 사이트를 구분한다면 해당 필드가 틀렸을 때 주소와 포트에 연결할 수 있어도 다른 서비스로 접속될 수 있습니다.

path는 대소문자, 앞쪽 슬래시, 쿼리 문자열을 포함해 서버에서 지정한 WebSocket 경로와 일치해야 합니다. HTTP 404나 업그레이드 실패는 계정 오류가 아니라 경로나 리버스 프록시 전달 설정의 불일치를 나타낼 수 있습니다. 먼저 요청이 예상한 서비스에 도달하는지 확인한 다음 프록시 프로토콜 인증을 살펴보세요. TLS 핸드셰이크 오류는 그보다 앞 단계에서 발생합니다. 이때는 HTTP 계층이 시작되지 않았으므로 WebSocket 경로를 계속 바꿔도 대개 결과가 달라지지 않습니다.

allowInsecure는 false로 유지하세요. 인증서 검증 오류가 나면 먼저 시스템 시간, 서버 이름, 인증서 유효 기간, 배포 상태를 확인해야 합니다. 검증을 끄면 중요한 오류가 가려질 뿐, 잘못된 서버에 연결된 문제가 해결되지 않습니다. 일부 환경에서는 추가로 신뢰할 인증서를 설정해야 할 수 있으므로 전체 검증을 건너뛰는 대신 실제 인증서 체인에 맞춰 처리하세요. 문제 해결 기록에는 ‘TLS 실패’처럼 모호한 표현만 남기지 말고 구체적인 오류 유형을 포함하세요.

REALITY와 Vision은 적용 범위가 명확합니다

REALITY는 Xray 생태계의 보안 기능입니다. V2Fly나 임의의 가져오기 도구도 같은 필드를 지원한다고 가정해서는 안 됩니다. 서버가 제공하는 이름, 공개 매개변수, 짧은 식별자, 클라이언트 핑거프린트는 서로 맞아야 합니다. 필드 이름은 현재 코어와 클라이언트가 지원하는 구조를 기준으로 확인하세요. 여러 가이드에서 각기 다른 부분을 복사해 조합하거나 다른 용도의 비밀 정보를 클라이언트에 입력하지 마세요. 작동 원리를 자세히 알아보려면 REALITY 및 XTLS Vision 원리 설명을 참고하세요.

flow는 해당 프로토콜 계정 설정에 있으며, xtls-rprx-vision은 이를 지원하는 서버와 전송 조합에서만 사용할 수 있습니다. 어디서나 적용되는 속도 옵션이 아니며 모든 VLESS 노드에 일괄 추가해서도 안 됩니다. 서버에서 해당 흐름 제어를 설정하지 않았다면 클라이언트에만 값을 입력했을 때 연결이 실패할 수 있습니다. 핑거프린트 필드 역시 특정 보안 계층의 옵션입니다. 올바른 서버 이름을 대신할 수 없으며 핑거프린트 이름만으로 실제 브라우저의 모든 네트워크 동작을 추론할 수도 없습니다.

다중화 Mux도 위에서 설명한 보안 계층과는 다른 개념입니다. 여러 논리 요청을 하나의 전송 연결에서 처리하려는 기능이며, 적합 여부는 프로토콜 지원, 전송 조합, 트래픽 특성에 따라 달라집니다. 기본적으로 켜져 있다고 더 빨라지는 것은 아니며 일부 조합에서는 사용할 수 없습니다. 동시 연결이나 장시간 연결에서만 문제가 생긴다면 다른 매개변수는 유지한 채 비교 테스트를 해 보세요. Mux 끄기, flow 변경, 핑거프린트 교체, TLS 조정을 한 번에 하지 마세요. 어떤 변경이 효과를 냈는지 알 수 없게 됩니다.

노드 가져오기에 성공했다면 필드를 읽었다는 뜻으로만 받아들이고, 모든 전송 기능이 검증됐다고 판단하지 마세요. 클라이언트가 다른 코어의 확장 필드를 보존하지 못하거나 편집 화면에서 저장할 때 설정을 다시 생성할 수도 있습니다. 가져온 뒤 주요 매개변수를 확인하고 새 연결로 테스트하세요. 해당 기능을 지원하는 클라이언트가 필요하다면 다운로드 페이지에서 플랫폼에 맞는 클라이언트를 선택하고 원래 설정도 비교용으로 보관하세요. 문제 해결 중 작동하는 기준 설정을 잃지 않는 것이 중요합니다.

설정 검증: 로드 확인, 로그 분석, 원복

구문, 로드, 실제 요청을 각각 검증하세요

설정 검증은 세 단계로 나뉩니다. 첫째, 괄호, 쉼표, 문자열, 데이터 유형이 유효한지 JSON 구문을 확인합니다. 둘째, 현재 구현이 필드, 프로토콜, 리소스, 참조를 인식하는지 코어 로드를 확인합니다. 셋째, 앱 요청이 올바른 인바운드에 도달하고 라우팅이 예상한 출구를 선택하며 아웃바운드 핸드셰이크가 성공해 대상 응답을 받는지 확인합니다. 앞 단계의 통과가 다음 단계의 검증을 대신하지 않습니다. 부분 예제를 병합한 뒤에는 복사한 부분만 검사하지 말고 전체 파일을 다시 확인하세요.

GUI 클라이언트에서는 클라이언트가 제공하는 설정 검사, 로그, 코어 재시작 기능을 우선 사용하세요. 구체적인 메뉴 위치는 클라이언트마다 다릅니다. 수정하기 전에 원래 설정을 보관하거나 복사본을 내보내고, 수정 후에는 저장이 완료됐는지 확인한 다음 코어를 다시 불러오세요. 클라이언트가 설정을 자동 생성한다면 실행 폴더의 임시 파일만 편집하지 말고 저장된 화면 옵션을 확인해야 합니다. 프로세스가 실행 중이라는 사실만으로 새 설정이 성공적으로 적용된 것은 아닙니다. 기존 프로세스가 계속 서비스 중인지, 새 프로세스가 시작 직후 종료됐는지는 로그에서 확인하세요.

문제를 파악하는 동안 로그 상세 수준을 일시적으로 높일 수 있습니다. 아래의 부분 로그 설정은 대상, 연결 과정, 라우팅 결과를 잠시 살펴보는 데 적합합니다. 상세 로그에는 접속 도메인, 서버 주소, 계정 관련 정보가 포함될 수 있으므로 장기간 수집하거나 그대로 공개하지 마세요. 필요한 증거를 확보한 뒤에는 로그 수준을 낮추고 더 이상 필요 없는 기록을 로컬 파일 관리 방식에 따라 처리하세요. 문제 해결 자료를 공유할 때는 오류 행과 필요한 맥락만 남기면 됩니다.

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

데이터 흐름을 따라 단계별로 확인하세요

첫째, 요청이 인바운드에 도달하는지 확인합니다. 프록시 설정을 따르는 앱에서 새 요청을 보내고 로그에 대상이 표시되는지 살펴보세요. 기록이 없다면 앱 프록시 유형, 수신 주소와 포트, 시스템 프록시 적용 범위를 먼저 확인합니다. 둘째, 라우팅 출구를 확인합니다. 로그에 표시된 아웃바운드가 예상과 다르면 태그 참조, 규칙 순서, 대상 정보를 살펴보세요. 이 단계에서는 계정 정보를 먼저 바꾸지 않는 것이 좋습니다. 셋째, 원격 연결, 보안 계층, 프록시 프로토콜 핸드셰이크를 확인하고 마지막으로 대상 서비스의 응답을 확인합니다.

오류 문구는 발생 단계를 고려해 해석해야 합니다. ‘연결이 거부됨’은 대체로 해당 주소와 포트가 연결을 수락하지 않았다는 뜻이며, 로컬 인바운드일 수도 원격 서버일 수도 있습니다. ‘시간 초과’는 DNS 조회, 연결 설정, 응답 대기 중 어디서든 발생할 수 있고, 인증서 오류는 보안 계층의 맥락을 확인해야 합니다. 마지막 단어만 보고 결론 내리지 마세요. 오류 직전의 대상, 포트, 사용한 아웃바운드를 함께 기록해야 어느 연결 단계에서 발생했는지 판단할 수 있습니다. 앞뒤 맥락을 저장하지 않고 테스트 버튼만 반복해서 눌러도 유용한 정보가 늘지는 않습니다.

원복할 수 있는 최소 변경 절차를 세우세요

매번 독립적인 변수 하나만 바꾸세요. 예를 들어 수신 포트를 수정하고 검증한 다음 도메인 규칙을 조정합니다. 노드 매개변수처럼 여러 항목을 함께 바꿔야 한다면 전체를 하나의 변경 단위로 취급하고 원래 값 전체를 원복용으로 보관하세요. 같은 앱과 대상, 새 연결로 테스트하고 한 번은 웹 브라우저를, 다음 번에는 다른 프로토콜의 도구를 사용하는 식으로 조건을 바꾸지 마세요. 특정 앱에서만 문제가 생긴다면 자체 DNS 조회, 연결 재사용, 프록시 우회 설정도 확인해야 합니다.

지연 시간 테스트는 실제로 시험한 연결 경로만 검증합니다. TCP 연결에 성공했다고 프록시 인증까지 성공한 것은 아닙니다. 실제 요청이 통과해도 대용량 전송이 안정적이라는 뜻은 아니며, 다운로드 속도가 정상이어도 모든 도메인 라우팅이 예상대로 동작한다고 볼 수 없습니다. v2rayN 속도 측정 방법에서 테스트 범위를 확인하세요. 라우팅 문제는 출구, DNS 문제는 조회 결과, 처리량 문제는 지속적인 데이터 전송을 우선 살펴보세요. 하나의 수치로 설정 전체의 상태를 판단하지 마세요.

다른 기기나 코어로 옮길 때 최종 JSON만 복사하고 끝내지 마세요. 시스템 권한, 포트 충돌, 분류 데이터, 인증서 신뢰, 클라이언트 설정 생성 방식이 다를 수 있습니다. 새 환경에서 최소 인바운드와 단일 노드 연결을 먼저 확인한 다음 사용자 지정 DNS, 라우팅, 정책을 단계적으로 복원하세요. 라우터나 보조 라우터는 시스템 수준의 트래픽 전달도 필요합니다. OpenWrt에서 Xray 실행하기에서 배포 방법을 확인하세요. 데스크톱의 명시적 프록시 설정을 투명 프록시 방식으로 그대로 간주해서는 안 됩니다.