설정 가이드 · JSON 참고

V2Ray 설정 파일 가이드

처음 설치하거나 구독을 가져온 뒤 연결을 확인하려면 입문 가이드의 빠른 시작 절차를 먼저 따라 해 보세요. 이 페이지는 설정 항목을 찾아볼 수 있는 참고 자료입니다. 최소 설정으로 요청 처리 과정을 이해한 다음, 목차에서 수정할 부분을 찾아보세요.

JSON 구조와 요청 흐름

완전한 최소 설정 파일부터 시작하기

설정 파일은 최상위 객체 하나로 구성됩니다. 인바운드와 아웃바운드는 배열입니다. 코어가 여러 경로로 트래픽을 받거나 여러 전송 경로를 둘 수 있기 때문입니다. 라우팅, DNS, 정책은 대개 각각 독립된 객체로 설정합니다. 파일에 적힌 순서대로 설정이 실행되는 것은 아닙니다. 요청을 처리할 때 각 설정이 별도로 판단에 참여하며, 설정이 파일에 있다고 해서 모든 요청에 적용되는 것도 아닙니다.

아래의 완전한 예제는 로컬 SOCKS 인바운드 하나만 열고, 아웃바운드는 직접 연결로 설정합니다. 앱의 요청이 코어에 전달되고 코어가 대상 서버에 연결되는지 확인할 때 사용할 수 있습니다. 원격 서버나 계정은 필요하지 않으며, 클라이언트 설치 후의 기본 설정을 뜻하지도 않습니다. 사용자 지정 코어 설정을 가져올 수 있는 화면에서 이 파일을 불러오기 전에 해당 로컬 포트를 다른 설정이 사용 중인지 확인하세요. 앱에서는 SOCKS5를 선택해야 하며, 이 인바운드를 HTTP 프록시로 사용하면 안 됩니다.

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

요청은 먼저 인바운드에 도착합니다. 인바운드는 자체 프로토콜에 따라 요청을 해석해 앱이 접속하려는 대상을 확인합니다. 라우팅 규칙이 없는 이 파일에서는 요청이 목록의 첫 번째 아웃바운드로 전달됩니다. 직접 연결 아웃바운드는 현재 기기에서 대상 서버로 연결합니다. 대상에 접속할 수 있는지는 운영체제의 네트워크 환경에 따라 달라집니다. 대상에 접속할 수 있다는 사실은 이 로컬 경로가 작동한다는 뜻일 뿐, 다른 원격 아웃바운드도 사용할 수 있다는 의미는 아닙니다.

필드 유형, 태그, 설정 예제

필드 이름과 문자열은 큰따옴표로 감쌉니다. 예제의 포트는 숫자이고, 스위치는 불리언 값입니다. 객체와 배열에는 서로 다른 괄호를 사용하며, 마지막 항목 뒤에는 쉼표를 붙이지 않습니다. 같은 객체에 동일한 필드를 두 번 쓰지 마세요. 파서에 따라 뒤의 값만 적용되어 앞서 수정한 내용이 반영되지 않을 수 있습니다. 저장할 때는 표준 JSON을 유지하세요. 일부 코어가 확장 문법을 지원하더라도 클라이언트 간 설정을 가져올 때는 확장 문법에 의존하지 않는 편이 안전합니다.

필드형식기능
inbounds배열앱 요청 수신
outbounds배열요청 전달 또는 거부
routing객체조건에 따라 아웃바운드 선택
dns객체코어 내장 DNS 설정
policy객체연결 동작과 통계 설정

태그는 설정 내부에서 사용하는 이름이지, 창에 표시되는 별칭이 아닙니다. 라우팅에서 대상 태그를 지정하면 코어는 문자열을 기준으로 아웃바운드를 찾습니다. 인바운드와 아웃바운드에 역할을 알기 쉽고 서로 겹치지 않는 태그를 지정하면 이름을 바꿀 때 실수를 줄일 수 있습니다. 예를 들어 직접 연결 아웃바운드의 이름을 바꿨다면 아웃바운드 배열에 새 이름이 있는지만 볼 것이 아니라 라우팅에서 이전 이름을 참조하는지도 확인해야 합니다.

이후 나오는 짧은 예제는 완전한 설정 파일에 합치는 조각입니다. 기존 객체 뒤에 두 번째 최상위 객체를 추가하면 안 됩니다. 배열을 교체하기 전에 원래 배열의 인바운드를 앱에서 계속 사용하는지 확인하세요. 설정에는 클라이언트가 인터페이스나 통계를 위해 생성한 전용 항목이 들어 있을 수도 있습니다. 특히 그래픽 인터페이스에서 서버를 계속 바꿔 사용할 예정이라면 이런 항목을 통째로 덮어쓰기보다 유지하는 편이 안전합니다.

구독 내용, 클라이언트에 저장된 옵션, 코어가 실제로 불러오는 설정 파일을 구분하세요. 구독에는 보통 서버 정보가 들어 있으며, 클라이언트는 로컬 포트와 라우팅 옵션에 맞춰 실행 설정을 생성합니다. 내보낸 파일을 수정해도 실행 중인 코어 설정은 자동으로 바뀌지 않습니다. 임시 실행 파일을 수정하면 다음에 서버를 바꿀 때 수정 내용이 덮어써질 수 있습니다. 먼저 어느 단계의 설정을 편집하는지 확인한 뒤, 인터페이스에서 저장할지 사용자 지정 설정으로 불러올지 결정하세요.

