Shadowrocket
규칙 및 설정 가이드

설정 파일은 연결 처리 방식을 설명하며 서버 계정 자체를 담고 있지는 않습니다. 이 점을 이해하면 ‘가져온 뒤 서버가 표시되는 것’과 ‘트래픽 분류 설정이 선택된 것’을 혼동하지 않을 수 있습니다. 서버 정보는 어디에 어떤 프로토콜과 인증 방식으로 연결할지를 정하고, 설정 파일은 어떤 요청을 직접 연결하거나 프록시로 보내고 거부할지 정합니다. 두 항목은 함께 사용해야 하지만, 하나를 가져왔다고 다른 하나까지 준비된 것은 아닙니다. 기존 구독을 사용하는 경우 Home에서 서버 정보를 확인한 다음 Config에서 실제로 활성화된 설정을 점검하세요.

섹션 이름, 필드, 규칙 행

Shadowrocket 설정 텍스트는 대괄호로 묶은 섹션 이름으로 용도를 구분합니다. [General]에는 일반 매개변수를 넣으며, 보통 필드 이름, 등호, 필드 값의 형태입니다. [Rule]에는 순서가 있는 트래픽 분류 규칙을, [Host]에는 지정한 호스트 이름의 주소 매핑을, [URL Rewrite]에는 조건에 맞는 URL 처리 규칙을 작성합니다. 섹션 이름은 단순한 제목이 아니므로 잘못된 위치에 넣으면 해석 방식이 달라집니다. General의 등호 문법을 Rule에 적용하거나, 설명용 한국어를 규칙 매개변수 뒤에 덧붙이지 마세요.

[General]
bypass-system = true

[Rule]
DOMAIN,router.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY

[Host]
router.example.com = 192.168.1.1

이 예시는 각 섹션의 관계를 보여 주기 위한 것이며 모든 네트워크에서 그대로 사용할 수 있는 완성 설정이 아닙니다. 첫 번째 규칙은 지정한 호스트를 직접 연결하고, 두 번째는 예시 도메인과 하위 도메인에 적용되며, 세 번째는 사설 주소 대역을 대상으로 하고, 마지막 규칙은 나머지를 처리합니다. Host 매핑은 예시 호스트 이름을 주소에 연결할 뿐, 해당 주소에서 서비스가 제공된다는 뜻은 아닙니다. 실제로 저장할 때는 용도를 이해하는 데 필요한 기존 필드를 유지하세요. 원격에서 관리하는 설정이라면 다음 업데이트에서 로컬 변경 사항이 덮어써지는지도 확인해야 합니다.

복사본 저장 및 활성 설정 확인

수정하기 전에 Config에서 현재 선택된 설정을 확인하고, 이름과 복구할 위치를 기록한 뒤 별도 복사본을 저장하세요. 파일을 열어 편집했다는 사실만으로 그 파일이 실제 연결 처리에 사용되고 있다고 볼 수는 없습니다. 저장 후 설정 목록으로 돌아가 선택 상태를 확인하고 새 연결로 검증하세요. 편집 화면에 문법 오류가 표시되면 먼저 수정한 뒤 활성화하세요. 구문 오류가 있는 상태에서 내용을 더 추가하면 이후의 현상을 특정 변경 사항과 연결하기 어려워집니다.

설정 파일 복사본과 서버 백업은 별개로 관리해야 합니다. 규칙 설정을 복원해도 서버 인증 필드는 복구되지 않을 수 있고, 구독을 다시 가져와도 수동으로 추가한 규칙은 돌아오지 않을 수 있습니다. 이전이나 복원 전에 서버, 설정, 필요한 앱 설정을 각각 확인하세요. 설정에는 개인 도메인, 서버 식별 정보 또는 인증 정보가 포함될 수 있습니다. 다른 사람에게 문제 해결 자료를 전달하기 전에는 이런 정보를 삭제하고, 문제를 재현하는 데 필요한 최소 규칙과 정리된 연결 기록만 남기세요.

이 페이지의 설정 예시 읽는 법

예시의 example.com은 문법 설명용이며, 사용할 수 있는 구독 주소나 특정 정책이 필요한 도메인을 뜻하지 않습니다. 예시 주소와 규칙은 실제 환경에 맞게 바꿔야 합니다. 코드 블록의 빈 줄은 내용을 구분하기 위한 것입니다. 완전한 섹션은 그대로 참고할 수 있지만 일부 발췌한 내용은 해당 설정 섹션에 넣어야 합니다. 잘 모르는 옵션은 먼저 앱에서 인식되는지 확인하고 적용 범위를 살펴보세요. 필드 이름이 비슷해도 동작은 다를 수 있으므로, 이름만 보고 추측해 여러 항목을 추가하지 마세요.

원격 규칙 파일과 로컬 설정은 유지 관리 방식도 다릅니다. 예외 규칙을 추가할 때는 수정 이유와 테스트 대상, 기대한 정책을 기록하고 업데이트할 때마다 예외가 계속 유지되는지 확인하세요. 출처를 알 수 없는 긴 목록보다 이해하기 쉬운 소수의 규칙을 유지하는 편이 관리하기 쉽습니다. 이 매뉴얼은 ‘실행 조건 설정, 매칭 범위 지정, 정책 선택, 결과 확인’ 순서로 설명합니다. 문제 해결도 같은 순서로 점검하세요.

