VMess·VLESS·Trojan·Shadowsocks 비교: 차이와 사용 환경

Xray API가 관리하는 범위부터 확인하기

Xray API는 실행 중인 코어에 gRPC 요청을 보내 관리 기능을 호출하는 인터페이스입니다. 클라이언트 화면의 노드 편집 기능과는 별개이며, API에 연결된 서비스가 제공하는 작업만 수행합니다. 이 글의 예시는 실행 중인 Xray 인스턴스에 아웃바운드를 추가·제거하는 HandlerService와 통계 조회를 위한 StatsService를 사용합니다.

중요한 제한은 API 변경이 디스크의 JSON 설정 파일을 자동으로 수정하지 않는다는 점입니다. API로 추가한 아웃바운드는 현재 프로세스에 반영되는 동적 상태입니다. 코어를 재시작하거나 설정을 다시 불러오면 해당 변경이 사라질 수 있으므로, 영구 적용이 필요하다면 관리 프로그램이 원본 설정과 변경 내용을 함께 보관해야 합니다.

포트 번호는 예시일 뿐이며, 실제 포트는 서버 환경에 맞춰 선택해야 합니다. 통계 항목 네 가지는 일반적으로 인바운드 업링크·다운링크와 아웃바운드 업링크·다운링크를 가리킵니다. 트래픽을 전달하는 포트와 관리용 API 포트를 같은 의미로 취급하지 마세요.

API 인바운드를 로컬에만 열기

Xray 설정에는 API 서비스 목록과 API 인바운드, 그리고 해당 인바운드에서 API 태그로 향하는 라우팅 규칙이 필요합니다. 다음은 구조를 설명하기 위한 부분 설정 예시입니다. 이미 인바운드나 라우팅 규칙을 사용 중이라면 배열을 통째로 덮어쓰지 말고 기존 항목과 병합하세요.

{
  "api": {
    "tag": "api",
    "services": [
      "HandlerService",
      "StatsService"
    ]
  },
  "inbounds": [
    {
      "tag": "api",
      "listen": "127.0.0.1",
      "port": 10085,
      "protocol": " dokodemo-door",
      "settings": {
        "address": "127.0.0.1"
      }
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "inboundTag": [
          "api"
        ],
        "outboundTag": "api"
      }
    ]
  }
}

예시의 protocol 값은 공백 없이 dokodemo-door로 작성해야 합니다. 실제 설정에 붙여 넣을 때는 아래처럼 정확히 입력하세요. API 인바운드의 태그와 api.tag 값, 라우팅 규칙의 inboundTag가 서로 맞아야 합니다. 대상 주소를 loopback으로 지정하면 같은 서버 안에서 실행되는 관리 프로그램이 연결하는 구성이 됩니다.

"protocol": "dokodemo-door"

설정을 저장한 뒤 Xray가 해당 구성으로 실행되는지 확인하세요. 설정 검사 도구가 제공되는 배포 환경이라면 재시작 전에 문법 검사를 수행하고, 시작 로그에서 API 인바운드가 정상적으로 열렸는지 살펴보는 편이 좋습니다. 관리 프로그램이 다른 서버에서 실행된다면 단순히 listen 주소를 외부로 바꾸기보다 SSH 터널이나 방화벽으로 접근 경로를 제한하세요. gRPC API에 별도의 사용자 비밀번호가 자동으로 붙는다고 가정해서는 안 됩니다.

아웃바운드를 추가하고 제거하기

HandlerService는 실행 중인 Xray에 아웃바운드를 추가하거나 제거하는 데 사용됩니다. 추가 요청에는 아웃바운드 태그와 해당 아웃바운드의 설정이 필요합니다. 다음 JSON은 API에 전달할 아웃바운드 설정 파일의 예시입니다. 이를 통해 직접 연결용 아웃바운드를 동적으로 추가하는 동작을 확인할 수 있습니다.

