V2Ray 설정 파일 가이드

JSON 구조와 설정 출처

먼저 수정하려는 설정 계층 확인하기

V2Ray 설정은 클라이언트 화면에 표시되는 모든 설정을 뜻하지 않습니다. v2rayN은 구독 그룹, 화면 옵션, 라우팅 프리셋을 저장한 뒤 현재 서버와 코어에 맞춰 실행 설정을 생성합니다. v2rayNG와 v2flyNG도 각각 앱 설정을 관리합니다. 수정하기 전에 구독 원본, 클라이언트에 저장된 설정, 코어가 실제로 읽는 JSON을 구분하세요. 같은 노드에 관한 내용이라도 세 설정은 서로 다른 파일에 저장될 수 있습니다.

클라이언트가 임시로 생성한 파일을 직접 수정하면 저장 직후에는 적용되지만 다음 실행 때 원래대로 돌아가는 경우가 많습니다. 대개 코어가 필드를 무시한 것이 아니라 클라이언트가 설정을 다시 생성했기 때문입니다. 먼저 클라이언트에서 제공하는 라우팅, 사용자 지정 설정, 노드 편집 기능을 이용하세요. 전체 JSON을 직접 관리해야 한다면 완전한 설정을 지원하는 입력 경로를 사용하고 별도 사본을 저장하세요. 선택한 코어도 기록해 두고 임시 파일을 유일한 원본으로 취급하지 마세요.

최상위 객체와 중첩 구조

대표적인 최상위 필드는 log, inbounds, outbounds, routing, dns, policy입니다. 인바운드와 아웃바운드는 배열이며, 배열의 각 객체는 수신 대기 지점이나 연결 출구 하나를 나타냅니다. 라우팅 객체의 rules도 배열이며 규칙을 순서대로 처리합니다. 필드 이름뿐 아니라 위치한 계층도 중요합니다. 유효한 필드라도 잘못된 객체에 넣으면 기대한 대로 작동하지 않습니다.

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

이 기본 설정은 로컬 SOCKS 연결을 받아 목적지에 직접 연결하며 원격 프록시 출구는 포함하지 않습니다. 수신 대기와 로컬 연결 경로를 확인하는 용도이며, 요청이 성공했다고 구독 서버가 정상이라고 판단할 수는 없습니다. 포트는 예제에서 명시적으로 선택한 값입니다. 클라이언트가 같은 주소와 포트를 이미 사용 중이면 설정을 하나 더 실행할 때 충돌할 수 있으므로 기존 프로세스를 중지하거나 테스트 사본의 수신 포트와 앱의 프록시 설정을 함께 변경하세요.

구문이 맞아도 의미가 맞는 것은 아닙니다

표준 JSON의 키와 문자열은 큰따옴표로 감싸야 합니다. 배열이나 객체의 마지막 항목 뒤에는 쉼표를 붙일 수 없으며, 코어에 전달할 파일에 설명용 주석을 넣지 마세요. 불리언 값은 true 또는 false로 쓰고 포트는 보통 숫자로 지정합니다. 문자열 안의 백슬래시도 이스케이프해야 하며, Windows 로그 경로를 직접 입력할 때 특히 주의하세요. JSON 구문을 검사할 수 있는 로컬 편집기로 괄호 짝과 따옴표 누락부터 확인하면 좋습니다.

다음으로 참조 관계를 확인하세요. 규칙의 outboundTag에 해당하는 아웃바운드 tag가 있어야 하며, 규칙에서 참조한 인바운드 태그도 실제로 존재해야 합니다. 태그는 이 설정 안에서 사용하는 이름일 뿐, 프록시 기능을 자동으로 만들지는 않습니다. 혼동을 줄이려면 짧고 의미가 분명한 영문 이름을 사용하고 중복되지 않게 하세요. 태그를 바꿀 때는 모든 참조 항목을 검색해 라우팅과 통계 설정도 함께 수정하세요.

설정이 받아들여지는 것과 실제로 적용되는 것은 다릅니다. 코어가 일부 기본값을 허용할 수도 있고, 구현 차이로 특정 필드를 거부할 수도 있습니다. 저장한 뒤에는 편집 창에 오류가 없는지만 보지 말고 실제 시작 로그와 실행 중인 코어를 확인하세요. JSON 포맷 검사는 구문만 확인할 뿐 전송 매개변수, 서버 인증서, 원격 프로토콜의 일치 여부까지 보장하지 않습니다. 이런 문제는 뒤의 장에서 단계별로 검증해야 합니다.

한 번에 한 가지 목적만 바꾸는 것이 좋습니다. 예를 들어 라우팅 순서만 바꾸거나 DNS 리졸버만 교체하세요. 원본 사본을 보관하고 변경 이유와 예상 결과를 간단히 기록해 두세요. 인바운드, 아웃바운드, DNS를 동시에 바꾸면 실패 원인을 찾기 어렵습니다. 설정을 정리하는 목적은 파일을 최대한 짧게 만드는 것이 아니라 각 필드의 소속과 참조 관계, 적용 조건을 명확히 설명할 수 있게 하는 것입니다.

inbounds: 앱 트래픽이 코어로 들어오는 경로

수신 주소, 포트, 프로토콜

인바운드는 앱이 코어로 전달하는 트래픽을 받습니다. 데스크톱 환경에서는 로컬 SOCKS 또는 HTTP 프록시가 가장 흔하며, 앱에서 해당 주소와 포트, 프록시 유형을 지정해야 합니다. listen은 연결을 받을 로컬 주소, port는 수신 대기 포트, protocol은 입구에서 처리할 요청 형식을 지정합니다. 포트 번호가 같더라도 HTTP 클라이언트가 이를 SOCKS 서비스로 임의로 사용할 수는 없습니다.

