V2Ray 설정 파일 레퍼런스

01 / STRUCTURE

JSON 구조와 설정 범위

클라이언트 설정과 코어 설정 구분하기

V2Ray 생태계에서 GUI 클라이언트와 프록시 코어는 서로 다른 역할을 맡습니다. v2rayN, v2rayNG, v2flyNG는 서버 관리, 구독 업데이트, UI 설정, 실행 제어를 담당하고, 코어는 포트 리스닝, 연결 수립, 라우팅 매칭, 데이터 처리를 담당합니다. UI의 스위치 하나가 여러 JSON 필드를 만들기도 하고, 시스템 프록시만 변경해 코어 설정에는 반영되지 않기도 합니다. 따라서 문제를 해결할 때는 클라이언트, 운영체제, 코어 중 어디서 발생했는지 먼저 확인하세요. UI 문구만 보고 최종 동작을 단정해서는 안 됩니다.

클라이언트는 보통 현재 서버와 전역 설정을 바탕으로 실행 설정을 생성합니다. 이 파일은 작업 디렉터리나 임시 디렉터리에 있을 수 있으며, 재시작하면 새로 만들어질 수도 있습니다. 생성된 파일을 직접 수정해도 변경 사항이 계속 유지된다는 보장은 없습니다. 지속적으로 적용할 설정은 클라이언트가 제공하는 라우팅, DNS 또는 사용자 지정 설정 메뉴에 추가하는 것이 좋습니다. 메뉴 이름은 클라이언트 UI에 따라 다를 수 있으므로, 설정 저장 후 실제로 실행되는 구성으로 확인하세요. 디스크에 있는 config.json 파일의 이름만 보고 판단하지 마세요.

최상위 객체와 참조 관계

기본 설정은 객체 하나를 루트로 사용합니다. inbounds와 outbounds는 여러 인바운드와 아웃바운드를 정의할 수 있는 배열이고, routing, dns, policy는 객체입니다. 인바운드는 앱 연결을 코어에 전달하고, 라우팅은 연결에 사용할 아웃바운드를 선택하며, 아웃바운드는 목적지에 직접 연결할지 원격 서버를 통해 전달할지 결정합니다. DNS는 이름 확인이 필요한 단계에 결과를 제공하고, 정책은 특정 사용자 레벨의 시간 제한이나 통계 동작을 제어합니다. 각 기능은 서로 독립된 목록이 아닙니다.

아래는 로컬 연결 테스트에 사용할 수 있는 기본 설정 전체 예제입니다. 앱은 SOCKS 인바운드로 네트워크에 접속하고 코어는 직접 연결 아웃바운드를 사용합니다. 원격 프록시 서버는 포함되어 있지 않습니다. 리스닝 주소와 포트, 앱 프록시 설정이 올바른지 확인할 때 유용하지만 원격 프로토콜 테스트에는 사용할 수 없습니다. 실행 전에 포트가 사용 중인지 확인하고, 선택한 코어가 지원하는 설정 입력 방식으로 불러오세요. GUI 클라이언트에서는 서버 주소 입력란에 JSON 전체를 붙여 넣지 말고 사용자 지정 설정 기능을 이용해야 합니다.

{
  "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": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": []
  }
}

문법이 맞아도 설정이 올바른 것은 아닙니다

엄격한 JSON에서는 키와 문자열을 큰따옴표로 묶고, 불리언 값은 true 또는 false로 씁니다. 배열의 마지막 항목 뒤에는 쉼표를 붙이지 않습니다. 포트는 보통 숫자로 쓰며, 보기 좋게 맞추려고 전부 문자열로 작성하면 안 됩니다. 일부 설정 로더는 주석이나 확장 문법을 허용하지만 다른 클라이언트에서는 호환되지 않을 수 있습니다. 이 페이지의 예제는 주석 없는 JSON을 사용하고, 설명은 코드 블록 밖에 두어 파싱할 내용과 설명을 구분하기 쉽도록 했습니다.

tag는 설정 내부에서 참조하기 위한 이름입니다. 프로토콜 이름도 아니고 UI에 표시되는 서버 메모와 반드시 같을 필요도 없습니다. 라우팅의 outboundTag는 실제 아웃바운드 태그와 일치해야 하므로 철자, 대소문자, 하이픈을 확인하세요. 복잡한 설정을 만들 때는 먼저 태그 간 관계를 정리한 다음 프로토콜 필드를 채우는 것이 좋습니다. 객체 안에서 같은 키를 중복 정의하지 마세요. 파서마다 중복 키 처리 방식이 다를 수 있으므로, 중복 키를 값 덮어쓰기 용도로 사용해서는 안 됩니다.

연결 흐름을 따라 읽으면 됩니다. 먼저 인바운드가 무엇을 받는지 확인하고, 다음으로 아웃바운드가 연결을 수립할 수 있는지 살펴본 뒤 라우팅과 DNS를 확인하세요. 여러 절의 필드를 한꺼번에 추가하지 마세요. 기본 연결이 안정되면 객체 하나나 규칙 하나씩 추가하고 예상한 변화와 실제 결과를 기록하세요. 이렇게 하면 이전 설정으로 되돌리기 쉽고, 문법 오류와 참조 오류, 네트워크 문제를 한 번의 테스트에서 혼동하지 않을 수 있습니다.

02 / INBOUNDS

inbounds: 로컬 인바운드 리스닝

리스닝 주소로 접속 범위 결정

inbounds는 코어가 연결을 받는 진입점을 정의합니다. 데스크톱 클라이언트에서는 SOCKS와 HTTP 프록시 인바운드를 자주 사용하며, 앱은 지정된 주소와 포트에 해당 프로토콜로 접속해야 합니다. listen을 127.0.0.1로 설정하면 이 IPv4 루프백 주소를 통해 로컬 기기에서만 접속할 수 있습니다. 서버 주소나 원격 노드의 출구 주소를 의미하는 값이 아닙니다. 로컬 앱에서만 사용할 때는 루프백 리스닝을 유지하는 편이 접속 범위를 관리하기 쉽습니다.