{
  "tag": "direct-dynamic",
  "protocol": "freedom",
  "settings": {}
}

이 파일은 Xray 전체 설정이 아니라 아웃바운드 하나의 설정입니다. `freedom`은 대상에 직접 연결하는 프로토콜이므로, 실제 프록시 서버 노드를 만들려면 서버 측에서 사용하는 프로토콜과 인증 정보, 전송 방식, 보안 설정에 맞는 아웃바운드 구성을 넣어야 합니다. 다른 노드의 JSON에서 태그만 바꿔 복사하면 서버 주소나 인증 매개변수가 남을 수 있으므로 민감한 값을 검토하세요.

일반적인 Xray 배포본에서 API 명령행 도구로 아웃바운드 추가와 제거를 요청할 수 있습니다. 명령 옵션은 설치된 Xray 버전에 따라 확인하고, API 주소는 실제로 열어 둔 로컬 포트와 일치시킵니다.

xray api adi --server=127.0.0.1:10085 --tag=direct-dynamic --config=outbound.json
xray api rmo --server=127.0.0.1:10085 --tag=direct-dynamic

첫 번째 명령은 설정 파일을 사용해 태그가 지정된 아웃바운드를 추가하고, 두 번째는 해당 태그의 아웃바운드를 제거하는 예입니다. 제거 전에 해당 아웃바운드를 참조하는 라우팅이나 관리 작업이 없는지 확인하세요. 호출 결과가 성공으로 표시되어도 실제 트래픽이 그 아웃바운드를 사용한다는 뜻은 아닙니다.

실제 적용 전후에 따라 할 5단계

운영 중인 서버에서는 테스트용 태그로 먼저 검증하고, 기존 아웃바운드와 겹치지 않는 이름을 사용하세요. 다음 순서는 API 접근을 확인한 뒤 추가·확인·제거하는 기본 흐름입니다. 관리 명령을 실행하는 계정과 자동화 프로그램에는 필요한 권한만 부여하고, 설정 파일에는 접근 제한을 적용하세요.

1. 설정 백업

   현재 Xray 설정과 실행 환경을 보관합니다. API 인바운드, 라우팅 규칙, 통계 정책을 기존 배열에 병합했는지 확인하고, 원본 파일을 덮어쓰기 전에 복구 가능한 사본을 준비하세요.

2. 로컬 연결 확인

   Xray가 실행 중인 서버에서 관리 포트 10085에 연결할 수 있는지 확인합니다. 연결이 되지 않으면 먼저 API 인바운드의 주소와 포트, 코어 시작 로그, 로컬 방화벽을 점검하세요.

3. 추가 요청 실행

   태그가 고유한지 확인한 뒤 xray api adi로 아웃바운드 설정 파일을 전달합니다. 명령에 입력한 태그와 JSON의 태그가 일치하는지 확인하고, 비밀번호나 UUID가 포함된 파일을 공개 경로에 두지 마세요.

4. 라우팅 검증

   기존 라우팅 규칙이 해당 아웃바운드를 선택하는지 살펴봅니다. API로 추가된 사실만 확인하지 말고, 의도한 요청이 실제로 그 경로를 이용하는지 로그와 테스트 대상으로 검증하세요.

5. 정리와 영구화

   시험이 끝나면 더 이상 필요하지 않은 태그를 제거합니다. 계속 사용할 변경이라면 관리 시스템의 원본 설정에도 반영하고, 적용 후 재시작해 아웃바운드와 라우팅이 복원되는지 확인하세요.

업링크와 다운링크 통계 조회하기

통계를 수집하려면 설정에서 통계 기능을 활성화하고, 추적하려는 트래픽 방향을 정책에 지정해야 합니다. 다음은 시스템 전체의 아웃바운드 업링크와 다운링크 집계를 켜는 부분 예시입니다. 이미 policy 설정이 있다면 기존 값과 병합해야 하며, 통계 항목이 꺼져 있으면 조회 결과가 비어 있거나 기대한 값과 다를 수 있습니다.