로컬 기기에서만 사용할 때는 127.0.0.1에서 수신 대기하도록 설정하는 것이 좋습니다. 이 IPv4 루프백 주소는 다른 기기가 컴퓨터의 LAN 주소를 통해 해당 포트에 접속하지 못하게 합니다. 0.0.0.0은 모든 IPv4 인터페이스에서 수신 대기한다는 뜻으로, 접근 범위가 훨씬 넓어집니다. 그렇다고 자동으로 안전해지는 것은 아닙니다. IPv6 수신은 주소와 방화벽 규칙을 별도로 확인해야 하며, 모든 인터페이스 주소로 바꾸면 모든 네트워크 스택이 올바르게 처리된다고 가정해서는 안 됩니다.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    },
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ]
}

두 입구를 설정하면 앱마다 지원하는 프록시 프로토콜을 선택할 수 있습니다. udp: true는 SOCKS 인바운드에서 해당 UDP 요청을 처리하도록 허용하지만, 앱도 SOCKS의 UDP 방식을 지원해야 하고 아웃바운드와 원격 구간까지 전체 경로가 이를 지원해야 합니다. 모든 시스템 UDP 트래픽을 자동으로 인바운드에 끌어들이거나, 시스템 프록시를 무시하는 프로그램의 동작을 바꾸지는 않습니다. 인바운드의 기능과 시스템 트래픽을 가로채는 기능은 별개의 문제입니다.

스니핑과 목적지 주소의 관계

스니핑은 일부 연결에서 프로토콜 정보를 읽어 도메인 등의 정보를 추출합니다. HTTP Host 헤더와 TLS 핸드셰이크의 서버 이름이 대표적인 정보입니다. 앱이 처음에 IP 주소를 코어에 전달했더라도 이를 통해 라우팅에 사용할 도메인 정보를 얻을 수 있습니다. 다만 모든 트래픽에 확인 가능한 도메인이 포함되는 것은 아니며 스니핑은 전체 내용을 복호화하지 않습니다. 스니핑을 켜는 것으로 올바른 DNS 설정을 대신할 수 없고 모든 앱의 도메인을 알아낼 수 있다고 보장할 수도 없습니다.

{
  "sniffing": {
    "enabled": true,
    "destOverride": ["http", "tls"],
    "routeOnly": true
  }
}

이 설정은 개별 인바운드 객체 안에 넣어야 합니다. routeOnly는 이를 지원하는 구현에서 스니핑 결과를 연결 목적지 자체를 바꾸지 않고 라우팅에만 사용하도록 합니다. 사용하기 전에 선택한 코어가 지원하는지 확인하세요. 필드가 거부되면 비슷한 이름을 계속 추측하지 마세요. 스니핑을 뺀 기본 설정으로 돌아가 인바운드부터 확인한 뒤, 해당 코어의 필드 정의에 따라 하나씩 추가해 미지원 필드와 원격 연결 실패를 구분하세요.

LAN 공유와 시스템 트래픽 처리

같은 네트워크의 다른 기기에서 컴퓨터의 프록시를 사용하려면 수신 주소를 바꾸는 것 외에도 컴퓨터의 실제 LAN IP, 방화벽, 네트워크 격리, 인증 설정을 확인해야 합니다. 프록시 포트를 공인 인터넷에 노출하거나 신뢰할 수 없는 네트워크에서 인증 없는 연결을 열지 마세요. 공유할 때 다른 기기에는 해당 컴퓨터의 LAN 주소를 입력해야 합니다. 각 기기의 루프백 주소는 그 기기 자신을 가리킵니다.

시스템 프록시는 해당 설정을 따르는 앱에 프록시 사용을 알릴 뿐, 모든 앱의 네트워크 동작을 바꾸지는 않습니다. TUN은 가상 네트워크 인터페이스와 라우팅 테이블, 권한, DNS 처리까지 포함하므로 보통 클라이언트의 전용 기능으로 설정해야 합니다. 한 코어의 TUN 필드를 다른 JSON 구조에 그대로 넣지 마세요. 시스템 프록시를 사용할 수 있는데 특정 앱만 직접 연결한다면, 먼저 해당 앱이 시스템 프록시를 지원하는지 확인한 다음 TUN이 필요한지 검토하세요.

인바운드 문제를 점검할 때는 먼저 클라이언트가 실행 중인지 확인하고, 다음으로 로그에 주소 사용 중 오류가 있는지 살펴본 뒤 앱에서 선택한 프록시 유형을 확인하세요. 브라우저는 HTTP 입구로 잘 연결되는데 다른 프로그램은 SOCKS 연결에 실패한다면 클라이언트를 바로 재설치하기보다 해당 프로그램의 인증, 도메인 확인 방식, UDP 요구 사항을 각각 점검하세요. LAN 연결에 관한 자세한 내용은 LAN 연결 허용 및 프록시 공유를 참고하세요.

outbounds: 출구, 프로토콜, 전송 계층

아웃바운드 태그와 기본 출구

아웃바운드는 코어가 받은 연결을 목적지로 전달합니다. 목적지에 직접 연결하거나 트래픽을 원격 프록시 서버로 전달할 수 있으며, 규칙에 따라 요청을 거부할 수도 있습니다. 대표적으로 freedom은 직접 연결, blackhole은 트래픽 폐기를 뜻합니다. VMess, VLESS, Trojan 등은 원격 서버와 통신할 프로토콜을 나타냅니다. 프로토콜 이름만으로 서버가 생기는 것은 아니므로 실제로 사용할 권한이 있는 주소, 포트, 인증 정보가 필요합니다.

다른 출구 선택 기능이 개입하지 않는 경우 라우팅 규칙에 일치하지 않은 트래픽은 대개 아웃바운드 배열의 첫 번째 항목을 사용합니다. 따라서 배열 순서를 바꾸면 파일 정리뿐 아니라 기본 연결 경로도 달라질 수 있습니다. 기본 아웃바운드를 명확히 기록하고 라우팅 항목에 이해하기 쉬운 기본 규칙을 두세요. 태그가 proxy인 항목을 정의해도 트래픽이 자동으로 프록시를 통과하지 않습니다. 태그는 참조용 이름일 뿐이며 실제 동작은 객체의 프로토콜과 설정에 따라 결정됩니다.

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

