V2Ray 설정 파일
구조 및 필드 가이드

01 / JSON 구조와 설정 출처

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

먼저 현재 사용하는 설정의 출처를 확인한 다음 수정할 위치를 정하세요. v2rayN, v2rayNG, v2flyNG는 구독 관리, 설정 선택, 코어 실행을 담당하는 그래픽 클라이언트입니다. 실제로 연결을 받고 라우팅 규칙을 적용해 데이터를 전달하는 역할은 코어가 수행합니다. 인터페이스에 저장된 구독 주소, 창 옵션, 자동 업데이트 일정이 코어 JSON에 포함되는 것은 아닙니다. 클라이언트 설정 파일을 코어 설정으로 착각해 수정하면 필드가 있어도 실행 결과가 달라지지 않을 수 있습니다.

설정이 클라이언트에서 자동 생성되는지도 확인하세요. 노드를 바꾸거나 라우팅을 조정하거나 클라이언트를 다시 시작하면 실행 설정을 다시 쓸 수 있습니다. 임시 파일을 직접 수정하면 다음 생성 때 변경 사항이 사라지기 쉽습니다. 계속 유지할 설정은 그래픽 인터페이스에서 지정하는 것이 좋습니다. JSON을 직접 편집해야 한다면 클라이언트가 공식 지원하는 사용자 지정 설정 기능을 사용하고 원본 파일을 보관하세요. 내보내기, 보기, 편집은 서로 다른 작업입니다. JSON이 보인다고 해서 그 위치에서 수정 사항이 계속 유지되는 것은 아닙니다.

객체와 배열로 구조 파악하기

최상위 항목을 서로 다른 역할을 맡은 객체로 살펴보세요. inbounds와 outbounds는 인바운드와 아웃바운드를 여러 개 둘 수 있어 배열입니다. routing, dns, policy는 보통 세부 설정을 담는 객체입니다. 객체는 중괄호, 배열은 대괄호로 묶습니다. 필드명과 문자열에는 영문 큰따옴표를 사용하고, 숫자와 불리언 값에는 따옴표를 붙이지 않습니다. 포트는 숫자로, 스위치는 true 또는 false로 입력하세요. 모든 값을 문자열로 바꾸면 안 됩니다.

다음은 단독으로 실행할 수 있는 로컬 직접 연결 예제로, 설정 구조를 이해하는 데 활용할 수 있습니다. 로컬 SOCKS 인바운드만 제공하며, 수신한 연결을 시스템 네트워크로 직접 전달합니다. 원격 프록시 연결은 만들지 않습니다. 테스트할 애플리케이션을 로컬 포트에 연결한 다음 코어가 요청을 받는지 확인하세요. 원격 서비스 정보가 없으므로 구독에서 제공하는 연결 설정을 대신할 수 없습니다. 클라이언트에서 사용할 경우 기존 리스너 포트와 충돌하지 않는지도 확인하세요.

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

문법을 확인한 뒤 필드의 의미 점검하기

먼저 로컬 편집기에서 JSON 문법을 확인하세요. 흔한 오류로는 마지막 항목 뒤에 쉼표가 남아 있는 경우, 복사 과정에서 한글 따옴표가 들어간 경우, 객체를 삭제하면서 중괄호를 덜 지운 경우가 있습니다. 이 페이지의 예제는 주석이 없는 표준 JSON입니다. 편집기에서 파일을 열 수 있다는 것은 텍스트를 읽을 수 있다는 뜻일 뿐이며, 문법 검사를 통과해도 구조가 올바르다는 점만 확인됩니다. 코어가 필드를 인식하는지, 프로토콜을 지원하는지, 대상에 연결할 수 있는지는 각각 따로 검증해야 합니다. 이 단계를 한데 묶어 ‘설정이 정상’이라고 판단하지 마세요.

수정할 때마다 어떤 객체를 바꿨는지, 어떤 연결이 달라져야 하는지, 원복하려면 어디로 돌아가야 하는지 간단히 기록하세요. 한 번에 하나의 역할 계층만 변경해 DNS, 라우팅, 전송 설정을 동시에 바꾸지 않는 것이 좋습니다. 비슷하거나 중복되어 보이는 필드가 있으면 경로부터 비교하세요. 라우팅 객체의 DNS 정책과 아웃바운드 객체의 DNS 정책은 서로 다른 단계에서 작동할 수 있습니다. 필드명이 같다고 역할까지 같은 것은 아니므로 상위 객체도 함께 확인하세요.

02 / inbounds 인바운드와 리스닝 범위

애플리케이션이 코어에 연결되는 방식 확인하기

인바운드는 코어가 연결을 받는 진입점입니다. 애플리케이션이 시스템 프록시를 사용하는지, 별도의 SOCKS 설정을 사용하는지, 클라이언트의 가상 네트워크 인터페이스가 트래픽을 처리하는지 먼저 확인한 다음 해당 설정을 살펴보세요. 데스크톱 애플리케이션은 보통 로컬 HTTP 또는 SOCKS 포트를 통해 코어에 연결합니다. Android VPN 모드에서는 클라이언트가 시스템 인터페이스를 통해 트래픽을 처리하므로 JSON에 SOCKS 포트가 있다는 이유만으로 모든 앱이 그 인바운드를 거친다고 단정할 수 없습니다. 인바운드에 요청이 도달하지 않는다면 아웃바운드를 바꿔도 문제가 해결되지 않습니다.

listen, port, protocol을 하나씩 확인하세요. 리스닝 주소는 어떤 네트워크 인터페이스에서 요청을 받을지 정하고, 포트는 서비스 진입점 번호를 지정하며, 프로토콜은 인바운드가 어떤 형식의 데이터를 받을지 결정합니다. 브라우저의 HTTP 프록시를 SOCKS만 받는 포트에 임의로 지정하면 안 됩니다. 클라이언트 인터페이스에 ‘혼합 포트’가 표시된다면 클라이언트가 제공하는 조합 기능인지, 코어 설정의 개별 인바운드인지 확인하세요. 인터페이스 용어를 일반적인 프로토콜 이름처럼 JSON에 입력하면 안 됩니다.