Rule의 규칙이 올바른지 따지기 전에 Global Routing부터 확인하세요. 설정 파일을 저장했더라도 현재 실행 모드가 Config가 아니라면 규칙이 적용되지 않는 것이 일반적인 원인일 수 있습니다. 화면의 Config, Proxy, Direct는 각각 설정 기반 분류, 프록시 연결, 직접 연결 모드를 뜻합니다. 특정 규칙의 우선순위를 조정하는 기능이 아니라 연결을 처리하는 전체 방향을 정합니다. 트래픽 분류를 테스트할 때는 Config를 명확히 선택하고, 매번 검증하기 전에 실행 모드가 바뀌지 않았는지 확인하세요.

General은 별도의 규칙 목록이 아닙니다

[General]의 필드는 일반 동작을 제어하며, 도메인별 Rule을 대신하지 않습니다. 예를 들어 bypass-system과 skip-proxy는 시스템이나 특정 대상의 우회 처리와 관련되며 일반 Rule 매칭과는 다른 단계에서 작동합니다. 대상이 앞선 우회 경로에서 처리되면 Rule에 PROXY를 추가해도 기대한 결과가 보이지 않을 수 있습니다. 따라서 문제를 해결할 때 규칙뿐 아니라 일반 설정 때문에 연결이 예상한 처리 경로를 거치지 않는지도 확인해야 합니다.

[General]
bypass-system = true
skip-proxy = 127.0.0.1, localhost, *.local
dns-server = system

이 예시는 시스템 우회 동작을 유지하고 로컬 호스트 및 로컬 도메인 형식을 함께 표시하며 DNS에는 시스템의 해석 설정을 사용합니다. 필드를 이해하기 위한 예시이므로 기존 설정을 덮어쓰고 그대로 사용하는 것은 권장하지 않습니다. 특히 skip-proxy 목록은 일반 필드의 값이며, 이를 근거로 Rule에서도 같은 와일드카드 형식을 사용할 수 있다고 추측하면 안 됩니다. 기존 파일을 확인할 때는 먼저 해당 행이 어느 섹션에 속하는지 파악하고, 쉼표로 구분된 항목을 필드의 의미에 맞춰 해석하세요.

연결 스위치, On Demand, 규칙은 각각 다른 단계에서 동작합니다

Home의 연결 스위치는 연결 처리를 시작하거나 중지합니다. Global Routing은 실행 모드를 정하고, 활성 설정의 Rule은 Config 모드에서 매칭 정책을 정합니다. 이 세 가지를 각각 확인해야 합니다. On Demand는 조건을 충족할 때 연결을 필요에 따라 시작할지 처리하며, 도메인마다 PROXY 또는 DIRECT를 선택하는 기능은 아닙니다. 네트워크 전환 후 상태가 달라졌다면 먼저 연결이 유지되는지 확인하고, 다음으로 실행 모드를 점검한 뒤 마지막으로 규칙 순서를 확인하세요.

처음 연결할 때 시스템에서 VPN 구성을 추가하도록 허용해 달라는 메시지가 표시될 수 있습니다. 이 권한은 앱이 해당 시스템 네트워크 기능을 사용할 수 있도록 허용하는 것이며, 서버에 연결할 수 있다는 보장이나 규칙이 올바르다는 증거는 아닙니다. 첫 연결 과정을 완료하지 않았다면 빠른 시작 가이드의 순서대로 진행하세요. 시스템 요구 사항은 App Store 페이지를 기준으로 확인해야 하며, 다른 사람의 오래된 화면 캡처만 보고 현재 기기의 호환 여부를 판단하지 마세요.

모드 전환으로 제한적인 비교 테스트하기

같은 테스트 대상에 대해 새 연결을 사용해 Direct와 Proxy 결과를 잠시 비교하면 직접 연결 경로와 프록시 경로 중 어느 쪽에 문제가 있는지 구분하는 데 도움이 됩니다. 비교를 마친 뒤에는 Config로 돌아오세요. 테스트 중에는 대상, 네트워크, 서버를 바꾸지 않아야 변수를 줄일 수 있습니다. Proxy에서는 열리지만 Config에서는 실패하는 페이지가 있다면 트래픽 분류를 확인할 필요가 있다는 뜻일 뿐, 모든 DIRECT 규칙이 잘못되었다고 단정할 수는 없습니다. 한 페이지에서 여러 도메인에 접속할 수 있으므로 관련 기록을 하나씩 확인하세요.

Direct에서 페이지가 열린다고 해서 해당 서비스를 항상 직접 연결해야 한다는 뜻도 아닙니다. 네트워크 위치, DNS 응답, 대상 서비스의 접근 조건은 달라질 수 있습니다. 적절한 설정은 실제 요구를 반영해야 하며, 한 번의 테스트 결과를 모든 상황에 적용해서는 안 됩니다. General의 설정이 불확실하다면 먼저 정상 작동이 확인된 복사본으로 되돌린 뒤 항목별로 확인하세요. 여러 스위치를 반복해서 바꾸며 결과를 기대하면 실제 처리 경계를 파악하기 어렵습니다.

도메인 규칙은 ‘어떤 호스트 이름을 기준으로 정책을 선택할지’를 정합니다. 자주 쓰이는 유형은 DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD이며, 차이는 규칙 이름의 길이나 우선순위가 아니라 매칭 범위에 있습니다. 세 유형 모두 Rule에 실제로 배치된 순서대로 판단됩니다. 규칙을 작성하기 전에 URL에서 대상 호스트 이름을 분리하세요. 프로토콜, 포트, 경로, 쿼리 매개변수를 도메인 값에 함께 넣으면 안 됩니다.

DOMAIN: 호스트 하나를 정확히 지정