설정을 익힐 때는 기준 파일을 두 개 마련해 두세요. 하나는 수정하지 않은 완전한 로컬 설정이고, 다른 하나는 현재 장에서 다루는 필드만 추가한 복사본입니다. 실행 전에는 설정 출처와 리슨 포트를 기록하고, 실행 후 예상 결과와 비교하세요. 그러면 새 필드가 요청 동작을 바꾼 것인지, 클라이언트가 여전히 이전 파일을 불러오는지 구분할 수 있습니다. 규칙을 한꺼번에 많이 가져오는 것보다 필드 하나씩 검증하는 편이 재현하기 쉽습니다.

inbounds 인바운드 설정

리슨 주소, 포트, 프로토콜

인바운드는 로컬 앱이 코어에 연결할 경로를 정합니다. listen은 리슨 주소, port는 포트, protocol은 코어가 수신한 요청을 해석하는 방식을 지정합니다. 세 항목은 앱에 입력한 프록시 주소와 일치해야 합니다. 앱의 프록시 유형을 잘못 설정하면 요청이 같은 포트에 도착하더라도 코어가 대상 주소를 제대로 읽지 못합니다.

현재 기기에서만 사용할 때는 예제처럼 IPv4 루프백 주소에 명시적으로 바인딩하세요. 앱에 로컬 호스트 이름을 입력하면 시스템이 이를 IPv6 루프백 주소로 먼저 해석할 수 있습니다. IPv4만 리슨하는 인바운드는 이런 요청을 받지 못할 수 있습니다. 문제를 진단할 때는 설정에 적힌 IP 주소를 그대로 입력해 양쪽 주소를 일치시키세요. 루프백 주소가 일치하지 않는 문제를 해결하려고 리슨 범위를 전체 LAN으로 넓히지 마세요.

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

이 설정 조각으로 최소 설정의 인바운드 배열을 교체합니다. 두 인바운드가 서로 다른 포트를 사용하므로 앱이 어느 쪽에 연결되는지 확인하기 쉽습니다. 앱에서 HTTP 프록시를 선택했다면 HTTP 인바운드 포트를 지정하세요. SOCKS5를 테스트할 때는 해당 포트로 바꾸면 됩니다. 일부 클라이언트는 혼합 리슨을 생성할 수 있지만 이 설정에는 해당 기능이 활성화되어 있지 않습니다. 두 인바운드를 각각 사용하는 방법을 혼합 인바운드에 그대로 적용하지 마세요.

프록시 포트와 대상 포트를 혼동하지 마세요. 프록시 포트는 앱이 코어에 연결할 때 사용하는 로컬 포트이고, 대상 포트는 앱 요청에 포함되어 최종 접속 대상 서비스를 가리킵니다. 웹을 탐색할 때 앱은 로컬 HTTP 인바운드를 통해 대상 HTTPS 서비스로 터널 연결을 요청할 수 있습니다. 대상 서비스의 포트는 그대로 사용하며 로컬 프록시 포트를 바꿀 필요가 없습니다. HTTP 인바운드라는 이름은 프록시 핸드셰이크 방식을 가리킬 뿐, 대상이 평문 웹 요청만 받는다는 뜻은 아닙니다.

프로토콜 기능과 로컬 테스트

예제에서는 일반적인 TCP 요청부터 확인할 수 있도록 SOCKS의 UDP 기능을 꺼 두었습니다. 이 옵션을 켜도 시스템의 모든 UDP 트래픽이 코어를 통과하는 것은 아닙니다. 앱이 지원되는 방식으로 요청을 보내야 하며, 선택된 아웃바운드도 해당 트래픽을 처리할 수 있어야 합니다. 웹은 되지만 다른 기능의 연결이 불안정하다면, 먼저 해당 기능이 실제로 어떤 네트워크 프로토콜을 사용하는지 확인하세요. 모든 문제를 포트 오류로 뭉뚱그리지 마세요.

인증을 설정하지 않은 로컬 인바운드는 루프백 주소에서만 리슨해야 합니다. 로컬로 제한하더라도 해당 포트에 연결할 수 있는 다른 로컬 프로그램이 요청을 보낼 수 있습니다. 여러 사용자가 함께 쓰는 기기나 컨테이너 환경에서는 어떤 프로세스가 연결해야 하는지, 앱과 코어가 같은 네트워크 환경에 있는지 먼저 확인하세요. 컨테이너의 루프백 주소는 대개 해당 컨테이너만 가리키므로 호스트의 같은 주소에 접속할 수 없습니다.

리슨에 실패하면 같은 주소와 포트를 다른 인스턴스나 설정이 사용 중인지 먼저 확인하세요. 포트를 바꾼 뒤에는 브라우저의 수동 프록시, 시스템 프록시, 터미널 설정에 입력된 주소도 하나씩 업데이트해야 합니다. 코어 쪽 포트만 바꾸면 이전 인바운드 주소가 계속 참조될 수 있습니다. 포트 사용 여부를 확인하고 수정하는 순서는 로컬 포트 충돌 문제 해결을 참고하세요.

테스트할 때는 테스트 앱에서 다른 프록시 경로를 끄고, 명확한 인바운드 하나만 사용하세요. 코어가 정상적으로 설정을 불러오는지 확인한 다음 접속 가능 여부를 아는 대상으로 다시 테스트합니다. 그 후 아웃바운드를 바로 바꾸지 말고 다른 앱에서 같은 주소를 확인하세요. 이렇게 하면 문제 원인이 특정 앱의 프록시 설정인지 로컬 리슨인지 구분할 수 있습니다. 인바운드 하나만 작동하더라도 두 포트를 각각 확인해야 하며, 한쪽의 결과로 다른 쪽까지 판단하면 안 됩니다.

