공식 매뉴얼 · 설정 참고

Shadowrocket 설정 가이드

설정 파일 구조, 트래픽 분류 규칙 및 매칭 우선순위

처음 연결할 때는 빠른 시작을 참고해 기존 구독이나 서버 정보를 가져온 뒤 연결을 확인하세요. 특정 요청이 왜 직접 연결되는지, 기본 정책이 왜 적용되는지 알아보거나 설정 파일을 수정하려면 이 페이지에서 해당 항목을 확인하면 됩니다. 아직 앱을 받지 않았다면 전체 플랫폼 다운로드를 먼저 살펴보세요.

iPhone / iPad 버전은 App Store에서 $2.99에 한 번 구매하면 됩니다. 시스템 요구 사항은 App Store 페이지를 확인하세요. Mac(Apple 칩 및 Intel), Windows, Android, Linux 버전은 무료이며 설치 파일은 사이트의 /dl/에서 받을 수 있습니다. 앱의 일회성 구매와 네트워크 서비스 이용료는 별개입니다. 이 사이트는 노드나 구독을 제공·판매·추천하지 않습니다.

설정 파일 구조와 [General]

설정 파일을 확인할 때는 먼저 어떤 파일을 사용 중인지 확인한 다음 규칙 내용을 살펴보세요. 파일을 가져왔다는 것은 앱에 등록되었다는 뜻일 뿐, 현재 연결을 처리하고 있다는 의미는 아닙니다. Config에서 적용 중인 파일을 확인하고 Home으로 돌아가 Global Routing을 점검하세요. 후자에서 Config를 선택하지 않았다면 실제 연결 결과만으로 파일의 일반 분류 규칙이 적용되었는지 판단할 수 없습니다. 편집 전에 원래 설정을 복원할 수 있도록 보관하고, 현재 사용 중인 파일 이름과 모드를 기록해 두세요.

먼저 섹션을 찾고 각 행의 매개변수를 확인하세요

대괄호는 섹션 이름을 표시합니다. 뒤따르는 내용은 다음 섹션 헤더가 나올 때까지 해당 섹션에 속합니다. [General]에는 일반 설정, [Rule]에는 매칭 조건과 정책, [Host]에는 호스트 이름 해석 매핑, [URL Rewrite]에는 조건에 맞는 URL의 변경 작업을 작성합니다. 이 섹션은 우선순위가 네 단계라는 뜻도, 요청 하나가 파일을 처음부터 끝까지 네 번 처리된다는 뜻도 아닙니다. 문제 유형에 맞는 섹션을 확인하세요. 목적지가 잘못되면 분류 규칙을, 해석 결과가 잘못되면 호스트 매핑을, 경로가 바뀌면 재작성 설정을 점검하면 됩니다.

자주 사용하는 설정 섹션 4가지
설정 섹션주요 기능수정 전 기록할 내용
[General]연결 처리에 사용하는 일반 옵션을 설정합니다.기존 제외 항목과 계속 처리해야 하는 요청입니다.
[Rule]조건에 따라 연결 정책을 선택합니다.요청의 실제 대상, 예상 정책 및 기본 정책입니다.
[Host]특정 호스트 이름의 해석 매핑을 지정합니다.대상 호스트 이름, 원래 주소 및 테스트 주소입니다.
[URL Rewrite]URL을 매칭해 지정한 변경 작업을 실행합니다.원래 URL, 예상 대상 및 리디렉션 결과입니다.

이 네 섹션의 행 형식은 서로 바꿔 쓸 수 없습니다. 등호는 설정 이름과 값을 연결하며 아래의 정적 매핑 예시에서도 사용합니다. 규칙 섹션은 쉼표로 필드를 구분하고, 재작성 예시는 공백으로 매칭식, 대상 주소, 작업을 구분합니다. 코드 블록을 복사할 때 설명 문구를 파일에 넣지 마세요. 앱에서 파일을 읽지 못한다고 알리면 최근 수정한 섹션 헤더와 필드 구분자를 먼저 확인하세요. 특히 입력기에서 만든 전각 쉼표와 등호, 편집기가 자동으로 삽입한 줄바꿈을 점검해야 합니다. 웹페이지에서 보이는 줄바꿈과 파일의 실제 줄바꿈은 다릅니다. 규칙 하나는 한 줄에 작성해야 합니다.

일반 설정: 용도가 확인된 제외 항목만 유지

[General]
skip-proxy = localhost, 127.0.0.1

skip-proxy는 일반 설정의 제외 목록이며, 예시에는 로컬 대상 두 개가 나와 있습니다. 한 줄짜리 DIRECT 규칙과는 다릅니다. 전자는 요청이 프록시 처리 범위에 들어가는지와 관련되고, 후자는 규칙 매칭 후 선택되는 정책 결과입니다. 분류 로그에 항목이 보이지 않는다고 해서 해당 항목이 직접 연결 규칙에 매칭되었다고 단정하지 마세요. 특히 네트워크나 앱에 따라 요청을 수집하는 방식이 다를 수 있으므로, 구체적인 매칭 행을 논하기 전에 요청이 현재 앱의 처리 범위에 들어왔는지 확인해야 합니다.

원래 파일의 다른 일반 설정은 그대로 유지하세요. 도메인 규칙 하나를 추가하려고 출처가 불분명한 설정 전체를 복사하지 마세요. 제외 목록에 다른 대상이 있다면 각 항목의 용도를 먼저 확인하세요. 같은 설정 이름을 반복해 쓰는 것으로 목록을 병합할 수는 없으며, 자동으로 추가된다고 가정해서도 안 됩니다. 특정 서비스의 경로를 바로잡으려는 목적이라면 우선 [Rule]에 정확한 규칙을 추가해 테스트하세요. 일반 설정의 적용 범위가 문제의 원인임을 확인한 경우에만 해당 설정을 별도로 수정하면 수정 전후 상태를 비교하기 쉽습니다.

