Shadowrocket 규칙 가이드

DOMAIN, DOMAIN-SUFFIX 및 DOMAIN-KEYWORD

도메인 규칙은 자주 바뀌는 서버 주소를 따라가기보다 이름을 기준으로 접근 정책을 표현할 때 적합합니다. 작성 전에 정확한 호스트 이름 하나를 매칭할지, 도메인 계열 전체를 매칭할지, 특정 문자열이 포함된 이름을 매칭할지 정한 다음 키워드를 선택하세요. 범위가 넓을수록 잘못 매칭될 가능성도 커집니다. 개인 구성을 관리할 때는 정확한 매칭부터 시작하고, 요청 기록에서 공통된 요구가 확인된 뒤 여러 개의 정확한 규칙을 접미사 규칙으로 통합하는 편이 좋습니다.

DOMAIN: 지정한 호스트 이름만 처리

[Rule]
DOMAIN,login.example.com,PROXY
DOMAIN,static.example.com,DIRECT
FINAL,DIRECT

DOMAIN은 전체 도메인 이름을 정확히 매칭합니다. 첫 번째 규칙은 login.example.com을 처리하며 api.login.example.com이나 example.com 전체까지 처리한다고 보면 안 됩니다. 규칙 필드에는 호스트 이름을 입력하고 프로토콜, 포트, URL 경로는 넣지 않습니다. 예를 들어 브라우저 주소창의 전체 주소에서는 이름 부분을 먼저 추출해야 합니다. 특정 경로만 처리하려는 경우 DOMAIN만으로는 조건을 표현할 수 없습니다.

한 페이지에서 로그인, 이미지, API, 통계용 호스트를 동시에 이용할 수 있습니다. 페이지 주소에 정확한 규칙을 추가해도 그중 하나의 이름만 다룰 수 있습니다. 페이지의 글자는 보이는데 이미지가 표시되지 않는다면 모든 이름에 규칙을 확대하기 전에 실패한 요청이 실제로 접속한 호스트를 확인하세요. 한 페이지를 열었을 때 발생하는 연결을 하나씩 살펴보면 필요한 리소스 도메인을 찾을 수 있고 다른 서비스의 정책을 불필요하게 바꾸지 않을 수 있습니다.

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

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

DOMAIN-SUFFIX는 지정된 도메인과 그 하위 도메인을 매칭합니다. 위 예시는 먼저 local.example.com을 직접 연결 예외로 두고, 나머지 example.com 도메인에 속하는 이름은 PROXY를 사용하도록 합니다. 이때 example.com을 입력하면 됩니다. 앞에 별표를 붙일 필요가 없으며 *.example.com을 같은 표기법으로 사용하지 마세요. 도메인 경계가 중요하므로 접미사 매칭을 문자열이 어디에든 나타나면 매칭되는 것으로 이해해서는 안 됩니다.

예외 규칙은 범위가 넓은 규칙보다 앞에 둬야 합니다. 위 예시의 첫 두 행을 바꾸면 접미사 규칙이 먼저 매칭되어 아래의 정확한 직접 연결 규칙은 결과를 바꿀 수 없습니다. 이는 DOMAIN의 우선순위가 낮아서가 아니라 Rule이 순서대로 처리되기 때문입니다. 더 구체적인 조건이 자동으로 높은 우선순위를 얻지는 않습니다. 파일 작성자가 규칙 배치로 의도를 표현해야 합니다. 예외를 추가할 때는 해당 예외보다 먼저 매칭될 수 있는 넓은 규칙을 모두 찾아 적절한 위치를 정하세요.

DOMAIN-KEYWORD: 범위가 넓으므로 경계를 먼저 확인

[Rule]
DOMAIN-KEYWORD,example,PROXY
FINAL,DIRECT

DOMAIN-KEYWORD는 도메인 이름에 지정한 키워드가 포함되어 있는지 확인하며, 특정 도메인 계열에 한정되지 않습니다. 위 예시는 문법 설명용이지 검토 없이 일상적으로 사용할 규칙은 아닙니다. 이름에 example이 들어 있다고 해서 같은 조직이나 업무에 속하는 것은 아니기 때문입니다. 키워드가 짧거나 흔한 의미일수록 잘못 매칭되기 쉽습니다. 정확한 도메인이나 접미사로 표현할 수 있는 요구라면 범위가 분명한 조건을 우선 사용하세요.

