Shadowrocket
규칙 및 설정 파일 가이드

01 / FILE STRUCTURE

설정 파일 구조와 적용 위치

설정 파일과 서버 정보는 별도로 관리

Shadowrocket의 서버 항목과 설정 파일은 서로 다른 역할을 합니다. 서버 항목에는 연결 대상, 포트, 프로토콜, 인증 정보가 저장됩니다. 설정 파일은 요청의 매칭 방식과 적용할 정책, 일부 DNS 및 요청 처리 방식을 지정합니다. 이 매뉴얼은 사용자가 이미 구독 또는 서버 정보를 보유하고 있다는 전제에서 작성되었습니다. 서버를 가져와 선택할 수 있다고 해서 규칙 파일이 활성화된 것은 아닙니다. 반대로 규칙 파일이 정상적으로 저장되어도 PROXY에 사용할 연결 대상이 없을 수 있습니다.

수정하기 전에 Home에서 선택된 서버를 확인하고, Config에서 현재 사용하는 설정 파일을 확인한 다음 Global Routing을 살펴보세요. 파일 안의 분기 규칙을 확인하려면 Global Routing을 Config로 설정해야 합니다. Proxy와 Direct는 전역 라우팅 방식을 바꾸는 옵션이므로, 이 상태에서의 테스트 결과만으로 특정 도메인 규칙이 올바른지 판단할 수 없습니다. 서버, 파일, 전역 라우팅 상태를 각각 기록해 두면 한 항목을 수정한 뒤 다른 항목까지 바뀐 것으로 착각하는 일을 줄일 수 있습니다.

섹션 제목을 기준으로 파일 읽기

설정 파일은 섹션별 텍스트 구조로 되어 있으며, 대괄호로 둘러싼 제목이 뒤따르는 내용의 영역을 나타냅니다. [General]에는 전역 매개변수를, [Rule]에는 매칭 조건과 정책을 한 줄씩 작성합니다. [Host]에는 지정한 도메인의 고정 매핑을, [URL Rewrite]에는 조건에 맞는 URL 처리 방식을 적습니다. 섹션 제목 자체는 규칙이 아니며 요청 매칭에도 참여하지 않습니다. [General] 아래에 DOMAIN-SUFFIX를 적어도 올바른 키워드가 포함됐다는 이유만으로 유효한 분기 규칙이 되지는 않습니다.

이 예시는 두 가지 라우팅 의도만 보여 줍니다. example.com과 하위 도메인은 PROXY를 사용하고, 나머지는 DIRECT로 처리합니다. 서버 인증 정보는 포함되어 있지 않으며 연결 서비스도 제공하지 않습니다. 예시 도메인은 문법 설명용이므로 특정 서비스에 접속할 수 있다고 기대해서는 안 됩니다. 전체 파일을 읽을 때는 먼저 섹션 제목을 찾고 [Rule]에서 FINAL의 위치를 확인하세요. 첫 줄부터 도메인을 찾다가 해당 항목이 실제로 어느 섹션에 있는지 놓치지 않도록 주의하세요.

쉼표, 등호, 주석의 용도

[General]에서는 dns-server = system처럼 키, 등호, 값을 사용합니다. [Rule]에서는 보통 DOMAIN,example.com,DIRECT처럼 영문 쉼표로 유형, 매칭 값, 정책을 구분합니다. 두 형식은 서로 바꿔 쓸 수 없습니다. 편집할 때는 반각 문장 부호를 사용하고 입력기가 쉼표를 전각 쉼표로 바꾸지 않았는지 확인하세요. 주석은 별도 줄 맨 앞에 #을 붙여 의도를 기록할 수 있습니다. 규칙 끝에 설명을 덧붙이기보다 주석을 별도 줄에 쓰면 필드 경계를 확인하고 텍스트를 복사하기 쉽습니다.

모든 설정 파일에 네 섹션이 다 필요한 것은 아닙니다. 고정 매핑이 없다면 [Host]를 생략해도 되고, URL을 처리할 필요가 없다면 [URL Rewrite]도 추가하지 않아도 됩니다. 필요한 최소 설정부터 시작해 목적이 분명한 내용을 하나씩 추가하는 편이 여러 파일의 섹션을 통째로 합치는 것보다 검증하기 쉽습니다. 중복된 섹션이나 매개변수가 있다면 중복 항목의 덮어쓰기 동작에 기대지 말고 하나의 명확한 정의로 정리하세요. 구조를 정리하기 전에 원본 파일을 복사해 두세요.

02 / GENERAL & DNS

General 매개변수 및 DNS 설정

네트워크 범위를 확인한 뒤 우회 범위 설정

[General]의 매개변수는 이후 규칙이 작동하는 환경에 영향을 줍니다. bypass-system = true는 시스템 관련 트래픽을 우회시키는 설정이지, 모든 Apple 도메인에 DIRECT를 지정하는 설정이 아닙니다. [Rule]을 대신하는 범용 규칙으로 이해해서도 안 됩니다. skip-proxy는 프록시 처리를 건너뛸 주소 범위를 지정합니다. 요청이 규칙 평가 전에 이미 우회되었다면 뒤에 있는 PROXY 규칙을 수정해도 기대한 결과가 나오지 않을 수 있습니다. 문제를 해결할 때는 규칙 행의 위치만 바꾸지 말고 전역 우회 설정과 [Rule]을 함께 확인하세요.