인바운드 설정에는 대상 식별 옵션이 포함되기도 합니다. 지원되는 트래픽에 라우팅용 정보를 추가할 수 있지만 모든 연결에서 원래 도메인을 복원할 수 있는 것은 아닙니다. 먼저 앱이 도메인을 보존해 요청했을 때의 규칙 일치 결과를 확인한 다음 추가 식별이 필요한지 판단하세요. 설정 이름이 같더라도 기본 동작까지 같은 것은 아닙니다. 특히 클라이언트가 인바운드를 자동 생성하는 경우 주의해야 합니다.

outbounds 아웃바운드 설정

직접 연결 및 거부 아웃바운드

아웃바운드는 요청이 코어를 떠난 뒤 어떻게 처리될지를 정합니다. 대상에 직접 연결하거나 원격 프로토콜로 전달하거나 트래픽을 거부할 수 있습니다. 목록에 있다고 해서 아웃바운드가 번갈아 요청을 처리하는 것은 아닙니다. 라우팅 규칙이 요청을 지정된 아웃바운드로 보내며, 일치하는 규칙이 없으면 일반적으로 목록의 첫 번째 항목이 요청을 처리합니다. 순서를 바꾸면 규칙에 걸리지 않은 모든 트래픽의 경로가 바뀔 수 있습니다.

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

이 설정으로 최소 설정의 아웃바운드 배열을 바로 교체할 수 있습니다. 직접 연결 아웃바운드는 첫 번째 항목으로 둡니다. 아직 어떤 규칙도 거부 아웃바운드를 참조하지 않으므로 요청을 자동으로 차단하지 않습니다. 다음 장에서는 테스트 도메인에 명시적인 거부 규칙을 추가합니다. 이 순서라면 기본 동작을 미리 파악하기 쉽고, 문제 발생 시 규칙이 적용된 것인지 대상에 접속할 수 없는 것인지 구분하기도 편합니다.

직접 연결은 코어가 실행 중인 기기에서 대상에 접속한다는 뜻이지, 앱이 로컬 코어를 우회한다는 의미는 아닙니다. 비교 테스트는 두 차례로 나눠 진행할 수 있습니다. 한 번은 앱에서 직접 접속하고, 다른 한 번은 로컬 인바운드와 직접 연결 아웃바운드를 거치게 합니다. 결과가 다르면 코어에 들어온 대상 정보와 DNS 해석 방식을 먼저 비교하세요. 두 방식 모두 실패하면 원격 노드부터 의심하지 말고 기기의 네트워크와 대상 서비스를 함께 확인하세요.

거부 아웃바운드는 규칙의 의도를 표현하는 용도이지 원격 서버의 상태를 확인하는 용도가 아닙니다. 앱에서는 거부된 요청을 연결 중단으로 표시하거나 단순히 접속 실패로 표시할 수 있습니다. 오류 메시지만 보고 규칙이 적용됐는지 판단하지 마세요. 한 가지 방법은 제어 가능한 테스트 대상을 지정한 규칙을 잠시 바꾼 뒤 변경 전후를 비교하고, 코어 로그에서 인바운드와 아웃바운드 태그를 함께 확인하는 것입니다.

원격 서버와 전송 설정

원격 아웃바운드는 보통 두 가지 설정이 모두 맞아야 합니다. 첫 번째는 서버 주소, 포트, 서비스 측에서 발급한 인증 정보 같은 프로토콜 매개변수입니다. 두 번째는 요청을 전달하는 전송 방식과 보안 설정으로, 전송 형식, 경로, 예상 서버 이름 등이 포함됩니다. 첫 번째가 맞다고 두 번째도 맞는 것은 아닙니다. 원격 서버와 기본 연결은 되지만 정상적으로 접속할 수 없다면 서비스에서 제공한 전체 설정을 항목별로 비교하세요.

settings의 구조는 프로토콜마다 다르므로 다른 프로토콜의 필드 구성을 그대로 가져오면 안 됩니다. streamSettings는 아웃바운드의 전송 방식과 관련 보안 설정을 지정하며 시스템 프록시 설정과는 다릅니다. 구독으로 아웃바운드를 생성했다면 클라이언트 화면에서 해당 필드가 구독 내용으로 채워졌는지 확인하세요. 오류를 없애려고 인증서 옵션을 일괄 교체하면 실제 원인인 서버 이름이나 시간 문제를 가릴 수 있습니다.

로컬 인바운드 주소와 원격 서버 주소는 서로 다른 방향의 연결 설정입니다. 원격 서버 포트를 로컬 프록시 포트에 입력해도 코어가 서버에 자동으로 연결되지는 않습니다. 반대로 로컬 루프백 주소를 원격 아웃바운드에 입력해도 실제 서버를 가리키지 않습니다. 값을 입력할 때는 어느 프로세스가 해당 설정을 읽는지, 연결의 상대가 누구인지 먼저 확인하세요. 서비스에서 제공한 도메인이 최종 접속 대상 웹사이트의 도메인과 다를 수도 있습니다.

직접 연결을 비교 기준으로 유지하려면 수동으로 추가한 원격 항목에 알아보기 쉬운 태그를 지정하고, 범위가 명확한 테스트 규칙 하나에서만 참조하세요. 규칙에 걸리지 않는 요청이 기존 경로로 처리되는지 먼저 확인합니다. 나중에 원격 항목을 교체할 때는 태그를 유지하거나 참조 규칙도 함께 수정하세요. 변경 하나의 영향을 확인할 때 기본 아웃바운드 순서를 동시에 바꾸지 마세요.

아웃바운드 문제를 설명할 때는 대개 프로토콜, 전송 방식, 오류가 발생한 단계, 민감 정보를 가린 필드 구조만 있으면 됩니다. 실제 인증 정보가 스크린샷이나 공개 설정 파일에 노출되지 않도록 주의하세요. 로컬 인바운드와 원격 아웃바운드를 나눠서 설명하면 어느 쪽의 로그를 확인해야 할지 파악하기도 쉽습니다. 여러 서버 중 하나를 골라야 한다면 노드 지연 시간·배율·프로토콜 비교를 참고하세요.