로컬 접속과 LAN 접속 구분하기

현재 기기에서만 사용할 경우 127.0.0.1에 바인딩하는 것이 좋습니다. 이 주소는 IPv4 루프백 인터페이스이므로 다른 기기에서 현재 기기의 프록시에 접속할 수 없습니다. LAN에서 공유하려면 리스닝 주소, 운영체제 방화벽, 인바운드 인증, 기기 간 네트워크 연결 가능 여부도 함께 고려해야 합니다. ‘LAN 연결 허용’을 켜는 것만으로 다른 기기의 접근 권한이 보장되지는 않으며, 연결에 자동으로 인증이 적용되는 것도 아닙니다.

다음은 HTTP 인바운드 객체 하나만 보여 줍니다. inbounds 배열의 항목으로 사용하세요. 앞에서 본 SOCKS 인바운드와 포트가 달라 애플리케이션 설정에서 쉽게 구분할 수 있습니다. 포트 번호는 로컬에서 사용하는 값일 뿐 원격 서비스 포트를 뜻하지 않습니다. 애플리케이션에서 요청이 나가지 않는다면 시스템 프록시가 이전 주소를 가리키는지 먼저 확인하고, 클라이언트가 실제로 해당 객체를 불러왔는지 살펴보세요. 흔히 쓰이는 포트 번호라는 이유만으로 시스템에 해당 서비스가 실행 중이라고 가정하지 마세요.

{
  "tag": "local-http",
  "listen": "127.0.0.1",
  "port": 10809,
  "protocol": "http",
  "settings": {}
}

UDP와 스니핑의 범위 이해하기

SOCKS 인바운드의 udp 스위치는 해당 인바운드에서 SOCKS UDP 요청을 처리하도록 허용한다는 뜻입니다. 모든 애플리케이션의 UDP 트래픽이 자동으로 코어에 전달되는 것은 아닙니다. 애플리케이션이 해당 프록시 방식을 지원해야 하며, 이후 아웃바운드와 네트워크 경로에서도 전달을 허용해야 합니다. 시스템 HTTP 프록시만 설정하면 일부 실시간 통신이나 게임 트래픽은 기존 경로를 계속 사용할 수 있습니다. 이 경우 애플리케이션이 지원하는 프록시 방식을 먼저 확인한 뒤 TUN 모드 안내를 살펴보세요. 리스닝 포트만 계속 바꾸지는 마세요.

스니핑은 연결 초기에 전송되는 데이터를 바탕으로 대상 정보를 알아내는 기능이며, 도메인 라우팅을 보조하는 데 쓰입니다. 모든 애플리케이션 데이터를 복호화하는 기능도, DNS 해석을 대신하는 기능도 아닙니다. 코어마다 지원하는 스니핑 필드와 대상 프로토콜, 라우팅 전용 옵션이 다를 수 있으므로 추가 전에 현재 구현을 확인하세요. 스니핑을 켠 뒤 일부 앱에서 이상 동작이 나타나면 나머지 설정은 유지하고 스니핑만 끈 상태와 비교하세요. 한 번의 전체 속도 측정이 아니라 실제 연결을 기준으로 판단해야 합니다.

마지막으로 로그에서 인바운드가 정상적으로 바인딩됐는지 확인하세요. 주소가 이미 사용 중이라면 클라이언트가 중복 실행 중인지, 이전 프로세스가 남아 있는지, 클라이언트가 같은 이름의 인바운드를 자동 생성했는지 살펴보세요. 충돌을 피하려고 바로 모든 인터페이스에서 리스닝하도록 바꾸지 마세요. 포트를 변경했다면 애플리케이션의 프록시 주소도 함께 수정해야 합니다. 루프백 주소를 사용하는 앱은 IPv4와 IPv6의 차이도 확인하세요. 시스템에 따라 localhost가 서로 다른 주소로 먼저 해석될 수 있습니다.

03 / outbounds 아웃바운드와 기본 경로

실제로 선택된 아웃바운드 찾기

아웃바운드는 코어가 요청을 받은 뒤 연결을 다음 단계로 전달하는 방식을 결정합니다. 주요 유형으로는 대상에 직접 연결, 원격 프록시 서버 연결, 요청 차단이 있습니다. 먼저 routing에서 트래픽이 특정 태그를 가리키는지 확인한 뒤 해당 아웃바운드 객체를 살펴보세요. 원격 프록시 아웃바운드가 목록에 있어도 모든 연결이 그 아웃바운드를 사용하는 것은 아닙니다. 규칙이 직접 연결을 먼저 선택하거나 태그 오류로 설정을 불러오지 못할 수 있습니다. 문제를 확인할 때는 ‘객체가 있음’과 ‘객체가 사용됨’을 구분하세요.

라우팅 규칙에 일치하지 않을 때는 보통 outbounds 배열의 첫 번째 항목이 기본으로 사용됩니다. 따라서 배열 순서를 바꾸면 규칙에 걸리지 않은 트래픽의 경로가 바로 달라질 수 있습니다. 읽기 편하다는 이유만으로 직접 연결 객체를 목록 맨 앞에 옮기지 마세요. 클라이언트는 대개 자체 모드에 따라 순서를 생성하며, 사용자 지정 설정에서는 기본 아웃바운드를 명확하게 설계해야 합니다. 태그 이름만 보고 추측하기보다 기본 동작을 유지보수 기록에 남겨 두세요. ‘프록시’라는 태그가 직접 연결 객체를 가리킬 수도 있습니다.

직접 연결, 차단, 원격 프로토콜 구분하기