DOMAIN,api.example.com,PROXY는 특정 호스트 이름에 적용되므로 단일 API나 좁은 범위의 예외에 적합합니다. example.com 전체 도메인이나 모든 하위 도메인까지 자동으로 포함하지는 않습니다. 하나의 앱도 로그인, 이미지, 파일 다운로드에 서로 다른 호스트를 사용할 수 있습니다. DOMAIN 하나를 추가한 뒤 메인 페이지가 열린다고 해서 관련 연결이 모두 같은 정책을 사용한다고 볼 수는 없습니다. 앱 이름으로 도메인을 추측하지 말고 실제 기록을 확인해 필요한 대상을 추가하세요.

DOMAIN-SUFFIX: 도메인과 하위 도메인에 적용

DOMAIN-SUFFIX,example.com,PROXY는 해당 도메인과 하위 도메인에 매칭됩니다. 예를 들어 www.example.com과 api.example.com이 포함됩니다. 여기서 도메인 접미사는 도메인 레이블 경계를 따르므로 임의의 문자열 끝부분과 같다고 보면 안 됩니다. 하위 도메인까지 포함하려면 example.com만 입력하면 되며, https://, 슬래시, 경로를 덧붙일 필요가 없습니다. 그중 특정 호스트를 제외하려면 정확한 호스트 규칙을 이 넓은 범위의 규칙보다 앞에 배치하세요.

[Rule]
DOMAIN,status.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

이 순서는 ‘상태 확인용 호스트는 직접 연결하고, 나머지 예시 도메인은 프록시를 사용한다’는 뜻입니다. 앞의 두 행을 바꾸면 상태 확인용 호스트가 먼저 접미사 규칙에 매칭되어 뒤의 정확한 예외 규칙이 실행되지 않습니다. 정확한 규칙이 예외로 작동하는 것은 DOMAIN이 DOMAIN-SUFFIX보다 자동으로 우선하기 때문이 아니라 앞에 배치되기 때문입니다. 파일을 관리할 때는 예외와 그 예외가 속한 넓은 범위의 규칙을 나란히 두어 관계를 확인하기 쉽게 하세요.

DOMAIN-KEYWORD: 범위가 넓으므로 주의해서 검증

DOMAIN-KEYWORD,example,PROXY는 도메인에 포함된 키워드를 기준으로 매칭하므로 서로 관련 없는 여러 도메인까지 포함할 수 있습니다. 브랜드, 웹사이트 소유자, 페이지 내용을 판별하는 기능은 아니며 영어 단어의 업무상 의미를 이해하지도 않습니다. 짧은 키워드는 특히 여러 단어가 호스트 이름 안에 이어 붙는 경우 예상보다 많은 대상을 포함할 수 있습니다. 키워드 범위가 꼭 필요한 경우가 아니라면 DOMAIN 또는 DOMAIN-SUFFIX를 우선 사용해 도메인만으로 규칙의 의도를 확인할 수 있도록 하세요.

웹 주소를 기준으로 규칙을 작성해도 매칭되지 않을 수 있는 이유

주소 표시줄에는 진입 주소만 표시되지만 페이지 리소스는 다른 호스트에서 제공될 수 있습니다. 리디렉션, 로그인 확인, 미디어 리소스, API 요청은 각각 별도의 연결을 만들기도 합니다. 연결 기록에서 실제로 실패한 대상을 확인하고, 진입 요청이 실패했는지 이후 리소스가 실패했는지 구분하세요. 페이지에 특정 경로가 보인다고 DOMAIN으로 경로를 매칭하려 하지 마세요. 도메인 규칙은 호스트 범위를 지정하며 URL 경로는 별도의 처리 조건입니다.

또한 도메인 규칙이 매칭되려면 해당 연결에서 클라이언트가 사용할 수 있는 도메인 정보를 확인할 수 있어야 합니다. IP에 직접 연결하거나, 앱이 직접 해석을 처리하거나, 기존 연결을 재사용하면 주소 표시줄에서 예상한 결과와 다를 수 있습니다. 도메인 규칙 뒤에는 도메인 조건에 매칭되지 않은 연결을 처리할 주소 규칙과 FINAL도 준비해야 합니다. 문제를 해결할 때는 기록에 표시된 대상 정보를 기준으로 판단하세요. ‘도메인 매칭이 보이지 않는다’는 이유만으로 규칙 파싱 실패라고 단정하지 마세요.

규칙 목록이 길어지면 먼저 업무상 필요한 범위가 가장 좁은 정확한 예외를 작성하고, 그다음 도메인 범위 규칙을 추가한 뒤, 근거가 분명한 경우에만 키워드 규칙을 고려하세요. 범위가 넓은 규칙을 추가할 때마다 매칭되어야 하는 대상 하나와 매칭되면 안 되는 대상 하나를 테스트하세요. 성공 사례만 확인하면 오매칭을 놓칠 수 있습니다. 양쪽을 모두 검증하면 키워드가 너무 짧거나 접미사를 잘못 썼거나 예외 순서가 뒤바뀐 문제를 더 일찍 발견할 수 있습니다.

주소 규칙은 연결 대상 IP를 기준으로 정책을 판단합니다. 이는 ‘어떤 웹사이트가 어느 지역에 속하는가’와는 다른 개념입니다. 한 도메인이 여러 주소로 해석될 수 있으며 네트워크나 시점에 따라 결과도 달라질 수 있습니다. 서비스가 분산형 인프라를 사용할 수도 있으므로 IP-CIDR과 GEOIP는 주소 수준의 조건으로 이해해야 하며, 고정된 웹사이트 분류로 보면 안 됩니다. 같은 도메인이 때로는 직접 연결되고 때로는 프록시를 사용한다면 매번 연결의 대상 주소를 비교한 뒤 주소 규칙이 결과에 적용되었는지 확인하세요.

IP-CIDR: IPv4 주소 대역을 명시