로컬 네트워크 기기에는 실제 주소 구성에 맞는 우회 범위를 설정해야 합니다. 192.168.0.0/16과 10.0.0.0/8은 사설 주소 범위의 예시일 뿐이며, 현재 네트워크가 반드시 이 범위를 사용한다는 뜻은 아닙니다. 먼저 기기의 네트워크 정보와 대상 서비스 주소를 확인한 뒤 해당 범위를 유지할지 결정하세요. 범위를 지나치게 넓게 잡으면 프록시로 접속해야 하는 내부 대상까지 제외될 수 있습니다. 반대로 범위가 너무 좁으면 프린터, 저장 장치 또는 기타 로컬 서비스의 트래픽이 적절하지 않은 경로로 전달될 수 있습니다.

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

DNS 확인과 라우팅 정책은 별개

dns-server = system은 시스템 DNS 설정을 사용한다는 뜻이며, 기본 상태를 확인하기에 적합합니다. DNS는 도메인을 주소로 변환하고 라우팅 규칙은 요청에 적용할 정책을 결정합니다. 도메인이 정상적으로 확인되더라도 선택된 서버가 해당 주소에 연결할 수 있다는 뜻은 아닙니다. 요청이 DIRECT 규칙에 매칭되어도 DNS 조회가 사용자가 예상한 경로로 처리된다는 보장은 없습니다. 연결 시간 초과를 모두 DNS 탓으로 돌리지 않도록 DNS 결과, 규칙 매칭, 최종 연결을 각각 확인하세요.

DNS를 바꾸기 전에 해결하려는 문제가 무엇인지 먼저 확인하세요. 도메인이 조회되지 않는지, 결과가 예상과 다른지, 아니면 주소는 확인됐지만 연결에 실패하는지 구분해야 합니다. 문제가 특정 대상 하나에서만 발생한다면 전체 파일의 DNS 설정을 즉시 바꾸지 말고 해당 대상과 [Host] 매핑을 확인하세요. 여러 도메인이 모두 조회되지 않는 경우에는 현재 네트워크에서 시스템 DNS를 사용할 수 있는지 살펴보세요. 암호화 DNS 주소, 부트스트랩 조회, 연결 경로 사이에 의존성이 있을 수 있으므로 주소 형식만 보고 현재 네트워크에 적합한 설정인지 판단해서는 안 됩니다.

규칙에 DNS 조회가 필요한지는 매칭 조건에 따라 달라집니다

DOMAIN 계열 규칙은 주로 도메인을 기준으로 판단합니다. IP-CIDR과 GEOIP는 판단에 사용할 대상 주소가 필요합니다. 요청이 도메인으로 시작되면 주소 기반 규칙을 적용하는 과정에서 DNS 조회가 필요할 수 있습니다. IP-CIDR에 no-resolve를 추가하면 해당 주소 규칙을 위해 별도로 도메인을 조회하지 않습니다. 클라이언트 전체의 DNS를 끄는 설정은 아닙니다. 특정 주소에 대한 요청이나 주소 규칙으로 인한 조회를 피해야 하는 경우에 적합하지만, 아직 주소를 얻지 못한 도메인 요청은 이 규칙에 매칭되지 않을 수 있습니다.

앱과 시스템은 조회 결과를 캐시할 수 있고, 웹 연결은 이미 만들어진 세션을 재사용할 수 있습니다. DNS를 변경한 뒤 같은 페이지를 새로고침해도 새로운 DNS 조회 결과를 확인하는 것은 아닐 수 있습니다. 검증할 때는 연결을 새로 시작하고, 필요한 경우 Shadowrocket을 다시 연결한 뒤 로그의 시간과 대상을 확인하세요. 비교를 위해 사용할 수 있는 dns-server = system 설정을 따로 보관하고, 매번 DNS 관련 매개변수 하나만 바꾸면 새 설정의 효과와 기존 캐시로 인한 변화를 구분하기 쉽습니다.

Wi-Fi와 셀룰러 네트워크를 전환한 뒤에만 문제가 발생한다면 각 네트워크에서의 증상을 따로 기록하세요. 시스템 DNS, 로컬 주소 범위, 서버 연결 가능 여부는 네트워크에 따라 달라질 수 있습니다. 이때 잘못된 설정을 가리려고 skip-proxy 범위를 넓히거나 DNS 매개변수를 반복해서 추가하지 마세요. 먼저 정상 작동하는 기본 설정으로 되돌리고 네트워크 간 차이를 확인한 다음 문제 해결의 연결 점검 방법을 참고하세요. 장기적으로 수정해야 한다고 판단한 뒤에만 평소 사용하는 설정 파일에 매개변수를 반영하세요.

03 / DOMAIN MATCHING

DOMAIN 계열 규칙의 적용 범위

DOMAIN은 지정한 도메인만 매칭

DOMAIN은 도메인을 정확히 매칭합니다. DOMAIN,api.example.com,PROXY는 api.example.com에 적용되며 example.com이나 도메인에 같은 문자열이 들어 있는 otherexample.com까지 자동으로 포함하지 않습니다. 규칙의 필드에는 호스트 이름을 입력하고 프로토콜, 경로, 포트, 쿼리 매개변수는 넣지 않습니다. 전체 웹 주소를 DOMAIN의 매칭 필드에 입력하면 URL과 도메인의 개념을 혼동하게 됩니다. 경로에 따라 처리해야 한다면 도메인 규칙의 범위를 넓히기보다 URL 처리에 해당하는지 먼저 살펴보세요.