리스닝 주소를 0.0.0.0으로 바꾸면 모든 로컬 IPv4 인터페이스에서 연결을 받습니다. 그렇다고 시스템 방화벽 규칙이 모두 열린다는 뜻은 아니며, 네트워크의 다른 기기가 해당 포트에 반드시 접속할 수 있는 것도 아닙니다. LAN 접속이 필요하다면 기기 주소, 방화벽 인바운드 규칙, 네트워크 격리, 인증 설정도 확인하세요. 루프백 주소는 요청을 보내는 기기 자신을 가리킵니다. 휴대폰에서 컴퓨터 프록시를 설정할 때 휴대폰의 루프백 주소를 컴퓨터의 LAN 주소 대신 사용하면 안 됩니다.

SOCKS와 HTTP 인바운드의 차이

아래 코드는 기본 설정의 inbounds 배열을 교체할 때 사용합니다. 두 인바운드는 포트와 태그가 다르며, 아웃바운드와 라우팅은 기존 설정을 그대로 사용합니다. SOCKS 인바운드에서 UDP를 활성화해도 앱이 해당 방식으로 UDP 프록시 요청을 보내야 합니다. HTTP 인바운드는 HTTP 프록시만 설정할 수 있는 앱에 적합합니다. 인바운드 두 개를 함께 설정해도 앱 하나가 둘 사이를 자동으로 전환하지는 않습니다.

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

스니핑은 DNS를 대신하지 않습니다

sniffing은 일부 연결의 프로토콜 내용에서 HTTP 호스트명이나 TLS 핸드셰이크의 서버 이름처럼 도메인 단서를 추출할 수 있습니다. 모든 연결의 원래 도메인을 복원하는 것은 아니며 앱 데이터를 복호화하지도 않습니다. 활성화 후 대상 처리 방식은 코어가 지원하는 필드에 따라서도 달라집니다. 따라서 스니핑을 켜면 모든 도메인 규칙이 매칭된다고 볼 수 없습니다. 연결 대상에 IP 주소만 남아 있다면 앱이 이름을 어떻게 확인하는지 먼저 살펴보세요.

destOverride는 대상 재정의에 사용할 수 있는 프로토콜 유형을 지정합니다. 대상 재정의와 라우팅 판단에만 사용하는 동작은 완전히 같지 않습니다. 일부 코어는 이를 제어하는 추가 필드를 제공하지만, 확장 필드를 모든 코어에 그대로 적용할 수는 없습니다. 서비스가 원래 목적지 주소에 의존하거나 동일한 IP에서 특수한 연결 로직을 사용한다면 스니핑 설정 변경 후 별도로 검증하세요. 명확한 필요가 없다면 탐지 유형을 최소한으로 설정해 불필요한 변수를 늘리지 않는 편이 좋습니다.

포트, 시스템 프록시, 트래픽 처리 방식

포트 사용 오류는 리스닝 단계에서 발생하며 원격 서버의 온라인 여부와 무관합니다. 중복 실행 중인 클라이언트를 종료하고 현재 프로세스가 사용하는 포트를 확인한 다음 포트를 변경할지 결정하세요. 인바운드 포트를 바꾸면 브라우저, 개발 도구, 시스템 프록시에 설정된 포트도 함께 변경해야 합니다. 코어만 바꾸고 시스템 프록시에 이전 주소를 남겨두면 앱 연결이 거부될 수 있습니다. 이때 구독을 계속 업데이트해도 해결되지 않습니다.

시스템 프록시는 운영체제 설정을 따르는 앱에 프록시 인바운드 사용을 안내할 뿐, 모든 앱의 트래픽이 코어를 거치도록 보장하지는 않습니다. TUN 방식은 가상 인터페이스, 시스템 라우팅, 권한도 관련되므로 SOCKS 인바운드를 추가하는 것으로 대신할 수 없습니다. Android 클라이언트의 시스템 트래픽 처리도 클라이언트와 플랫폼 기능이 함께 담당합니다. 트래픽이 코어에 들어오는지 확인하려면 UI의 시스템 프록시 스위치만 보지 말고 실제 연결 기록을 살펴보세요.

인바운드를 검증할 때는 테스트 앱 하나와 접속 가능한 대상 하나를 정해 연결 기록이 생성되는지, 예상한 아웃바운드가 선택되는지 차례로 확인하세요. 연결 기록이 없다면 앱이 프록시를 사용하는지, 프로토콜과 주소가 맞는지, 이전 설정이 캐시되어 있지 않은지 살펴보세요. 기록이 있다면 아웃바운드와 라우팅을 확인할 차례입니다. 최초 설정 순서는 v2rayN 초기 설정 안내를 참고하세요.

03 / OUTBOUNDS

outbounds: 아웃바운드 프로토콜과 태그

아웃바운드가 다음 연결을 정의합니다

outbounds는 코어가 받은 연결을 어떻게 처리할지 결정합니다. freedom은 목적지에 직접 연결하고, blackhole은 연결을 차단하며, VLESS 같은 프록시 프로토콜은 설정된 원격 서버로 연결을 전달합니다. 아웃바운드 하나가 구체적인 라우팅 규칙 하나를 의미하지는 않습니다. 여러 규칙에서 같은 아웃바운드를 참조할 수 있고, 한 규칙이 여러 도메인과 매칭되어 같은 출구를 선택할 수도 있습니다. 프로토콜 매개변수와 트래픽 분류를 분리해 관리할 수 있습니다.

라우팅 규칙에 매칭되지 않으면 일반적으로 아웃바운드 배열의 첫 번째 항목이 기본 출구로 사용됩니다. 따라서 배열 순서는 실제 동작에 영향을 줍니다. direct를 첫 번째 항목에 두는 것은 표시 순서만 바꾸는 일이 아닙니다. 매칭되지 않은 모든 트래픽의 처리 방식이 바뀔 수 있습니다. 설정을 만들기 전에 기본 동작부터 정하세요. 기본 프록시가 필요하다면 사용할 수 있는 프록시 아웃바운드를 앞에 두고, 기본 직결이 필요하다면 직결 아웃바운드를 첫 번째 항목으로 명시하세요.

