V2Ray 설정 파일 가이드

JSON 구조와 설정 범위

클라이언트 설정과 코어 실행 파일 구분하기

V2Ray 환경의 설정은 보통 두 계층으로 나뉩니다. 첫 번째는 GUI 클라이언트에 저장되는 구독, 그룹, 인터페이스 환경설정, 프록시 모드입니다. 두 번째는 코어를 실행할 때 생성되는 런타임 설정입니다. 둘 다 JSON을 사용할 수 있지만 필드의 의미는 서로 다릅니다. 구독 업데이트 간격은 클라이언트 관리 기능이므로 코어의 최상위 객체에 직접 추가할 수 없습니다. 파일을 확인하기 전에 클라이언트 데이터베이스인지, 구독 내용인지, 코어가 실제로 읽는 설정 파일인지 먼저 확인하세요. 파일 확장자가 같아도 서로 바꿔 쓸 수 있는 것은 아닙니다.

실행 설정은 데이터 흐름에 따라 이해할 수 있습니다. inbounds는 앱의 연결을 받고, routing은 연결을 전달할 아웃바운드를 결정하며, outbounds는 직접 연결·프록시·차단을 수행합니다. dns는 내장 DNS 설정을 제공하고 policy는 연결 정책을 조정합니다. log는 시작 및 실행 상태를 확인하는 데 사용됩니다. 각 모듈은 서로 참조하지만, 모든 기능을 처음부터 활성화할 필요는 없습니다. 기능을 추가할수록 함께 검증해야 할 조건도 늘어납니다. 문제를 해결할 때는 최소 경로를 유지한 뒤 항목을 하나씩 복원하세요.

최소 설정: 로컬 SOCKS 인바운드와 직접 연결 아웃바운드

아래는 원격 프록시 서버 없이 사용할 수 있는 기본 설정 전체 예시입니다. 앱이 로컬 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 객체는 중괄호로, 배열은 대괄호로 묶으며 필드명과 문자열에는 영문 큰따옴표를 사용합니다. 숫자 포트는 따옴표로 감싼 문자열이 아니어야 하며, 불리언 값은 true 또는 false로 씁니다. 실제 설정 파일에는 주석, 마지막 쉼표, 작은따옴표를 넣지 마세요. 문서의 예시는 보통 모듈 하나만 담고 있으므로 올바른 계층에 넣어야 합니다. 전체 최상위 객체를 인바운드의 settings에 넣으면 문법은 맞더라도 코어의 구조 요건을 충족하지 않습니다.

문법 검사를 통과한 뒤에도 현재 코어가 해당 필드를 지원하는지, 참조한 태그가 존재하는지, 외부 파일 경로에 접근할 수 있는지 확인해야 합니다. Xray와 V2Fly는 설정 개념 일부를 공유하지만 신규 프로토콜, 전송 필드, 테스트 매개변수는 완전히 같지 않습니다. 클라이언트 이름만으로 호환성을 판단하지 말고 실제 실행 중인 코어 이름과 로그를 확인하세요. 클라이언트가 공유 링크를 가져올 수 있다고 해서 선택한 코어가 링크의 모든 전송 매개변수를 실행할 수 있는 것은 아닙니다. 가져오기 성공과 연결 성공은 서로 다른 단계입니다.

수정하기 전에 실행 가능한 설정을 하나 보관하고, 변경 사항이 클라이언트 UI에서 발생했는지 사용자 지정 파일에서 발생했는지 기록하세요. 실행 파일이 클라이언트에서 자동 생성된다면 직접 편집해도 노드를 바꾸거나 재시작할 때 덮어써질 수 있습니다. 먼저 UI에서 일반 설정을 완료한 다음 클라이언트가 명시적으로 제공하는 사용자 지정 설정 기능으로 확장 항목을 추가하세요. 해당 기능을 찾을 수 없다면 현재 생성된 결과를 내보내거나 확인하세요. 임시 파일을 반복해서 수정하는 방식으로 영구 설정을 대신하지 마세요. 이후 장에서도 같은 계층 구분을 적용해 덮어쓰기 문제를 필드 오류로 오인하지 않도록 합니다.

inbounds 인바운드: 수신 주소·포트·프로토콜

인바운드는 앱이 코어에 연결되는 방식을 정의합니다

inbounds는 배열이며 각 객체는 연결을 받는 진입점을 나타냅니다. tag는 라우팅에서 참조할 이름이고, listen은 바인딩할 로컬 주소, port는 수신 포트, protocol은 인바운드 프로토콜을 지정합니다. 앱이 HTTP 프록시를 사용하도록 설정되어 있으면 HTTP 인바운드에 연결해야 합니다. SOCKS 프록시를 사용한다면 SOCKS 인바운드에 연결해야 합니다. 포트 번호만으로 두 인바운드를 서로 바꿔 쓸 수는 없습니다. 포트 연결에 성공해도 앱과 인바운드가 같은 프록시 핸드셰이크 방식을 사용한다는 뜻은 아닙니다.

로컬에서만 사용할 때는 127.0.0.1을 수신 주소로 사용하는 것이 좋습니다. IPv4 루프백 인터페이스에만 바인딩되므로 컴퓨터가 다른 네트워크에 연결되어도 LAN에 자동으로 공개되지 않습니다. 0.0.0.0은 사용 가능한 모든 IPv4 인터페이스에 바인딩한다는 뜻입니다. 충분히 검토한 LAN 공유 환경에서 사용할 수 있지만 방화벽으로 접속 출처도 제한해야 합니다. 수신 주소는 원격 서버 주소가 아니며 다른 기기에서 입력할 대상 주소도 아닙니다. 다른 기기에서는 클라이언트가 실행 중인 컴퓨터의 같은 LAN 내 실제 주소를 입력해야 합니다.

