Shadowrocket
규칙 및 설정 종합 가이드

01 설정 파일 구조와 적용 범위

설정 파일은 먼저 올바르게 읽혀야 하며, 규칙이 예상대로 작동하는지는 그다음에 확인할 수 있습니다. Shadowrocket 설정 파일은 일반적으로 섹션별로 구성됩니다. 대괄호 안의 이름은 섹션을 나타내며, 섹션 아래의 내용은 해당 섹션의 문법에 따라 해석됩니다. 같은 문장이라도 섹션에 따라 의미가 달라질 수 있습니다. 예시를 확인하거나 복사할 때는 섹션 이름, 행의 내용, 대상 정책을 함께 확인하세요. 중간의 키워드 몇 개만 발췌해서는 안 됩니다.

General, Rule, Host의 역할

[General]에는 해석 및 우회와 관련된 옵션 등 일반 설정을 저장합니다. [Rule]에는 연결 경로를 결정하는 규칙을 저장하고, [Host]에는 지정된 호스트 이름의 정적 해석 매핑을 저장합니다. 각각 기본 처리 조건, 대상에 적용할 정책, 이름에 대응하는 주소를 지정합니다. 역할이 서로 다르므로 한 섹션을 수정해도 다른 섹션의 결과가 바뀌지 않을 수 있습니다.

최소 구성으로 문법 이해하기

아래 예시는 구조를 설명하기 위한 것으로, 모든 네트워크에서 사용할 수 있는 완성된 설정이 아닙니다. 예시 도메인과 문서 주소는 실제로 이용 가능한 서비스를 나타내지 않습니다. 실제로 사용할 때는 현재 설정에서 필요한 항목을 유지하고, 기존 서버를 사용할 수 있는지 확인하세요. PROXY는 정책일 뿐, 파일에 적는다고 서버가 자동으로 생기지 않습니다. 마찬가지로 도메인 규칙을 추가해도 해당 도메인의 해석이나 서비스 상태가 자동으로 수정되지는 않습니다.

[General]
dns-server = system

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

[Host]
test.example.com = 192.0.2.10

섹션 제목에는 영문 대괄호를, 규칙 필드 구분에는 영문 쉼표를 사용하고, 일반 옵션에서는 등호로 이름과 값을 연결합니다. 입력기에서 생성된 전각 쉼표, 휘어진 따옴표, 보이지 않는 공백 때문에 겉보기에는 같은 문장도 예상대로 해석되지 않을 수 있습니다. 복사한 뒤 편집기에서 한 줄씩 확인하고, 특히 행 끝에 설명 문구가 붙어 있지 않은지 살펴보세요. 설명은 본문이나 별도의 주석 행에 작성하고 정책 필드 뒤에 바로 덧붙이지 마세요.

파일이 있다고 현재 사용 중인 것은 아닙니다

Config로 이동해 현재 선택된 설정 파일을 확인한 다음 편집하세요. 선택되지 않은 파일을 저장해도 현재 실행 중인 설정이 자동으로 바뀌지는 않습니다. 마찬가지로 기존 구독을 업데이트하면 일반적으로 서버 목록이 변경될 뿐, 규칙 파일도 함께 업데이트되었다고 볼 수는 없습니다. 서버 출처, 설정 출처, 현재 선택 상태를 각각 확인해 서로 다른 대상을 반복해서 수정하지 않도록 하세요.

시작하기 전에 로컬 사본을 보관하고 기존 파일 이름을 기록하세요. 현재 설정이 업데이트 가능한 주소에서 제공되는 경우 원격 원본과 로컬 수정 내용을 구분해야 합니다. 나중에 내용을 다시 가져오면 로컬 변경 사항을 다시 확인해야 할 수 있습니다. ‘저장됨’이 ‘검증 완료’를 의미하지는 않습니다. 저장은 텍스트 기록이 완료되었다는 뜻일 뿐입니다. 실제 적용 여부는 Global Routing, 연결 상태, 실제 매칭된 규칙을 함께 확인해야 합니다.

파일을 읽는 중 오류가 발생하면 최근에 수정한 섹션부터 확인한 다음, 섹션 이름을 중복해서 붙여 넣었거나 규칙을 잘못된 위치에 작성했는지 살펴보세요. 파일은 열리지만 연결 결과가 예상과 다르면 모드, 정책, 매칭 순서를 확인해야 합니다. 문법 오류와 실행 결과 문제를 따로 처리하면 쉼표 오류를 수정하려다 해석 설정, 서버, 전체 규칙까지 동시에 바꾸는 일을 막고 원인을 명확히 파악할 수 있습니다.

