Shadowrocket
규칙 및 설정 필드

설정 파일 구조와 적용 전 확인 사항

설정 파일은 서버 목록이 아닙니다

설정 파일은 클라이언트가 요청을 처리하는 방식을 정의하고, 서버 정보는 연결을 설정하는 데 필요한 내용을 담습니다. 두 항목은 따로 확인해야 합니다. 구독을 가져온 뒤 Home에 항목이 표시된다는 것은 서버 데이터가 클라이언트에 들어왔다는 뜻일 뿐, 특정 규칙 파일이 활성화됐다는 의미는 아닙니다. 반대로 설정 파일이 정상적으로 저장되어도 그 안의 PROXY 정책에 사용할 수 있는 연결이 있다는 뜻은 아닙니다. 문제를 확인할 때는 두 대상을 먼저 구분해 서버 인증 정보 문제를 규칙 교체로 해결하려 하지 마세요.

Config에서 현재 선택된 설정을 확인한 뒤 Global Routing이 Config인지 확인하세요. 이 모드는 현재 설정에 따라 트래픽을 처리하므로 이 페이지의 Rule 예제를 살펴보기 위한 전제입니다. Proxy 또는 Direct로 바꾸면 요청 처리 경로가 달라집니다. 같은 규칙 매칭 결과를 기대하며 설정의 옳고 그름을 판단할 수 없습니다. 파일 이름은 구분을 위한 것일 뿐, 이름이 같다고 내용까지 같은 것은 아닙니다. 파일이 여러 개라면 선택 상태와 실제 저장된 텍스트를 특히 주의해 확인하세요.

섹션 이름에 따라 역할 구분하기

섹션 이름은 대괄호 안에 쓰며, 뒤따르는 각 줄을 어떤 문법으로 해석할지 결정합니다. General은 보통 키와 값으로 구성되고, Rule은 영문 쉼표로 구분한 규칙 필드를 사용하며, Host는 도메인을 주소에 매핑합니다. 도메인 규칙을 Host 아래에 붙여 넣거나 일반 설정을 Rule 아래에 넣으면 텍스트가 완전해 보여도 원래 기대한 대로 동작하지 않습니다. 편집할 때는 키워드만 검색하는 것보다 먼저 섹션 이름을 확인한 다음 내용을 추가하는 편이 안전합니다.

[General]
dns-server = system

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

[Host]
router.example.com = 192.168.1.1

위 파일에는 역할이 다른 세 섹션이 있습니다. 도메인 접미사 규칙은 연결 정책을 선택하고, Host 행은 특정 호스트 이름의 해석 주소를 지정합니다. 둘은 같은 방식으로 덮어쓰는 설정이 아닙니다. 이 예제에서 DIRECT를 기본 처리로 둔 것은 매칭 범위를 명확히 보여 주기 위해서이지, 모든 상황에서 이 값을 사용하라는 뜻은 아닙니다. 기본 정책을 바꾸려면 먼저 미매칭 요청을 어떻게 처리할지 정하고, 선택한 연결이 실제로 작동하는지 확인하세요. 파일 이름만 보고 용도를 판단하지 마세요.

되돌릴 수 있는 편집 절차 만들기

수정하기 전에 현재 설정을 내보내거나 복사본을 보관하고, 테스트 파일에는 용도를 알아볼 수 있는 이름을 붙이세요. 복사본을 열고 한 번에 설정 섹션 하나 또는 밀접한 관련이 있는 규칙 묶음 하나만 변경합니다. 저장한 뒤 Config에서 선택된 항목을 다시 확인하세요. 다른 파일을 편집했다면 텍스트를 저장하는 것만으로 현재 사용 중인 설정이 자동으로 바뀌지는 않습니다. 테스트가 끝나면 변경 목적을 기록하세요. 성공한 변경은 유지하고, 실패하면 검증된 복사본으로 돌아가세요. 불확실한 필드를 계속 덧붙이지 마세요.

설정 텍스트의 구두점도 문법의 일부입니다. 규칙에는 영문 쉼표, 키-값 설정에는 영문 등호, 주소 범위에는 슬래시를 사용합니다. 서식 있는 텍스트에서 복사했다면 한글 구두점, 보이지 않는 공백, 줄바꿈으로 잘린 필드가 섞이지 않았는지 확인하세요. 편집기에서 긴 규칙이 자동으로 줄 바꿈되어 보여도 실제 줄바꿈이 아닐 수 있습니다. 파일의 실제 행을 기준으로 판단하세요. 주석은 규칙의 의도를 설명할 수 있지만 정책 필드를 대신하지 않으며, 연결 암호를 설명에 적어서도 안 됩니다.

원격 설정 업데이트와 수동 편집은 덮어쓰기 가능성도 고려해야 합니다. 원격 출처에서 업데이트되는 파일을 편집 중이라면 다음 업데이트 때 로컬 내용이 바뀔 수 있습니다. 파일 출처와 앱 내 업데이트 동작을 확인한 뒤, 자체 규칙을 관리할 로컬 복사본이 필요한지 결정하세요. 구독 업데이트는 보통 서버 데이터를, 설정 업데이트는 설정 텍스트를 대상으로 합니다. 둘 다 주소를 사용한다고 같은 작업으로 보면 안 됩니다. 저장 및 이전 절차는 설정 백업 및 기기 변경 노트에서 확인하세요.

General 설정과 DNS 해석 범위

일반 설정과 규칙 선택을 구분해서 이해하기

General은 설정의 일반적인 동작을 정의하며 Rule처럼 규칙을 한 줄씩 매칭하지 않습니다. 이 섹션의 설정은 도메인 해석, 주소 처리, 연결 환경에 영향을 줄 수 있지만 별도의 분기 규칙 목록으로 봐서는 안 됩니다. 알 수 없는 필드는 먼저 앱 내 설정 편집이나 안내에서 지원 여부를 확인한 다음 값이 유효한지 판단하세요. 다른 텍스트에 키 이름이 등장했다고 해서 현재 앱이 이를 인식한다는 뜻은 아닙니다. 용도를 확인할 수 없는 필드는 실제 사용하는 설정에 바로 추가하지 않는 편이 좋습니다.