freedom은 흔히 사용하는 직접 연결 아웃바운드이고 blackhole은 요청을 차단하는 데 사용됩니다. 둘 다 원격 계정이 필요하지 않지만, 선택된 경우에만 작동합니다. 차단된 연결의 결과가 항상 같지는 않습니다. 앱에 연결 실패가 표시되거나 재시도 대기 상태가 될 수 있고, 다른 주소로 다시 요청할 수도 있습니다. 페이지가 최종적으로 열렸다고 해서 차단 규칙이 작동하지 않았다고 단정할 수 없습니다. 어떤 연결이 차단됐는지, 앱이 후속 요청을 보냈는지도 확인하세요.

다음은 로컬 라우팅 실험에 사용할 수 있는 전체 아웃바운드 배열입니다. 직접 연결과 차단만 포함하며 원격 프록시 기능은 없습니다. tag는 라우팅 규칙에서 참조하고, 프로토콜 이름은 코어가 구현 방식을 선택할 때 사용합니다. 둘은 서로 바꿔 쓸 수 없습니다. 뒤 장에서 outboundTag를 사용한다면 여기의 태그와 정확히 일치해야 합니다. 대소문자, 하이픈, 불필요한 공백도 참조 불일치의 원인이 될 수 있으므로 이름을 바꿀 때는 모든 참조 위치를 함께 검색하세요.

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

원격 프록시 아웃바운드에는 프로토콜에 맞는 서버 주소, 포트, 인증 매개변수를 입력해야 합니다. VMess, VLESS, Trojan은 인증 구조가 서로 다르므로 한 프로토콜의 사용자 객체를 다른 프로토콜에 가져오면 안 됩니다. 구독에서 생성된 설정에는 흐름 제어, 암호화, 보안 계층 등의 추가 필드가 포함될 수도 있습니다. 먼저 클라이언트에서 원본 연결 정보가 완전한지 확인한 다음 생성된 객체를 살펴보세요. 원본 정보에 필드가 빠져 있다면 라우팅을 수정해도 서버 인증 정보가 채워지지는 않습니다.

프로토콜 이름만으로 연결 조건을 판단하지 마세요

하나의 프록시 프로토콜도 여러 전송 방식 및 보안 계층과 함께 사용할 수 있습니다. 두 설정에 모두 VLESS가 적혀 있어도 전송 경로, 서비스 이름, TLS 서버 이름, 보안 매개변수가 다르면 서로 바꿔 쓸 수 없습니다. 서버 주소는 연결을 설정하는 데 사용하고, 인증서 검증 이름은 원격 서버의 신원을 확인합니다. 두 값은 같을 수도, 다를 수도 있습니다. 서비스에서 제공한 정보를 각각의 필드에 맞게 입력하세요. 비슷해 보이는 필드에 같은 도메인을 무조건 넣거나 구독 그룹 이름을 네트워크 주소에 입력하지 마세요.

여러 아웃바운드를 구성할 때는 연결 루프도 방지해야 합니다. 프록시 아웃바운드가 원격 서버에 연결하는 트래픽을 클라이언트의 전역 가로채기 기능이 다시 같은 인바운드로 보내면 순환이 발생할 수 있습니다. 그래픽 클라이언트는 자체 프로세스, 서버 주소, 바인딩 인터페이스 등을 고려해 처리하는 경우가 많으므로 사용자 지정 설정에서 해당 구성을 함부로 제거하지 마세요. 연결 수가 계속 늘거나 로그에 같은 주소가 반복되면 새로 추가한 체인 전달과 전역 가로채기를 먼저 끄고 단일 아웃바운드로 복구해 확인하세요.

원격 서버에 연결되지 않을 때는 주소, 포트, 인증, 전송, 보안 계층 순으로 확인하세요. TCP 연결이 된다는 것은 기본 네트워크 경로에 도달할 수 있다는 뜻일 뿐, 프록시 프로토콜 핸드셰이크 성공을 보장하지 않습니다. 지연 시간 측정과 실제 웹 요청이 서로 다른 대상을 사용할 수도 있습니다. 지표를 비교하려면 노드 속도 측정 지표 안내를 참고하고 측정 대상을 먼저 확인하세요. 한 번의 낮은 지연 시간만으로 아웃바운드 설정 전체가 올바르다고 판단하지 마세요.

04 / 전송 매개변수와 보안 계층

프로토콜, 전송, 암호화 연결을 나눠 확인하기

먼저 세 가지를 구분하세요. 프록시 프로토콜은 인증과 요청을 구성하는 방식, 전송 방식은 해당 데이터를 전달하는 방식, 보안 계층은 외부 연결을 보호하고 신원을 검증하는 방식입니다. 클라이언트에서는 한 화면에 함께 표시되기도 하지만 서로 다른 설정 계층에 속합니다. 프록시 프로토콜이 맞아도 전송 설정이 틀리면 연결할 수 없고, 전송 연결이 성립해도 인증 정보가 틀리면 이후 단계에서 거부됩니다. 문제를 해결할 때는 실패한 계층을 구체적으로 짚고, 모든 실패를 노드 문제로 뭉뚱그리지 마세요.

일반적인 설정에서 streamSettings는 전송 및 보안 관련 옵션을 구성합니다. 해당 인바운드나 아웃바운드 객체 안에 둘 수 있으며, 최상위에 넣는다고 전체에 적용되는 공통 스위치가 아닙니다. 코어마다 지원하는 전송 이름과 전용 필드가 다르고, 같은 기술도 단계에 따라 설정 방식이 달라질 수 있습니다. 오래된 문서의 객체 전체를 덮어쓰기보다는 클라이언트가 현재 생성한 구조를 유지하면서 사용 중인 코어의 안내에 맞춰 수정하는 편이 안전합니다.

TLS 이름 및 인증 설정을 확인하기

