Shadowrocket
규칙 및 설정 참고

하나의 파일, 각 섹션의 역할은 다릅니다

Shadowrocket 설정 파일에는 연결 처리 옵션, 분기 조건, 도메인 매핑, 요청 재작성 규칙을 함께 넣을 수 있습니다. 대괄호로 표시된 섹션 이름이 각 항목의 역할을 구분합니다. [General]에는 일반 처리 옵션, [Rule]에는 순서대로 확인하는 규칙, [Host]에는 명시적 도메인 매핑, [URL Rewrite]에는 조건에 맞는 URL 처리 규칙을 저장합니다. 섹션 이름은 장식용 제목이 아닙니다. 내용을 잘못된 섹션에 넣으면 예상대로 해석되지 않을 수 있습니다. 처음 보는 파일을 읽을 때는 해당 섹션부터 찾고, 각 항목을 차례로 살펴보세요. 도메인을 먼저 검색해 내용을 그대로 붙여 넣는 방식은 피해야 합니다.

서버 정보와 분기 규칙도 서로 다른 항목입니다. 서버 정보는 연결 대상, 프로토콜, 인증 매개변수를 설명하고, 규칙은 요청에 적용할 정책을 지정합니다. DOMAIN-SUFFIX,example.com,PROXY 한 줄만으로 사용할 수 있는 서버가 만들어지지는 않습니다. 구독을 성공적으로 가져왔더라도 지정한 규칙 파일이 활성화됐다는 뜻은 아닙니다. 이 페이지의 설명은 사용자가 이미 자신의 구독이나 서버 정보를 보유하고 있다는 전제에서 작성했습니다. 예시 도메인과 주소는 매칭 범위를 설명하기 위한 것이며, 연결 리소스를 제공하지 않습니다.

먼저 복사본을 저장한 뒤 한 항목씩 수정

Config에서 현재 선택된 파일을 확인하고 이름을 기록한 다음, 원본 내용을 별도 복사본으로 보관하세요. 편집하기 전에 파일이 원격 주소에서 가져온 것인지, 이후 업데이트 시 전체 내용이 다시 다운로드되는지 확인합니다. 원격 설정 파일과 서버 구독은 모두 링크 형태로 보일 수 있지만, 업데이트되는 대상은 다를 수 있습니다. 실제 가져오기 경로와 내용을 기준으로 구분하세요. 업데이트 방식을 이해하기 전에 원격 파일을 영구적인 로컬 메모처럼 편집하지 마세요. 다음 업데이트에서 직접 추가한 규칙이 덮어써질 수 있습니다.

수정할 때는 기존 섹션 이름을 유지하고 대상 섹션에만 내용을 추가하세요. 먼저 범위가 명확한 DOMAIN 규칙 하나를 추가하고 저장·활성화한 다음 테스트 연결을 새로 설정하는 것이 좋습니다. 결과를 확인한 뒤 DOMAIN-SUFFIX로 범위를 넓히세요. 편집기에 저장 완료가 표시되더라도 텍스트가 기록됐다는 뜻일 뿐, 모든 키워드와 매개변수, 정책이 유효하다는 보장은 없습니다. 파싱 안내가 표시되면 안내된 문제부터 해결하세요. 오류를 가리려고 규칙을 계속 추가하지 마세요.

[General]
dns-server = system

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

[Host]
lab.example.com = 192.168.10.20

이 조각은 설정 파일의 기본 구조를 보여주는 예시이지, 완전한 연결 설정이 아닙니다. 시스템 DNS를 사용하고, 지정한 전체 도메인은 DIRECT로, example.com과 하위 도메인은 PROXY로, 나머지 요청은 DIRECT로 보냅니다. 실험용 도메인 하나에는 고정 주소도 지정합니다. 실제 접속 가능 여부는 선택한 서버, 네트워크 연결 상태, 주소가 사용자 환경에 맞는지, 관련 서비스가 실행 중인지에 따라 달라집니다. 실험용 주소 매핑을 그대로 운영 환경에 적용하지 마세요.

문법이 유효한지와 용도에 맞는지 구분하기

문법상 문제가 없는 한 줄이라도 네트워크 사용 목적에는 맞지 않을 수 있습니다. 예를 들어 FINAL,DIRECT와 FINAL,PROXY는 모두 유효한 기본 처리 방식을 나타내지만, 어느 규칙에도 매칭되지 않은 요청을 서로 다른 방향으로 처리합니다. 설정을 검토할 때는 오류가 없는지만 보지 말고, 어떤 요청이 이 규칙에 해당하는지, 지정된 정책을 사용할 수 있는지, 실패했을 때 복구할 수 있는지도 확인하세요. 수정할 때마다 예상 입력과 결과를 기록하고 수정 전후의 차이를 보관하는 것이 좋습니다.