DNS는 호스트 이름을 주소로 해석하고, Rule은 요청 정보를 바탕으로 정책을 선택합니다. 이름 해석에 성공해도 프록시 연결이 성공하는 것은 아니며, 정책을 올바르게 선택해도 해석 결과가 정확하다는 보장은 없습니다. 예를 들어 도메인 규칙이 PROXY에 매칭됐지만 서버 연결에 실패했다면 연결 매개변수가 문제일 수 있습니다. 반대로 DIRECT로 요청이 처리됐는데 접근할 수 없는 주소를 받았다면 해석 출처와 대상 서비스를 확인해야 합니다. 두 단계를 각각 검증하면 수정 범위를 좁힐 수 있습니다.

단순한 DNS 기준 설정부터 유지하기

[General]
dns-server = system

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

dns-server = system은 해당 설정의 이름 해석에 시스템 DNS를 사용한다는 뜻입니다. 이 예제의 목적은 쉽게 되돌릴 수 있는 기준을 마련하는 것이며, 모든 네트워크 환경에서 결과가 같다는 보장은 아닙니다. 시스템 DNS를 사용하면 현재 네트워크의 DNS 설정이 결과에 영향을 줍니다. 네트워크를 바꾸면 해석 결과와 접근 가능 여부도 달라질 수 있습니다. 두 테스트를 비교할 때는 네트워크 환경이 같은지 기록해야 합니다. 그렇지 않으면 네트워크 차이를 규칙 변경의 결과로 오해할 수 있습니다.

DNS 서버를 바꿔야 한다면 먼저 사용자의 네트워크 요구 사항과 현재 앱이 허용하는 값 형식을 확인한 뒤 설정 하나만 수정하세요. 해석 출처 변경, Host 매핑 추가, 규칙 재정렬을 동시에 하면 성공이나 실패의 원인을 파악하기 어렵습니다. 해석 서버 주소와 프록시 서버 주소는 서로 다른 필드입니다. 기존 구독 주소를 DNS 설정에 넣어도 서버가 가져와지지 않습니다. 설정을 마친 뒤 요청을 다시 실행하고 로그에서 받은 주소가 예상과 일치하는지 확인하세요.

도메인, 주소, no-resolve

도메인 규칙은 요청의 도메인을 사용할 수 있으면 매칭할 수 있지만, 주소 규칙은 대상 주소 정보가 필요합니다. 주소가 아직 없는 도메인 요청은 일부 주소 매칭에 판단을 위한 해석이 필요할 수 있으므로 규칙 순서에 따라 추가 해석 여부가 달라질 수 있습니다. 해석 지연을 확인할 때 DNS 설정만 보지 마세요. 매칭을 판단하기 위해 앞쪽 주소 규칙이 해석을 유발하는지, 먼저 매칭할 수 있는 도메인 규칙이 뒤에 놓여 있지는 않은지도 확인해야 합니다.

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

no-resolve는 주소 규칙에 선택적으로 붙이는 수정자로, 해당 규칙의 매칭을 위해 도메인을 능동적으로 해석하지 않도록 합니다. 설정 파일 전체에서 DNS를 끈다는 뜻도, 이후 연결에 해석이 필요 없다는 뜻도 아닙니다. 클라이언트가 대상 주소를 이미 알고 있다면 그 주소를 바탕으로 규칙을 확인할 수 있습니다. 주소가 없다면 이 규칙이 추가 해석을 통해 도메인을 네트워크 대역에 포함할 것이라고 기대해서는 안 됩니다. 모든 규칙 끝에 붙이지 마세요. 도메인 규칙과 FINAL의 의미가 달라지는 것도 아닙니다.

주소 계열과 캐시로 인한 차이

같은 호스트 이름에서 여러 주소가 반환될 수 있으며 서로 다른 주소 계열이 함께 반환되기도 합니다. IPv4 네트워크 규칙 하나만 있다고 IPv6 대상까지 자동으로 처리되지는 않습니다. 반대로 IPv6 주소 규칙을 설정해도 네트워크 연결이 보장되는 것은 아닙니다. 먼저 실제로 사용된 대상 주소를 확인한 다음 규칙에 해당 주소가 포함되는지 판단하세요. 특정 실패를 해결하려고 한 주소 계열을 무작정 비활성화하면 대상 네트워크나 연결 설정의 문제를 가릴 수 있습니다. 관련 스위치는 앱 내 안내를 확인해 설정하세요.

해석 설정을 수정한 뒤에도 기존 연결, 앱 캐시, 시스템 캐시가 관찰 결과에 영향을 줄 수 있습니다. 페이지를 새로고침해도 항상 새 연결이 생기는 것은 아니며, 텍스트가 바뀌었다고 기존 연결이 전체 매칭을 다시 수행하는 것도 아닙니다. 관련 요청을 종료한 뒤 구분하기 쉬운 접근을 새로 실행하세요. 필요한 경우 앱에서 제공하는 기능으로 해석 상태를 갱신합니다. 도메인, 반환 주소, 매칭 정책, 연결 결과를 기록하면 단순히 '열림' 또는 '열리지 않음'만 적는 것보다 비교하기 쉽습니다.

DOMAIN 계열 규칙의 범위와 작성법

정확히 일치하는 규칙과 접미사 규칙

DOMAIN은 전체 도메인 하나를 매칭하고, DOMAIN-SUFFIX는 지정된 도메인과 하위 도메인을 매칭합니다. 둘의 차이는 우선순위가 아니라 우선 범위입니다. 특정 호스트 하나만 처리하려면 정확한 매칭이 영향 범위를 제한하기 쉽고, 도메인 트리 전체를 처리하려면 접미사 매칭이 관리하기 쉽습니다. 어떤 호스트를 포함하고 제외할지 먼저 정한 다음 유형을 선택하세요. 단지 표현이 짧다는 이유로 분기 범위를 넓히는 일을 막을 수 있습니다.

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