IP-CIDR,192.168.0.0/16,DIRECT는 주소 범위를 나타내며, 슬래시 뒤의 프리픽스 길이가 범위 크기를 정합니다. 프리픽스가 길수록 범위가 좁고, 단일 IPv4 주소에는 /32를 사용할 수 있습니다. 네트워크 주소는 마스크 경계에 맞아야 합니다. 일반 웹 주소, 포트 또는 임의의 시작·끝 주소를 이 매개변수에 넣지 마세요. 로컬 네트워크 규칙을 관리할 때는 현재 네트워크에서 실제 사용하는 주소 대역을 기준으로 하세요. 특정 사설 대역이 모든 로컬 서비스에 공통으로 사용된다고 오해하지 마세요.

[Rule]
IP-CIDR,192.168.1.10/32,DIRECT,no-resolve
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
FINAL,PROXY

첫 번째 행은 단일 주소를, 두 번째 행은 더 넓은 주소 범위를 나타냅니다. 따라서 이 예시에서 첫 번째 행은 최종 정책을 바꾸지 않으며 범위 관계를 확인하기 쉽게 보여 주는 역할을 합니다. 정책이 서로 다르면 순서가 결과에 직접 영향을 줍니다. IPv6 주소에는 IP-CIDR6과 IPv6 프리픽스 표기법을 사용하세요. 브라우저에 도메인이 표시된다고 연결이 IPv4만 사용한다고 볼 수는 없습니다. 문제 기록에 IPv6 대상이 있다면 해당 IPv6 규칙과 실제 네트워크 연결 가능 여부를 확인하세요.

no-resolve: 매칭을 위한 해석 동작 제어

주소 규칙 끝의 no-resolve는 해당 규칙에 매칭하기 위해서만 도메인 해석을 시작하는 것을 방지합니다. 앱 전체에서 DNS를 중지하거나 모든 해석 요청을 차단하는 옵션은 아닙니다. 대상이 이미 IP이거나 연결 처리 과정에 판단에 사용할 주소가 있다면 이 매개변수가 주소 규칙을 항상 건너뛴다는 뜻도 아닙니다. 도메인 규칙을 먼저 적용하고 주소 규칙은 이미 알려진 주소를 보완하는 용도로만 사용하려는 경우 이 매개변수로 불필요한 해석을 줄일 수 있습니다. 실제 기록으로 효과를 확인하세요.

GEOIP: 주소 데이터베이스에 따른 분류

GEOIP,CN,DIRECT는 대상 주소의 데이터베이스 분류를 기준으로 매칭하며 도메인 접미사, 웹페이지 언어, 사용자 위치를 기준으로 판단하지 않습니다. 데이터베이스 업데이트가 늦거나 주소 귀속 정보가 다를 수 있으므로 서비스 운영 주체나 데이터 저장 위치를 증명하는 용도로 사용할 수 없습니다. 특정 도메인에 안정적으로 지정된 정책을 적용해야 한다면 명확한 도메인 규칙이 주소 분류에 의존하는 것보다 설명하기 쉽습니다. GEOIP는 적용 범위를 이해한 뒤 보조 조건으로 사용하세요.

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

이 예시는 명확한 도메인 규칙을 먼저 적용하고 주소 분류 규칙으로 보완한 뒤 마지막에 FINAL로 처리합니다. 도메인 규칙이 이미 매칭되면 GEOIP를 다시 비교해 정책을 바꾸지 않습니다. 반대로 범위가 넓은 주소 조건을 앞에 두면 뒤에 작성한 도메인 규칙의 의도가 실현되지 않을 수 있습니다. 서로 다른 유형의 규칙이 표결하듯 결과를 정한다고 생각하지 마세요. 모든 규칙은 하나의 순서 체인에 있으며, 먼저 매칭된 조건이 해당 연결의 처리 방식을 결정합니다.

USER-AGENT: 요청 정보가 제공될 때 적용

USER-AGENT,Example*,DIRECT는 User-Agent 패턴으로 매칭하는 방법을 보여 주는 예시입니다. 앱 이름을 기준으로 트래픽을 분류하는 기능이 아니며 기기의 모든 앱을 식별한다고 보장하지도 않습니다. 판단에 필요한 정보가 요청에 포함되어 있어야 매칭될 수 있습니다. 암호화된 HTTPS 트래픽에서 연결 스위치만 켜면 HTTP 요청 헤더를 읽을 수 있다고 가정하지 마세요. 정보가 보이지 않는다면 패턴 범위를 계속 넓히는 대신 확인 가능한 도메인 또는 주소 조건을 사용하세요.

진단할 때는 먼저 명확한 DOMAIN 규칙 하나로 기준을 만든 다음 USER-AGENT 같은 보조 조건을 검토하세요. 특정 규칙을 테스트하려고 인증서 신뢰 범위를 넓히거나 요청 처리 설정을 대량으로 변경하지 마세요. 대상 앱이 요청 헤더를 바꾸거나 다른 네트워크 라이브러리를 사용하거나 연결을 재사용하면 패턴 매칭 결과도 달라질 수 있습니다. 규칙의 신뢰성은 이름이 앱과 비슷해 보이는지가 아니라 실제로 확인할 수 있는 입력 조건에 달려 있습니다.

규칙은 매칭 조건과 처리 정책으로 구성됩니다. 매칭 조건은 ‘이 연결이 대상에 해당하는가’를, 정책은 ‘매칭된 뒤 어떻게 처리하는가’를 결정합니다. PROXY, DIRECT, REJECT는 서로 다른 처리 결과이지 연결 품질 등급이 아닙니다. 모든 대상을 같은 정책으로 바꾸면 일시적으로 문제를 피할 수는 있어도 기존 설정의 트래픽 분류 의도가 사라집니다. 먼저 각 대상 유형의 요구를 정하고, 범위가 가장 좁은 매칭 조건과 알맞은 정책을 선택하세요.