파일에 같은 섹션이 여러 번 나오거나 설정이 서로 충돌한다면 문제를 찾기 전에 구조부터 정리하세요. 중복 항목은 “마지막 항목이 항상 적용된다” 같은 검증되지 않은 가정에 기대지 마세요. 같은 용도의 규칙은 알아보기 쉽게 모으고, 중복 매핑을 줄이며, 이유를 알 수 있는 기록을 남기면 조건을 계속 늘리는 것보다 관리하기 쉽습니다.

DOMAIN: 전체 도메인 하나만 지정

DOMAIN의 매칭 값은 도메인이며 전체 URL이 아닙니다. DOMAIN,api.example.com,PROXY는 api.example.com에 적용됩니다. 페이지 경로에 같은 문자열이 있다는 이유로 다른 사이트에 매칭되지 않으며, www.example.com에 자동 적용되지도 않습니다. 입력할 때 https://, 경로, 쿼리 매개변수, 끝의 포트 번호를 넣지 마세요. 같은 도메인에서 경로별로 구분하려는 경우 도메인 규칙은 적합한 방법이 아닙니다. 먼저 앱에서 해당 요청 정보를 실제로 확인할 수 있는지 살펴보세요.

전체 도메인 규칙은 범위를 좁힌 예외를 설정할 때 유용합니다. 기본 사이트와 다른 하위 도메인은 프록시로 보내되 내부 인터페이스 하나는 직접 연결해야 한다면, 해당 인터페이스의 DOMAIN 규칙을 넓은 후위 도메인 규칙보다 앞에 두세요. 이렇게 하면 예외를 먼저 적용한다는 점을 설정에서 명확히 확인할 수 있습니다. 전체 도메인 규칙이 클라이언트에서 자동으로 더 높은 우선순위를 얻는 것은 아닙니다. 먼저 확인되기 때문에 적용되는 것이며, 두 줄의 순서를 바꾸면 뒤에 있는 예외가 실행되지 않을 수 있습니다.

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

DOMAIN-SUFFIX: 후위 도메인과 하위 도메인

DOMAIN-SUFFIX,example.com,PROXY는 example.com 자체와 api.example.com, img.cdn.example.com 같은 하위 도메인에 적용됩니다. 후위 도메인은 도메인 경계를 기준으로 판단하며 임의의 문자열 포함 여부를 확인하지 않습니다. 따라서 notexample.com은 example.com의 하위 도메인이 아닙니다. 일반적으로 기본 도메인을 그대로 입력하면 되며 *.example.com처럼 적을 필요가 없습니다. 와일드카드 표기법을 후위 도메인 값에 섞으면 오히려 혼란이 생길 수 있습니다.

후위 조건은 같은 도메인 트리를 관리할 때 적합하지만, 같은 서비스가 항상 하나의 도메인 트리만 사용하는 것은 아닙니다. 페이지가 별도의 로그인 도메인, 정적 리소스 도메인, API 도메인을 함께 사용할 수 있으므로 기본 사이트 규칙이 매칭된 뒤에도 이미지나 로그인 요청은 다른 방향으로 처리될 수 있습니다. 실제 요청을 관찰하고 필요한 도메인의 용도를 하나씩 확인하세요. 규칙 범위를 공개 후위 도메인 전체로 넓히지 마세요. 공유 호스팅 도메인에 특히 주의해야 합니다. 범위가 지나치게 넓으면 관련 없는 서비스에도 영향을 줍니다.

DOMAIN-KEYWORD: 더 넓은 포함 조건

DOMAIN-KEYWORD는 도메인에 지정한 키워드가 포함되어 있는지 확인합니다. DOMAIN-KEYWORD,example,PROXY는 example.com 후위 조건보다 범위가 넓어 이름에 example이 들어간 다른 도메인에도 매칭될 수 있습니다. 해당 도메인들이 같은 운영 주체에 속하는지는 판단하지 않으며, 기본 도메인 부분만 검색하지도 않습니다. 이렇게 넓은 포함 조건이 필요한 이유가 분명하고 추가 매칭을 감수할 수 있을 때만 사용하세요.