이 예제에서는 api.example.com에 PROXY를 사용하고, example.com에 속한 나머지 호스트에는 DIRECT를 사용합니다. 해당 호스트도 접미사 조건에 맞으므로 예외를 더 넓은 범위의 규칙보다 앞에 둬야 합니다. 앞의 두 행을 바꾸면 접미사 규칙이 먼저 매칭되어 아래의 정확한 규칙은 해당 요청의 결과를 결정하지 못합니다. 정확한 매칭 유형이라고 해서 앞선 규칙을 자동으로 건너뛰는 것은 아닙니다. 실행 순서는 텍스트의 위치로 결정됩니다.

도메인 필드에는 호스트 이름만 입력하고 프로토콜, 경로, 쿼리 매개변수, 포트는 포함하지 않습니다. 접속 주소의 페이지 경로는 DOMAIN 매칭 값에 포함되지 않습니다. 전체 페이지 주소를 붙여 넣으면 보통 의도한 호스트 매칭을 표현할 수 없습니다. 경로에 따라 주소를 바꿔야 한다면 도메인 규칙에 슬래시를 추가하지 말고 URL Rewrite를 확인하세요. 편집한 뒤에는 필드를 유형, 매칭 값, 정책으로 나눠 각 역할이 명확한지 점검합니다.

키워드 매칭 범위 관리하기

DOMAIN-KEYWORD는 도메인 안의 키워드를 확인합니다. 매칭 범위는 보통 접미사 규칙보다 텍스트만 보고 파악하기 어렵습니다. 같은 문자열이 관련 없는 호스트 이름에 나타날 수도 있으므로, 도메인 소유 범위를 명확히 정하는 규칙의 대체재로 적합하지 않습니다. 키워드 매칭은 정규식이 아닙니다. 점, 별표, 괄호를 정규식처럼 입력해도 정규식 매칭이 되지 않습니다. 명확한 도메인 목록이 있다면 대상 범위를 정확하게 설명하는 조건을 우선 사용하세요.

[Rule]
DOMAIN,keep.example.com,DIRECT
DOMAIN,ads.example.com,REJECT
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

예제는 앞의 두 행에서 직접 연결 예외 하나를 유지하고 호스트 하나를 정확히 거부한 다음, 키워드 규칙으로 나머지 조건에 맞는 도메인을 처리합니다. 여기서 ads.example.com은 문법 설명용 예시일 뿐 실제 콘텐츠 분류를 나타내지 않습니다. 호스트를 거부하면 페이지 로딩에 필요한 요청까지 영향을 받을 수 있으므로 사용 전에 대상의 용도를 확인하세요. 잘못 거부해 페이지가 비어 보인다면 더 넓은 허용 규칙을 곧바로 추가하지 말고 실제 요청 로그에서 의존 관계를 찾으세요.

하위 도메인, 별칭, 요청 정보의 범위

한 페이지가 API, 이미지, 인증, 정적 리소스 등 여러 호스트에 요청을 보낼 수 있습니다. 브라우저 주소 표시줄에 보이는 도메인에만 규칙을 작성해도 다른 호스트가 자동으로 같은 정책을 사용하는 것은 아닙니다. 일부 콘텐츠가 로드되지 않으면 실패한 요청의 호스트를 목록으로 정리하고 현재 접미사 범위에 포함되는지 각각 확인하세요. 같은 대상 주소를 사용한다는 이유만으로 서로 다른 도메인을 동일한 도메인 규칙 범위에 넣어서도 안 됩니다.

도메인 별칭과 해석 체인은 원래 요청의 호스트와 구분해야 합니다. DNS 결과가 다른 이름을 가리킨다고 해서 모든 매칭이 반드시 그 이름을 대상으로 바뀌는 것은 아닙니다. 어떤 정보가 보이는지는 현재 요청 기록을 기준으로 확인하세요. 주소로 직접 접속하면 클라이언트에 DOMAIN 계열 규칙을 매칭할 도메인 정보가 충분하지 않을 수 있습니다. 이때는 주소 규칙과 기본 처리 방식을 확인하세요. 웹페이지 제목이나 앱 이름만으로 요청에 사용된 호스트 이름을 추측하지 마세요.

접미사 규칙을 검증할 때는 최소한 루트 도메인, 하위 도메인 하나, 범위 밖 도메인 하나를 골라 각각 확인하세요. 앞에 둔 예외 규칙도 별도 요청으로 테스트해 로그의 정책이 실제로 다른지 확인합니다. 임시 테스트를 위해 정확한 규칙을 추가했다면 테스트 기록에 이유를 적고, 완료 후 유지할지 삭제할지 결정하세요. 예외가 늘어나면 중복 행을 합치고 만료된 호스트를 정기적으로 제거하세요. 파일 맨 위에 규칙을 계속 추가하는 것보다 유지·복구가 쉽습니다.

주소 규칙과 USER-AGENT 조건

IP-CIDR과 주소 범위

IP-CIDR은 IPv4 주소 범위를 서브넷으로 표현합니다. 슬래시 뒤의 숫자는 프리픽스 길이이며 포트 번호나 매칭할 주소 개수가 아닙니다. 프리픽스가 길수록 범위가 좁아집니다. 규칙을 확인하기 전에 앞부분 몇 글자만 비교하지 말고 대상 주소가 어느 네트워크에 속하는지 확인하세요. 여러 범위가 겹쳐도 정책은 규칙 위치에 따라 선택됩니다. 따라서 더 좁은 범위의 예외는 이를 포함하는 넓은 범위보다 앞에 두어야 합니다.

[Rule]
IP-CIDR,192.168.1.10/32,REJECT,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