파일, 모드, 서버를 한꺼번에 바꾸면 테스트 결과를 비교하기 어렵습니다. 한 번에 한 가지 요소만 바꿔 다시 테스트하세요. 먼저 설정을 읽을 수 있는지 확인한 뒤, 요청이 새 규칙에 실제로 도달하는지 확인합니다.

구독 내용과 로컬 규칙 복사본을 구분하는 것도 중요합니다. 기존 구독은 서버 항목을 갱신하는 데 쓰일 수도 있고, 외부 출처에서 설정 파일 전체를 가져오는 데 쓰일 수도 있습니다. 두 동작을 혼동하지 마세요. 편집 전에 앱이 가져온 로컬 복사본을 사용 중인지, 원격 출처에서 계속 업데이트되는 설정을 사용 중인지 확인하세요. 새로 고친 뒤 로컬 수정 사항이 사라진다면 규칙 문법을 바꾸기 전에 파일의 출처와 현재 선택된 파일을 확인하세요. 사용자 지정 행은 인증 정보 없이 따로 기록해 두면 다음 업데이트 후 병합이 필요한지 확인할 수 있습니다.

도메인 규칙: 정확 매칭, 접미사, 키워드

대상 호스트 이름을 알고 있다면 도메인 규칙부터 사용하세요. 도메인 필드에는 호스트 이름만 입력하고 프로토콜, 포트, 경로, 쿼리 매개변수는 넣지 않습니다. 웹 주소에서 조건을 가져올 때는 전체 주소에서 호스트 이름을 먼저 추출하세요. 주소 표시줄에는 최상위 페이지의 위치만 나타납니다. 이미지, 세션 API, 정적 리소스는 다른 호스트에 요청할 수 있습니다. 홈페이지는 열리지만 일부 콘텐츠가 실패한다면 실패한 요청을 구분해야 합니다. 이를 근거로 같은 호스트 이름에 두 가지 정책이 동시에 적용되었다고 추측할 수는 없습니다.

요구 사항을 가장 좁은 조건으로 표현하세요