두 인바운드 예시와 필드 설명

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

예시에서는 앱 설정에서 구분하기 쉽도록 두 프로토콜에 서로 다른 포트를 지정했습니다. SOCKS의 udp 옵션을 켜면 해당 인바운드에서 UDP 요청을 처리할 수 있지만, 전체 경로에서 UDP가 전달된다고 보장하지는 않습니다. 앱이 해당 기능을 사용해야 하고 아웃바운드 프로토콜과 원격 측도 지원해야 하며, 중간 네트워크가 패킷을 제한할 수도 있습니다. 웹 페이지는 정상인데 특정 실시간 앱에 문제가 있다면 인바운드 연결 여부, UDP 요청 발생 여부, 아웃바운드 경로의 지원 여부를 각각 확인하세요. 인바운드 옵션만 반복해서 바꾸지 마세요.

스니핑, 시스템 프록시, TUN은 서로 다른 설정입니다

코어 기능에 따라 인바운드에 sniffing을 설정해 일부 프로토콜 핸드셰이크에서 대상 도메인 등의 정보를 식별할 수 있습니다. 도메인 기반 라우팅 판단에 도움이 되지만 범용 콘텐츠 분석 도구는 아닙니다. 암호화 핸드셰이크의 특성, 앱 구현, 코어 설정에 따라 얻을 수 있는 정보가 달라집니다. 스니핑은 원래 대상과 식별된 도메인의 사용 방식에도 영향을 줄 수 있으므로 모든 분할 라우팅 문제의 기본 해결책으로 취급하지 마세요. 먼저 앱이 도메인과 IP 중 무엇을 전달하는지 확인한 다음 필요한 경우 활성화하고, 사용 중인 코어가 관련 옵션을 어떻게 해석하는지도 확인하세요.

시스템 프록시는 운영체제가 해당 설정을 따르는 앱에 프록시 진입점을 알리는 기능이며, 그 자체로 인바운드를 생성하지는 않습니다. TUN은 가상 네트워크 인터페이스, 라우팅 제어, DNS 연동이 필요하므로 위 JSON에 같은 이름의 불리언 필드를 추가하는 것만으로 설정되지 않습니다. 구체적인 기능은 클라이언트, 선택한 코어, 관련 구현에 따라 달라집니다. 먼저 로컬 포트가 수신 중인지 확인하고, 시스템 프록시가 그 포트를 가리키는지 확인한 뒤, 대상 앱이 시스템 설정을 따르는지 확인하세요. 이 세 단계를 나누면 앱이 직접 연결한 상황을 코어 라우팅 오류로 오인하지 않을 수 있습니다.

LAN 공유에서는 기기 주소 변경, 게스트 네트워크 격리, 컴퓨터 절전도 고려해야 합니다. 휴대전화와 컴퓨터의 이름이 비슷하거나 같은 액세스 포인트에 연결되어 있다고 해서 서로 접근할 수 있다는 뜻은 아닙니다. 먼저 같은 서브넷에서 연결 가능한지 확인하고 필요한 포트만 열어 테스트한 다음, 더 이상 필요하지 않은 인바운드는 닫으세요. 자세한 방법은 v2rayN LAN 연결 허용 설정을 참고하세요. 문제 해결을 위해 기기 전체의 방화벽을 계속 끄지 마세요. 포트와 출처 네트워크를 제한하는 규칙을 만들고 용도를 기록하는 것이 좋습니다.

outbounds 아웃바운드: 대상 연결과 태그 참조

아웃바운드는 연결을 수행하며 구독을 관리하지 않습니다

outbounds도 배열이며 각 객체는 코어에서 외부로 연결하는 방식을 정의합니다. 일반적인 freedom은 대상에 직접 연결하고, blackhole은 연결을 차단하며, 프록시 프로토콜은 원격 서버에 맞는 연결 매개변수가 필요합니다. tag는 라우팅에서 선택할 아웃바운드의 이름이지 프로토콜 자체가 아닙니다. 태그 이름을 proxy로 지정해도 원격 프록시 기능이 자동으로 생기지 않습니다. 실제 동작은 protocol, settings 및 해당되는 전송 설정에 따라 결정됩니다.

규칙에 일치하는 항목이 없으면 보통 아웃바운드 배열의 첫 번째 항목을 사용하므로 배열 순서가 실제 동작에 영향을 줍니다. 기본적으로 프록시를 사용하려면 첫 항목이 원하는 프록시 아웃바운드인지 확인하세요. 기본 직접 연결을 원한다면 첫 항목을 직접 연결로 둘 수 있습니다. 일치하지 않은 연결이 자동으로 proxy라는 객체를 찾을 것이라고 가정하지 마세요. GUI 클라이언트는 현재 모드에 따라 아웃바운드 순서를 바꾸거나 다시 생성할 수 있습니다. 구독 목록의 표시 순서가 아니라 실제 실행 설정을 기준으로 기본 동작을 확인하세요.

로컬 업스트림으로 프록시·직접 연결·차단 살펴보기

아래 조각은 실제 원격 인증 정보를 예시 설정과 섞지 않도록 다른 로컬 SOCKS 서비스를 업스트림으로 사용합니다. 로컬에 사용 가능한 SOCKS 서비스가 실제로 127.0.0.1:10810에서 실행 중일 때만 첫 번째 아웃바운드가 연결을 완료할 수 있습니다. 자신의 인바운드 포트를 가리키면 안 됩니다. 연결이 되돌아오는 루프가 생길 수 있습니다. 첫 장의 직접 연결 경로만 테스트한다면 이 조각은 필요하지 않습니다. 업스트림을 추가하기 전에 업스트림 자체가 독립적으로 요청을 처리하는지 먼저 확인하세요.

