Shadowrocket 설정 항목
및 규칙 참고 가이드

설정 파일 구조: 먼저 섹션별 역할을 구분하세요

Shadowrocket 설정 파일은 보통 .conf 형식으로 작성합니다. 대괄호 안의 이름은 섹션을 나타내고, 각 섹션의 행은 설정, 매핑 또는 규칙을 뜻합니다. 설정 파일은 모든 값을 한데 모아 나열한 목록이 아닙니다. 같은 문구라도 섹션에 따라 의미가 완전히 달라지거나 파싱되지 않을 수 있습니다. 낯선 설정 파일을 살펴볼 때는 특정 도메인을 바로 검색하기보다 먼저 섹션 경계를 확인하고 각 항목을 읽어야 파일 전체의 의도를 파악하기 쉽습니다.

자주 쓰이는 네 섹션의 역할

[General]에는 DNS 관련 옵션과 같은 일반 동작 설정을 둡니다. [Rule]은 트래픽의 매칭 조건과 적용할 정책을 지정합니다. [Host]는 특정 도메인을 주소에 매핑합니다. [URL Rewrite]는 표현식에 맞는 URL을 처리합니다. 각 기능은 서로 다른 처리 단계에 있으므로 서로 대체할 수 없습니다. 도메인을 직접 연결하려면 먼저 규칙을 검토하세요. 트래픽 경로를 바꾸기 위해 도메인 해석 결과를 임의로 수정해서는 안 됩니다.

간단한 예제로 문법 이해하기

다음 예제는 섹션, 대입, 규칙의 세 가지 작성 방식을 보여줍니다. 등호는 설정값을 지정할 때, 쉼표는 규칙의 필드를 구분할 때 사용하므로 서로 바꿔 쓸 수 없습니다. 규칙의 PROXY는 정책이지 서버 주소가 아닙니다. 예제에는 사용자의 서버 정보가 없으므로 규칙 구조를 설명하는 용도로만 참고하세요. 사용하려면 앱에 사용할 수 있는 기존 서버를 준비하고 현재 선택된 연결 대상을 확인해야 합니다.

[General]
dns-server = system

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

한 줄씩 읽을 때는 먼저 영문 쉼표와 등호를 확인한 다음 키워드, 매개변수 개수와 정책 이름을 살펴보세요. 한국어 입력기에서 입력한 전각 문장 부호는 비슷해 보여도 유효한 구분자로 인식되지 않을 수 있습니다. 섹션 이름은 원문 그대로 유지해야 합니다. 행의 앞뒤에 붙은 보이지 않는 문자나 복사 과정에서 섞인 서식 기호도 올바른 규칙을 무효화할 수 있습니다. 일반 텍스트 편집을 사용하고 빈 줄을 적절히 남겨 두세요.

전체 설정 파일과 규칙 예제의 차이

이 페이지의 코드 블록 대부분은 관련 섹션만 보여 줍니다. 각 코드 블록을 하나의 파일에 차례로 모두 붙여 넣으면 안 됩니다. 서로 독립적인 상황을 설명하는 예제일 수 있으며, 특히 여러 개의 FINAL을 다단계 대체 규칙처럼 쌓아 두어서는 안 됩니다. 기존 파일에 예제를 반영할 때는 해당 섹션에 합치고, 같은 유형의 규칙이 이미 있는지 확인한 뒤 삽입 위치를 정하세요. 중복 섹션과 서로 반대되는 정책이 늘어나면 설정을 읽고 관리하기 어려워집니다.

서버 구독과 설정 파일은 서로 다른 데이터입니다. 구독은 보통 서버 항목을 제공하거나 업데이트하고, 설정 파일은 연결 동작을 정합니다. 둘 중 하나가 있다고 해서 나머지도 준비된 것은 아닙니다. 구독은 서비스 제공업체에서 받아야 하며, 형식은 가져오기 메뉴에서 지원하는 형식이어야 합니다. 링크 종류가 헷갈린다면 구독 가져오기 방식 안내를 먼저 확인하세요. 링크 형식 문제를 해결하려고 설정을 반복해서 바꾸지 마세요.

이 장의 목표는 모든 섹션을 채우는 것이 아니라 각 섹션의 역할을 설명할 수 있는 것입니다. 목적이 분명하지 않은 기능은 추가하지 않아도 됩니다. 짧고 이해하기 쉬운 설정일수록 검증하기 편합니다. 낯선 항목은 앱 내 안내와 실제 동작을 먼저 확인하세요. 다른 설정 파일에 들어 있다는 이유만으로 현재 기기와 네트워크에도 적합하다고 단정해서는 안 됩니다.

General: 일반 설정 및 Global Routing

[General]은 설정 파일의 일반 옵션 섹션이고, Global Routing은 실행 중 라우팅 모드를 선택하는 메뉴입니다. 서로 관련은 있지만 같은 단계에 있지는 않습니다. 텍스트 파일에 규칙을 작성했더라도 현재 모드에서 해당 규칙을 사용하는지 확인해야 합니다. 규칙이 있는데도 적용되지 않는다면 필드를 계속 추가하기 전에 모드와 현재 설정 파일부터 점검하세요. 잘못된 전제를 바탕으로 규칙만 계속 늘릴 수 있습니다.

Config, Proxy, Direct 세 가지 모드

설정 모드인 Config는 현재 설정에 따라 연결을 처리합니다. 프록시 모드인 Proxy는 일반적으로 앱이 처리하는 연결을 프록시 방향으로 보냅니다. 직접 연결 모드인 Direct는 연결을 직접 보내는 데 사용합니다. 이는 전체적으로 선택한 동작을 설명할 뿐, 시스템의 모든 연결이 반드시 같은 경로를 거친다는 뜻은 아닙니다. 시스템의 기본 동작, 기존 연결 및 처리 범위에 들어오지 않는 트래픽은 모드 이름만으로 판단할 수 없습니다.

