V2Ray 설정 파일 JSON 구조 해설: inbounds·outbounds·routing 항목별 가이드

1. 단독 테스트용 config.json 만들기

아래 예제는 이 형식을 지원하는 V2Fly 코어에서 사용할 수 있는 기존 V2Ray JSON 설정 구조입니다. 먼저 v2ray version을 실행해 실제로 구동 중인 프로그램을 확인하고, 이어서 v2ray help를 살펴보세요. V2Fly와 Xray는 일부 필드를 공유하지만 확장 기능과 명령줄 옵션이 완전히 같지는 않습니다. 다른 코어의 설정을 범용 형식으로 간주해 그대로 사용하지 마세요.

아래 내용을 UTF-8 인코딩의 config.json 파일로 저장하세요. 127.0.0.1:10808에서 SOCKS 연결을 받고, example.org와 그 하위 도메인에 대한 연결은 차단하며 나머지 요청은 기본적으로 직접 연결합니다. 여기서 ‘실행 가능’이란 인바운드, 라우팅, 아웃바운드가 작동한다는 뜻이며 원격 프록시 기능까지 갖췄다는 의미는 아닙니다.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "socks-local",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "inboundTag": ["socks-local"],
        "domain": ["domain:example.org"],
        "outboundTag": "blocked"
      }
    ]
  },
  "dns": {
    "servers": [
      "1.1.1.1",
      "8.8.8.8"
    ]
  }
}

• 객체는 중괄호로, 배열은 대괄호로 묶습니다. inbounds와 outbounds는 항목이 하나뿐이어도 배열로 작성해야 합니다.
• 키와 문자열은 영문 큰따옴표로 감쌉니다. 숫자 10808과 불리언 값 false에는 따옴표를 붙이지 않습니다.
• 마지막 속성 뒤에는 쉼표를 붙이지 않습니다. 여러 도구에서 문제없이 확인할 수 있도록 예제에는 주석이나 후행 쉼표를 사용하지 않았습니다.
• 최상위 필드의 작성 순서는 요청 경로를 결정하지 않습니다. 순서가 중요한 부분은 라우팅 규칙 배열과 기본 아웃바운드의 위치입니다.

2. log: 오류를 확인할 위치 정하기

log는 로그 출력을 설정하며 프록시나 트래픽 분기를 담당하지 않습니다. 예제에서는 loglevel만 설정하고 로그 파일 경로는 지정하지 않았습니다. 터미널에서 직접 실행하는 경우 프로세스 출력을 확인하세요. 서비스로 실행한다면 임의의 디렉터리에서 기본 로그 파일을 찾지 말고 해당 서비스의 로그를 확인해야 합니다.

시작에 실패하면 먼저 명확한 오류 메시지가 처음 나타나는 지점을 확인하세요. 파싱 오류는 보통 필드나 위치를 가리키고, address already in use는 수신 포트가 이미 사용 중이라는 뜻입니다. 권한 오류라면 설정 파일과 로그 디렉터리를 확인하세요. 노드 주소를 계속 바꿔도 로컬 포트 충돌은 해결되지 않습니다.

3. inbounds: 앱은 로컬 인바운드에 연결합니다

inbounds는 코어가 요청을 받는 방식을 설정합니다. 예제의 protocol: socks는 앱과 로컬 코어 사이에서 사용하는 SOCKS 프로토콜이지 원격 서버의 프로토콜이 아닙니다. 브라우저나 터미널에서 이 인바운드를 직접 지정해야 합니다. 프로세스를 실행하는 것만으로 시스템 프록시가 설정되거나 모든 앱의 트래픽이 자동으로 전달되지는 않습니다.

listen은 인바운드에 연결할 수 있는 대상을, port는 인바운드 포트를 지정합니다. 여기서는 루프백 주소를 사용하므로 다른 LAN 기기에서 컴퓨터의 사설 IP로 접속할 수 없습니다. 문제를 해결하려고 0.0.0.0으로 바꾸면서 인증 없이 계속 사용하지 마세요. 수신 범위가 넓어집니다.

settings.auth를 noauth로 설정하면 로컬 SOCKS 연결에 사용자 이름과 비밀번호가 필요하지 않습니다. udp: false는 이 예제에서 SOCKS UDP 전달을 허용하지 않는다는 뜻입니다. 이 글에서는 TCP 요청만 테스트하므로 게임, 음성 통화 또는 다른 UDP 앱이 작동한다고 볼 수는 없습니다.

4. outbounds: 프로토콜 설정과 아웃바운드 태그 구분하기