{
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "socks",
      "settings": {
        "servers": [
          {
            "address": "127.0.0.1",
            "port": 10810
          }
        ]
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "block",
      "protocol": "blackhole",
      "settings": {}
    }
  ]
}

프로토콜 매개변수와 전송 매개변수를 나눠 확인하기

VMess, VLESS, Trojan, Shadowsocks는 인증 구조가 서로 다르므로 한 프로토콜의 설정 객체를 다른 프로토콜에 그대로 복사할 수 없습니다. 서버 주소와 포트가 같다는 사실만으로 인증 매개변수가 올바르다고 볼 수 없습니다. 구독에서 가져온 노드라면 먼저 가져온 매개변수를 모두 유지하고 클라이언트가 프로토콜을 올바르게 인식했는지 확인한 뒤 전송 유형, 보안 계층, 서버 이름을 점검하세요. 문제를 해결할 때는 오류가 확인된 필드 하나만 조정하세요. 프로토콜, 전송, 라우팅을 동시에 바꾸면 결과를 비교하기 어렵습니다.

streamSettings는 지원되는 전송 및 보안 설정에 사용되지만 내부 구조는 프로토콜과 코어 기능에 따라 달라집니다. WebSocket 경로, TLS 서버 이름, REALITY 관련 매개변수는 서로 대체할 수 있는 문자열이 아닙니다. 전송 방식은 서버와 일치해야 하고 보안 계층도 서버 설정에 맞아야 합니다. 서버 이름이나 시간 오류를 감추려고 인증서 검증을 끄지 마세요. 시스템 시간, 서버 이름, 서버 인증서 조건부터 확인해야 합니다. 핸드셰이크 단계에서 연결이 실패한다면 라우팅 목록을 바꿔도 원격 매개변수 불일치는 해결되지 않습니다.

같은 원격 노드를 여러 코어에서 사용할 수 있는지는 프로토콜과 전송 특성을 모두 확인해야 합니다. 프로토콜 이름만 보고 선택하지 마세요. 예를 들어 VLESS를 인식하더라도 링크에 포함된 모든 보안 매개변수를 지원한다는 뜻은 아닙니다. 두 코어 계열의 차이는 Xray 코어와 V2Fly 코어의 차이에서 더 자세히 확인할 수 있습니다. 호환성을 확인한 뒤 코어를 전환하고 실제 생성된 파일을 다시 점검해 클라이언트가 이전 설정을 재사용하거나 표현할 수 없는 매개변수를 누락하지 않았는지 확인하세요.

아웃바운드를 관리할 때는 명확한 대체 경로도 남겨 두세요. 프록시 아웃바운드를 추가할 때 확인 가능한 직접 연결 및 차단 태그를 유지하고, 범위가 좁은 규칙 하나로 테스트 대상을 지정하세요. 성공을 확인한 뒤에만 규칙 범위를 넓히세요. 아웃바운드를 삭제하기 전에 라우팅과 다른 모듈에서 해당 아웃바운드를 참조하는지 검색하세요. 참조가 끊긴 태그는 설정 오류를 일으키거나 연결이 예상과 다르게 처리되게 할 수 있습니다. 연결 재사용이나 체인 프록시 같은 확장 기능은 기본 연결이 안정된 뒤 별도로 검토하고 최소 예시에 기본 포함하지 마세요.

routing 라우팅: 매칭 순서와 기본 출구

문구가 아니라 규칙 순서에 따라 매칭됩니다

라우팅은 연결을 어떤 아웃바운드로 전달할지 결정하며 원격 노드의 연결 가능 여부를 정하지 않습니다. rules 배열은 보통 앞에서부터 검사하며 적용되는 규칙과 일치하면 해당 아웃바운드를 선택합니다. 구체적인 규칙을 광범위한 규칙보다 앞에 두세요. 예를 들어 LAN 대상부터 처리하고 특정 도메인 유형을 처리한 다음 더 넓은 범위의 규칙을 적용합니다. 첫 번째 규칙이 모든 TCP와 UDP에 이미 일치하면 뒤에 있는 세부 규칙은 적용되지 않습니다. 규칙이 많다고 분할 라우팅이 정확해지는 것은 아닙니다. 조건끼리 서로를 덮어쓰는지 확인하는 것이 중요합니다.

규칙 하나에서 서로 다른 유형의 조건은 보통 모두 충족해야 합니다. 같은 조건 배열에 여러 값이 있으면 대체로 그중 하나에 일치하면 됩니다. 예를 들어 domain과 port를 함께 쓰면 대상 도메인과 대상 포트 조건을 모두 충족해야 한다는 뜻이지, 둘 중 하나만 충족해도 된다는 뜻이 아닙니다. 도메인 또는 IP 중 하나에 일치시키려면 보통 규칙 두 개로 나누는 편이 명확합니다. 가져온 규칙을 읽을 때 조건을 완전한 문장으로 바꿔 보면 AND 조건을 OR 조건으로 잘못 이해한 부분을 빠르게 찾을 수 있습니다.

LAN 직접 연결 및 특정 도메인 차단

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

이 설정을 사용하려면 direct 및 block 아웃바운드가 있어야 하고, 코어가 해당 지역 IP 데이터를 불러올 수 있어야 합니다. 예시 도메인은 설명용 이름이며 실제 서비스가 아닙니다. 규칙에 일치하지 않는 연결은 기본 아웃바운드를 사용합니다. 이전 장처럼 프록시를 첫 번째에 두었다면 나머지 트래픽은 프록시로 전달됩니다. AsIs는 IP 규칙을 위해 도메인 대상을 능동적으로 해석하지 않습니다. 따라서 도메인으로 내부 서비스에 접속할 때 사설 IP 규칙만으로 반드시 직접 연결된다고 판단해서는 안 됩니다. 내부 도메인 규칙을 따로 추가하거나 DNS 처리 방식을 명확히 검토하세요.