위에서 아래로 확인하며 처음 매칭되면 종료

Rule 규칙 목록에서 먼저 나오고 조건을 충족한 규칙이 정책을 결정합니다. 더 구체적인 DOMAIN이 앞에 있는 DOMAIN-SUFFIX보다 항상 우선한다고 가정하면 안 되며, 주소 규칙이 본래 도메인 규칙보다 낮은 우선순위라고 볼 수도 없습니다. 예외를 우선 적용하려면 규칙의 위치를 조정해야 합니다. 복잡한 설정을 읽을 때는 대상 도메인만 검색해 직관에 맞는 행에서 멈추지 말고, 관련된 첫 번째 규칙부터 아래로 확인하세요.

[Rule]
DOMAIN,private.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

이 예시에서는 지정된 두 호스트를 먼저 각각 처리하고, 나머지 예시 도메인은 PROXY로 보냅니다. 도메인 조건에 매칭되지 않은 연결은 주소 규칙을 계속 확인하며, 앞선 규칙에 모두 매칭되지 않은 경우에만 FINAL에 도달합니다. FINAL을 맨 앞에 두면 뒤의 규칙은 정상적으로 매칭될 기회를 잃습니다. FINAL에는 도메인이나 주소 매개변수를 붙이지 않으며 FINAL,PROXY처럼 작성합니다. 일반적인 세 부분 규칙 형식으로 잘못 작성하지 마세요.

PROXY 매칭이 연결 성공을 뜻하지는 않습니다

규칙이 매칭되었다는 사실은 정책 선택 조건이 충족되었음을 보여 줄 뿐입니다. 이후에도 서버 연결 불가, 인증 실패, 대상의 연결 거부, 주소 해석 오류가 발생할 수 있습니다. PROXY는 보통 현재 선택된 프록시 경로를 사용합니다. 기존 설정에서 이름이 지정된 정책이나 정책 그룹을 사용한다면 해당 이름이 실제로 존재하고 예상한 대상을 가리키는지 확인하세요. 이름 오타, 참조된 그룹 삭제, 그룹 내 선택 변경은 ‘규칙은 맞는데 열리지 않는’ 현상을 일으킬 수 있지만 매칭 조건 자체의 문제는 아닙니다.

DIRECT는 현재 네트워크 제한을 우회한다고 보장하지 않습니다. 연결을 대상에 직접 보내는 정책입니다. 로컬 네트워크에서 대상에 접근할 수 없다면 DIRECT 실패는 경로 문제입니다. REJECT는 연결을 명시적으로 거부하며 페이지 레이아웃을 수정하거나 캐시된 콘텐츠를 삭제하거나 같은 호스트에서 용도별 요청을 구분하지는 않습니다. 로그인과 다른 리소스를 한 호스트에서 제공하는 경우 도메인 전체를 거부하면 정상 기능도 함께 영향을 받을 수 있습니다. 적용 범위는 REJECT 규칙 작성법과 매칭 한계에서 더 확인할 수 있습니다.

FINAL 정책 선택 방법

FINAL은 다른 규칙에 매칭되지 않은 연결에 적용되는 기본 처리이며 ‘자동 판단’ 기능이 아닙니다. PROXY를 선택하면 명확하게 분류되지 않은 연결을 프록시 경로로 보내고, DIRECT를 선택하면 직접 연결합니다. 설정 목표와 기존 규칙의 적용 범위, 허용 가능한 실패 유형을 고려해 결정하세요. FINAL만 바꿔도 이전에 주목하지 않았던 많은 연결의 동작이 달라질 수 있습니다. 정상 사례와 문제 사례를 함께 확인하고 웹페이지 하나만 테스트한 뒤 끝내지 마세요.

관리할 때는 FINAL을 하나만 유지하고 규칙 목록의 맨 끝에 배치하세요. FINAL을 여러 개 두어도 대체 경로가 생기는 것은 아니며 앞에 있는 기본 규칙이 먼저 판단을 끝냅니다. 규칙 순서는 서버 장애 시 자동 전환하는 기능도 아닙니다. PROXY 규칙에 매칭된 뒤 연결에 실패해도 아래쪽 DIRECT 규칙으로 자동 진행하지 않습니다. 매칭과 연결 수립은 별개의 단계이므로 이후 규칙을 실패에 대한 대체 처리로 생각하면 안 됩니다.

규칙 목록이 길어지면 완전히 중복된 항목을 정리하고, 위쪽의 넓은 범위 규칙에 이미 포함된 항목이 있는지 확인하며, 중요한 예외의 변경 내역을 기록하세요. Rule 전체를 알파벳순으로 정렬하지 마세요. 정렬하면 우선순위가 달라집니다. 가독성은 실행 순서를 이해하는 데 도움이 되어야 합니다. 같은 그룹의 정확한 예외, 범위 규칙, 보완 규칙을 서로 가까이 배치하고 마지막 기본 규칙은 따로 확인하기 쉽게 두면 설정이 여전히 요구 사항에 맞는지 점검하기 좋습니다.

DNS는 호스트 이름을 주소로 해석하고, 트래픽 분류 규칙은 사용할 수 있는 조건을 기준으로 연결 정책을 선택하며, Host는 지정된 호스트에 주소를 매핑할 수 있습니다. 서로 연관은 있지만 대체할 수 있는 기능은 아닙니다. 페이지가 열리지 않는다면 주소를 얻지 못한 것인지, 적절하지 않은 주소를 얻은 것인지, 주소는 유효하지만 연결 경로가 실패한 것인지 먼저 확인하세요. DNS 설정을 전부 바꾸면 현상이 일시적으로 달라질 수 있지만 장애가 발생한 위치를 설명해 주지는 않습니다.