outbounds는 요청이 코어를 빠져나가는 방식을 설정합니다. 예제의 freedom은 직접 연결, blackhole은 요청 차단 또는 폐기에 사용합니다. 둘 다 원격 노드가 아니므로 서버 주소, 사용자 식별자, 전송 보안 매개변수를 입력할 필요가 없습니다.

1. 먼저 protocol을 확인하세요. 사용할 수 있는 프로토콜 필드가 settings에 따라 달라집니다. SOCKS 인바운드의 인증 필드를 VMess 아웃바운드에 복사하지 마세요.
2. 다음으로 settings를 확인하세요. 해당 프로토콜에 필요한 연결 매개변수가 여기에 들어갑니다. 실제 프록시 노드를 추가할 때는 기본값을 임의로 추측하지 말고 서버 정보와 사용 중인 코어의 문서를 참고하세요.
3. 마지막으로 tag를 확인하세요. 설정 내부에서 참조하는 이름입니다. 예제의 direct와 blocked는 직접 지정한 태그이며 시스템에 미리 정의된 프로토콜 이름이 아닙니다.
4. streamSettings도 확인하세요. 필요한 경우 아웃바운드 객체에 전송 방식과 전송 보안 매개변수를 설정합니다. settings와 같은 수준의 필드이므로 임의로 중첩하면 안 됩니다.

VMess와 VLESS는 서로 다른 프록시 프로토콜이므로 protocol 하나만 바꿔서는 변환할 수 없습니다. VLESS를 사용한다면 실제 코어 버전과 지원 범위도 확인하세요. 특히 Xray 전용 전송 확장은 필드 모양이 비슷하다는 이유만으로 V2Fly 설정에 그대로 옮길 수 없습니다.

5. routing: 규칙 순서에 따라 아웃바운드 선택하기

요청이 코어에 들어오면 라우팅 모듈이 대상 도메인, 대상 IP, 포트, 인바운드 태그 등의 조건에 따라 아웃바운드를 선택합니다. 예제의 처리 흐름은 다음과 같습니다. 가상 네트워크 어댑터를 사용하지 않으며 시스템 프록시도 자동으로 설정하지 않습니다.

예제의 규칙은 요청의 출처가 socks-local이고 대상 도메인이 domain:example.org에 일치할 때 해당 요청을 blocked로 전달합니다. 같은 규칙에 있는 두 조건을 모두 충족해야 합니다. domain 배열에 도메인을 여러 개 지정한 경우에는 그중 하나만 일치해도 도메인 조건을 충족합니다.

어떤 규칙에도 일치하지 않으면 outbounds의 첫 번째 항목을 기본으로 사용합니다. 이 글의 첫 항목은 direct이므로 일반 요청은 직접 연결됩니다. 프록시 아웃바운드를 첫 번째로 옮기면 규칙에 일치하지 않는 요청의 동작도 달라집니다. ‘모든 사이트가 같은 경로로 나간다’면 규칙뿐 아니라 배열의 첫 항목도 확인하세요.

domainStrategy: AsIs는 라우팅 단계에서 현재 가지고 있는 대상 정보를 기준으로 일치 여부를 확인하며, IP 규칙에 맞추기 위해 도메인을 미리 조회하지 않는다는 뜻입니다. 앱이 SOCKS에 IP 주소를 전달하면 도메인 규칙만으로 원래 도메인을 알아낼 수 없습니다. 이 예제는 스니핑을 설정하지 않았으므로 테스트할 때 앱이 도메인을 SOCKS 인바운드에 전달해야 합니다.

6. dns: DNS 서버 설정이 시스템 DNS를 대신하지는 않습니다

최상위 dns는 코어에 내장된 DNS 모듈을 설정합니다. 예제에는 DNS 서버 두 곳인 1.1.1.1과 8.8.8.8이 지정되어 있지만, 이 설정만으로 운영체제의 DNS가 바뀌거나 모든 앱의 DNS 요청이 자동으로 코어에 전달되지는 않습니다.

• 앱에서 미리 DNS 조회: 앱이 먼저 대상 IP를 확인한 뒤 해당 IP를 SOCKS에 전달합니다. 이 경우 코어에서 원래 도메인을 확인할 수 없어 도메인 기반 분기가 적용되지 않을 수 있습니다.
• 앱에서 도메인 전달: 앱이 도메인을 SOCKS 대상 주소로 전달하면 라우팅 모듈에서 도메인 조건을 바로 확인할 수 있습니다.
• 라우팅 중 DNS 조회: DNS 조회가 필요한 라우팅 전략을 사용하면 IP 규칙을 계속 확인하기 위해 라우팅 모듈이 내장 DNS를 호출할 수 있습니다.
• 아웃바운드에서 DNS 조회: 직접 연결 아웃바운드에도 자체 도메인 조회 전략이 적용됩니다. 기본값인 AsIs를 사용한다면 최상위에 지정한 DNS 서버를 반드시 조회한다고 가정해서는 안 됩니다.