예제의 첫 번째 행은 IPv4 주소 하나만 매칭하고, 뒤의 두 행은 일반적인 사설 주소 범위를 각각 매칭합니다. 첫 번째 행이 더 넓은 범위보다 앞에 있으므로 해당 주소는 먼저 거부됩니다. 뒤에 배치하면 이미 있는 DIRECT 규칙에 매칭됩니다. 사설 주소 규칙이 있다고 해서 서로 다른 네트워크의 같은 주소가 동일한 기기를 가리키는 것은 아닙니다. 네트워크를 바꾸면 다른 호스트를 가리킬 수 있습니다. 이 범위를 사용할 때는 현재 LAN과 사용자의 연결 환경을 함께 고려하세요.

IP-CIDR6은 IPv6 주소 범위에 사용하며 IPv4 문법으로 대체할 수 없습니다. 예제의 범위는 IPv4 사설 주소와 일대일 대응하지 않으며, 주소 계열마다 별도로 표현해야 한다는 점을 보여 줍니다. 서비스 하나가 두 종류의 주소를 모두 사용할 수 있으며, 어떤 규칙에 매칭되는지는 실제 대상에 따라 달라집니다. 문제를 확인할 때는 전체 주소를 기록하세요. 화면에 도메인이 표시되어도 최종적으로 어떤 주소 계열을 사용하는지 놓치지 마세요.

GEOIP는 도메인 분류가 아닙니다

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

GEOIP는 주소의 지역 데이터베이스 정보를 바탕으로 매칭합니다. 도메인 접미사, 페이지 언어, 웹사이트 이름으로 대신 판단할 수 없습니다. 한 도메인이 서로 다른 배포 주소를 사용하면 실제 주소에 따라 매칭 결과가 달라질 수 있습니다. GEOIP는 주소 분류 조건을 표현하는 데 적합하지만, 하나의 서비스 전체가 항상 같은 정책을 사용하도록 보장하지는 않습니다. 특정 도메인에 대한 처리 요구가 명확하다면 지역 규칙보다 앞에 도메인 규칙을 두고 예외를 구체적인 조건으로 표현하세요.

주소 데이터베이스와 서비스의 실제 배포 위치 사이에는 차이가 있을 수 있으며, 지역 매칭 결과가 서비스 운영 주체의 소재지를 뜻하지도 않습니다. 예상과 다른 요청이 있으면 대상 주소와 로그 기록을 먼저 확인한 뒤 정확한 도메인 규칙을 추가할지 결정하세요. 한 도메인의 문제를 고치려고 모든 지역 트래픽의 정책을 바꾸면 영향 범위가 커지는 경우가 많습니다. 주소를 얻기 위해 해석이 필요한 요청은 앞 장의 DNS 및 no-resolve 범위도 함께 살펴보세요.

USER-AGENT 적용 조건

[Rule]
USER-AGENT,ExampleClient*,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

USER-AGENT는 확인 가능한 요청 헤더 정보를 바탕으로 매칭합니다. 여기서 ExampleClient*는 와일드카드 표기를 설명하기 위한 예시 패턴이며 실제 앱 식별자가 아닙니다. 앱 이름이나 기기 프로세스를 기준으로 매칭하는 기능이 아닙니다. 관련 요청 정보를 확인할 수 있어야 이 조건을 판단할 수 있습니다. 모든 앱 연결에 같은 요청 헤더가 포함된다고 가정하거나 특정 앱의 모든 트래픽을 안정적으로 분류하는 수단으로 사용하지 마세요.

암호화된 요청의 내부 헤더 필드는 당연히 보이는 정보가 아닙니다. USER-AGENT 규칙을 매칭시키려고 인증서를 임의로 추가하거나 HTTPS 처리 설정을 바꾸지 마세요. 이는 명확한 권한과 목적이 필요한 별도의 신뢰 및 접근 범위와 관련됩니다. 일반적인 도메인 분기에는 우선 DOMAIN 계열을 사용하세요. 특정 테스트에서 요청 헤더를 확인했더라도 백그라운드 연결, 다른 API, 이후 요청에도 같은 조건이 적용된다고 단정할 수 없습니다.

규칙을 조합할 때는 구체적인 호스트 예외를 먼저 배치한 다음 필요한 주소 범위와 지역 조건을 추가하세요. 요청 헤더 조건을 사용한다면 정보가 보이는지와 매칭 범위를 별도로 확인합니다. 미매칭 원인을 살필 때는 세 가지 경우를 구분하세요. 필드가 없음, 필드는 있지만 값이 다름, 앞선 규칙이 이미 매칭됨입니다. 각 경우의 해결 방법은 다르며 와일드카드만 조정해서 모두 해결할 수는 없습니다. 유지 관리 메모에 각 규칙이 필요로 하는 정보를 적어 두면 나중에 반복해서 추측할 일이 줄어듭니다.

정책, Global Routing, 매칭 순서

모드를 먼저 확인하고 정책을 살펴보세요

Global Routing은 현재 사용할 전체 처리 모드를 결정합니다. Config는 설정에 따른 분기, Proxy는 프록시 모드, Direct는 직접 연결 모드입니다. 구체적인 동작은 앱의 현재 설정과 요청 유형을 함께 확인해야 합니다. Config가 사용 중인지 확인해야 Rule 텍스트의 개별 매칭으로 이 장의 예제를 설명할 수 있습니다. 모드를 바꿔 문제를 좁혀 볼 수는 있지만 규칙을 수정하는 대신 사용할 수 있는 해결책은 아닙니다. 테스트가 끝나면 원래의 모드를 명확히 선택해 복원하세요.

화면의 Proxy와 규칙의 PROXY는 서로 다른 계층에 있으므로 이름이 비슷하다고 완전히 같은 의미로 보면 안 됩니다. 전자는 전체 모드 선택이고 후자는 규칙이 매칭된 뒤 적용되는 정책입니다. DIRECT는 선택된 프록시를 거치지 않고 대상에 연결하지만, 대상 주소와 로컬 네트워크가 연결 가능한 상태여야 합니다. REJECT는 요청을 명시적으로 거부하는 정책입니다. 연결 실패 후 자동으로 시도하는 대체 정책이 아닙니다. 거부된 요청은 실패했다고 해서 다음 허용 규칙을 계속 찾지 않습니다.

