Shadowrocket
설정 및 규칙 가이드

설정 파일 구조와 적용 범위

서버 정보와 설정 파일 구분하기

서버 정보에는 원격 연결에 필요한 주소, 포트, 프로토콜 및 인증 항목이 들어갑니다. 설정 파일은 요청을 처리하는 방법, 사용할 규칙, 도메인 확인 방식을 정합니다. 구독을 Home에 가져왔다고 해서 Config의 규칙 파일이 교체되는 것은 아닙니다. 반대로 Rule이 포함된 파일을 가져와도 사용자 본인의 서버 인증 정보가 자동으로 추가되지는 않습니다. 문제를 해결할 때는 먼저 이 두 항목을 구분해 잘못된 곳을 반복해서 수정하지 않도록 하세요.

Config에서 현재 선택된 설정을 확인한 다음 편집 내용을 열어 보세요. 가져오기, 저장, 선택은 서로 다른 작업입니다. 목록에 파일이 표시되면 파일이 존재한다는 뜻이고, 편집기에서 새 내용이 보이면 해당 파일을 열어 보고 있다는 뜻입니다. 실제 연결에 적용되는지는 현재 선택 상태를 확인해야 합니다. 수정 전에 파일 이름과 선택 상태를 기록하고, 저장 후 다시 확인하세요. 필요하다면 연결을 껐다가 켜 새 설정으로 테스트하세요.

네 섹션의 역할

섹션 제목은 대괄호로 표시하며, 해당 제목 아래에 항목과 규칙을 작성합니다. General은 일반 설정, Rule은 요청 매칭과 정책, Host는 정적 도메인 주소 매핑, URL Rewrite는 조건에 맞는 URL 변경을 담당합니다. 각 섹션은 서로 대체할 수 없습니다. 도메인 매핑을 Rule에 작성해도 Host가 되지 않고, 리디렉션 표현식을 General에 작성해도 실행 가능한 분기 규칙이 되지 않습니다. 섹션 이름과 규칙 키워드는 영어 원문 그대로 사용합니다.

[General]
bypass-system = true
skip-proxy = 192.168.0.0/16, 10.0.0.0/8, localhost
dns-server = system

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

[Host]
localhost = 127.0.0.1

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

이 예시는 일치하지 않는 요청을 DIRECT로 보내고 예시 도메인에만 PROXY를 적용하므로 범용 프록시 설정이 아닙니다. 복사하기 전에 마지막 정책의 의미를 이해해야 합니다. General의 우회 범위도 이후 처리 경로에 영향을 줍니다. 요청이 앞선 단계에서 이미 프록시를 우회했다면 Rule 한 줄을 옮기는 것만으로 다시 규칙 매칭 과정에 들어오게 할 수 없습니다.

편집·저장·백업 기본 순서

먼저 사용할 수 있는 파일을 보관한 다음, 실험용 복사본을 만드세요. 한 번에 섹션 하나 또는 규칙 하나만 수정하고 저장한 뒤 다시 선택해 테스트합니다. 파일이 원격 주소에서 제공된다면 다음 업데이트 때 로컬 변경 내용이 덮어써지는지도 확인하세요. 오래 유지할 수정 사항은 한 번의 업데이트 후 남아 있는 차이에 의존하지 말고 독립적으로 관리할 수 있는 로컬 복사본에 보관해야 합니다. 백업 이름은 용도를 알아볼 수 있게 정하되 계정 정보, 서버 주소, 인증 정보는 넣지 마세요.

규칙 매개변수는 쉼표로 구분하고, 일반 항목이나 Host의 키와 값은 등호로 구분합니다. 한글 문장 부호, 설명 문구, 웹페이지에서 복사할 때 들어가는 특수 공백은 설정에 넣지 마세요. 여러 줄 예시의 줄바꿈은 실제 줄바꿈입니다. 편집기에 한 줄이 길게 표시되면 가로로 확인하고 규칙을 임의로 여러 줄로 나누지 마세요. 주석은 #으로 시작하는 별도 줄에 작성해 정책 매개변수 뒤에 메모가 붙지 않도록 합니다.

파일을 저장할 수 있다고 해서 의미까지 모두 올바른 것은 아닙니다. 문법은 맞지만 범위가 지나치게 넓은 DOMAIN-KEYWORD는 정상 실행되면서 관련 없는 요청까지 매칭할 수 있습니다. 유효한 FINAL도 너무 앞에 두면 뒤의 규칙을 가릴 수 있습니다. 확인할 때는 문법, 선택 상태, 실제 요청 결과를 모두 살펴보세요. 편집기에 오류가 표시되는지만 확인해서는 안 됩니다.

General 항목 및 DNS 처리

일반 항목은 규칙 앞에 붙는 내용에 그치지 않습니다

General은 일부 요청이 처리 과정에 들어가는 방식과 도메인을 확인할 때 사용하는 출처를 결정합니다. Rule을 살펴보기 전에 이 항목을 이해해야 합니다. 연결이 프록시 처리에 들어가는지, 주소를 이미 얻었는지, 매칭에 필요한 도메인 정보가 남아 있는지에 따라 이후 결과가 달라질 수 있습니다. General을 고정된 템플릿처럼 사용하지 마세요. 특정 LAN에 적합한 우회 범위가 다른 네트워크에서는 필요하지 않을 수 있습니다.

bypass-system = true는 관련 시스템 트래픽이 프록시 처리를 우회하도록 합니다. 모든 요청을 직접 연결하는 스위치가 아니며 Global Routing의 Direct와도 같지 않습니다. 이 설정을 유지한다면 관련 시스템 요청이 일반 규칙 경로를 거치지 않을 수 있다는 점을 고려하세요. 특정 시스템 기능에 문제가 생겼다면 해당 요청과 네트워크 환경을 함께 확인해야 합니다. 웹페이지 테스트 한 번으로 모든 시스템 트래픽의 동작을 추론할 수는 없습니다.