정확한 규칙은 특정 서비스 진입점에 예외를 적용할 때 적합합니다. 예를 들어 example.com 전체는 PROXY를 사용하되 status.example.com은 DIRECT로 처리할 수 있습니다. 이 예외는 범위가 더 넓은 DOMAIN-SUFFIX보다 앞에 배치해야 합니다. 접미사 규칙이 먼저 매칭되면 뒤에 있는 정확한 규칙은 평가되지 않습니다. 여기서 우선순위는 행의 위치로 결정됩니다. DOMAIN이 DOMAIN-SUFFIX보다 구체적으로 보인다고 해서 우선하는 것은 아닙니다. 클라이언트가 구체성에 따라 파일을 자동으로 정렬하지 않습니다.

DOMAIN-SUFFIX는 도메인 경계를 기준으로 매칭

DOMAIN-SUFFIX,example.com,PROXY는 example.com과 그 하위 도메인에 매칭됩니다. 예를 들면 www.example.com과 a.b.example.com이 포함됩니다. 접미사 매칭은 도메인 계층의 경계를 기준으로 하므로 임의의 문자열 포함과는 다릅니다. 따라서 otherexample.com은 하위 도메인이 아닙니다. 접미사 필드에는 보통 앞에 점을 붙이거나 별표를 쓸 필요가 없습니다. *.example.com을 일반적인 접미사 예시로 복사하면 해당 규칙 문법과 맞지 않는 와일드카드 개념을 적용하게 될 수 있습니다.

[Rule]
# 정확한 예외를 먼저
DOMAIN,status.example.com,DIRECT
# 기본 도메인과 하위 도메인은 뒤에
DOMAIN-SUFFIX,example.com,PROXY
FINAL,DIRECT

하나의 웹페이지가 페이지의 기본 도메인, 이미지 도메인, 인증 도메인, API 도메인에 동시에 요청을 보낼 수 있습니다. 주소창에 표시된 도메인 하나에만 규칙을 추가해도 관련 요청이 모두 같은 정책을 따르는 것은 아닙니다. 연결 기록에서 실제 요청 호스트 이름을 확인한 다음 DOMAIN을 여러 개 사용할지, 합리적으로 범위를 지정하는 DOMAIN-SUFFIX를 사용할지 결정하세요. 서로 관련 없는 대상을 짧은 키워드 하나로 묶으면 한 페이지의 문제를 해결하는 과정에서 다른 앱의 트래픽 경로까지 바뀔 수 있습니다.

DOMAIN-KEYWORD는 문자열 포함 여부로 매칭

DOMAIN-KEYWORD,example,PROXY는 도메인에 example이라는 문자열이 포함되어 있는지 판단하므로 example.com보다 훨씬 넓은 범위를 대상으로 할 수 있습니다. 등록 도메인 경계가 같지 않아도 해당 문자열이 들어 있는 다른 도메인에 매칭됩니다. 키워드 규칙은 문자열 기준의 넓은 매칭이 꼭 필요한 상황에 적합합니다. 하나의 기본 도메인과 그 하위 도메인만 대상으로 한다면 DOMAIN-SUFFIX를 우선 사용하세요. 키워드가 짧을수록 의도하지 않은 매칭이 없는지 꼼꼼히 확인해야 합니다.

검증할 수 있는 조건으로 규칙 의도를 작성하세요

도메인 규칙을 추가하기 전에 적용 범위를 한 문장으로 설명해 보세요. 예를 들어 “status.example.com만 직접 연결”이라고 정한 뒤 실제 필드와 맞는지 확인합니다. 설명에 “모든 하위 도메인”이 들어간다면 접미사 규칙을 써야 하는지 점검하세요. “특정 경로”가 조건이라면 도메인 규칙만으로는 요구 사항을 표현하기 어렵습니다. 국제화 도메인은 연결 기록에 실제로 나타나는 호스트 이름을 확인해 표시 이름과 설정 텍스트가 다르지 않은지 살펴보세요. 웹페이지 제목이나 앱 이름만으로 도메인을 추측하지 마세요.

검증할 때는 규칙에 매칭되어야 하는 대상과 매칭되면 안 되는 대상을 각각 방문해 양쪽 결과를 확인하세요. 페이지가 열렸는지만 기록하지 말고 호스트 이름, 매칭된 규칙, 적용 정책도 함께 확인해야 합니다. DIRECT로도 페이지에 접속할 수 있으므로 페이지가 열린다는 사실만으로 PROXY 규칙이 적용됐다고 볼 수 없습니다. 페이지가 열리지 않는 원인도 서버나 대상 서비스에 있을 수 있습니다. 수정한 뒤 관련 없는 요청까지 PROXY로 전달된다면 같은 종류의 규칙을 파일 끝에 계속 추가하지 말고 먼저 키워드 범위를 좁힌 다음 행 순서를 확인하세요.

04 / ADDRESS & REQUEST

GEOIP, IP-CIDR 및 USER-AGENT

IP-CIDR은 주소와 접두사 길이로 매칭

IP-CIDR은 IP-CIDR,192.168.0.0/16,DIRECT처럼 IPv4 주소 범위를 지정합니다. 슬래시 뒤 숫자는 접두사 길이이지 포트나 매칭할 주소 개수가 아닙니다. 접두사 길이가 길수록 범위가 좁아집니다. 단일 IPv4 주소는 /32로 나타낼 수 있습니다. IP 대역 규칙을 수정할 때는 대상의 실제 주소와 네트워크 경계를 함께 확인하세요. 주소 앞부분이 비슷하다는 이유만으로 대상이 범위에 포함된다고 판단해서는 안 됩니다. 접두사를 잘못 지정하면 관련 없는 다수의 요청이 같은 정책에 포함될 수 있습니다.