03 DOMAIN 계열 도메인 규칙

대상 도메인을 알고 있다면 도메인 규칙부터 확인하세요. 도메인 규칙은 호스트 이름을 기준으로 하며 브라우저 주소창의 전체 URL을 대상으로 하지 않습니다. api.example.com을 입력할 때는 프로토콜 접두사, 경로, 쿼리 매개변수, 페이지 제목을 붙이지 마세요. URL에서 호스트 이름 다음에 오는 슬래시와 그 뒤의 내용은 별도의 정보이므로 DOMAIN 매칭 필드에 그대로 사용할 수 없습니다.

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

DOMAIN은 완전한 도메인 이름을 매칭합니다. example.com을 지정해도 www.example.com까지 함께 지정되는 것은 아닙니다. DOMAIN-SUFFIX는 도메인과 그 하위 도메인까지 포함할 때 적합합니다. 조건으로 example.com을 지정하면 해당 도메인 자체와 그 하위 도메인 범위에 적용할 수 있습니다. 두 규칙의 차이에 따라 하나의 진입점에만 적용할지, 같은 도메인 아래의 여러 서비스에 적용할지가 결정됩니다.

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

접미사 규칙을 선택하기 전에 도메인의 경계를 확인하세요. 임의의 문자열 끝부분과 비교하는 규칙이 아니며, 비슷한 글자가 들어 있다고 매칭되는 것도 아닙니다. 겉보기에 비슷한 이름도 같은 도메인에 속하지 않을 수 있습니다. 문제를 확인할 때는 로그의 전체 호스트 이름과 규칙 필드를 한 글자씩 비교하세요. 특히 하위 도메인이 추가되었는지, 최상위 도메인이 다른지, 앱 전환 후 다른 서비스 도메인을 사용하는지 살펴보세요.

DOMAIN-KEYWORD는 더 넓은 범위에 적용됩니다

DOMAIN-KEYWORD는 도메인에 포함된 키워드로 매칭하며, 문자열 기준의 범위가 필요한 경우에 사용할 수 있습니다. 브랜드나 서비스 소속, 용도까지 판별하지는 않으므로 같은 문자가 서로 관련 없는 도메인에 함께 들어 있을 수 있습니다. 키워드가 짧을수록 의도하지 않은 매칭 범위를 예측하기 어렵습니다. 완전한 도메인을 지정할 수 있다면 넓은 키워드보다 정확한 규칙이 이해하기 쉽고 나중에 확인하기도 편합니다.

[Rule]
DOMAIN,ads.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,tracking,REJECT
FINAL,PROXY

이 예시는 범위가 명확한 예외를 넓은 규칙보다 앞에 둡니다. ads.example.com에 접속하면 정확한 거부 규칙이 먼저 매칭되고, 같은 도메인의 다른 호스트에는 뒤의 접미사 규칙이 프록시를 선택합니다. 키워드 규칙은 뒤에 있으므로 이미 매칭된 연결을 다시 처리하지 않습니다. 예시는 순서를 설명하기 위한 것이며 일반적인 차단 목록으로 바로 사용할 수 없습니다. 실제 거부 범위는 사용자가 직접 지정한 대상과 로그 기록을 기준으로 정해야 합니다.

웹페이지에는 여러 도메인이 사용될 수 있습니다

페이지 본문, 이미지, 스크립트, 로그인 API, 미디어 콘텐츠가 서로 다른 호스트에서 제공될 수 있습니다. 주소창에 표시되는 도메인에만 정책을 설정해도 모든 리소스가 같은 경로를 사용한다고 보장할 수 없습니다. ‘첫 화면은 열리지만 이미지가 표시되지 않음’ 문제가 생기면 실패한 리소스가 실제로 요청한 호스트 이름을 확인하세요. 모든 접미사 규칙에 같은 정책을 즉시 적용하지 마세요. 범위를 점진적으로 넓히면 정상 작동 중인 다른 서비스에 미치는 영향을 줄일 수 있습니다.