routing 라우팅 규칙

규칙 순서에 따라 아웃바운드 선택

라우팅은 코어에 이미 들어온 요청을 처리합니다. 시스템 프록시는 해당 설정을 따르는 앱의 요청을 코어로 전달하고, 라우팅은 요청이 어디로 나갈지 결정합니다. 둘은 서로 대체할 수 없습니다. 라우팅 모드만 바꿔도 시스템 프록시를 무시하던 터미널 프로세스가 자동으로 코어에 연결되지는 않습니다. 그래픽 인터페이스의 모드와 스위치 관계는 시스템 프록시와 라우팅 모드 비교에서 확인하세요.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["app-socks"],
        "domain": ["full:example.com"],
        "outboundTag": "reject"
      },
      {
        "type": "field",
        "inboundTag": ["app-socks"],
        "outboundTag": "direct"
      }
    ]
  }
}

대응하는 인바운드와 두 아웃바운드가 있는 예제에 이 설정을 추가하세요. 첫 번째 규칙은 요청이 지정된 인바운드에서 들어오고 대상이 정확한 도메인일 때 적용됩니다. 같은 도메인의 하위 도메인까지 거부하지는 않습니다. 두 번째 규칙은 해당 인바운드에서 들어오는 나머지 트래픽을 처리합니다. 일치하는 규칙이 없는 다른 인바운드는 기본 아웃바운드로 전달됩니다. 첫 번째 규칙을 테스트하려면 앱이 도메인을 SOCKS 인바운드에 전달해야 합니다. 앱에서 먼저 주소로 해석해 전송하면 현재 조건으로는 원래 도메인을 매칭할 수 없습니다.

규칙은 배열 순서대로 검사하며 처음 일치한 규칙이 경로를 결정합니다. 범위가 넓은 두 번째 규칙을 앞에 두면 첫 번째 규칙이 올바르더라도 적용되지 않습니다. 실제 규칙을 관리할 때는 예외를 먼저, 범위가 넓은 분류 규칙을 그다음에, 기본 규칙을 마지막에 두세요. 한 규칙의 조건 필드에 여러 종류의 조건을 함께 설정했다면 모든 조건을 동시에 만족해야 한다고 이해해야 합니다. 각 조건을 서로 독립된 대안으로 해석하면 안 됩니다.

하나의 도메인 조건 배열에 여러 후보를 넣을 수 있습니다. 특정 호스트 하나만 테스트할 때는 정확히 일치하는 조건이 적합하고, 도메인과 하위 도메인까지 매칭하려면 domain: 접두사를 사용할 수 있습니다. 웹 주소 전체를 도메인 조건에 넣지 마세요. 링크의 경로, 쿼리 매개변수, 해시는 호스트 이름에 포함되지 않습니다. 웹페이지가 다른 도메인에도 요청을 보낸다면 각 연결을 따로 확인해야 합니다. 페이지의 기본 주소만으로 모든 리소스에 같은 규칙이 적용된다고 단정할 수 없습니다.

도메인 정책과 IP 주소 규칙

앱이 코어에 도메인을 전달한 경우 AsIs는 라우팅의 IP 주소 조건을 확인하기 위해 도메인을 자동으로 해석하지 않습니다. 그렇다고 요청에서 DNS 해석이 전혀 일어나지 않는다는 뜻은 아닙니다. 직접 연결 아웃바운드는 최종적으로 도메인을 해석해야 할 수 있습니다. 정책을 IPIfNonMatch로 바꾸면 원래 대상에 일치하는 규칙이 없을 때 IP 규칙을 위해 추가 해석을 수행할 수 있습니다. 항상 일치하는 규칙을 마지막에 두면 이 대체 매칭이 실행되지 않을 수 있습니다.

IPOnDemand는 IP 주소가 필요한 규칙을 판단할 때 필요에 따라 DNS 해석을 시작합니다. 이 정책을 선택하기 전에 어떤 규칙이 실제로 해석 결과를 사용하는지 확인하세요. 도메인이 여러 IP 주소를 반환할 수 있고 결과도 네트워크 환경에 따라 달라질 수 있습니다. IP 주소를 기준으로 만든 규칙은 웹사이트의 정체성을 기준으로 한 규칙이 아닙니다. 같은 IP를 공유하는 다른 도메인에도 같은 처리가 적용될 수 있습니다. 앱이 이미 IP 주소를 전달한 경우에는 도메인을 판단하는 데 쓸 정보가 남아 있는지 먼저 확인해야 합니다.

지역 목록을 사용하기 전에 현재 코어가 해당 데이터 파일을 읽을 수 있고 규칙에서 참조하는 분류가 존재하는지 확인하세요. 규칙만 복사하고 클라이언트가 제공하던 데이터 리소스를 옮기지 않으면 시작할 때 오류가 발생할 수 있습니다. 먼저 외부 분류를 사용하지 않는 규칙 하나로 라우팅 동작을 검증한 다음 분류 목록을 추가하세요. 그러면 필드 설정과 데이터 리소스 문제를 분리해 확인할 수 있습니다.

설정을 바꿀 때마다 규칙에 일치해야 하는 대상과 일치하면 안 되는 대상을 하나씩 확인하고, 앱이 실제로 어느 인바운드에서 요청을 보냈는지 기록하세요. 변경 후에는 새 연결을 만들어 이전 규칙으로 생성된 연결을 재사용하지 않도록 합니다. 특정 브라우저에서만 차이가 난다면 브라우저가 자체적으로 DNS를 조회하거나 별도의 프록시 규칙을 사용하는지 확인하세요. 설정의 라우팅 순서가 올바르더라도 입력 조건 확인을 대신할 수는 없습니다.