매칭되면 중단, 예외는 앞에

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

이 예제는 위에서 아래로 확인합니다. API 호스트에는 먼저 PROXY를 사용하고, 지정 호스트는 먼저 REJECT하며, 나머지 도메인 트리는 DIRECT로 처리합니다. 앞의 도메인 조건이 결과를 결정하지 않은 경우에만 뒤의 주소 조건이 정책을 결정할 기회가 있습니다. 규칙 유형에 자동 정렬이나 '더 구체적이면 항상 우선'이라는 숨은 우선순위는 없습니다. 텍스트 위치가 중요한 우선순위 표현입니다. 예외를 추가할 때는 바로 위 행만 보지 말고 더 앞에서 매칭될 수 있는 모든 규칙을 확인하세요.

흔히 말하는 '도메인 우선, 주소 기본 처리'는 관리자가 정한 순서이지 모든 설정이 자동으로 따르는 동작이 아닙니다. 주소 규칙을 앞에 두면 원래 도메인에 따라 처리하려던 요청이 먼저 결정될 수 있고, 해석 필요 여부에도 영향을 줄 수 있습니다. 실제 결과는 이용 가능한 요청 정보와 구체적인 조건에 따라 달라집니다. 낯선 파일을 살펴볼 때는 그룹 주석으로 우선순위를 추측하지 말고 실제 순서대로 확인하세요. 주석에 예외라고 적혀 있어도 넓은 규칙 뒤에 배치되어 있다면 작동하지 않습니다.

FINAL의 위치와 의미

FINAL은 추가 매칭 값이 없는 기본 처리 규칙입니다. 일반적인 표기는 FINAL,PROXY 또는 FINAL,DIRECT입니다. 앞의 명확한 조건이 먼저 선택되도록 규칙 목록 맨 끝에 둬야 합니다. FINAL을 중간에 두면 뒤의 규칙은 예상한 대로 매칭될 기회를 잃습니다. FINAL을 여러 개 추가해도 순서대로 시도하는 대체 연결 목록이 만들어지지 않습니다. 기본 정책을 정하기 전에 나열하지 않은 요청을 어떻게 처리할지 먼저 결정하세요.

PROXY에 매칭된 뒤 연결에 실패해도 클라이언트가 자동으로 DIRECT로 되돌아가거나 다음 Rule을 계속 매칭하지는 않습니다. 규칙은 정책을 정하고 연결 결과는 그다음 단계입니다. 별도로 명시적으로 설정된 관련 기능이 있는 경우에만 이후 동작이 달라질 수 있습니다. 프록시 사용 가능 여부를 확인하려면 사용자가 보유한 연결을 별도로 테스트하고 인증 및 전송 매개변수를 점검하세요. 지나치게 넓은 직접 연결 규칙으로 프록시 장애를 감추면 로그에서 '페이지가 열림'이라는 결과가 검증의 의미를 잃습니다.

용도에 따라 유지 관리 순서 구성하기

정확한 예외, 도메인 범위, LAN 주소, 기타 주소 분류, FINAL 순으로 구성하고 각 그룹의 용도를 적어 두는 방식을 권장합니다. 순서가 고정된 템플릿은 아닙니다. 중요한 점은 각 예외가 왜 해당 위치에 있는지 설명할 수 있어야 한다는 것입니다. 중복 규칙을 발견하면 호스트가 같아 보인다는 이유만으로 삭제하지 말고 정책이 다른지, 의도적으로 덮어쓰는 설정인지 확인하세요. 넓은 범위 규칙 앞의 정확한 예외는 의미가 있을 수 있지만, 뒤에 있는 동일 범위·동일 정책의 중복 행은 보통 유지 관리 부담만 늘립니다.

Config와 Proxy의 테스트 결과를 비교할 때는 매칭된 규칙과 선택한 연결을 함께 기록하세요. Proxy에서는 연결되지만 Config에서 실패한다면 DIRECT 또는 REJECT로 분기되는 조건부터 확인합니다. 둘 다 실패한다면 연결과 네트워크를 계속 점검하세요. Direct 연결에 성공해도 프록시 매개변수가 올바르다는 증거는 아닙니다. 모드에 대한 자세한 내용은 Global Routing 세 가지 모드 노트를 참고하고, 수정할 때는 현재 앱에서 실제로 기록되는 내용을 기준으로 판단하세요.

Host 매핑과 LAN 범위

주소를 매핑하는 기능이지 정책을 선택하는 기능은 아닙니다

Host는 지정된 호스트 이름을 주소에 매핑하는 기능입니다. '이 이름에 어떤 주소가 연결되는가'를 정할 뿐 '이 요청이 어떤 연결을 사용하는가'를 정하지 않습니다. 매핑한 뒤에도 적용되는 규칙과 현재 모드를 확인해야 합니다. 특히 Host에서 호스트 이름을 LAN 주소로 지정했다고 해서 요청이 반드시 직접 연결되는 것은 아닙니다. 앞선 도메인 규칙이 여전히 PROXY를 선택할 수 있습니다. 설정을 읽을 때 Host와 Rule을 함께 살펴보되 역할은 구분하세요.

[Host]
router.example.com = 192.168.1.1
service.example.com = 192.168.1.20

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

예제는 두 호스트의 주소를 명시적으로 지정하고, 정확한 도메인 규칙으로 직접 연결 의도를 표시합니다. 사용자가 접근 권한을 가진 기기가 현재 네트워크에 실제로 있을 때만 적용할 수 있습니다. 예제 주소는 모든 네트워크에서 접근 가능한 공용 주소가 아닙니다. 현재 LAN이 다른 대역을 사용한다면 그대로 복사해도 서비스에 연결되지 않습니다. 매핑을 설정하기 전에 대상 기기의 주소와 포트, 서비스가 정상인지 확인한 뒤 도메인을 알아보기 쉬운 접속 이름으로 사용하세요.