도메인 규칙, IP 규칙, 데이터 파일

full:은 도메인 전체와 일치시키고 domain:은 지정한 도메인과 하위 도메인에 일치시킵니다. 일반 텍스트와 정규식 규칙은 각각 고유한 의미가 있습니다. 특정 호스트 하나만 지정할 때는 전체 일치가 더 쉽게 검토할 수 있고, 도메인 전체를 포함해야 할 때는 도메인 일치를 사용하세요. 간단한 규칙으로 요구사항을 표현할 수 없을 때 정규식을 사용하고 JSON 문자열에서 백슬래시를 이스케이프해야 한다는 점에 유의하세요. 정규식 테스트 도구의 문자열을 JSON에 그대로 붙여 넣으면 이스케이프 단계 차이로 최종 의미가 달라질 수 있습니다.

geosite:와 geoip:는 데이터 분류를 참조하며 실시간 조회 서비스가 아닙니다. 분류의 존재 여부, 포함 항목, 업데이트 후 변경 여부는 실제로 불러온 데이터 파일에 따라 달라집니다. 규칙 이름의 철자가 맞더라도 파일이 없거나 경로가 잘못되었거나 분류가 존재하지 않으면 시작에 실패할 수 있습니다. 클라이언트의 데이터 업데이트 기능을 사용한 뒤 관련 코어를 다시 시작하고 로그를 확인하세요. 여러 출처의 데이터 파일을 한꺼번에 교체한 뒤 웹 페이지 결과만으로 성공 여부를 판단하지 마세요. 먼저 코어가 예상한 파일과 경로를 불러왔는지 확인하세요.

위 정책은 라우팅 단계에서 언제 조회가 필요한지 결정합니다. DNS 모듈의 주소 계열 선택이나 직접 연결 아웃바운드가 최종 연결을 설정하는 방식과는 다릅니다. 도메인은 먼저 규칙 판단에 사용되더라도 이후 아웃바운드나 원격 측에서 연결을 위해 다시 조회될 수 있습니다. 문제를 해결할 때는 “라우팅 선택에 사용되는 주소”와 “실제 연결에 사용되는 주소”를 구분하세요. 두 단계에서 조회 출처가 다르면 로그에 표시된 IP와 최종 접속 경로가 완전히 같지 않을 수 있습니다. 조회 결과 하나만 보고 전체 경로가 고정되었다고 판단하지 마세요.

새 규칙을 검증할 때는 대상을 명확히 하나 정하고 입력값이 도메인인지 IP인지 기록한 뒤 규칙 범위를 일시적으로 좁히세요. 접속 로그에서 예상한 인바운드와 아웃바운드를 거치는지 확인하고 규칙을 원래대로 복원합니다. 앱 캐시나 기존 연결은 새로운 연결 결정을 우회할 수 있으므로 테스트 전에 기존 연결을 종료하고 요청을 새로 시작하세요. 클라이언트에서 라우팅 템플릿을 자동 업데이트한다면 업데이트 후 사용자 지정 규칙이 유지되는지도 확인하세요. 규칙 관련 자주 묻는 질문은 여러 템플릿을 반복해서 바꾸는 대신 자주 묻는 질문과 함께 확인할 수 있습니다.

dns 설정: 조회 출처·주소 계열·연결 경로

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

DNS 문제에서 먼저 정할 것은 어떤 서버를 입력할지가 아니라 조회가 어디서 일어나는지입니다. 앱이 시스템 조회로 IP를 얻은 뒤 프록시에 전달할 수도 있고, 도메인을 SOCKS 또는 HTTP 인바운드에 전달할 수도 있습니다. 코어가 라우팅 정책에 따라 직접 조회하거나 원격 프록시가 최종 조회를 담당할 수도 있습니다. 요청이 실제로 코어 DNS를 사용할 때만 dns 모듈 변경이 해당 단계에 영향을 줍니다. 시스템 DNS, 브라우저 자체 조회 설정, 코어 DNS는 서로 다른 설정이며 한 번의 설정 변경으로 모든 앱의 동작을 설명할 수는 없습니다.

확인할 때는 대상 입력값, 앱의 프록시 방식, 라우팅 정책을 기록하세요. 앱이 이미 IP를 전달했다면 코어는 보통 DNS 설정만으로 원래 도메인을 복원할 수 없습니다. 스니핑으로 일부 정보를 얻을 수는 있지만 모든 연결에서 도메인을 식별한다고 보장하지 않습니다. 반대로 앱이 도메인을 전달하더라도 AsIs에서는 라우팅 단계에서 조회가 일어나지 않을 수 있습니다. 요청 경로를 먼저 파악한 다음 시스템 조회, 앱 설정, 코어 모듈 중 어디를 수정할지 결정하면 조회 캐시, 규칙 매칭, 원격 연결 실패를 모두 같은 DNS 문제로 취급하는 일을 피할 수 있습니다.

정적 매핑과 DNS 서버 예시

{
  "dns": {
    "hosts": {
      "full:reference.example": "192.0.2.10"
    },
    "servers": [
      "223.5.5.5",
      "1.1.1.1"
    ],
    "queryStrategy": "UseIP"
  }
}

정적 매핑에는 문서용 예시 주소를 사용했으며 실제로 접속할 수 있는 서비스가 아닙니다. 도메인 덮어쓰기 구조를 이해하는 데 사용할 수 있습니다. 두 DNS 서버 주소는 설정 형식만 보여 주는 예시이며 모든 네트워크에 적합하다는 뜻은 아닙니다. 여러 DNS 서버의 선택, 동시 조회, 대체 동작은 설정 형식과 코어 구현에 따라 달라집니다. 배열을 브라우저 즐겨찾기처럼 순서대로 시도한다고 단순하게 이해하지 마세요. 실제로 사용하기 전에 현재 네트워크에서 서버에 접근할 수 있는지, 요청이 예상한 경로를 거치는지 확인하세요. 정적 매핑은 해당 도메인의 결과를 바꾸므로 테스트가 끝나면 필요 없는 항목을 삭제하세요.