이 아웃바운드는 로컬 규칙 테스트에 사용할 수 있습니다. 일반 요청은 직접 연결하고 차단 규칙에 일치하는 요청은 폐기합니다. 여기에는 프록시 서버도 proxy라는 출구도 없습니다. 다른 가이드의 라우팅 설정을 읽을 때는 먼저 참조하는 태그가 정의되어 있는지 확인하세요. 존재하지 않는 태그를 가리키는 규칙을 그대로 복사하면 설정 검사가 실패할 수 있으며 클라이언트가 빠진 서버 객체를 자동으로 보완해 주지는 않습니다.

프로토콜 설정과 전송 설정을 따로 확인하기

원격 아웃바운드는 보통 프로토콜 매개변수와 전송 매개변수로 나뉩니다. 서버 주소, 포트, 사용자 ID, 비밀번호 같은 프로토콜 매개변수는 해당 settings 구조에 들어가며, 전송과 보안 협상은 대개 streamSettings로 지정합니다. 두 계층 모두 서버 측 설정과 일치해야 합니다. 주소와 인증 정보를 확인해도 전송 방식, TLS, 경로를 확인하지 않으면 포트 연결은 되지만 프로토콜 핸드셰이크가 완료되지 않을 수 있습니다.

서버 주소, TLS 서버 이름, 일부 전송 방식의 Host 값이 항상 같은 것은 아닙니다. 주소는 처음 연결할 곳을 정하고, 서버 이름은 TLS 인증 및 인증서 검증에 사용됩니다. Host나 경로는 리버스 프록시의 요청 분배에 사용될 수도 있습니다. 여러 항목을 같은 값으로 맞춰 보이게 하려고 전부 바꾸지 마세요. 구독을 가져온 경우에는 제공된 전체 매개변수를 우선 유지하고, 로그를 바탕으로 필드 누락이나 호환성 문제를 확인하세요.

검증을 느슨하게 해 문제를 덮지 마세요

인증서 오류가 발생하면 먼저 시스템 시간을 맞춘 다음 서버 이름, 인증서 유효 기간, 인증서 체인을 확인하세요. 인증서 검증을 건너뛰면 연결의 신뢰 조건이 달라지므로 일반적인 해결 방법으로 사용해서는 안 됩니다. 직접 연결은 되는데 원격 프록시 핸드셰이크가 실패한다면 인바운드와 일부 로컬 네트워크는 작동하는 것입니다. 이때는 원격 프로토콜과 전송 설정에 집중하고 모든 로컬 포트를 다시 조정하거나 라우팅 테이블 전체를 지울 필요는 없습니다.

일부 프로토콜은 추가 핸드셰이크 필드나 전용 보안 설정을 요구하며, 지원 필드는 코어 구현마다 다릅니다. 클라이언트에 프로토콜 이름이 표시된다고 해서 모든 코어가 같은 매개변수를 지원한다고 볼 수는 없습니다. 가져온 뒤 프로토콜 미지원, 알 수 없는 보안 유형 등의 오류가 발생하면 실행 중인 코어와 노드 요구 사항이 맞는지 먼저 확인하세요. 코어를 바꾼 뒤에는 클라이언트가 생성한 전송 필드도 달라졌는지 다시 확인해야 합니다.

다중화, 연결 유지, 기타 최적화 옵션을 많이 켠다고 항상 좋은 것은 아닙니다. 이런 설정은 연결 구성 방식을 바꾸므로 장시간 연결, 서버 자원, 중간 네트워크 장비의 동작에 영향을 줄 수 있습니다. 기본 연결이 성립하기 전에는 제공자가 권장하는 설정을 사용하세요. 문제가 명확하고 재현 가능한 테스트가 있으며 서버도 지원하는 경우에만 조정하세요. 짧은 요청 한 번이 성공했다고 장시간 전송, UDP, 모든 목적지가 정상이라는 뜻은 아닙니다.

아웃바운드 문제는 주소 연결, 전송 핸드셰이크, 프로토콜 인증, 목적지 접속의 네 단계로 나눠 점검하세요. 한 단계가 성공해도 이후 단계 점검을 생략할 수는 없습니다. 노드 전체가 시간 초과되는 경우의 점검 순서는 시스템 시간·포트·전송 계층 점검을 참고하세요. 인증 정보가 포함된 로그나 설정을 공유할 때는 사용자 ID, 비밀번호, 전체 구독 주소를 삭제하고 프로토콜 유형과 오류 종류만 남기세요.

routing: 일치 순서와 트래픽 분기 범위

연결 하나를 따라 규칙 적용 확인하기

라우팅은 단순한 도메인 목록이 아닙니다. 연결의 목적지 주소, 인바운드 태그, 포트 등의 정보를 바탕으로 아웃바운드를 선택하는 과정입니다. 일반적인 필드 규칙은 type: "field"를 사용합니다. 규칙은 순서대로 검사하며 먼저 일치한 규칙이 출구를 결정하므로 구체적인 예외를 앞쪽에 두는 것이 보통입니다. 포괄적인 규칙이 앞에 있으면 뒤의 세부 규칙은 실행되지 않을 수 있습니다. 규칙이 있는데도 작동하지 않는 것처럼 보이는 흔한 이유입니다.

하나의 규칙에 서로 다른 조건 필드를 함께 지정하면 보통 모든 조건을 만족해야 합니다. 도메인이나 IP 배열의 여러 항목은 대개 하나만 일치해도 됩니다. 예를 들어 inboundTag와 domain을 함께 쓰면 지정한 인바운드에서 지정한 도메인을 대상으로 합니다. 두 가지 독립적인 조건을 뜻하지는 않습니다. “이 인바운드의 모든 트래픽은 한 출구로 보내거나, 이 도메인들은 다른 출구로 보낸다”처럼 표현하려면 조건별로 규칙을 나누세요.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "direct"
      }
    ]
  }
}