호스트 이름, 포트, 경로를 각각 처리하기

Host의 왼쪽에는 호스트 이름, 오른쪽에는 해당 주소를 입력합니다. 페이지 경로, 프로토콜 접두사, 포트는 넣지 마세요. 매핑은 앱이 요청하는 포트를 바꾸지 않으며 일반 웹 요청을 다른 프로토콜로 바꾸지도 않습니다. 대상 서비스가 특정 포트에서만 대기한다면 접속 측에서 올바른 방식으로 사용해야 합니다. 매핑은 적용됐지만 서비스에 연결되지 않는다면 Host 값에 경로를 덧붙이지 말고 연결 대상과 서비스의 수신 상태를 확인하세요.

Host는 접미사 규칙이 아닙니다. 특정 호스트 하나를 매핑했다고 모든 하위 도메인에 같은 결과가 적용된다고 가정하지 마세요. 여러 호스트가 필요하다면 앱에서 지원하는 표기와 각각의 대상을 확인하고, 먼저 명확한 호스트 이름으로 검증 가능한 결과를 만드세요. 일반적인 트래픽 분기에는 Host가 필요하지 않습니다. 도메인을 프록시로 보내려는 목적이라면 Rule로 정책을 표현하고 정상적인 해석을 유지하세요. 주소를 임의로 고정하면 추가 유지 관리가 필요해집니다.

HTTPS 호스트 이름 검증은 그대로 적용됩니다

호스트 이름을 주소에 매핑해도 요청의 호스트 식별 정보가 바뀌지 않으며 대상 인증서가 해당 이름에 자동으로 적용되지도 않습니다. HTTPS 연결은 여전히 인증서 이름과 신뢰 체인을 확인할 수 있고, 대상 서비스는 호스트 이름에 따라 사이트를 선택할 수 있습니다. 매핑 후 인증서 오류가 발생한다면 서비스가 해당 이름을 실제로 지원하는지 확인하세요. 검증을 끄는 것을 일반적인 해결 방법으로 삼지 마세요. 주소 접근 가능 여부, 도메인 매핑, 인증서 유효성은 서로 별개의 조건입니다.

직접 관리하는 서비스라면 서버 설정에 맞춰 올바른 호스트 이름과 인증서를 구성하고 현재 네트워크에서 확인하세요. 관리하지 않는 서비스의 해석 주소를 임의로 고정하면 잘못된 서버에 접속하거나 주소 변경 후 계속 실패할 수 있습니다. 네트워크 배포 서비스는 해석 결과로 여러 주소를 반환하는 경우가 많습니다. 한 번 관찰한 주소를 장기간 고정하면 정상적인 분산 처리를 방해할 수 있습니다. 명확한 요구가 없다면 테스트용 매핑을 우선 삭제해 정상적인 해석을 복원하세요.

네트워크 변경 후 유지 관리 및 복구

LAN 매핑에서 흔히 마주치는 제약은 네트워크 변경입니다. 같은 사설 주소가 다른 네트워크에는 없거나 다른 기기를 가리킬 수 있습니다. 원래 네트워크를 벗어나도 매핑은 용도가 더 이상 맞지 않는다고 해서 공용 주소로 자동 변경되지 않습니다. 테스트에 성공하면 적용되는 네트워크와 서비스를 기록하고 다른 네트워크에서 관련 설정을 비활성화해야 하는지 검토하세요. 한 번 성공한 기록만으로 모바일 네트워크나 다른 LAN에서도 매핑이 올바르다고 볼 수는 없습니다.

문제를 해결할 때는 먼저 현재 네트워크를 확인하고 대상 주소의 서비스 연결을 직접 점검한 다음, 매핑된 도메인 요청이 예상한 주소와 정책을 사용하는지 확인하세요. 주소에 직접 접근할 수 없다면 네트워크나 대상 서비스를 먼저 확인합니다. 주소에는 접근할 수 있지만 도메인 요청이 실패한다면 이름, 인증서, 앱 요청 방식을 살펴보세요. 둘 다 정상이지만 정책이 잘못됐다면 앞선 Rule을 확인합니다. 단계별로 검증하면 Host 주소를 반복해서 바꾸면서 실제 원인인 규칙을 놓치는 일을 줄일 수 있습니다.

매핑을 삭제하거나 수정한 뒤에는 요청을 새로 보내고 기존 연결 및 해석 캐시에 이전 결과가 남아 있을 수 있다는 점에 유의하세요. 복사본을 관리할 때 주석에 각 매핑의 용도와 되돌리는 방법을 적되 기기 인증 정보는 기록하지 마세요. 진단용 임시 매핑은 테스트가 끝나면 상시 설정에서 제거하세요. 장기간 유지한다면 대상 주소가 바뀌지 않았는지 정기적으로 확인합니다. 설정의 용도를 명확히 제한해 두면 나중에 검토할 때 여전히 필요한 내용인지 판단하기 쉽습니다.

URL Rewrite 문법과 적용 범위

URL을 재작성하는 기능이지 도메인 분기가 아닙니다

URL Rewrite는 정규식으로 요청 주소를 찾은 다음 설정된 방식으로 주소를 변경합니다. Rule과 목적이 다릅니다. Rule은 처리 정책을 선택하고 재작성은 조건에 맞는 주소의 동작을 바꿉니다. 특정 호스트를 DIRECT 또는 PROXY로 보내기만 하면 된다면 재작성 섹션을 추가하지 마세요. 한 접속 주소를 다른 주소로 보내야 할 명확한 이유가 있고 앱이 해당 요청을 어떻게 처리하는지 이해한 경우에만 규칙을 만드세요.

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

이 예제는 지정된 호스트의 HTTP 주소를 매칭해 캡처한 내용으로 HTTPS 대상을 구성합니다. 마지막의 302는 리디렉션 상태 코드입니다. 매칭 조건, 대상, 상태 코드는 Rule의 쉼표 형식이 아니라 공백으로 구분합니다. 구조를 설명하기 위한 예제이며 해당 도메인이 실제로 관련 서비스를 제공한다는 뜻도, 임의의 웹사이트에 적용할 범용 재작성 규칙이라는 뜻도 아닙니다. 실제 설정은 사용자가 명확한 권한을 갖고 검증할 수 있는 대상에 맞춰야 합니다.