도메인 규칙을 검증할 때는 최소한 매칭되어야 하는 이름 하나와 매칭되면 안 되는 이름 하나를 준비하세요. 접미사 규칙이라면 루트 도메인과 하위 도메인도 포함해야 합니다. 키워드 규칙은 같은 문구를 포함하지만 대상 범위에는 속하지 않는 이름도 추가로 확인하세요. 이런 반례를 테스트하면 규칙 범위가 지나치게 넓은지 알아낼 수 있습니다. 대상이 열린다는 사실만으로는 원래 직접 연결되어야 할 다른 요청까지 프록시 경로로 전송되었는지 판단할 수 없습니다.

도메인에 국제화 문자가 포함되어 있다면 요청 기록에 실제로 표시된 이름을 확인한 뒤 클라이언트가 허용하는 형식으로 입력하세요. 공백이 포함된 표시 제목을 그대로 복사하거나 브라우저가 읽기 쉽게 표시한 문구를 최종 매칭값으로 간주하지 마세요. 규칙 수정 후 기존 페이지를 반복해서 새로고침하는 것도 흔한 실수입니다. 앱이 기존 연결을 재사용할 수 있으므로 새 요청을 만들고 새 연결에 수정된 정책이 적용되는지 확인해야 합니다.

규칙이 많아지면 '정확한 예외, 업무별 접미사, 신중하게 사용할 키워드'를 연속된 그룹으로 나눌 수 있지만 키워드 순서대로 기계적으로 정렬하지 마세요. 정렬 기준은 알파벳이 아니라 업무상 예외 관계여야 합니다. 지정한 웹사이트만 프록시를 이용하게 하려면 특정 웹사이트 라우팅 규칙을 참고하세요. 범위를 좁힌 목록부터 만들고 실제 리소스 요청에 따라 보완하면 관련 없는 이름을 한꺼번에 포함하지 않아도 됩니다.

Host와 URL Rewrite의 사용 범위

Host와 URL Rewrite는 모두 사용자에게 보이는 접속 결과를 바꿀 수 있지만 해결하는 문제는 다릅니다. Host는 주로 이름을 주소에 매핑하고, URL Rewrite는 보이는 URL을 기준으로 매칭해 처리합니다. Host는 프록시 정책이 아니며 URL Rewrite도 도메인 라우팅을 대신하지 않습니다. 필요한 기능을 판단할 때는 목표를 한 문장으로 정리하세요. 주소를 지정할지, 연결 경로를 선택할지, 특정 주소 형식을 다른 형식으로 바꿀지 확인하면 됩니다.

Host: 주소를 고정해도 출구 경로가 고정되지는 않습니다

[Host]
printer.example.com = 192.0.2.20

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

예시에서는 한 이름을 문서용 예시 주소에 매핑하고, Rule에서 해당 이름의 경로로 DIRECT를 선택합니다. 두 행은 각각 이름 해석과 경로 결정을 담당하므로 서로 대신할 수 없습니다. 실제로 사용할 때는 본인이 사용할 권한이 있고 현재 네트워크에서 도달할 수 있는 주소를 지정해야 합니다. 도메인을 특정 주소에 연결한다고 해서 원래 접근할 수 없던 네트워크에 연결할 수 있게 되거나, 인증·포트 전달·서버 측 가상 호스트 구성이 자동으로 마련되는 것은 아닙니다.

주소를 고정하면 기존의 동적 이름 해석이 더 이상 적용되지 않을 수도 있습니다. 대상이 주소 변경, 가까운 서버 선택, 장애 조치에 의존한다면 오래된 매핑을 계속 유지할 경우 연결 시간이 초과될 수 있습니다. 추가하기 전에 주소를 고정해야 하는 이유가 분명한지 확인하고 제거 방법도 기록하세요. 테스트할 때는 이름이 예상한 주소로 해석되는지뿐 아니라 서비스, 포트, 인증서의 신원도 예상과 일치하는지 확인해야 합니다. 주소가 응답한다는 사실만으로 서비스가 정상이라고 판단해서는 안 됩니다.