skip-proxy는 프록시 처리를 건너뛸 대상 범위를 지정하며, 주로 LAN 주소와 로컬 기기 이름에 사용됩니다. 여기서의 우회와 Rule에서 DIRECT를 선택하는 것은 처리 단계가 다릅니다. DIRECT는 요청이 규칙 처리에 들어간 뒤 선택하는 정책입니다. 반면 우회 설정은 요청이 일반적인 프록시 규칙 경로를 따르지 않게 할 수 있습니다. 로그에 예상한 Rule 매칭이 보이지 않는다면 같은 규칙을 파일 맨 위에 복사하기 전에 우회 목록을 확인하세요.

[General]
bypass-system = true
skip-proxy = 192.168.0.0/16, 10.0.0.0/8, localhost
dns-server = system

system의 의미와 테스트 기준

dns-server = system은 시스템이 제공하는 DNS를 사용한다는 뜻이며, 특정 DNS 서버를 고정해서 사용한다는 의미는 아닙니다. 다른 Wi-Fi나 모바일 네트워크로 전환하면 시스템에서 받은 DNS 설정도 바뀔 수 있습니다. LAN 내부 이름은 현재 네트워크의 DNS 서버만 확인할 수 있는 경우도 있습니다. 우선 system을 기준으로 기존 네트워크에서 대상 도메인을 확인할 수 있는지 살펴본 다음, 필요한 경우 사용자 환경에 맞는 다른 DNS 출처를 지정하세요.

DNS는 이름을 주소로 확인하고, 규칙은 요청에 적용할 정책을 결정합니다. 두 기능은 서로 관련이 있지만 같지는 않습니다. DOMAIN 규칙은 알고 있는 도메인 이름으로 매칭할 수 있으며, GEOIP나 IP-CIDR은 주소를 대상으로 하므로 DNS 조회 결과가 필요할 수 있습니다. 로그에 조회 실패가 표시되면 필요한 주소를 아직 얻지 못했다는 뜻입니다. 이를 곧바로 PROXY 서버를 사용할 수 없는 상황으로 해석하거나, FINAL을 추가해 해결하려 해서는 안 됩니다.

앱 요청과 DNS 요청을 구분하는 것도 중요합니다. 대상 웹페이지가 PROXY를 사용하더라도 모든 DNS 조회가 같은 경로를 따른다는 뜻은 아닙니다. 실제 DNS 동작은 앱, 시스템 캐시, 설정 옵션에 따라서도 달라집니다. 정확히 확인하려면 규칙의 정책 이름만 보고 조회 경로를 추측하지 말고 실제 로그와 현재 설정을 확인하세요. 서버가 도메인 이름으로 지정되어 있다면 서버 자체의 이름도 먼저 확인할 수 있어야 합니다. 연결 진입점에서 발생한 문제를 대상 사이트 분기 문제로 오해하지 않도록 하세요.

DNS 변경 전후의 범위 확인

외부 도메인은 확인되지만 내부 도메인은 확인되지 않는다면 먼저 내부 DNS를 제공하는 네트워크에서 벗어났는지 확인하세요. 모든 이름 조회가 실패하지만 이미 알고 있는 주소에는 직접 연결할 수 있다면 DNS 출처를 집중적으로 살펴보세요. DNS, 서버, Rule을 한꺼번에 수정하면 연결이 복구되더라도 어떤 변경이 효과가 있었는지 알 수 없습니다. 변경할 때마다 같은 네트워크와 대상에 새 연결로 다시 테스트하고 결과를 기록하세요.

DNS 캐시 때문에 변경 효과가 늦게 나타날 수 있습니다. 시스템, 클라이언트, 앱이 이전 결과를 보관할 수 있고 브라우저가 기존 연결을 재사용할 수도 있습니다. 설정을 저장한 뒤 페이지만 새로고침해도 새로운 DNS 조회가 발생하지 않을 수 있습니다. 기존 연결을 끊고 다시 연결한 다음 대상 앱을 다시 여세요. 그래도 문제가 있고 필요한 이유가 분명할 때만 시스템 네트워크 상태를 추가로 확인합니다. 캐시에서 가져온 한 번의 결과를 새 설정이 검증된 증거로 여기지 마세요.

IPv4와 IPv6도 각각 확인해야 합니다. 도메인에서 두 종류의 주소가 모두 반환되더라도 한 네트워크에서 한쪽 주소로의 연결이 원활하지 않아 조회는 성공했지만 연결은 시간 초과될 수 있습니다. 이때는 DNS 출처를 무조건 바꾸기보다 실제 사용된 주소와 매칭된 규칙을 확인하세요. 출처를 알 수 없는 항목을 여러 개 쌓기보다 작동하는 기준 설정을 유지하고 이름, 주소, 정책, 연결 결과를 서로 대응해 살펴보세요.

DOMAIN 계열 규칙의 적용 범위

정확한 도메인과 도메인 접미사

DOMAIN은 지정한 도메인 이름을 매칭하며, 명확한 호스트 이름 하나만 처리할 때 적합합니다. 예를 들어 api.example.com만 PROXY를 사용하게 하고 같은 사이트의 다른 이름에는 영향을 주지 않으려면 정확한 규칙을 우선 고려하세요. 매개변수에는 도메인만 작성하고 프로토콜, 경로, 포트, 쿼리 문자열은 넣지 않습니다. 전체 웹 주소를 DOMAIN에 넣으면 더 구체적으로 보일 수 있지만, 실제로는 이 규칙이 매칭하려는 대상이 아닙니다.

DOMAIN-SUFFIX는 도메인 계층의 접미사로 매칭합니다. example.com은 해당 이름 자체와 www.example.com, api.example.com 같은 하위 도메인을 포함할 수 있습니다. 임의의 문자열 끝부분을 경계 없이 찾는 방식은 아닙니다. 도메인 사이의 점으로 나뉜 계층이 중요합니다. 접미사를 작성할 때는 보통 도메인만 입력하면 되므로 별표를 직접 붙이지 말고 매개변수 끝에 웹페이지 경로도 추가하지 마세요.

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