앵커, 이스케이프, 캡처 그룹

정규식 앞의 ^는 주소의 시작부터 매칭하고 끝의 $는 끝까지 매칭하도록 제한합니다. 도메인의 점은 임의의 문자로 해석되지 않도록 백슬래시로 이스케이프합니다. 괄호는 캡처 그룹을 만들고 대상의 $1은 첫 번째 그룹의 내용을 참조합니다. 규칙을 확인할 때 표현식 전체를 고정 문자열처럼 복사하지 말고 기호의 역할을 하나씩 설명해 보세요. 이스케이프나 앵커가 하나만 빠져도 원래 의도한 범위보다 넓게 매칭될 수 있습니다.

[URL Rewrite]
^http://example\.com/old/(.*)$ https://example.com/new/$1 302

두 번째 예제는 지정 호스트에서 /old/로 시작하는 경로만 처리합니다. 다른 경로는 조건에 포함되지 않습니다. 캡처한 부분은 대상 주소를 구성하는 데 쓰이므로 실제 입력에 어떤 내용이 들어오는지 확인해야 합니다. 쿼리 매개변수, 인코딩 문자, 마지막 슬래시가 매칭 결과에 영향을 줄 수 있습니다. 짧은 주소 하나만으로 모든 요청이 올바르게 처리된다고 판단하지 마세요. 대상 주소에 슬래시가 추가되거나 매개변수가 사라지거나 잘못된 주소가 만들어지면 프록시 정책을 바꾸지 말고 표현식을 수정하세요.

리디렉션은 새로운 요청을 발생시킵니다

리디렉션 응답을 받으면 보통 클라이언트가 대상 주소로 다시 요청해야 합니다. 새 요청은 다른 호스트, 프로토콜, 경로를 사용할 수 있으므로 이후 정책과 서비스 동작도 다시 고려해야 합니다. 원래 요청이 DIRECT로 처리됐다고 새 대상도 DIRECT를 사용한다는 보장은 없습니다. 대상 호스트가 달라지면 두 요청의 규칙 매칭을 각각 확인하세요. 디버깅 로그에 여러 요청이 보여도 반드시 오류는 아닙니다. 예상한 대로 제한적이고 명확한 이동 과정이 만들어졌는지 확인하는 것이 중요합니다.

대상을 다시 같은 조건에 매칭되는 주소로 지정하면 리디렉션이 반복될 수 있으므로 피해야 합니다. 원래 주소, 재작성 대상, 대상 주소가 조건에 다시 매칭되는지를 최소한 기록하세요. 범위가 넓은 정규식이 앞에 있으면 뒤의 정확한 조건보다 먼저 처리될 수도 있습니다. 범위가 좁은 예외를 먼저 두고 검증된 일반 규칙을 뒤에 배치하세요. 정규식이 점점 복잡해진다면 중첩을 계속 추가하는 것보다 설명 가능한 조건 몇 개로 나누는 편이 문제를 찾기 쉽습니다.

HTTPS 정보 확인 및 접근 범위

일반적인 연결 전달만으로는 암호화된 요청의 전체 경로와 헤더 필드를 직접 읽을 수 없습니다. 따라서 HTTPS 경로를 대상으로 한 재작성 규칙이 당연히 매칭될 것으로 가정하면 안 됩니다. HTTPS 내용을 처리하려면 앱 관련 설정, 인증서 신뢰, 대상 범위를 별도로 이해해야 합니다. 이 페이지의 간단한 예제에는 해당 기능을 켤 필요가 없습니다. 일반 연결 문제를 해결하려고 콘텐츠 처리 설정을 추가하면 문제 범위가 규칙 분기에서 신뢰와 호환성으로 확대되므로 이렇게 섞어 문제를 해결하지 마세요.

대상 서비스를 관리할 권한이 있더라도 명확히 필요한 호스트와 경로만 처리하고 원래 설정을 복구 기준으로 보관하세요. 재작성은 인증 리디렉션, 여러 호스트에 걸친 요청, 폼 제출, 서버의 주소 검증에 영향을 줄 수 있습니다. 먼저 일반적인 읽기 요청으로 주소가 바뀌는지 확인한 다음 실제 서비스 흐름을 점검하세요. 페이지가 한 번 열렸다는 사실만으로 전체 검증을 대신하지 마세요. 민감한 매개변수가 포함된 주소는 테스트 기록에 필요한 부분만 비식별 처리해 남기고 전체 접근 데이터를 내보내지 마세요.

유지 관리 시 각 재작성 규칙의 목적, 매칭 범위, 취소 방법을 기록하세요. 작동하지 않으면 해당 행을 비활성화하고 원래 주소에 접근할 수 있는지 확인한 뒤 서비스가 바뀐 것인지 표현식 문제인지 판단합니다. Rule과 재작성을 동시에 변경하면 결과가 달라진 원인을 파악하기 어려우므로 두 차례로 나눠 테스트하세요. 호스트 분기만 필요한 경우 도메인 규칙으로 돌아가면 됩니다. 재작성 요구가 없는 설정에는 이 섹션을 아예 포함하지 않아도 됩니다. 구조를 완성하려고 빈 동작을 추가할 필요는 없습니다.

설정 검증, 장애 단계별 확인, 복구

원인을 설명할 수 있는 테스트 설정 만들기

필드를 계속 추가해 복잡해진 파일이 아니라 정상 작동을 확인한 상태에서 검증을 시작하세요. 먼저 사용자가 보유한 서버가 기본 연결을 완료할 수 있는지 확인하고, 복사본에는 필요한 일반 설정, 명확한 규칙 몇 개, FINAL 하나만 남깁니다. 이번 테스트와 관계없는 Host 및 재작성 규칙은 잠시 제외하세요. 잘못됐다고 단정하는 것이 아니라 변수를 줄이기 위한 조치입니다. 기준 상태가 안정되면 규칙을 그룹별로 복원하고 매번 같은 요청으로 확인합니다.