대상이 api.example.com과 download.example.com뿐이라면 짧게 쓰려고 무리하게 키워드 조건을 사용하지 말고 전체 도메인이나 후위 조건을 우선 고려하세요. 한 글자나 흔한 약어는 검토하기 어렵고, 설정을 수정하지 않아도 나중에 추가된 사이트가 의도치 않게 포함될 수 있습니다. 키워드 규칙은 확인하기 쉬운 위치에 두고, 매칭되어야 하는 사례와 매칭되지 않아야 하는 사례를 몇 가지씩 테스트하세요.

도메인 확인 가능 여부와 입력값 정리

도메인 조건을 적용하려면 처리 과정에서 요청과 도메인을 연결할 수 있어야 합니다. 앱이 IP 주소에 직접 연결하거나 매칭에 쓸 이름이 요청 정보에 남아 있지 않다면 도메인 규칙이 예상대로 작동하지 않을 수 있습니다. 이때는 IP를 DOMAIN에 넣지 말고 대상 주소와 로그를 확인하세요. 국제화 도메인의 경우 설정에 사용하는 형식이 실제 인식된 이름과 일치해야 합니다. 복사할 때 전각 쉼표, 보이지 않는 공백, URL 인코딩 문자가 섞이지 않았는지 확인하세요.

규칙을 일괄 정리할 때는 중복 항목을 먼저 제거하고, 앞쪽의 넓은 조건이 뒤쪽의 구체적인 조건을 덮는지 확인하세요. 같은 도메인에 서로 다른 정책을 적용하는 중복 규칙을 두더라도 자동으로 선택되지는 않습니다. 결과는 여전히 위치에 따라 결정됩니다. 기본적인 범위 예시는 DOMAIN, GEOIP, FINAL 규칙 입문에서 확인할 수 있습니다. 이 페이지로 돌아와 규칙 범위와 전체 설정의 순서를 함께 검토하세요.

PROXY, DIRECT, REJECT의 차이

PROXY는 요청을 프록시 방향으로 처리한다는 뜻이며, 실제 연결은 현재 선택과 설정에 참조된 유효한 서버에 따라 달라집니다. DIRECT는 대상에 직접 연결한다는 의미입니다. “먼저 프록시를 시도하고 실패하면 직접 연결”하는 방식이 아닙니다. REJECT는 매칭된 요청을 거부하며 성능을 높이는 스위치가 아닙니다. 세 가지는 서로 다른 목적을 위한 것이므로 요청이 실패했다고 무작정 바꾸지 마세요. 먼저 대상 요청이 어떤 경로를 사용해야 하는지 판단한 다음, 해당 경로의 주소 해석, 연결, 서비스 응답을 확인하세요.

설정에서 사용자 지정 정책 이름을 사용한다면 해당 이름이 실제로 존재하는지, 참조 이름과 정의가 정확히 일치하는지 확인하세요. 서버 메모 이름을 사용할 수 있는 정책 이름으로 간주하지 말고, 다른 파일에서 참조만 복사해 관련 정의를 빠뜨리지도 마세요. 이 페이지는 기본 처리 방향으로 기본 로직을 설명하며, 사용자 지정 정책 그룹의 전체 정의는 다루지 않습니다. 이름을 인식하지 못한다면 같은 이름의 규칙을 더 추가하기보다 참조 관계부터 수정하세요.

위에서 아래로 확인하며 자동으로 ‘가장 구체적인 규칙’을 우선하지 않습니다

Rule은 위에서 아래로 읽는 것이 기본입니다. 요청이 어떤 규칙의 조건과 일치하면 해당 규칙의 정책이 적용되고, 같은 매칭에 다른 정책을 적용하기 위해 뒤의 규칙을 계속 확인하지 않습니다. 규칙 유형에 텍스트 순서를 무시하는 보편적인 우선순위는 없습니다. 예를 들어 앞에 example.com 후위 규칙이 있고 뒤에 api.example.com 전체 도메인 예외가 있으면, 뒤의 예외는 앞의 규칙에 이미 포함될 수 있습니다. 큰 규칙 목록을 관리할 때 흔히 발생하는 숨은 오류입니다.

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