Host는 브라우저가 접속 중인 호스트 이름을 바꾸지 않습니다. HTTPS 이름에 접속할 때 서버 인증서는 여전히 해당 이름의 검증 조건을 충족해야 합니다. 해당 서비스를 제공하지 않는 주소에 이름을 매핑하면 인증서 오류나 엉뚱한 사이트가 표시될 수 있습니다. 검증을 무시하는 방식으로 해결해서는 안 됩니다. 대상 서비스가 해당 이름을 지원하는지, 승인된 테스트 환경에서 매핑을 사용하는지 확인하세요. 정상적인 이름 해석으로 복구한 다음 관련 캐시도 갱신되었는지 확인해야 합니다.

URL Rewrite: 정규식, 대상 및 동작

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

이 예시는 정규식으로 이전 주소를 매칭하고 캡처한 경로를 새 주소에 붙여 302 리디렉션을 반환합니다. 점 앞의 역슬래시는 실제 점 문자를 매칭하며, 시작·끝 앵커는 매칭 범위를 제한합니다. 괄호로 캡처한 값은 $1로 참조합니다. 두 도메인 모두 예시용입니다. 본인 구성에 적용하기 전에 테스트 권한이 있는 대상으로 바꾸고 쿼리 매개변수와 인코딩이 필요한 대로 유지되는지 확인하세요.

정규식에서 점은 기본적으로 특별한 의미를 가지므로 이스케이프를 빠뜨리면 대상이 아닌 이름까지 매칭할 수 있습니다. 호스트 경계를 생략해도 비슷해 보이는 다른 주소까지 포함될 수 있습니다. URL Rewrite를 관리할 때는 최소한 매칭되어야 할 예시, 비슷하지만 매칭되면 안 되는 예시, 경로와 쿼리 매개변수가 포함된 예시를 준비하세요. 경로가 없는 홈페이지 주소만 테스트해서는 안 됩니다. 홈페이지에서 성공해도 더 긴 URL이 올바르게 처리된다는 뜻은 아닙니다.

암호화로 인한 가시성 제한과 처리 단계

전체 HTTPS URL의 경로는 암호화된 내용에 포함되어 있으므로 일반적인 연결 라우팅이 그 안의 모든 필드를 자동으로 읽을 수는 없습니다. URL Rewrite가 대상에 적용될 수 있는지는 요청 정보의 가시성과 관련 처리 조건에 달려 있습니다. 정규식을 작성했다는 사실만으로 경로를 읽을 수 있는 조건이 갖춰졌다고 볼 수 없습니다. 리디렉션 규칙을 검증하기 위해 해독 범위를 바로 넓혀서도 안 됩니다. 인증서 및 암호화 처리 설정은 권한, 개인정보 보호, 앱 호환성을 따로 고려해야 합니다.

Rule의 위에서 아래로 처리 원칙을 구성 파일 전체가 위에서 아래로 한 번만 실행된다는 뜻으로 확대 해석해서는 안 됩니다. 각 구성 섹션은 서로 다른 기능을 맡으므로 파일에서 Host가 Rule보다 앞에 있다고 해서 반드시 문자 순서대로 먼저 실행되는 것은 아닙니다. URL Rewrite 문제를 확인할 때는 요청 흐름을 따라가세요. 원래 주소, 리디렉션 발생 여부, 리디렉션 후 대상, 이후 연결에 적용된 정책을 확인해야 합니다. 그래야 재작성 미적용, 리디렉션 대상 장애, 후속 라우팅 오류를 구분할 수 있습니다.

리디렉션이 반복되면 이번에 추가한 규칙을 먼저 비활성화하세요

새 대상이 다시 기존 규칙에 매칭되거나 사이트가 요청을 원래 주소로 되돌리면 순환이 발생할 수 있습니다. 원래 구성으로 복구해 정상 여부를 확인한 다음 정규식 범위를 좁히세요. 반대 방향의 리디렉션을 계속 추가하지 마세요.

브라우저가 리디렉션 결과를 캐시할 수 있고, 앱도 이름 해석과 연결을 캐시할 수 있습니다. 규칙을 취소했는데도 이전 동작이 남아 있다고 해서 파일이 저장되지 않은 것은 아닐 수 있습니다. 현재 구성을 확인하고 새 테스트 요청이나 별도의 테스트 세션으로 다시 확인하세요. 장기간 사용할 재작성 규칙에는 목적, 적용 호스트, 예상 동작, 삭제 조건을 기록하세요. 대상 사이트의 주소 구조가 바뀌었는데도 로컬 규칙이 오래된 절차를 강제하지 않도록 해야 합니다.