주소 계열 정책과 IPv6 조건

queryStrategy는 내장 DNS가 조회하거나 사용할 주소 계열을 제한합니다. UseIP는 IPv4와 IPv6를 모두 고려하고, UseIPv4 또는 UseIPv6는 한쪽으로 제한합니다. 주소 계열 설정은 기기 UI에 IPv6 주소가 표시되는지가 아니라 실제 네트워크 기능에 맞춰야 합니다. 기기에 로컬 IPv6 주소가 있다고 해서 대상 네트워크까지 IPv6 경로가 완전하다는 뜻은 아닙니다. 반대로 한 번의 시간 초과를 피하려고 시스템 전체에서 IPv6를 영구적으로 끄면 다른 정상 앱에 영향을 줄 수 있습니다.

일부 도메인이 조회되지만 연결되지 않는다면 반환된 주소 계열과 아웃바운드의 도달 가능성을 비교하세요. IPv6 결과를 받은 경우에만 실패한다면 범위를 제한해 IPv4 조회를 먼저 시험한 뒤 로컬 라우팅, 원격 출구, 서버 수신 상태를 확인할 수 있습니다. 조회 자체가 시간 초과되면 DNS 서버에 도달하는 경로부터 점검하세요. “주소를 조회했다”는 사실과 “해당 주소의 서비스를 사용할 수 있다”는 사실은 다릅니다. DNS 성공은 응답을 받았다는 것만 증명하며 이후 포트 연결과 보안 핸드셰이크는 각각 확인해야 합니다.

도메인 기반 DNS 분할을 구성하면 서버 객체에 일치시킬 도메인, 원하는 IP 범위, 대체 조회 관련 옵션이 포함될 수 있습니다. 조합 방식은 단순한 서버 배열보다 복잡하고 코어마다 확장 필드가 다릅니다. 먼저 DNS 서버 하나로 동작하는 기준을 만든 뒤 도메인 범위와 대체 조건을 추가하세요. 처음부터 여러 분류, 주소 제한, 대체 옵션을 모두 추가하면 응답이 없을 때 업스트림 연결 실패인지, 응답 필터링인지, 현재 대상이 조건에 일치하지 않는지 판단하기 어렵습니다.

암호화 DNS도 연결 가능한 네트워크 경로가 있어야 합니다. 업스트림 호스트를 조회하려면 먼저 같은 업스트림을 사용해야 하는 구성에서는 시작 의존성이 생길 수 있습니다. 프록시 노드 주소도 아직 연결되지 않은 같은 프록시 경로에 의존한다면 문제가 더 복잡해집니다. 설정 전에 “노드 주소 조회, 노드 연결, DNS 업스트림 접속, 서비스 도메인 조회” 순서를 그려 서로 기다리는 순환이 없는지 확인하세요. 암호화 전송 방식이라는 이유만으로 연결 가능성이 보장되지는 않습니다. 실제로는 주소 조회, 라우팅, 연결 권한의 영향을 받습니다.

DNS 변경을 검증할 때는 캐시도 고려해야 합니다. 시스템, 브라우저, 앱, 코어가 각각 결과를 저장할 수 있고 기존 연결은 이전 주소를 계속 사용할 수도 있습니다. 새 연결과 명확한 테스트 도메인을 사용해 로그를 확인하고, 필요한 경우 플랫폼에 맞는 정상적인 방법으로 캐시를 비우거나 앱을 다시 시작하세요. 캐시 계층을 모르는 상태에서 여러 서버 설정을 연속으로 바꾸지 마세요. 이전 설정이 나중 테스트에서 우연히 적용되어 잘못된 결론을 내릴 수 있습니다. 웹 페이지가 열리는지만 비교하는 것보다 테스트 시각과 당시 설정을 기록하는 편이 유용합니다.

policy 정책: 연결 수명 주기와 통계 조건

정책은 연결 경로를 선택하는 기능이 아닙니다

policy는 연결 처리와 통계 동작을 조정하며 특정 도메인을 프록시 노드에 배정하지 않습니다. 일반적인 구조에는 사용자 등급별 levels와 전역 시스템 통계 설정인 system이 포함됩니다. 등급 키는 "0"처럼 JSON 문자열로 표시합니다. 사용자에게 적용되는 등급은 프로토콜 설정과 코어의 해석 방식에 따라 달라집니다. 분명한 필요가 없다면 설정을 완전해 보이게 하려고 여러 등급을 추가할 필요는 없습니다. 기본 동작을 유지하고 로그에서 재현 가능한 연결 문제에 한해 매개변수를 소수만 조정하세요.

정책을 이해하려면 핸드셰이크 단계, 정상 전송 단계, 한 방향이 종료된 단계를 구분해야 합니다. 핸드셰이크 시간 초과는 초기 협상에 적용되고, 유휴 시간 초과는 일정 시간 활동이 없는 연결에 적용됩니다. 한쪽 방향이 끝난 뒤의 대기 시간은 다른 방향의 데이터를 계속 전달할 필요가 있는지와 관련됩니다. 모든 값을 지나치게 낮추면 정상적인 장기 연결이 종료될 수 있고, 모두 크게 설정하면 비정상 연결이 자원을 오래 점유할 수 있습니다. 값이 클수록 안정적인 것은 아니므로 앱의 연결 방식과 실제 증상에 맞게 선택하세요.

등급 정책 및 시스템 통계 설정 예시

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