dns DNS 설정

먼저 DNS 조회가 어느 단계에서 이뤄지는지 확인

앱이 대상을 직접 해석한 뒤 주소를 프록시에 전달할 때도 있고, 도메인과 함께 로컬 인바운드에 전달할 때도 있습니다. 코어가 라우팅 판단이나 직접 연결을 위해 직접 해석할 수도 있습니다. 원격 프로토콜이 도메인 전달을 지원하면 대상 접속에 필요한 DNS 조회를 원격 서버에서 수행할 수도 있습니다. 최상위 dns 설정은 코어의 내장 DNS를 관리하며, 다른 단계에서 이미 시작되거나 완료된 조회까지 자동으로 처리하지는 않습니다.

아래 예제에서는 로컬 시스템 DNS를 대체 경로로 사용하고, 확인하기 쉬운 정적 매핑을 추가합니다. 테스트 이름에는 예약 도메인을 사용합니다. 이 매핑은 해당 기기를 가리키므로 같은 기기에서 테스트 서비스를 직접 실행하는 데 적합합니다. 코어 내장 DNS를 사용하는 조회에만 적용됩니다. 테스트 서비스는 사용자가 직접 실행해 예상 포트에서 리슨해야 합니다. 연결 거부가 발생했다고 해서 DNS 설정이 잘못됐다고 단정할 수는 없습니다.

{
  "dns": {
    "hosts": { "v2ray-test.invalid": "127.0.0.1" },
    "servers": ["localhost"]
  },
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": { "domainStrategy": "UseIP" }
    }
  ]
}

이 설정을 최소 설정에 추가하면 아웃바운드 배열을 교체하게 됩니다. 직접 연결 아웃바운드의 UseIP는 도메인 대상에 접속할 때 코어 내장 DNS로 조회한 뒤 IP 주소로 연결하게 합니다. 라우팅 장의 거부 아웃바운드를 이미 사용 중이라면 해당 항목을 유지하거나 더 이상 필요하지 않은 참조를 제거하세요. 정적 매핑을 확인하려면 미리 조회한 IP 주소가 아니라 도메인을 SOCKS 인바운드로 전달해야 합니다.

앱이 코어에 연결하기도 전에 도메인을 찾을 수 없다는 오류가 발생하면 앱의 SOCKS 설정에서 호스트 이름을 프록시에 전달하도록 허용했는지 먼저 확인하세요. 앱에서 발생한 DNS 오류와 코어 로그에 기록된 DNS 오류는 서로 다른 문제입니다. 시스템의 별도 조회 도구는 코어를 실행 중이어도 이 설정의 정적 레코드를 사용하지 않습니다. 조회 경로에 따라 결과가 다르면 먼저 경로가 다른 이유를 확인하고 시스템 설정을 바로 덮어쓰지 마세요.

주소 계열, 상위 DNS 서버, 캐시

IPv4 또는 IPv6만 조회하도록 설정할 때는 응답 레코드와 기기의 실제 연결 가능성을 구분해야 합니다. IPv6 주소를 조회했다고 해서 현재 기기에서 IPv6로 접속할 수 있는 것은 아닙니다. IPv4만 강제하면 IPv6 주소만 제공하는 대상에 접속하지 못할 수도 있습니다. 먼저 기본 동작을 유지한 상태로 확인한 다음 단일 주소 계열과 비교하세요. 문제 해결을 위해 임시로 추가한 제한을 일상 설정에 남긴다면 그 이유를 기록해야 합니다.

상위 DNS 서버를 바꿔야 한다면 한 번에 하나만 수정하세요. DNS 서버 자체도 현재 네트워크에서 접속할 수 있어야 합니다. 상위 서버를 도메인 이름으로 지정했다면 코어가 어떤 경로로 해당 서버의 주소를 조회하는지도 확인하세요. 암호화 DNS를 설정할 때는 현재 코어가 지원하는 주소 형식을 사용해야 합니다. 다른 코어에서 쓰는 형식을 의미를 확인하지 않고 복사하면 트래픽 경로나 DNS 조회 경로가 예상과 달라질 수 있습니다.

조회가 실패했다고 해서 목록의 다음 DNS 서버를 즉시 시도하는 것은 아닙니다. 도메인별 제한, 실패 시 대체 동작, 주소 필터 등의 설정이 최종 서버 선택에 영향을 줍니다. 먼저 DNS 서버 하나와 대상 하나로 확인하고, 성공한 뒤 제한을 추가하세요. 그러면 DNS 서버에 연결할 수 없는 것인지 응답이 필터링되는 것인지 구분할 수 있습니다. DNS 시간 초과로 앱의 연결 대기 시간이 길어지면 대상 연결 시간 초과와 비슷한 오류로 보일 수도 있습니다.

설정을 바꾼 뒤에도 이전 DNS 결과가 앱, 시스템, 코어 중 한 곳에 남아 있을 수 있습니다. 기존 테스트 연결을 종료하고 설정을 다시 불러온 뒤 새 요청으로 비교하세요. 특정 앱만 이전 주소를 받는다면 해당 앱의 캐시와 전용 DNS 설정을 확인하세요. 기기 전체의 네트워크를 먼저 초기화할 필요는 없습니다. 주소 하나만 기록하기보다 테스트 시간과 DNS 조회 경로도 함께 기록하면 결과가 달라진 이유를 파악하기 쉽습니다.

유지보수 기록에는 정적 항목을 추가한 이유와 제거해야 할 시점을 적어 두세요. 테스트용 로컬 매핑을 일상적으로 사용하는 실제 설정에 포함하면 안 됩니다. 테스트 항목을 정리한 다음 정상적으로 DNS 조회가 되는 대상으로 라우팅과 직접 연결 아웃바운드를 확인하세요. 로컬 예제에서 DNS 설정이 작동했다고 해서 원격 DNS를 사용하는 트래픽도 같은 결과를 얻는다고 볼 수는 없습니다.