api.example.com은 첫 번째 전체 도메인 조건에 매칭되어 DIRECT로 처리되고 후위 조건은 더 확인하지 않습니다. www.example.com은 첫 번째 조건에 매칭되지 않고 두 번째 조건에 매칭되어 PROXY로 처리됩니다. example이 포함되어도 해당 후위 도메인에 속하지 않는 다른 도메인은 키워드 조건에 매칭될 수 있습니다. 앞의 조건에서 매칭이 끝나지 않은 경우에만 주소 규칙을 확인합니다. 주소 규칙을 독립적으로 겹쳐 적용되는 강제 규칙처럼 이해하면 안 됩니다.

FINAL은 목록의 마지막 기본 규칙이어야 합니다

FINAL에는 별도의 매칭 값이 없으며 일반적인 표기는 FINAL,PROXY 또는 FINAL,DIRECT입니다. 앞의 규칙에 매칭되지 않은 요청을 처리하므로 목록 맨 끝에 두어야 합니다. FINAL을 중간에 두면 뒤의 규칙은 정상적으로 확인되지 않습니다. 새 규칙을 파일 끝에 추가하다가 기존 FINAL 뒤에 넣는 실수도 생길 수 있습니다. 새 줄이 있는지만 확인하지 말고 편집할 때마다 마지막 위치를 살펴보세요.

기본 처리 방향은 네트워크 사용 목적과 테스트 예상 결과에 맞춰 선택하세요. FINAL은 네트워크 장애 시 자동으로 대신 연결해 주는 서버가 아니며, 앞의 PROXY 연결이 실패한 뒤 다음 규칙을 계속 실행하지도 않습니다. 한 번 매칭되어 정책이 정해지면 이후 연결 실패는 해당 정책 경로에서 해결해야 할 문제입니다. FINAL을 실패 시 대체 경로로 오해하면 프록시 서버가 작동하지 않을 때 무관한 마지막 규칙을 계속 수정하게 되고 실제 문제는 해결되지 않습니다.

검토하기 쉬운 순서로 구성하기

일반적인 구성 방식은 구체적인 서비스 예외를 먼저 배치하고, 적절한 범위의 도메인 규칙을 그 뒤에 둔 다음, 로컬 주소와 지리 조건을 배치하고 마지막에 FINAL을 두는 것입니다. 이는 검토하기 편한 구성 방법일 뿐 모든 환경에서 따라야 하는 고정 순서는 아닙니다. 특정 주소 대역을 모든 도메인 조건보다 우선 적용해야 한다면 앞쪽에 배치하세요. 주소 정보가 필요할 수 있고 이후 도메인 판단에 영향을 줄 수 있다는 점도 고려해야 합니다.

순서를 검토할 때 중요한 규칙마다 매칭되어야 하는 입력 하나와 계속 다음 규칙으로 넘어가야 하는 입력 하나를 정리하세요. 긍정 사례만 확인하면 범위가 넓은 규칙이 다른 항목을 덮는 문제를 놓칠 수 있습니다. 오래된 규칙을 삭제할 때도 같은 방법으로 확인해야 합니다. 오랫동안 효과가 없어 보인 예외가 특정 네트워크, 주소 계열, 로그인 절차에서만 필요할 수 있습니다. 규칙 수로 설정 품질을 판단하기보다 각 규칙의 용도를 명확히 기록하는 것이 중요합니다.

USER-AGENT가 확인하는 정보

USER-AGENT는 요청에서 확인할 수 있는 User-Agent 정보를 대상으로 하며, 기기에 설치된 앱 이름을 모두 찾아주는 일반적인 목록이 아닙니다. 앱 아이콘만으로 모든 연결의 출처를 알 수 없으며 모든 트래픽을 앱별로 분기하는 기능이라고 설명해서도 안 됩니다. 서로 다른 앱이 같은 시스템 네트워크 구성 요소를 사용할 수 있고, 같은 앱도 요청마다 다른 식별 정보를 보내거나 이런 매칭에 쓸 정보를 전혀 제공하지 않을 수 있습니다. 따라서 사용 전에 실제 요청에 어떤 필드가 있는지 확인해야 합니다.

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

이 예시는 ExampleApp으로 시작하는 식별 값을 사용해 조건 형식을 보여줄 뿐, 실제 특정 앱이 반드시 매칭된다는 뜻은 아닙니다. 처리 과정에서 해당 요청 정보를 확인할 수 있을 때만 이 조건을 판단할 수 있습니다. 관련 필드가 보이지 않는 연결은 도메인이나 대상 주소처럼 확인 가능한 정보를 기준으로 분석하세요. 입력 정보가 없는 문제를 해결하려고 범위가 모호한 와일드카드를 계속 추가하지 마세요.