General의 DNS 설정

dns-server = system은 시스템에서 제공하는 해석 설정을 사용한다는 뜻입니다. 결과는 현재 네트워크 환경에 따라 달라지며 매번 같은 응답을 받는다는 의미는 아닙니다. 기존 설정에서 다른 해석 방식을 명시적으로 사용한다면 그 의미를 보존하고 필드 인식 여부, 주소 연결 가능 여부, 기존 설정과의 호환성을 먼저 확인하세요. 인터넷에서 찾은 주소 목록을 그대로 추가하거나 용도를 모르는 확장 매개변수를 섞은 뒤 규칙이 제대로 작동하는지 판단하지 마세요.

[General]
dns-server = system

[Host]
router.example.com = 192.168.1.1

[Rule]
DOMAIN,router.example.com,DIRECT
FINAL,PROXY

이 예시는 지정한 호스트를 사설 주소로 매핑하고 DIRECT 정책을 명시합니다. Host와 Rule을 함께 작성한 이유는 해석 결과와 처리 정책이 별개의 의도임을 보여 주기 위해서입니다. 로컬 주소로 매핑했다고 반드시 직접 연결되는 것은 아니며 DIRECT 규칙 하나가 올바른 주소를 자동으로 만들어 주는 것도 아닙니다. 실제 기기에서 해당 사설 주소에 접근할 수 있어야 하고 지정한 포트에서 대상 서비스가 실행 중이어야 합니다.

Host는 대상 서비스의 신원을 바꾸지 않습니다

Host는 연결에 사용할 주소를 바꿀 수 있지만 다른 서버를 원래 도메인의 정식 서비스로 바꾸지는 않습니다. HTTPS에는 인증서와 호스트 이름 확인도 포함됩니다. 잘못된 주소에 매핑하면 네트워크 연결이 이루어져도 인증서 오류나 서비스 불일치가 발생할 수 있습니다. 이런 문제가 생기면 매핑을 취소하고 주소를 확인하세요. 신원 확인을 끄는 방법을 일반적인 해결책으로 사용해서는 안 됩니다. 사설 서비스도 도메인과 인증서를 올바르게 구성해야 합니다.

Host를 관리할 때는 주소가 바뀔 수 있다는 점에 주의하세요. 모바일 기기에서 네트워크를 바꾸면 기존 사설 주소에 더 이상 접근할 수 없거나 다른 기기를 가리킬 수 있습니다. 고정 매핑은 명확하고 안정적이며 검증할 수 있는 대상에 적합합니다. 주소가 분산된 공용 서비스 도메인에 한 번의 해석 결과를 장기간 고정해서는 안 됩니다. 여러 주소를 사용하는 도메인에서 IP 하나를 고정하면 정상적인 주소 선택을 방해해 일부 지역에서는 작동하고 다른 네트워크에서는 실패할 수 있습니다.

해석 결과와 규칙 매칭의 순서

도메인 규칙은 도메인을 직접 기준으로 판단할 수 있지만 주소 규칙은 사용할 수 있는 IP 정보가 필요합니다. 주소 판단 과정에서 DNS 해석이 필요할 수 있으며, 앞서 설명한 no-resolve는 매칭을 위해 직접 해석할지 제어합니다. 명시적인 DOMAIN 규칙이 먼저 매칭되면 뒤의 GEOIP 규칙이 결과를 바꾸지 않습니다. 연결 기록을 분석할 때는 대상 도메인, 해석된 주소, 매칭된 규칙, 최종 정책을 함께 확인하세요. 주소의 지역 분류만 비교해서는 안 됩니다.

기록에 IP만 표시된다고 해서 곧바로 Host나 DNS가 작동하지 않는다고 판단하지 마세요. 앱이 IP에 직접 연결했거나 현재 관찰 화면에 도메인 정보가 표시되지 않았을 수 있습니다. 반대로 도메인이 표시되어도 모든 해석이 같은 경로를 거쳤다는 뜻은 아닙니다. 재현할 수 있는 단일 요청을 기준으로 같은 대상과 네트워크를 사용하고 새 연결을 만들어 어떤 단계에서 매칭 정보가 제공되는지 확인하세요.

캐시와 기존 연결이 검증 결과에 영향을 줄 수 있습니다

DNS 설정이나 Host를 수정해도 기존 연결의 대상 주소가 즉시 바뀌지 않을 수 있으며 앱 자체가 해석 결과를 보관하기도 합니다. 설정을 저장한 뒤 필요한 경우 연결을 새로 만들고 대상 앱에서 새 요청을 보내세요. 재생 중인 미디어나 오랫동안 유지된 메시지 연결로 새 규칙을 판단하지 마세요. 수정 전에 이미 연결된 상태일 수 있습니다. 페이지를 새로고침했더라도 기록에서 새로운 대상 연결이 실제로 생성되었는지 확인하세요.

서로 관련 없는 여러 도메인의 해석이 동시에 실패한다면 각 도메인에 Host를 추가하기보다 현재 네트워크와 DNS 경로를 먼저 확인하세요. 한 도메인만 문제가 있다면 오타, 기존 매핑, 대상 서비스 상태를 점검하세요. Host는 주소를 정확히 관리하는 도구이지 모든 DNS 문제를 해결하는 일반 목록이 아닙니다. 매핑을 소수의 명확하고 되돌릴 수 있는 항목으로 유지하면 모바일 기기가 네트워크를 전환할 때도 안정적으로 관리할 수 있습니다.