TLS는 암호화 연결을 만들고 원격 서버의 신원을 검증하는 여러 메커니즘을 가리킵니다. 먼저 보안 유형을 확인한 다음 serverName이 서비스에서 제공한 값과 일치하는지 살펴보세요. 이 이름은 보통 서버 이름 표시와 인증서 검증에 사용되며 임의로 적는 메모가 아닙니다. 연결 주소에 IP를 사용한다고 해서 검증 이름도 같은 IP로 바꿔야 하는 것은 아닙니다. 원격 인증서가 도메인용이라면 이름을 임의로 바꿀 경우 연결 가능한 서비스도 핸드셰이크 단계에서 실패할 수 있습니다.

다음은 필드 구조를 보여 주는 일반적인 TLS 설정 객체입니다. example.com은 문서용 예제 도메인이므로 실제 서비스 매개변수에 맞춰 바꿔야 하며, 이 값만으로 프록시 연결을 설정할 수는 없습니다. 전송 유형은 예제에 지정하지 않았습니다. 실제 서비스와 일치해야 하기 때문입니다. allowInsecure를 꺼 두면 인증서 검증을 임의로 건너뛰지 않습니다. 검증을 끄는 것을 일반적인 해결 방법으로 사용하지 마세요. 이름, 인증서 체인, 기기 시간의 오류를 가릴 수 있습니다.

{
  "streamSettings": {
    "security": "tls",
    "tlsSettings": {
      "serverName": "example.com",
      "allowInsecure": false
    }
  }
}

인증서 오류가 발생하면 먼저 기기의 날짜와 시간대, 서버 이름, 서비스 주소, 네트워크 환경을 확인하세요. 시스템 시간이 맞지 않으면 인증서가 아직 유효하지 않거나 이미 만료된 것처럼 보일 수 있습니다. 일부 네트워크에서는 포털 로그인을 먼저 완료해야 하며, 이 경우 요청이 대상 서비스가 아닌 로그인 페이지로 전달될 수 있습니다. 기본 조건을 확인한 다음 코어 로그에 표시된 구체적인 핸드셰이크 오류를 살펴보세요. 브라우저에서 특정 사이트가 열린다고 해서 프록시 서비스의 TLS 설정까지 모두 올바르다는 뜻은 아닙니다.

전송 방식에 맞춰 경로와 서비스 이름 설정하기

WebSocket에서는 경로와 관련 요청 헤더가 서버 측 트래픽 분기에 사용될 수 있고, gRPC에서는 서비스 이름이 별도 매개변수로 쓰입니다. 서로 대체할 수 없으며 인터페이스의 ‘호스트’라는 표기만 보고 의미를 추측해서도 안 됩니다. 매개변수를 복사할 때 경로 앞의 슬래시와 대소문자를 유지하고, 빈 문자열과 필드 생략이 서로 다른 의미인지 확인하세요. 서비스 주소, HTTP 호스트 필드, TLS 이름은 각각 다른 역할을 맡을 수 있으므로 모양을 통일하려고 같은 값으로 억지로 바꾸지 마세요.

REALITY는 특정 코어에서 지원하는 보안 방식입니다. 다른 코어도 VLESS를 지원한다는 이유만으로 관련 필드를 모두 공통으로 사용할 수 있다고 가정하지 마세요. 공개 키, 짧은 ID, 흐름 제어 설정은 서버 측 약속 및 현재 코어 구현에 맞춰 하나씩 확인해야 합니다. 서로 다른 연결 정보의 매개변수를 조합해 실제로는 작동하지 않는 설정을 만들지 않도록 원격 연결 예제를 임의로 조립해 제공하지 않습니다. 클라이언트에 가져온 뒤에는 먼저 매개변수를 그대로 유지해 테스트하고, 이후 한 번에 하나씩 조정하세요.

전송 설정과 연결 재사용도 구분하세요. 연결 재사용은 여러 애플리케이션 연결이 하위 채널을 공유하는 방식을 바꾸지만, 잘못된 인증서 이름, 전송 경로, 인증 매개변수를 자동으로 수정하지는 않습니다. 변수를 분리하려면 원래 연결 조건에서 먼저 확인한 뒤 호환되는 재사용 방식을 적용할지 결정하세요. 일부 프로토콜, 흐름 제어, 전송 조합에는 재사용 관련 추가 제약이 있을 수 있으므로 다른 설정에서 스위치 하나만 복사하면 안 됩니다. 재사용을 켠 뒤 간헐적 연결 끊김이 나타나면 별도 변수로 보고 원복해 테스트하세요.

05 / routing 라우팅 규칙과 적용 순서

첫 번째 규칙부터 순서대로 읽기

라우팅은 각 연결에 사용할 아웃바운드를 선택합니다. 먼저 rules 배열을 순서대로 읽고 처음 조건에 맞는 규칙을 찾은 다음 해당 규칙이 가리키는 아웃바운드를 확인하세요. 규칙 목록을 모든 조건이 차례로 적용되는 목록으로 이해하면 안 됩니다. 범위가 넓은 규칙이 앞에 있으면 뒤의 세부 규칙이 적용될 기회를 잃을 수 있습니다. 규칙을 추가할 때는 어떤 연결에 영향을 줄지 먼저 정하고 삽입 위치를 선택하세요. 습관적으로 맨 끝에 추가하지 마세요.

한 규칙의 여러 조건은 보통 함께 적용되어 일치 범위를 좁힙니다. 예를 들어 인바운드 태그와 대상 도메인이 모두 맞아야 할 수 있습니다. 하나의 조건 배열에 후보가 여러 개 있으면 대개 그중 하나에 일치하면 됩니다. 구체적인 조합 방식은 현재 코어 구현을 확인하세요. 처음 디버깅할 때는 조건 하나로 대상을 검증한 뒤 제한을 차례로 추가하세요. 인바운드, 포트, 프로토콜, 도메인을 처음부터 모두 지정하면 정밀해 보일 수 있지만 일치하지 않는 원인을 찾기 어려워집니다.