같은 대상이 Proxy에서는 접속되지만 Config에서는 실패한다면 규칙 매칭, DIRECT 경로와 DNS 차이를 확인할 수 있습니다. 다만 이것만으로 특정 규칙이 잘못됐다고 단정할 수는 없습니다. 테스트 전후에 서버, 대상 및 네트워크 조건을 동일하게 유지하세요. 비교가 끝나면 원래 모드로 되돌려 임시 테스트 상태가 일상적인 사용 상태로 남지 않도록 하세요. 그래야 이후의 동작을 설정 파일과 연결해 이해할 수 있습니다.

DNS 설정은 트래픽 정책이 아닙니다

DNS는 도메인을 주소로 변환하고, 규칙은 연결을 어떻게 처리할지 결정합니다. 도메인이 올바르게 해석되어도 대상에 연결할 수 있다는 보장은 없습니다. PROXY를 선택했다고 해서 모든 DNS 요청의 처리 경로를 추론할 수도 없습니다. DNS는 앱 설정, 캐시, 네트워크 환경 및 요청 방식의 영향을 받습니다. ‘어떤 주소로 해석됐는가’와 ‘연결에 어떤 정책이 적용됐는가’를 별개의 문제로 확인하세요.

[General]
dns-server = system

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

dns-server = system은 이 항목의 설정값으로 시스템 DNS 설정을 사용한다는 뜻이지, 현재 네트워크의 해석 결과가 항상 적절하다는 보장은 아닙니다. 문법을 익히기 위한 출발점으로는 적합하지만 모든 환경에 적용할 정답은 아닙니다. DNS 처리 방식을 바꿔야 한다면 먼저 기존 값을 기록하고 한 번에 하나씩 변경하세요. 대상 도메인과 자주 사용하는 다른 도메인을 각각 확인해 한 대상만 해결하고 나머지 요청에 영향을 주는 상황을 방지하세요.

기본값과 명시적 설정의 차이

일반 설정 항목을 삭제하면 보통 기본 처리 방식으로 돌아갑니다. 특정 불리언 값으로 설정하는 것과 반드시 같은 의미는 아닙니다. 기본 동작은 앱 설정의 영향도 받을 수 있으므로 ‘이 행이 없다’고 해서 해당 기능이 반드시 꺼졌다고 해석하지 마세요. 설정을 옮길 때는 목적이 분명한 항목만 유지하세요. 의미가 불분명한 옵션은 사본에서 먼저 시험하고, 이른바 최적화 설정을 한꺼번에 복사하지 마세요.

IPv6, DNS 및 네트워크 범위 설정은 규칙이 확인할 수 있는 연결 정보에도 영향을 줍니다. 예를 들어 대상이 IPv6 주소를 우선 사용하지만 설정에는 IPv4 대역만 있다면 일반 옵션 하나를 추가하는 것만으로 현상을 모두 설명할 수 없습니다. 먼저 실제 연결 주소를 확인한 뒤 주소 규칙을 추가할지, DNS 동작을 조정할지, 기본값을 유지할지 결정하세요. 주소 체계를 변경하면 다른 서비스에도 영향을 줄 수 있으므로 충분히 다시 테스트해야 합니다.

On Demand와 설정 규칙은 따로 관리

On Demand는 언제 연결을 시작할지를 다루고, [Rule]은 연결이 처리 단계에 들어온 뒤 어떻게 라우팅할지를 다룹니다. 도메인 규칙을 On Demand의 연결 트리거 설정처럼 작성해서는 안 됩니다. 시스템이 자동 연결됐다는 이유만으로 특정 규칙이 매칭됐다고 볼 수도 없습니다. 먼저 앱 내 메뉴에서 On Demand 조건을 확인한 다음 설정 규칙을 별도로 검증하세요. 두 과정의 결과를 각각 기록해야 문제를 분명하게 구분할 수 있습니다.

일반 설정의 목표는 동작을 예측할 수 있게 하는 것이지 파일을 최대한 복잡하게 만드는 것이 아닙니다. 현재 모드가 Config인지, 의도한 설정 파일을 사용 중인지, 선택한 서버를 사용할 수 있는지 확인한 뒤 규칙을 살펴보세요. 기본 연결조차 확인하지 못했다면 빠른 시작 안내로 돌아가 시스템 권한 및 연결 절차를 점검하세요. 이 페이지의 이후 내용은 기본 연결을 확인할 수 있는 상태를 전제로 합니다.

도메인 규칙: 정확한 도메인, 접미사 및 키워드

도메인 규칙은 ‘어떤 호스트에 어떤 정책을 적용할지’를 지정하는 데 적합합니다. 서비스 주소가 바뀔 때마다 추적하는 것보다 관리하기 쉬운 경우가 많지만, 연결 처리 시 해당 도메인 정보를 확인할 수 있어야 합니다. 페이지에 표시된 URL, 앱이 실제로 연결하는 호스트, 로그인 서비스 및 리소스 도메인은 서로 다를 수 있습니다. 브라우저 주소창의 기본 도메인만 복사하면 한 번의 접속에서 발생하는 모든 요청을 처리할 수 있다고 가정하지 마세요.

DOMAIN: 전체 호스트 이름만 매칭

DOMAIN은 완전한 도메인 이름을 매칭합니다. 아래 첫 번째 규칙은 api.example.com만 지정하며 다른 같은 수준의 호스트까지 자동으로 포함하지 않습니다. 도메인 필드에 프로토콜, 경로 또는 포트를 넣어서는 안 됩니다. https://와 /login은 URL의 다른 요소이므로 DOMAIN 필드에 넣어도 페이지 경로별 라우팅을 설정할 수 없습니다. 특정 접속 지점을 정확히 제어하려면 적용 범위가 분명한 이 방식을 우선 고려하세요.