policy 연결 정책

레벨과 시간 초과의 적용 대상

연결 정책은 연결이 얼마나 기다리고 어떻게 종료되는지, 특정 통계를 수집할지 등을 정합니다. 도메인을 특정 아웃바운드로 보내지는 않으며 앱 자체의 재시도나 시간 초과 설정을 대신하지도 않습니다. 요청이 실제로 사용한 인바운드와 아웃바운드를 확인한 뒤 연결 정책을 살펴보세요. 여러 시간 초과를 먼저 늘리면 빠르게 재현되던 문제가 오래 기다려야 하는 문제로 바뀌어 관찰하기 어려워질 수 있습니다.

레벨 정책은 levels에 설정하며 레벨 번호는 객체의 문자열 키로 지정합니다. 예제에서는 레벨 0을 설정해 해당 레벨을 사용하는 연결을 살펴봅니다. 일부 프로토콜이나 사용자 설정에서는 다른 레벨을 지정할 수 있습니다. 정책이 설정되어 있다고 해서 모든 프로토콜과 연결에 적용되는 것은 아닙니다. 먼저 해당 프로토콜이 레벨을 선택하는 방식을 확인한 뒤 레벨 0을 조정할지, 특정 용도의 값을 별도로 둘지 결정하세요.

{
  "policy": {
    "levels": {
      "0": {
        "handshake": 8,
        "connIdle": 300,
        "uplinkOnly": 2,
        "downlinkOnly": 5
      }
    }
  }
}

값은 초 단위이며 동작을 확인하기 위한 예시일 뿐, 권장값으로 통용되는 것은 아닙니다. handshake는 해당 연결의 핸드셰이크 대기 시간을 제한하며 웹페이지 전체 로딩 시간을 제한하는 설정은 아닙니다. connIdle은 데이터 전송이 없는 동안의 대기 시간과 관련됩니다. 요청이 느리더라도 계속 데이터를 전송하는 상황과 오랫동안 완전히 유휴 상태인 연결은 서로 다르므로 같은 시간 초과 문제로 판단하면 안 됩니다.

uplinkOnly와 downlinkOnly는 한 방향만 전송이 계속될 때의 대기 시간과 관련됩니다. 한쪽에서 전송을 끝냈다고 해서 다른 쪽의 응답까지 모두 도착했다는 뜻은 아닙니다. 단방향 대기 시간을 너무 짧게 설정하면 처음에는 정상으로 보이더라도 마지막 데이터가 도착하기 전에 연결이 끝날 수 있습니다. 이런 문제를 진단할 때는 어느 방향이 먼저 종료됐는지, 특정 앱이나 대상에서만 문제가 생기는지 먼저 기록하세요.

정책 매개변수는 한 번에 하나씩 수정

먼저 기존 설정으로 문제를 재현한 뒤 증상과 가장 관련 있는 항목을 고르세요. 연결이 성립되기 전에 반복해서 실패한다면 연결을 시작한 시점부터 오류가 발생할 때까지의 시간을 기록합니다. 연결이 성립된 뒤 일정 시간 동안 유휴 상태였다가 끊긴다면 종료 전 마지막으로 데이터를 주고받은 시간을 기록하세요. 필드 하나만 바꾸고 새 연결로 확인합니다. 효과가 없으면 원래 값으로 되돌리고 모든 시간을 무작정 늘리지 마세요.

브라우저, 터미널, 원격 서비스, 중간 네트워크 장비 모두 연결을 종료할 수 있습니다. 앱이 이미 응답 대기를 멈췄다면 코어의 유휴 시간을 늘려도 해당 요청을 복구할 수 없습니다. 서로 다른 여러 연결이 비슷한 시점에 끊긴다면 로컬 직접 연결 예제로 비교해 볼 수 있습니다. 특정 원격 아웃바운드에서만 발생한다면 비슷한 시간에 끊긴다는 이유만으로 로컬 정책을 원인으로 단정하지 말고 원격 서비스 설정과 중간 경로를 확인하세요.

정책의 일부 스위치는 특정 대상의 통계를 수집할지 여부만 정합니다. 통계 모듈이 있는지, 연결에 식별 가능한 사용자 정보가 있는지, 인터페이스가 데이터를 어떻게 읽는지는 각각 별개의 문제입니다. 그래픽 인터페이스에 표시된 누적 트래픽이 코어의 같은 통계에서 나온다고 볼 수도 없습니다. 연결 문제를 확인하기 위해 전체 통계 기능을 켜거나 상세 로그를 장기간 보관할 필요는 없습니다.

일상 설정의 값을 정할 때는 유휴 연결을 정리하면서 간헐적으로 데이터를 주고받는 세션을 유지할 수 있어야 합니다. 유휴 시간을 너무 짧게 설정하면 일부 앱에서 연결을 자주 다시 만들고, 너무 길게 설정하면 더 이상 필요하지 않은 연결이 남을 수 있습니다. 오래 응답하지 않는 문제가 생기면 데이터를 계속 전송 중인 연결을 유휴 상태로 오해하지 말고 앱이 실제로 결과를 기다리는지 확인하세요. 문제가 난 앱과 같은 앱으로 다시 테스트해야 하며, 짧은 요청 한 번으로 긴 세션까지 복구됐다고 볼 수는 없습니다.