직결과 차단을 각각 테스트할 수 있습니다

아래 배열은 직결과 차단 동작을 확인하는 데 사용할 수 있습니다. 기본 설정의 outbounds를 교체하세요. 라우팅에서 참조할 태그 두 개를 정의하며, 기본 출구는 첫 번째 항목인 직결입니다. blackhole은 연결을 의도적으로 버리는 아웃바운드이지, 예비 경로나 다른 서버를 자동으로 찾는 기능이 아닙니다. 테스트 도메인에 이 아웃바운드를 사용하면 앱에서 연결 실패가 나타나는 것이 정상입니다. 전체 클라이언트 오류로 판단하지 말고 라우팅 기록에서 규칙이 매칭됐는지 확인하세요.

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

VLESS 매개변수는 서버 설정과 일치해야 합니다

아래는 VLESS 아웃바운드 객체의 구조 예제이며, 바로 접속할 수 있는 공개 서버가 아닙니다. your-server.example은 설명용 도메인이고 예시 UUID도 형식만 보여주기 위한 값입니다. 실제 사용 시에는 정당하게 이용할 수 있는 서버의 매개변수로 바꾸세요. 이 객체에는 TCP와 TLS 설정이 포함되어 있으므로 원격 서버도 같은 조합을 제공해야 합니다. 객체를 배열에 추가한다고 기존의 다른 프로토콜 서버가 VLESS 연결을 자동으로 받아들이는 것은 아닙니다.

{
  "tag": "proxy",
  "protocol": "vless",
  "settings": {
    "vnext": [
      {
        "address": "your-server.example",
        "port": 443,
        "users": [
          {
            "id": "00000000-0000-4000-8000-000000000001",
            "encryption": "none",
            "level": 0
          }
        ]
      }
    ]
  },
  "streamSettings": {
    "network": "tcp",
    "security": "tls",
    "tlsSettings": {
      "serverName": "your-server.example",
      "allowInsecure": false
    }
  }
}

address는 서버 주소, port는 서버 리스닝 포트, id는 프로토콜 사용자 식별자입니다. VLESS 사용자 객체의 encryption은 전송 보안 계층과 별개입니다. 값을 none으로 설정해도 바깥쪽 TLS가 비활성화되는 것은 아닙니다. 전송 보안은 streamSettings.security 등의 필드에서 설정합니다. 이름이 비슷한 여러 ‘암호화’ 옵션을 하나로 묶어 해석하지 마세요. 프로토콜은 가져와지지만 연결이 되지 않는 문제가 생길 수 있습니다.

사용자 객체의 level은 policy.levels와 연결할 수 있습니다. 노드 우선순위나 라우팅 규칙 순서를 제어하는 값은 아닙니다. flow 등의 확장 매개변수는 서버, 코어, 전송 조합이 모두 지원할 때만 사용하세요. 가져온 링크에 특정 값이 있었다는 이유만으로 모든 서버에 똑같이 추가해서는 안 됩니다. 가져온 뒤에는 주소, 포트, 사용자 식별자, 전송 방식, 보안 계층을 확인하고, 특히 클라이언트에서 알 수 없는 필드 경고가 표시되는지 살펴보세요.

프로토콜과 클라이언트는 따로 선택하세요

클라이언트 이름이 지원 프로토콜 목록을 뜻하는 것은 아닙니다. 데스크톱에서는 v2rayN을 우선 사용하고, Android에서는 실제 코어 요구사항에 따라 v2rayNG 또는 v2flyNG를 선택할 수 있습니다. 특정 확장을 쓸 수 있는지는 클라이언트 메모에 프로토콜 이름이 있는지가 아니라 현재 코어와 설정 조합에 달려 있습니다. 선택 기준은 세 클라이언트의 코어 차이를 참고하고, 설치 파일은 다운로드 페이지에서 받으세요.

아웃바운드 문제는 서버에 연결할 수 없는 경우, 프로토콜 인증 실패, 전송 핸드셰이크 실패로 나누어 살펴보세요. 주소나 포트 오류는 대개 하위 연결을 수립하는 단계에서 발생하고, 사용자 식별자가 맞지 않으면 프로토콜 처리 단계에서 실패합니다. TLS 이름 오류는 보안 계층 문제입니다. 로그에서 실패 단계를 확인한 다음 해당 필드를 점검하세요. 주소, 사용자 식별자, 전송 방식을 한 번에 바꾸면 연결이 복구되더라도 원인을 알 수 없어 유지 관리가 어려워집니다.

04 / STREAM SETTINGS

전송 방식과 TLS 보안 계층

프로토콜, 전송, 보안 계층 구분하기

프록시 프로토콜은 양쪽이 프록시 요청을 주고받는 방식을 정의하고, 전송 방식은 데이터를 전달할 통로를 지정하며, 보안 계층은 핸드셰이크와 신원 확인, 암호화된 연결을 처리합니다. 보통 세 설정은 아웃바운드 객체에 함께 들어가지만 임의로 조합할 수는 없습니다. UI에 같은 VLESS로 표시된 서버라도 요구하는 전송 방식과 보안 계층이 다를 수 있습니다. 한 서버의 전송 매개변수를 다른 서버에 복사하면 프로토콜 인증 전 단계에서 실패할 수 있습니다.

streamSettings.network에서 전송 유형을 선택하고, 해당 설정 객체에서 세부 매개변수를 지정합니다. TCP는 구조가 비교적 단순하고 WebSocket은 보통 경로가 필요하며 HTTP 호스트명 설정이 추가될 수도 있습니다. 서버가 리버스 프록시를 거친다면 공개 포트와 경로는 서버 배포 방식에 따라 달라집니다. 클라이언트에 입력하는 각 값은 서버 설정을 근거로 해야 합니다. 흔히 쓰이는 경로를 임의로 시도해 매개변수 확인을 대신하지 마세요.