예시의 시간은 초 단위이며 필드 구조를 보여 주기 위한 것으로 모든 앱에 적용할 최적화 값은 아닙니다. handshake는 해당 연결의 핸드셰이크 대기 시간을 제한하고 connIdle은 유휴 연결을 제한합니다. uplinkOnly와 downlinkOnly는 한쪽 방향이 종료된 뒤의 대기와 관련됩니다. 구체적인 적용 범위는 프로토콜과 코어 구현을 함께 확인하세요. 값을 조정한 뒤 업로드가 끝나자마자 다운로드가 끊기거나 백그라운드 연결이 주기적으로 다시 설정된다면 먼저 원래 값으로 복원한 다음 연결 로그를 바탕으로 범위를 좁히세요. 정책을 계속 추가하지 마세요.

통계 활성화와 데이터 표시를 구분하세요

통계 옵션을 켜도 클라이언트에 모든 수치가 즉시 표시되는 것은 아닙니다. 통계 모듈, 조회 인터페이스, 클라이언트의 데이터 읽기 기능이 함께 동작해야 합니다. 사용자 단위 통계에는 프로토콜에서 지원하는 사용자 식별자 등의 조건도 적용됩니다. 예시는 시스템 인바운드 및 아웃바운드 통계 옵션만 보여 주기 위해 사용자 송수신 통계를 명시적으로 끕니다. 클라이언트가 이미 통계와 인터페이스 설정을 자동 생성한다면 같은 이름의 모듈을 무작정 추가하지 마세요. 설정이 중복되어 충돌하거나 UI가 이전 인터페이스를 계속 읽어 코어는 실행 중인데 표시 영역은 바뀌지 않을 수 있습니다.

유휴 연결과 느린 연결은 서로 다른 개념입니다. 연결이 적은 양의 데이터를 계속 전송하는 경우 유휴 상태로 판단되는지는 코어의 활동 판정 방식에 따라 달라집니다. 앱 계층의 하트비트 전송 방식도 연결 유지에 영향을 줍니다. 주기적으로 연결이 끊기는 문제를 조사할 때는 앱 로그의 재연결 시각, 코어가 연결을 닫은 이유, 시스템 절전 기록을 비교하세요. 컴퓨터 절전, 무선 네트워크 전환, 모바일 앱의 백그라운드 제한도 비슷한 현상을 일으킬 수 있습니다. 특정 시점에 연결이 끊겼다는 이유만으로 connIdle 설정이 부적절하다고 단정하지 마세요.

통계가 필요하다면 클라이언트에 이미 제공되는 상태 화면과 접근이 제한된 로컬 인터페이스를 우선 사용하세요. 수치를 확인하려고 관리 인터페이스를 모든 네트워크 인터페이스에 공개하지 마세요. 인터페이스의 존재 여부, 수신 주소, 접근 가능한 사용자는 각각 독립적인 보안 경계입니다. 일반적인 데스크톱 사용에서는 이 장을 읽기 위해 원격 관리 진입점을 직접 만들 필요가 없습니다. 통계는 코어를 재시작하면 다시 집계될 수도 있습니다. 클라이언트의 누적 기록에서 이번 프로세스의 카운터를 빼서 설정이 사라졌거나 연결이 우회했다고 추론하지 마세요.

정책을 바꾸려면 먼저 증상을 설명하고, 그다음 필드를 선택한 뒤, 마지막으로 부작용을 확인하세요. 예를 들어 유휴 상태 이후 코어가 특정 앱의 연결을 종료한 사실을 확인한 경우에만 관련 유휴 대기 시간을 검토하세요. 인증 단계에서 실패했다면 아웃바운드 매개변수를 다시 확인해야 합니다. 원래 값, 변경 값, 테스트 조건을 매번 기록하고 다른 설정은 그대로 유지하세요. 되돌릴 때는 기억을 더듬어 하나씩 바꾸기보다 검증된 설정 전체를 복원하는 편이 안전합니다. 정책은 후반부의 세부 조정이며 인바운드 접근성, 아웃바운드 연결, 올바른 라우팅보다 먼저 다룰 항목이 아닙니다.

클라이언트 연동: 생성 파일·구독·코어 전환

클라이언트의 영구 설정을 수정 경로로 사용하세요

데스크톱에서는 Windows, macOS, Linux를 지원하는 v2rayN을 주로 사용합니다. Android에서는 설정에 따라 v2rayNG 또는 v2flyNG를 선택할 수 있습니다. 설치 파일은 클라이언트 다운로드 페이지에서 확인하세요. 이 클라이언트는 노드, 모드, 라우팅 옵션을 실행 가능한 설정으로 구성하므로 UI 구조가 JSON과 일대일로 대응하지 않을 수 있습니다. 이 가이드를 참고할 때는 먼저 사용 중인 클라이언트의 설정 미리보기, 로그, 사용자 지정 설정 기능을 찾아 해당 변경을 UI에 유지할지 별도 파일에 둘지 판단하세요.

구독을 가져오면 클라이언트는 보통 소스 정보와 노드 목록을 저장한 뒤 현재 선택에 따라 실행 설정을 생성합니다. 노드 그룹, 필터 키워드, 자동 업데이트는 클라이언트 계층 기능이지 일반적인 routing 또는 policy 필드가 아닙니다. 코어 파일에 그룹 이름을 추가해도 구독 목록이 자동으로 분류되지는 않습니다. 구독에서 생성된 노드 매개변수를 직접 바꾸면 다음 업데이트에서 덮어쓸 수도 있습니다. 장기적으로 설정을 조정할 때는 원본 데이터와 로컬 덮어쓰기를 구분해 구독 업데이트가 검증 중인 설정을 조용히 변경하지 않도록 하세요.

생성 결과에서 네 가지 연결 관계를 확인하세요

