Xray gRPC API로 트래픽 통계 확인하고 노드를 자동 전환하는 실전 가이드

Xray의 gRPC API를 사용하면 실행 중인 코어에서 아웃바운드별 업로드·다운로드 누적량을 조회하고, 외부 스크립트나 모니터링 도구와 연결할 수 있습니다. 다만 트래픽 통계 조회와 노드 선택은 서로 다른 기능입니다. API가 통계를 반환한다고 해서 코어가 자동으로 가장 빠른 노드를 고르는 것은 아닙니다. 통계 수집, 노드 상태 확인, 전환 정책을 각각 설계해야 안정적으로 자동화할 수 있습니다.

gRPC API가 하는 일과 하지 않는 일

Xray API는 클라이언트 화면을 조작하는 인터페이스가 아니라, 실행 중인 Xray 코어가 제공하는 gRPC 서비스입니다. StatsService는 정책에 따라 수집된 트래픽 카운터를 조회하고, HandlerService는 실행 중인 인바운드·아웃바운드 핸들러를 추가하거나 제거하는 등 런타임 관리를 담당합니다. 따라서 API를 켰다고 해서 v2rayN의 노드 목록이나 현재 선택 항목이 자동으로 바뀌지는 않습니다.

노드 자동 전환에는 별도의 판단 주체가 필요합니다. 외부 스크립트가 여러 후보의 연결 상태를 확인하고 선택 결과를 반영하거나, Xray의 라우팅·관측 기능을 구성해 코어가 출구를 선택하도록 설계할 수 있습니다. 반면 트래픽 카운터는 얼마나 전송했는지를 보여 줄 뿐, 서버 부하·실제 대역폭·다음 연결의 성공 여부를 직접 보증하지 않습니다. 사용량이 적다는 이유만으로 노드가 고장 났다고 판단해서는 안 됩니다.

• StatsService: 설정한 정책에 따라 인바운드·아웃바운드 트래픽 통계를 조회합니다.
• HandlerService: 실행 중인 핸들러를 관리합니다. 모든 클라이언트의 구독 목록이나 GUI 상태를 동기화하는 서비스는 아닙니다.
• 전환 정책: 지연 시간, 연결 검사 결과, 실패 횟수, 대기 시간 등을 조합해 별도로 정해야 합니다.

설정 준비: API 인바운드와 통계 정책

다음은 V2Ray 형식의 JSON 설정에서 API 관련 항목을 찾기 위한 예시입니다. 전체 실행 설정이 아니므로 기존 설정의 api, inbounds, outbounds, routing, policy 구조에 맞춰 필요한 필드만 반영하세요. API용 인바운드는 일반 프록시 인바운드와 구분하는 태그를 사용하고, 로컬 주소에서만 수신하게 구성하는 것이 기본입니다.

API 인바운드는 일반적으로 dokodemo-door로 만들고, api 태그를 가진 요청이 API 아웃바운드로 라우팅되도록 구성합니다. 설정 파일에 API 서비스만 추가하고 라우팅 규칙을 빠뜨리면 gRPC 요청을 처리하지 못할 수 있습니다. 다음은 필드 관계를 보여 주는 일부 예시입니다.

{
  "api": {
    "tag": "api",
    "services": ["HandlerService", "StatsService"]
  },
  "stats": {},
  "policy": {
    "levels": {
      "0": {
        "statsUserUplink": true,
        "statsUserDownlink": true
      }
    }
  }
}

위 정책의 레벨 0은 설정 예시에서 사용할 값일 뿐, 모든 노드가 반드시 이 레벨을 사용한다는 뜻은 아닙니다. 실제로 적용되는 사용자의 레벨이 다르면 해당 레벨의 정책을 수정해야 합니다. 또한 통계를 켜는 것만으로 모든 인바운드·아웃바운드 카운터가 원하는 형태로 생기는 것은 아닙니다. Xray 버전과 설정에 따라 표시되는 항목을 조회해 확인하세요.

• API 인바운드의 listen을 127.0.0.1로 제한하고, 필요하지 않다면 외부 인터페이스에 노출하지 마세요.
• 라우팅에 API 인바운드 태그와 API 아웃바운드 태그의 연결이 있는지 확인하세요.
• 기존 routing.rules 순서를 보존하세요. 앞선 광범위한 규칙이 API 요청을 먼저 가져가면 뒤의 API 규칙에 도달하지 못할 수 있습니다.
• JSON 편집 후 코어의 설정 검사 기능으로 문법과 필드 구성을 확인한 다음 적용하세요.

StatsService로 트래픽 확인하기

Xray의 API 명령줄 도구로 로컬 gRPC 서버의 통계를 조회할 수 있습니다. Xray 실행 파일과 설정에 맞춰 서버 주소를 지정하고, 실제로 쓰이는 명령 옵션은 설치된 버전의 도움말에서 확인하세요.

xray api statsquery --server=127.0.0.1:10085