이 순서에서는 api의 정확한 규칙이 먼저 매칭되고, 이후 나머지 example.com 요청에 접미사 규칙이 적용됩니다. DOMAIN-SUFFIX를 앞에 두면 api 요청도 더 넓은 규칙에 먼저 매칭됩니다. 뒤에 있는 DOMAIN이 더 정확하다는 이유로 우선 적용되지는 않습니다. 구체성은 규칙을 배치할 때 고려할 기준이지 규칙 엔진이 자동으로 순서를 바꾸는 기준이 아닙니다.

키워드 규칙을 신중하게 사용해야 하는 이유

DOMAIN-KEYWORD는 도메인에 특정 키워드가 포함되어 있는지 매칭하며, 문자열 범위가 필요한 경우에 사용합니다. 사이트의 소유 관계를 파악하거나 단어가 특정 서비스를 가리키는지 이해하는 규칙은 아닙니다. example이라는 키워드는 서로 다른 계층과 접미사의 이름에 포함될 수 있어 보통 DOMAIN-SUFFIX보다 넓은 범위를 대상으로 합니다. 명확한 도메인이나 접미사로 표현할 수 있다면 범위를 검토하기 쉬운 좁은 규칙을 우선 사용하세요.

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

여기서 키워드 규칙은 적용 범위의 차이를 보여주기 위한 예시이며, 실제 파일에 세 가지 형태를 모두 넣어야 한다는 뜻은 아닙니다. 로그인 이름에는 먼저 DIRECT를 적용하고, 이후 도메인과 하위 도메인에는 PROXY를 적용하며, 키워드가 포함된 다른 이름은 세 번째 줄에서 처리합니다. 실제 설정에서는 필요성이 분명하지 않은 넓은 규칙을 삭제해 오매칭과 문제 해결 부담을 줄이세요. 규칙이 많다고 설정이 더 정확해지는 것은 아닙니다.

도메인 규칙 매칭에 필요한 정보

도메인 규칙이 이름을 기준으로 동작하려면 요청 처리 시 사용할 수 있는 도메인 정보가 있어야 합니다. 앱이 IP 주소에 직접 연결하거나 관련 단계에서 원래 도메인과 연결되지 않으면 규칙 엔진은 주소 규칙만 확인할 수 있습니다. 브라우저 주소창에 도메인을 입력했다고 해서 이후 모든 연결에 같은 이름이 남아 있다고 단정할 수는 없습니다. 페이지는 이미지, API, 글꼴 또는 다른 리소스 도메인을 불러올 수도 있습니다.

홈페이지는 열리지만 일부 리소스가 실패한다면 홈 도메인에 같은 규칙을 반복해서 추가하지 말고 로그에서 실제로 실패한 요청의 도메인을 찾으세요. 하나의 서비스 페이지도 여러 도메인에 의존할 수 있습니다. 각 도메인에 같은 정책을 적용할지는 실제 요청을 확인해 판단해야 합니다. 편의를 위해 짧은 키워드를 비슷한 이름 전체로 확대하거나, 한 번 접속에 성공했다고 모든 의존 리소스가 처리된 것으로 추정하지 마세요.

테스트에는 매칭되어야 하는 이름 하나와 매칭되면 안 되는 이름 하나를 준비해 각각 정책을 확인하세요. 첫 번째는 규칙 적용 여부를, 두 번째는 범위가 지나치게 넓지 않은지를 확인합니다. DOMAIN-SUFFIX를 사용한다면 루트 도메인과 하위 도메인을 모두 확인하세요. DOMAIN을 사용한다면 인접한 하위 도메인이 잘못 포함되지 않는지 확인합니다. 성공한 페이지 하나만 테스트하는 것보다 이렇게 양쪽을 확인해야 범위 오류를 더 잘 찾을 수 있습니다.

도메인 대소문자는 보통 문제 해결의 핵심이 아니지만 설정을 검토하기 쉽게 표기 방식을 통일하는 것이 좋습니다. 국제화 도메인, 특수 이름, 앱이 실제 사용하는 정규화 형태는 로그에 표시되는 매칭 대상을 기준으로 확인하세요. 웹페이지에 보이는 이름으로 규칙 매개변수를 추측하지 마세요. 표시 제목이나 링크 문구와 실제 연결 호스트는 전혀 다를 수 있습니다. 수정 후 테스트 근거를 남겨야 다음에 같은 문제가 생겼을 때 규칙이 바뀐 것인지 요청 대상이 바뀐 것인지 판단할 수 있습니다.

IP-CIDR, IP-CIDR6 및 GEOIP

주소 대역은 도메인 분류와 다릅니다

IP-CIDR은 IPv4 주소 범위를 대상으로 하며, 네트워크 주소와 프리픽스 길이로 범위를 지정합니다. 192.168.0.0/16은 단일 호스트가 아니라 해당 사설 주소 대역을 나타냅니다. IPv4 주소 하나만 매칭하려면 해당 주소에 /32를 사용하세요. 규칙을 작성하기 전에 실제 대상 주소와 넷마스크를 확인하세요. 라우터 주소를 네트워크 전체로 착각하거나 기기 하나를 대상으로 모든 사설 대역까지 범위를 넓히지 마세요.

IP-CIDR6은 IPv6 주소 범위에 사용하며 프리픽스 길이로 적용 범위를 정합니다. fc00::/7은 IPv6 고유 로컬 주소 범위를 포함하고, ::1/128은 루프백 주소만 나타냅니다. IPv4와 IPv6 규칙은 서로 대체되지 않습니다. 도메인에서 두 종류의 주소를 모두 받는 경우 IPv4 대역만 작성해도 IPv6 연결이 자동으로 제한되지는 않습니다. 문제를 해결할 때 로그에 표시된 실제 주소 유형을 확인하세요.

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