Host와 URL Rewrite는 범위가 좁고 이유를 설명할 수 있는 요구에 적합합니다. 모든 접속 문제를 해결하는 첫 번째 수단으로 사용해서는 안 됩니다. 특정 사이트에 PROXY를 사용하려는 것뿐이라면 도메인 규칙을 확인하세요. 이름 해석 결과가 잘못되었다면 먼저 DNS와 기존 매핑을 확인해야 합니다. 사이트에서 요청을 거부한다면 인증과 서비스 응답도 살펴봐야 합니다. 문제가 발생한 계층을 먼저 판단한 뒤 구성 섹션을 선택하면 파일이 간결해지고 문제도 재현하기 쉬워집니다.

매칭 검증, 문제 진단 및 구성 복구

규칙 검증의 목적은 한 번의 접속이 우연히 성공하게 만드는 것이 아닙니다. 지정한 요청이 의도한 조건에 매칭되어 예정된 정책을 사용하는 동시에 유지해야 할 동작을 해치지 않는지 확인하는 것입니다. 한 번의 테스트를 기록할 때는 테스트 시간, 현재 구성 이름, Global Routing, 대상 이름 또는 주소, 실제 매칭 결과, 연결 상태를 포함하세요. 시간은 해당 테스트를 비교하기 위한 정보일 뿐 앱 업데이트 정보를 뜻하지 않습니다. 근거를 구체적으로 남겨야 다음에 네트워크가 바뀌었을 때 이전 결과와 비교할 수 있습니다.

규칙 개수로 원인을 추측하지 말고 계층별로 확인

먼저 연결이 수립되었는지, 현재 파일이 선택되어 있는지 확인한 다음 요청이 예상한 처리 범위에 들어왔는지 살펴보세요. 이어서 이름 해석과 실제 대상을 확인하고, 최초로 매칭된 조건을 찾은 뒤 정책 출구가 사용 가능한지 점검하세요. 앞 단계에서 이미 실패했다면 뒷단을 수정해도 대개 효과가 없습니다. 예를 들어 이름 해석에 실패했다면 도메인 접미사를 더 추가해도 도움이 되지 않을 수 있습니다. PROXY가 매칭되었지만 서버 연결에 실패했다면 FINAL을 옮기는 것은 문제를 해결하는 방법이 아닙니다.

Connectivity Test는 기존 서버의 테스트 결과를 확인하는 데 도움이 될 수 있지만 모든 사이트, 프로토콜, 업무 요청이 사용 가능하다는 점을 증명하지는 않습니다. 테스트에 성공해도 실제 접속에서는 이름 해석, 대상의 요청 거부, 서비스 인증 문제를 만날 수 있습니다. 테스트 결과는 여러 근거 중 하나로 취급해야 하며 최종 결론으로 삼아서는 안 됩니다. 마찬가지로 웹페이지가 열렸다고 PROXY를 사용했다는 뜻도 아닙니다. 해당 요청의 정책 기록과 함께 확인해야 합니다.

정방향, 반대 방향, 회귀 테스트 사례 준비

정방향 테스트는 대상이 매칭되어야 한다는 점을, 반대 방향 테스트는 범위가 넓어지지 않았다는 점을, 회귀 테스트는 기존 기능이 계속 작동한다는 점을 확인합니다. 예를 들어 DOMAIN-SUFFIX를 추가한 뒤 루트 도메인과 하위 도메인 하나를 테스트하고, 해당 접미사에 속하지 않는 이름도 확인한 다음 로그인과 로컬 네트워크 접근을 점검할 수 있습니다. 테스트 목적으로 사용 권한이 없거나 용도를 모르는 대상을 방문할 필요는 없습니다. 본인이 접근 권한을 가진 목적이 분명한 서비스만 사용하세요. 예시 도메인은 문법 설명용입니다.