변경 이유, 검증 조건, 원래 값을 함께 기록하세요. 코어를 업그레이드하거나 클라이언트를 바꾼 뒤에는 텍스트만 비교하지 말고 레벨이 실제로 적용되는지 다시 확인해야 합니다. 정책을 바꿨는데 차이가 없다면 현재 불러온 설정의 출처와 연결에 적용된 레벨부터 확인하세요. 이 조건을 모두 분명히 해야 변경 전후의 테스트를 비교할 수 있습니다.

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

올바른 설정 경로 선택

데스크톱에서는 v2rayN을 우선 사용하세요. Windows, macOS, Linux용 설치 파일은 각 운영체제에 맞게 선택하면 됩니다. Android에서는 Xray 코어를 사용하는 v2rayNG를 먼저 확인하세요. V2Fly 코어가 필요하다면 v2flyNG를 선택할 수 있습니다. 세 클라이언트는 다운로드 페이지에서 확인할 수 있습니다. 처음 사용할 때는 운영체제와 기기 아키텍처에 맞는 설치 파일만 선택하면 되며, 코어 설정을 직접 작성할 필요는 없습니다.

클라이언트플랫폼우선 확인할 항목
v2rayNWindows、macOS、Linux실행 코어, 로컬 리슨, 시스템 프록시
v2rayNGAndroid연결 권한, 앱 범위, Xray 필드
v2flyNGAndroid연결 권한, 앱 범위, V2Fly 필드

그래픽 클라이언트는 서버 항목, 구독 주소, 로컬 포트, 라우팅 설정을 서로 다른 데이터로 저장하는 경우가 많습니다. 서버를 선택하고 실행할 때 이러한 정보를 바탕으로 코어 설정을 생성합니다. 따라서 서버 목록을 가져오는 것과 코어 설정 파일 전체를 가져오는 것은 다르며, 노드 목록 백업만으로 로컬 라우팅까지 저장되는 것도 아닙니다. 작업하기 전에 서버 정보, 연결 경로, 실행 설정 중 무엇을 바꾸려는지 확인하세요.

데스크톱에서 앱의 연결 방식을 바꿀 때는 대개 로컬 리슨과 시스템 프록시 설정부터 확인합니다. 시스템 프록시를 자동 설정하면 시스템 설정을 따르는 앱이 사용할 연결 경로를 제공할 수 있지만 모든 트래픽이 처리되는 것은 아닙니다. 데스크톱 운영체제마다 프록시 설정 위치가 다르고, 같은 앱이라도 자체 프록시 설정만 사용할 수 있습니다. 테스트 전에 앱이 시스템 설정을 읽는지, 직접 입력한 주소를 사용하는지 기록하세요.

Android에서는 클라이언트가 시스템에서 제공하는 연결 기능을 통해 앱 트래픽을 처리하는 경우가 많습니다. 연결을 시작할 수 있는지는 권한과 앱 범위에 따라 달라집니다. 데스크톱 예제처럼 앱에서 루프백 포트에 수동으로 연결하는 방법을 모바일 연결 절차로 그대로 사용하면 안 됩니다. 특정 앱 하나만 항상 작동하거나 실패한다면, 현재 클라이언트의 처리 범위에 포함되는지 먼저 확인한 뒤 코어의 라우팅 결과와 비교하세요.

설정 이전 시 클라이언트가 생성한 항목 유지

여러 코어 제품군은 기본 필드를 많이 공유하지만 프로토콜 옵션, 전송 이름, 확장 동작이 완전히 일치한다고 보장할 수 없습니다. 설정을 가져오기 전에 클라이언트 이름이나 파일 확장자만 보고 판단하지 말고 새 환경에서 실제로 실행되는 코어를 확인하세요. 대상 클라이언트가 생성한 설정을 기준으로 필요한 필드만 옮기세요. 복사할 때는 클라이언트가 관리하는 연결 설정과 인터페이스, 기타 내부 항목을 유지하고 다른 기기의 설정을 무작정 가져오지 마세요.

아래 예제는 로그 수준을 일상적으로 사용하기 적합한 값으로 조정하는 방법만 보여 줍니다. 기존 로그 객체가 있다면 다른 매개변수는 그대로 두고 로그 수준 필드만 합치세요. 인터페이스가 실행 설정을 자동 생성한다면 인터페이스의 로그 옵션을 우선 사용하세요. 사용자 지정 설정으로 시작할 때만 해당 파일에서 로그 수준을 지정하면 됩니다. 이렇게 하면 클라이언트를 재시작하거나 구독을 업데이트한 뒤에도 설정 출처를 확인할 수 있습니다.

{
  "log": {
    "loglevel": "warning"
  }
}

기기를 바꾸기 전에 앱별 연결 여부, 필요한 로컬 리슨, 지정 아웃바운드로 보내야 할 대상처럼 유지할 동작을 목록으로 작성하세요. 새 환경에서 기본 연결을 확인한 다음 트래픽 분기와 DNS 설정을 하나씩 복원합니다. 구독을 업데이트한 뒤 목록이 바뀌면 구독 그룹 및 서버 필터 안내에서 서버 출처를 확인하세요. 다른 그룹에 있는 이름이 같은 항목을 현재 서버로 착각하지 않도록 주의하세요.

내보낸 설정에는 구독 주소와 인증 정보가 포함될 수 있으므로 개인 작업 환경에만 보관하세요. 다른 사람의 도움을 받을 때는 관련 필드만 담은 별도 설명을 만들고 공개해도 되는 문제는 로컬 직접 연결 예제로 재현하세요. 이렇게 하면 개인 연결 정보가 노출되는 것을 막고 상대방이 확인할 범위도 줄일 수 있습니다. 문제를 기록할 때는 단순히 ‘가져오기 실패’라고 쓰는 것보다 클라이언트 이름, 운영체제, 실행 중인 코어를 함께 적는 편이 유용합니다.