이 예시는 나열된 로컬 주소 범위에 DIRECT를 적용하고 나머지 요청은 PROXY로 보냅니다. 모든 특수 용도 주소를 포함하지 않으며 General의 우회 설정을 대체하지도 않습니다. ‘로컬 대역은 직접 연결’이라는 설명만 보고 모든 LAN 이름에 접속할 수 있다고 생각하지 마세요. 이름이 올바른 주소로 확인되어야 하고, 네트워크에서 해당 기기에 연결할 수 있어야 하며, 대상 서비스도 작동 중이어야 합니다.

no-resolve는 조회를 유발할지 제어합니다

no-resolve는 해당 주소 규칙을 매칭하기 위해 도메인 조회를 추가로 시작하지 않도록 합니다. DIRECT의 별칭도 아니고 설정 파일 전체에서 DNS를 끄는 옵션도 아닙니다. 현재 요청에 매칭할 수 있는 주소가 포함되어 있으면 규칙은 여전히 주소를 기준으로 판단할 수 있습니다. 필요한 주소 없이 도메인만 있는 경우 이 규칙이 직접 조회를 시작한 뒤 매칭할 것이라고 기대해서는 안 됩니다. 추가 여부는 매칭할 요청의 형태에 따라 결정하세요.

처음부터 IP로 접속하는 LAN 기기에는 no-resolve가 포함된 대역 규칙을 이해하기 쉽습니다. 내부 이름으로 접속하는 기기라면 조회 과정에서 로컬 주소를 얻을 수 있는지도 확인해야 합니다. ‘조회 줄이기’를 위해 모든 주소 규칙에 이 매개변수를 추가하면 기존에 조회 결과에 의존하던 매칭 경로가 달라질 수 있습니다. 결과가 바뀌었다면 최종 웹페이지가 열리는지만 비교하지 말고 해당 규칙을 확인할 때 요청에 주소가 이미 있었는지 살펴보세요.

GEOIP는 IP 주소 데이터베이스를 기준으로 판단합니다

GEOIP는 IP 주소의 소속을 데이터베이스와 비교합니다. GEOIP,CN,DIRECT는 흔히 볼 수 있는 문법 예시입니다. 웹페이지 언어, 도메인 접미사, 계정 지역, 사용자 위치를 기준으로 분류하지 않습니다. 중국어 페이지라도 서로 다른 소속의 주소를 사용할 수 있고, 같은 도메인도 분산 서비스에서 서로 다른 주소를 반환할 수 있습니다. 따라서 GEOIP는 넓은 주소 분류 기준으로 활용할 수 있지만, 특정 서비스가 반드시 직접 연결된다는 근거는 아닙니다.

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

도메인 예외를 GEOIP 앞에 두면 해당 이름에 명확한 정책을 먼저 적용할 수 있습니다. 이후 주소 대역과 지역 분류 규칙이 나머지 요청을 처리하고, 마지막으로 FINAL이 남은 요청을 처리합니다. 필요한 도메인 예외보다 GEOIP를 앞에 두면 주소 조건이 이미 충족된 요청이 주소 규칙에 먼저 매칭될 수 있습니다. ‘도메인 우선’은 규칙 순서로 표현해야 하며, 규칙 유형만으로 자동 보장되지 않습니다.

데이터베이스상의 주소 소속과 현재 네트워크에서의 연결 가능성은 반드시 일치하지 않습니다. GEOIP에 매칭된 뒤 연결에 실패했다면 로컬 네트워크에서 대상에 접근할 수 없거나 대상 서비스에 문제가 있을 수 있습니다. 이를 근거로 데이터베이스 문법이 잘못됐다고 단정할 수는 없습니다. 안정적인 예외가 필요하다면 확인 가능한 도메인에 더 구체적인 규칙을 작성하세요. 한 번의 테스트에 사용된 임시 조회 주소를 넓은 대역의 영구 예외로 만들지 마세요.

주소 규칙은 연결 재사용의 영향도 받기 쉽습니다. 대역 정책을 수정한 뒤에도 앱이 기존 연결을 계속 사용하면 로그에 새 매칭 기록이 나타나지 않을 수 있습니다. 새 연결을 만든 뒤 대상 IP, 규칙 유형, 최종 정책을 확인하세요. 같은 이름을 여러 번 조회했을 때 다른 주소가 반환된다면 그 차이를 기록하고 주소 풀 변경인지 규칙 범위 누락인지 판단하세요. FINAL을 계속 옮기는 것으로 해결하려 하지 마세요.

정책, Global Routing 및 매칭 순서

설정의 정책과 화면의 라우팅 모드를 구분하세요

규칙의 PROXY, DIRECT, REJECT는 요청 처리 정책입니다. Home의 Global Routing에 있는 Config, Proxy, Direct는 전체 라우팅 모드입니다. 이름은 서로 관련이 있지만 혼용하면 안 됩니다. Config를 사용한다면 현재 설정의 Rule을 확인하세요. Proxy나 Direct로 전환한 경우 정상적인 설정 모드에서의 개별 분기 동작을 기준으로 테스트 결과를 해석해서는 안 됩니다. 문제를 기록할 때 먼저 현재 모드를 적어 두세요.

전체 라우팅 모드를 바꿔도 시스템 트래픽 우회나 제외 범위 같은 경계 설정이 사라지는 것은 아닙니다. 세 모드를 비교하는 이유는 서버 연결 문제와 설정 매칭 문제를 구분하기 위해서이지, 모든 시스템 요청이 같은 경로를 거친다는 것을 입증하기 위해서가 아닙니다. 테스트가 끝나면 예상한 Config 상태로 되돌린 뒤 규칙을 확인하세요. 그렇지 않으면 파일을 올바르게 수정했더라도 기대한 분기 결과를 확인하지 못할 수 있습니다.

자주 사용하는 세 가지 정책의 의미