URL Rewrite와 Rule은 역할이 다릅니다. Rule은 연결에 PROXY, DIRECT, REJECT 등의 정책을 선택하고, URL Rewrite는 처리할 수 있는 요청 URL을 매칭해 변경합니다. 특정 도메인의 연결 경로를 바꾸려면 URL Rewrite로 트래픽 분류를 대신하지 말고 먼저 Rule을 사용하세요. URL 전체의 특성을 기준으로 요청을 처리해야 한다면 필요한 요청 정보가 보이고 처리 조건을 충족하는지 확인하세요.

정규식이 대상으로 삼는 항목부터 파악하기

URL Rewrite의 매칭 부분은 보통 정규 표현식을 사용하므로 시작 앵커, 문자 이스케이프, 매칭 범위를 구분해야 합니다. 정규식에서 도메인의 점은 특수한 의미가 있으므로 문자 그대로의 점을 나타내려면 \.로 작성합니다. 앞의 ^는 URL 시작 위치부터 매칭하도록 제한합니다. 필요한 경계 표시가 없으면 매칭 범위가 넓어질 수 있습니다. 정규식 일부를 DOMAIN에 넣지 마세요. 두 기능은 서로 다른 매칭 문법을 사용합니다.

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

이 예시는 리디렉션 문법만 보여 줍니다. 지정 호스트의 정확한 경로를 매칭해 요청을 다른 경로로 보내며 상태 코드로 302를 사용합니다. 끝의 $는 문자열의 끝을 제한하므로 쿼리 매개변수가 붙은 URL은 이 예시와 자동으로 같은 조건이 되지 않습니다. 대상 주소 역시 문법 예시이며 실제 서비스 테스트용이 아닙니다. 임의로 넓게 매칭하기보다 범위가 좁고 설명 가능한 조건부터 작성하면 리디렉션이 예상한 요청에만 적용되는지 확인하기 쉽습니다.

쿼리 매개변수, 경로 경계, 리디렉션 반복

URL의 경로, 쿼리 문자열, 호스트 이름은 서로 다른 부분입니다. 쿼리 매개변수를 허용하려면 매칭 범위와 보존 방식을 명확히 설계하세요. 모든 경계를 간단히 제거해도 동작이 같을 것이라고 기대해서는 안 됩니다. 매개변수에 로그인 상태, 서명, 일회용 식별자가 포함될 수 있으므로 임의로 제거하면 요청이 실패할 수 있습니다. 인증에 사용되는 요청은 원래 상태를 유지하고, 먼저 개인정보가 없는 테스트 대상에서 표현식의 실제 결과를 확인하세요.

변경된 대상이 같은 규칙에 다시 걸리지 않는지도 확인해야 합니다. 원본 범위에 대상 범위가 포함되면 클라이언트나 대상 서비스가 계속 리디렉션하여 페이지가 반복해서 로드되거나 리디렉션 횟수 초과 메시지가 표시될 수 있습니다. 여러 Rewrite 항목이 서로를 가리키는 경우도 있습니다. 문제를 해결할 때 ‘원본 URL, 변경 대상, 서버가 다음에 반환하는 위치’의 순서를 적고 각 단계를 확인하세요. 첫 번째 표현식의 매칭 여부만 살펴서는 안 됩니다.

HTTPS에서 전체 요청이 자동으로 노출되지는 않습니다

HTTPS의 경로와 요청 헤더는 암호화된 통신 안에 있으므로 일반 트래픽 분류만으로 전체 URL을 읽고 변경할 수 있다고 가정해서는 안 됩니다. 도메인 분류가 가능하다고 해서 경로 변경도 사용할 수 있다는 뜻은 아닙니다. HTTPS 요청 처리와 관련해서는 앱 내 기능, 인증서 신뢰 범위, 대상 앱의 검증 방식을 별도로 이해해야 합니다. 일부 앱은 더 엄격한 인증서 검증을 사용하므로 모든 요청을 같은 방식으로 처리할 수 있다고 보장할 수 없습니다.

REJECT와 콘텐츠 처리의 차이

Rule의 REJECT는 매칭된 연결을 대상으로 하며 페이지의 요소를 하나씩 분석하지 않습니다. 필요한 API와 콘텐츠가 같은 도메인을 공유하면 해당 호스트를 거부할 때 다른 요청도 함께 영향을 받습니다. URL Rewrite는 더 세밀한 URL 조건을 표현할 수 있지만 실제로 볼 수 있는 정보, 프로토콜 방식, 대상의 동작에 따라 제약이 있습니다. 특정 Rewrite 또는 차단 규칙을 모든 앱에 통하는 콘텐츠 정리 방법으로 해석하지 마세요. 로딩 실패가 발생했다고 규칙이 의도한 결과를 달성한 것으로 단정해서도 안 됩니다.

Rewrite를 검증할 때는 개인정보가 포함된 전체 주소를 저장해 공개하지 말고 원본 URL의 구조, 기대한 대상, 실제 리디렉션을 기록하세요. 변경된 대상이 원래 프로토콜 요구 사항을 유지하는지, 경로나 매개변수가 예상치 않게 빠지지 않았는지 확인한 뒤 페이지의 기능이 정상적으로 작동하는지 살펴보세요. 트래픽 분류 테스트와 마찬가지로 영향을 받지 않아야 할 요청도 함께 검증해 정규식이 지나치게 넓어 같은 사이트의 로그인, 결제, 기타 필수 과정에 영향을 주지 않는지 확인해야 합니다.

유지 관리 시에는 임시 테스트 항목과 장기적으로 필요한 항목을 따로 기록하고, 더 이상 근거가 없는 표현식은 삭제하세요. 원격 설정을 업데이트한 뒤에는 관련 규칙의 매칭 범위가 바뀌었는지도 확인해야 합니다. 거부 정책과 도메인 범위에 대한 자세한 설명은 REJECT의 원리, 매칭 범위와 한계를 참고하세요. 요청 수준의 처리가 실제로 필요한지 결정하기 전에 연결 수준의 적용 범위부터 이해하세요.