WebSocket 예제의 필드 구성

아래 객체는 흔히 사용하는 WebSocket과 TLS 조합을 보여줍니다. 최상위 설정이 아니라 아웃바운드 안의 streamSettings 전체를 교체하세요. 도메인과 경로는 설명을 위한 예시입니다. address는 실제 연결 대상을 결정하는 프로토콜 서버 객체에 그대로 둡니다. 여기의 호스트명, 서버 이름, 경로는 상위 계층 핸드셰이크에 사용됩니다. 실제 배포에서 값이 서로 다르다면 각각에 맞는 값을 입력하세요. 세 값이 항상 같다고 가정하면 안 됩니다.

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

인증서 오류는 이름과 유효기간부터 확인

TLS 연결에서는 인증서의 적용 대상 이름과 유효기간을 확인해야 합니다. 시스템 시간이 크게 어긋났거나 서버 이름과 인증서가 일치하지 않거나 인증서 체인이 올바르게 배포되지 않은 경우 핸드셰이크가 실패할 수 있습니다. IP 주소로 연결하더라도 인증서가 도메인에 발급됐다면 서버 요구사항에 맞는 서버 이름을 설정해야 합니다. 서버 주소, HTTP 호스트명, 인증서 이름은 서로 바꿔 쓸 수 있는 동의어가 아닙니다. 우연히 같은 값을 쓰더라도 각자 역할은 다릅니다.

allowInsecure는 인증서 검증의 일부 확인을 건너뛸지 결정하는 설정이지 인증서 배포 문제를 해결하는 옵션이 아닙니다. 이 페이지 예제에서는 false로 유지합니다. 인증서 오류가 발생하면 시스템 시간을 동기화하고 서버 이름, 인증서 적용 범위, 서버 인증서 체인을 확인하세요. 검증을 계속 비활성화하면 연결의 신원 확인 조건이 달라지고 이름 설정 오류도 가려질 수 있습니다. 문제 해결 순서는 TLS 핸드셰이크 및 인증서 오류 안내를 참고하세요.

확장 필드와 연결 재사용의 범위

REALITY는 특정 코어가 지원하는 보안 계층 방식이며 일반 TLS 설정의 다른 이름이 아닙니다. 서버 이름, 공개 키, 기타 관련 매개변수는 실제 서버 요구사항에 맞춰 함께 설정해야 합니다. security 문자열만 바꿔서는 사용할 수 없습니다. 일부 전송 이름과 확장 설정도 코어마다 다릅니다. 설정을 옮기기 전에 구현 방식과 지원 범위를 확인하세요. 알 수 없는 필드 경고가 뜨면 해당 필드만 삭제한 뒤 동작이 같을 것이라고 가정하지 마세요.

Mux 다중화는 특정 조건에서 하위 연결을 재사용하려는 기능입니다. 트래픽 분할 기능도 아니며 프로토콜 매개변수 오류를 해결하지도 않습니다. 활성화 여부는 프로토콜, 서버 지원 여부, 앱의 연결 방식, 현재 코어의 제한에 따라 판단하세요. 단일 연결 실패를 조사할 때는 먼저 다중화를 끈 상태에서 기본 연결이 안정적인지 확인한 다음 별도로 테스트하세요. 다중화와 전송 계층 자체의 연결 재사용 기능을 혼동하지 말고, 다중화와 DNS, 라우팅을 동시에 바꿔 결과를 비교하지도 마세요.

전송 문제를 확인할 때는 같은 서버와 같은 테스트 대상을 유지하고 하위 연결, TLS 핸드셰이크, 전송 핸드셰이크, 프록시 요청 순으로 원인을 좁히세요. 연결 시간이 초과되면 주소와 접속 가능 여부부터 확인합니다. 인증서 오류가 발생했다면 이름과 인증서를 살펴보세요. WebSocket 경로가 맞지 않으면 요청 전달 규칙을 확인해야 합니다. 로그는 실패 단계의 단서이지 완전한 결론이 아닙니다. 서버 매개변수와 클라이언트가 실제 생성한 설정을 함께 확인하세요.

05 / ROUTING

routing: 규칙 매칭과 출구 선택

규칙 개수보다 순서와 기본 출구가 먼저입니다

routing.rules는 설정에 적힌 순서대로 규칙을 확인합니다. 규칙이 매칭되면 보통 지정된 아웃바운드를 사용하며, 더 ‘정확한’ 도메인을 찾으려고 뒤의 규칙까지 계속 살펴보지는 않습니다. 범위가 넓은 규칙을 앞에 두면 뒤의 세부 규칙이 매칭되지 않을 수 있습니다. 규칙을 관리할 때는 명확한 예외를 먼저 작성하고, 그다음 넓은 범위의 분류를 두며, 마지막에 기본 출구를 분명히 하세요. 규칙이 많다고 적용 범위가 정확한 것은 아닙니다. 순서가 모호하면 동작을 파악하기도 어려워집니다.

규칙 하나에 서로 다른 조건 필드가 여러 개 있으면 일반적으로 조건을 모두 만족해야 합니다. 반면 조건 배열에 값이 여러 개 있으면 해당 필드에서 대체 후보로 매칭됩니다. 예를 들어 inboundTag와 domain을 함께 설정하면 지정된 인바운드에서 들어오고 대상 도메인도 조건에 맞아야 합니다. 둘 중 하나만 만족하면 되는 것이 아닙니다. 서로 독립적인 예외 조건 두 개가 필요하다면 복잡한 조건 하나를 만드는 것보다 규칙 두 개로 나누는 편이 확인하기 쉽습니다.

도메인 전략과 도메인 매칭은 별개의 설정입니다