PROXY는 매칭된 요청을 현재 프록시 경로로 보내며, 사용할 수 있는 서버 정보가 있어야 합니다. 규칙에 PROXY를 작성했다는 것은 프록시 정책을 선택했다는 뜻일 뿐 서버 인증이 완료되었거나 원격에서 대상에 접근할 수 있다는 뜻은 아닙니다. DIRECT는 현재 네트워크에서 대상에 직접 연결합니다. 로컬 라우팅, DNS 확인, 대상 서비스 문제로 연결에 실패할 수도 있습니다. REJECT는 매칭된 요청을 거부합니다. 명확하게 차단해야 하는 대상에 사용하고, 원인을 모르는 연결 문제를 숨기는 용도로 사용하지 마세요.

설정에서 추가 이름의 정책을 참조한다면 현재 파일이 해당 이름을 실제로 정의하고 지원하는지 먼저 확인하세요. 서버 메모를 임의로 정책 키워드처럼 사용해서는 안 됩니다. 이 문서의 예시는 파일 외부 항목에 대한 의존을 줄이기 위해 기본 정책 세 가지만 사용합니다. 서버 메모, 구독 이름, 규칙 정책은 서로 다른 계층에 속하므로 이름이 비슷해도 바꿔 쓸 수 없습니다.

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

Rule은 파일에 작성된 순서대로 확인합니다. 조건에 맞는 규칙이 해당 요청의 정책을 결정하며, 이후의 일반 규칙은 더 나은 매칭을 찾아 계속 확인하지 않습니다. 명확한 예외를 앞에 두고 넓은 범위의 분류를 뒤에 배치한 다음 FINAL로 나머지를 처리하는 구성을 권장합니다. 이런 순서는 검토하기 편하지만 실제 적용 범위가 핵심입니다. 구체적으로 보이는 키워드 규칙도 뒤에 있는 접미사 규칙보다 범위가 넓을 수 있습니다.

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

blocked 이름은 먼저 거부하고, api 이름에는 먼저 PROXY를 적용하며, 나머지 example.com 이름에는 DIRECT를 적용합니다. 첫 번째 줄과 접미사 규칙의 순서를 바꾸면 차단 예외가 접미사 규칙에 가려집니다. FINAL을 앞에 두면 일찍 처리가 끝나 뒤의 규칙이 의도대로 실행되기 어렵습니다. 순서를 확인할 때는 파일에서 대상 도메인을 검색하는 데 그치지 말고 요청이 각 조건을 위에서부터 어떻게 통과하는지 살펴보세요.

FINAL은 매칭 대상을 지정하지 않고 보통 FINAL,PROXY 또는 FINAL,DIRECT 형태로 Rule의 마지막에 작성합니다. 기본 정책을 나타내지만 모든 요청이 반드시 이를 거친다는 뜻은 아닙니다. FINAL이 적절한지 판단하려면 먼저 ‘앞선 규칙에서 분류되지 않은 요청을 어떻게 처리할 것인가’를 생각한 다음 사용자가 보유한 서버가 사용 가능한지 확인하세요. 어느 쪽을 마지막 정책으로 사용할지 정해진 답은 없습니다.

규칙을 관리할 때는 ‘차단 예외, 정확한 도메인, 도메인 접미사, 주소 분류, 마지막 정책’ 순으로 묶고 그룹 앞에 주석을 작성할 수 있습니다. 규칙을 추가할 때마다 기존 규칙이 새 대상을 이미 포함하는지 확인하세요. 같은 줄을 반복해도 신뢰성이 높아지지 않으며, 뒤의 규칙이 앞선 결정을 덮을 수 있다고 오해하게 만들 수 있습니다. 중복 항목을 삭제하기 전에는 매개변수가 완전히 같은지 확인해 의도적으로 범위를 달리한 설정까지 지우지 않도록 하세요.

Proxy 모드에서는 연결되지만 Config에서는 안 된다면 우선 매칭 규칙, DIRECT 분기, REJECT, DNS 관련 동작을 확인하세요. 두 모드 모두 실패한다면 서버 정보와 네트워크를 점검합니다. Direct에서 연결된다고 해서 모든 대상이 직접 연결에 적합하다는 뜻은 아니며, 당시 테스트한 대상의 해당 연결 경로가 사용 가능했다는 의미입니다. 같은 대상을 세 모드로 테스트한 결과를 기록해야 의미 있는 비교가 가능합니다.

Host 정적 매핑과 주소 범위

이름을 매핑하며 정책은 지정하지 않습니다

Host는 지정한 도메인을 정적 주소에 연결합니다. 이름에 해당하는 주소 정보를 바꾸지만 PROXY나 DIRECT를 직접 선택하지는 않으며 Rule을 대체하지도 않습니다. 내부 서비스의 주소를 지정하면서 직접 연결하려면 주소 매핑과 정책을 각각 설정해야 합니다. Host만 작성한 뒤 요청이 자동으로 직접 연결되기를 기대하거나 DOMAIN만 작성한 뒤 도메인이 특정 주소로 확인되기를 기대하면 두 기능을 혼동한 것입니다.

[Host]
localhost = 127.0.0.1
intranet.example.com = 192.168.1.20

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

여기서 사용하는 내부 이름과 주소는 학습용 예시입니다. 사용자의 네트워크에 해당 서비스가 실제로 있을 때만 의미가 있습니다. 예시 도메인을 설정에 입력한다고 서버가 생기지는 않으며 정적 매핑이 대상 서비스를 실행해 주지도 않습니다. 사용하기 전에 기기 주소, 서비스 포트, 현재 네트워크를 확인한 뒤 매핑을 유지할지 결정하세요. 예시를 바로 사용할 수 있는 기능 진입점으로 오해하지 않도록 주의하세요.

localhost는 현재 기기를 가리킵니다