효과적인 문제 해결에서는 네 가지를 확인해야 합니다. 대상이 무엇인지, 어떤 규칙에 매칭되었는지, 어떤 정책을 사용했는지, 어느 단계에서 최종적으로 실패했는지입니다. 단순히 ‘열리지 않는다’는 설명만으로는 규칙, 해석, 연결 경로 중 어디에 문제가 있는지 알기 어렵습니다. 시작하기 전에 반복해서 접근할 수 있는 테스트 대상을 하나 정하고 현재 네트워크, 활성 설정, 서버 선택을 기록하세요. 테스트 중 여러 조건이 자동으로 바뀌지 않게 하세요. 문제 해결 자료를 공유할 때는 개인 주소 매개변수와 인증 정보를 삭제해야 합니다.

재현에 필요한 최소 규칙 그룹 만들기

복구 가능한 설정을 먼저 복사한 뒤 대상에 범위가 좁은 DOMAIN 규칙 하나를 추가하세요. 해당 규칙을 포함할 수 있는 다른 규칙보다 앞에 배치합니다. 저장하고 선택 상태를 확인한 다음 Config 모드에서 새 연결을 시작하세요. 요청 또는 연결 기록에서 확인할 수 있는 대상, 규칙, 정책 정보를 살펴보세요. 화면에 표시되는 정보는 다를 수 있으므로 현재 앱의 표시를 기준으로 판단해야 합니다. 예상한 정책에 매칭되었다면 매칭 조건을 더 바꾸지 말고 해석 결과와 경로 연결 가능성을 확인하세요.

[Rule]
DOMAIN,test.example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,DIRECT

이 예시는 규칙 선택을 쉽게 확인할 수 있도록 테스트 호스트 하나와 나머지 연결을 분리한 것이며 일반적인 설정 권장안은 아닙니다. 실제로 관리하는 테스트 대상에 맞게 예시 호스트를 바꾸세요. 검증을 마치면 유효한 변경 사항을 원래 설정에 반영하고 기존 기본 처리 의도를 복구해야 합니다. 임시 설정이 짧다는 이유로 원본 파일의 다른 필수 규칙, 일반 매개변수, 로컬 서비스 예외를 무시하지 마세요.

현상을 단계별로 분류하고 모든 실패를 규칙 오류로 보지 않기

Connectivity Test는 관련 연결 조건을 판단하는 데 도움이 될 수 있지만 테스트 결과가 대상 앱의 실제 요청을 대신하지는 않습니다. 테스트에 응답이 왔다고 대상 도메인이 올바르게 해석되거나 모든 프로토콜, 포트, 리소스가 사용 가능하다는 뜻은 아닙니다. 반대로 개별 테스트가 실패한 경우에도 테스트 방식에 따라 결과를 해석해야 합니다. 진단 도구는 범위를 좁히는 단서로 사용하고, 최종 동작은 실제 대상에 새로 연결해 확인하세요.

구독 업데이트와 규칙 업데이트는 따로 확인

기존 구독 업데이트에 실패하면 Rule을 바로 다시 작성하지 말고 주소가 완전한지, 현재 네트워크가 정상인지, 계정 상태가 유효한지부터 확인하세요. 서버 목록이 비어 있는 문제와 트래픽 분류 규칙이 잘못 매칭되는 문제는 서로 다른 단계에 있습니다. 단일 공유 링크와 구독 주소는 업데이트 방식도 다르므로 한쪽을 다른 쪽처럼 반복해서 가져오면 안 됩니다. 가져오기 경로는 구독을 가져오는 네 가지 방법에서, 형식 차이는 공유 링크와 구독 주소 안내에서 확인하세요.

원격 설정 업데이트 후 동작이 달라졌다면 먼저 변경된 섹션을 비교하고 직접 추가한 예외가 남아 있는지 확인하세요. 구독 업데이트, 설정 교체, 서버 변경을 한꺼번에 진행한 뒤 단일 결과로 원인을 추측하지 마세요. 구독이 비어 있거나 파싱에 실패하는 문제는 구독 업데이트 실패 및 목록이 비어 있을 때 확인할 사항을 참고하세요. 이 페이지는 설정과 매칭 로직을 다루며 서비스 출처를 추천하지 않습니다.

복구, 재테스트 및 장기 유지 관리

수정 후 더 넓은 범위에서 문제가 발생하면 정상 작동이 확인된 설정 복사본으로 먼저 복구하고 Global Routing, 서버 선택, 일반 설정도 함께 복원되었는지 확인하세요. 복구한 뒤 연결을 새로 만들고 같은 대상을 다시 테스트해 기존 상태가 정상인지 확인합니다. 실패한 설정에 서로 충돌하는 예외를 계속 추가하지 마세요. 각 임시 규칙의 용도를 설명할 수 있어야 하며 그렇지 않으면 이후 문제 해결이 우연한 결과에 의존하게 됩니다.

장기적으로 관리하려면 어떤 설정 섹션을 왜 수정했는지, 어떤 대상을 테스트해 통과했는지, 어떻게 복구할 수 있는지 간단히 기록하세요. 더 이상 사용하지 않는 도메인, 중복 규칙, 지나치게 넓은 키워드, 필요 없는 Host 매핑도 정기적으로 점검합니다. 구매 복원, 호환성, App Store 검색 문제는 구매 복원 안내와 App Store 검색 확인 방법을 참고하세요. 기본 사용 절차를 다시 확인하려면 빠른 시작 가이드로 돌아가세요.