로컬 네트워크 범위는 [General]의 skip-proxy와 함께 살펴봐야 합니다. 어떤 범위가 이미 전역적으로 우회되고 있다면 [Rule]에 같은 범위의 DIRECT를 추가해도 중복 표현일 뿐, 규칙 엔진이 해당 행을 매칭했다는 증거가 되지 않을 수 있습니다. 특정 규칙의 동작을 확인하려면 먼저 요청이 규칙 평가에 들어오는지 알아야 합니다. 일상 설정에서 필요한 보호 목적의 직접 연결 규칙을 유지할 수는 있지만, 주석으로 용도를 밝혀 두세요. 중복 항목을 우선순위를 높이는 방법으로 사용하지 마세요.

[Rule]
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
GEOIP,CN,DIRECT
FINAL,PROXY

IP-CIDR6과 no-resolve의 적용 범위

IP-CIDR6은 IPv6 주소 범위를 지정합니다. IPv6 주소를 IP-CIDR에 그대로 넣어도 같은 방식으로 처리되지 않습니다. fc00::/7은 로컬 IPv6 범위의 예시이며 모든 IPv6 요청을 DIRECT로 처리해야 한다는 뜻은 아닙니다. 하나의 도메인에서 IPv4와 IPv6 주소를 모두 받을 수 있으므로 한 종류의 주소만 확인하면 실제 연결 경로를 놓칠 수 있습니다. 같은 도메인이 어떤 때는 매칭되고 어떤 때는 매칭되지 않는다면 요청에 어떤 주소가 사용됐는지 먼저 확인한 뒤 필요한 규칙을 추가하세요.

no-resolve는 해당 행의 매칭을 위해 도메인을 별도로 조회하지 않도록 하는 주소 규칙의 추가 매개변수입니다. 주소를 직접 사용하는 요청은 이미 가지고 있는 주소로 매칭할 수 있습니다. 아직 매칭할 주소가 없는 도메인 요청에는 이 행이 적용되지 않을 수 있습니다. 이는 문법 오류가 아니라 사용 조건의 차이입니다. 조회 시간을 줄이겠다는 이유로 모든 주소 규칙에 no-resolve를 기계적으로 추가하지 마세요. 강제 직접 연결이나 원격 DNS 사용을 지정하는 옵션도 아닙니다.

GEOIP는 도메인의 지역 정보를 판단하지 않습니다

GEOIP,CN,DIRECT는 도메인 접미사, 웹페이지 언어, 서비스 브랜드가 아니라 대상 IP의 지역 분류를 기준으로 판단합니다. 하나의 도메인이 여러 지역의 주소로 확인될 수 있으며, IP 주소 데이터베이스의 분류가 실시간 네트워크 품질을 나타내는 것도 아닙니다. 특정 도메인에 안정적으로 같은 정책을 적용해야 한다면 DOMAIN 또는 DOMAIN-SUFFIX로 명시한 뒤, 남은 트래픽은 뒤쪽에서 GEOIP로 처리하세요. 그렇지 않으면 주소가 바뀔 때 같은 서비스도 네트워크에 따라 다른 정책을 사용할 수 있습니다.

USER-AGENT는 확인할 수 있는 요청 필드가 필요합니다

USER-AGENT는 확인 가능한 HTTP 요청의 User-Agent 값을 매칭하며 앱 표시 이름으로 프로세스를 식별하지 않습니다. 예시 USER-AGENT,ExampleClient*,DIRECT는 접두사 매칭을 나타내지만 해당 요청 필드를 읽을 수 있어야 판단할 수 있습니다. 일반적인 암호화 연결에서는 HTTP 요청 헤더를 직접 확인하기 어렵습니다. 앱이 실제로 이 필드를 보낸다고 해서 클라이언트가 반드시 규칙 매칭에 사용할 수 있는 것은 아닙니다. 모든 앱의 분기 규칙을 대신하는 범용 방법으로 적합하지 않습니다.

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

USER-AGENT를 적용하려고 요청 복호화를 활성화하면 추가적인 신뢰 및 호환성 조건이 필요합니다. 처음 분기 설정을 할 때 반드시 거쳐야 하는 단계는 아닙니다. 도메인 규칙으로 요구 사항을 표현할 수 있다면 먼저 도메인 규칙을 사용하세요. 주소 규칙과 요청 특성 규칙에는 모두 명확한 검증 조건이 필요합니다. 판단에 사용할 주소가 있는지, 요청 필드를 확인할 수 있는지, 앞선 규칙이 이미 매칭되지 않았는지 살펴보세요. 규칙을 파일 아래쪽에서 위쪽으로 옮기는 것보다 이런 질문에 답하는 편이 문제를 더 정확히 진단할 수 있습니다.

05 / POLICY & PRIORITY

PROXY, DIRECT, REJECT 및 규칙 순서

정책은 매칭 후 요청 처리 방식을 결정합니다

규칙 유형은 무엇을 확인할지 정하고 정책은 매칭된 요청을 어떻게 처리할지 결정합니다. PROXY는 요청을 프록시 경로로 보냅니다. 간단한 설정에서는 보통 현재 선택된 서버를 사용하지만, 파일에 정책 그룹이나 다른 연결 설정이 있다면 실제로 선택된 구성원도 확인해야 합니다. DIRECT는 프록시 서버를 거치지 않고 대상에 직접 연결한다는 뜻입니다. 다만 연결 결과는 현재 네트워크, DNS, 대상 서비스의 상태에 영향을 받습니다. REJECT는 매칭된 요청을 거부하며 연결 실패 시 자동으로 전환되는 대체 정책이 아닙니다.