domainStrategy는 라우팅 매칭 과정에서 도메인의 IP 주소를 언제 확인할지 결정합니다. AsIs는 기존 대상 형식을 유지합니다. IPIfNonMatch는 도메인이 매칭되지 않을 때 주소를 조회해 IP 규칙과 비교합니다. IPOnDemand는 매칭 과정에서 IP 정보가 필요할 때 조회를 시작합니다. 이 설정은 모든 앱에서 DNS를 강제로 사용하게 하지 않으며, 앱이 이미 변환해 버린 원래 도메인을 복원하지도 않습니다. 전략을 선택할 때는 입력 대상의 실제 형식도 함께 고려하세요.

아래 객체는 최상위 routing을 교체하는 예제이며, 아웃바운드에 direct가 정의되어 있어야 합니다. 사설 주소는 매칭 조건을 쉽게 확인할 수 있도록 일반 IP 대역으로 표시했고, 도메인 예외에는 예시용 예약 도메인을 사용했습니다. 규칙에 매칭되지 않으면 첫 번째 아웃바운드가 기본 출구로 사용되므로 기본 설정에 직결만 있다면 이 예제에서도 프록시 출구가 생기지 않습니다. 다른 기본 동작이 필요하다면 해당 아웃바운드도 실제로 사용할 수 있도록 함께 설정해야 합니다.

{
  "domainStrategy": "IPIfNonMatch",
  "rules": [
    {
      "type": "field",
      "ip": [
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16"
      ],
      "outboundTag": "direct"
    },
    {
      "type": "field",
      "domain": [
        "full:example.com",
        "domain:example.org"
      ],
      "outboundTag": "direct"
    }
  ]
}

매칭 접두사로 범위 지정하기

full:example.com은 도메인 전체를 정확히 매칭합니다. domain:example.org는 해당 도메인과 하위 도메인을 매칭합니다. regexp:는 정규식을 사용하며 JSON 문자열의 백슬래시 이스케이프에 주의해야 합니다. 접두사가 없는 문자열에는 코어가 정의한 키워드 매칭 방식이 적용될 수 있으므로 범위를 알 수 없을 때 완전한 도메인 대신 사용하기에는 적절하지 않습니다. 호스트 하나를 정확히 제어하려면 의미가 분명한 접두사를 우선 사용하고 실제 요청을 확인해 하위 도메인을 추가하세요.

geosite:는 도메인 분류 리소스를, geoip:는 IP 분류 리소스를 참조합니다. 예를 들면 geosite:cn과 geoip:private가 있습니다. 온라인에서 분류를 자동으로 조회하는 명령은 아닙니다. 실행 환경에 매칭 데이터를 담은 파일이 있어야 하며 해당 파일에 필요한 분류가 포함되어 있어야 합니다. 분류 이름, 데이터 내용, 업데이트 상태에 따라 결과가 달라질 수 있습니다. 분류를 찾지 못하거나 규칙을 불러오지 못했다면 대상 사이트 탓으로 돌리지 말고 리소스와 코어를 확인하세요.

요청 조건에서 규칙을 역으로 확인

문제를 확인할 때는 인바운드 태그, 대상이 도메인인지 IP인지, 대상 포트, 예상 출구를 기록하고 첫 번째 규칙부터 확인하세요. 도메인 규칙이 매칭되지 않으면 코어가 실제로 도메인을 가져왔는지 확인합니다. IP 규칙이 매칭되지 않으면 조회 시점, 반환된 주소 유형, 네트워크 범위를 살펴보세요. 근거 없이 범위가 넓은 규칙을 추가하면 당장은 문제가 가려질 수 있지만 다른 연결의 출구까지 바뀔 수 있습니다.

규칙을 바꿔도 새 연결에만 적용되며 기존 장기 연결은 이전 경로를 계속 사용할 수 있습니다. 테스트 전에 테스트 앱의 관련 연결을 닫거나 요청을 새로 보내 기존 연결 결과를 규칙 미적용으로 오해하지 않도록 하세요. 문법과 우선순위 예제는 사용자 지정 라우팅 규칙 작성법에서 확인할 수 있습니다. 용어가 궁금하다면 용어집에서 도메인 분류, IP 대역, 아웃바운드 태그의 차이를 살펴보세요.

06 / DNS

dns: 확인 출처와 조회 경로

먼저 DNS 조회를 요청한 주체 확인

앱 요청 한 번에도 여러 단계의 이름 확인이 필요할 수 있습니다. 앱이 대상 도메인을 직접 조회하거나, 운영체제가 서버 주소를 조회하거나, 코어가 라우팅 매칭을 위해 대상을 확인하거나, 아웃바운드가 연결을 수립하며 주소를 조회할 수 있습니다. 최상위 dns 설정은 내장 리졸버를 호출하는 관련 단계에만 영향을 줍니다. 모든 앱의 DNS 요청을 자동으로 가로채지는 않습니다. 브라우저나 다른 앱이 별도의 암호화 DNS 기능을 사용한다면 자체 연결 경로를 이용할 수도 있으므로 코어 DNS만 수정했다고 동작이 바뀌었다고 단정할 수 없습니다.

문제를 확인하기 전에 대상부터 명확히 하세요. 프록시 서버 도메인이 확인되지 않는 것인지, 대상 사이트 도메인이 확인되지 않는 것인지 구분해야 합니다. 이름 확인 자체가 실패하는지, 조회된 주소에는 접속할 수 없는지, 시스템 조회가 비정상인지, 라우팅 매칭 단계에서만 문제가 생기는지도 확인하세요. 경우에 따라 살펴볼 설정이 다릅니다. 서버 도메인 조회는 프록시 연결 전에 필요한 단계이고, 대상 도메인 조회는 로컬이나 원격에서 이루어질 수 있으므로 모두 ‘DNS 연결 문제’로 묶으면 안 됩니다.

hosts, servers, 주소 유형