따라서 이 예제의 DNS 항목은 주로 설정 구조를 보여 주며 매번 실제로 사용된다는 보장은 없습니다. 라우팅의 domainStrategy와 직접 연결 아웃바운드의 settings.domainStrategy는 서로 다른 계층의 설정입니다. 전자는 규칙의 일치 방식에, 후자는 직접 연결 시 대상 주소를 처리하는 방식에 영향을 줍니다. 이름이 같다고 해서 어느 한쪽을 바꾸면 모든 DNS 조회 경로가 달라지는 것은 아닙니다.

7. 설정 테스트와 두 가지 요청 검증

test와 run 하위 명령을 지원하는 V2Fly 버전에서는 설정 파일이 있는 디렉터리에서 다음 명령을 실행할 수 있습니다. Windows에서 현재 디렉터리의 프로그램을 실행할 때는 프로그램 이름을 .\v2ray.exe로 입력하세요. 그 외 버전은 먼저 로컬 도움말에서 옵션을 확인해야 합니다. 실행하기 전에 데스크톱 클라이언트가 10808을 이미 사용 중인지 확인하세요.

v2ray version
v2ray help
v2ray test -c config.json
v2ray run -c config.json

test가 성공했다는 것은 현재 코어가 설정을 받아들였다는 뜻일 뿐, 네트워크 연결이 가능하다는 의미는 아닙니다. 코어를 실행한 채 다른 터미널에서 다음 명령을 실행하세요. Windows에서는 터미널 별칭과의 충돌을 피하기 위해 curl.exe를 사용할 수 있습니다.

curl --connect-timeout 10 --max-time 20 --proxy socks5h://127.0.0.1:10808 -I https://example.com/
curl --connect-timeout 10 --max-time 20 --proxy socks5h://127.0.0.1:10808 -I https://example.org/

1. 첫 번째 테스트는 직접 연결 확인입니다. 현재 네트워크에서 대상에 접속할 수 있다면 첫 번째 명령에 HTTP 응답 헤더가 표시됩니다. 응답 상태 코드는 대상 사이트에 따라 달라지므로 반드시 200일 필요는 없습니다.
2. 두 번째 테스트는 차단 확인입니다. 두 번째 요청은 정상적인 HTTPS 응답을 받지 못해야 합니다. 오류 메시지는 curl과 코어 버전에 따라 다를 수 있으므로 특정 문구만 보고 성공 여부를 판단하지 마세요.
3. 요청 시간 제한도 확인하세요. 명령은 연결 시간 초과를 10초, 전체 시간 초과를 20초로 설정해 오래 기다리지 않도록 합니다. 이는 응답 시간 측정이나 성능 평가가 아닙니다.
4. 설정을 한 번에 하나씩 바꾸세요. 먼저 차단 규칙의 outboundTag를 direct로 변경한 뒤 다시 테스트하고 코어를 재시작합니다. 두 번째 요청에서 응답이 돌아오면 태그 참조와 라우팅 규칙이 실제 처리에 관여한다는 것을 확인할 수 있습니다.

디스크에 저장된 JSON을 수정해도 실행 중인 프로세스가 자동으로 다시 읽는다고 가정하지 마세요. 이 글처럼 직접 실행하는 경우 기존 프로세스를 중지한 다음 설정을 테스트하고 다시 시작해야 합니다. v2rayN에서 구독 노드를 사용하면 클라이언트가 실행 설정을 새로 생성할 수 있습니다. 클라이언트가 생성한 파일과 직접 관리하는 사용자 지정 설정을 구분하고, 수정 전에 사본을 보관하세요.

8. 자주 발생하는 설정 문제와 해결 방법

최종 점검 순서는 JSON 파싱, 코어 실행, 인바운드 연결, 규칙 일치, 대상에 대한 아웃바운드 연결입니다. 한 번에 한 계층만 수정하고 작동하는 기준 설정 파일을 보관하세요. 그러면 나중에 VMess, VLESS 또는 복잡한 DNS 분기를 추가하더라도 설정 전체를 반복해서 교체하는 대신 문제를 특정 필드로 좁힐 수 있습니다.