도메인 규칙이 적용되려면 연결 처리 중 해당 이름을 확인할 수 있어야 합니다. 앱이 숫자 주소로 직접 연결하거나 그 시점에 이름과 주소의 연관 정보를 확인할 수 없다면, 사용자가 해당 주소가 어떤 웹사이트의 것인지 알고 있다는 이유만으로 도메인 규칙이 반드시 매칭된다고 볼 수는 없습니다. 이때는 연결 기록에 표시된 대상 유형을 확인한 다음 주소 규칙을 추가할지 결정하세요. 요청 하나를 해결하려고 식별되지 않은 연결을 모두 직접 연결하도록 변경하지 마세요.

도메인 조건을 수정한 뒤에는 새 요청을 시작하세요. 브라우저와 앱은 기존 연결을 재사용할 수 있어 새 규칙이 같은 세션을 처리하지 못할 수 있습니다. 관련 페이지를 닫았다 다시 열고, 필요한 경우 연결을 새로 설정한 다음 새로 생성된 기록을 확인하세요. 판단 기준은 새 요청의 대상과 매칭 결과이지, 이전에 로드한 콘텐츠가 페이지에 남아 있는지가 아닙니다. 캐시된 페이지로는 네트워크 요청에 어떤 규칙이 적용되었는지 알 수 없습니다.

규칙을 관리할 때는 각 그룹에 ‘완전한 도메인 예외’나 ‘전체 서비스 도메인’처럼 간단한 용도 설명을 남겨 두세요. 도메인이 작동하지 않으면 규칙을 삭제하기 전에 서비스가 다른 호스트를 사용하게 되었는지 확인하세요. 용도 기록 없이 규칙을 오래 쌓으면 같은 도메인이 서로 다른 정책으로 중복 지정되기 쉽습니다. 이런 충돌은 순서에 따라 결정되며 자동으로 합쳐지지 않습니다.

05 매칭 순서, USER-AGENT 및 FINAL

일반적인 [Rule] 목록에서는 설정에 적힌 순서대로 규칙을 확인하고, 연결이 매칭되면 해당 정책을 적용합니다. 이를 ‘가장 구체적으로 작성된 규칙을 자동으로 선택한다’고 이해하면 안 됩니다. 구체적인 조건도 적절한 위치에 있어야 매칭될 수 있습니다. 앞의 넓은 조건이 대상을 먼저 포함하면 뒤의 정확한 조건은 결과를 바꿀 수 없습니다. 설정을 정리할 때는 조건뿐만 아니라 순서도 중요합니다.

예외를 먼저, 넓은 범위는 나중에

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

이 예시에서는 로그인 도메인을 먼저 직접 연결로 설정하고, 같은 도메인의 다른 호스트는 접미사 규칙으로 프록시를 사용합니다. 키워드 규칙은 앞에서 아직 처리되지 않았고 도메인에 해당 문자가 포함된 대상만 처리합니다. 접미사 규칙을 첫 번째 행으로 옮기면 로그인 도메인도 먼저 프록시에 매칭됩니다. 로그인 도메인의 규칙이 더 길거나 구체적으로 보인다고 파일이 자동으로 우선순위를 높여 주지는 않습니다.

중복 규칙도 순서에 따라 이해해야 합니다. 같은 도메인에 DIRECT를 먼저 쓰고 PROXY를 나중에 쓴다고 두 경로가 선택지로 함께 유지되는 것은 아닙니다. 조건에 먼저 부합한 규칙이 결과를 결정합니다. 충돌을 확인할 때는 완전히 같은 행만 검색하지 말고 해당 도메인을 포함할 수 있는 접미사, 키워드, 기타 넓은 조건도 찾아보세요. 겉보기에 다른 문장도 같은 요청에 적용될 수 있습니다.

USER-AGENT는 요청 정보가 확인되어야 합니다

USER-AGENT는 요청의 User-Agent 정보를 조건으로 사용합니다. 앱 이름을 감지하는 기능이 아니므로 규칙에 특정 앱 이름을 적는 것만으로 해당 앱의 모든 연결을 식별할 수는 없습니다. 처리 시점에 관련 요청 정보를 확인할 수 있어야 이 규칙을 적용할 수 있습니다. 암호화된 연결에서는 모든 요청 헤더가 기본적으로 보인다고 가정하지 마세요. 이 규칙 하나만으로 모든 연결을 처리하려고 해서는 안 됩니다.

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