이 설정은 이미 정의된 direct와 block 아웃바운드, 그리고 실행 환경에서 해당 지리 데이터에 접근할 수 있는 상태를 전제로 합니다. 첫 번째 규칙은 정확히 일치하는 도메인만 차단하고, 두 번째 규칙은 사설 주소를 처리하며, 마지막 규칙은 나머지 TCP와 UDP를 직접 연결합니다. 순서를 보여 주기 위한 예제이지 모든 환경에 맞는 운영 정책은 아닙니다. 실제 프록시 출구를 추가하려면 먼저 아웃바운드를 정의한 뒤 필요한 트래픽 규칙이 해당 태그를 가리키도록 설정하세요.

도메인 규칙과 IP 규칙은 서로 다른 조건입니다

full:example.com은 도메인 전체가 정확히 일치할 때 사용합니다. domain:example.com은 대개 해당 도메인과 하위 도메인을 대상으로 합니다. 접두사가 없는 문자열, 정규식, 분류 데이터는 각각 매칭 방식이 다르므로 혼동하지 마세요. 기본 도메인을 차단해도 별도의 리소스 도메인까지 차단되는 것은 아닙니다. 사이트 로딩 실패는 여러 요청 중 특정 리소스 하나가 규칙에 걸려서 발생할 수도 있습니다. 점검할 때는 주소창만 보지 말고 실제 요청 도메인을 확인하세요.

geosite:와 geoip:는 데이터셋을 참조하며, 코어에 실시간 인터넷 조회 기능이 내장되어 있다는 뜻은 아닙니다. 분류가 존재하는지, 어떤 항목을 포함하는지, 데이터 파일을 불러올 수 있는지는 현재 데이터 리소스에 따라 달라집니다. 분류나 데이터 파일을 찾을 수 없다는 로그가 표시되면 먼저 리소스와 경로를 수정하세요. 태그 이름을 계속 바꾸지 마세요. 데이터가 갱신되면 규칙 순서는 그대로여도 매칭 범위가 달라질 수 있습니다.

{
  "type": "field",
  "domain": ["geosite:category-ads-all"],
  "outboundTag": "block"
}

이 규칙은 데이터 파일에 해당 분류가 있을 때만 사용할 수 있습니다. 추가하기 전에 기존 규칙에 더 넓은 도메인 조건이나 전체 트래픽 조건이 있는지 확인하세요. 규칙을 중복해서 넣어도 효과가 커지지 않으며 오히려 해석이 어려워집니다. 순서만 시험하려면 먼저 앞에서 사용한 정확히 일치하는 예제 도메인을 활용해 로그의 대상 태그가 바뀌는지 확인한 다음 외부 데이터가 필요한 분류 규칙을 추가하세요.

domainStrategy: 매칭에 필요한 DNS 조회 시점

AsIs는 연결에 이미 포함된 주소를 기준으로 매칭합니다. IPIfNonMatch는 도메인 매칭에 실패한 경우 주소를 조회한 뒤 IP 규칙을 확인할 수 있습니다. IPOnDemand는 규칙 판단에 IP가 필요할 때 더 일찍 조회합니다. 이 값은 라우팅 판단 과정에서 DNS를 조회하는 시점에 관한 것으로, 앱의 DNS, 시스템 DNS, 아웃바운드 연결의 주소 계열 설정 전체를 뜻하지는 않습니다. 더 적극적인 조회 정책은 DNS 요청과 대기 시간을 늘릴 수 있습니다.

앱이 IP 주소를 전달했고 사용할 수 있는 도메인 정보가 없다면 도메인 규칙이 일치하지 않을 수 있습니다. 앱이 도메인을 전달했더라도 정책이 DNS 조회를 실행하지 않으면 IP 규칙에 필요한 판단 근거가 없을 수 있습니다. 먼저 인바운드가 받은 목적지 유형을 확인한 다음 스니핑을 사용할지, 조회 정책을 바꿀지 결정하세요. 모든 미일치를 규칙 형식 탓으로 돌리지 마세요. 매칭 입력이 없으면 도메인 조건을 아무리 정확히 작성해도 목적지 이름을 알아낼 수 없습니다.

정리할 때는 로컬 서비스와 필요한 예외를 앞에 두고, 출구를 명확히 지정해야 하는 규칙을 가운데에 배치한 뒤 기본 동작을 마지막에 명시하는 방식이 유용합니다. 사설 네트워크 규칙은 대상 환경을 고려해야 하며 특수 용도의 모든 주소를 일반 공용 인터넷 주소로 취급해서는 안 됩니다. 검증할 때는 규칙과 일치해야 하는 대상뿐 아니라 일치하지 않아야 하는 대상도 테스트해야 범위가 지나치게 넓은지 알 수 있습니다. 트래픽 분기 관련 추가 문제는 문제 해결에서 확인하세요.

dns: 조회 출처, 요청 경로, 연결 주소

먼저 세 가지 DNS 조회 방식 구분하기

DNS를 설정하기 전에 앱 자체 조회, 코어 내장 DNS 조회, 시스템 DNS 조회를 구분하세요. 앱이 먼저 IP를 얻어 프록시에 전달할 수도 있고, 도메인을 코어에 넘겨 이후 단계에서 조회할 수도 있습니다. 브라우저가 별도의 보안 DNS를 사용할 수도 있습니다. 코어의 dns 객체를 수정해도 모든 앱과 시스템의 조회 설정이 자동으로 바뀌지는 않습니다. 조회가 어디서 시작되는지 모르면 설정이 실제로 어느 경로에 영향을 주는지 판단하기 어렵습니다.