외부 리소스가 필요 없는 규칙부터 사용하기

다음은 첫 번째 장의 로컬 예제에 합칠 수 있는 routing 객체입니다. 세 번째 장의 block 아웃바운드도 함께 추가해야 합니다. 문서용 예제 도메인은 차단 아웃바운드로 보내고 나열된 사설 주소 범위는 직접 연결 아웃바운드로 보냅니다. 그 외 트래픽은 기존 설정의 기본 아웃바운드를 사용합니다. 외부 도메인 분류 파일이 필요하지 않아 참조 방식과 순서를 이해하기 쉽습니다. 다만 LAN 주소 전체를 포함하지 않으므로 운영 환경의 분기 설정으로 바로 사용할 수는 없습니다.

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

도메인 일치 방식을 명확히 선택하세요. full:은 도메인 전체와 일치하고, domain:은 보통 해당 도메인과 하위 도메인에 일치합니다. 정규식은 더 특수한 패턴에 적합합니다. 일반 문자열은 접두사 형식과 일치 방식이 다르므로 규칙을 작성하기 전에 예상 동작을 확인하세요. 한 사이트의 연결을 제어하려면 정적 리소스, 로그인, API가 다른 도메인에 있을 수 있다는 점도 고려해야 합니다. 첫 페이지의 도메인만 일치시키면 앱에서 실제로 만드는 연결을 모두 포함하지 못할 수 있습니다.

라우팅 단계의 DNS 해석과 최종 연결의 DNS 해석 구분하기

domainStrategy는 라우팅 단계에서 대상 도메인을 처리하는 방식을 정합니다. 흔히 사용하는 AsIs는 IP 규칙을 위해 도메인을 적극적으로 해석하지 않습니다. IPIfNonMatch는 도메인 규칙이 일치하지 않을 때 해석을 시도해 IP 조건이 적용될 기회를 제공합니다. IPOnDemand는 일치 과정에서 IP가 필요한 규칙을 만났을 때 해석을 시도합니다. 이 설정은 라우팅 판단 방식에 영향을 주며 전역 DNS 아웃바운드 스위치가 아닙니다. 모든 앱의 최종 DNS 해석 방식을 직접 정하지도 않습니다.

더 적극적인 해석 전략을 선택하기 전에 대상 IP 기준으로 분기해야 하는지 확인하세요. 추가 해석은 대기 시간, 캐시, 응답 주소 변경 등의 변수를 더할 수 있습니다. 같은 도메인에서 주소 여러 개가 반환될 수 있으며 코어가 이를 기준으로 어떻게 일치시키는지도 실제 동작으로 확인해야 합니다. 대상이 처음부터 IP라면 도메인 규칙으로 원래 도메인을 복원할 수 없습니다. 스니핑이 일부 프로토콜에서 정보를 보완할 수 있지만 모든 연결에 적용되지는 않으며 암호화된 앱 트래픽을 모두 식별한다고 보장할 수도 없습니다.

geosite와 geoip는 분류 데이터를 참조하는 방식이며, 문자열에 입력한다고 온라인 조회가 자동으로 이루어지는 것은 아닙니다. 규칙을 사용하려면 코어 지원 여부, 리소스 파일 존재 여부, 분류 이름의 정확성, 클라이언트의 리소스 관리 방식을 확인해야 합니다. 분류 로드 오류가 발생하면 먼저 명시적인 도메인 또는 주소 규칙으로 되돌려 확인하세요. 한 환경에서 사용하던 분류 태그를 다른 환경에 그대로 복사하면서 필요한 데이터 출처와 파일 위치를 놓치지 마세요.

라우팅을 조정한 뒤에는 대상이 분명한 요청 하나로 확인하세요. 기존 연결을 정리하고 새 연결이 어떤 아웃바운드를 사용하는지 살펴본 다음 관련 앱의 다른 도메인도 테스트합니다. 기존의 장기 연결은 이전 경로를 계속 사용할 수 있어 설정을 바꿔도 한동안 동작이 달라지지 않을 수 있습니다. 우회 연결이나 오차단이 발생하면 ‘인바운드 태그, 대상 정보, 처음 일치한 규칙, 아웃바운드 태그’ 순서로 확인하세요. 일반적인 사용 질문은 자주 묻는 질문에서 찾아볼 수 있습니다. 설정 전체를 먼저 초기화할 필요는 없습니다.

06 / dns DNS 해석기와 분기 범위

도메인을 누가 해석하는지 먼저 확인하기

DNS는 도메인을 네트워크 주소로 변환하는 조회 방식입니다. 애플리케이션이 도메인을 프록시에 전달하는지, 이미 해석된 IP를 전달하는지 먼저 확인한 다음 코어의 DNS 설정을 살펴보세요. 브라우저, 운영체제, 코어, 원격 서버가 각각 해석에 관여할 수 있습니다. 설정에 dns 객체가 있다고 해서 기기의 모든 조회가 그 객체를 거치는 것은 아닙니다. 앱이 별도의 암호화 DNS를 사용하면 시스템 기본 해석 경로를 우회할 수 있으므로 앱 설정과 코어 설정을 함께 확인하세요.

코어 내장 해석기는 IP 라우팅이나 일부 직접 연결 아웃바운드처럼 도메인 해석이 필요한 내부 기능에 사용되는 경우가 많습니다. 원격 프록시가 도메인을 받으면 최종 해석을 원격에서 수행할 수도 있습니다. 이렇게 두 번 해석할 때 같은 서버를 사용하는 것은 아니며 결과도 다를 수 있습니다. 문제를 점검할 때는 조회가 발생한 위치, 조회한 도메인, 반환된 주소를 기록하세요. 시스템 기본 조회 도구의 결과만으로 코어도 같은 응답을 받았다고 추측하지 마세요.

