공식 매뉴얼 · 규칙 가이드
Shadowrocket 규칙 및 설정 파일 가이드
먼저 현재 설정 파일과 Global Routing을 확인한 다음 요청이 어떤 규칙에 매칭됐는지 살펴보세요. 설정 파일은 매칭 조건을, 정책은 매칭 후 처리를 결정하므로 각각 따로 확인해야 합니다.
이 페이지는 설정을 체계적으로 확인하기 위한 매뉴얼이며, 이미 본인의 구독 또는 서버 정보를 보유하고 규칙을 조정하려는 사용자를 위한 안내입니다. 처음 사용한다면 먼저 빠른 시작 가이드에 따라 가져오기, 연결 및 기본 테스트를 마친 뒤 해당 장에서 문법을 확인하세요. 아래에서는 가져오기와 연결이 필요한 부분에 가이드를 연결하며, 설치 절차를 반복하지 않습니다.
Shadowrocket은 iPhone, iPad, Mac(Apple 칩 및 Intel), Windows, Android, Linux 버전을 제공합니다. 플랫폼에 따라 화면 구성이 다를 수 있으므로, 이 가이드에서는 설정 키워드와 실제 매칭 동작을 기준으로 확인합니다. 플랫폼별 다운로드 방법과 시스템 설치 허용 절차는 전체 플랫폼 다운로드 안내를 참고하세요.
설정 파일 구조와 안전한 편집 절차
설정 파일은 설정과 규칙을 모아 둔 것으로, 구독 링크나 서버 목록과는 다릅니다. 구독은 일반적으로 서비스 제공업체가 관리하는 서버 정보를 가져오는 데 사용하고, 설정 파일은 요청을 어떻게 해석하고 매칭해 처리할지 정의합니다. 두 가지를 함께 사용할 수 있지만, 구독을 업데이트했다고 현재 규칙이 올바르다는 뜻은 아니며 규칙을 수정해도 서버 설정이 고쳐지지는 않습니다. 편집을 시작하기 전에 방금 내려받은 동명의 파일만 확인하지 말고 Config에서 현재 사용 중인 파일을 먼저 확인하세요.
네 가지 섹션의 역할
[General]에는 DNS 및 시스템 트래픽 처리 옵션 등의 일반 설정을 저장합니다. [Rule]에는 매칭 조건과 정책을 한 줄씩 작성합니다. [Host]는 지정한 호스트 이름의 정적 해석 정보를 정의합니다. [URL Rewrite]는 정규식으로 URL 변경 또는 리디렉션을 지정합니다. 섹션 이름은 문법 요소이므로 번역하거나 다른 섹션의 끝에 섹션 이름 없이 내용을 이어 붙이지 마세요.
아래 예시는 구조를 이해하기 위한 것으로, 개인 설정 파일 전체를 그대로 대체할 수 있는 완성본이 아닙니다. 예시 도메인은 설명을 위한 것이며, PROXY를 사용하려면 이용 가능한 서버를 선택해야 합니다. 실제 설정 파일에는 여기에 나오지 않은 섹션도 있을 수 있으므로, 이 페이지에서 다루지 않았다는 이유로 삭제하지 마세요. 내용을 이해하기 어렵다면 수정하기 전에 출처와 용도를 먼저 확인하세요.
[General]
bypass-system = true
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
FINAL,PROXY
[Host]
localhost = 127.0.0.1
[URL Rewrite]
^http://example\.com(?=/|$) https://example.com 302
키와 필드, 줄바꿈 구분하기
일반 설정과 Host 매핑은 보통 등호로 좌우 항목을 구분하고, 규칙 행은 영문 쉼표로 유형, 조건, 정책을 구분합니다. 한국어 쉼표, 전각 공백, 복사 과정에서 함께 들어간 따옴표는 파싱 결과를 바꿀 수 있습니다. 각 규칙은 한 줄에 하나씩 작성하세요. 편집기에서 자동 줄바꿈으로 두 줄처럼 보여도 파일에 실제 줄바꿈 문자가 들어간 것은 아닐 수 있습니다.
빈 줄은 내용을 묶어 보기 쉽게 하지만 우선순위를 새로 만들지는 않습니다. 섹션을 구분하는 것은 섹션 이름이고, 적용 순서는 Rule 안의 위치가 결정합니다. 설명은 #으로 시작하는 주석을 별도 줄에 작성하세요. 규칙 필드 뒤에 임의로 덧붙이지 마세요. 특히 조건 뒤에 자연어 설명을 붙이면 클라이언트가 불필요한 문구를 알아서 무시할 것이라고 기대해서는 안 됩니다.
복사한 뒤 수정하고, 적용할 파일을 선택하세요
현재 정상적으로 사용할 수 있는 파일을 복사해 원본과 서비스 제공업체가 전달한 정보를 보존하는 것이 좋습니다. 복사본에서 한 가지 항목만 수정하고 저장한 뒤, 선택된 설정 파일을 다시 확인한 다음 새 테스트 요청을 보내세요. 원격으로 관리되는 파일의 로컬 복사본을 편집했다면 원격 원본과 로컬 수정 사항의 관계도 구분해야 합니다. 그래야 다음 업데이트에서 임시 변경 내용이 덮어써지는 일을 방지할 수 있습니다.
파일 이름이 같아도 내용까지 같다는 뜻은 아니며, 파일을 저장했다고 현재 적용 중이라는 뜻도 아닙니다. 문제를 확인할 때 복사본에 알아보기 쉬운 테스트 규칙을 추가한 뒤 요청 기록에서 매칭 결과를 확인할 수 있습니다. 기록에 이전 규칙이 계속 표시된다면 수정 사항을 더 쌓지 말고 먼저 활성 파일과 Global Routing을 확인하세요. 되돌릴 때는 기억에 의존해 한 줄씩 취소하는 것보다 원본 파일로 다시 전환하는 편이 안전합니다.
예시는 완성형 범용 설정 파일이 아닙니다규칙을 병합할 때는 필요한 기존 섹션과 서버 정보를 보존하고, 이해한 행만 이동하거나 추가하세요. 출처가 다른 파일 전체를 단순히 이어 붙이지 마세요.
구독 정보는 이용 중인 서비스 제공업체에서 받아야 합니다. 가져오는 방법은 가이드의 가져오기 및 첫 연결 절차를 참고하세요. 가져온 뒤 선택할 서버가 없다면 규칙을 살펴보기 전에 입력 정보와 가져오기 결과부터 확인해야 합니다. 그렇지 않으면 PROXY에 매칭되더라도 연결할 대상이 없습니다. 설정 구조가 올바른 것은 첫 단계의 점검일 뿐, 모든 네트워크 경로가 검증됐다는 의미는 아닙니다.
Global Routing의 세 가지 모드와 기본 정책
Global Routing은 전체 라우팅 모드를 제어하고, 규칙의 정책은 매칭된 요청을 처리하는 방식을 정합니다. 화면의 Config, Proxy, Direct와 규칙의 PROXY, DIRECT, REJECT는 서로 다른 계층입니다. “규칙이 왜 적용되지 않나요?”를 확인할 때는 먼저 Config 모드인지 확인하세요. Proxy 또는 Direct 모드에서의 연결 결과만으로 Rule의 매칭 로직이 올바르다고 판단할 수는 없습니다.
Config, Proxy, Direct의 역할
Config는 현재 설정에 따라 트래픽을 분기하므로 사용자 지정 규칙을 확인할 때 적합합니다. Proxy는 클라이언트가 처리하는 요청을 프록시 경로로 보내 규칙 분기 요인을 분리해 확인할 때 사용할 수 있습니다. Direct는 현재 네트워크의 직접 연결 상태를 살펴보는 모드입니다. 이는 클라이언트가 처리하는 범위의 전반적인 동작을 설명하며, 시스템의 모든 패킷이 반드시 같은 절차를 거친다는 뜻은 아닙니다. 모드를 전환해도 기존 연결이 모두 즉시 다시 설정되는 것은 아닙니다.
| 화면 모드 | 주요 용도 | 중점 확인 사항 |
|---|---|---|
| Config(설정) | 현재 설정에 따라 트래픽 분기 | 규칙 순서, 매칭 조건 및 최종 정책 |
| Proxy(프록시) | 프록시 경로의 기본 연결 가능 여부 확인 | 선택한 서버와 연결 설정 |
| Direct(직접 연결) | 현재 네트워크의 직접 연결 상태 확인 | 로컬 네트워크, DNS 해석 및 대상 서비스 |
예를 들어 어떤 도메인이 Proxy에서는 열리지만 Config에서는 실패한다면, 두 모드의 결과가 다르다는 점만 확인된 것입니다. DNS 문제라고 바로 단정할 수는 없습니다. Config에서 실제로 어떤 정책이 선택됐는지, 앞선 DIRECT 또는 REJECT 규칙에 먼저 매칭됐는지, 대상 요청의 도메인이 처음 입력한 이름과 같은지 계속 확인하세요. 브라우저 리디렉션으로 도메인이 바뀌었을 수도 있습니다.
PROXY, DIRECT, REJECT의 의미
PROXY는 매칭된 요청을 현재 선택된 프록시로 전달하고, DIRECT는 직접 연결하며, REJECT는 요청을 거부합니다. 정책이 연결 성공을 보장하는 것은 아닙니다. PROXY는 유효한 서버 정보와 대상에 대한 연결 가능성에 달려 있고, DIRECT는 현재 네트워크의 영향을 받으며, REJECT의 적용 범위는 매칭 조건에 따라 달라집니다. 세 정책은 “빠름”, “느림” 또는 “복구 버튼”이 아니라 처리 방식으로 이해하는 것이 정확합니다.
[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN,local.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY
이 예시는 한 호스트를 지정해 거부하고, 다른 호스트는 지정해 직접 연결하며, 해당 도메인 접미사에 속하는 나머지 요청만 PROXY로 전달합니다. 접미사 규칙을 가장 위로 옮기면 뒤의 두 가지 예외 규칙이 매칭될 기회를 잃을 수 있습니다. 정책 자체에 고정된 우선순위는 없으므로 REJECT가 항상 PROXY보다 우선하는 것은 아닙니다. 적용 범위는 조건과 순서가 결정합니다.
프록시 선택과 프로토콜 설정은 별도로 확인하세요
규칙에 PROXY를 적어도 서버 주소, 포트 또는 인증 정보가 함께 설정되는 것은 아닙니다. Shadowsocks, VMess, VLESS, Trojan 등의 프로토콜을 사용할 때는 서비스 제공업체가 안내한 정보를 바탕으로 해당 설정을 유지해야 합니다. 이름이 비슷하다는 이유로 다른 프로토콜의 필드를 가져오지 마세요. 프로토콜은 연결 계층에, 규칙은 경로 선택 계층에 속하므로 규칙이 올바르더라도 연결 정보가 빠져 있으면 해결되지 않습니다.
On Demand는 조건에 따른 연결 동작을 관리하며 Rule의 정책 유형이 아닙니다. 테스트 중 연결 상태가 계속 바뀐다면 트리거 조건도 확인해 연결 해제나 재연결을 규칙이 불안정한 것으로 오해하지 않도록 하세요. Connectivity Test는 테스트한 연결의 상태를 확인하는 데 도움이 되지만, 실제 서비스 요청의 분기 검증을 대신할 수는 없습니다.
모드를 전환할 때는 한 번에 하나의 변수만 바꾸세요. 기존 설정을 기록하고, 모드를 바꾼 뒤 새 요청을 만들어 결과를 기록한 다음 평소 사용하는 Config로 돌아오세요. 자세한 모드 비교는 Global Routing의 Config / Proxy / Direct 비교를 참고하세요. 한 번의 테스트에서 서버, DNS, 규칙을 동시에 바꾸면 성공하거나 실패한 원인을 파악하기 어렵습니다.
DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD
도메인 규칙은 “이 호스트”, “이 도메인 및 하위 도메인”, “이 문자열을 포함한 이름”에 대한 처리 방식을 지정할 때 적합합니다. 규칙 유형은 범위가 넓은 키워드 규칙부터 작성하기보다 필요한 최소 범위부터 선택하세요. 범위가 넓을수록 로그인, 결제, 콘텐츠 전송 또는 관련 없는 요청까지 함께 바뀔 가능성이 커지고, 나중에 예상치 못한 사이트가 영향을 받은 이유를 설명하기도 어려워집니다.
DOMAIN: 전체 호스트 이름 하나만 지정
DOMAIN은 호스트 이름을 정확히 매칭합니다. 조건에 example.com을 쓰더라도 www.example.com까지 자동으로 포함한다고 보아서는 안 됩니다. 특정 API 또는 호스트 하나만 조정할 때 적합합니다. 조건에는 도메인 이름만 작성하고 프로토콜 접두사, 포트, 경로, 쿼리 매개변수는 넣지 마세요. 주소 표시줄에서 복사한 전체 URL을 그대로 넣어서도 안 됩니다.
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,static.example.com,DIRECT
FINAL,PROXY
웹페이지 하나를 열 때 여러 호스트에 연결하는 경우가 많습니다. 페이지 문서는 한 도메인에서 제공되더라도 이미지, API, 인증은 각각 다른 도메인에서 제공될 수 있습니다. 페이지가 일부만 로드되더라도 곧바로 키워드 매칭 범위를 넓히지 마세요. 먼저 요청 기록에서 실패한 호스트를 찾아 필요한 경우 정확한 규칙을 추가하세요. 한 도메인에 연결됐다고 해서 페이지의 모든 요청이 같은 정책을 사용한다고 볼 수는 없습니다.
DOMAIN-SUFFIX: 도메인 계층에 따라 범위 지정
DOMAIN-SUFFIX,example.com,PROXY는 해당 도메인과 하위 도메인을 매칭합니다. 예를 들면 www.example.com과 그보다 깊은 단계의 호스트 이름이 포함됩니다. 임의의 문자열 포함 여부가 아니라 도메인 접미사 경계를 기준으로 판단하므로, notexample.com은 끝부분의 문자가 비슷하다는 이유만으로 해당 도메인의 하위 도메인이 되지 않습니다. 조건에 별표나 프로토콜 접두사를 추가할 필요는 보통 없습니다.
같은 도메인의 대부분 서비스에 PROXY를 사용하고 내부 API 하나만 DIRECT로 연결하려면, 내부 API의 DOMAIN 예외를 먼저 작성한 뒤 DOMAIN-SUFFIX 기본 규칙을 작성할 수 있습니다. 첫 번째 규칙은 예외를, 두 번째 규칙은 도메인 범위를 처리하므로 의도가 분명해집니다. 서비스가 다른 도메인으로 이전되면 기존 접미사 규칙이 새 도메인을 자동으로 추적하지 않으므로 실제 요청을 바탕으로 규칙을 업데이트해야 합니다.
| 유형 | 조건 예시 | 적용 범위 |
|---|---|---|
| DOMAIN | api.example.com | 지정한 전체 호스트 이름 |
| DOMAIN-SUFFIX | example.com | 해당 도메인 및 하위 도메인 |
| DOMAIN-KEYWORD | example | 도메인 이름에 지정한 문자열이 포함된 경우 |
DOMAIN-KEYWORD: 편리하지만 영향 범위가 넓어지기 쉬움
DOMAIN-KEYWORD는 도메인 이름 안의 문자열을 매칭합니다. 웹페이지 콘텐츠를 검색하거나 URL 경로를 검사하는 기능은 아닙니다. 조건에 example을 쓰면 서로 관계없는 여러 도메인에 매칭될 수 있습니다. 범위가 넓은 문자열 조건이 꼭 필요하고 적용 범위를 확인한 경우에 사용하세요. 잘 모르는 서비스에 적용하는 첫 규칙으로는 적합하지 않으며, 특히 흔히 쓰이는 짧은 문자열을 거부 정책에 사용해서는 안 됩니다.
특히 REJECT 정책은 좁은 범위부터 적용해야 합니다. 여러 서비스가 공유하는 도메인을 거부하면 이미지, 인증 코드 또는 계정 기능까지 중단될 수 있습니다. 서비스 콘텐츠를 제공하는 호스트를 거부하더라도 원치 않는 리소스만 차단된다고 보장할 수 없습니다. 도메인 규칙은 같은 암호화 연결 안의 페이지 요소를 세밀하게 구분하지 못합니다. 자세한 원리는 REJECT 규칙의 역할과 한계에서 확인하세요.
도메인 조건이 실제로 매칭됐는지 확인하는 방법
먼저 테스트 범위를 확인된 호스트 하나로 제한하세요. 요청 기록에 나타난 이름이 조건과 일치하는지 확인한 다음 매칭된 규칙과 정책을 살펴보세요. 리디렉션, 캐시, 백그라운드 API 때문에 실제 요청 목록이 달라질 수 있으므로 브라우저 주소 표시줄만 확인해서는 안 됩니다. 기록에 대상 IP만 표시된다면 같은 규칙을 계속 추가하지 말고 도메인 정보를 사용할 수 있는지 확인하세요.
도메인 별칭과 리소스 이전도 구분해야 합니다. 해석 과정에서 대상이 다른 이름을 참조하더라도 그 해석 경로에 포함된 모든 도메인을 규칙에 추가해야 한다는 뜻은 아닙니다. 클라이언트 기록과 실제 서비스 요청을 기준으로 판단하세요. 수정한 뒤에는 같은 진입 경로로 다시 테스트하고 수정 전후 기록을 보존해, 예상한 호스트에만 영향을 주는지 확인한 다음 접미사 전체로 확대할지 결정하세요.
IP-CIDR, GEOIP, USER-AGENT의 사용 범위
도메인 외에도 대상 주소나 요청에서 확인할 수 있는 정보를 기준으로 규칙을 적용할 수 있습니다. 이런 조건은 도메인 규칙을 대신하지 않습니다. 도메인은 서비스 이름을, IP는 연결 대상 주소를, USER-AGENT는 특정 요청 필드를 나타냅니다. 조건을 선택하기 전에 클라이언트가 요청의 해당 단계에서 어떤 정보를 확인할 수 있는지 알아야 합니다. 그렇지 않으면 문법이 올바른 규칙도 매칭되지 않을 수 있습니다.
IP-CIDR: 네트워크 대역으로 주소 범위 지정
IP-CIDR은 주소와 프리픽스 길이로 IPv4 네트워크 대역을 지정합니다. 프리픽스 길이가 길수록 범위는 좁아지며, 단일 IPv4 주소에는 /32를 사용할 수 있습니다. 예를 들어 192.168.0.0/16은 해당 프리픽스의 주소를 포함하고, 192.168.10.0/24는 더 좁은 범위입니다. 규칙에는 대상 대역에 해당하는 네트워크 주소를 사용하고, 슬래시 뒤의 숫자를 포트로 해석하지 마세요.
[Rule]
IP-CIDR,192.168.10.0/24,DIRECT,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
GEOIP,CN,DIRECT
FINAL,PROXY
아래 행은 사설 네트워크 주소, IPv6 로컬 주소 범위, 지역 판별 규칙의 작성 방법을 보여주는 예시이며 모든 설정 파일에 그대로 넣어야 한다는 뜻은 아닙니다. 회사 네트워크나 원격 네트워크에서도 같은 사설 주소 범위를 사용할 수 있습니다. 특정 원격 경로를 통해 사설 대역에 연결하려는 경우, 범위가 넓은 DIRECT 규칙은 오히려 연결을 잘못된 경로로 보낼 수 있습니다. 현재 네트워크와 대상 주소의 용도를 함께 고려해 정책을 정하세요.
no-resolve는 DNS를 끄는 설정이 아닙니다
추가 매개변수 no-resolve는 해당 IP 규칙의 판별만을 위해 도메인을 능동적으로 해석하지 않도록 합니다. 앱의 DNS 기능을 완전히 중지하거나 이후의 모든 규칙에서 해석을 금지하는 설정은 아닙니다. 요청이 이미 IP 주소를 사용하거나 이용 가능한 주소 정보가 있으면 주소 조건을 판별할 수 있습니다. 도메인 해석 결과에 따라 매칭해야 하는 상황에서 이를 무심코 추가하면 예상과 다른 결과가 나올 수 있습니다.
따라서 도메인 요청이 어떤 대역 규칙에도 매칭되지 않는다면 주소 매칭을 위해 해석이 허용되어 있는지, 이후 규칙이 어떻게 처리하는지 확인하세요. no-resolve를 모든 주소 규칙에 추가하는 범용 성능 옵션으로 취급하지 마세요. 먼저 어떤 해석 동작을 줄이려는지 분명히 하고 기록으로 동작을 확인하세요. 해석을 줄이는 것과 올바른 정책을 적용하는 것은 별개의 문제입니다.
GEOIP: IP 데이터베이스에 따른 판별이지 웹사이트 신원 확인이 아닙니다
GEOIP,CN,DIRECT는 사용 중인 데이터베이스에서 대상 IP의 지역을 기준으로 판별합니다. 웹사이트가 어떤 언어를 사용하는지, 운영 주체가 어디에 있는지를 판별하지 않으며, 네트워크와 시점, 해석 결과가 달라져도 같은 도메인이 항상 같은 지역으로 매칭된다고 보장하지 않습니다. 콘텐츠 전송 서비스는 다른 주소를 반환할 수 있으며, 데이터베이스의 분류가 실제 서비스의 전체 배포 위치를 뜻하지도 않습니다.
업무상 의도가 분명한 도메인은 먼저 도메인 규칙으로 표현하고, GEOIP는 그 뒤에 더 넓은 분류 조건으로 두는 편이 좋습니다. 특정 사이트의 경로가 가끔 바뀐다면 당시의 해석 주소와 매칭 기록을 확인해 “주소가 바뀐 것”과 “규칙이 적용되지 않는 것”을 구분하세요. 구체적인 도메인 요구를 해결하려고 GEOIP를 계속 이동하면 더 많은 요청에 영향을 주게 됩니다.
USER-AGENT: 확인 가능한 요청 필드에만 적용
USER-AGENT,Example*,DIRECT는 User-Agent 패턴을 매칭하는 규칙 예시이며, 별표는 패턴 매칭에 사용됩니다. 앱 이름, 프로세스 이름 또는 아이콘으로 앱을 식별하는 방식은 아닙니다. 여러 앱이 같은 요청 라이브러리를 사용할 수도 있고 필드 값이 바뀔 수도 있습니다. 일부 요청에서는 규칙 판별에 사용할 User-Agent를 가져올 수 없습니다.
암호화된 요청에서는 클라이언트가 모든 HTTP 필드를 당연히 확인할 수 있다고 가정해서는 안 됩니다. 따라서 USER-AGENT를 모든 앱 트래픽 분류의 범용 기준으로 사용하지 마세요. 이 규칙을 사용하기 위해 별도의 복호화 설정을 활성화할 필요는 없습니다. 특정 서비스의 경로를 지정하려는 경우, 명확한 도메인 또는 주소 조건으로 표현할 수 있는지 먼저 살펴보고 테스트 중에는 필드의 가시성과 정책 결과를 함께 확인하세요.
IPv4와 IPv6도 따로 확인해야 합니다. IP-CIDR만 작성해도 해당 IPv6 주소까지 자동으로 적용되지는 않습니다. 대상 서비스가 다른 주소 계열을 사용하면 다른 규칙에 매칭될 수 있습니다. 같은 도메인이 네트워크에 따라 다르게 동작한다면 네트워크 기능을 바로 끄기보다 주소 계열도 점검하세요. 실제 연결 대상 주소를 확인해야 어떤 조건이 빠졌는지 판단할 수 있습니다.
위에서 아래로 매칭되는 순서, 예외 규칙 및 FINAL
Rule은 위에서 아래로 확인하며, 먼저 매칭된 규칙이 해당 요청의 정책을 결정합니다. 더 구체적인 유형이라고 해서 자동으로 우선순위가 높아지는 것은 아니며, 파일 끝의 규칙이 앞부분의 규칙을 덮어쓰지도 않습니다. 이 점을 이해하면 “규칙을 작성했는데 적용되지 않아요”라는 상황을 검증 가능한 질문으로 바꿀 수 있습니다. 해당 규칙에 도달하기 전에 요청이 다른 조건에 먼저 매칭됐는지 확인하세요.
범위가 넓은 규칙보다 구체적인 예외를 먼저 작성
같은 도메인에서 호스트 하나만 직접 연결하고 나머지는 프록시로 연결해야 한다고 가정해 보겠습니다. 해당 호스트의 DOMAIN 규칙을 먼저 작성하고, 도메인 전체에 적용되는 DOMAIN-SUFFIX 규칙을 뒤에 작성해야 합니다. 순서를 반대로 하면 정확한 조건의 규칙이 저장되어 있어도 매칭될 기회를 얻지 못할 수 있습니다. 규칙 유형은 범위를, 위치는 순서를 나타내므로 두 가지를 모두 확인해야 합니다.
[Rule]
# 지정한 예외부터 확인
DOMAIN,intranet.example.com,DIRECT
DOMAIN,blocked.example.com,REJECT
# 다음으로 더 넓은 도메인 범위 확인
DOMAIN-SUFFIX,example.com,PROXY
# 주소 분류와 최종 정책은 뒤에 배치
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
이 예시에서는 구체적인 서비스 요구가 더 넓은 주소 분류보다 먼저 적용되도록 도메인 규칙을 GEOIP 앞에 둡니다. 모든 설정에 고정으로 적용되는 순서 공식은 아닙니다. 특정 주소 범위를 우선 처리해야 한다면 검토를 마친 주소 예외를 앞에 둘 수도 있습니다. 중요한 것은 어떤 규칙이 다른 규칙을 가리는지 설명하고, 조건이 겹치는 요청을 테스트하는 것입니다.
FINAL은 기본 정책이지, 앞선 규칙을 덮어쓰는 규칙이 아닙니다
FINAL,PROXY는 앞선 규칙에 매칭되지 않은 요청에 PROXY를 적용합니다. 도메인이나 네트워크 대역 조건은 포함하지 않습니다. 일반적으로 FINAL은 Rule 섹션의 마지막 유효 규칙으로 두어 뒤의 조건이 무시되지 않도록 하세요. FINAL을 중간에 배치해도 “먼저 프록시를 시도하고 실패하면 다음 규칙으로 넘어가는” 동작은 하지 않습니다. 매칭은 연결 가능 여부에 따라 한 줄씩 재시도하는 과정이 아닙니다.
FINAL에 DIRECT와 PROXY 중 무엇을 선택할지는 전체 트래픽 분기 목표에 따라 달라지며, 모든 상황에 맞는 정답은 없습니다. PROXY를 선택하면 분류되지 않은 요청이 사용 가능한 프록시에 의존하고, DIRECT를 선택하면 현재 네트워크의 직접 연결에 의존합니다. 기본 정책을 유지 관리 메모에 기록하고 앞선 조건에 매칭되지 않는 요청을 테스트해 실제 경로가 예상과 일치하는지 확인하세요.
중복 규칙, 충돌 규칙 및 도달할 수 없는 규칙
완전히 같은 규칙은 대개 읽기만 어렵게 만듭니다. 같은 조건에 서로 다른 정책을 지정했다면 앞선 규칙이 뒤의 결정을 가립니다. 더 알아차리기 어려운 충돌은 키워드 조건이 접미사 조건을 포함하거나, 접미사 조건이 정확한 호스트 조건을 포함하는 등 범위가 겹치는 경우입니다. 문제를 확인할 때 똑같은 행만 검색하지 말고 대상 요청에 먼저 매칭될 수 있는 더 넓은 조건도 찾아보세요.
출처가 다른 규칙을 병합할 때는 알파벳순으로 정렬하기보다 업무상 목적별로 정리한 다음 조건이 겹치는지 확인하세요. 정렬 도구를 사용하면 원래 위쪽에 있던 예외 규칙이 뒤로 밀릴 수 있습니다. 규칙 그룹 앞에 용도를 주석으로 적어 두면 읽기 편하지만, 주석은 우선순위를 바꾸지 않습니다. “최우선”이라고 써 두어도 FINAL 뒤에 있으면 적용되지 않습니다.
대조 요청으로 적용 범위 확인
접미사 규칙을 검증할 때는 최소한 해당 도메인 자체, 하위 도메인 하나, 해당 도메인에 속하지 않는 이름 하나를 확인하세요. 정확한 예외는 같은 도메인의 다른 호스트도 함께 테스트해야 합니다. 목적은 “페이지 하나가 열린다”는 것을 증명하는 게 아니라, 필요한 요청은 매칭되고 영향을 받지 않아야 할 요청은 잘못 처리되지 않는지 확인하는 것입니다. REJECT 정책은 정상 기능이 계속 작동하는지도 특히 확인하세요.
여러 규칙이 같은 요청에 매칭될 수 있다면 복사본에서 테스트 범위를 일시적으로 줄이고, 앞선 후보 규칙을 단계별로 제외해 보세요. 매번 순서만 또는 조건만 수정하고 정책은 동시에 바꾸지 마세요. 현재 매칭된 규칙, 예상한 규칙, 대상 호스트를 기록하면 설정 파일 전체를 반복해서 캡처하는 것보다 문제를 파악하기 쉽습니다.
규칙 매칭은 연결 실패 후 다음 후보로 넘어가는 대기열이 아닙니다PROXY에 매칭된 연결이 실패해도 다음 줄의 DIRECT 규칙을 실행하지 않습니다. 동일한 조건을 뒤에 추가하지 말고 선택한 경로를 확인하거나 트래픽 분기 정책을 명확하게 수정하세요.
General, DNS, Host가 규칙 판별에 미치는 영향
DNS는 이름을 주소로 변환하고 규칙은 요청에 적용할 정책을 결정합니다. 둘은 서로 관련 있지만 같은 것은 아닙니다. 도메인 규칙은 주소가 나오기 전에 명확한 의도를 표현할 수 있고, 주소 규칙은 대상 주소 정보가 필요합니다. 문제를 확인할 때는 “주소를 가져오지 못함”, “적절하지 않은 주소를 가져옴”, “주소를 가져온 뒤 잘못된 경로를 선택함”을 구분하세요. 그렇지 않으면 DNS를 바꿔 현상이 일시적으로 달라져도 실제 원인을 파악하지 못할 수 있습니다.
General 설정은 정상 작동이 확인된 값을 먼저 유지하세요
dns-server = system은 시스템 DNS 설정을 사용한다는 뜻입니다. 이해하기 쉬운 기본 상태를 만들 때 적합하지만, 모든 네트워크에서 같은 결과를 보장하지는 않습니다. bypass-system = true는 시스템 관련 트래픽의 우회 처리와 관련된 설정이지, 도메인 허용 목록이 아니며 “모든 로컬 트래픽이 반드시 직접 연결된다”는 뜻도 아닙니다. 구체적인 트래픽 처리 범위는 시스템과 현재 설정에 따라서도 달라집니다.
[General]
bypass-system = true
dns-server = system
[Host]
localhost = 127.0.0.1
printer.example.com = 192.168.10.20
현재 설정이 정상적으로 작동한다면 파일을 더 완전해 보이게 하려고 낯선 General 매개변수를 복사하지 마세요. 일반 설정은 정확한 도메인 규칙보다 설정 전체에 영향을 줄 수 있어 적용 범위를 제한하기 어렵습니다. 수정하기 전에 기존 값을 기록하고, DNS 해석 출처, 시스템 트래픽 처리 또는 다른 옵션 중 무엇을 바꾸려는지 확인해 전역 변수를 여러 개 동시에 변경하지 않도록 하세요.
시스템 DNS, 사용자 지정 DNS 및 DNS over HTTPS
시스템 DNS는 현재 네트워크 환경의 DNS 설정을 사용하고, 사용자 지정 DNS는 실제로 사용할 수 있으며 출처를 알고 있는 해석 서비스를 설정해야 합니다. DNS over HTTPS는 해석 요청을 HTTPS로 전송하지만, 연결 가능한 서비스 주소와 유효한 연결, 적절한 경로가 필요합니다. 전송 방식이 다르다고 현재 업무에 더 적합한 결과가 보장되는 것은 아니며, 실제 서비스 요청이 프록시를 통과한다는 뜻도 아닙니다.
이 페이지에서는 외부 DNS 서비스 추천을 제공하지 않습니다. DNS를 변경해야 한다면 별도의 복사본에서 해석 설정만 바꾼 다음, 같은 도메인과 같은 라우팅 모드로 테스트하세요. 도메인 해석이 필요한 DNS 엔드포인트는 초기 이름을 어떻게 해석하는지도 확인해 설정이 자기 자신에 의존하는 순환을 피해야 합니다. 선택 방법은 시스템 DNS, 사용자 지정 DNS, DNS over HTTPS 비교를 참고하세요.
Host는 매핑만 설정하며 정책을 직접 지정하지 않습니다
Host의 printer.example.com = 192.168.10.20은 지정된 이름을 주소에 매핑할 뿐, 자동으로 DIRECT를 적용하지 않습니다. 직접 연결이 필요하다면 명확한 규칙으로 경로도 지정하고 대상 주소가 현재 접근 가능한 네트워크에 속하는지 확인하세요. 이름을 사설 주소로 매핑한다고 기기가 원격 사설 네트워크에 자동으로 연결되는 것은 아닙니다.
정적 매핑은 주소가 확정되어 있고 직접 관리하는 호스트에 적합하며, 대형 서비스의 해석 결과를 확인 없이 고정하는 데는 적합하지 않습니다. 서비스 주소는 지역, 부하, 장애 대응에 따라 바뀔 수 있으므로 오래된 매핑을 유지하면 정상적인 해석 변경을 우회하게 됩니다. 연결이 갑자기 실패한다면 Rule뿐 아니라 Host의 수동 항목도 확인하세요.
주소 매핑은 암호화된 서비스의 신원을 바꾸지 않습니다
도메인을 다른 서버로 연결해도 브라우저는 원래 도메인을 기준으로 암호화 연결 및 인증서 검증을 진행할 수 있습니다. 대상 서버가 해당 이름의 서비스를 제공하지 않으면 연결이 실패할 수 있습니다. Host는 인증서 오류를 해결하는 범용 방법도 URL 리디렉션도 아닙니다. 신원 확인을 무시해 매핑 오류를 감추지 말고 도메인, 주소, 대상 서비스가 서로 맞는지 먼저 확인하세요.
DNS 캐시와 연결 재사용으로 인해 수정 사항이 늦게 반영될 수 있습니다. 설정을 저장한 뒤 새 요청을 보내고 앱에서 이전 연결을 재사용하는지 확인하세요. 필요하다면 해당 앱의 기존 세션을 종료한 다음 다시 테스트하세요. 이전 주소를 사용한 요청 한 번만 보고 Host가 작동하지 않는다고 판단하지 말고, 기록 없이 여러 DNS 설정을 연달아 전환하지도 마세요.
“도메인 접속은 실패하지만 IP로 직접 접속하면 성공하는” 현상만으로 DNS 문제라고 단정할 수 없습니다. IP에 직접 접속하면 다른 가상 호스트, 인증서 또는 규칙이 적용될 수 있으므로 두 테스트는 완전히 같은 조건이 아닙니다. 더 정확히 비교하려면 같은 도메인을 유지하고 해석 결과, 매칭된 규칙, 실제 대상 주소를 확인해 매 테스트의 차이를 파악할 수 있도록 하세요.
URL Rewrite의 매칭, 리디렉션 및 위험 범위
URL Rewrite는 URL 형식의 조건을 매칭하고 변경하는 기능이지 Rule의 다른 작성 방식이 아닙니다. Rule은 요청에 적용할 정책을 결정하고, 리디렉션은 앱이 다른 주소로 다시 요청하게 만들 수 있습니다. 두 기능은 한 번의 접근 과정에 차례로 영향을 줄 수 있습니다. 규칙을 추가하기 전에 “연결 경로 변경”이 필요한지 “요청 주소 변경”이 필요한지 먼저 확인하세요. 도메인 하나를 프록시로 보내려는 목적이라면 보통 URL Rewrite는 필요하지 않습니다.
정규식, 대체 주소, 상태 코드부터 확인
아래 예시는 지정한 호스트의 HTTP 주소를 같은 호스트 이름의 HTTPS 주소로 보내며, 대상 서버가 실제로 HTTPS를 지원해야 합니다. 매칭 표현식, 대체 주소, 상태 코드는 각각 다른 역할을 하므로 쉼표로 구분하는 도메인 규칙 문법을 이 섹션에 가져오지 마세요. 이 예시는 규칙 하나를 설명하기 위한 것으로, 기존 내용을 확인하지 않고 모든 설정 파일에 바로 추가하지 않는 것이 좋습니다.
[URL Rewrite]
^http://example\.com(?=/|$) https://example.com 302
처음의 ^는 URL의 시작 위치에서 매칭되도록 제한합니다. \.는 정규식에서 임의의 문자를 뜻하는 점이 아니라 실제 점 문자를 나타냅니다. (?=/|$)는 호스트 이름 뒤에 슬래시가 있거나 문자열이 끝나는 경우만 허용해 비슷한 접두사를 가진 다른 호스트까지 매칭되는 것을 방지합니다. 대체 내용은 매칭된 접두사를 변경하며 뒤에 오는 경로가 유지되는지는 실제로 테스트해야 합니다.
302는 임시 리디렉션을 의미하며, 응답을 받은 클라이언트가 새 요청을 보낼 수 있습니다. 프록시 정책도 아니고 연결 실패 시 대체 경로로 돌아가는 설정도 아닙니다. 테스트할 때는 첫 페이지가 나타나는지만 보지 말고 새 대상 주소, 리디렉션 횟수, 최종 매칭 규칙을 확인하세요. 대상 주소가 반대 방향의 리디렉션 규칙에 다시 매칭되면 반복 이동 후 실패할 수 있습니다.
경로, 쿼리 매개변수 및 요청 방식도 확인하세요
주소 접두사를 바꾸면 해당 호스트 아래의 여러 경로에 영향을 줄 수 있습니다. 유지해야 하는 경로와 쿼리 매개변수를 테스트에 포함하고 사이트 첫 화면만 확인하지 마세요. 로그인 콜백이나 서명이 포함된 요청은 URL에 민감합니다. 페이지가 열려도 매개변수의 의미가 달라지면 서버가 요청을 거부할 수 있습니다. 복잡한 캡처 그룹은 각 그룹의 용도를 설명해 나중에 검토하기 쉽게 하세요.
브라우저 탐색과 앱 API 요청도 서로 다른 상황입니다. 요청 본문이 포함된 경우 앱의 리디렉션 처리 방식은 브라우저와 다를 수 있습니다. 브라우저에서 한 번 테스트한 결과만으로 같은 규칙을 모든 API에 적용해서는 안 됩니다. 계정, 인증 또는 데이터 쓰기 요청은 원래 동작을 우선 유지하고, 대상 서비스의 요구 사항을 명확히 이해한 경우에만 제한된 범위에서 테스트하세요.
암호화 트래픽의 가시성 한계
HTTPS 요청의 전체 경로는 일반적으로 암호화로 보호되므로 일반적인 트래픽 전달 중 클라이언트가 이를 자유롭게 읽고 수정할 수 있다고 가정해서는 안 됩니다. 특정 재작성 규칙을 적용할 수 있는지는 트래픽 가시성과 실제 설정에 따라 달라집니다. 도메인 규칙으로 호스트 이름을 매칭할 수 있다고 해서 경로 재작성도 가능하다고 판단하지 마세요. 호스트 정보와 전체 HTTP 콘텐츠는 서로 다른 계층입니다.
이 페이지는 URL Rewrite를 위해 별도로 복호화를 설정하거나 인증서를 설치하라고 안내하지 않습니다. 도메인 분기로 업무 목적을 달성할 수 있다면 적용 범위가 분명한 Rule을 우선 사용하세요. 계정과 민감한 데이터가 관련된 경우 각 설정이 영향을 미치는 범위를 특히 잘 이해해야 합니다. 설명할 수 없는 재작성 규칙은 일상 설정 파일에 바로 적용하지 말고 복사본에서 검증하세요.
재작성 규칙과 이후 규칙의 상호 작용 확인
원래 주소가 다른 도메인으로 리디렉션된다면 새 요청에도 해당 라우팅 판단이 적용됩니다. 원래 도메인에 DIRECT가 적용된다고 리디렉션된 도메인도 직접 연결되는 것은 아닙니다. 웹페이지에서 “첫 번째 단계는 성공했지만 이후 실패”한다면 리디렉션 전체 경로를 나열하고 각 호스트의 해석 결과, 매칭 규칙, 정책을 차례로 확인하세요. 첫 도메인 규칙만 계속 수정하지 마세요.
재작성 규칙을 관리할 때는 원래 주소 패턴, 대상 주소, 예상 상태 코드와 매칭되지 않아야 하는 사례를 기록하세요. 반례에는 비슷하지만 매칭되면 안 되는 호스트 하나와 유지해야 하는 경로 하나를 포함하는 것이 좋습니다. 문제가 생기면 다른 설정은 그대로 두고 새 재작성 규칙부터 비활성화하세요. 문제가 사라지면 표현식을 단계별로 좁히고, DNS, 서버, 모든 규칙을 동시에 조정하지 마세요.
도메인 분기와 주소 재작성을 각각 검증PROXY는 URL을 바꾸지 않으며, 리디렉션이 자동으로 PROXY 정책을 지정하지도 않습니다. 각 단계의 호스트와 정책을 기록해야 어느 부분에서 문제가 발생했는지 확인할 수 있습니다.
규칙 검증, 자주 발생하는 문제 및 장기 관리
규칙 검증은 예상 동작을 정하고, 복사본을 저장하고, 한 가지 항목을 수정하고, 새 요청을 보내고, 기록을 확인한 뒤 유지하거나 되돌리는 순서로 진행해야 합니다. 웹페이지 하나가 열린다는 사실만으로 모든 검증을 마쳤다고 보거나, 한 번의 실패로 설정 전체가 잘못됐다고 판단하지 마세요. 규칙은 연결 과정의 일부일 뿐입니다. 해석 결과, 선택한 서버, 대상 서비스, 로컬 네트워크를 계층별로 구분해 확인해야 합니다.
반복해서 실행할 수 있는 테스트 구성
각 변경마다 매칭되어야 하는 호스트, 적용할 정책, 영향을 받지 않아야 하는 대조 호스트를 준비하세요. 테스트 전에 Global Routing이 Config인지, 활성 파일이 방금 저장한 복사본인지, 서버 선택이 이전 테스트와 같은지 확인하세요. 캐시된 페이지를 보는 데 그치지 말고 새 요청을 보내 실제 호스트, 대상 주소, 적용된 정책을 기록하세요. 필요하면 당시 네트워크 환경도 함께 적어 두세요.
Connectivity Test는 정상이지만 서비스가 실패한다면 서버 테스트만 반복하지 말고 해당 서비스의 실제 요청을 확인하세요. 반대로 서비스 페이지가 열려도 캐시나 다른 호스트의 콘텐츠일 수 있어 모든 규칙이 올바르게 매칭됐다는 뜻은 아닙니다. 유효한 근거는 이번에 새로 발생한 요청과 연결되고, 어떤 규칙을 거쳤는지 보여줘야 합니다. “더 빨라진 것 같다”는 느낌만으로 결론 내리지 마세요.
현상에 따라 문제 범위를 좁히기
| 현상 | 우선 확인 | 다음 단계 |
|---|---|---|
| 새 규칙이 매칭되지 않음 | 활성 설정, Config, 앞선 조건 | 실제 호스트와 먼저 매칭된 규칙 확인 |
| PROXY에 매칭됐지만 연결 실패 | 서버 선택 및 연결 설정 | 프록시 경로와 대상 서비스 연결 여부를 따로 확인 |
| 일부 리소스만 실패 | API, 정적 리소스 및 리디렉션 도메인 | 호스트별 정책 확인 |
| 업데이트 후 로컬 수정 사항이 사라짐 | 원격 원본과 로컬 복사본 | 업데이트 전후의 관련 섹션 비교 |
저장 후 문법 오류가 발생하면 최근 수정한 섹션 이름, 영문 쉼표, 등호, 줄 끝의 내용을 먼저 확인한 뒤 몇 줄만 남겨 검증하세요. 연결 후 모든 서비스가 실패하면 이전에 정상 작동하던 파일을 복원해 전역 설정 변경과 개별 규칙 변경을 구분하세요. 도메인 하나만 실패한다면 모든 서버 정보를 다시 구성하기보다 해당 도메인의 해석 결과, 앞선 매칭, 재작성 규칙부터 확인하세요.
구독 업데이트와 규칙 관리는 별도로 기록
구독 정보는 이용 중인 서비스 제공업체에서 받아야 합니다. 구독 업데이트와 설정 파일 업데이트는 서로 다른 작업으로 기록하세요. 한 번의 업데이트로 서버 항목이나 선택 상태가 바뀔 수 있고, 원격 설정 업데이트로 로컬 규칙이 대체될 수도 있습니다. 업데이트 후에는 어떤 종류의 내용이 변경됐는지 먼저 확인하고 관련 테스트를 다시 실행하세요. 가져오기 경로의 차이는 Subscribe, Add Server, QR 코드 및 클립보드 가져오기 안내를 참고하세요.
로컬 예외 규칙은 용도, 조건 범위, 예상 정책, 검증 방법을 간단히 기록해 두는 것이 좋습니다. 비활성화된 호스트, 중복 행, 다른 규칙에 가려진 예외를 정기적으로 확인하고, 규칙을 계속 추가하기만 하지 마세요. 규칙이 많다고 적용 범위가 정확해지는 것은 아닙니다. 각 조건의 목적을 설명할 수 있고 빠르게 되돌릴 수 있는 설정 파일이 업무 변화에도 관리하기 쉽습니다.
기록을 저장할 때 개인정보 보호
요청 기록에는 접속한 도메인, 경로, 쿼리 매개변수가 포함될 수 있으며, 구독 링크에는 접근 자격 증명이 들어갈 수도 있습니다. 다른 사람에게 문제를 설명할 때는 필요한 규칙 유형, 익명화한 호스트, 매칭 정책만 남기세요. 전체 구독 링크, 인증 정보 또는 검토하지 않은 설정 파일 전체를 보내지 마세요. 예시에는 example.com을 사용할 수 있지만, 재현에 필요한 조건 관계와 규칙 순서는 유지해야 합니다.
클라이언트 구입과 연결 서비스 이용은 별개입니다. iPhone / iPad 버전은 App Store에서 $2.99 일회성 결제이며, Mac / Windows / Android / Linux 버전은 무료입니다. 클라이언트 일회성 구매가 연결 서비스 요금제를 포함하는 것은 아닙니다. Shadowrocket은 상용 비공개 소스 앱입니다. 이 매뉴얼은 사용자가 이미 서비스 정보를 보유한 경우를 전제로 설정 방법을 설명하며, 서버를 제공하지 않습니다. iPhone / iPad의 시스템 요구 사항은 App Store 페이지에 표시된 내용을 기준으로 확인하세요.
클라이언트를 다시 받아야 한다면 다운로드 페이지에서 안내된 경로를 확인하세요. iPhone / iPad에서는 개발자 이름 Shadow Launch Technology Limited와 앱 ID 932747118을 확인하고, 다른 플랫폼의 설치 파일은 사이트의 /dl/에서 제공합니다. 설치 차단 문제는 설치 허용 안내를 참고하세요. 규칙에 문제가 있다면 이 페이지의 해당 장으로 돌아와 단계별로 확인하고 설치 문제와 트래픽 분기 문제를 혼동하지 마세요.
첫 연결을 설정하는 것이 목적이라면 빠른 시작 가이드의 절차를 순서대로 따르세요. 특정 오류의 원인을 확인하려면 실제 요청을 기준으로 활성 파일, Global Routing, 매칭 조건, 최종 정책, 해석 결과, 연결 경로를 차례로 살펴보세요. 한 번에 관찰 가능한 문제 하나씩 해결해야 변경 사항과 결과를 연결할 수 있고, 되돌리는 방법도 명확하게 유지할 수 있습니다.