코어 내장 DNS는 라우팅의 IP 매칭에 사용하거나 일부 아웃바운드의 조회 정책에서 호출할 수 있습니다. 선언하기만 하면 시스템 DNS 서비스가 자동으로 시작되는 것은 아닙니다. 시스템이나 다른 기기가 코어에 DNS 요청을 보내게 하려면 별도의 인바운드와 전달 구조가 필요합니다. 구체적인 기능과 필드는 사용하는 코어를 기준으로 확인하세요. 클라이언트에서 TUN을 켠 뒤 이루어지는 DNS 처리는 또 다른 계층이므로 이 객체만 보고 시스템 조회가 가로채지고 있다고 판단할 수 없습니다.

{
  "dns": {
    "queryStrategy": "UseIPv4",
    "servers": [
      "1.1.1.1",
      {
        "address": "8.8.8.8",
        "port": 53,
        "domains": ["domain:example.org"]
      }
    ]
  }
}

다음은 내장 리졸버 설정의 일부 예제입니다. 공용 리졸버 주소는 구조를 설명하기 위한 것으로 실제 연결 가능 여부는 네트워크 환경에 따라 다릅니다. domains는 지정한 도메인의 리졸버 선택에 영향을 주며 해당 도메인으로 가는 프록시 경로를 설정하지는 않습니다. 대체 조회 동작도 확인해야 합니다. 다른 서버를 조회에 사용할지는 우선 매칭, 실패 상태, 폴백 설정에 따라 달라지므로 도메인 선택 조건만으로 조회가 엄격히 분리된다고 볼 수 없습니다.

DNS 조회 정책과 아웃바운드 정책은 별도로 설정하기

queryStrategy는 IPv4만 요청하거나 지원되는 방식으로 IPv4와 IPv6를 처리하는 등 내장 DNS 요청의 주소 계열에 영향을 줍니다. 라우팅의 domainStrategy와는 다른 필드이며 일부 아웃바운드에 설정하는 도메인 정책과도 다릅니다. IPv6 접속 문제를 점검할 때는 조회 결과, 시스템의 IPv6 경로 사용 가능 여부, 선택한 아웃바운드의 주소 사용 방식까지 함께 확인하세요. 설정 하나만 끄는 것으로 해결된다고 가정하지 마세요.

네트워크의 IPv6 경로가 불안정한데 연결할 수 없는 IPv6 주소를 우선 시도하면 요청이 대기한 뒤에야 성공할 수 있습니다. 반대로 IPv4를 무작정 제한하면 IPv6 전용 리소스에 영향을 줄 수 있습니다. 먼저 실패한 대상의 조회 결과와 연결 오류를 확인한 뒤 주소 계열 정책을 결정하세요. 듀얼 스택 웹사이트 하나가 열린다고 모든 네트워크 조건이 정상이라는 뜻은 아닙니다. 대상마다 DNS 기록과 연결 폴백, 앱 캐시가 다를 수 있습니다.

조회 경로도 연결 가능한지 확인하기

리졸버를 선택할 때는 주소뿐 아니라 조회 요청이 리졸버까지 어떻게 전달되는지도 확인해야 합니다. 일반 UDP 조회, 암호화 DNS 요청, 로컬 시스템 리졸버 호출은 서로 다른 경로를 사용할 수 있습니다. 일부 로컬 조회 방식은 일반적인 라우팅 처리를 우회할 수 있습니다. 프로토콜 이름만 보고 요청이 지정한 프록시를 통과한다고 단정하지 마세요. 코어가 지원하는 DNS 전송 방식과 로그, 네트워크 환경을 함께 확인해 예상 경로와 실제 경로를 구분하세요.

도메인 형식의 암호화 DNS 주소를 사용할 때는 초기 연결 의존성도 고려해야 합니다. 리졸버에 접속하려면 먼저 리졸버 도메인을 조회해야 하는데, 그 조회마저 아직 사용할 수 없는 같은 리졸버에 전적으로 의존하면 순환 문제가 생길 수 있습니다. 프록시 서버 주소도 조회가 필요하고 해당 요청을 아직 연결되지 않은 프록시를 통해 보내도록 설정하면 의존성에 갇힐 수 있습니다. 시작 단계에서 사용할 수 있는 명확하고 연결 가능한 조회 경로를 마련하세요.

캐시 때문에 DNS 설정 변경이 바로 적용되지 않는 것처럼 보일 수 있습니다. 시스템, 브라우저, 앱, 코어가 모두 조회 결과를 저장할 수 있어 한 계층만 다시 시작해도 다른 계층의 캐시는 남아 있을 수 있습니다. 검증할 때 기존 연결을 닫고 필요한 앱을 다시 시작한 뒤 기대하는 결과를 알고 있는 대상을 사용하세요. 여러 리졸버를 연달아 바꾸고 웹페이지를 한 번 새로 고친 결과만으로 판단하지 마세요. 기존 연결은 DNS를 다시 조회하지 않을 수 있어 새 설정의 사용 여부를 확인할 수 없습니다.

도메인으로는 접속할 수 없지만 목적지 IP에 직접 연결할 수 있다면 DNS 조회나 도메인 관련 핸드셰이크가 문제일 가능성이 큽니다. 다만 TLS 인증서는 도메인에 의존하므로 IP로 직접 접속하는 테스트가 동일한 조건은 아닐 수 있습니다. DNS 요청이 응답하는지, 응답으로 받은 주소에 연결할 수 있는지, 프로토콜 핸드셰이크가 성공하는지 각각 확인하세요. 한 번에 조회 출처나 주소 계열 중 하나만 바꾸고 변경 전후 로그를 보관해야 여러 변경을 하나의 원인으로 혼동하지 않습니다.

policy: 사용자 레벨, 시간 초과, 통계 범위

사용자 레벨에 연결되는 정책