설정 파일의 PROXY, DIRECT, REJECT는 정책 키워드입니다. Home에서 선택하는 서버와 Global Routing의 Proxy, Direct는 인터페이스 상태를 나타냅니다. 대소문자와 사용 위치가 다르므로 같은 개념으로 혼용하면 안 됩니다. 규칙 하나를 PROXY로 바꿔도 서버 암호, 포트, 프로토콜 매개변수가 자동으로 수정되지는 않습니다. PROXY에 매칭되는 요청이 모두 실패한다면 각 규칙을 하나씩 DIRECT로 바꾸기보다 프록시 경로를 먼저 확인하세요.

Global Routing의 세 가지 모드

이 표는 테스트 모드를 정하는 데 참고하기 위한 것으로, 모든 상황에서 시스템 우회나 다른 전역 설정을 무시해도 된다는 뜻은 아닙니다. 진단할 때 Proxy 또는 Direct를 잠시 사용해 연결 경로를 비교할 수 있지만, 확인이 끝나면 Config로 되돌린 뒤 현재 파일의 규칙 매칭을 점검하세요. 그렇지 않으면 파일을 수정해도 전역 프록시 또는 직접 연결 모드가 유지되어 변화가 없는 것처럼 보일 수 있습니다. 테스트 결과를 기록할 때는 대상과 함께 모드도 적어 같은 대상이 라우팅 조건에 따라 어떻게 달라지는지 구분하세요.

처음 매칭된 규칙에서 처리 종료, 자동 대체 없음

[Rule]은 위에서 아래로 확인하며 조건에 처음 일치한 규칙이 정책을 결정합니다. 더 구체적인 규칙을 일반적인 규칙보다 앞에 두는 것이 원칙입니다. 클라이언트가 자동으로 정렬해 주는 것은 아닙니다. 앞의 DOMAIN-KEYWORD가 도메인에 매칭되면 뒤의 DOMAIN이 더 정확하더라도 적용되지 않습니다. 같은 조건이 반복되면 뒤의 항목은 대개 도달할 수 없는 중복 규칙입니다. 나중에 작성한 내용이 앞의 규칙을 자동으로 덮어쓸 것이라 기대하지 말고 정리하세요.

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

이 예시에서는 status.example.com이 첫 번째 행에 매칭되면 뒤의 접미사 규칙은 평가되지 않습니다. blocked.example.com은 REJECT에 매칭되고, 나머지 example.com 하위 도메인은 PROXY를 사용합니다. 그 밖의 요청은 GEOIP를 확인한 뒤 마지막으로 FINAL이 처리합니다. 요청이 PROXY에 매칭된 뒤 연결에 실패해도 다음 행의 DIRECT를 찾으러 내려가지 않습니다. 규칙 매칭과 연결 실행은 서로 다른 단계이며, 연결 결과가 이미 끝난 첫 매칭을 바꾸지는 않습니다.

FINAL에는 분명한 기본 정책을 지정해야 합니다

FINAL에는 매칭 필드가 필요하지 않습니다. FINAL,PROXY 또는 FINAL,DIRECT 형식으로 작성합니다. 앞선 규칙에 매칭되지 않은 요청을 처리하므로 [Rule]의 마지막에 배치하세요. FINAL 뒤에 있는 규칙은 남은 요청을 처리할 기회가 없습니다. 기본 정책을 정하기 전에 “별도로 지정하지 않은 대상은 어디로 보낼 것인가?”를 먼저 생각하세요. 복사한 파일에 특정 기본 정책이 있다는 이유만으로 그대로 유지하지 마세요. FINAL을 두 개 작성해도 주 경로와 예비 경로가 만들어지지 않으며 두 번째 항목은 장애 전환 기능이 아닙니다.

REJECT를 추가할 때는 범위를 가능한 한 구체적으로 정하고 별도로 테스트하세요. 한 페이지의 통계, 이미지, 인증, 서비스 API가 같은 도메인을 공유할 수 있으므로 범위를 넓게 거부하면 페이지는 열리지만 기능이 제대로 작동하지 않을 수 있습니다. 실제 거부가 필요한지, 정확한 도메인으로 표현할 수 있는지 먼저 판단한 뒤 관련 요청을 살펴보세요. 되돌릴 때는 직접 추가한 거부 규칙을 삭제하거나 비활성화하고 새 연결을 시작하세요. 앞에서 이미 매칭된 REJECT를 상쇄하려고 뒤에 DIRECT를 추가하지 마세요.

06 / HOST & URL REWRITE

Host 매핑과 URL Rewrite의 역할 구분

Host는 주소 매핑을 변경하며 정책을 직접 결정하지 않습니다

[Host]에는 도메인과 주소의 고정 매핑을 지정합니다. 예를 들면 lab.example.com = 192.168.1.20입니다. 이 설정은 “이 도메인이 어떤 주소를 받아야 하는가?”를 정하며 “요청을 프록시로 보낼 것인가, 직접 연결할 것인가?”를 정하지 않습니다. 이 매핑을 사용해도 도메인이나 대상 주소에 대한 [Rule]의 처리를 확인해야 합니다. 예시는 사용자가 관리하는 로컬 서비스의 설명용입니다. 해당 주소가 의도한 대상과 실제로 일치하는지 확인한 경우에만 사용하세요. 예시 주소를 실제 웹사이트 접속에 그대로 사용하지 마세요.