아래는 최상위 dns 구조 예제입니다. hosts에는 설명을 위한 도메인과 문서용 주소를 매핑했습니다. 정적 매핑 형식을 보여주는 예제로 실제 서비스에 접속할 수는 없습니다. 숫자로 된 DNS 서버 주소 두 개는 서버 배열 작성 방법을 보여줍니다. 실제 환경에서는 현재 네트워크에서 접속할 수 있고 사용 목적에 맞는 DNS 서비스를 선택하세요. 설정에 객체를 추가한 뒤에도 내장 리졸버를 호출하는 동작이 있어야 효과를 확인할 수 있습니다.

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

hosts는 명확하고 안정적인 주소 매핑에 적합하며, 자주 바뀌는 서비스 주소를 장기간 고정하기에는 적합하지 않습니다. 대상 서비스는 여러 주소를 사용하거나 지역별로 연결을 분산할 수 있고, 인증서와 서비스 진입점을 변경할 수도 있습니다. 오래된 매핑은 정상 조회 결과를 우회하게 만듭니다. 문제 해결이 끝나면 임시 매핑을 삭제하고 시스템 hosts 파일이나 클라이언트의 다른 DNS 설정이 값을 덮어쓰는지 확인하세요. 그렇지 않으면 DNS 서버를 바꿔도 요청이 계속 이전 정적 결과를 사용할 수 있습니다.

queryStrategy는 조회할 주소 유형을 제어합니다. 자주 쓰는 값은 UseIP, UseIPv4, UseIPv6이며 구체적인 지원 여부는 현재 코어를 기준으로 확인하세요. 이 설정은 운영체제에서 IPv6를 켜거나 끄는 스위치가 아닙니다. 네트워크에 사용할 수 있는 IPv6 경로가 없어도 IPv6 주소를 반환하는 것과 IPv6 연결에 성공하는 것은 별개의 문제입니다. IPv4만 조회해도 프록시 서버 자체의 연결 문제가 해결되지는 않습니다. 주소 유형과 실제 라우팅 사용 가능 여부를 확인한 뒤 조회 범위를 바꾸세요.

DNS 조회 트래픽에도 출구 설정이 필요합니다

코어가 시작한 DNS 조회가 어떤 경로로 전송되는지는 리졸버 유형, 코어 구현, 관련 라우팅 설정에 따라 달라집니다. 일반 원격 조회, 시스템 리졸버 호출, 로컬 처리 방식이 포함된 일부 조회가 모두 같은 분할 규칙을 따르는 것은 아닙니다. 암호화 DNS를 설정하면 리졸버 호스트명, TLS 이름, 연결 가능 여부에 대한 의존성도 생깁니다. 주소가 암호화 조회 형식을 사용한다는 사실만으로 실제 조회가 어느 출구를 통해 나가는지 알 수는 없습니다.

순환 의존성을 특히 주의하세요. 프록시 서버 주소가 도메인인데 그 도메인을 확인하는 요청까지 아직 연결되지 않은 동일한 프록시를 통하도록 설정하는 경우가 있습니다. 암호화 리졸버의 도메인을 그 리졸버 자신으로만 조회할 수 있는 경우도 마찬가지입니다. 시작 단계에 사용할 수 있는 조회 경로를 마련하고, 필요하면 명확한 부트스트랩 조회나 서버에서 승인한 연결 주소를 사용하세요. 모든 DNS 관련 주소를 프록시 출구로 지정한 뒤 코어가 의존성 문제를 알아서 해결하길 기대해서는 안 됩니다.

캐시와 분할 라우팅 함께 검증

DNS 캐시는 앱, 운영체제, 코어, 상위 리졸버에 남을 수 있습니다. 설정을 바꿔도 코어를 재시작한 뒤 앱이 캐시나 기존 연결을 계속 사용할 수 있습니다. 테스트할 때는 도메인 하나를 정하고 반환된 주소와 연결 출구를 기록한 다음 캐시가 어디에 있는지 각각 확인하세요. 설정을 전부 초기화하고 여러 DNS 서버까지 한꺼번에 바꾸면 결과를 비교하기 어려워집니다. 여러 주소를 사용하는 서비스에서는 한 번의 조회 결과가 다르다고 해서 설정이 불안정하다는 뜻은 아닙니다.

도메인 규칙과 IP 규칙을 함께 사용한다면 DNS는 별도의 최적화 스위치가 아니라 라우팅에 입력을 제공하는 요소로 봐야 합니다. 도메인이 규칙에 먼저 매칭되면 로컬 조회가 필요하지 않을 수 있지만, IP 매칭 단계로 넘어가면 조회 결과에 따라 출구가 바뀔 수 있습니다. 따라서 분할 라우팅을 설계할 때는 ‘언제 조회하는지’와 ‘조회 후 어떻게 매칭하는지’를 모두 정리하세요. 도메인 하나의 문제만 해결하려는 경우에는 먼저 해당 설정만 테스트한 다음 전역 설정에 적용할지 결정하세요.

07 / POLICY & LOG

policy: 연결 정책, 로그, 통계

사용자 레벨은 정책 인덱스입니다

policy는 연결 처리와 통계 관련 정책을 정의합니다. levels는 사용자 레벨을 인덱스로 사용하며 프로토콜 사용자 객체의 level을 해당 정책에 연결할 수 있습니다. 이 레벨은 계정 권한 순위도, 서버 성능도, 라우팅 우선순위도 의미하지 않습니다. 해당 프로토콜과 연결에서 지정된 레벨을 사용할 때만 관련 설정이 예상대로 적용됩니다. 참조되지 않는 레벨에 매개변수를 입력해도 모든 연결의 동작이 바뀌지는 않습니다.

JSON 객체의 레벨 키는 "0"처럼 문자열로 작성하지만, 프로토콜 사용자 객체의 레벨 필드는 보통 숫자로 작성합니다. 이름은 비슷해도 위치와 유형이 다릅니다. 여러 레벨을 관리한다면 각 레벨을 사용하는 객체와 조정 목적을 기록하세요. 설명하기 어려운 숫자만 남기지 않는 것이 좋습니다. 일반적인 클라이언트 사용 환경에서는 정책을 자주 수정할 필요가 없습니다. 출처가 불분명한 ‘범용 최적화 매개변수’를 적용하기보다 기본 동작을 유지하는 편이 문제를 해결하기 쉽습니다.