policy는 연결 처리 정책과 일부 통계 옵션을 설정합니다. 도메인별 트래픽 분기나 원격 서버의 인증 허용 여부는 담당하지 않습니다. 일반적인 구조에는 levels와 system이 있습니다. 전자는 사용자 레벨별 시간 초과와 통계 옵션을 설정하고, 후자는 시스템 수준의 인바운드 또는 아웃바운드 통계에 사용됩니다. 레벨은 설정을 연결하기 위한 값이지 유료 등급이나 속도 등급이 아닙니다. 숫자가 높다고 연결이 빨라지지 않습니다.

일부 프로토콜의 사용자 객체에는 level을 설정할 수 있으며, 값은 levels의 동일한 숫자 문자열 항목과 연결됩니다. 명시적으로 지정하지 않았다면 해당 프로토콜과 코어의 기본 레벨을 기준으로 판단하세요. 사용자가 참조하지 않는 레벨을 정의해도 모든 연결에 자동 적용되지는 않습니다. 정책이 적용되는지 점검하려면 설정에 객체가 있다는 사실만으로 판단하지 말고 연결에 사용된 사용자와 레벨을 먼저 확인하세요.

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

시간 값의 단위는 초입니다. 설명을 위한 정책 예시이며 모든 용도에 적합한 최적 설정은 아닙니다. handshake는 해당 핸드셰이크 단계의 제한 시간이고, connIdle은 유휴 연결과 관련됩니다. 업로드와 다운로드의 단방향 대기 항목은 한쪽 전송이 끝난 뒤 연결을 유지하는 시간을 나타냅니다. 전체 다운로드 시간을 제한하거나 앱 자체의 재시도 및 시간 초과 설정을 대신하지는 않습니다. 현재 연결에 어떤 필드가 적용되는지는 프로토콜 구현을 기준으로 확인하세요.

시간 초과 설정으로 프로토콜 불일치를 해결할 수는 없습니다

핸드셰이크 실패에는 여러 원인이 있습니다. 인증 정보 불일치, 전송 방식 오류, 인증서 문제, 목적지 연결 불가가 모두 연결 종료로 나타날 수 있습니다. 핸드셰이크 시간을 늘리면 원래 느리지만 유효한 협상에 더 많은 시간을 줄 수는 있어도 잘못된 프로토콜을 올바르게 바꾸지는 못합니다. 로그에 인증 거부나 필드 미지원이 명확히 표시된다면 시간을 늘려도 실패가 늦게 발생할 뿐입니다. 먼저 확실한 오류를 해결한 뒤 대기 시간을 조정하세요.

유휴 연결 회수 설정도 앱 동작에 맞춰야 합니다. 메신저, 원격 세션, 스트리밍 응답, 간헐적으로 데이터를 보내는 연결은 필요한 유휴 시간이 서로 다릅니다. 임계값이 너무 낮으면 백그라운드 연결이 반복해서 생성될 수 있고, 너무 높으면 자원을 더 오래 점유할 수 있습니다. 조정하기 전에 연결 끊김이 실제로 유휴 회수 때문에 발생했는지 확인하세요. 네트워크 전환, 절전 정책, 서버의 연결 종료, 중간 장비의 시간 초과 때문일 수도 있습니다.

통계 옵션을 켜도 통계 화면이 생기지는 않습니다

통계 관련 불리언 옵션을 켠다고 그래프 보고서가 자동으로 만들어지지는 않습니다. 코어에서 사용자 통계를 보려면 보통 통계 모듈과 식별 가능한 사용자, 조회 인터페이스 등이 함께 필요합니다. 클라이언트에 표시되는 트래픽은 별도의 방식으로 수집될 수도 있습니다. 코어의 사용자 통계, 클라이언트 프로세스 트래픽, 네트워크 인터페이스 전체 트래픽을 같은 수치로 취급하면 안 됩니다. 전달 방식, 프로토콜 오버헤드, 집계 범위, 재시작 후의 집계 주기에 따라 결과가 다를 수 있습니다.

트래픽 표시를 위해 API 인바운드나 제어 인터페이스를 직접 추가할 때는 특히 주의하세요. 제어 인터페이스의 접근 범위를 신뢰할 수 있는 영역으로 제한하고, LAN에서 편하게 조회하려고 모든 주소에서 수신하도록 열지 마세요. 일반 사용자는 대개 클라이언트에 내장된 로그와 상태 기능으로 충분하며 별도의 조회 인터페이스를 만들 필요가 없습니다. 이 페이지의 예제에서 통계를 끈 것은 연결과 규칙에 집중하기 위해서이며 모든 환경에서 해당 기능을 반드시 꺼야 한다는 뜻은 아닙니다.

Android에서 앱이 백그라운드로 들어간 뒤 연결이 끊기는 경우는 코어의 유휴 정책보다 시스템의 백그라운드 제한이 원인일 수 있습니다. v2rayNG의 VpnService 권한, 백그라운드 실행 권한, 제조사별 배터리 절약 설정을 각각 확인하세요. 자세한 방법은 VpnService, 배터리 최적화 예외, 앱별 프록시를 참고하세요. 시스템 권한을 올바르게 설정하는 대신 지나치게 큰 시간 초과 값을 사용하지 마세요.

정책을 조정할 때는 재현 조건을 명확히 하세요. 사용한 앱, 연결이 유휴 상태였던 시간, 네트워크 전환 여부, 데이터가 계속 전송된 방향을 기록한 뒤 조정 전후의 차이를 관찰합니다. 이런 조건이 없으면 설정 변경 효과와 일시적인 환경 복구를 구분하기 어렵습니다. 일반적인 웹 탐색과 구독 사용은 클라이언트가 생성한 적절한 기본값을 유지하는 편이 관리하기 쉽습니다. 연결 정확성에 직접 영향을 주는 인바운드, 아웃바운드, 라우팅 문제부터 해결하세요.