localhost = 127.0.0.1은 IPv4 루프백 주소로 요청을 보내는 기기 자체를 가리킵니다. 라우터나 프록시 서버를 가리키는 주소가 아닙니다. 휴대폰에서 localhost에 접속해도 다른 기기의 서비스에 자동으로 연결되지 않습니다. 사용자의 LAN 기기에 연결해야 하는 안내를 따를 때는 실제로 연결할 수 있는 주소나 올바른 내부 이름을 사용하고, 서비스가 다른 기기의 접속을 허용하는 주소에 바인딩되어 있는지 확인하세요.

사설 주소는 해당 네트워크의 라우팅 범위 안에서만 의미가 있습니다. 집 Wi-Fi에서 유효한 192.168.1.20이 다른 네트워크에서는 존재하지 않거나 전혀 다른 기기를 가리킬 수 있습니다. 내부 이름을 사설 주소에 고정하기 전에 사용 범위를 고려하세요. 여러 네트워크에서 오래 사용할 파일이라면 정적 매핑으로 인해 이름이 더 이상 유효하지 않은 주소를 계속 가리킬 수 있습니다. 이때는 DNS 조회 실패가 아니라 지속적인 시간 초과로 나타날 수 있습니다.

Host로 TLS 신원 확인을 우회할 수 없습니다

HTTPS 연결에서는 대상 인증서와 요청 호스트 이름이 일치하는지 계속 확인합니다. 도메인을 다른 주소에 연결해도 그 주소에 설치된 아무 인증서나 신뢰할 수 있는 것은 아닙니다. 서버가 호스트 이름에 따라 사이트를 선택할 수도 있습니다. 매핑 후 인증서 오류가 발생하면 Host가 적용되지 않았다고 단정하지 말고 주소가 해당 서비스에 속하는지, 인증서가 원래 이름을 포함하는지 확인하세요. 주소 조회 성공과 신원 확인 성공은 따로 살펴봐야 합니다.

하나의 IP에서 여러 사이트를 제공할 수 있으므로 도메인 이름은 요청 대상을 구분하는 데 사용됩니다. 따라서 ‘해당 IP에 연결할 수 있다’고 해서 그 IP에 매핑한 모든 도메인이 작동하는 것은 아닙니다. 내부 HTTPS 서비스를 확인할 때는 이름, 주소, 포트, 인증서를 함께 점검하세요. 이 문서에서는 정적 매핑을 위해 인증서 신뢰 설정을 변경하도록 안내하지 않습니다. 사용자가 직접 운영하는 서비스에 이미 설정된 올바른 이름과 주소를 우선 사용하세요.

정적 매핑, 캐시 및 동적 서비스

주소가 동적으로 바뀌거나 분산 서비스를 사용하는 이름에 고정 주소를 지정하면 기존 연결 분배가 깨질 수 있습니다. 한 번 조회한 주소에 연결할 수 있다고 해서 장기간 Host에 등록해도 된다는 뜻은 아닙니다. 서비스 변경 후 이전 주소가 같은 콘텐츠를 제공하지 않을 수 있으며, 정적 매핑이 정상 조회 경로를 계속 덮어쓸 수도 있습니다. 관리 근거가 분명하지 않다면 조회 시간을 한 번 줄이려는 목적으로 공용 서비스 도메인의 주소를 고정하지 않는 것이 좋습니다.

앱이 자체 조회 결과나 기존 연결을 유지할 수 있고, 일부 요청은 같은 조회 경로를 따르지 않을 수도 있습니다. Host를 수정한 뒤에는 새 연결을 만들고 실제 대상 주소를 확인하세요. 로그에 이전 주소가 계속 표시되면 먼저 캐시와 연결 재사용을 확인한 다음 잘못된 설정을 선택했는지 살펴보세요. 편집기에 새 매핑이 표시된다는 이유만으로 대상 앱이 이를 사용한다고 단정하거나 모든 앱의 동작이 같다고 가정하지 마세요.

매핑을 삭제한 뒤에도 이전 캐시 때문에 정상 조회가 바로 복구되지 않을 수 있습니다. 되돌릴 때는 원본 파일을 보관하고 해당 매핑만 제거한 다음 저장하고 다시 선택해 같은 대상으로 테스트하세요. 이름 확인은 복구됐지만 특정 주소에 접속할 수 없다면 이전 정적 주소가 유효하지 않았을 가능성이 큽니다. 조회가 계속 실패한다면 DNS 섹션으로 돌아가 시스템 DNS 출처와 네트워크 환경을 확인하세요.

Host를 장기간 관리할 때는 각 매핑의 용도를 설명할 수 있어야 합니다. 별도의 주석 줄에 ‘로컬 테스트 서비스’나 ‘내부 고정 주소’처럼 이유를 기록할 수 있지만 계정 인증 정보는 적지 마세요. 기기에 새 주소가 할당되거나 네트워크 대역이 바뀌거나 서비스가 이전되면 함께 다시 확인해야 합니다. Host 항목이 적고 명확할수록 유효하지 않은 항목을 쉽게 찾고 실험과 무관한 정상 요청에 영향을 줄 가능성도 줄어듭니다.

URL Rewrite 및 USER-AGENT 적용 범위

URL 변경과 라우팅 정책 선택은 다릅니다

URL Rewrite는 확인 가능한 요청 URL을 매칭하고 변경하며 Rule은 요청 조건에 따라 정책을 선택합니다. 주소 하나를 다른 주소로 리디렉션해도 PROXY가 적용되는 것은 아닙니다. 새 주소에서 발생하는 요청도 현재 라우팅 설정에 따라 처리됩니다. 이 점을 이해하면 ‘변경은 됐지만 대상 페이지가 열리지 않는’ 상황에서 정규식만 고치고 새 대상의 도메인 규칙, 조회 결과, 연결 상태 확인을 놓치는 일을 피할 수 있습니다.

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