첫째, UI에서 선택한 현재 노드가 실제 아웃바운드와 일치하는지 확인합니다. 둘째, 시스템 프록시 또는 앱 설정이 실제 인바운드 포트를 가리키는지 확인합니다. 셋째, 현재 라우팅 모드가 예상한 규칙과 기본 아웃바운드를 생성했는지 확인합니다. 넷째, UI에서 선택한 코어와 시작 로그에 표시된 코어가 일치하는지 확인합니다. 이 네 가지를 점검한 다음 프로토콜 매개변수를 자세히 살펴보세요. 노드를 바꿨는데 기존 연결이 이전 출구를 계속 사용하거나 백그라운드의 다른 인스턴스가 시스템 프록시가 가리키는 포트를 점유하는 등, 설정이 맞아 보이는데 동작이 다른 여러 상황을 설명할 수 있습니다.

{
  "inbounds": [
    {
      "tag": "local-http",
      "listen": "127.0.0.1",
      "port": 10809,
      "protocol": "http",
      "settings": {}
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": ["local-http"],
        "outboundTag": "direct"
      }
    ]
  }
}

이 독립 예시는 HTTP 인바운드를 직접 연결 아웃바운드에 명시적으로 연결해 UI 포트와 태그의 대응 관계를 보여 줍니다. 기존 구독을 대체하라는 뜻은 아닙니다. 클라이언트의 사용자 지정 설정 모드가 전체 실행 파일을 대체한다면 해당 모드에서도 시스템 프록시 설정, 포트 업데이트, 통계 인터페이스 생성이 자동으로 이루어지는지 확인하세요. 기능별 입력란은 역할이 다릅니다. 라우팅 추가용 입력란에는 모든 인바운드와 아웃바운드가 포함된 전체 파일을 붙여 넣지 마세요. 저장하기 전에 입력란 안내를 읽고, 저장 후에는 UI의 성공 메시지만 확인하지 말고 실제 생성 결과를 확인하세요.

코어 전환과 트래픽 가로채기 모드 전환을 따로 검증하세요

Xray와 V2Fly는 일부 필드명이 같더라도 설정 호환성을 완전히 추론할 수 없습니다. 코어를 전환하기 전에 프로토콜과 전송에 필요한 기능을 확인하고 이전 설정을 보관하세요. 전환한 뒤에는 다시 시작하고 로그의 코어 식별 정보를 확인한 다음 생성된 설정이 바뀌었는지 점검하세요. 사용자 지정 파일을 사용한다면 클라이언트가 특정 계열의 전용 필드를 다른 계열에서 지원하는 구조로 자동 변환하지 않을 수 있습니다. 알 수 없는 필드나 프로토콜이 나타나면 원래 코어로 되돌려 기본 연결이 복구되는지 확인한 뒤 호환되는 설정을 하나씩 구성하세요. 오류가 난 필드를 모두 바로 삭제하지 마세요.

시스템 프록시와 TUN도 각각 별도의 테스트 기준을 마련해야 합니다. 모든 트래픽을 가로채지 않는 상태에서 로컬 프록시 포트를 먼저 검증하고, 시스템 프록시를 활성화해 해당 설정을 따르는 앱을 테스트한 다음 TUN을 검토하세요. TUN은 추가 권한, 가상 인터페이스, 라우팅, DNS 설정이 필요할 수 있으며 지원 범위는 현재 클라이언트와 관련 코어에 따라 달라집니다. 활성화 후 LAN 접근에 문제가 생기면 가로채기 범위와 사설 네트워크 규칙을 확인하세요. 특정 앱만 시스템 프록시를 사용하지 않는다면 먼저 구독이 손상되었다고 의심하지 마세요.

구독 소스가 여러 개라면 복잡한 사용자 지정 설정을 다루기 전에 소스와 그룹부터 정리하는 것이 좋습니다. 노드 업데이트 후 매개변수의 출처를 빠르게 확인하고 정상 동작이 확인된 항목으로 되돌리기도 쉽습니다. 정리 방법은 v2rayN 구독 그룹 및 노드 필터링을 참고하세요. 데스크톱 권한 문제는 플랫폼 설치 경로에서 해결해야 합니다. 예를 들어 macOS 설치 및 네트워크 권한 안내를 확인하세요. 권한이 없는 상태에서 JSON을 계속 바꿔도 시스템이 네트워크 제어를 거부하는 문제는 해결되지 않는 경우가 많습니다.

설정을 이전해야 한다면 구독 소스, 사용자 지정 규칙, 현재 플랫폼에 따른 옵션을 따로 기록하세요. 플랫폼마다 설정 디렉터리, 파일 권한, 네트워크 권한이 다르므로 절대 경로 하나를 그대로 복사한다고 사용할 수 있는 것은 아닙니다. 이전 후에는 노드 하나를 먼저 검증하고 라우팅과 DNS 확장을 복원한 다음 트래픽 가로채기 모드를 확인하세요. 처음 설정하는 순서는 빠른 시작 가이드를 기준으로 삼으세요. 이 페이지는 필드 설명을 제공하며 현재 클라이언트 UI의 조작 안내를 대신하지 않습니다.

검증 및 문제 해결: 파일 읽기부터 대상 연결까지

실패 단계에 따라 범위를 좁히세요

설정 문제는 시작, 수신, 연결 수용, 라우팅, 조회, 원격 연결 순으로 점검해야 합니다. 코어가 시작되지 않았다면 웹 페이지 결과로 라우팅이 맞는지 판단할 수 없습니다. 앱 연결이 인바운드에 도달하지 않았다면 아웃바운드 변경도 검증할 수 없습니다. 클라이언트 로그를 열고 코어를 한 번 다시 시작해 이번 시작 과정에서 가장 먼저 발생한 오류를 찾으세요. 이후 반복되는 재시도 중에서 임의로 한 줄을 고르지 마세요. 초기 오류가 여러 후속 메시지를 일으킬 수 있으므로 명확하게 실패한 첫 지점을 먼저 해결하는 편이 모든 경고를 동시에 다루는 것보다 효과적입니다.