예시의 클라이언트 식별자는 매칭 형식을 설명하기 위한 것이며 실제 앱을 가리키지 않습니다. 사용할 때는 확인할 수 있는 요청 정보에서 실제 필드를 찾고 매칭 결과를 확인하세요. 같은 앱의 여러 구성 요소가 서로 다른 식별자를 사용하거나 시스템 서비스가 대신 요청을 보낼 수도 있습니다. 대상을 도메인으로 명확히 지정할 수 있다면 추측한 요청 헤더보다 설명하기 쉬운 도메인 조건을 유지하는 편이 좋습니다.

FINAL은 마지막 기본 처리만 담당합니다

FINAL은 앞의 규칙이 하나도 매칭되지 않을 때 정책을 선택하며 일반적으로 목록 맨 끝에 둡니다. 우선순위를 높이는 표시도 아니고 잘못된 규칙을 수정하는 스위치도 아닙니다. 규칙 목록 앞쪽에 배치하면 뒤의 규칙이 매칭될 기회를 잃을 수 있습니다. FINAL,PROXY와 FINAL,DIRECT 중 무엇을 사용할지는 분류되지 않은 연결의 경로를 어떻게 할지에 따라 결정하세요. 다른 설정 파일의 관행을 그대로 복사하지 마세요.

프록시를 기본 처리로 선택하면 명확히 분류되지 않은 요청은 기존 프록시 경로에 의존합니다. 직접 연결을 기본 처리로 선택하면 아직 규칙에 포함되지 않은 서비스가 현재 네트워크를 통해 직접 연결을 시도합니다. 두 방식 모두 실제로 확인해야 합니다. 무엇보다 결과를 설명할 수 있어야 합니다. 대상이 최종 규칙에 매칭된 것은 앞의 조건이 대상을 포함하지 않았다는 뜻인 경우가 많으며, 최종 규칙이 원래 매칭되어야 할 연결을 ‘가로챘다’는 의미는 아닙니다. 대상 이름과 주소, 규칙 범위를 확인하세요.

설정을 병합할 때는 먼저 유지할 최종 규칙을 정한 다음 구체적인 조건을 그 앞에 배치하세요. 완성된 파일 두 개를 그대로 이어 붙이면 섹션이 중복되고 규칙이 반복되거나 기본 처리 규칙이 너무 앞에 놓이는 경우가 많습니다. 사용할 수 있는 파일 하나를 기준으로 삼고 용도별 규칙을 그룹으로 옮긴 뒤, 각 그룹을 추가할 때마다 대상의 매칭 결과를 확인하세요. 이렇게 하면 문제가 생겨도 수백 줄을 처음부터 추측하는 대신 가장 최근에 추가한 범위를 살펴볼 수 있습니다.

07 URL Rewrite 적용 범위와 한계

[URL Rewrite]는 URL 조건에 따라 처리하며, 연결 정책에 따라 트래픽을 분기하는 [Rule]과는 다릅니다. 전자는 확인할 수 있는 URL 정보와 그에 따른 처리 동작을 다루고, 후자는 연결이 어떤 경로를 이용할지 결정합니다. 특정 도메인을 프록시로 보내려면 먼저 도메인 규칙을 검토하세요. 명확한 기존 페이지 주소를 새 주소로 이동하려는 경우에만 재작성 조건과 동작을 살펴보면 됩니다.

전체 대상을 정한 다음 정규식 범위를 좁히세요

재작성 규칙은 일반적으로 매칭 표현식, 대상, 처리 방식으로 구성됩니다. 아래 예시는 정확한 기존 주소를 임시 리디렉션 방식으로 새 주소에 연결하는 방법을 보여 줍니다. 문법과 매칭 범위를 설명하는 예시일 뿐, 사용자가 실제로 예시 도메인에 접속할 필요는 없습니다. 실제로 수정한 뒤에는 현재 앱에서 해당 행이 올바르게 받아들여지는지 확인하고 새 요청을 보내 결과를 검증하세요. 파일이 저장되는지만 확인해서는 안 됩니다.

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

표현식 시작의 ^는 시작 위치를, 끝의 $는 종료 위치를 제한합니다. 도메인의 마침표는 \.로 작성해 문자 그대로의 마침표를 나타냅니다. 이스케이프하지 않으면 정규식에서 마침표는 일반적으로 임의의 문자 하나를 의미하므로 원하지 않는 주소까지 포함될 수 있습니다. 긴 표현식에서 몇 글자를 지우거나 바꾸기보다 각 기호의 의미를 이해한 뒤 수정하는 편이 범위를 관리하기 쉽습니다.