이 줄은 조건에 맞는 HTTP 주소를 HTTPS 주소로 리디렉션하는 문법을 보여줍니다. 왼쪽은 정규식, 가운데는 대상 URL, 마지막은 리디렉션 상태 코드입니다. ^는 문자열의 시작부터 매칭하고 \.은 문자 그대로의 점을 나타냅니다. 도메인 뒤의 슬래시는 호스트 경계를 구분하는 데 도움이 됩니다. 이스케이프가 없으면 정규식의 점이 다른 문자와도 일치해 의도하지 않은 이름이 매칭될 수 있습니다.

경로와 쿼리 매개변수를 유지할지 명확히 설정하세요

위의 간단한 예시는 원래 경로와 쿼리 매개변수를 유지한다고 명시하지 않으므로 요청의 업무 매개변수를 보존해야 하는 경우 그대로 사용할 수 없습니다. 대상 주소에 API 경로, 검색 매개변수, 인증 정보가 포함되어 있다면 고정된 홈으로 리디렉션할 때 요청의 의미가 달라집니다. 규칙을 작성하기 전에 입력과 원하는 출력을 정리하고 캡처 그룹이 필요한지 결정하세요. 먼저 넓은 표현식을 복사한 뒤 우연히 페이지가 열린다는 이유로 올바르다고 판단하지 마세요.

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

이 예시는 캡처 그룹과 $1 참조를 사용해 슬래시 뒤의 내용을 유지합니다. 하지만 여전히 문법을 설명하기 위한 예시입니다. 대상 서비스가 HTTPS를 지원해야 하며 클라이언트가 리디렉션에 따라 다음 요청을 이어서 보내야 합니다. 인코딩된 문자, 쿼리 매개변수, 여러 단계의 이동이 있다면 실제 요청 결과를 확인해 새 주소가 예상과 일치하는지 살펴보세요. 리디렉션은 서버 내부의 경로 변경이 아니며 원격 서비스가 제공하는 콘텐츠도 바꾸지 않습니다.

302와 영구 리디렉션은 캐시 동작이 다릅니다. 테스트 단계에서는 임시 리디렉션이 변화를 확인하기 쉽지만 브라우저와 앱 자체의 캐시도 고려해야 합니다. 설정이 적용된 뒤 다른 규칙이 대상을 다시 원래 주소로 돌리면 반복 이동이 생길 수 있습니다. 브라우저에 리디렉션이 너무 많다는 메시지가 표시되면 마지막 규칙만 고치지 말고 각 이동의 출발지와 대상을 확인하세요. 먼저 설명할 수 있는 변경 하나만 남겨 검증하세요.

HTTPS에서 확인할 수 있는 정보와 처리 제한

일반적인 HTTPS 요청의 경로와 헤더는 암호화 연결 안에 있으므로 클라이언트가 연결을 전달한다는 이유만으로 모든 필드를 변경할 수 있다고 가정해서는 안 됩니다. HTTPS 콘텐츠를 처리하려면 별도의 MITM 설정, 도메인 범위, 인증서 신뢰가 필요하며 앱의 인증서 검증 방식에 따라 제한될 수도 있습니다. 이 문서의 최소 예시에는 이러한 설정이 없으므로 모든 HTTPS 앱의 내용을 바로 변경할 수 있다는 뜻이 아닙니다.

콘텐츠를 처리할 수 있는 조건이 갖춰져 있더라도 사용자가 이해하고 테스트할 필요가 있는 도메인으로 범위를 제한하세요. 규칙 하나를 매칭시키려고 모든 요청으로 확대하지 마세요. 로그인 매개변수, 세션 정보, 개인 데이터가 포함된 URL을 공개 메모에 복사해서는 안 됩니다. 현재 해결하려는 문제가 연결 실패라면 먼저 Rule, DNS, 서버를 확인하세요. 일반적으로 콘텐츠 변경부터 시작할 이유는 없습니다. 라우팅 문제 해결과 콘텐츠 변경은 별도로 다뤄야 합니다.

USER-AGENT는 모든 앱을 식별하는 기능이 아닙니다

USER-AGENT는 Rule에서 확인 가능한 HTTP 요청 헤더를 기준으로 매칭하는 유형이지 앱 이름으로 모든 연결을 식별하는 기능이 아닙니다. 암호화 트래픽에서 해당 헤더를 확인할 수 없다면 매칭을 기대할 수 없습니다. 앱마다 다른 식별자를 사용하거나 여러 네트워크 구성 요소를 거칠 수 있으며, 사용 가능한 필드가 없을 수도 있습니다. 따라서 USER-AGENT는 명확한 요청 사례가 있는 경우에 적합하며 ‘특정 앱의 모든 트래픽’을 처리하는 범용 규칙으로 사용하기에는 적합하지 않습니다.

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

여기서 ExampleClient는 학습용 식별자이며 별표는 매칭 패턴의 와일드카드 범위를 나타냅니다. 실제로 확인 가능한 필드가 패턴과 일치할 때만 첫 번째 줄이 적용되고, 조건에 맞지 않는 요청은 뒤의 규칙을 계속 확인합니다. 이 줄을 앞에 두면 매칭된 요청은 이후 도메인 접미사 조건에도 해당하더라도 먼저 DIRECT를 사용합니다. 규칙을 배치하기 전에 이 우선순위가 의도한 동작인지 확인하세요.

USER-AGENT 또는 URL Rewrite를 확인할 때는 먼저 매칭 대상이 확인 가능한지, 다음으로 표현식이 일치하는지, 마지막으로 결과가 올바른지 증명하세요. 세 단계를 각각 기록해야 합니다. 매칭 기록이 없다고 곧바로 와일드카드 범위를 넓히지 마세요. 필드를 확인할 수 없거나 요청이 다시 발생하지 않았거나 설정이 선택되지 않은 경우에도 같은 현상이 나타날 수 있습니다. 먼저 일반 도메인 규칙으로 라우팅 기준을 확인한 뒤 콘텐츠 관련 조건을 하나씩 추가하면 되돌릴 수 있는 테스트를 진행하기 쉽습니다.