결과에는 구성에 따라 outbound>>>태그>>>traffic>>>uplink 또는 downlink 형태의 카운터가 나타날 수 있습니다. 아웃바운드 태그는 노드 표시 이름과 같지 않을 수 있으므로 실제 설정의 outbounds[].tag를 기준으로 연결하세요. 예를 들어 노드별 태그가 node-a, node-b라면 스크립트가 두 태그의 업로드와 다운로드 값을 각각 식별하도록 해야 합니다.

카운터를 주기적으로 저장할 때는 누적값과 구간별 사용량을 구분하세요. 조회 시 통계를 초기화하는 옵션을 사용하면 그 뒤의 값은 새 구간부터 계산될 수 있으므로, 초기화 전후 값을 같은 누적 기록처럼 비교하면 안 됩니다. 일반적으로는 일정 간격으로 누적값을 읽고 이전 값과의 차이를 계산하는 편이 기록을 보존하기 쉽습니다. 코어 재시작이나 통계 초기화 뒤 값이 감소하는 경우도 별도 구간으로 처리하세요.

• 업로드: 클라이언트에서 프록시 출구 방향으로 보낸 데이터량을 확인할 때 사용합니다.
• 다운로드: 프록시를 통해 클라이언트 방향으로 받은 데이터량을 확인할 때 사용합니다.
• 태그 매핑: 설정의 아웃바운드 태그와 조회 결과의 이름을 대조합니다.
• 시간 기록: 조회 시각, 코어 재시작 여부, 카운터 초기화 여부를 함께 저장합니다.

노드 전환 자동화: 검사와 변경을 분리하기

실제 전환은 통계 조회만으로 완성되지 않습니다. 먼저 후보 노드를 어떻게 검사할지 정하고, 실패가 일시적인지 확인한 다음, 선택된 노드가 새 연결에 적용되도록 해야 합니다. 간단한 스크립트라도 전환 조건을 너무 민감하게 잡으면 순간적인 패킷 손실이나 대상 사이트의 응답 지연만으로 노드가 계속 바뀌는 플래핑이 생길 수 있습니다.

1. 태그 정리

   사용할 아웃바운드마다 node-a, node-b처럼 고유한 태그를 부여합니다. 구독을 갱신할 때 태그가 바뀔 수 있는 클라이언트라면 설정 생성 후 실제 태그를 다시 확인하세요.

2. 통계 수집

   StatsService에서 각 태그의 업로드·다운로드 카운터를 일정 간격으로 조회합니다. 예를 들어 10초 간격은 관찰 주기의 예시이며, 서비스의 요청량과 운영 목적에 맞게 조정하세요.

3. 연결 검사

   후보 노드별로 새 연결을 만들어 검사합니다. 검사 주소와 제한 시간을 고정하고, 카운터가 증가하는지만으로 연결 성공을 판정하지 마세요.

4. 전환 조건 적용

   예를 들어 연속 3회 검사 실패 때만 장애 후보로 표시하고, 전환 뒤 60초 동안 재전환을 보류할 수 있습니다. 이 값은 정책 예시이므로 사용 환경에서 오탐과 복구 시간을 확인해 조정하세요.

5. 결과 확인

   전환 뒤 새 연결이 목표 아웃바운드를 이용하는지 확인하고, 이전 노드로 돌아갈 조건과 수동 복구 방법도 기록합니다. 실행 로그에는 시각, 기존 태그, 새 태그, 검사 결과를 남기되 구독 주소나 인증 정보는 기록하지 마세요.

전환 방식은 클라이언트와 코어 구성에 따라 달라집니다. 여러 아웃바운드를 미리 구성하고 라우팅의 밸런싱·관측 기능을 사용하는 방식은 코어가 선택을 맡는 구조입니다. 외부 제어 스크립트가 설정을 바꾸는 방식은 설정 파일 재생성, 코어 재시작 또는 지원되는 런타임 API 호출이 필요할 수 있습니다. HandlerService는 실행 중인 핸들러를 관리하지만, 그 호출만으로 v2rayN의 활성 노드 표시까지 변경된다고 가정해서는 안 됩니다. 적용 전에 현재 Xray 버전의 API 명령과 클라이언트의 설정 관리 방식을 검증하세요.

• 테스트할 때는 먼저 후보 노드 두 개와 명시적인 라우팅 규칙만 사용하세요.
• 자동화 스크립트에는 동시 실행 방지와 전환 쿨다운을 넣으세요.
• 전환 실패 시 기존 설정을 복원하거나 수동으로 주 노드를 지정할 방법을 마련하세요.
• GUI가 생성한 설정 파일을 직접 덮어쓰면 구독 업데이트나 재시작 때 변경 내용이 사라질 수 있습니다.

API 보안과 자주 만나는 문제

gRPC API는 관리 인터페이스입니다. 로컬에서만 제어할 목적이라면 포트를 인터넷이나 신뢰하지 않는 LAN에 공개하지 마세요. 방화벽으로 접근을 제한하고, 원격 관리가 꼭 필요하다면 인증·암호화·접근 허용 범위를 갖춘 관리 경로를 별도로 설계해야 합니다. 예시의 127.0.0.1:10085는 로컬 접속을 전제로 하며, 이를 0.0.0.0으로 바꾸는 것은 단순한 연결 오류 해결책이 아닙니다.