파일을 읽는 단계에서는 JSON 구조, 필드 유형, 경로를 중점적으로 확인하세요. 오류가 특정 필드 근처를 가리켜도 원인은 그 앞에 있을 수 있습니다. 이전 줄에 쉼표가 빠졌거나 문자열이 닫히지 않았거나 배열 끝 위치가 잘못되었을 수 있습니다. 오류가 표시된 줄만 삭제하지 마세요. 최상위 객체와 모듈 계층을 먼저 파악한 다음 최근에 수정한 부분을 비교하세요. 편집기 검사가 필요하면 노드 정보가 포함된 파일은 로컬에서 처리하세요. 출처가 불분명한 온라인 처리 페이지에 전체 설정을 올리지 말고 로그를 공유하기 전에 주소와 인증 정보를 제거하세요.

장기 실행보다 테스트 모드를 먼저 사용하세요

코어 파일을 직접 관리한다면 먼저 현재 코어가 지원하는 설정 테스트 명령을 실행해 볼 수 있습니다. 아래 명령은 Xray용이며 시스템에서 해당 실행 파일을 찾을 수 있고 작업 디렉터리에 대상 파일이 있어야 합니다. V2Fly는 명령 매개변수가 다를 수 있으므로 다른 코어에 같은 옵션을 그대로 적용하지 말고 로컬 프로그램의 도움말을 먼저 확인하세요. GUI 클라이언트 사용자는 클라이언트 로그와 제공되는 검사 기능을 우선 이용하세요. 코어를 별도로 관리할 필요가 없다면 명령 실행을 위해 별도의 실행 환경을 추가로 설치할 필요는 없습니다.

xray run -test -config config.json

테스트 통과는 현재 프로그램이 파일을 받아들일 수 있다는 뜻일 뿐, 원격 서버에 접근할 수 있거나 앱이 프록시를 사용한다는 의미는 아닙니다. 다음으로 포트 수신이 정상적으로 이루어지는지 확인하세요. 주소가 이미 사용 중이라는 오류가 표시되면 클라이언트가 중복 실행 중인지, 이전 코어 프로세스가 남아 있는지, 다른 로컬 서비스가 사용 중인지 확인하세요. 충돌을 피하려고 JSON에서만 포트를 바꾸고 시스템 프록시나 앱 설정을 그대로 두지 마세요. 그러면 코어는 정상적으로 시작해도 앱은 이전 포트에 계속 연결합니다. 포트를 바꾼 뒤 요청을 새로 보내고 인바운드 로그를 확인하세요.

로그를 관찰해 연결 경로를 검증하세요

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

로그 수준을 일시적으로 info로 설정하면 실행 정보를 더 볼 수 있지만 실제로 표시되는 내용은 클라이언트가 코어 출력을 수집하는 방식과 액세스 로그의 별도 설정 여부에 따라 달라집니다. 라우팅을 확인하려면 클라이언트의 연결 기록이나 액세스 로그에서 인바운드 태그, 대상 형식, 아웃바운드 태그를 구분해 살펴보세요. 문제가 해결되면 일상 사용에 적합한 로그 수준으로 되돌리세요. 상세 로그에는 접속 대상, 기기 주소, 연결 시간이 포함될 수 있습니다. 목적 없이 장기간 보관하거나 검토 없이 공개된 게시판에 붙여 넣지 마세요.

인바운드와 라우팅이 정상이라면 조회와 원격 핸드셰이크를 확인하세요. 연결 시간 초과는 원격 포트에 접근할 때도, 서비스 대상에 접근할 때도 발생할 수 있습니다. 인증 실패, 서버 이름 불일치, 조회 실패는 각각 다른 방식으로 처리해야 합니다. 로그에 표시된 실제 대상과 실패 단계를 비교하고 “시간 초과”라는 문구만으로 노드가 작동하지 않는다고 판단하지 마세요. 같은 설정이 네트워크에 따라 다르게 동작한다면 네트워크 전환, 주소 계열, 권한 조건을 기록하고 설정은 그대로 둔 채 비교하세요. 네트워크 차이와 설정 변경을 한 번의 테스트에 섞지 마세요.

항목을 하나씩 복원하는 과정은 수정이 효과가 있었는지 검증하는 마지막 단계입니다. 먼저 정상 동작이 확인된 최소 설정으로 연결 하나를 완료한 뒤 대상 아웃바운드, 규칙 하나, DNS와 정책 확장을 차례로 추가하세요. 각 단계의 결과를 저장하면 문제가 생겼을 때 가장 최근 변경 사항을 찾을 수 있습니다. 테스트 규칙은 예상대로 일치할 대상과 일치하지 않아야 할 대상을 모두 포함해야 합니다. 넓은 규칙 하나가 특정 웹 페이지만 열리게 하고 나머지 트래픽은 잘못된 출구로 보내는 상황을 방지할 수 있습니다. 기존 연결을 종료하고 다시 시도해 새 설정이 실제 판단에 적용되는지도 확인하세요.

로그를 더 자세히 읽는 방법은 로그로 config.json 오류 찾기에서 확인할 수 있습니다. 반복되는 기본 질문은 자주 묻는 질문을, 용어의 뜻은 용어집을 참고하세요. 마지막으로 검증된 설정 기준본을 보관하고 구독 업데이트, 클라이언트 생성, 로컬 관리 항목을 구분해 두세요. 이후 업그레이드나 이전 시에는 먼저 기준본과 비교한 뒤 필요한 필드만 조정하세요. 전체 파일에서 원인을 다시 추측하는 일을 피할 수 있습니다.