[Host]
lab.example.com = 192.168.1.20

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

고정 매핑을 사용하면 조회 결과가 고정되므로 대상 주소가 바뀔 때 함께 수정해야 합니다. 원래 서비스가 여러 주소를 사용해 부하를 분산하는 경우 하나의 주소로 고정하면 정상적인 분산 과정이 우회될 수 있습니다. 수정하기 전에 원래 DNS 조회 결과를 기록하고 도메인, 주소, 사용 목적이 모두 맞는지 확인하세요. 한 기기에서 성공한다고 해서 다른 네트워크에도 적합한 매핑이라는 뜻은 아닙니다. 예를 들어 로컬 주소는 해당 Wi-Fi를 벗어나면 접속할 수 없을 수 있습니다. 이 경우 같은 매핑을 반복해서 시도하기보다 네트워크 범위를 확인하세요.

매핑은 인증서와 서비스 신원을 대체하지 않습니다

도메인으로 HTTPS 서비스에 접속할 때 연결 대상 주소와 인증서에 포함된 도메인은 서로 다른 조건입니다. [Host]는 주소를 바꿀 뿐 서비스 인증서를 임의의 도메인에 맞게 바꾸거나 서버의 이름 설정을 수정하지 않습니다. 인증서 오류가 발생하면 해당 도메인에 맞는 인증서를 서비스가 제공하는지 확인하세요. 인증서 검증을 우회하는 방법으로 고정 매핑을 사용해서는 안 됩니다. 매핑을 되돌린 뒤 새 연결을 시작하면 원래 서비스의 문제인지 직접 추가한 주소 고정의 문제인지 구분하는 데 도움이 됩니다.

URL Rewrite는 정규식으로 대상을 지정합니다

[URL Rewrite]에는 URL 매칭 표현식과 그에 따른 처리 동작을 지정합니다. 아래 예시는 특정 경로를 다른 경로로 리디렉션하며 302는 임시 리디렉션 응답을 의미합니다. 이는 프록시 정책이 아니며 PROXY를 자동으로 DIRECT로 바꾸지도 않습니다. 예시의 example.com은 문법 설명용 문자열이지 외부 서비스의 접속 주소가 아닙니다. 사용하기 전에 현재 요청 환경에 해당 동작이 적합한지 확인하고, 도메인의 모든 경로를 대상으로 하는 넓은 표현식을 작성하기보다 구체적인 경로 하나부터 검증하세요.

[URL Rewrite]
^http://example\.com/legacy$ http://example.com/current 302

표현식의 ^는 시작 위치를, $는 끝 위치를 지정합니다. 도메인의 마침표는 \.처럼 백슬래시를 붙여 정규식에서 임의의 문자로 해석되지 않도록 합니다. 이 예시는 /legacy로 끝나고 추가 쿼리 매개변수가 없는 전체 주소에만 매칭됩니다. /legacy/ 또는 쿼리 매개변수가 붙은 요청은 같은 조건에 해당하지 않습니다. 경로나 매개변수를 유지해야 한다면 캡처 그룹과 치환의 관계를 먼저 이해한 뒤 확장하세요. .*를 무심코 사용해 모든 내용을 매칭 범위에 포함하지 마세요.

HTTPS 요청의 가시성 제한을 먼저 확인하세요

일반적인 HTTPS 연결에서는 전체 HTTP URL 경로가 그대로 드러나지 않습니다. 이런 요청에 경로 단위 재작성을 적용하려면 보통 추가적인 요청 복호화 조건과 인증서 신뢰 설정이 필요합니다. 파일에 [URL Rewrite]만 추가한다고 경로가 보이는 것은 아닙니다. 일부 앱에는 별도의 인증서 검사 기능도 있어 관련 설정을 활성화하면 호환성에 영향을 줄 수 있습니다. 필요한 이유가 분명하지 않다면 기본 연결 동작을 유지하세요. 도메인 분기를 위해 경로 재작성용 복호화 설정까지 추가할 필요는 없습니다.

리디렉션은 새로운 접속 대상을 만들며 새 요청에는 라우팅과 서비스 조건을 다시 적용해야 합니다. 다른 재작성 규칙이 대상을 원래 경로로 되돌리면 순환이 발생할 수 있습니다. 검증할 때는 원본 URL, 매칭된 표현식, 응답의 리디렉션 위치, 최종 대상을 기록하세요. 브라우저에 마지막으로 표시된 페이지만 확인해서는 충분하지 않습니다. 먼저 다른 재작성 규칙을 비활성화하고 하나씩 테스트한 뒤 차례로 복구하면 규칙 간 충돌과 대상 서비스 자체의 리디렉션을 구분할 수 있습니다. 계속 리디렉션된다면 정규식 범위를 넓히지 말고 재작성 규칙부터 되돌리세요.

07 / EDITING WORKFLOW

설정 수정 절차와 자주 쓰는 규칙 문법

현재 파일을 복사한 뒤 최소한으로 수정

수정하기 전에 현재 정상적으로 작동하는 설정을 보관하고, 원본 파일과 테스트 파일을 용도에 따라 구분할 수 있는 이름으로 저장하세요. 바꿀 대상, 매칭 범위, 기대하는 정책을 먼저 정리한 다음 Config에서 해당 파일을 열어 편집합니다. 저장 후 테스트 파일이 현재 사용 중인 설정인지 확인하고 Global Routing을 Config로 설정한 뒤 대상 요청을 새로 시작하세요. 서버, DNS, 기본 정책, 여러 규칙을 한꺼번에 바꾸면 결과가 달라졌을 때 원인을 특정하기 어렵습니다.