조회 목적에 맞는 서버 선택하기

다음은 DNS 객체의 일부 예제입니다. 문서용 예제 도메인은 지정한 해석기를 우선 사용하고 나머지 조회는 다른 해석기를 사용할 수 있습니다. 예제 주소는 공개 DNS 서비스 주소입니다. 사용 전에 현재 네트워크에서 접속할 수 있는지, 해당 서비스에 조회 정보가 전달되는지 확인하세요. 이 조각은 servers의 객체 및 문자열 형식을 설명하기 위한 것이며 모든 지역과 네트워크에 적합한 설정은 아닙니다. 조회가 반드시 프록시 아웃바운드를 통과한다고 보장하지도 않습니다.

{
  "dns": {
    "servers": [
      {
        "address": "223.5.5.5",
        "domains": ["domain:example.com"],
        "skipFallback": true
      },
      "1.1.1.1"
    ],
    "queryStrategy": "UseIP"
  }
}

domains는 서버가 우선 처리할 도메인 범위를 지정하며, 해당 서버만 항상 사용한다는 뜻은 아닙니다. 실패 후의 대체 동작은 전역 폴백 설정과 개별 서버 옵션의 영향을 받습니다. skipFallback은 보통 해당 서버가 관련 없는 도메인의 폴백 조회에 참여하지 않도록 하는 옵션이지, 일치하는 도메인에 해당 서버만 절대적으로 사용하게 하는 설정은 아닙니다. 해석 경로를 엄격하게 분리해야 한다면 현재 코어의 폴백 동작도 확인하고 로그나 조회 기록으로 검증하세요.

반환 주소 필터링과 주소 계열 이해하기

expectIPs는 예상 응답 주소 범위를 제한합니다. 해석 결과를 필터링하는 설정이지 연결을 특정 아웃바운드로 자동 전달하지는 않습니다. 범위를 지나치게 좁히면 정상적인 콘텐츠 전송 주소까지 거부될 수 있습니다. 분류 리소스에 의존하는 형식으로 범위를 지정했다면 해당 리소스가 실제로 있는지도 확인하세요. 서버가 응답하지 않는 것이 아니라 응답이 필터 조건에 맞지 않아 해석에 실패할 수도 있습니다. 먼저 필터를 제거해 비교한 뒤 더 정확한 범위가 필요한지 판단하세요. 대상 도메인이 작동하지 않는다고 바로 단정하면 안 됩니다.

queryStrategy는 조회할 주소 계열을 정합니다. IPv4와 IPv6를 함께 고려하거나 둘 중 하나만 조회하는 방식이 흔합니다. 기기에 IPv6 주소가 있다고 해서 모든 대상까지 IPv6 경로를 사용할 수 있다는 뜻은 아닙니다. 반대로 IPv4만 조회하면 일부 네트워크 환경에서 실제로 가능한 연결을 놓칠 수 있습니다. 설정 전에 현재 경로와 아웃바운드 지원 여부를 확인하세요. 일시적인 시간 초과 하나를 없애려고 원인을 기록하지 않은 채 주소 계열 전체를 영구적으로 끄지 마세요.

hosts는 코어 해석기에서 정적 매핑을 제공할 수 있지만 시스템의 모든 앱에 적용되는 전역 호스트 테이블은 아닙니다. 매핑을 사용하면 일반적인 해석 업데이트를 건너뛰므로 통제된 테스트나 명확한 로컬 요구에 적합합니다. 주소가 자주 바뀌는 공개 서비스에 장기간 적용하는 것은 적합하지 않습니다. 매핑한 뒤에도 TLS에서 어떤 이름을 검증하는지, 매핑된 주소를 기준으로 라우팅이 다시 적용되는지 고려해야 합니다. 정적 주소로 연결된다고 해서 원래 DNS 서비스가 복구된 것은 아닙니다.

암호화 DNS를 사용할 때는 부트스트랩 해석과 연결 경로를 함께 고려해야 합니다. 해석 서비스 자체가 도메인 이름을 사용한다면 먼저 서비스 주소를 찾는 방법이 필요합니다. 이 과정이 다시 같은 서비스에 의존하면 시작 단계에서 순환이 발생할 수 있습니다. 조회 프로토콜, 직접 전송 방식, 라우팅 연동 문법은 코어마다 다르므로 주소 접두사만 바꾸고 분기 설정이 끝났다고 판단하지 마세요. 먼저 단순한 DNS 설정으로 기준을 만든 다음 해석 서비스 연결과 대상 도메인 결과를 각각 확인하세요.

마지막으로 캐시를 정리한 뒤 변경 결과를 비교하세요. 앱 캐시, 시스템 캐시, 코어 캐시, 사용 중인 연결에 이전 결과가 남아 있을 수 있습니다. 구성 요소 하나를 재시작해도 나머지 구성 요소의 상태가 지워진다고 보장할 수 없습니다. 테스트 도메인 하나를 정해 변경 전후의 주소 계열, 반환 주소, 실제 아웃바운드를 기록하세요. 중국 본토와 해외 도메인의 분리 해석에 관한 추가 안내는 DNS 분리 해석 설정 노트를 참고하세요. DNS 해석 분리를 연결 라우팅과 같은 의미로 보면 안 됩니다.

07 / policy 정책과 실행 상태

기본값을 유지한 채 시간 초과 원인 파악하기

policy는 일부 연결의 수명과 통계 동작을 제어하며 자동으로 속도를 높이는 기능이 아닙니다. 먼저 기본 정책으로 실행하고, 로그와 재현 절차에서 특정 시간 조건이 원인으로 확인될 때만 조정을 고려하세요. 네트워크가 느리거나 서버 응답이 늦거나 앱 전송이 멈춘 경우 모두 대기 현상으로 보일 수 있지만 원인은 다릅니다. 모든 시간 제한을 늘리면 실패가 늦게 나타날 뿐일 수 있고, 전부 줄이면 유지할 수 있는 유휴 연결까지 너무 일찍 종료될 수 있습니다.