시간 제한 필드는 단계마다 다르게 적용됩니다

아래 객체는 최상위 policy 설정의 참고용으로 자주 쓰이는 정책 필드를 보여줍니다. 값의 단위는 초이며, 모든 환경에 권장되는 설정이 아니라 예시입니다. handshake는 해당 핸드셰이크 단계의 시간 제한을 설정하고, connIdle은 유휴 연결과 관련됩니다. uplinkOnly와 downlinkOnly는 한 방향으로만 활동이 계속되는 단계를 처리합니다. 모두 같은 전체 연결 시간 제한을 뜻하는 것은 아니며, 실제 적용 위치는 프로토콜 구현에 따라서도 달라집니다.

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

유휴 연결 정책을 너무 짧게 설정하면 대화형 터미널, 알림 연결, 일시적으로 데이터가 없는 세션이 자주 다시 연결될 수 있습니다. 너무 길게 설정하면 사용하지 않는 연결이 오래 유지될 수도 있습니다. 앱에는 자체 하트비트, 읽기·쓰기 시간 제한, 재연결 로직이 있으므로 주기적으로 연결이 끊긴다면 앱 설정과 코어 로그를 함께 살펴보세요. 끊기는 간격이 특정 정책값과 비슷하다는 이유만으로 원인을 단정하지 마세요. 네트워크 장비나 원격 서비스에도 별도 시간 제한이 있을 수 있습니다.

핸드셰이크에 실패하면 시간을 늘리기 전에 프로토콜, 주소, 보안 계층 매개변수부터 확인하세요. 잘못된 매개변수는 더 오래 기다린다고 올바르게 바뀌지 않습니다. 네트워크가 실제로 느린 환경에서는 시간 예산을 적절히 늘리는 것이 도움이 될 수 있지만 반복 가능한 테스트를 근거로 판단해야 합니다. 수정할 때는 한 번에 필드 하나만 바꾸고 핸드셰이크 시작 시점과 오류 단계를 기록하세요. 전송 핸드셰이크 전에 문제가 발생했다면 앱 데이터 단계의 유휴 정책을 바꾸는 것은 보통 해결책이 아닙니다.

로그 레벨로 기록 상세도 조절

로그 설정은 최상위 log에 있으며 policy 안에 들어가지 않습니다. 평소에는 warning을 사용하고 문제를 확인할 때는 일시적으로 info나 더 자세한 레벨로 바꾸세요. 아래 객체는 기록 상세도만 설정합니다. 로그 저장 위치는 클라이언트와 코어의 실행 방식에 따라 달라집니다. 디스크 경로를 지정하지 않았다면 로그가 특정 폴더에 저장됐다고 가정하지 마세요. 먼저 클라이언트 로그 패널이나 명시적으로 안내된 로그 파일 위치를 확인하세요.

{
  "loglevel": "warning"
}

연결 기록에는 대상 도메인, IP 주소, 인바운드 태그, 오류 원인이 포함될 수 있습니다. 문제 해결 내용을 공개하기 전에 구독 주소, 사용자 식별자, 개인 경로 등 불필요한 정보를 지우세요. 진단에 필요한 정보는 유지하면서 민감한 이름을 일관된 예시 태그로 바꿀 수 있습니다. 다만 오류가 발생한 단계, 필드 유형, 태그 간 참조 관계는 남겨야 합니다. ‘연결 실패’ 한 줄만으로는 문제를 파악하기 어려운 경우가 많으며 초기화와 핸드셰이크 전후 기록도 중요합니다.

통계 수집 스위치와 통계 UI는 별개입니다

정책의 통계 스위치는 관련 횟수를 수집할지 여부를 정할 뿐, 클라이언트에 차트를 자동으로 만들지는 않습니다. 통계를 읽으려면 코어의 통계 기능, 인터페이스, 클라이언트 지원도 필요합니다. 일부 사용자 통계는 프로토콜 사용자 식별 정보에 의존하므로 시스템 통계를 켜면 앱이나 서버별 데이터가 자동으로 수집된다고 볼 수 없습니다. 연결 실패 원인을 찾는 것만 목적이라면 보통 로그부터 확인하면 되며, 이를 위해 별도의 인터페이스 전체를 활성화할 필요는 없습니다.

로그와 통계는 상태를 확인하기 위한 도구이지 연결 성공의 전제 조건이 아닙니다. 정책을 잘못 조정하면 문제가 더 복잡해질 수 있고, 차트가 없다고 프록시가 실행되지 않는 것도 아닙니다. 설정을 적용한 뒤 먼저 실제 요청을 검증하고 유지 관리에 필요한 기록 상세도를 선택하세요. 클라이언트에서 이미 통계를 지원한다면 기존 기능을 우선 사용해 불필요한 관리 인터페이스를 중복으로 열지 마세요. 상세 기록을 마치면 평소 로그 레벨로 되돌리고 더 이상 필요하지 않은 임시 진단 파일을 정리하세요.

08 / APPLY & DIAGNOSE

설정 적용, 구독 관리, 단계별 문제 해결

되돌릴 수 있는 변경 절차부터 마련하세요

새 설정을 적용하기 전에 현재 정상 동작하는 클라이언트 설정과 사용자 지정 설정을 복사해 보관하고, 변경할 필드와 예상 동작을 기록하세요. 백업은 직접 알아볼 수 있는 위치에 두고 클라이언트 임시 실행 파일과 섞지 마세요. 복원할 때는 서버 선택, 시스템 프록시, 라우팅 모드, DNS 설정도 함께 고려해야 합니다. JSON 일부만 복원해서는 클라이언트 전체 상태가 되돌아오지 않을 수 있습니다. 한 번의 변경 범위가 명확할수록 안전하게 되돌릴 수 있습니다.