사용자가 보유한 서버 구독과 원격 설정 파일은 업데이트 경로가 다를 수 있습니다. 서버 목록 업데이트가 로컬 규칙까지 업데이트한다는 뜻은 아닙니다. 원격 설정을 다시 가져오면 해당 파일에 직접 적용한 변경 사항이 덮어써질 수도 있습니다. 원격 내용을 수정하기 전에 저장 및 업데이트 방식을 확인하고, 직접 작성한 규칙 의도는 복사본이나 별도 기록으로 보존하세요. 파일 이름만으로 직접 추가한 내용을 기억하려 하지 말고 각 규칙 그룹의 목적을 별도 주석으로 남기는 편이 좋습니다.

기본은 직접 연결, 지정 도메인만 프록시 사용

명시한 도메인만 프록시로 보내고 나머지는 직접 연결하려면 다음 구조를 사용할 수 있습니다. DOMAIN-SUFFIX는 예시의 기본 도메인과 하위 도메인을 포함하며 FINAL,DIRECT는 나머지 요청을 명시적으로 처리합니다. 대상을 추가하기 전에 기존 접미사 범위에 이미 포함되는지 확인하세요. 이미 포함된다면 같은 정책을 중복해서 추가할 필요가 없습니다. 서비스가 다른 도메인을 사용한다면 더 넓은 키워드로 추측해 덮기보다 실제 연결 기록을 확인해 추가하세요.

[General]
dns-server = system

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

기본은 프록시 사용, 특정 대상은 직접 연결 예외

반대로 별도로 지정하지 않은 요청은 프록시로 보내고 로컬 네트워크나 특정 도메인은 직접 연결 예외로 두는 방식도 있습니다. FINAL,PROXY를 사용하면 나머지 요청이 해당 연결 경로를 사용하므로 현재 서버가 정상적으로 작동하는지 먼저 확인해야 합니다. 주소 예외와 도메인 예외는 각각 구체적으로 지정하세요. 내부 도메인 하나 때문에 모든 사설 주소 외 범위를 넓히지 마세요. 일상 설정에 전역 우회가 이미 포함되어 있다면 관련 매개변수를 확인한 뒤 IP 대역 규칙이 중복으로 필요한지 판단하세요.

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

두 구조는 고정된 권장 설정이 아니라 서로 다른 기본 정책을 표현합니다. FINAL 두 개를 그대로 합쳐서는 안 됩니다. 먼저 최종 기본 정책을 정한 다음 필요한 구체적인 규칙을 그 앞에 배치해야 합니다. 도메인 하나만 바꾸려는 경우 설정 파일 전체의 기본 정책까지 함께 변경하지 마세요. 예외를 검증할 때는 해당 대상이 구체적인 규칙에 매칭되는지 확인하고, 별도로 지정하지 않은 대상이 FINAL을 따르는지도 확인해 서로 보완되는 두 가지 결과를 기록하세요.

파일을 합칠 때는 길이보다 충돌부터 정리

직접 보관한 여러 설정 파일에서 규칙을 정리할 때는 유형과 매칭 범위가 겹치는 항목부터 찾으세요. 조건이 완전히 같은데 정책이 다르면 현재 의도를 나타내는 항목을 결정해야 합니다. 정확한 도메인과 접미사 규칙이 겹친다면 올바른 예외 순서를 유지하고, 키워드와 접미사 규칙이 겹친다면 키워드의 범위가 지나치게 넓지 않은지 확인하세요. 규칙이 많다고 범위가 더 정확해지는 것은 아닙니다. 중복되거나 도달할 수 없는 항목은 확인 부담만 늘립니다. 정리한 뒤에도 FINAL은 하나로 명확하게 유지해야 합니다.

전체 파일을 로컬 예외, 서비스 도메인, 주소 범위, 기본 정책의 네 그룹으로 나누는 것은 사람이 확인하기 쉽게 정리하는 방법이지 반드시 따라야 하는 순서는 아닙니다. 그룹 사이에 주석으로 의도를 표시할 수 있지만 실제 우선순위는 행 위치에 따라 결정됩니다. 넓은 도메인 조건보다 주소 예외가 먼저 적용되어야 한다면 실제 요구에 맞게 위치를 조정하세요. 한 그룹을 정리할 때마다 같은 대상으로 다시 테스트하고 결과를 기록해야 전체 순서를 바꾼 뒤 기존 동작을 찾지 못하는 일을 줄일 수 있습니다.

가져오기 메뉴와 서버 필드의 조작 방법은 이 페이지에서 반복해서 설명하지 않습니다. 기존 항목을 다시 정리하려면 구독 가져오기 방법을, 프로토콜 필드를 확인하려면 프로토콜 및 매개변수 안내를 참고하세요. 인증 정보나 전송 매개변수 오류를 규칙 수정으로 해결하려 하지 마세요. 서로 다른 계층에서 발생하는 문제입니다.

08 / VERIFICATION

규칙 매칭 검증 및 문제 해결

테스트 한 번에 네 가지 사실 기록