클라이언트 생성 설정과 코어별 차이

같은 화면 옵션도 JSON은 서로 다를 수 있습니다

v2rayN은 데스크톱 환경을 대상으로 하며 시스템 프록시, TUN, 라우팅 프리셋, 코어 선택에 따라 실행 방식이 달라집니다. v2rayNG는 주로 Xray 코어를 사용하며, v2flyNG는 V2Fly 코어를 사용하는 Android 대안입니다. 세 클라이언트에서 비슷한 노드 개념을 다루더라도 앱 데이터 경로, 가져오기 방법, 백그라운드 동작, 설정 생성 방식은 서로 다릅니다. 한 클라이언트의 데이터 폴더 전체를 다른 클라이언트에 덮어쓰지 마세요.

V2Fly와 Xray는 공통된 설정 방식을 바탕으로 해 일부 JSON 필드가 비슷하지만, 확장 기능과 지원 프로토콜, 필드 변경 사항이 완전히 같지는 않습니다. sing-box는 별도의 구조를 사용하며 인바운드 유형, 아웃바운드 정의, DNS, 라우팅 동작을 자체 규칙에 따라 작성해야 합니다. 프로토콜 이름이 같아도 설정을 그대로 복사할 수 있는 것은 아닙니다. 마이그레이션할 때는 기능상 의미를 대응한 뒤 필드를 새로 구성하고 프로토콜 이름만 기계적으로 바꾸지 마세요.

시스템 프록시, 라우팅, TUN을 계층별로 이해하기

시스템 프록시는 이를 지원하는 앱이 요청을 로컬 인바운드에 전달하는 방식을 정합니다. 코어 라우팅은 코어에 들어온 요청이 사용할 아웃바운드를 결정합니다. TUN은 가상 네트워크 인터페이스를 통해 더 많은 시스템 트래픽을 받습니다. 세 기능은 서로 다른 계층에서 작동합니다. 라우팅 규칙을 수정해도 코어에 들어오지 않은 앱이 갑자기 제어되는 것은 아닙니다. TUN을 켜도 코어의 규칙이 자동으로 올바르게 되거나 원격 인증 오류가 해결되지는 않습니다.

클라이언트에서 말하는 “전역”은 보통 기본 출구나 트래픽을 가로채는 범위를 가리키지만, 정확한 뜻은 현재 모드에 따라 다릅니다. 코어 라우팅을 바꾸는 기능일 수도 있고 시스템 프록시 모드의 이름일 수도 있습니다. 버튼 문구만 믿지 말고 생성된 설정, 실제 인바운드, 로그를 확인하세요. LAN 서비스에 접속할 수 없다면 코어가 사설 주소를 잘못된 출구로 보내는지와 TUN의 시스템 라우팅이 로컬 네트워크 처리 방식을 바꾸었는지 모두 점검해야 합니다.

TUN에는 적절한 권한이 필요하며 다른 가상 네트워크 프로그램과 충돌할 수 있습니다. 켠 뒤 모든 네트워크가 끊기면 먼저 TUN을 꺼서 기본 연결을 복구한 다음 권한, 가상 인터페이스, DNS, 라우팅 충돌을 확인하세요. 원격 서버 매개변수를 동시에 바꾸지 마세요. 시스템 프록시 모드에서 연결이 된다면 핵심 연결 경로 일부는 이미 정상이라는 뜻입니다. 이때 노드 설정은 그대로 두고 트래픽 처리 계층만 검증하는 편이 구독을 전부 다시 가져오는 것보다 효과적입니다.

구독, 사용자 지정 규칙, 업데이트 덮어쓰기

구독은 보통 노드 정보를 제공하며 로컬 라우팅, 시스템 프록시, DNS까지 포함하지는 않습니다. 더 완전한 설정을 제공하는 가져오기 형식도 있으므로 가져오기 전에 콘텐츠 유형을 확인하세요. 구독을 업데이트한 뒤 노드 매개변수가 바뀌는 것은 정상적인 동기화 동작이지만 직접 수정한 노드 설정은 덮어써질 수 있습니다. 오래 유지해야 하는 예외는 클라이언트가 지원하는 로컬 규칙이나 별도 설정에 보관해 구독을 갱신할 때마다 같은 항목을 다시 수정하지 않도록 하세요.

전체 사용자 지정 설정을 클라이언트가 처리하는 방식도 확인해야 합니다. 설정을 그대로 실행할 수도 있고 수신 포트, 로그, 제어 인터페이스, 통계 설정을 추가할 수도 있습니다. 파일 내용이 최종 실행 설정이라고 가정하지 마세요. 문제를 분석할 때는 가져온 출처, 클라이언트 선택 항목, 최종 시작 로그를 함께 기록하세요. 설정을 내보냈다고 공개해도 안전한 것은 아닙니다. 서버 주소, 인증 정보, 구독 링크가 포함될 수 있으므로 공유하기 전에 민감한 내용을 하나씩 삭제하세요.

macOS, Windows, Linux에서는 JSON이 같더라도 파일 경로, 디렉터리 권한, 방화벽, 시스템 프록시 연결 방식이 다릅니다. 로그 파일은 클라이언트에 쓰기 권한이 있는 위치에 두세요. 다른 운영체제의 절대 경로를 그대로 붙여 넣지 마세요. 최초 설치에 필요한 디렉터리와 실행 환경은 v2rayN 최초 설치 및 초기 설정을 참고하세요. 실행에 실패하면 프로세스 충돌인지 설정 거부인지 먼저 구분해야 합니다.

클라이언트를 설치하거나 교체하려면 설치 파일 페이지에서 운영체제와 프로세서 아키텍처에 맞는 파일을 선택하세요. 데스크톱에서는 v2rayN을 우선 권장합니다. 필드 하나를 시험하려고 클라이언트와 코어를 자주 바꾸면 설정 차이와 환경 차이가 겹칩니다. 변경을 되돌릴 수 있는 작은 단계로 나누고 마지막으로 작동한 설정을 보관해야 어떤 기능이나 계층이 바뀌었는지 확인하기 쉽습니다.