정책은 사용자 등급별로 구성하는 경우가 많습니다. levels 객체의 키는 등급 번호를 나타내며 프로토콜 사용자의 등급 설정과 연결됩니다. 노드 순서나 클라이언트 창의 그룹 번호가 아닙니다. 명시적으로 지정하지 않는 일반적인 상황에서는 기본 등급을 사용합니다. 여러 사용자나 인바운드가 설정되어 있다면 해당 연결에 실제로 어떤 등급이 적용되는지 먼저 확인한 뒤 사용자 지정 정책이 적용될지 판단하세요. 참조되지 않는 등급 객체만 추가해도 현재 연결은 보통 달라지지 않습니다.

연결 단계에 따라 시간 필드 이해하기

다음은 정책 객체 예제입니다. 시간 필드의 단위는 초이며 버퍼 필드는 킬로바이트 단위입니다. 값은 필드 간 관계를 설명하기 위한 것으로 모든 기기에 적용되는 최적화 설정이 아닙니다. 일부 필드의 적용 범위는 코어 구현에 따라 다르며, 특히 프로토콜과 버퍼 관리에 관련된 동작은 현재 코어를 기준으로 확인해야 합니다. 설정에 합친 뒤에는 코어가 정상적으로 시작되는지 확인하고 같은 앱과 같은 작업으로 비교하세요. 아웃바운드까지 동시에 바꾸지 마세요.

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

handshake는 해당 연결의 핸드셰이크 단계에서 대기할 수 있는 시간을 제한합니다. 웹 페이지 전체 로딩 시간이나 앱의 파일 다운로드 시간을 제어하는 값은 아닙니다. 연결을 맺기 전에 항상 실패한다면 대기 시간을 늘리기 전에 주소, 포트, 전송 협상을 확인하세요. 기본 매개변수가 잘못된 경우 대기 시간만 늘리면 실패를 늦게 알게 될 뿐이며 호환되지 않는 프로토콜을 연결 가능하게 만들지는 않습니다.

connIdle은 연결이 유휴 상태로 유지되는 시간 제한을 나타냅니다. 푸시 알림, 채팅, 원격 세션은 한동안 눈에 띄는 데이터 교환이 없을 수 있어 유휴 제한이 너무 짧으면 앱이 계속 재연결할 수 있습니다. 반대로 제한이 지나치게 길면 쓸모없어진 연결이 더 오래 남습니다. 앱 계층의 하트비트, 하위 네트워크 연결 유지, 코어 정책을 구분하세요. 각 설정은 서로 다른 계층에 속하므로 한 계층에서 연결 유지를 설정했다고 다른 계층에서도 연결이 살아 있다고 판단하는 것은 아닙니다.

uplinkOnly와 downlinkOnly는 연결의 한쪽 방향이 종료된 뒤 반대 방향을 얼마나 유지할지 다룹니다. 업로드와 다운로드 속도 제한이 아닙니다. 일부 앱은 요청 전송을 먼저 끝낸 뒤 응답을 오래 기다릴 수 있으므로 한쪽 방향의 대기 시간을 지나치게 짧게 설정하면 응답이 잘릴 수 있습니다. ‘요청은 보냈지만 결과가 중간에 끊긴다’면 로그의 시간 흐름을 확인하세요. 필드에 업링크와 다운링크라는 이름이 있다고 해서 대역폭으로 해석하면 안 됩니다.

버퍼와 통계 설정도 함께 이해하기

bufferSize는 관련 연결의 버퍼 설정에 영향을 줍니다. 버퍼를 늘린다고 회선 대역폭이 바로 늘지는 않으며 여러 연결을 사용할 때 메모리 부담이 커질 수도 있습니다. 특히 Android 기기에서는 시스템이 프로세스를 종료하는 현상, 백그라운드 실행 제한, 큰 버퍼 설정이 겉으로 비슷하게 나타날 수 있으므로 마지막 연결 끊김만 보고 원인을 정하지 마세요. 먼저 시스템 리소스와 클라이언트 상태를 관찰한 뒤 설정 변경을 고려하세요. 불분명한 성능 조언을 모든 기기에 적용되는 고정값으로 사용하지 마세요.

통계 스위치도 켜기만 하면 사용자가 볼 수 있는 보고서가 자동으로 생성되는 것은 아닙니다. 코어 통계를 활용하려면 보통 통계 모듈, 조회 인터페이스, 클라이언트의 데이터 읽기 기능이 함께 필요합니다. 클라이언트 화면에 표시되는 트래픽은 다른 방식으로 계산될 수도 있습니다. 사용 전에 실제로 데이터를 읽는 구성 요소가 있는지 확인하고 설정을 완성된 것처럼 보이게 하려고 불필요한 인터페이스를 추가하지 마세요. 통계는 해당 측정 기준에 따른 데이터 양만 보여 줍니다. 실제 처리량, 응답 시간, 원격 서비스 품질을 판단할 수는 없습니다.

정책을 변경한 뒤에는 시작 로그, 앱 동작, 발생 시각을 함께 기록하세요. 클라이언트 프로세스 전체가 사라진다면 연결 시간 제한을 계속 늘리지 말고 프로세스 종료 원인과 시스템 제한을 먼저 확인하세요. 데스크톱 실행 환경, 압축 해제 경로, 설정 읽기 오류와 Android 권한 및 백그라운드 제한은 별도의 문제 해결 경로입니다. 시작 시 충돌 문제 해결을 참고해 구분하세요. 연결 정책은 실행 중인 연결에만 적용되며 아직 정상적으로 시작되지 않은 코어를 복구할 수 없습니다.