실제 적용되는 설정은 여러 계층에서 올 수 있습니다. 구독에서 서버 매개변수를 제공하고, 클라이언트 전역 설정에서 인바운드와 라우팅 템플릿을 구성하며, 사용자 지정 설정이 일부 필드를 덮어쓸 수도 있습니다. 문제를 확인할 때는 일반 서버 설정과 전체 사용자 지정 설정 중 어떤 방식으로 실행 중인지, 최종 결정권을 가진 설정 경로가 무엇인지 확인하세요. 실행 모드가 다르면 같은 UI 스위치도 결과에 영향을 주지 않을 수 있습니다. 사용되지 않는 사용자 지정 파일을 계속 수정하면서 코어가 설정을 읽지 않는다고 오해하지 마세요.

구독이 전체 실행 설정을 포함하는 것은 아닙니다

구독은 보통 서버 항목이나 공유 정보를 배포하는 데 사용되며 로컬 리스닝, 시스템 프록시, 라우팅, DNS 정책 전체를 제공한다고 보장하지 않습니다. 구독을 업데이트하면 서버 이름, 주소, 선택적 매개변수가 바뀔 수 있습니다. 로컬 사용자 지정 라우팅이 유지되는지는 클라이언트 구현에 따라 다릅니다. 구독 주소도 안전하게 관리해야 하는 정보이므로 공개 스크린샷이나 게시물, 문제 해결 글에 포함하지 마세요. 가져오기에 성공했다는 사실은 클라이언트가 내용을 읽었다는 뜻일 뿐, 서버 매개변수가 모두 적합하다는 보장은 아닙니다.

여러 기기에서 동기화할 때는 서버 정보를 공유하는 것과 기기별 설정을 맞추는 일을 구분하세요. 컴퓨터와 휴대폰에서 같은 정식 구독을 사용할 수 있지만 리스닝 포트, 시스템 트래픽 처리 방식, 네트워크 권한은 다를 수 있습니다. 데스크톱 실행 설정 전체를 모바일 클라이언트에 그대로 덮어쓰지 마세요. 설정을 옮겨야 한다면 먼저 서버 항목을 동기화하고 기기별로 인바운드, 라우팅, DNS를 확인하세요. 방법은 구독, 공유 링크, 설정 내보내기를 이용한 동기화 안내를 참고하세요.

연결 단계에 따라 실패 지점 찾기

첫 번째 단계에서는 설정을 불러오고 실행하는지 확인합니다. JSON 파싱 오류가 나면 근처의 따옴표, 쉼표, 괄호부터 확인하세요. 필드가 지원되지 않는다는 메시지가 나오면 코어 종류와 필드가 속한 기능을 확인합니다. 리스닝에 실패하면 포트 사용 여부와 권한을 확인하세요. 이 문제들은 실제 프록시 요청을 보내기 전에 발생하므로 우선 원격 서버 설정을 바꿀 필요는 없습니다. 수정한 뒤 코어가 계속 실행 중인지 확인하고 다음 단계로 넘어가세요. 프로세스가 종료된 상태에서 네트워크를 테스트하지 마세요.

두 번째 단계에서는 요청이 코어에 들어오는지 확인합니다. 프록시가 명확히 설정된 테스트 앱을 선택해 연결을 새로 시도하고 로그를 확인하세요. 기록이 없다면 앱의 프록시 프로토콜, 루프백 주소, 포트를 확인하고 시스템 프록시가 이전 인바운드를 가리키고 있지 않은지 살펴보세요. 기록은 있지만 출구가 예상과 다르면 라우팅 순서, 인바운드 태그, 대상 형식을 확인하세요. 실제 요청 경로를 확인하지 않은 채 클라이언트를 반복해서 재설치하는 것은 해결책이 아닙니다.

세 번째 단계에서는 원격 서버와 대상 사이트를 확인합니다. 서버 연결에 실패하면 주소, 포트, 연결 시작 단계의 DNS 조회를 확인하세요. 핸드셰이크에 실패하면 프로토콜 사용자, 전송 경로, 인증서 이름을 확인합니다. 서버에는 연결되지만 일부 대상에서 문제가 생기면 대상 DNS, 규칙, 주소 유형을 살펴보세요. 특정 서비스만의 문제인지 전체 설정 문제인지 구분하려면 여러 대상을 테스트하되, 한 차례 테스트에서는 다른 변수를 그대로 유지해야 합니다. 한 번 접속에 성공했다고 모든 규칙이 예상대로 동작한다고 볼 수는 없습니다.

변경 후 검증과 정리

최소한 로컬 인바운드, 기본 출구, 명확한 직결 예외, 차단하도록 설정한 테스트 조건 하나를 검증하세요. 차단 규칙이 없다면 검증을 위해 새로 추가할 필요는 없습니다. 각 테스트의 입력 조건과 예상 출구를 명시하고 새 연결로 확인해야 합니다. 기존 연결이나 캐시에 이전 결과가 남을 수 있으므로 테스트 세션을 새로 만드세요. 설정이 저장됐는지 확인한 뒤 클라이언트를 정상적으로 한 번 재시작하고 실행 설정이 변경 내용과 일치하는지 확인하세요.

마지막으로 평소 로그 레벨을 복원하고 임시 hosts 매핑과 테스트 규칙을 삭제한 뒤 간단한 변경 기록을 남기세요. 처음 사용하는 경우에는 빠른 시작 가이드에서 클라이언트 설정의 기본 순서를 확인하세요. 필드별 내용은 이 페이지 목차를 따라 살펴보면 됩니다. 설정 관리의 핵심은 스위치를 더 많이 쌓는 것이 아니라 인바운드, DNS 조회, 라우팅, 아웃바운드의 관계를 설명하고 검증할 수 있게 유지하는 것입니다. 문제가 생겼을 때 정확히 이전 상태로 되돌릴 수 있어야 합니다.