설정 확인, 문제 해결 및 관리 절차

재현 가능한 기준부터 마련하세요

문제 해결을 시작하기 전에 현재 네트워크, Global Routing 모드, 선택한 설정, 현재 서버, 테스트 대상을 기록하세요. 서로 다른 Wi-Fi, 대상, 서버에서 얻은 결과를 한 번의 비교로 묶지 마세요. 사용자가 기존 구독을 방금 업데이트했다면 Home에서 현재 선택이 예상한 서버를 가리키는지 확인하세요. 설정 텍스트가 바뀌지 않았더라도 구독 내용이나 선택 대상이 달라져 결과가 달라질 수 있습니다.

Connectivity Test는 서버 테스트 결과를 확인하는 데 도움이 되지만, 한 번 성공했다고 모든 대상에 연결할 수 있거나 Rule이 예상대로 매칭된다는 뜻은 아닙니다. 테스트 도구와 대상 앱은 서로 다른 요청 경로를 사용할 수 있습니다. 테스트 결과는 기준 정보로 활용하고 실제 대상에 새 연결을 만들어 도메인, 주소, 정책을 확인하세요. 연결 스위치가 켜져 있다는 것은 클라이언트가 연결 상태에 들어갔다는 뜻일 뿐 대상 요청이 성공했다는 증거는 아닙니다.

처리 경로에 따라 하나씩 확인하기

첫째, 파일이 실제로 선택되어 있는지 확인합니다. 둘째, Global Routing이 Config인지 확인합니다. 셋째, General 설정이 대상 요청을 일반 처리 경로에서 우회시키는지 확인합니다. 넷째, 실제 도메인이나 IP가 무엇인지 확인합니다. 다섯째, 매칭된 규칙과 정책을 살펴봅니다. 마지막으로 선택한 연결 경로의 결과를 확인합니다. 이 순서를 따르면 전제 조건이 성립하지 않은 상태에서 뒤의 규칙을 논하는 일을 피하고, ‘매칭 단계에 들어가지 않은 경우’와 ‘매칭은 됐지만 연결에 실패한 경우’를 구분할 수 있습니다.

로그를 볼 때는 같은 시각에 발생한 새 요청을 찾으세요. 이전 기록의 정책은 수정 전 설정에 따른 결과일 수 있습니다. 연결 재사용으로 인해 새 규칙 매칭 과정이 실행되지 않을 수도 있습니다. 연결을 다시 시작한 뒤 대상을 다시 열면 이런 영향을 줄일 수 있습니다. 예상한 기록이 계속 없다면 대상에서 실제 요청을 보냈는지, IP로 직접 연결하는지, 우회 설정의 영향을 받는지 추가로 확인하세요. 중복 규칙을 바로 추가하지 마세요.

최소 규칙으로 하나의 가설 검증하기

도메인 규칙 범위가 잘못됐다고 의심된다면 사용 가능한 설정을 복사한 뒤 필요한 General, 대상의 정확한 규칙, FINAL만 남기고 관련 키워드 규칙, Host, URL Rewrite는 일시적으로 제거하세요. 최소 설정 파일은 장기간 사용할 설정이 아니라 가설 하나를 검증하기 위한 것입니다. 정확한 규칙이 안정적으로 매칭되면 접미사, 주소 분류, 기타 예외를 차례로 복원해 어느 단계에서 처리 결과가 달라지는지 찾으세요.

[General]
dns-server = system

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

이 예시를 사용하려면 사용자에게 사용 가능한 서버가 있어야 합니다. Proxy 모드에서도 실패한다면 Rule을 더 추가할 이유가 분명하지 않으므로 서버와 네트워크를 다시 확인하세요. 최소 규칙은 성공하지만 전체 설정은 실패한다면 두 파일의 앞선 매칭 범위, 정적 매핑, DNS 설정을 비교하세요. 한 번에 한 그룹씩 복원하고 처음 차이가 생기는 지점을 기록하면 모든 내용을 한꺼번에 추가하는 것보다 원인을 빠르게 찾을 수 있습니다.

정보 보호와 되돌릴 수 있는 상태 유지

문제 해결 자료를 공유하기 전에 구독 주소, 인증 항목, 개인 도메인, 민감한 경로, 계정을 식별할 수 있는 쿼리 매개변수를 제거하세요. 규칙 유형, 대상 범주, 정책, 오류 현상은 남기고 실제 대상은 예시 도메인으로 바꿔도 됩니다. 스크린샷과 로그에도 인증 정보가 포함될 수 있으므로 설정 파일이 아니라는 이유로 확인을 생략하지 마세요. 기본 규칙 문법을 설명하는 데 사용자의 구독 정보를 공개할 필요는 없습니다.

장기간 관리할 때는 최근에 작동한 로컬 복사본을 보관하고 변경할 때마다 목표와 테스트 결과를 기록하세요. 원격 설정이 업데이트되면 파일 이름만 비교하지 말고 선택 상태, FINAL, General, 주요 예외를 다시 확인합니다. 규칙을 추가하기는 쉽지만 삭제하기 어렵다면 먼저 그룹별 용도를 검토하세요. 이유를 설명할 수 없는 넓은 규칙은 예외를 계속 덧붙이지 말고 복사본에서 제거했을 때의 결과를 확인하세요.

기본 사용법은 빠른 시작 안내를, 화면 및 규칙 용어는 용어집을 확인하세요. 연결이 켜져 있는데 웹페이지가 열리지 않는다면 서버, 모드, DNS 및 규칙 문제 해결을 따라 항목별로 비교해 보세요. 시스템 권한 관련 문제가 있다면 VPN 구성 추가 안내를 참고하세요. 각 안내는 서로 다른 문제를 다루므로 같은 현상에 대해 구매, 가져오기, 설정을 모두 다시 진행할 필요는 없습니다.