08 / 설정 검증 및 문제 해결 순서

코어 시작과 접속 성공을 나눠서 확인하기

먼저 변경 사항을 저장한 뒤 클라이언트에서 해당 설정을 다시 불러오세요. 인터페이스에서 예상한 설정이 선택되어 있는지 확인하고 로그에 표시된 실제 코어가 계획한 코어와 일치하는지 살펴보세요. 클라이언트에 연결 버튼이 실행 중으로 표시된다고 해서 시작 절차가 수행됐다는 것만 확인될 뿐, 리스닝, 라우팅, 원격 접속까지 검증된 것은 아닙니다. 사용자 지정 파일이 디스크에 있어도 현재 실행 중인 파일이라는 뜻은 아닙니다. 동작이 설정 내용과 전혀 다르면 읽히지 않는 파일을 계속 수정하지 말고 먼저 설정 출처를 확인하세요.

첫 단계는 설정 로드 확인입니다. 문법 오류, 필드 유형 오류, 알 수 없는 프로토콜, 분류 리소스 누락은 보통 실제 트래픽을 처리하기 전에 발생합니다. 로그에서 가장 마지막 프로세스 종료 메시지만 보지 말고 최근 수정과 관련된 첫 오류를 찾으세요. 구조 오류 하나를 고친 뒤 다음 오류가 나타날 수 있습니다. 그렇다고 수정이 소용없었던 것은 아닙니다. 현재 확인된 문제만 한 번에 하나씩 해결하고 시작 단계를 통과한 뒤 연결을 테스트하세요.

요청 경로를 따라 범위를 좁히기

두 번째 단계는 인바운드 확인입니다. 프록시 설정을 지원하는 앱 하나에서 요청을 보내고 주소, 포트, 프로토콜을 확인한 뒤 코어가 연결을 받는지 살펴보세요. 인바운드 기록이 없다면 앱 자체 프록시 옵션과 시스템 프록시 적용 범위를 먼저 확인하세요. 일부 프로그램은 시작할 때만 시스템 설정을 읽으므로 기존 연결을 닫거나 앱을 다시 시작해야 합니다. 시스템 프록시를 전혀 사용하지 않는 프로그램도 있습니다. 요청이 코어에 들어오는지 확인하기 전에 아웃바운드 인증을 원인으로 지목하지 마세요.

세 번째 단계는 라우팅과 DNS 확인입니다. 대상이 도메인과 IP 중 어떤 형식으로 들어오는지 확인하고, 순서에 따라 일치할 수 있는 규칙을 찾은 뒤 아웃바운드 태그를 점검하세요. 로그에 대상 정보가 부족하다면 통제된 테스트 중에만 로그 상세도를 일시적으로 높이세요. 테스트 후에는 원래대로 돌려야 합니다. 상세 로그에는 접속 도메인, 연결 주소, 로컬 경로가 포함될 수 있으므로 공유 전에 문제와 무관한 정보를 삭제하세요. 로그 수준은 관찰 가능성을 바꾸며 라우팅 결과를 자동으로 변경하지 않습니다.

네 번째 단계는 아웃바운드 핸드셰이크 확인입니다. 연결 거부, 응답 대기 시간 초과, 인증서 검증 실패, 사용자 인증 실패를 구분하세요. 각각 다른 단계의 문제를 가리킵니다. 연결 거부는 대상 포트와 서비스 상태를 먼저 확인하고, 시간 초과는 경로와 방화벽을 살펴보세요. 인증서 오류는 이름과 시간을, 인증 오류는 연결 정보를 확인해야 합니다. 모든 오류를 DNS 변경으로 해결하려고 하지 마세요. 항목별 안내는 실행 로그 해설에서 확인할 수 있습니다.

패치를 계속 덧붙이지 말고 통제된 방식으로 원복하기

기준 설정 하나와 현재 검증할 변경만 넣은 설정 하나를 준비하고 각각 변경 내용을 명확히 기록하세요. 테스트할 때는 같은 앱, 같은 대상, 같은 연결 방식을 사용해야 합니다. 서버와 라우팅을 동시에 바꾸면 어떤 변수가 영향을 줬는지 결과만으로 판단하기 어렵습니다. 새 규칙으로 일부 연결에 문제가 생겼다면 먼저 규칙을 되돌려 복구되는지 확인하세요. 복구되면 예외를 계속 추가하기보다 규칙 조건을 좁히는 편이 원인을 찾기 쉽습니다.

객체를 합칠 때 배열을 일반 텍스트 단락처럼 다루지 마세요. 완성된 routing 객체 두 개를 그대로 나란히 붙이면 중복 키나 구조 오류가 발생합니다. 두 번째 outbounds 객체를 첫 번째 객체 위에 덮어쓰면 라우팅에서 참조 중인 아웃바운드가 삭제될 수 있습니다. 먼저 유지할 상위 객체를 정한 다음 필요한 배열 항목만 하나씩 합치고 태그 고유성, 참조 관계, 기본 아웃바운드 순서를 확인하세요. 일부 파서가 중복 키를 허용하더라도 덮어쓰기 동작에 의존해서는 안 됩니다.

검증을 마치면 안정적으로 동작하는 설정을 계속 유지할 수 있는 위치로 옮긴 뒤 클라이언트 재시작, 설정 전환, 구독 업데이트 후에도 다시 확인하세요. 재시작할 때 이전 값으로 돌아간다면 변경 사항이 자동 생성 파일에만 남아 있다는 뜻입니다. 클라이언트가 지원하는 설정 메뉴로 돌아가 수정하세요. 최종 설정에는 사용한 코어, 수정한 계층, 필요한 분류 리소스, 원복 방법을 간단히 기록하세요. 관련 없는 기기 정보는 남길 필요가 없으며 인증 정보는 공개 메모에 적지 마세요.