[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,files.example.com,DIRECT
FINAL,PROXY

정확한 규칙을 관리할 때는 각 예외에 짧은 주석을 달아 다른 호스트와 다르게 처리하는 이유를 기록할 수 있습니다. 주석에는 서비스 용도나 테스트 결과를 적고 계정, 토큰 및 민감한 전체 링크는 남기지 마세요. 정확한 규칙이 많아지면 먼저 서비스별로 정리한 뒤 접미사 규칙이 실제로 필요한지 검토하세요. 몇 줄을 줄이려고 매칭 범위를 넓히면 의도치 않은 매칭이 늘어날 수 있습니다.

DOMAIN-SUFFIX: 루트 도메인과 하위 도메인 포함

DOMAIN-SUFFIX,example.com,PROXY는 example.com과 그 하위 도메인에 적용됩니다. 예를 들어 www.example.com과 api.example.com이 해당합니다. 도메인 접미사의 경계를 기준으로 매칭하며 임의의 문자열 포함 여부를 확인하는 것은 아닙니다. 철자가 비슷한 다른 도메인까지 자동으로 포함된다고 보아서는 안 됩니다. 보통 루트 도메인 형식으로 작성하고 앞에 별표를 붙이거나 뒤에 경로를 추가하지 마세요.

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

이 순서는 먼저 예외를 처리한 다음 일반 범위를 적용한다는 뜻입니다. local.example.com에 접속하면 앞쪽의 정확한 규칙이 먼저 매칭되고, 다른 해당 하위 도메인에는 접미사 규칙이 적용됩니다. 접미사 규칙을 앞에 두면 뒤에 있는 정확한 규칙이 더 구체적이라는 이유만으로 우선 적용되지는 않습니다. 규칙은 브라우저의 스타일 선택자처럼 전체 목록에서 가장 세밀한 항목을 다시 계산하지 않습니다.

DOMAIN-KEYWORD: 범위를 검토한 뒤 사용

DOMAIN-KEYWORD는 도메인에 특정 키워드가 포함되어 있는지 확인하므로 고정된 도메인보다 적용 범위가 넓습니다. 같은 키워드가 서로 관련 없는 여러 도메인에 나타날 수 있으므로 공통된 작명 규칙이 실제로 있고 영향 범위를 파악한 경우에 적합합니다. 브랜드명, 짧은 약어 또는 흔한 영어 단어를 정확한 서비스 범위로 간주해서는 안 됩니다. 무관한 연결까지 같은 정책에 포함될 수 있습니다.

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

위 예제는 키워드 규칙의 문법만 보여 주며 일상적인 라우팅 설정으로 바로 사용하는 것은 권장하지 않습니다. 이 규칙은 사이트 소속, 서비스 종류 또는 페이지 내용이 아니라 문자열을 기준으로 매칭합니다. 연결 기록에 안정적인 전체 호스트 이름이 표시된다면 DOMAIN 또는 DOMAIN-SUFFIX를 우선 고려하세요. 규칙의 의미를 설정 파일에서 바로 파악할 수 있고 제한된 테스트로 확인하기도 쉽습니다.

한 번의 접속에 여러 규칙이 필요한 이유

로그인, 이미지, API 및 미디어 리소스가 서로 다른 도메인을 사용할 수 있습니다. 메인 페이지는 열리지만 로그인이 실패한다면 모호한 키워드 범위를 넓히기보다 실패한 연결의 실제 호스트를 확인하세요. 분명한 도메인을 하나씩 추가한 뒤 재시도하여 새 규칙이 해당 연결을 실제로 바꿨는지 확인합니다. 리디렉션이 있다면 리디렉션 후 대상도 확인해야 합니다. 최초 접속 지점이 매칭됐다고 해서 최종 대상에도 같은 정책이 적용된다는 뜻은 아닙니다.

연결 기록에 도메인 없이 주소만 표시된다면 DOMAIN 규칙을 더 추가해도 효과가 없을 수 있습니다. 요청이 주소를 직접 사용하는지, 도메인 정보를 확인할 수 있는지, 주소 규칙이 먼저 매칭되는지 살펴보세요. 도메인 규칙은 알려진 호스트를 매칭하는 기능이지 서비스를 찾아주는 기능이 아닙니다. 자주 묻는 질문의 라우팅 문제 해결 항목과 함께 확인할 수도 있습니다.

주소 및 요청 조건: GEOIP, IP-CIDR, USER-AGENT

대상이 주소로 표시되거나 네트워크 대역으로 접근 범위를 지정해야 할 때는 주소 규칙을 사용할 수 있습니다. 도메인 규칙과의 가장 큰 차이는 매칭 대상입니다. 도메인은 호스트 이름을, 주소 규칙은 연결 대상 주소를 다룹니다. 하나의 도메인이 여러 주소로 해석될 수 있고 하나의 주소에 여러 도메인이 연결될 수도 있습니다. 따라서 주소 규칙은 범위가 분명한 네트워크 대역에 적합하며, 근거 없이 모든 도메인 규칙을 대체하는 용도로는 적절하지 않습니다.

IP-CIDR: 주소와 프리픽스 길이

IP-CIDR은 IPv4 주소와 프리픽스 길이로 네트워크 대역을 지정합니다. 슬래시 뒤의 숫자는 네트워크 프리픽스 비트 수이며 포트나 연결 개수가 아닙니다. 숫자가 클수록 적용 범위는 좁아집니다. 단일 IPv4 주소는 /32로 표현할 수 있습니다. 작성 전에 실제 네트워크 범위를 확인하세요. 기기 하나의 주소를 너무 넓은 대역으로 잘못 지정하면 다른 연결까지 같은 정책에 포함될 수 있습니다.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
FINAL,PROXY

이 예제는 흔히 쓰이는 사설 주소 대역을 직접 연결하려는 설정을 보여 줍니다. 모두 추가해야 하는지는 기기가 연결된 네트워크에 따라 다릅니다. 규칙은 앱이 처리하는 범위에 적용할 정책만 결정하며 라우터가 접근을 허용하는지 보장하거나 로컬 네트워크 권한 및 대상 기기의 접근 설정을 대신하지 않습니다. 대상이 실제로 다른 네트워크에 있다면 DIRECT만 지정해도 그 네트워크로 연결 경로가 생기지는 않습니다.

no-resolve의 역할과 주의점

no-resolve는 주소 규칙의 추가 옵션으로, 이 규칙을 시도하기 위해 도메인 조회를 실행하지 않도록 합니다. ‘DNS 끄기’를 뜻하지 않으며 이후 연결에 주소 해석이 필요 없다는 의미도 아닙니다. 대상이 이미 주소라면 네트워크 대역을 기준으로 판단할 수 있습니다. 도메인만 있고 사용할 수 있는 주소가 없다면 이 규칙이 먼저 조회한 뒤 적용될 것으로 기대해서는 안 됩니다. 불필요한 조회를 줄이기 위해 로컬 네트워크 주소 규칙에서 이 옵션을 자주 사용합니다.

도메인이 해석된 주소의 소속에 따라 라우팅하려는 경우에는 no-resolve를 추가하기 전에 매칭 조건이 어떻게 달라지는지 이해해야 합니다. 문제를 확인할 때는 이 옵션을 반복해서 추가하거나 삭제하기보다 ‘사용할 주소 정보가 있는 요청’과 ‘주소 정보가 없는 요청’을 비교하는 편이 유용합니다. 주소 규칙의 이 옵션을 DOMAIN이나 FINAL 행에 기계적으로 복사하지 마세요. 규칙마다 요구하는 필드가 다릅니다.

GEOIP: 주소 위치 데이터에 따라 매칭

GEOIP는 주소 위치 데이터에 따라 지역을 판별합니다. 예를 들어 아래의 CN은 해당 지역 코드입니다. 페이지의 표시 언어, 기업 소재지 또는 도메인 접미사를 기준으로 판단하지 않습니다. 서비스가 여러 지역에 분산되어 있으면 주소의 지역이 사용자의 예상과 다를 수 있고 데이터가 최신이 아닐 수도 있습니다. 안정적으로 예외를 적용해야 한다면 지역 규칙에 서비스 식별을 맡기지 말고 명확한 도메인 규칙을 앞에 두세요.

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

이 예제는 api.example.com에 명확한 정책을 먼저 적용한 뒤 나머지 연결에 지역 매칭을 시도합니다. 앞쪽 예외 규칙이 없다면 해당 도메인이 조건에 맞는 주소로 해석될 경우 DIRECT가 적용될 수 있습니다. 설정이 예상대로 동작하는지는 실제 매칭 규칙과 대상 주소를 확인해야 하며 사이트 이름만으로 판단할 수 없습니다. 주소 데이터베이스 관련 동작은 현재 앱에서 이용 가능한 데이터와 설정도 함께 확인하세요.

IP-CIDR6 및 USER-AGENT의 적용 범위

IP-CIDR6는 IPv6 네트워크 대역을 지정합니다. 아래 주소는 문서용 예시 범위로 프리픽스 작성법만 보여 주며 실제 서비스 주소로 사용할 수 없습니다. IPv4 규칙이 IPv6 대상까지 자동으로 처리하지는 않습니다. 연결이 실제로 IPv6를 사용한다면 필요한 범위를 별도로 설정해야 합니다. IPv4 규칙이 매칭되지 않는다는 이유만으로 전체 규칙 목록이 작동하지 않는다고 단정하지 마세요.

[Rule]
IP-CIDR6,2001:db8::/32,PROXY
USER-AGENT,ExampleClient*,PROXY
FINAL,DIRECT

USER-AGENT는 요청에서 확인할 수 있는 User-Agent 정보를 사용하며 와일드카드 형태로 문자열을 지정할 수 있습니다. 예제의 ExampleClient는 설명용 값이지 실제 앱을 가리키지 않습니다. 기기에 설치된 앱 이름이나 프로세스를 기준으로 매칭하는 규칙이 아닙니다. 요청에 해당 정보가 없거나 확인할 수 없고 클라이언트가 식별 값을 변경하면 기대한 범위에 적용되지 않을 수 있습니다.

특히 암호화된 연결에서 일반적인 라우팅 처리가 HTTP 요청 헤더를 읽을 수 있다고 가정해서는 안 됩니다. USER-AGENT 규칙을 적용하기 위해 복호화 범위를 무턱대고 넓히지 마세요. 이 페이지의 기본 라우팅 예제에는 이런 처리가 필요하지 않습니다. 보통은 명확하게 확인하고 검증할 수 있는 도메인 또는 주소 조건을 우선 사용하고, USER-AGENT는 적용 조건이 있는 보조 수단으로 다루세요. 서비스를 식별하는 범용 방법은 아닙니다.

정책 및 우선순위: 먼저 매칭된 규칙이 결정합니다

규칙의 왼쪽은 조건을, 오른쪽은 매칭된 뒤 적용할 정책을 나타냅니다. PROXY, DIRECT, REJECT는 가장 흔히 쓰이는 정책 키워드로 각각 프록시, 직접 연결 및 거부를 뜻합니다. 규칙이 매칭됐다고 해서 대상에 반드시 접속할 수 있는 것은 아닙니다. 매칭은 처리 방식이 선택됐다는 뜻일 뿐, 이후 서버 사용 불가, 대상의 거부 또는 네트워크 조건으로 연결이 실패할 수 있습니다. ‘정책이 올바르게 선택됐는가’와 ‘해당 경로를 사용할 수 있는가’를 따로 확인하세요.

PROXY와 DIRECT 모두 사용 가능한 연결 경로가 필요합니다

PROXY는 현재 선택된 프록시를 통해 처리하지만 서버 정보가 없을 때 사용할 수 있는 연결을 자동으로 설정하지 않습니다. 선택한 서버를 사용할 수 없다면 규칙이 올바르게 작성되어도 연결은 실패합니다. DIRECT는 기기가 현재 네트워크를 통해 대상에 접근할 수 있어야 합니다. 프록시보다 더 나은 문제 해결 방법이라는 뜻은 아닙니다. 두 경로 모두 같은 대상에 실제로 요청해 확인하세요. 규칙 문구만 보고 속도나 안정성을 판단할 수 없습니다.

REJECT는 매칭된 요청을 명시적으로 거부합니다. 이는 관리 목적을 표현하는 정책이지 연결 실패 후 사용할 대체 정책이 아닙니다. 넓은 도메인 범위에 REJECT를 적용하기 전에 로그인, 인증 및 리소스 API까지 포함되는지 확인하세요. 그렇지 않으면 메인 페이지는 열리지만 일부 기능이 계속 실패할 수 있습니다. 이런 문제를 해결할 때는 서버 설정부터 바꾸지 말고 거부 기록을 먼저 확인하세요.

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

구체적인 규칙을 넓은 규칙보다 앞에 두세요

규칙은 보통 목록 위에서 아래로 확인하며, 먼저 매칭된 규칙의 정책을 적용합니다. 모든 조건을 확인한 뒤 ‘가장 구체적인 규칙’을 선택하지 않습니다. 위 예제는 먼저 두 가지 예외를 처리한 뒤 나머지 example.com 범위에 접미사 규칙을 적용합니다. 접미사 규칙을 첫 줄로 옮기면 앞쪽 범위가 두 예외를 먼저 포함하게 됩니다. 설정을 읽을 때는 원하는 규칙이 있는지만 찾지 말고 실행 흐름처럼 한 줄씩 판단하세요.

우선순위는 키워드 자체가 아니라 목록에서의 위치로 정해집니다. DOMAIN이 DOMAIN-SUFFIX보다 본래 우선하는 것도 아니고 도메인 규칙이 주소 규칙보다 본래 우선하는 것도 아닙니다. 관리자가 이해하기 쉽도록 ‘명확한 예외, 서비스 범위, 네트워크 범위, 최종 정책’ 순으로 구성할 수 있지만 이는 정리 방식일 뿐 앱이 자동으로 순서를 재배치하지 않습니다. 가져온 뒤 실제 목록을 확인해 편집한 규칙이 의도한 순서를 유지하는지 점검하세요.

FINAL은 최종 대체 규칙이지 자동 장애 전환이 아닙니다

FINAL에는 도메인이나 주소 조건이 필요하지 않습니다. 보통 규칙 목록 끝에 두고 앞의 규칙이 매칭되지 않을 때 적용할 경로를 지정합니다. 앞선 연결이 실패하면 실행하라는 지시가 아닙니다. 어떤 규칙이 PROXY에 매칭됐는데 프록시 연결이 실패해도 다음 줄의 DIRECT가 자동으로 이어받지 않습니다. 조건 매칭과 연결 경로 장애는 서로 다른 문제입니다. 둘을 혼동하면 잘못된 대체 동작을 설계하게 됩니다.

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

이 예제는 지정된 범위에만 PROXY를 적용하고 나머지는 DIRECT로 처리합니다. 마지막 줄을 FINAL,PROXY로 바꾸면 앞선 규칙에 매칭되지 않은 요청은 프록시 경로를 사용합니다. 두 방식 모두 의도를 명확히 표현할 수 있으며 모든 상황에 통하는 단일 정답은 없습니다. 어떤 서비스에 명확한 예외가 필요한지 목록으로 정리한 뒤 최종 정책을 바꾸고, 별도 규칙이 없는 대상도 다시 테스트하세요. 규칙에 추가한 도메인만 시험해서는 안 됩니다.

규칙을 하나씩 따라가며 충돌 확인

대상을 기준으로 규칙을 직접 확인할 때는 실제 도메인과 주소를 기록한 뒤 첫 번째 규칙부터 ‘현재 정보가 조건에 맞는가?’를 판단하세요. 처음 매칭되는 규칙을 찾으면 확인을 멈추고 정책과 위치를 기록합니다. 예상과 실제 연결 기록이 다르면 현재 설정 파일, DNS 결과, 기존 연결 및 동일한 대상 정보가 확인됐는지 살펴보세요. 이 방식은 넓은 규칙이 가리는 예외, 잘못된 예외 및 최종 정책 누락을 각각 구분하는 데 도움이 됩니다.

우선순위를 표현하려고 같은 규칙을 반복해서 추가하지 마세요. 여러 FINAL을 두고 실행 결과를 추측해서도 안 됩니다. 중복 규칙을 삭제하기 전에 정책이나 추가 옵션이 서로 다른지 먼저 확인하세요. 규칙을 합친 뒤에는 의미를 설명할 수 있는 순서로 남겨 두세요. 유지 관리가 잘됐다는 기준은 규칙이 많다는 것이 아니라 자주 사용하는 대상이 ‘왜 이 행에 매칭됐는지’를 설명할 수 있다는 점입니다. 정책은 맞는데 연결이 실패한다면 같은 조건의 규칙을 더 쌓지 말고 연결 문제를 진단하세요.

Host 및 URL Rewrite: 주소 매핑과 URL 처리

[Host]와 [URL Rewrite]는 규칙 파일에서 자주 볼 수 있지만 라우팅 규칙의 다른 표기가 아닙니다. Host는 지정된 도메인의 주소 매핑을 바꾸고, URL Rewrite는 표현식에 맞는 URL을 처리하며, Rule은 연결 정책을 결정합니다. ‘이름에 대응하는 주소’, ‘요청 URL’, ‘연결 경로’ 중 무엇을 바꾸려는지 먼저 구분해야 적절한 섹션을 선택할 수 있습니다. 여러 곳을 수정해 결과를 설명하기 어려워지는 일을 피하세요.

Host 매핑에는 실제로 유효한 대상 주소가 필요합니다

아래 Host 예제는 전체 호스트 이름을 문서용 예시 주소에 연결합니다. 이 주소는 형식을 설명하기 위한 것으로 실제 서비스 접속에 사용할 수 없습니다. 실제로 사용하려면 대상 주소를 알고 있어야 하고, 서비스가 해당 호스트 이름을 지원하며, 주소 변경을 관리할 수 있어야 합니다. 공유 호스팅, 로드 밸런싱 및 서비스 이전으로 고정 주소가 더 이상 유효하지 않을 수 있습니다.

[Host]
api.example.com = 192.0.2.10

[Rule]
DOMAIN,api.example.com,PROXY
FINAL,PROXY

Host 행 자체에는 DIRECT 또는 PROXY가 지정되어 있지 않습니다. 예제의 연결 정책은 Rule 섹션에서 정합니다. 주소 매핑이 성공했다고 해서 정책까지 올바르다는 뜻은 아닙니다. 도메인이 지정한 주소로 해석되더라도 대상이 해당 서비스를 올바르게 제공해야 하며 인증서도 접속에 사용하는 호스트 이름과 일치해야 합니다. 인증서 또는 호스트 오류가 발생하면 매핑을 원래대로 되돌리고 대상을 확인하세요. 주소 선택 문제를 가리려고 검증 기준을 낮추지 마세요.

이전에 접속되던 도메인이 고정 매핑 후 실패한다면 먼저 해당 Host 행을 삭제하거나 원래대로 되돌린 뒤 같은 조건으로 다시 시도하세요. 서비스 주소가 바뀌었거나 네트워크가 도달 가능한 주소를 다르게 반환할 수 있습니다. 매핑 전후의 결과를 기록해야 문제가 매핑으로 인한 것인지 판단할 수 있습니다. 계속 관리할 수 없는 도메인이라면 주소를 직접 고정하기보다 일반적인 DNS 해석을 유지하는 편이 일관성을 지키기 쉽습니다.

URL Rewrite의 세 가지 요소

URL Rewrite에는 보통 매칭 표현식, 대체 대상 및 처리 동작이 포함됩니다. 아래 예제는 지정된 예시 도메인의 HTTP URL을 HTTPS로 리디렉션하는 형식을 보여 줍니다. 표현식은 주소 시작 부분부터 매칭하고 괄호로 경로를 캡처합니다. 대체 부분은 $1로 캡처한 내용을 참조하며, 끝의 302는 리디렉션 동작을 뜻합니다. 독립적인 문법 예제일 뿐 모든 웹사이트에 같은 규칙을 추가해야 한다는 의미는 아닙니다.

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

표현식에서 점은 이스케이프해야 도메인의 문자 그대로의 마침표를 나타낼 수 있습니다. 이스케이프하지 않은 점은 정규식에서 더 넓은 의미를 가질 수 있습니다. 앞의 ^는 URL 시작 위치부터 매칭하도록 지정해 비슷한 문구가 포함된 다른 주소의 오매칭을 줄입니다. 규칙을 작성한 뒤에는 매칭되어야 할 요청과 매칭되면 안 되는 요청을 모두 테스트하세요. 성공 사례 하나만 확인해서는 부족합니다.

리디렉션은 프록시 정책 전환이 아닙니다

리디렉션이 발생하면 클라이언트가 새 요청을 보냅니다. 새 대상에는 해당 규칙이 다시 적용되어야 합니다. 원래 연결에 PROXY를 설정하는 것과 같지 않으며 서버 암호나 프로토콜 매개변수 오류도 해결하지 않습니다. 대체 후 호스트가 바뀌면 원래 호스트와 대상 호스트의 규칙을 각각 확인하세요. 규칙끼리 서로 되돌려 보내거나 서버 측 리디렉션과 로컬 처리가 충돌하면 리디렉션이 반복될 수 있습니다. 먼저 관련 Rewrite를 비활성화해 문제 범위를 좁히세요.

URL을 처리할 수 있는지는 프로토콜, 요청 정보의 가시성 및 관련 기능 설정에도 달려 있습니다. 일반 HTTP 예제만 보고 임의의 HTTPS 경로까지 읽을 수 있다고 추론해서는 안 됩니다. 암호화된 연결의 경로와 요청 헤더는 일반 라우팅 처리에 기본적으로 노출되지 않습니다. 이 페이지는 이를 위해 추가 복호화 기능을 켜도록 요구하지 않습니다. 호스트 기준 라우팅만 필요하다면 도메인 규칙을 우선 사용해 필요한 범위만 처리하세요.

유지 관리를 위해 각 매핑의 해제 조건을 기록하세요

유용한 유지 관리 기록에는 왜 추가했는지뿐 아니라 언제 삭제해야 하는지도 적어야 합니다. 예를 들어 특정 서비스 주소를 잠시 테스트했다면 테스트 후 일반적인 DNS 해석으로 되돌리세요. 이전 작업을 위해 리디렉션을 추가했다면 진입점이 통합된 후 다시 검토하세요. 해제 조건이 없는 임시 항목은 장기적인 장애 원인이 될 수 있습니다. 파일을 수정하기 전에 다른 섹션에서 같은 도메인이 사용되는지도 검색해 한 곳은 되돌렸는데 다른 곳에서 요청이 계속 바뀌는 일을 막으세요.

연결이 예상과 다르게 동작하면 원래 URL, 매핑된 주소, 수정된 URL 및 최종 매칭 정책을 순서대로 기록하세요. 네 항목 중 하나라도 예상과 다르면 먼저 그 단계부터 확인합니다. 이 과정을 통해 오래된 주소, 지나치게 넓은 표현식, 대상의 리디렉션 및 정책 선택 오류를 구분할 수 있습니다. 모든 이상을 규칙 자체의 문제로 돌리지 마세요. 복잡한 기능은 최소 설정이 검증된 뒤에 추가해야 합니다.

설정 가져오기 및 유지 관리: 출처, 선택 상태와 복구 지점 관리

설정 관리에서 중요한 것은 파일 개수가 아니라 현재 적용 중인 내용이 무엇인지, 업데이트로 어떤 항목이 바뀔 수 있는지 알고 검증된 상태로 되돌릴 수 있는지입니다. 기존 구독은 서비스 제공업체에서 받아야 합니다. 가져오기 전에 링크가 서버 목록, 전체 설정 파일 또는 다른 데이터 중 무엇을 제공하는지 확인하세요. 가져오기 메뉴마다 필요한 데이터가 다를 수 있습니다. 브라우저에서 링크가 열린다고 해서 현재 메뉴에서 읽을 수 있는 형식이라는 뜻은 아닙니다.

가져오기 전에 데이터 종류부터 확인하세요

서버 구독을 업데이트하면 서버 이름, 항목 개수 및 매개변수가 바뀔 수 있고, 규칙 설정을 업데이트하면 정책과 순서가 달라질 수 있습니다. 두 항목은 따로 기록하세요. 기존 서버만 추가하려는 경우 가져오기 성공을 위해 검증된 설정 파일 전체를 교체하지 마세요. 전체 설정을 가져오는 경우에는 General, Host, Rewrite 등의 추가 설정이 들어 있는지 먼저 확인하고 기존 네트워크 동작이 어떻게 바뀔지 파악해야 합니다.

Config에서 파일을 관리할 때는 가져오기를 마친 뒤 예상한 설정 파일이 선택되어 있는지도 확인하세요. 파일이 목록에 있는 것과 현재 적용 중인 것은 다릅니다. 사본을 편집했더라도 실행 중 설정이 그 사본으로 바뀐 것은 아닙니다. 일상용과 테스트용 설정을 용도에 맞는 이름으로 구분하고 선택 상태를 기록하는 것이 좋습니다. 구체적인 가져오기 메뉴와 작업은 앱 화면을 따르세요. 처음 사용하는 경우 사용 안내를 참고할 수 있습니다.

한 번의 변경 범위를 검증할 수 있게 줄이세요

예를 들어 로컬 서비스를 직접 연결하려는 경우 DNS 교체, 대역 추가, FINAL 변경 및 Rewrite 추가를 동시에 하기보다 먼저 정확한 도메인 규칙 하나를 추가하세요. 변수를 하나씩 늘릴 때마다 설명해야 할 가능성도 늘어납니다. 사본을 보관한 뒤 관련 섹션만 수정하고 같은 대상으로 다시 테스트하세요. 다른 자주 사용하는 대상에 영향이 없는지도 확인합니다. 결과가 확인된 다음 규칙 범위를 넓힐지 결정하세요.

# 이번에는 local.example.com 직접 연결 예외만 추가
[Rule]
DOMAIN,local.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY

주석에는 ‘이번에 무엇을 바꿨는지’와 ‘어떻게 확인할지’를 분명하게 적으세요. 최적화, 수정 또는 속도 향상처럼 모호한 내용만 써서는 안 됩니다. 파일 이름, 주석 및 테스트 기록에 실제 구독 토큰을 넣지 마세요. 구독 링크는 접근 자격 정보일 수 있으므로 문제 해결을 위해 다른 사람에게 전달하기 전에 전체 쿼리 매개변수와 민감한 서버 정보를 제거해야 합니다. 규칙 문제를 설명하는 데 필요한 문법 구조만 남기면 되며 실제 자격 정보를 공개할 필요는 없습니다.

원격 업데이트와 로컬 수정은 따로 확인하세요

원격 설정을 다시 업데이트하면 관리 방식에 따라 로컬 수정 내용이 덮어써질 수 있습니다. 업데이트 전에 사용자 지정 항목과 위치를 기록하고 업데이트 후에는 규칙 순서, 최종 정책 및 추가 섹션을 비교하세요. 파일 이름이 같다는 이유만으로 내용이 바뀌지 않았다고 가정하지 마세요. 규칙이 사라진 것을 발견해도 여러 파일을 곧바로 반복해서 가져오지 마세요. 먼저 업데이트 대상과 현재 적용 중인 설정을 확인한 뒤 필요한 사용자 지정 항목만 복원하세요.

서버 항목 이름이 바뀌었는지도 확인해야 합니다. 다른 설정에서 특정 이름을 참조하는 경우 업데이트 후 이름이 달라지면 참조가 유효하지 않을 수 있습니다. 이 페이지는 기본 정책을 주로 사용하더라도 서버 선택이 여전히 예상한 대상으로 설정되어 있는지 확인하세요. 가져오기와 업데이트를 마친 뒤 서버 연결, Config 모드 및 규칙 매칭을 각각 확인해 서버 업데이트 문제를 규칙 문법 문제로 오해하지 않도록 하세요.

설정 복원은 구매 또는 계정 상태 복원이 아닙니다

설정 파일은 네트워크 동작을 관리하며 App Store 구매 내역을 복원하지 않습니다. Shadowrocket은 Apple 플랫폼용 유료 앱이며 App Store에서만 제공됩니다. 구매 및 구입 항목 복원은 구입 항목 복원 안내를 확인하세요. 시스템 요구 사항은 App Store 페이지에 표시된 내용을 기준으로 합니다. 앱을 한 번 구매했다고 해서 회선 요금제가 포함되는 것은 아닙니다. 앱 구매만으로 설정 파일에 서버가 추가되는 것도 아니므로 기존 서비스 정보를 준비해야 합니다.

기기를 바꾸기 전에 보관할 설정과 서버 정보를 각각 저장하고 민감한 데이터의 저장 위치도 확인하세요. 시스템 백업, 앱 내 가져오기 및 App Store 구입 항목 복원은 서로 다른 기능이므로 대체할 수 없습니다. 앱을 재설치해 실행할 수 있다고 해서 기존 규칙, 구독 및 선택 상태까지 복원됐다고 볼 수는 없습니다. 모든 이전 파일을 바로 가져오기보다 항목을 순서대로 확인하는 편이 혼란을 줄일 수 있습니다.

구독 업데이트가 실패하거나 목록이 비어 있다면 Rule 섹션을 다시 작성하지 말고 링크 형식과 유효성, 서비스 제공업체의 상태부터 확인하세요. 구독 업데이트 실패 또는 서버 목록이 비었을 때 확인할 사항을 참고할 수 있습니다. 유지 관리가 끝나면 마지막으로 검증한 사본을 남기고 사용하지 않는 테스트 파일을 정리해 오래된 설정을 잘못 선택할 가능성을 줄이세요.

검증 및 문제 해결: 실제 매칭 결과부터 확인

규칙을 검증할 때는 근거를 순서대로 확인할 수 있어야 합니다. 현재 어떤 설정 파일을 사용하는지, Global Routing 모드는 무엇인지, 요청의 실제 대상은 무엇인지, 어떤 규칙이 매칭됐는지, 어떤 정책이 적용됐는지, 연결이 어느 단계에서 실패했는지 기록하세요. 단순히 ‘네트워크가 안 된다’는 설명만으로는 원인을 구분하기 어렵습니다. 먼저 현상을 대상 하나와 테스트 한 번으로 좁힌 뒤 처리 단계별로 확인하세요. 설정 파일 전체를 계속 교체하는 것보다 효과적입니다.

1단계: 테스트 조건 고정

현재 네트워크, 선택한 서버 및 설정 파일 이름을 기록하고 반복해서 접속할 수 있는 대상을 하나 고르세요. 가능한 한 조건을 바꾸지 말고 테스트 중에 네트워크, 서버 및 규칙을 동시에 전환하지 마세요. 앱이 기존 연결을 재사용할 수 있으므로 설정을 바꿔도 이미 열린 연결에 새 규칙이 바로 적용되지 않을 수 있습니다. 필요하면 관련 요청을 끝낸 뒤 다시 시작하고 새 연결 기록을 확인하세요. 기존 연결 결과를 새 규칙의 동작으로 오인하지 않도록 주의하세요.

아래 예제로 최소한의 비교 설정을 만들 수 있습니다. 사본에서 테스트하고 예시 도메인을 직접 관리하는 대상 도메인으로 바꾸세요. 이 예제의 목적은 규칙 수를 줄여 매칭 결과를 쉽게 설명하는 것이지, 모든 일상 트래픽에 적용할 범용 설정을 제공하는 것이 아닙니다. 최소 설정이 정상이라면 기존 설정을 그룹별로 복원하세요. 특정 그룹을 복원한 뒤 문제가 다시 나타나면 그 그룹의 범위, 순서 및 추가 설정을 집중적으로 확인하세요.

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

2단계: 테스트 도구의 의미 구분

Connectivity Test는 해당 테스트 방식에서 서버에 연결할 수 있는지 확인하는 데 도움이 되지만 각 대상에 대한 실제 접속을 대신하지는 않습니다. 테스트 성공이 모든 프로토콜, 포트 및 원격 서비스를 사용할 수 있다는 뜻은 아닙니다. 테스트 실패도 테스트 방법과 실제 요청을 함께 고려해야 합니다. 대상 접속 결과와 연결 기록을 모두 확인하고 테스트 수치 하나만으로 전체 규칙이 올바르다고 판단하지 마세요.

3단계: 증상에 따라 해당 처리 단계 확인

도메인 해석에 실패하면 도메인 철자, DNS 설정 및 Host 매핑부터 확인하세요. 연결 시간 초과가 발생하면 실제 대상 주소, 정책 경로 및 대상 서비스를 점검하세요. 명확한 거부가 나타나면 REJECT 규칙과 대상에서 반환한 거부가 같은 단계의 문제인지 확인합니다. 앱에서 표시하는 서비스 오류가 항상 네트워크 오류인 것은 아닙니다. 대상 서비스의 로그인 상태, 요청 권한 및 API 조건도 실패 원인일 수 있습니다. 근거를 확인하기 전에 네트워크 설정부터 바꾸지 마세요.

페이지에서 일부 리소스만 실패한다면 실패한 요청별로 호스트와 정책을 확인하세요. 모든 트래픽을 곧바로 같은 경로로 보내지 마세요. 같은 도메인이 네트워크마다 다르게 동작한다면 해석 결과와 주소 체계를 기록한 뒤 주소 지역 규칙의 영향을 확인합니다. 업데이트 후에만 문제가 발생했다면 업데이트 전후의 설정 내용과 서버 선택을 비교하세요. 먼저 바뀐 부분을 찾고 그다음 추가 규칙이 필요한지 판단하세요.

4단계: 되돌리기도 테스트에 포함

검증된 설정으로 되돌린 뒤 같은 요청을 반복하세요. 문제가 사라지면 이번 설정 변경을 우선 점검할 근거가 됩니다. 문제가 계속되면 네트워크, 서버 및 대상 자체를 살펴봐야 합니다. 되돌리기는 설정이 잘못됐다고 단정하는 행위가 아니라 변수를 통제하는 실험입니다. 테스트마다 차이를 하나만 남기고 예상 결과와 실제 결과를 기록해야 근거 있는 수정이 가능합니다. 우연히 한 번 성공한 결과를 바탕으로 설정을 계속 덧붙이지 마세요.

문제를 설명할 때는 앱의 모드, 대상 유형, 규칙 예제, 예상 정책 및 실제 매칭 결과를 제공하세요. 전체 구독 링크, 암호, 토큰 및 개인 주소는 제거하고 연결 기록에서 관련 없는 도메인도 삭제해야 합니다. 규칙 한 줄만 보여 주는 것보다 처음 매칭된 항목 주변의 필요한 내용을 함께 제공하는 편이 유용합니다. 순서 문제는 해당 규칙 자체보다 앞에 있는 넓은 범위의 규칙에서 발생하는 경우가 많기 때문입니다.

처음 가져오기, 권한 및 연결 절차를 다시 확인하려면 사용 안내로 돌아가세요. 짧은 문답을 모아 보고 싶다면 자주 묻는 질문을 확인하세요. 정품 구매 안내는 App Store 정품 확인에서 확인할 수 있습니다. 이 페이지에서는 먼저 설정 파일 구조를 파악하고, 조건과 순서를 확인한 뒤 실제 연결로 검증합니다. 규칙 수를 늘리는 대신 결과를 설명할 수 있어야 합니다.