이전을 마친 뒤에는 클라이언트를 다시 시작한 후에도 설정이 적용되는지 확인하세요. 현재 세션에서만 정상 작동하는 설정은 다음번 실행 설정을 생성하는 데 사용되는 출처에 저장되지 않았을 수 있습니다. 재시작 후 동작이 달라지면 실제로 활성화된 서버 항목, 구독 그룹, 선택된 사용자 지정 파일을 확인하세요. 선택한 설정이 바뀌지 않았음을 확인한 다음 코어마다 같은 필드를 다르게 처리하는지 살펴보세요.

설정 검증과 문제 진단

불러오기 단계에 따라 원인 범위 좁히기

먼저 코어가 정상적으로 시작됐는지 확인하세요. 파일 구문 오류는 대개 불러오기 직후 발생하고, 리슨 충돌은 로컬 인바운드를 열기 직전에 나타납니다. 두 문제 모두 클라이언트가 전혀 작동하지 않는 것처럼 보일 수 있지만 해결 방법은 다릅니다. 이번 시작 과정에서 처음 발생한 명확한 오류부터 읽고 이후 메시지를 확인하세요. 초기화 하나가 실패한 뒤 이어지는 오류를 서로 무관한 여러 문제로 보고 하나씩 수정할 필요는 없는 경우가 많습니다.

구문 오류가 발생하면 표시된 위치에서 앞쪽으로 이동하며 괄호, 쉼표, 따옴표를 확인하세요. 오류가 다음 줄을 가리키더라도 실제로 빠진 기호는 이전 줄에 있을 수 있습니다. 구문 오류가 해결됐는데도 설정을 불러오지 못하면 필드 유형, 프로토콜 이름, 참조 항목, 데이터 파일을 확인하세요. JSON 문법이 올바르다는 사실은 텍스트 구조를 읽을 수 있다는 뜻일 뿐, 현재 코어가 모든 필드를 인식하거나 아웃바운드 연결에 성공한다는 뜻은 아닙니다.

코어가 실행 중인지 확인한 다음 앱이 연결할 수 있는지 검사하세요. 프록시 유형과 주소를 지정한 앱 하나로 테스트하고 시스템 프록시와 앱 자체 프록시를 동시에 켜지 마세요. 앱에서 연결 거부가 표시되면 로컬 주소와 리슨 포트를 먼저 확인합니다. 요청이 코어에 들어왔는데 대상에 접속하지 못한다면 일치한 아웃바운드와 DNS 결과를 살펴보세요. 브라우저는 되지만 터미널에서 실패한다면 브라우저와 터미널을 구분해 문제를 해결하는 방법을 참고해 설정 출처를 확인하세요.

로그 비교와 설정 되돌리기 순서

필요하다면 아래 설정 조각을 사용해 진단 정보를 일시적으로 늘릴 수 있습니다. 로그 수준만 바꾸며 새 리슨을 추가하거나 기본 아웃바운드를 변경하지는 않습니다. 재현이 끝나면 로그 수준을 원래대로 되돌리세요. 로그에 접속 대상이나 네트워크 정보가 기록될 수 있습니다. 로그를 확인할 때는 한 번의 테스트가 진행된 시간대를 기준으로 살펴보세요. 클라이언트와 코어에 따라 표시 형식이 다를 수 있으므로 고정된 문구에 의존하지 마세요.

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

요청이 코어에 들어왔는데 예상과 다른 아웃바운드로 나간다면 규칙 순서, 인바운드 태그, 대상 형식, 아웃바운드 태그를 차례로 확인하세요. IP 주소만 테스트해서는 도메인 규칙이 작동한다고 확인할 수 없습니다. 선택된 아웃바운드가 맞는데 연결 시간이 초과되면 직접 연결 기준으로 로컬 경로를 확인한 다음 현재 아웃바운드의 전송 방식, DNS, 원격 설정을 살펴볼 수 있습니다. 테스트마다 변수 하나만 바꾸고 인바운드와 아웃바운드를 동시에 변경하지 마세요.

도메인으로 접속할 때는 실패하지만 IP 주소를 직접 지정하면 접속되는 경우 DNS를 따로 비교하세요. 누가 DNS를 조회하는지, 요청이 코어에 들어올 때 도메인이 보존되어 있는지 테스트 조건에 기록해야 합니다. 서버 이름에 의존하는 서비스는 IP 주소를 직접 지정하면 인증서의 이름이 일치하지 않을 수 있습니다. 이런 결과를 네트워크 연결 실패로 단정하지 마세요. 유휴 상태가 된 뒤에만 끊긴다면 유휴 시간을 따로 비교한 다음 연결 정책을 확인하세요.

설정을 되돌릴 때는 문제가 있는 설정의 불러오기를 중단하고, 정상 작동이 확인된 복사본을 복원한 다음 앱의 프록시 주소도 함께 복구하세요. 코어만 되돌리고 새 시스템 프록시 포트를 유지하면 문제가 계속될 수 있습니다. 기존 경로가 복구된 것을 확인한 뒤 인바운드, 아웃바운드, 라우팅, DNS, 정책 순서로 변경 사항을 하나씩 다시 적용하세요. 이상이 처음 다시 나타난 부분부터 다음 진단을 시작하면 됩니다.

반복되는 문제는 유발한 동작, 사용한 인바운드, 비교 경로, 변경한 필드, 결과, 되돌리는 방법을 짧게 기록해 두세요. 먼저 재현한 다음 원인을 판단하세요. 연결 한 번이 성공했다고 모든 앱이 같은 경로를 사용한다고 볼 수 없고, 한 번 실패했다고 설정 파일 전체가 잘못된 것도 아닙니다. 최소한의 재현 절차를 남겨 두면 다음 클라이언트 업데이트나 구독 변경 후에도 같은 방법으로 확인할 수 있습니다.