전체 설정 예제와 단계별 검증

로컬 직접 연결 및 정확한 차단을 위한 기준 설정

다음은 로컬에서 검증할 수 있는 전체 JSON입니다. 루프백 주소에서 SOCKS와 HTTP 포트를 수신하고, 일반 트래픽은 직접 연결하며, 정확히 일치하는 예제 도메인은 차단 아웃바운드로 보냅니다. 원격 프록시 인증이나 분류 데이터 파일에 의존하지 않아 라우팅을 이해하기 위한 기준 설정으로 적합합니다. 클라이언트가 같은 포트를 사용 중이면 먼저 클라이언트의 코어를 중지하거나 별도의 테스트 사본에서 사용 가능한 포트로 바꾸고 앱의 설정도 함께 변경하세요.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    },
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.com"],
        "outboundTag": "block"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "direct"
      }
    ]
  }
}

검증할 때는 클라이언트가 지원하는 전체 설정 입력 경로를 사용하고, 대상 코어가 실행 중인지 확인한 뒤 설정 로드 결과를 살펴보세요. 시작 직후 실패한다면 구문 오류, 알 수 없는 필드, 포트 사용 충돌부터 해결하세요. 시작은 성공했지만 앱 요청이 기록되지 않는다면 앱이 실제로 로컬 인바운드에 연결했는지 확인하세요. 요청이 아직 해당 설정을 거치는 단계에 도달하지 않았을 수 있으므로 이때 DNS나 원격 전송부터 조정하지 마세요.

순서대로 정상 테스트와 역방향 테스트하기

먼저 HTTP 프록시를 지원하는 앱 하나를 골라 주소를 127.0.0.1, 포트를 10809로 설정하고 현재 네트워크에서 직접 연결할 수 있는 대상에 접속하세요. 다음으로 정확히 차단되도록 설정한 예제 도메인에 접속해 규칙에 맞게 실패하는지 확인합니다. 마지막으로 차단 규칙을 잠시 제거하고 설정을 다시 불러와 결과를 비교하세요. 요청은 반드시 도메인으로 프록시에 전달되어야 합니다. 앱이 미리 IP로 조회하면 도메인 규칙에 필요한 정보가 없을 수 있습니다.

역방향 테스트도 중요합니다. 차단 범위에 포함되지 않은 대상은 정상적으로 접속할 수 있어야 합니다. 대상 하나가 실패한 것만으로 규칙이 올바르다고 입증할 수 없으며, 인바운드 전체가 작동하지 않는 경우일 수도 있습니다. 테스트할 때 앱의 기존 연결을 종료하고 브라우저 캐시, 보안 DNS, 별도 프록시 확장 프로그램이 경로를 바꾸지 않는지 확인하세요. 앱 동작을 확신할 수 없다면 한 가지 앱으로 전체 비교 테스트를 먼저 완료해 변수를 줄인 뒤 다른 프로그램으로 범위를 넓히세요.

연결 단계별로 로그 읽기

로그는 가능한 한 많이 모으기보다 실패한 단계를 찾는 데 사용하세요. 평소에는 불필요한 기록이 적은 수준으로 유지하고 문제를 재현할 때만 잠시 상세도를 높이세요. 인바운드 태그, 목적지 주소, 일치한 아웃바운드, 최종 오류가 같은 요청에 관한 것인지 확인해야 합니다. 여러 앱이 동시에 연결하면 연달아 표시된 두 줄이 같은 연결을 설명한다고 볼 수 없습니다. 로그에 중복 연결이 많이 나타나면 테스트 범위를 좁혀 백그라운드 앱 활동을 현재 대상의 결과로 오해하지 않도록 하세요.

로그에는 방문한 도메인, LAN 주소, 서버 정보가 포함될 수 있습니다. 문제 해결이 끝나면 평소 로그 수준으로 되돌리고 더는 필요하지 않은 상세 기록을 삭제하세요. 다른 사람에게 문제를 설명할 때는 오류 종류와 발생 단계를 남기되 인증 정보, 전체 구독 주소, 개인 접속 기록은 제거하세요. 클라이언트 데이터 디렉터리 전체를 공개하지 마세요. 실행 설정 외에도 이전 노드, 그룹 정보, 계정 관련 데이터가 저장되어 있을 수 있습니다.

기준 설정부터 실제 설정을 단계별로 복원하기

로컬 기준 설정이 통과하면 먼저 정상 작동이 확인된 원격 아웃바운드 하나를 복원하고 복잡한 라우팅은 동시에 추가하지 마세요. 원격 경로를 확인한 뒤 명확한 분기 규칙 하나를 추가하고, 그다음 분류 데이터와 DNS를 적용합니다. 정책 조정은 마지막에 진행하세요. 각 단계에서 일치해야 하는 요청과 일치하면 안 되는 요청을 모두 테스트하세요. 문제가 생기면 변경이 여러 겹 쌓인 파일에서 계속 시도하는 것보다 직전의 정상 사본으로 돌아가는 편이 원인을 찾기 쉽습니다.

구독 업데이트, 코어 변경, 클라이언트 업그레이드 후에도 같은 검증 순서를 활용할 수 있습니다. 창이 열린다고 모든 설정이 적용된 것은 아니며 웹페이지 하나가 열린다고 모든 프로토콜이 정상이라는 뜻도 아닙니다. 인바운드, 아웃바운드, 규칙, DNS가 각각 기대한 결과를 내야 해당 설정이 현재 용도에 맞는지 확인할 수 있습니다. 기본 사용법은 빠른 시작 가이드를 참고하고, 구체적인 문제는 문제 해결에서 이어서 확인하세요.