[General]
dns-server = system

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

이 예제는 정확한 프록시 예외, 명시적 거부, 접미사 직접 연결, 기본 프록시 처리의 네 가지 결과를 확인할 수 있습니다. 문법 예제에 불과하므로 실제 검증에는 사용자가 접근 권한을 갖고 상태를 알고 있는 대상을 사용하세요. 예제 도메인에 웹페이지가 제공되는지를 클라이언트 정상 여부의 판단 기준으로 삼지 마세요. 각 테스트 대상은 한 가지 검증 목적만 담당하도록 하고, 알 수 없는 인터페이스 여러 개에 동시에 의존하지 않는 편이 좋습니다. 그래야 차이가 발생했을 때 설정 파일 전체가 아니라 구체적인 조건을 확인할 수 있습니다.

저장했다고 다시 테스트한 것은 아닙니다

저장한 뒤 현재 Config, Global Routing, 연결을 다시 확인하고 기존 테스트 요청을 종료한 다음 새 요청을 보내세요. 기존 장기 연결은 이전 경로를 계속 사용할 수 있고 앱 캐시가 예전 내용을 표시할 수도 있습니다. 페이지가 바뀌지 않았다고 새 규칙이 작동하지 않는다고 바로 판단할 수는 없습니다. 앱 내 연결 정보나 로그를 볼 때 요청 호스트, 대상 주소, 매칭 조건, 실제 결과를 확인해 수정 후 생성된 기록을 보고 있는지 점검하세요.

문법, 매칭, 연결 장애를 구분하세요

문법 문제는 설정을 정상적으로 불러오지 못하거나 특정 행을 건너뛰고 설정을 예상대로 인식하지 못하는 식으로 나타날 수 있습니다. 영문 구두점, 섹션 위치, 추가 필드, 실제 줄바꿈을 확인한 다음 최근 추가한 내용을 복사본에서 제외해 비교하세요. 매칭 문제는 요청에 예상과 다른 정책이 적용되는 형태로 나타납니다. 목록의 맨 위에서 조건을 처음 만족하는 규칙을 찾으세요. 요청에 도메인이나 주소 정보가 없는 경우 '조건에 필요한 정보 부족'도 별도의 원인으로 고려하고 필드 오타만 의심하지 마세요.

정책은 맞지만 연결에 실패한다면 서버, 해석, 대상 서비스, 로컬 네트워크를 확인하세요. Connectivity Test는 연결 상태를 살펴보는 데 도움이 되지만 한 번의 테스트가 모든 프로토콜과 서비스 요청을 검증하지는 않습니다. 사용자가 보유한 서버 매개변수를 자신의 서비스 정보와 대조해 주소, 포트, 인증, 전송 관련 설정을 하나씩 확인하세요. 지연 시간 테스트에 결과가 있다고 모든 대상에 접근할 수 있는 것은 아닙니다. 대상 하나의 실패를 이유로 전체 분기의 기본값을 바꾸지도 마세요.

거부로 인한 실패는 별도로 확인해야 합니다. REJECT에 매칭되어 대상에 접근할 수 없는 것은 해당 정책의 직접적인 결과이지 프록시 연결 품질 문제가 아닙니다. 거부가 차단하면 안 되는 서비스에 영향을 준다면 매칭 범위를 좁히거나 앞에 예외 규칙을 추가하고 페이지 의존 관계를 다시 테스트하세요. 특히 도메인 키워드 규칙의 오매칭을 확인해야 합니다. 수정할 때는 넓은 도메인 트리 전체를 허용하는 규칙으로 거부 조건을 상쇄하지 말고 정확한 호스트 조건으로 바꾸는 것이 우선입니다.

복구 및 변경 기록

수정할 때마다 세 가지를 기록하세요. 원래 어떤 현상이 나타났는지, 어느 행을 바꿨는지, 어떤 요청으로 결과를 확인했는지입니다. 나중에 재현할 수 있는 정도면 충분하며 실제 구독 주소, 인증 정보, 전체 접근 로그를 저장할 필요는 없습니다. 설정을 내보내기 전에 사용자의 민감한 정보가 포함됐는지 확인하세요. 다른 사람에게 문제 해결용 일부 설정을 보여 줄 때는 관련 섹션과 비식별 처리된 요청 조건만 제공하세요. 설정 예제의 명시적인 예시 값과 실제 인증 정보는 항상 분리해 관리해야 합니다.

원격 설정이나 구독을 업데이트한 뒤에는 어떤 항목이 바뀌었는지 먼저 확인하고 기존 테스트 목록을 다시 사용하세요. 서버 데이터 변경은 PROXY 연결에, 규칙 변경은 매칭에 영향을 줄 수 있습니다. 두 종류의 업데이트를 한 번의 테스트 결과로 묶어 판단하지 마세요. 업데이트 후 작동하지 않는다면 검증된 로컬 복사본으로 돌아가고 선택 상태도 실제로 복원됐는지 확인합니다. 이전 파일이 목록에 남아 있는 것만으로 복구된 것은 아닙니다. 복원한 뒤 차이를 하나씩 확인하고 문제가 있는 파일에 임시 패치를 계속 쌓지 마세요.

이 페이지는 설정 동작을 설명합니다. 처음 가져오기, 연결 시작, 기본 검증은 빠른 시작 가이드를 확인하세요. 필드 이름을 간단히 확인하려면 용어 빠른 참조를 참고하세요. 구매, 기존 계정 복원, App Store 호환성은 설정을 수정해 처리하지 말고 구매 항목 복원 안내를 사용하세요. 문제를 해당 계층에서 확인하고 최소한으로 수정해 검증하는 것이 오래 유지할 수 있는 설정의 기본입니다.