이 예시는 하위 도메인, 추가 경로, 쿼리 매개변수를 포함하지 않습니다. 주소 끝에 물음표와 매개변수가 추가되면 정확한 종료 조건이 예상대로 매칭되지 않을 수 있습니다. 매개변수를 처리해야 한다면 먼저 매개변수를 유지할지, 삭제할지, 재구성할지 정한 뒤 그에 맞게 표현식을 설계하세요. 모든 내용을 포함하는 넓은 조건을 바로 추가하지 마세요. 로그인 콜백, 리소스 경로, 이후 페이지까지 함께 매칭될 수 있습니다.

리디렉션과 연결 정책은 따로 확인하세요

리디렉션이 발생하면 요청은 새 대상을 계속 방문합니다. 새 대상도 이름을 해석해야 하며 해당 라우팅 조건에 따라 연결을 설정해야 합니다. 기존 주소의 도메인이 직접 연결을 사용해도 리디렉션된 다른 도메인이 직접 연결을 사용한다는 뜻은 아닙니다. 문제를 확인할 때는 처음 주소와 최종 주소를 모두 기록하세요. 첫 번째 요청만 보면 정책이 적용되지 않은 것처럼 보이지만 실제로는 다음 대상에서 실패했을 수 있습니다.

URL Rewrite로 서버 인증 오류, 누락된 프로토콜 필드, 연결할 수 없는 DNS 서비스를 해결하려고 하지 마세요. 이런 문제는 서로 다른 계층에서 발생하므로 URL 문자열을 바꿔도 하위 계층의 매개변수가 보완되지는 않습니다. 연결이 설정되기 전에 시간 초과가 발생한다면 서버, 해석, 정책을 먼저 확인하세요. 요청이 처리 가능한 단계에 진입한 것을 확인한 다음 정규식과 리디렉션 동작을 살펴보면 됩니다.

HTTPS 정보의 표시 여부는 별도로 이해해야 합니다

HTTPS의 전체 경로와 요청 헤더는 암호화된 연결 안에 있으므로 재작성 규칙을 추가하는 것만으로 모든 내용을 읽고 수정할 수 있다고 가정해서는 안 됩니다. 구체적인 규칙을 적용할 수 있는지는 프로토콜, 앱 동작, 관련 설정 조건에 따라 달라집니다. 인증서 신뢰 설정은 보안 경계를 바꾸므로 규칙을 적용하기 위한 기본 절차로 취급하면 안 됩니다. 일반적인 도메인 트래픽 분기는 암호화된 내용을 읽지 않아도 할 수 있습니다.

재작성 규칙이 적용되지 않으면 표현식이 실제 주소를 포함하지 않는지, 요청이 기존 연결을 재사용하는지, 결과가 캐시에서 온 것인지 먼저 확인하세요. 처리 범위를 바로 넓히거나 모든 도메인을 추가 처리가 필요한 그룹에 넣지 마세요. 용도를 확인할 수 없는 인증서나 설정을 발견했다면 수정을 멈추고 기존에 작동하던 상태를 보존한 뒤 출처와 필요성을 하나씩 확인하세요. 규칙 범위가 넓을수록 검증에 드는 비용과 영향 범위도 커집니다.

리디렉션 루프도 방지해야 합니다. 새 주소가 기존 매칭 조건에 다시 들어가면 같은 동작이 반복될 수 있습니다. 테스트 중 주소가 계속 바뀌는지, 페이지에 리디렉션 횟수 초과가 표시되는지, 로그에 같은 대상이 반복되는지 확인하세요. 해결하려면 기존 주소 조건을 명확히 하고 새 대상이 같은 조건에 매칭되지 않도록 해야 합니다. 프록시 서버를 바꿔서 반복 동작을 숨기려 하지 마세요.

설정을 관리할 때는 연결 규칙과 URL 처리 규칙을 각각 그룹으로 기록하세요. 재작성 규칙을 삭제하거나 비활성화한 뒤 기본 접속이 복구된다면 해당 구간에서 문제 범위를 더 좁히고, 전체 트래픽 분기 설정을 곧바로 바꾸지 마세요. 도메인 기준으로 경로만 선택하면 되는 경우에는 재작성 섹션을 비워 두거나 추가하지 않아도 됩니다. 설정이 완전한지는 실제 요구 사항을 충족하는지로 판단해야 하며, 사용 가능한 기능을 모두 파일에 넣었는지로 판단하지 않습니다.