도메인 규칙 비교
키워드조건 예시매칭 범위
DOMAINapi.example.com이 호스트 이름 전체와 정확히 일치하는 경우만 매칭합니다.
DOMAIN-SUFFIXexample.com해당 도메인과 하위 도메인을 매칭합니다. 비슷한 철자의 다른 도메인은 하위 도메인으로 취급하지 않습니다.
DOMAIN-KEYWORDexample호스트 이름에 해당 문자열이 포함된 요청을 매칭합니다.
[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

이 예시는 먼저 API 호스트를 예외로 처리한 뒤 같은 도메인의 나머지 요청을 PROXY로 보냅니다. api.example.com 요청은 첫 번째 행에서 멈추므로 두 번째 행은 실행되지 않습니다. www.example.com은 접미사 행에 매칭됩니다. api.example.org는 해당 접미사에 속하지 않지만 키워드 행에는 매칭됩니다. 키워드 행은 적용 범위를 보여 주기 위한 예시이지 모든 설정에 남겨 두라는 뜻은 아닙니다. 명확히 나열할 수 있는 도메인 하나만 처리하려면 이 넓은 조건을 삭제하세요. 접미사가 여러 개라면 대개 하나씩 작성하는 편이 나중에 확인하기 쉽습니다.

접미사는 파일 확장자나 URL 끝부분이 아닙니다. 예를 들어 example.com.other.test는 example.com의 하위 도메인이 아니지만 assets.example.com은 하위 도메인입니다. 키워드는 도메인 레이블 경계에 맞출 필요가 없으므로 무관한 호스트 이름에 같은 문자열이 있어도 매칭될 수 있습니다. 비슷한 도메인이 있는지 확인하지 않았다면 브랜드 약칭, 환경 이름, 흔한 업무 용어를 키워드로 사용하지 마세요. 한 사이트와 테스트 도메인을 함께 처리하려면 모호한 조건 하나보다 정확 매칭이나 접미사 조건 두 개가 보통 관리하기 쉽습니다.

사이트 표시 이름이 아니라 요청 대상을 확인하세요

웹페이지 문제를 살펴볼 때는 페이지 열기, 이미지 가져오기, 양식 제출처럼 재현 가능한 동작을 기록하고 해당 동작에서 발생한 호스트 이름을 확인하세요. 다른 앱의 경우 바탕 화면 아이콘에 표시된 이름을 도메인 필드에 넣지 마세요. 클라이언트에 목적지 IP만 표시된다면 도메인 규칙으로 호스트 이름을 매칭할 수 없습니다. 기록에 요청 도메인과 주소 중 무엇이 표시되는지 확인한 뒤 적절한 유형을 선택하세요. 도메인이 특정 주소로 해석된다고 해서 해당 주소를 사용하는 다른 도메인에도 같은 정책을 적용해야 하는 것은 아닙니다.

경로는 도메인 규칙의 매칭 범위에 포함되지 않습니다. 같은 호스트의 경로 두 개가 서로 다른 기능을 하더라도 동일한 도메인 조건에 매칭됩니다. DOMAIN의 두 번째 필드에 슬래시와 경로를 넣어도 더 세밀하게 분류되지 않습니다. 직접 관리하는 HTTP 주소의 경로를 바꾸려면 URL Rewrite를 참고하세요. 인터페이스 하나만 테스트하려는 경우 해당 인터페이스의 전체 URL로 테스트를 시작해도 되지만, 매칭 조건에는 호스트 이름을 입력해야 합니다.

도메인 규칙은 최소 두 가지 예시로 확인하세요. 원래 매칭되어야 하는 대상 하나와 철자가 비슷하지만 매칭되면 안 되는 대상 하나를 테스트합니다. 예외도 설정했다면 넓은 규칙이 먼저 요청을 가져가지 않는지 확인하기 위해 예외도 테스트하세요.

서버에 리소스 도메인이 추가되면 같은 용도에 속하는지 먼저 확인한 뒤 정확한 조건을 추가할지 기존 접미사 범위를 넓힐지 결정하세요. 접미사 범위를 넓히면 나중에 추가되는 하위 도메인에도 영향을 줍니다. 반복 관리는 줄일 수 있지만 테스트나 관리용 진입점의 경로까지 바뀔 수 있습니다. 공통 범위가 확실하지 않다면 새 호스트를 별도로 추가하세요. 각 키워드의 필드와 범위를 빠르게 확인하려면 규칙 유형 자세히 알아보기를 참고하세요.

주소 규칙: GEOIP, IP-CIDR, IP-CIDR6

주소 규칙은 연결의 목적지 주소를 매칭합니다. 기기의 주소나 접속자의 지역을 기준으로 하지 않습니다. 주소로 직접 접속하는 서비스, 용도가 확인된 주소 대역, 도메인 예외 뒤에 적용하는 넓은 지역 조건을 처리할 때 유용합니다. 안정적인 내부 네트워크 대역을 주소로 지정하는 것은 간단하지만, 공용 도메인을 주소로 대체하는 것은 신중해야 합니다. 공용 서비스는 주소가 바뀔 수 있고 무관한 사이트와 주소를 공유할 수도 있으므로, 한 번의 DNS 조회 결과를 장기 규칙으로 바로 사용하지 마세요.

주소 유형과 접두사 범위를 먼저 구분하세요

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR6,2001:db8:1::/48,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

IP-CIDR에는 IPv4 대역을 작성합니다. 예시의 /16은 앞의 16비트가 고정된다는 의미이며 192.168.0.0부터 192.168.255.255까지 전체 범위를 포함합니다. 주소가 고정된 기기 한 대에만 접속하려는 경우 해당 주소와 /32를 사용하면 범위를 좁힐 수 있습니다. 앞의 세 옥텟이 동일한 서브넷이 실제로 필요할 때만 /24를 사용하세요. 접두사가 짧을수록 범위가 넓습니다. 슬래시 뒤 숫자를 기기 수로 해석하면 안 됩니다. 파일에 넣기 전에 대역 안의 주소 하나와 인접 대역 주소 하나로 경계를 각각 확인하는 것이 좋습니다.

IP-CIDR6에는 IPv6 대역을 작성합니다. 예시 주소는 문서용으로 예약된 주소이며 실제 온라인 서비스 주소가 아닙니다. IPv6 주소 한 개만 지정하려면 /128을 사용하세요. IPv4 조건 하나만으로 IPv6 요청에도 같은 정책이 적용된다고 추측하지 마세요. 하나의 호스트가 두 유형의 주소를 모두 반환할 수 있으며, 실제 연결 대상은 네트워크와 서비스 상태에 따라 달라집니다. 네트워크마다 같은 도메인의 결과가 달라진다면 실제로 사용된 주소 유형을 비교해 한쪽에만 해당 조건이 설정되어 있는지 확인하세요.

지역 데이터와 해석의 범위 이해하기

GEOIP,CN,DIRECT는 목적지 주소가 지역 데이터에서 CN으로 분류될 때 DIRECT를 실행한다는 뜻입니다. 도메인 접미사를 기준으로 판단하지 않으며 콘텐츠 언어, 계정 지역, 서비스 제공업체 이름도 식별하지 않습니다. 공유 인프라를 사용하는 사이트는 네트워크에 따라 서로 다른 주소로 해석될 수 있고, 데이터베이스의 지역 분류가 예상과 다를 수도 있습니다. 특정 사이트가 항상 같은 경로를 사용해야 한다면 도메인 예외를 먼저 설정하고 지역 규칙은 일반 조건으로 사용하세요. 지역 표시는 사이트의 정체성을 증명하지 않습니다.

대상이 처음에 도메인으로 나타났다면 도메인만으로 주소 조건을 판단할 수 없습니다. 매칭하려면 사용 가능한 목적지 주소가 필요하며, 경우에 따라 DNS 해석도 이루어집니다. 앞에 배치된 주소 규칙이 도메인으로 처리할 수 있었던 요청을 먼저 주소 기준으로 판단하게 할 수 있습니다. 특정 호스트가 반드시 지정된 정책을 따라야 한다면 주소 판단이 필요한 일반 규칙보다 도메인 규칙을 앞에 두세요. 주소 범위를 우선 적용하려는 경우에만 주소 규칙을 앞으로 옮기고, 도메인이 확인된 요청으로 다시 테스트하세요. 브라우저에서 별도로 조회한 결과를 클라이언트가 이번에도 반드시 사용한다고 가정하지 마세요.

주소 매칭과 주소 연결 가능 여부는 별개의 문제입니다. 대상이 DIRECT에 올바르게 매칭되더라도 현재 네트워크에 해당 대역으로 가는 경로가 없을 수 있습니다. 이때 접두사를 바꿔도 경로가 생기지는 않습니다.

내부 서비스 문제를 확인할 때는 먼저 네트워크를 확인하세요. 서로 다른 장소에서 같은 사설 네트워크 대역을 사용할 수 있습니다. 원래 네트워크를 벗어나면 기존 주소에 접속하지 못하거나 다른 기기에 연결될 수 있습니다. 넓은 사설 주소 직접 연결 규칙으로는 장소를 구분할 수 없습니다. 특정 위치의 서비스 하나만 허용해야 한다면 조건을 기록하고 모든 사설 주소로 범위를 넓히지 마세요. 기존 일반 제외 항목도 확인해야 합니다. 대상이 규칙 처리에 들어오지 않으면 주소 규칙 매칭이 보이지 않아도 접두사 오류라는 뜻은 아닙니다.

주소 규칙을 테스트할 때는 두 가지 관찰 결과를 기록하세요. 실제 매칭된 행과 연결이 종료된 단계를 각각 기록합니다. 주소 범위 안의 테스트가 실패하면 정책을 잘못 선택했는지, 예상대로 직접 연결했지만 목적지에 도달하지 못했는지 먼저 확인하세요. 프록시 연결이 실패하면 선택한 서버가 테스트 대상에 접속할 수 있는지 점검합니다. 한 번 접속할 수 없었다는 이유로 전체 대역을 직접 연결에서 프록시로 바꾸지 마세요. 되돌려야 한다면 방금 추가한 주소 조건을 제거하고 같은 목적지로 다시 연결해야 새 규칙이 변화의 원인이었는지 확인할 수 있습니다.

요청 식별자와 PROXY, DIRECT, REJECT

규칙의 앞쪽 필드는 무엇을 기준으로 테스트할지, 행 끝의 필드는 매칭 후 무엇을 할지 나타냅니다. USER-AGENT는 사용할 수 있는 요청 식별자를 기준으로 판단하는 조건입니다. PROXY, DIRECT, REJECT는 정책입니다. 식별자를 정책으로 오해하지 말고 화면의 Proxy 모드를 규칙 행의 첫 필드로 쓰지도 마세요. 아래 예시에서는 세 정책을 각기 다른 행에 두어 매칭과 실행 결과를 따로 확인할 수 있습니다.

요청 식별자 매칭의 전제 조건

[Rule]
DOMAIN,unused.example.com,REJECT
USER-AGENT,ExampleReader*,PROXY
DOMAIN,docs.example.com,DIRECT
FINAL,DIRECT

예시의 ExampleReader*는 접두사 매칭을 설명합니다. 대상은 실제 요청에 포함된 User-Agent 값이지 앱 아이콘 이름, 설치 파일 이름, 로그인 계정이 아닙니다. 요청 라이브러리에 따라 식별자가 다를 수 있고, 한 앱의 웹 보기, 리소스 로드, 백그라운드 작업도 서로 다른 값을 보낼 수 있습니다. 식별자는 변경하거나 생략할 수 있으므로 인증 수단으로 대체할 수 없으며, 특정 연결이 특정 앱에서 왔다고 단정하는 근거도 아닙니다. 테스트에는 제어 가능한 예시 요청을 사용하고 전송된 식별자와 실제 매칭 행을 기록하세요.

또한 규칙을 사용할 수 있는지는 클라이언트가 해당 요청에서 어떤 필드를 확인했는지에 따라 달라집니다. 연결 기록에 호스트 이름이 있다고 해서 읽을 수 있는 요청 헤더도 있다는 뜻은 아닙니다. 특히 “암호화된 사이트에 연결됨”을 “식별자 필드를 반드시 매칭할 수 있음”으로 해석하면 안 됩니다. 기록으로 확인할 수 없다면 키워드를 계속 줄여 억지로 매칭하려 하지 마세요. 특정 서비스를 처리하려는 목적이라면 확인 가능한 정확한 도메인 규칙을 우선 사용하세요. 식별자로 요청을 구분해야 하고 테스트에서 해당 필드를 확인할 수 있을 때만 이 유형의 규칙을 유지하세요.

정책을 선택한 뒤에는 웹페이지뿐 아니라 실제 동작도 확인하세요

기본 정책의 기능과 확인 방법
정책기능우선 확인할 항목
PROXY현재 선택한 프록시로 요청을 처리합니다.프록시 선택이 올바른지, 서버가 대상에 접속할 수 있는지 확인합니다.
DIRECT현재 네트워크에서 목적지 서비스에 직접 접속합니다.현재 네트워크의 DNS 해석과 라우팅, 목적지 서비스를 사용할 수 있는지 확인합니다.
REJECT매칭된 요청을 거부합니다.거부된 대상이 실제로 의도한 호스트 또는 요청인지 확인합니다.

PROXY는 서버 주소가 아니며 구독을 자동으로 추가하지도 않습니다. 이 정책에 매칭된 뒤에도 앱에 사용할 수 있는 서버가 이미 등록되어 있고 선택되어 있어야 합니다. 매칭 기록은 예상대로인데 페이지 요청이 실패한다면 같은 서버를 선택한 상태에서 접속 가능한 것으로 확인된 민감하지 않은 대상 하나를 테스트한 다음, 해당 프록시가 실패한 대상에 접속할 수 있는지 확인하세요. 구독을 새로 고치는 데 문제가 있다면 빠른 시작에서 가져오기와 연결 절차를 확인하세요. 서버 가용성 테스트와 분류 규칙 수정은 서로 다른 작업이므로 동시에 하지 마세요.

DIRECT는 앱을 종료하거나 연결을 끊는다는 뜻이 아닙니다. 해당 요청이 직접 연결을 선택했다는 의미이며, 앱은 다른 요청에 다른 규칙을 적용할 수 있습니다. REJECT는 요청을 적극적으로 거부하는 정책입니다. 앱에서 오류를 표시하거나 반복해서 재시도할 수 있고, 일부 리소스만 표시되지 않을 수도 있습니다. 페이지가 실패했다는 이유만으로 거부 규칙이 원인이라고 단정하지 말고 일부 리소스가 로드되지 않았다는 이유로 모든 거부 항목을 바꾸지도 마세요. 정확히 어떤 요청과 규칙이 매칭되었는지 범위를 좁히세요. 넓은 접미사 조건 하나가 본문, 로그인, 리소스 서비스를 함께 포함할 수 있다는 점도 주의해야 합니다.

요청 하나에 여러 조건이 동시에 적용될 수 있습니다. 예를 들어 예시의 문서 호스트가 지정된 식별자를 사용할 수도 있습니다. 식별자 매칭이 가능하면 뒤에 있는 정확한 도메인 직접 연결보다 식별자 행의 PROXY가 먼저 실행됩니다. 문서 호스트를 항상 직접 연결하려면 해당 도메인 규칙을 식별자 행보다 앞으로 옮기세요. 변경 후에는 해당 호스트와 계속 프록시를 사용해야 하는 비교 대상도 다시 테스트해 무관한 동작이 바뀌지 않았는지 확인하세요.

매칭 순서, FINAL 및 Global Routing

분류를 확인할 때는 파일 내부 행 순서보다 먼저 Global Routing을 확인하세요. 같은 파일도 모드에 따라 다르게 적용됩니다. [Rule]의 특정 규칙이 적용되는지 확인하려면 먼저 Config를 선택하세요. Proxy 또는 Direct로 연결을 비교 중이라면 전체 프록시 경로 또는 직접 연결 경로가 작동하는지만 확인할 수 있습니다. 특정 규칙이 올바르게 작성되었는지 증명할 수는 없습니다. 비교 테스트가 끝나면 필요한 원래 모드로 되돌리세요.

모드와 규칙 정책의 관계
화면 표시선택 기준확인하기 좋은 항목
Config현재 설정에 따라 트래픽을 분류합니다.규칙 매칭 순서, 예외 및 기본 정책입니다.
Proxy처리 범위에 들어온 트래픽에 프록시 경로를 사용합니다.현재 서버를 사용할 때 요청을 완료할 수 있는지 확인합니다.
Direct처리 범위에 들어온 트래픽에 직접 연결 경로를 사용합니다.현재 네트워크에서 대상에 직접 접속할 수 있는지 확인합니다.

먼저 매칭된 규칙이 먼저 실행되며, 가장 정확한 규칙을 자동으로 선택하지 않습니다

[Rule]
DOMAIN,health.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

규칙 매칭을 시작한 새 요청을 예로 들어 보겠습니다. health.example.com에 접속하면 첫 번째 조건이 충족되어 즉시 직접 연결됩니다. www.example.com에 접속하면 두 번째 행에서 처리가 멈춥니다. 나머지 요청만 지역 조건을 확인하고, 그래도 매칭되지 않으면 FINAL이 실행됩니다. 처음 두 행의 순서를 바꾸면 확인용 주소도 접미사 조건에 먼저 매칭됩니다. 이는 정확한 규칙이 작동하지 않는다는 뜻이 아니라 그 규칙을 실행할 차례가 오지 않았다는 뜻입니다. 설정은 알려진 예외, 일반 조건, 넓은 조건 순으로 배치하세요. 업무상 예외를 덮어써야 하는 경우에만 이 순서를 바꾸면 됩니다.

범위가 같은 조건에 서로 다른 정책을 지정해도 파일 끝의 규칙이 마지막으로 적용되는 것은 아닙니다. 중복 행을 발견하면 기존 설정에서 가져온 행인지 먼저 확인한 뒤 정책을 바꿀지 범위가 더 좁은 예외를 추가할지 결정하세요. 어떤 조건이 가리는지 찾기 어렵다면 대상 호스트와 매칭될 수 있는 모든 조건을 파일 순서대로 나열하세요. 충분한 정보가 있고 처음으로 조건을 충족한 행부터 확인해야 합니다. 그 행을 건너뛰고 아래쪽의 정확한 조건을 계속 다시 작성하지 마세요.

기본 정책은 동작을 선택하는 설정이지 문제 해결책이 아닙니다

FINAL에는 규칙 이름과 정책만 쓰며 도메인이나 주소 필드는 쓰지 않습니다. [Rule]의 마지막 행에 두세요. 그 뒤에 작성한 일반 조건은 유효한 예외가 되지 않습니다. FINAL,DIRECT는 목록에 없는 요청을 직접 연결하므로 프록시가 필요한 대상을 명시적으로 나열하는 설정에 적합합니다. FINAL,PROXY는 목록에 없는 요청을 프록시로 보내므로 프록시를 기본으로 사용하고 직접 연결 예외를 관리하는 설정에 적합합니다. 선택하기 전에 알 수 없는 대상에 어떤 처리를 해야 하는지 생각하세요. 한 번 테스트에 실패했다는 이유로 목록에 없는 모든 요청의 동작을 급하게 뒤집지 마세요.

요청이 FINAL에 매칭되었다면 그보다 앞선 조건이 요청을 처리하지 않았다는 뜻입니다. 먼저 새 규칙이 실제로 필요한 대상인지 확인한 다음 대상 필드, 접두사, 행 순서를 점검하세요. 전역 기본 정책부터 바꾸지 마세요.

규칙을 확인할 때는 최소 세 가지 비교 동작을 테스트하세요. 정확한 예외에 해당하는 대상, 넓은 조건에만 해당하는 대상, 둘 다에 해당하지 않는 대상을 각각 방문합니다. 주소나 식별자 조건도 있다면 세 번째 대상이 다른 규칙에 먼저 매칭되지 않았는지 확인하세요. 수정 내용을 저장하고 적용된 것을 확인한 뒤 새 연결을 시작해야 합니다. 화면만 새로 고쳐서는 기존 연결을 재사용하지 않는다고 보장할 수 없습니다. 브라우저 캐시, 앱의 장시간 연결, 기존 페이지 요청 때문에 결과가 늦게 반영될 수 있습니다. 이전 기록이 보인다고 해서 행 순서가 적용되지 않았다고 판단하지 마세요.

요청 동작과 기록이 일치하지 않으면 모드를 잠깐 바꿔 비교해 보세요. 직접 연결은 되지만 프록시 연결이 안 되면 우선 선택된 서버를 점검합니다. 두 경로 모두 되지만 설정 모드에서 실패한다면 매칭 행과 해당 행의 정책을 집중적으로 확인하세요. 둘 다 실패하면 대상과 현재 네트워크부터 확인합니다. 직접 연결과 프록시 경로를 비교할 때는 두 경로 모두 허용되는 테스트 대상을 사용하세요. 비교 결과가 규칙 기록을 대신할 수는 없지만 잘못된 섹션을 반복해서 수정하는 일을 줄여 줍니다.

[Host]: 해석 매핑과 트래픽 분류의 차이

[Host]는 지정한 호스트 이름의 해석 매핑을 설정합니다. 브라우저의 URL을 다른 도메인으로 바꾸지 않으며 PROXY나 DIRECT를 직접 선택하지도 않습니다. 관리할 수 있는 테스트 환경에서 원래 호스트 이름을 유지한 채 알고 있는 테스트 주소를 사용하려는 경우에 적합합니다. 예를 들어 직접 관리하는 서비스를 확인할 수 있습니다. 기존 사이트의 네트워크 경로만 바꾸려는 목적이라면 [Rule]을 수정하면 됩니다. 정책에 맞추려고 먼저 해석 설정을 변경하지 마세요.

이름, 주소, 정책을 각각 기록하세요

[Host]
lab.example.com = 192.0.2.20

[Rule]
DOMAIN,lab.example.com,DIRECT
FINAL,DIRECT

매핑 행의 왼쪽은 호스트 이름이고 오른쪽은 주소입니다. 여기에는 실제 접속 가능한 서비스를 제공하지 않는 문서용 예약 주소를 사용합니다. 규칙 행은 해당 호스트에 접속할 때 사용할 정책을 지정하며 매핑을 만들지는 않습니다. 예시에서 두 곳에 같은 호스트 이름이 적혀 있어도 테스트 결과를 두 질문으로 나눠야 합니다. 예상한 주소가 요청을 받았는지, 요청이 예상한 경로를 사용했는지 각각 확인하세요. 직접 관리하는 테스트 서비스라면 서버에 요청이 도착했는지와 클라이언트 기록을 대조할 수 있습니다. 페이지가 열렸다는 사실만으로 매핑이 적용되었다고 증명할 수는 없습니다.

원래 사이트의 전체 주소를 등호 왼쪽에 넣거나 오른쪽에 포트와 경로를 덧붙이지 마세요. 호스트 이름 해석과 연결 대상 포트는 서로 다른 매개변수입니다. 실제 포트는 요청에서 지정되거나 프로토콜의 기본값으로 선택됩니다. 테스트 포트를 사용하는 서비스라면 요청을 보내는 쪽에서 포트를 명시해야 합니다. 호스트 이름을 해당 도메인 전체에 적용되는 패턴으로 함부로 넓히지도 마세요. 서비스 하나만 확인하려면 정확한 호스트 이름을 지정해 같은 도메인의 다른 진입점에 예상치 못한 영향을 주지 않도록 하세요.

캐시, 해석 경로 및 서비스의 정체성

정적 매핑은 해당 매핑을 사용하는 해석 과정에 영향을 줄 수 있지만 모든 앱과 모든 해석 경로를 강제로 바꾸지는 않습니다. 앱에 캐시가 있거나, 주소로 직접 연결하거나, 자체적으로 해석하거나, 실제 해석을 원격에서 처리한다면 로컬에 매핑 행을 추가한 뒤 모든 요청이 새 주소를 사용한다고 가정하지 마세요. 먼저 확인하려는 앱에서 새 요청을 보내고 기록된 목적지 주소를 확인하세요. 다른 앱이나 시스템 조회 도구의 결과만 비교하지 마세요. 같은 해석 경로를 사용하지 않았을 수 있습니다.

호스트 이름에 새 주소를 지정해도 해당 사이트의 신원 확인이 새 주소로 이전되지는 않습니다. 요청은 계속 원래 호스트 이름을 사용하며, 관리 대상 테스트 서버는 해당 이름에 맞는 서비스를 제공할 수 있어야 합니다. 인증서가 일치하지 않거나 업무 페이지가 다르게 표시되거나 서버가 예상치 못한 사이트를 반환하면 해당 호스트 이름과 포트의 서버 설정부터 확인하세요. 인증서 경고를 무시한 채 매핑이 성공했다고 판단하지 말고 직접 관리하지 않는 사이트의 해석 결과를 임의로 바꾸지 마세요. 테스트 중에는 계정 정보가 없는 요청을 사용해 실제 세션이 잘못된 대상으로 전송되지 않도록 하세요.

문제가 DNS 해석 오류로 확인되었다면 GEOIP 예외를 동시에 추가하거나 기본 정책을 바꾸지 마세요. 주소 조건은 실제 목적지 주소에 따라 매칭되므로 해석 결과가 바뀌면 해당 조건의 매칭도 간접적으로 달라질 수 있습니다. 이 변수를 고정하려면 테스트용 복사본에 명확한 도메인 규칙을 유지한 뒤 주소를 따로 확인하세요. 매핑이 올바른 것을 확인한 다음 주소에 의존하는 일반 조건을 복원할지 결정하세요. 이렇게 하면 새 주소를 검증하면서 프록시와 직접 연결의 차이를 해석 확인에 섞지 않을 수 있습니다.

매핑 행은 유지 기간이 명확한 테스트에 적합합니다. 테스트가 끝나면 활성 설정에서 제거하고 새 연결을 시작해 해석 결과가 복원되었는지 확인하세요. 테스트용 복사본을 보관한다면 테스트 환경에서만 사용하는 설정임을 표시하세요.

매핑을 제거한 뒤에도 이전 주소에 연결된다면 현재 파일에 같은 이름의 매핑이 중복되어 있지 않은지, 이전 연결이 재사용되고 있지 않은지 먼저 확인하세요. 시스템의 모든 해석 설정을 바로 바꾸지 말고 같은 네트워크에서 새 요청을 보내 기록을 비교하세요. 활성 파일이 새로 고침되는 출처에서 제공되었다면 매핑을 로컬에서 추가했는지 원래 파일에 포함되어 있었는지도 확인하세요. 원래 파일에 있었다면 설정을 업데이트할 때 다시 나타날 수 있습니다. 지속적인 변경은 올바른 출처에서 수정하고 임시 확인은 별도 복사본에서 진행하세요.

[URL Rewrite]: URL 매칭과 리디렉션 확인

재작성은 확인 가능한 요청 URL을 처리합니다. 직접 관리하는 테스트 서비스에서 이전 경로에서 새 경로로의 전환을 확인할 때 사용할 수 있으며, 트래픽 분류 규칙과는 다른 문제를 해결합니다. DOMAIN은 호스트의 요청에 적용할 정책을 결정하지만 이전 경로를 새 경로로 바꾸지는 않습니다. [Host]는 해당 매핑을 사용하는 해석 주소를 바꿀 수 있지만 경로는 변경하지 않습니다. 요청 대상이 예상과 다르면 경로, 해석 결과, 클라이언트가 실제로 요청한 URL 중 무엇이 바뀌었는지 먼저 구분하세요.

정확한 HTTP 요청 하나로 시작하세요

[URL Rewrite]
^http://example\.com/old$ http://example.com/new 302

이 행에는 매칭 표현식, 대상 URL, 작업 순으로 작성합니다. 시작의 ^와 끝의 $는 주소 전체를 조건으로 지정합니다. \.는 도메인에 실제로 있는 점을 뜻하며 임의의 문자를 나타내지 않습니다. 전체 주소가 이전 경로와 정확히 같은 샘플만 이 표현식에 매칭됩니다. 쿼리 매개변수, 끝의 슬래시, 다른 프로토콜이 포함된 주소는 이 예시에 해당하지 않습니다. 마지막의 302는 임시 리디렉션을 의미합니다. 리디렉션을 따르는 요청 측에서 대상 주소로 후속 요청을 보냅니다. 후속 요청의 도착지는 주소와 적용되는 규칙을 각각 확인해야 합니다.

예시 주소는 작성 방법을 설명하기 위한 것으로 해당 사이트가 이 두 경로를 제공한다는 뜻은 아닙니다. 직접 관리하는 테스트 호스트와 개인 정보가 없는 읽기 전용 요청으로 확인하세요. example.com을 테스트 호스트로 바꾸더라도 왼쪽 표현식의 점은 계속 이스케이프해야 합니다. 오른쪽의 리터럴 대상 URL에서는 일반 점을 사용합니다. 테스트 서비스에 명시적 포트가 필요하다면 매칭식에도 실제 입력되는 포트를 반영해야 합니다. 모든 페이지를 덮는 표현식을 먼저 작성한 뒤 추가 규칙으로 부작용을 막으려 하지 마세요. 경로 하나가 예상대로 리디렉션되는 것을 확인한 뒤 범위를 넓히세요.

매칭 범위, 쿼리 매개변수 및 리디렉션 루프 확인

이 예시는 의도적으로 HTTP를 사용합니다. 클라이언트가 HTTPS 연결의 호스트 정보를 확인할 수 있다고 해서 연결 내부의 경로나 요청 내용도 직접 읽을 수 있다는 뜻은 아닙니다. 호스트 이름이 보인다는 이유로 접두사를 HTTPS로 바꾸어도 완전히 동일하다고 가정하지 마세요. 브라우저에서 HTTP를 테스트할 때는 브라우저가 먼저 입력을 HTTPS로 업그레이드하는지도 확인해야 합니다. 그러면 실제 요청이 예시와 일치하지 않습니다. 테스트 서버에 기록된 실제 프로토콜과 URL부터 확인하고 매칭을 위해 일반 브라우징의 보안 설정을 낮추지 마세요.

쿼리 매개변수도 매칭 경계의 일부입니다. 이 예시는 매개변수가 붙은 이전 주소까지 처리하지 않으며 대상에 매개변수를 자동으로 덧붙이지도 않습니다. 업무상 매개변수를 처리해야 한다면 유지할 매개변수와 전달하지 않을 매개변수를 각각 명확히 정하고 인증 정보가 없는 테스트 값으로 결과를 확인하세요. 로그인이나 제출 요청은 이 예시만으로 동작을 추론하기에 적합하지 않습니다. 요청 측에서 리디렉션을 따를 때 메서드가 바뀔 수 있고 서비스가 요청 본문에 의존할 수도 있습니다. 마이그레이션 확인은 일반 읽기 요청부터 시작하고 제출 동작이 있는 경로는 별도로 테스트하세요.

대상 주소가 이 조건에 다시 매칭되거나 다른 재작성 규칙에 의해 원래 주소로 돌아가서는 안 됩니다. 확인할 때는 최소 세 번 요청하세요. 이전 주소는 리디렉션되어야 하고, 대상 주소는 정상적으로 완료되어야 하며, 조건에 해당하지 않는 비슷한 경로는 그대로 유지되어야 합니다. 브라우저에서 리디렉션이 반복된다고 표시되면 실제 대상을 단계별로 확인해 설정에서 발생한 리디렉션과 서버에서 발생한 리디렉션을 구분하세요. 마지막 주소 표시줄만 보지 마세요. 잘못된 중간 리디렉션이 이후 페이지에서 가려져도 리소스 요청이나 다른 접속 방법에는 영향을 줄 수 있습니다.

테스트에서는 먼저 첫 응답을 확인하세요. 예상한 임시 리디렉션이 발생했는지, 대상 주소가 올바른지 확인합니다. 그런 다음 리디렉션을 따른 요청이 도착하는지 점검하세요. 재작성 규칙에 매칭되었다는 사실과 대상에 접속할 수 있다는 사실은 별개의 결론입니다.

테스트용 재작성을 비활성화한 뒤 새 요청을 직접 보내 다시 비교하세요. 결과를 캐시한 페이지, 서버의 기존 리디렉션, 앱의 URL 업그레이드 동작이 계속 나타나 설정이 아직 작동하는 것처럼 보일 수 있습니다. 현재 파일에 해당 행이 없음을 확인했다면 요청 측이 이전 결과를 재사용하는지, 대상 서버에서 원래 같은 리디렉션을 제공하는지 확인하세요. 기록에는 테스트 도메인, 경로, 작업만 남기고 실제 신원 정보가 포함된 전체 주소는 복사하지 마세요.

설정 예시, 확인 순서 및 되돌리기

다음은 기존 설정을 조금 수정하는 예시입니다. 상태 확인 호스트는 직접 연결하고 같은 도메인의 다른 서비스는 선택한 프록시를 사용하며, 확인된 내부 네트워크 대역은 직접 연결하고 목록에 없는 대상도 직접 연결합니다. 템플릿의 도메인은 문법 설명용이므로 테스트가 허용된 직접 관리 호스트로만 바꾸세요. 프록시가 필요한 경우에는 본인의 구독이나 서버 정보를 이미 가져왔고 기존 연결의 가용성을 테스트했다는 전제가 필요합니다.

[Rule]
DOMAIN,health.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.40.0/24,DIRECT
FINAL,DIRECT

예상 결과를 먼저 정하고 항목별로 확인하세요

이 내용을 기존 파일의 FINAL 뒤에 그대로 덧붙여서는 안 되며, 사용하려고 설정 파일 전체를 새로 만들 필요도 없습니다. 기존에 [Rule]이 있다면 해당 섹션에 필요한 조건을 병합하세요. 먼저 앞선 행이 관련 대상을 이미 처리하는지 확인한 뒤 삽입 위치를 정합니다. 기본 정책은 목록에 없는 요청의 동작을 실제로 바꾸려는 경우에만 교체하세요. 기존 기본값이 직접 연결이라면 내부 네트워크 행은 현재 기본 결과와 같지만 의도를 명시하기 위해 작성할 수 있습니다. 나중에 기본 정책을 바꿀 때는 이 명시적 예외도 다시 확인해야 합니다.

테스트 기록에는 각 항목의 대상, 예상 매칭 행, 예상 정책, 실제 결과를 적으세요. 상태 확인 호스트로 첫 번째 행을 확인하고, 같은 도메인의 다른 호스트로 접미사를 확인하며, 지정한 내부 주소로 대역을 확인합니다. 다른 범위에 해당하지 않는 대상을 사용해 기본 정책도 확인하세요. 충돌 예시도 추가해야 합니다. 같은 도메인의 요청이 최종적으로 내부 대역 주소를 가리킬 때 앞선 도메인 접미사 규칙이 우선 적용됩니다. 실제로는 호스트 이름과 상관없이 내부 주소를 항상 직접 연결해야 한다면 현재 행 순서는 요구 사항에 맞지 않습니다. 주소 조건을 사용할 수 있는지 먼저 확인한 뒤 순서를 조정하고 앞의 두 항목도 다시 테스트하세요.

매칭 성공 여부와 연결 성공 여부를 구분해야 합니다. 잘못된 규칙에 매칭되었는데 페이지가 열렸더라도 검수를 통과한 것이 아닙니다. 같은 대상이 프록시와 직접 연결 경로 모두에서 열릴 수 있습니다. 반대로 규칙에 올바르게 매칭되었지만 연결할 수 없다고 해서 바로 규칙을 바꾸면 안 됩니다. 어떤 대상 유형에서 실패가 발생하는지 확인하세요. 프록시 대상만 실패한다면 기존 서버 선택과 연결 상태를 점검하고, 내부 대상만 실패한다면 테스트 중인 네트워크와 실제 주소를 확인하세요. 페이지 일부 요청만 실패한다면 리소스가 사용하는 호스트 이름과 해당 요청의 매칭 기록을 비교하세요.

적용 안 됨, 매칭 안 됨, 연결 실패 순으로 단계별 확인

첫 번째 단계는 파일과 모드입니다. 저장 후 활성 설정과 Global Routing을 다시 확인하고 테스트 요청을 새로 시작했는지 점검하세요. 새 규칙이 기록에 전혀 반영되지 않는다면 파일을 잘못 선택했거나 비교 모드를 사용 중인지 먼저 확인합니다. 두 번째 단계는 매칭 필드입니다. 주소만 있다면 주소를 기준으로 확인하고, 도메인이 있다면 실제 호스트 이름과 행 순서를 점검하세요. 웹페이지 제목으로 추측하지 마세요. 세 번째 단계에서 정책 실행을 확인합니다. 올바른 정책에 매칭되었다면 직접 연결이나 프록시 연결 중 어느 단계에서 실패했는지 점검하세요. 화면의 위치를 확인하려면 화면 영어 용어 대조표를 참고하세요.

네트워크를 전환한 뒤에만 문제가 발생한다면 같은 설정, 같은 모드, 같은 서버를 유지하고 네트워크만 바꿔 비교하세요. 달라진 것이 해석 주소인지, 매칭 규칙인지, 접속 결과인지 기록합니다. 주소가 바뀌면 다른 지역 또는 네트워크 대역 조건에 매칭될 수 있습니다. 규칙과 정책은 같은데 실패한다면 네트워크 경로를 확인하는 편이 좋습니다. 앱을 시작할 때 설치나 다운로드 문제가 발생한다면 설정을 편집해 해결하려 하지 말고 다운로드 페이지의 설치 안내나 스토어 및 계정 지역 안내를 먼저 확인하세요.

되돌릴 때는 보관해 둔 원래 설정으로 전환하고 서버와 테스트 네트워크는 그대로 둔 채 같은 요청을 다시 테스트하세요. 원래 설정에서 문제가 재현되지 않는 경우에만 이번 설정 변경을 항목별로 비교할 근거가 있습니다.

되돌렸다고 해서 관찰 결과를 지울 필요는 없습니다. 민감한 내용을 제거한 설정 차이와 최소 재현 기록을 보관하고 예상과 실제의 차이를 적으세요. 원래 파일에서도 같은 현상이 나타난다면 규칙을 더 추가하지 말고 빠른 시작으로 돌아가 기존 구독, 서버 선택, 기본 연결을 다시 확인하세요. 새 파일에서만 문제가 재현된다고 확인되면 다음에는 조건 한 묶음만 추가하고 검수를 통과한 뒤 두 번째 묶음을 추가하세요. 이렇게 하면 어떤 변경이 동작을 바꿨는지 찾기 쉽고 설정 출처가 업데이트된 뒤에도 다시 확인할 수 있습니다.