{
  "stats": {},
  "policy": {
    "system": {
      "statsOutboundUplink": true,
      "statsOutboundDownlink": true
    }
  }
}

인바운드 방향도 보고 싶다면 해당 인바운드에 적용되는 사용자 정책 또는 시스템 정책에서 statsInboundUplink와 statsInboundDownlink를 활성화해야 합니다. 정책의 적용 범위는 설정 구조에 따라 달라지므로, 모든 사용자에게 통계를 켜려는지 특정 사용자에 한정할지 결정하세요. 통계가 필요하지 않은 방향까지 무조건 수집하면 메모리와 관리 부담만 늘 수 있습니다.

StatsService의 조회 요청은 통계 이름을 기준으로 값을 찾습니다. 아웃바운드 태그가 proxy-main이면 다음과 같은 패턴으로 업링크 항목을 조회할 수 있습니다.

xray api statsquery --server=127.0.0.1:10085 --pattern="outbound>>>proxy-main>>>traffic>>>uplink"
xray api statsquery --server=127.0.0.1:10085 --pattern="outbound>>>proxy-main>>>traffic>>>downlink"

패턴 검색이 지원되는 명령 옵션과 통계 이름은 설치된 코어의 버전에 따라 확인하세요. 누적값을 주기적으로 읽어 사용량을 계산하려면 같은 시각 간격으로 조회하고, 이전 값보다 새 값이 작아졌을 때는 코어 재시작이나 통계 초기화가 있었는지 고려해야 합니다. 조회 명령의 초기화 옵션은 누적 통계를 지울 수 있으므로, 모니터링 스크립트에서 무심코 사용하지 마세요.

보안과 운영에서 놓치기 쉬운 점

gRPC API는 관리 권한을 가진 인터페이스로 다뤄야 합니다. API 인바운드를 0.0.0.0에 바인딩하면 의도하지 않은 네트워크에서 접근할 수 있습니다. loopback 바인딩을 기본으로 하고, 원격 관리가 필요할 때는 방화벽과 암호화된 터널로 접근 범위를 제한하세요. 방화벽 규칙을 적용했더라도 실제 외부에서 포트가 열려 있지 않은지 별도로 확인해야 합니다.

• 태그를 명확하게 관리: 동적 아웃바운드마다 고유한 태그를 사용하고, 자동화 프로그램에 추가·삭제 기록을 남깁니다. 같은 태그를 여러 작업에서 재사용하면 제거 대상이 예상과 달라질 수 있습니다.
• 요청 권한을 분리: API 호출 권한이 필요한 관리 프로그램만 접근하게 합니다. 사용하지 않는 API 서비스는 활성화하지 말고, 관리용 설정 파일과 인증 정보에 운영체제의 파일 권한을 적용하세요.
• 변경 전후를 검증: 추가 요청, 라우팅 결과, 통계 증가, 제거 요청을 각각 확인합니다. 성공 응답 하나만으로 전체 구성이 정상이라고 판단하지 마세요.
• 코어 버전을 기록: API 명령 옵션과 설정 지원 여부는 Xray 버전에 따라 달라질 수 있습니다. 운영 환경과 테스트 환경의 버전을 맞춘 뒤 변경을 적용하세요.

동적 관리의 핵심은 API 호출 자체보다 상태를 일관되게 유지하는 데 있습니다. 관리 프로그램이 현재 아웃바운드 목록과 원본 설정을 추적하고, 실패한 추가 요청을 재시도할 때 중복 태그를 처리하며, 제거 실패를 기록하도록 설계하세요. 통계는 조회 시각과 코어 재시작 여부를 함께 기록해야 누적값의 변화를 해석할 수 있습니다. 이런 원칙을 지키면 Xray API를 임시 명령 모음이 아니라 검증 가능한 운영 인터페이스로 활용할 수 있습니다.