테스트할 때는 가능한 한 한 번에 하나의 변수만 바꾸세요. 서버, 네트워크, 실행 모드는 그대로 두고 규칙 하나만 조정한 뒤 결과를 비교하세요. 네트워크를 바꿔야 한다면 별도로 기록해 네트워크 변화로 인한 이름 해석 차이를 규칙 수정의 결과로 오인하지 않도록 하세요. 페이지가 연결을 재사용한다면 관련 테스트 세션을 종료하고 새 요청을 보내세요. 새 규칙은 새 연결로 확인하는 것이 일반적이며, 기존 연결이 계속되는 동작만으로 판단해서는 안 됩니다.

로그 공유 시 민감 정보 처리

문제 해결을 위해 기록을 공유해야 한다면 재현에 필요한 대상, 규칙, 정책, 오류 정보만 남기세요. 구독 링크의 인증 매개변수, 서버 비밀번호, 비공개 요청 경로, 계정 식별 정보, 전체 구성에 포함된 인증 정보는 먼저 삭제해야 합니다. 스크린샷에도 이러한 정보가 담길 수 있으므로 이미지라고 해서 확인을 건너뛰지 마세요. 민감한 정보는 알아보기 쉬운 예시 값으로 바꾸고 어떤 필드를 교체했는지 설명해야 재현 가능성과 정보 보호를 함께 지킬 수 있습니다.

문제를 좁혀야 한다면 최소 테스트 구성을 만들 수 있습니다. 필요한 General 설정, 대상 규칙 하나, FINAL 하나만 남기고 본인이 이미 보유한 서버를 계속 사용하세요. 최소 구성에서 정상 작동하면 원래 규칙을 그룹별로 복원해 차이를 일으키는 부분을 찾으세요. 복원할 때는 그룹 안의 원래 순서를 유지하고 파일 전체를 한꺼번에 재정렬하지 마세요. 이를 통해 문제가 특정 조건, 외부 참조, 예외 간 순서 중 어디에서 비롯되었는지 확인할 수 있습니다.

복구 후에도 실행 상태를 다시 확인하세요

되돌리기는 텍스트만 원래대로 바꾸는 작업이 아닙니다. 원래 구성을 다시 선택하고 Global Routing 및 기존 서버 선택을 확인한 뒤 필요한 경우 연결을 새로 수립하고 이전에 정상이었던 테스트 사례와 비교하세요. 원래 구성으로 복구한 뒤에도 문제가 지속된다면 네트워크, 서버, 대상 서비스에 변화가 있었는지 고려해야 합니다. 모든 문제를 이번 편집의 탓으로 돌리지 마세요. 수정 전후의 파일 두 개와 간단한 기록을 남기면 기억에 의존해 반복해서 복구하다가 새로운 차이를 만들지 않을 수 있습니다.

수정 완료 여부를 판단하는 기준

대상이 올바르게 매칭되고, 예외 규칙이 다른 요청에 영향을 주지 않으며, 일상적인 요청이 회귀 테스트를 통과하고, 수정 전 상태로 되돌릴 수 있어야 합니다. 네 가지를 모두 확인한 뒤 테스트 복사본을 장기 구성으로 사용하세요.

기기를 변경해 복구할 때는 먼저 앱을 App Store에서 받았는지 확인하고, 직접 저장해 둔 서버 정보와 구성 파일을 복원한 다음 현재 구성과 시스템 연결 권한을 다시 확인하세요. 구체적인 시스템 요구 사항은 App Store 페이지에 표시된 내용을 기준으로 합니다. 구입 및 앱 재다운로드 관련 내용은 구입 항목 복원 안내와 해당 페이지의 구입 관련 자주 묻는 질문을 확인하세요. 처음 연결하는 단계는 사용 방법 안내에서 확인하고, 규칙의 의미는 이 페이지의 목차를 따라 하나씩 살펴보세요.

장기간 관리할 때는 안정 버전과 테스트 버전을 각각 하나씩 두는 방법이 좋습니다. 안정 버전에는 검증된 변경 사항만 적용하고, 테스트 버전은 새로운 조건과 재현 실험에 사용하세요. 더는 필요하지 않은 예외를 정기적으로 정리하고, 고정 주소가 여전히 유효한지 확인하며, 원격 구성을 업데이트한 뒤 개인 규칙을 다시 점검하세요. 규칙 파일의 가치는 길이가 아니라 각 조건의 목적을 설명할 수 있는지, 결과를 확인할 수 있는지, 수정 사항을 되돌릴 수 있는지에 달려 있습니다.