규칙을 검증할 때는 대상 호스트 이름 또는 주소, 현재 Global Routing 모드, 매칭된 규칙 또는 정책, 최종 연결 결과를 최소한 기록하세요. 페이지가 열리는지는 마지막 항목일 뿐이며 앞서 확인해야 할 라우팅 근거를 대신하지 않습니다. 현재 연결이나 로그에서 대상과 정책을 확인할 때는 앱에 실제로 표시되는 정보를 기준으로 삼으세요. 요청에 따라 여러 도메인과 연결이 사용될 수 있습니다. 반복해서 요청을 보낼 수 있는 명확한 대상을 하나 정하고 새 기록을 추적해 백그라운드 요청을 테스트 대상으로 착각하지 않도록 하세요.

Connectivity Test는 연결 상태를 확인하는 기능이지만 특정 웹페이지의 모든 관련 요청이 예상한 규칙을 따르는지 증명하지는 않습니다. 서버에 연결할 수 있음을 확인한 뒤에도 실제 대상 요청을 보내 매칭 결과를 살펴봐야 합니다. 규칙을 수정해도 기존 연결이 유지될 수 있고 브라우저가 캐시된 내용을 표시할 수도 있습니다. 필요한 경우 다시 연결하고 새 세션을 시작하세요. 수정 전후를 비교할 때는 네트워크, 서버, 대상을 동일하게 유지하고 검증할 규칙 하나만 바꿔야 다른 조건의 변화가 결과에 영향을 주지 않습니다.

설정이 바뀌지 않으면 적용 경로부터 확인

수정 후 변화가 없다면 파일, 라우팅 모드, 규칙 순서의 세 가지를 확인하세요. 먼저 저장한 파일이 현재 사용하는 파일인지, 이름이 같은 다른 파일은 아닌지 확인합니다. 그런 다음 Global Routing이 Config인지 확인하고, 마지막으로 [Rule]의 맨 위부터 대상에 먼저 매칭되는 조건이 있는지 살펴보세요. 범위가 넓은 키워드, 큰 IP 대역, 앞쪽에 배치된 FINAL을 특히 확인해야 합니다. 새로 추가한 행의 문법이 맞더라도 앞선 규칙을 건너뛰지 마세요. 첫 번째 매칭이 전체 순서 목록의 결과를 결정합니다.

규칙 매칭 성공이 연결 성공을 보장하지 않습니다

기록에 예상한 정책이 표시된다면 이제 실제 연결 경로를 확인해야 합니다. PROXY 연결에 실패하면 Home에서 선택한 서버가 여전히 유효한지, 인증 필드와 포트, 전송 조건이 보유한 정보와 일치하는지 살펴보세요. DIRECT 연결에 실패하면 현재 네트워크에서 대상에 직접 접속할 수 있는지 확인합니다. REJECT가 표시된다면 요청을 거부하는 것이 원래 의도였는지 점검하세요. 명확한 연결 실패를 계속 규칙 우선순위 문제로 다루지 마세요. 필요하면 Proxy와 Direct를 잠깐 비교한 뒤 Config로 되돌려 다시 테스트하세요.

일부 기능만 실패한다면 페이지의 기본 요청과 후속 API 요청을 구분하세요. 로그인, 파일 업로드, 이미지 로드, 지속 연결은 서로 다른 도메인이나 연결 방식을 사용할 수 있습니다. 페이지 하나가 열려도 관련 요청이 모두 성공한 것은 아닙니다. 핵심 API 요청에 REJECT가 적용됐는지 먼저 확인한 다음 관련 요청이 예상과 다른 FINAL에 매칭되는지 살펴보세요. 특정 전송 방식만 실패한다면 서버와 프로토콜 지원 여부를 다시 확인해야 합니다. 전송 계층 문제를 도메인 매칭 범위를 넓혀 해결하려 하지 마세요.

최소 설정으로 원인을 찾은 뒤 전체 파일 복구

최소 설정에는 필요한 [General], 대상 규칙 하나, FINAL 하나만 남기고 직접 추가한 Host, 재작성 규칙, 범위가 넓은 키워드는 잠시 제거합니다. 이는 기본 매칭이 예상대로 작동하는지 확인하기 위한 방법이지 기존 설정을 영구히 버리라는 뜻은 아닙니다. 최소 설정에서 정상 작동하면 기존 내용을 그룹별로 복구하면서 차이가 생기는 지점을 찾으세요. 그래도 실패한다면 대상 이름, DNS 조회 결과, 서버 경로를 먼저 확인합니다. 매번 한 그룹씩 복구해야 전체 파일에 문제가 있다는 사실만 아는 데서 그치지 않고 구체적인 원인을 찾을 수 있습니다.

설정을 되돌릴 때는 파일 내용과 테스트 모드를 함께 복구하고 새 연결을 시작하세요. 문제를 기록할 때 대상, 네트워크 유형, 규칙 예시, 오류 내용을 적을 수 있지만 구독 링크의 인증 매개변수, 서버 비밀번호 등 민감한 정보는 삭제해야 합니다. 실제 인증 정보를 문제 기록에 그대로 붙여 넣으면 제한적인 연결 문제에 정보 노출 위험까지 더해집니다. 구조 설명에 필요한 예시만 남겨도 규칙 순서, 섹션 위치, 필드 개수에 대해 충분히 논의할 수 있습니다.

첫 연결 및 VPN 설정 권한 문제는 시작하기를 참고하세요. 구매, 구입 항목 복원, 시스템 요구 사항은 구입 항목 복원 안내에서 확인할 수 있습니다. 시스템 요구 사항은 App Store 페이지 표기를 기준으로 합니다. 증상별 비교는 문제 해결을 참고하세요. 이 페이지는 설정 동작을 설명하며 앱 구매, 서버 연결, 규칙 매칭을 하나의 문제 유형으로 혼동하지 않도록 안내합니다.