HTTPS에서 요청 경로와 헤더가 자동으로 보이는 것은 아닙니다

일반적인 분기에 사용할 수 있는 이름이나 주소 정보와 암호화된 요청 전체를 읽는 것은 서로 다른 기능입니다. 도메인을 기준으로 DOMAIN-SUFFIX 규칙을 적용할 수 있다고 해서 HTTPS 경로, 쿼리 매개변수, User-Agent까지 읽을 수 있다는 뜻은 아닙니다. 실제로 확인할 수 있는 필드에 맞춰 규칙을 설계하세요. 적용되지 않는 요청 헤더 규칙을 확인하려고 인증서 신뢰 설정을 성급하게 변경하거나 처리 범위를 넓히지 마세요. 이런 변경은 보안에 미치는 영향과 적용 조건을 별도로 이해해야 합니다.

특정 사이트를 원하는 방향으로 보내는 것이 목적이라면 도메인 규칙이 더 간단한 경우가 많습니다. 실제 서비스에 요청 단위 조건이 필요하고 처리 과정에서 해당 정보를 인식한다는 사실을 확인할 수 있을 때만 USER-AGENT 등의 조건을 사용하세요. 확인할 때는 직접 제어하는 테스트 요청을 사용해 입력 식별 값과 예상 정책을 연결하세요. 한 번 접속에 성공했다는 이유만으로 해당 필드를 읽었다고 단정하지 마세요.

URL Rewrite: 요청 주소를 바꾸며 프록시를 선택하지는 않습니다

URL Rewrite는 표현식에 일치하는 URL을 처리합니다. Rule과 역할이 다릅니다. Rule은 정책을 선택하고, 재작성은 조건에 맞는 요청 주소를 바꾸거나 해당 요청을 리디렉션합니다. 아래 예시는 일반 HTTP URL을 대상으로 example.com 요청을 대응하는 HTTPS 주소로 리디렉션합니다. 표현식에서 점은 이스케이프해야 하고, 시작 앵커는 매칭 시작 위치를 제한하며, 캡처 그룹은 원래 경로를 보존합니다.

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

여기서 302는 임시 리디렉션을 나타냅니다. 클라이언트가 이후 예상대로 새 요청을 보내는지는 실제 요청 방식과 앱 동작에도 달려 있습니다. 리디렉션이 항상 메서드와 요청 본문을 그대로 유지한다고 가정하지 마세요. 브라우저 주소 표시줄이 바뀌었다고 모든 백그라운드 API 요청에도 같은 규칙이 적용됐다고 볼 수는 없습니다. 확인하기 쉽고 관찰 가능한 단순 요청을 대상으로 응답과 리디렉션 경로를 확인한 뒤 범위를 넓히세요.

정규식의 범위와 반복을 제한하기

표현식을 작성할 때는 먼저 프로토콜, 도메인 경계, 경로 범위를 정하고 캡처 그룹을 고려하세요. 도메인의 점을 이스케이프하지 않으면 정규식에서 임의의 문자로 해석되어 예상치 못한 주소에 매칭될 수 있습니다. 범위가 넓은 키워드 하나만 사용해도 쿼리 매개변수나 다른 사이트에 영향을 줄 수 있습니다. 대체된 주소가 원래 표현식에 다시 매칭되면 반복 리디렉션이 발생할 수도 있습니다. “원래 URL → 새 URL → 재매칭 여부”의 전체 흐름을 확인하세요.

공유할 수 있는 재작성 조각에 계정 인증 정보, 구독 토큰, 서비스 키를 넣지 마세요. 교육과 기록용 요청에서는 민감한 매개변수를 제거하고 규칙 동작을 재현하는 데 필요한 구조만 남기세요. 실제 설정에 민감한 정보가 꼭 필요하다면 개인 설정으로 관리하고 문제 해결 첨부 파일로 공개하지 마세요. 다른 사람이 작성한 표현식을 복사할 때도 첫 번째 조건만 보지 말고 대상 도메인과 대체 주소를 먼저 확인하세요.

설정을 검토할 때는 Rule만 보지 말고 URL Rewrite를 별도 목록으로 확인하세요. 도메인 분기가 예상대로여도 잘못된 재작성 때문에 요청이 다른 경로로 갈 수 있습니다. 반대로 재작성 규칙이 있다고 모든 연결에 적용되는 것은 아닙니다. 요청 프로토콜, 확인 가능한 정보, 현재 설정에 따라 적용 여부가 결정됩니다.