01 설정 파일 구조와 수정 범위
Shadowrocket 설정 파일은 연결이 클라이언트에 들어온 뒤 어떻게 처리할지를 정의하며, 서버 인증 정보 목록과는 다릅니다. Subscribe로 가져온 항목은 보통 서버 목록을 관리하고, Config에서 선택한 파일은 규칙과 관련 설정을 담당합니다. 두 항목은 각각 따로 업데이트할 수 있습니다. “구독 업데이트는 성공했는데 접속 경로가 그대로”라면 같은 구독을 반복해서 가져오기보다 현재 설정 파일부터 확인하세요. 서버 정보는 연결할 위치를 결정하고, 규칙은 각 요청에 적용할 정책을 결정합니다.
섹션 제목으로 구성된 설정
설정은 대괄호로 섹션을 표시합니다. 예를 들어 [General] 및 [Rule]과 같습니다. General에는 키-값 형식의 설정이 흔히 쓰이고, Rule에는 보통 한 줄에 규칙 하나를 작성하며 영문 쉼표로 항목을 구분합니다. 섹션 제목은 일반 주석이 아니므로 빠뜨리면 이후 내용이 잘못된 섹션에 포함될 수 있습니다. 한글 쉼표, 전각 등호, 서식 있는 텍스트에서 복사한 특수 공백 때문에 올바르게 보이는 줄도 예상대로 파싱되지 않을 수 있습니다.
[General]
bypass-system = true
dns-server = system
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
FINAL,PROXY
이 코드는 구조를 보여 주는 예시이며 모든 네트워크에 적합한 완성 설정이 아닙니다. bypass-system은 시스템 트래픽 우회 동작과 관련되고, dns-server = system은 시스템이 제공하는 리졸버를 사용한다는 뜻입니다. 이 설정들이 서버 정보를 대신 채워 주거나 모든 연결이 반드시 Rule을 거치도록 보장하지는 않습니다. 설정을 살펴볼 때는 먼저 트래픽의 진입 경로와 우회 조건을 확인한 다음 규칙 목록을 살펴보세요. 마지막 몇 줄의 정책만 확인해서는 충분하지 않습니다.
자주 쓰는 네 가지 섹션의 역할
| 섹션 | 주요 역할 | 중점 확인 항목 |
|---|---|---|
[General] | 일반 네트워크 및 이름 해석 설정 | DNS 출처와 우회 조건이 현재 네트워크에 적합한지 |
[Rule] | 요청을 매칭하고 정책 선택 | 규칙 순서, 대상 필드, FINAL |
[Host] | 지정된 호스트 이름의 로컬 해석 매핑 | 주소가 여전히 유효한지, 정상적인 해석을 덮어쓰는지 |
[URL Rewrite] | URL 표현식에 따라 재작성 또는 리디렉션 | 표현식 범위, 대상 주소, 적용 조건 |
기능을 사용하지 않는다면 설정을 완성된 것처럼 보이게 하려고 해당 섹션을 추가할 필요는 없습니다. 특히 출처가 불분명한 Host 및 재작성 규칙 모음을 복사하지 마세요. 오래된 매핑 하나가 정상적인 이름 해석을 우회할 수 있고, 범위가 지나치게 넓은 재작성 하나가 로그인이나 리디렉션 동작을 바꿀 수 있습니다. 설정이 짧다고 반드시 좋은 것은 아니지만 각 항목의 용도와 영향 범위, 되돌리는 방법은 설명할 수 있어야 합니다.
편집, 저장, 활성화는 각각 별개의 작업입니다
Config에서 실제로 사용 중인 설정 파일을 찾고, 먼저 복사본을 저장한 다음 용도를 구분할 수 있는 이름을 붙여 편집하세요. 텍스트를 저장한 뒤 오류 메시지를 확인하고, 설정 목록으로 돌아가 선택 상태를 점검합니다. 활성화되지 않은 복사본을 편집해도 현재 분할 라우팅에는 영향이 없습니다. 다른 원격 설정을 활성화해도 이전 로컬 수정 사항이 자동으로 합쳐지지는 않습니다. 연결을 다시 설정해야 하는 항목은 연결을 끊었다가 다시 연결하고 새 요청으로 확인하세요.
원격 설정은 업데이트로 수정 사항이 덮어써질 수도 있습니다. 새로 고칠 때 교체되는 파일을 직접 수정하면 다음 업데이트에서 사용자 규칙이 사라질 수 있습니다. 파일의 업데이트 방식을 먼저 확인한 뒤 별도의 로컬 복사본을 사용할지, 앱에서 지원하는 변경 보존 기능을 사용할지 결정하세요. 이름이 비슷하고 내용이 다른 활성 후보 파일을 여러 개 동시에 관리하지 마세요. 문제 해결 시 최근에 어떤 파일을 편집했는지 기억하는 것보다 파일 이름, 선택 상태, 수정 내용을 기록해 두는 편이 정확합니다.
플랫폼이나 빌드에 따라 설정 메뉴 위치가 다를 수 있습니다. 이 문서는 설정의 의미를 설명하며 화면을 픽셀 단위로 안내하지 않습니다. 현재 클라이언트에서 특정 필드를 인식하지 못하면 해당 항목을 되돌리고 앱 내 안내를 확인하세요. 오류를 없애려고 매개변수를 계속 추가하지 마세요. 처음 설정한다면 튜토리얼의 설정 및 검증 절차를 참고하고, 구체적인 문제는 질문과 답변에서 증상별로 찾아보세요.
02 매칭 순서, 우선 적용 규칙과 FINAL
분할 라우팅을 이해할 때 가장 중요한 원칙은 요청이 설정 규칙 처리 단계에 들어온 경우 Rule을 보통 위에서 아래로 확인하며, 처음으로 매칭된 규칙이 해당 요청의 정책을 결정한다는 것입니다. 클라이언트는 매칭 결과를 전부 모은 뒤 가장 “정확해 보이는” 규칙을 고르지 않습니다. 따라서 규칙의 내용만큼 위치도 중요합니다. 구체적인 예외를 포괄적인 규칙 아래에 두면 예외를 작성하지 않은 것과 마찬가지가 될 수 있습니다.
예외를 먼저, 범위가 넓은 규칙은 나중에
[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,ads,REJECT
FINAL,PROXY
이 예시에서는 login.example.com이 첫 번째 줄에 먼저 매칭되어 DIRECT를 적용합니다. example.com에 속하는 나머지 도메인만 두 번째 줄에 매칭될 수 있습니다. 앞의 두 줄을 바꾸면 로그인 도메인도 먼저 접미사 규칙에 매칭되므로 뒤에 있는 DOMAIN 규칙이 요청의 결정을 바꾸지 못합니다. DOMAIN이 DOMAIN-SUFFIX보다 본래 우선한다고 생각하지 마세요. 여기서는 규칙을 배치한 순서가 우선순위를 결정합니다.
세 번째 줄은 또 다른 우선 적용 사례를 보여 줍니다. example.com 하위 도메인에 ads가 포함되더라도 두 번째 줄에 이미 매칭되면 뒤의 키워드 차단 규칙은 실행되지 않습니다. 먼저 의도를 정하세요. 도메인 계열 전체에 PROXY를 적용할지, 광고 키워드를 우선 거부할지 선택해야 합니다. 목적과 무관하게 통용되는 정답 순서는 없지만, 겹치는 요청이 각 줄에서 어떻게 처리되어야 하는지는 설명할 수 있어야 합니다.
FINAL은 기본 처리 규칙이지 강제 덮어쓰기가 아닙니다
FINAL,PROXY는 앞선 규칙이 요청의 경로를 결정하지 못했을 때 PROXY를 적용한다는 뜻입니다. 도메인 조건이 없으며 앞에서 잘못 작성한 항목을 바로잡지도 않습니다. FINAL을 규칙 중간에 두면 뒤에 나오는 규칙이 일반 요청을 처리하지 못할 수 있습니다. 일반적인 설정에서는 Rule의 마지막에 FINAL을 두고, 읽을 때 혼동이 없도록 명확한 기본 규칙 하나만 유지하세요.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY
이 설정은 먼저 도메인을 확인하고, 그다음 대상 주소의 지리 데이터베이스 분류를 확인하며, 나머지 요청에는 기본 규칙을 적용합니다. 도메인이 GEOIP에서 CN으로 분류되는 주소로 해석되더라도 앞의 접미사 규칙에 먼저 매칭되면 PROXY를 사용합니다. 반대로 도메인 정보를 사용할 수 없어 도메인 규칙에 매칭되지 않으면 주소 규칙을 계속 확인해야 합니다. 결과를 검증하기 전에 당시 매칭에 사용할 수 있었던 정보가 호스트 이름인지 주소인지부터 확인하세요.
규칙 순서와 우회 조건은 서로 다른 문제입니다
“위에서 아래로”라는 설명은 해당 규칙 목록에 진입한 뒤의 처리 방식을 뜻합니다. 모든 시스템 라우팅, 일반 우회 설정, 기존 연결을 목록이 덮어쓸 수 있다는 뜻은 아닙니다. 트래픽이 앞선 처리 경로에서 이미 우회되었다면 Rule의 줄 순서를 바꿔도 다시 규칙에 포함되지 않습니다. 특히 로컬 네트워크 접근을 조사할 때는 General의 우회 설정, 시스템 라우팅, Rule의 DIRECT를 구분하세요. 결과가 비슷해 보여도 적용되는 단계는 다릅니다.
규칙을 전환한 뒤에도 기존 장기 연결은 이전 경로를 계속 사용할 수 있습니다. 브라우저의 연결 재사용, 앱의 백그라운드 연결 유지, DNS 캐시 때문에 한 번 새로 고침하는 것만으로 새 규칙이 실패했다고 단정하기 어렵습니다. 대상에 새 연결을 만들고 필요하면 앱을 완전히 종료한 뒤 다시 시도하세요. 그런 다음 기록에서 대상 도메인, 매칭된 규칙, 정책을 비교합니다. 페이지가 열리는지만 보고 우선순위를 판단하면 서버 상태와 규칙 문제를 혼동할 수 있습니다.
반례로 우선순위 검증하기
예외를 추가할 때마다 최소 두 개의 테스트 대상을 준비하세요. 하나는 새 규칙에 매칭되어야 하고, 다른 하나는 비슷하지만 매칭되면 안 되는 대상이어야 합니다. 예를 들어 login.example.com을 수정했다면 api.example.com도 테스트하세요. 주소 대역을 추가한 경우 대역 밖의 주소도 확인합니다. 이렇게 하면 “규칙이 적용되지 않음”과 “규칙 범위가 너무 넓음”을 함께 찾아낼 수 있어 한 번 접속에 성공했는지만 확인하는 것보다 판단하기 쉽습니다.
03 도메인, 주소 및 요청 특성 규칙
규칙 유형에 따라 요청의 어느 부분을 비교할지가 달라집니다. 도메인 규칙은 호스트 이름을, 주소 규칙은 대상 IP를, USER-AGENT 규칙은 확인 가능한 요청 식별자를 살펴봅니다. 서로 다른 정보를 표현하는 규칙이므로 임의로 바꿔 쓸 수 없습니다. 유형을 선택하기 전에 전체 도메인 하나, 도메인 계열, 네트워크 대역, 식별 가능한 요청 유형 가운데 무엇을 지정할지 정한 뒤 문법을 선택하세요.
DOMAIN과 DOMAIN-SUFFIX
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.net,DIRECT
DOMAIN은 api.example.com이라는 호스트 이름 하나를 정확히 지정하는 예외에 적합하며 img.api.example.com을 자동으로 포함하지 않습니다. DOMAIN-SUFFIX는 도메인 접미사를 지정합니다. example.net 자체와 하위 도메인은 범위에 포함되지만 notexample.net은 example.net의 하위 도메인이 아닙니다. 도메인 필드에는 프로토콜 접두사, 경로, 포트 또는 끝의 슬래시를 넣지 마세요. 이들은 도메인 매칭 필드에 해당하지 않습니다.
같은 사이트의 로그인, 이미지, API 서비스를 구분해야 한다면 모두 메인 사이트 도메인에 속한다고 가정하지 말고 실제 요청에서 호스트 이름을 확인하세요. 최신 앱은 리소스 전용 도메인을 사용할 수 있고, 한 페이지에서도 여러 연결이 만들어질 수 있습니다. 메인 페이지 요청 하나가 규칙에 매칭되었다고 해서 모든 리소스에 같은 정책이 적용되는 것은 아닙니다.
DOMAIN-KEYWORD는 더 넓은 범위에 적용됩니다
DOMAIN-KEYWORD,ads,REJECT
이 규칙은 도메인에 키워드가 포함될 때 매칭되는 방식을 설명하는 예시이며 일반적인 차단 권고가 아닙니다. ads는 단순한 문자열 조각이라 거부할 필요가 없는 도메인에도 포함될 수 있습니다. 키워드 규칙은 접미사 규칙보다 경계를 제한하기 어려우므로 적용 전에 잘못 매칭될 대상을 확인하세요. 처리할 전체 도메인이나 고정된 접미사를 알고 있다면 의미가 더 분명한 유형을 우선 사용해 유지 관리 부담을 줄이세요.
IP-CIDR, IP-CIDR6 및 GEOIP
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
GEOIP,CN,DIRECT
IP-CIDR은 IPv4 주소와 접두사 길이로 네트워크 대역을 나타내고, IP-CIDR6은 IPv6을 처리합니다. 접두사 길이는 포트 번호가 아니며 임의로 생략해도 되는 주석도 아닙니다. 대역을 너무 넓게 지정하면 관계없는 대상 주소까지 포함될 수 있습니다. 예시의 사설 주소와 IPv6 로컬 주소 범위는 용도를 설명하기 위한 것입니다. 직접 연결 가능 여부는 시스템 라우팅과 현재 네트워크에 따라 달라지므로 모든 내부 주소에 접근할 수 있다고 단정하지 마세요.
no-resolve는 이 주소 규칙만을 위해 도메인을 능동적으로 해석하지 않는다는 뜻입니다. 요청에 대상 IP가 이미 있으면 계속 비교할 수 있습니다. 클라이언트 전체의 DNS를 끄는 기능이 아니며, 도메인 요청이 모두 사설 대역 규칙에 자동으로 매칭된다는 뜻도 아닙니다. GEOIP는 주소 데이터베이스의 분류에 의존하며 웹 콘텐츠 유형, 기업 등록 지역 또는 사용자 위치를 뜻하지 않습니다. 데이터베이스의 차이나 주소 할당 변경도 결과에 영향을 줄 수 있습니다.
USER-AGENT와 확인 가능한 정보의 범위
USER-AGENT,ExampleApp*,DIRECT
USER-AGENT는 확인 가능한 User-Agent 식별자와 매칭됩니다. 예시의 ExampleApp은 테스트용 가상 이름이며 별표는 와일드카드 매칭 의도를 나타냅니다. 시스템 앱 패키지 이름을 지정하는 규칙이 아니며 암호화된 요청을 모두 식별한다고 보장하지도 않습니다. 연결 단계에서 해당 요청 헤더를 확인할 수 없다면 이 규칙에는 신뢰할 수 있는 비교 대상이 없습니다. 앱 이름이 예시와 비슷하다는 이유로 모든 연결이 매칭된다고 생각하지 마세요.
| 유형 | 비교 대상 | 자주 하는 실수 |
|---|---|---|
| DOMAIN | 전체 호스트 이름 | 전체 URL 입력 |
| DOMAIN-SUFFIX | 도메인 및 하위 도메인 | 임의의 문자열로 끝나는 것으로 오해 |
| DOMAIN-KEYWORD | 도메인에 포함된 문자열 조각 | 잘못 매칭되는 범위를 과소평가 |
| IP-CIDR / IP-CIDR6 | 대상 주소 대역 | 주소 범위를 도메인 범위로 착각 |
| GEOIP | 대상 주소의 데이터베이스 분류 | 웹 콘텐츠 유형로 결과를 추측 |
| USER-AGENT | 확인 가능한 요청 식별자 | 앱별 일반 분할 라우팅 규칙으로 오해 |
| FINAL | 앞선 규칙에 매칭되지 않은 요청 | 목록 중간에 배치 |
두 유형 모두 요구 사항을 표현할 수 있다면 의미가 가장 명확하고 전제 조건이 적은 유형을 선택하세요. 도메인 예외에는 보통 DOMAIN, 도메인 계열 전체에는 DOMAIN-SUFFIX, 명확한 내부 주소 범위에는 CIDR을 사용합니다. 넓은 범위가 꼭 필요한 경우에만 키워드 규칙을 고려하세요. 모든 광범위한 규칙에 매칭되면 안 되는 반례를 마련해 목록이 길어지면서 오류가 숨겨지는 일을 방지하세요.
04 PROXY, DIRECT, REJECT 및 Global Routing
규칙은 “어떤 요청을 매칭할지”에 답하고, 정책은 “매칭된 뒤 어떻게 처리할지”에 답합니다. 이 페이지에서 사용하는 PROXY, DIRECT, REJECT는 기본 정책 키워드 세 가지로, 설정에는 영문 대문자로 씁니다. 이들은 화면의 Config, Proxy, Direct와 같은 계층이 아닙니다. 앞의 항목은 규칙의 동작 위치에 쓰이고, 뒤의 항목은 Global Routing의 작동 모드입니다. 이 둘을 혼동하면 “규칙을 작성했는데도 적용되지 않는” 상황이 생길 수 있습니다.
기본 정책 세 가지의 의미
PROXY는 매칭된 연결이 프록시 경로를 사용하도록 합니다. 실제 사용할 서버나 관련 정책 선택은 Home에서 선택된 항목과 현재 설정을 함께 확인해야 합니다. PROXY를 작성했다고 사용 가능한 서버가 생기거나 인증, 전송, 대상 접근이 성공하는 것은 아닙니다. 서버 선택이 잘못되었거나 인증 정보가 만료되었거나 대상에 접근할 수 없다면 규칙은 올바르게 매칭되더라도 이후 연결은 실패할 수 있습니다.
DIRECT는 선택한 프록시 서버를 거치지 않고 대상에 직접 연결한다는 뜻입니다. 이 연결도 기기의 네트워크, DNS, 시스템 라우팅, 대상 서비스 상태에 좌우되며 “모든 네트워크 문제를 우회한다”는 뜻은 아닙니다. 예를 들어 내부 관리 페이지의 정책이 DIRECT여도 기기가 해당 로컬 네트워크에 연결되어 있지 않으면 연결할 수 없습니다. 문제를 해결할 때는 “직접 연결을 선택함”과 “직접 연결로 도달할 수 있음”을 따로 확인하세요.
REJECT는 매칭된 연결을 거부합니다. 예상되는 결과는 요청 실패 또는 리소스 미로드이지, 다른 사용 가능한 경로로 자동 전환되는 것이 아닙니다. 앱이 거부된 요청을 반복해서 시도해 기록이 늘어날 수 있고, 필수 인터페이스 하나가 거부되어 앱 전체가 비정상적으로 작동할 수도 있습니다. 이런 현상이 생기면 거부된 대상을 먼저 확인하세요. 메인 페이지가 열리지 않는다는 이유만으로 서버가 문제라고 단정하지 마세요.
Global Routing의 세 가지 모드
| 화면 용어 | 설명 | 확인할 사항 |
|---|---|---|
| Config | Config: 현재 설정에 따라 분할 라우팅 | Rule, 우선순위, 기본 규칙 확인 |
| Proxy | Proxy: 인계된 트래픽에 프록시 모드 적용 | 규칙 차이를 일시적으로 분리해 확인 |
| Direct | Direct: 인계된 트래픽에 직접 연결 모드 적용 | 기기 네트워크의 접속 결과 비교 |
사용자 규칙을 일상적으로 검증할 때는 Config를 선택하세요. Proxy는 “프록시 경로 자체가 작동하는지”, Direct는 “기기 네트워크에서 접근할 수 있는지” 비교하는 데 사용할 수 있지만, 어느 쪽도 특정 Rule이 적용되었다는 증거는 아닙니다. 이러한 모드 설명이 모든 시스템 트래픽을 인계할 수 있다는 뜻도 아닙니다. 시스템 우회, 앱 동작, 기존 연결도 각각 고려해야 합니다.
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN,printer.example.net,DIRECT
DOMAIN,metrics.example.org,REJECT
FINAL,PROXY
같은 대상을 사용해 조건별로 비교하기
대상이 Proxy에서는 열리지만 Config에서는 실패한다면 서버를 바로 바꾸기보다 Config에서 DIRECT, REJECT 또는 앞선 규칙에 매칭되는지 확인하세요. Proxy와 Config에서 모두 실패한다면 프록시 경로, 이름 해석, 대상 상태를 점검합니다. Direct에서는 성공하지만 Proxy에서 실패하는 경우에는 선택한 서버와 대상까지의 연결을 추가로 확인해야 합니다. 이것만으로 모든 규칙에 문제가 있다고 판단해서는 안 됩니다.
비교 테스트에서는 대상, 네트워크, 서버 선택을 가능한 한 동일하게 유지하고 한 번에 조건 하나만 바꾸세요. 네트워크, 모드, 서버를 계속 함께 바꾸면 결과의 원인을 파악하기 어렵습니다. 페이지의 첫 로드와 이후 리소스 요청도 구분해야 합니다. 한 웹페이지에 PROXY, DIRECT, REJECT 기록이 모두 나타날 수 있으므로 특정 기록 하나를 페이지 전체의 동작으로 간주하지 마세요.
프로토콜 매개변수와 분할 라우팅 정책은 서로 다른 부분을 담당합니다
Shadowsocks, VMess, VLESS, Trojan 등은 프록시 연결을 설정하는 방식을 결정하고, Rule은 어떤 요청을 프록시 경로로 보낼지 결정합니다. DOMAIN-SUFFIX를 DOMAIN으로 바꿔도 서버 비밀번호 오류는 해결되지 않으며, 전송 매개변수를 바꿔도 범위가 지나치게 넓은 거부 규칙이 자동으로 수정되지는 않습니다. 프로토콜 필드를 확인하려면 프로토콜 및 주요 매개변수 설명을 참고한 다음 여기로 돌아와 요청 경로를 확인하세요.
On Demand는 조건에 따라 연결을 시작하는 기능입니다. Global Routing에서 선택하는 분할 라우팅 모드와는 별도로 이해해야 합니다. 자동으로 연결되더라도 Config가 적용된다는 뜻은 아니며, 수동 연결이 규칙을 무시한다는 뜻도 아닙니다. 모드를 전환한 뒤에는 현재 연결 상태와 설정 선택을 다시 확인해 자동 연결 동작을 규칙 선택 결과로 오해하지 않도록 하세요.
05 DNS, Host와 주소 규칙의 상호 작용
도메인 규칙과 주소 규칙은 서로 다른 정보에 의존하므로 DNS가 분할 라우팅 문제 해결의 분기점이 되는 경우가 많습니다. 도메인 이름을 주소로 해석한 뒤 Rule이 당시 확인 가능한 정보를 바탕으로 정책을 판단합니다. 실제 처리는 캐시, 연결 방식, 클라이언트 설정에도 영향을 받습니다. “특정 주소로 해석되었다”는 사실만으로 “특정 경로를 사용했다”고 단정하지 마세요. 이름 해석 경로와 실제 연결 경로를 각각 확인해야 합니다.
현재 상태를 기록한 뒤 DNS 출처를 조정하세요
[General]
dns-server = system
이 줄은 시스템 리졸버를 사용한다는 뜻이며, 필드를 이해하기 위한 시작점이지 모든 경우에 가장 좋은 설정은 아닙니다. 시스템 리졸버는 현재 네트워크와 시스템 설정에 따라 제공되므로 Wi-Fi나 모바일 네트워크를 전환하면 실제 환경도 달라질 수 있습니다. 내부 호스트 이름처럼 특정 네트워크에서만 해석되는 대상은 다른 DNS 출처로 바꾸면 오히려 작동하지 않을 수 있습니다. 수정하기 전에 대상 도메인, 기존 해석 결과, 네트워크 조건을 기록하세요.
이름 해석 문제를 조사할 때는 실패가 해석 전인지 연결 후인지 먼저 확인하세요. 주소를 받지 못한 경우, 주소는 받았지만 연결 시간이 초과된 경우, 연결 후 인증서 오류가 발생한 경우는 서로 다른 단계의 문제입니다. 첫 번째 경우에만 DNS 경로를 우선 의심할 수 있으며, 나머지는 주소 도달 가능성, 대상 서비스, 시간 설정, 핸드셰이크 조건도 관련됩니다. 실패 단계를 확인하지 않고 DNS를 계속 바꾸면 실제 원인을 가릴 수 있습니다.
Host 매핑은 해석 결과만 바꿉니다
[Host]
portal.example.com = 192.0.2.10
test.example.net = 198.51.100.20
Host 섹션은 지정된 호스트 이름을 로컬에서 특정 주소로 매핑합니다. 위의 주소는 문서 예시용 예약 범위에 속하므로 실제 접속에 사용할 수 없습니다. Host는 서버 인증서를 만들어 주거나 도달할 수 없던 주소에 연결되게 하지 않습니다. 도메인이 지정된 IP로 해석되더라도 서버는 해당 호스트 이름을 올바르게 처리해야 합니다. Host를 임의의 웹페이지 오류를 해결하는 간편한 스위치처럼 사용하지 마세요.
실제 매핑을 설정할 때는 대상 주소가 안정적이고 관리 권한이 있는 서비스에서 제공되는지 먼저 확인하세요. 많은 사이트가 동적 주소, 지역별 라우팅, 다중 주소 장애 조치를 사용하므로 한 번 조회한 IP로 고정하면 잠시 작동하다가 이후 실패할 수 있습니다. 네트워크가 바뀐 뒤에도 이 매핑은 정상적인 이름 해석을 계속 덮어씁니다. 각 Host 항목에는 명확한 용도가 있어야 하며, 필요하지 않게 되면 삭제하세요.
주소 규칙이 매칭되지 않는 경우
[Rule]
DOMAIN,portal.example.com,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
IP-CIDR6,fc00::/7,DIRECT,no-resolve
FINAL,PROXY
첫 번째 줄은 호스트 이름만으로 정책을 결정하므로 뒤의 주소 범위 규칙에 같은 의도를 맡길 필요가 없습니다. 뒤의 두 줄은 특정 네트워크 대역만 다루며, 매칭을 위해 도메인을 능동적으로 해석하지 않습니다. 명확한 내부 도메인에 항상 직접 연결하려면 특정 사설 대역으로 해석될 것이라고 가정하고 주소 규칙에 의존하기보다 도메인 규칙을 명시하는 편이 좋습니다.
같은 도메인에서 IPv4와 IPv6 주소가 함께 반환될 수 있습니다. IPv4 대역만 설정했다고 해서 IPv6 연결도 이 규칙에 적용된다고 볼 수 없으며, 한 번의 해석 결과만으로 모든 요청이 같은 주소를 사용한다고 판단할 수도 없습니다. 결과가 때에 따라 달라진다면 실제 대상 주소와 주소 계열을 기록한 다음 규칙 범위와 비교하세요. 같은 도메인 항목을 계속 중복해서 추가하지 마세요.
캐시, GEOIP와 관측 오차
DNS 캐시는 클라이언트, 시스템, 대상 앱에 저장될 수 있으며 기존 연결은 이전 주소를 계속 사용할 수도 있습니다. Host 또는 이름 해석 설정을 바꾼 뒤에는 새 연결을 만든 다음 새 결과가 사용되는지 확인하세요. 필요하다면 앱에서 제공하는 방법으로 관련 캐시를 지우세요. 도메인 하나를 검증하려고 네트워크 설정 전체를 초기화하지 마세요. 변수만 늘어나고 어떤 변경이 영향을 주었는지 확인하기 어려워집니다.
GEOIP는 대상 주소를 데이터베이스에서 분류하며 도메인 소속에 대한 권위 있는 판정이 아닙니다. 콘텐츠 전송 서비스나 주소 재할당 때문에 예상과 다른 분류가 나올 수 있습니다. 업무상 고정된 정책이 필요하면 명확한 도메인 예외를 GEOIP 앞에 두세요. 대상 하나 때문에 전체 지리 기반 라우팅을 바꾸지 마세요. 주소 분류가 의심스러우면 실제 대상 IP와 첫 번째 매칭 기록을 확인해야 합니다.
06 URL Rewrite의 역할과 안전한 사용 범위
URL Rewrite는 확인 가능한 URL 표현식과 치환 관계를 처리하고, Rule은 연결에 적용할 정책을 처리합니다. 둘은 같은 설정 파일에 함께 들어갈 수 있지만 서로 대체할 수는 없습니다. 특정 도메인을 프록시로 보내려면 분할 라우팅 규칙을 작성하세요. 명확한 이전 주소를 새 주소로 리디렉션하려는 경우에만 재작성을 고려하면 됩니다. 접속 실패를 모두 URL Rewrite로 해결하려 하면 단순한 연결 문제가 추적하기 어려운 리디렉션 문제로 바뀔 수 있습니다.
가장 간단한 리디렉션부터 이해하기
[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302
이 예시는 지정된 HTTP 주소를 HTTPS 주소로 리디렉션하는 관계를 나타냅니다. 왼쪽은 정규식, 가운데는 치환 대상, 마지막의 302는 임시 리디렉션을 뜻합니다. 맨 앞의 캐럿은 문자열 시작 위치에서 매칭하도록 제한하고, 끝의 달러 기호는 문자열 끝에 맞춥니다. 백슬래시는 도메인 이름의 마침표를 일반 마침표로 처리하도록 합니다. 캡처 그룹의 내용은 치환 대상에서 $1로 참조합니다.
이 예시는 문법 설명용이며 예시 도메인에 실제로 접속하라는 뜻도, 모든 사이트를 클라이언트에서 강제로 재작성해도 된다는 뜻도 아닙니다. 실제로 적용하기 전에 대상 서비스가 새 주소를 지원하는지, 경로의 의미가 동일한지, 쿼리 매개변수와 로그인 콜백 및 리소스 참조가 계속 정상인지 확인하세요. 재작성은 요청 대상을 바꿀 수 있지만 새 대상에서 동일한 콘텐츠나 권한 동작이 제공된다고 보장하지는 않습니다.
설명할 수 있는 범위의 표현식을 사용하세요
도메인 이름의 마침표를 이스케이프하지 않으면 정규식에서 보통 임의의 한 문자를 뜻해 매칭 범위가 넓어질 수 있습니다. 시작 또는 끝 제한을 생략해도 의도하지 않은 위치에 매칭될 수 있습니다. 일반 도메인 접미사 매칭의 직관을 정규식에 그대로 적용하지 마세요. DOMAIN-SUFFIX와 정규식의 의미는 다르며, 전자의 도메인 경계가 후자에 자동으로 적용되지 않습니다.
모든 주소를 포괄하는 표현식 하나를 작성하기보다 범위를 단계적으로 좁히는 편이 검증하기 쉽습니다. 먼저 전체 호스트 이름과 명확한 경로 하나를 대상으로 테스트한 뒤 캡처 그룹을 추가하세요. 와일드카드 범위를 넓힐 때마다 재작성되면 안 되는 주소를 반례로 준비해야 합니다. 괄호나 이스케이프 문자의 용도를 설명할 수 없다면 적용을 멈추세요. 사용 중인 설정을 시행착오로 수정하지 마세요.
리디렉션과 투명한 변경을 구분하세요
302 리디렉션은 이 동작을 지원하는 클라이언트가 대상 주소에 다시 요청하도록 합니다. 이후 요청도 이름 해석, 연결, 규칙 처리를 거칩니다. 원래 연결이 다른 경로로 조용히 바뀌는 기능은 아닙니다. 대상 주소가 또 다른 리디렉션 규칙에 매칭되면 여러 번 이동할 수 있고, 서로 반대 방향인 규칙 두 개는 순환을 일으켜 페이지가 끝내 로드되지 않을 수 있습니다.
리디렉션 순환을 조사할 때는 먼저 새로 추가한 재작성을 비활성화해 원래 접속이 복구되는지 확인한 다음 원본 주소부터 대상 주소까지의 전체 경로를 살펴보세요. 브라우저 캐시와 사이트 자체 리디렉션도 영향을 줄 수 있으므로 새 요청으로 확인하고 주소 표시줄의 최종 위치만 보지 마세요. 영구 리디렉션 동작은 특히 주의해야 하며, 테스트 중에는 캐시 결과가 판단을 방해하지 않도록 하세요.
HTTPS가 전체 경로를 자동으로 드러내지는 않습니다
일반적인 암호화 연결은 설정에 URL Rewrite가 있다는 이유만으로 전체 요청 경로와 헤더를 클라이언트에 자동으로 제공하지 않습니다. 도메인 수준의 연결 정보와 전체 URL은 서로 다릅니다. 일부 HTTPS 재작성 기능은 별도의 복호화 조건과 인증서 신뢰 설정에 의존합니다. 이 페이지는 분할 라우팅을 위해 이러한 기능을 활성화할 필요가 없으며, 도메인 규칙 하나를 수정하려고 복호화 범위를 넓히는 것도 권장하지 않습니다.
목표가 “특정 도메인을 직접 연결하거나 프록시로 보내기”라면 인증서 관련 설정을 추가하지 말고 Rule로 돌아가세요. 권한이 있는 테스트에 꼭 필요한 경우에도 호스트 범위를 제한하고 앱의 인증서 고정 및 민감한 세션에 미치는 영향을 이해한 뒤 되돌리는 방법을 마련해야 합니다. “재작성이 실행되지 않음”을 곧바로 표현식 오류로 결론 내리지 말고 클라이언트가 요청 정보를 충분히 확인할 수 있는지 먼저 판단하세요.
원격 설정을 관리할 때는 새로 추가된 재작성 섹션에 특히 주의하세요. 규칙 업데이트는 프록시 경로뿐 아니라 접속 주소도 바꿀 수 있습니다. 업데이트 후 로그인 복귀, 링크 이동, 리소스 주소가 달라지면 Rule만 확인하지 말고 URL Rewrite와 Host의 차이도 비교하세요. 실제로 필요한 기능만 최소한으로 유지하면 이후 문제 해결 범위를 좁힐 수 있습니다.
07 자주 쓰는 규칙 문법과 조합 방법
규칙을 조합할 때는 먼저 목표를 한 문장으로 설명한 뒤 정확한 예외, 포괄적인 그룹, 기본 처리로 나누세요. 아래 코드는 서로 독립된 예시이며 배치 순서를 설명할 뿐, 회선 정보를 제공하지 않습니다. 실제로 사용하기 전에 예시 호스트 이름을 확인된 업무 대상으로 바꾸고 비교할 수 있도록 원본 설정을 보관하세요. 코드가 짧다는 이유로 검증을 생략하거나 기존 파일을 덮어쓰지 마세요.
지정한 도메인은 프록시로, 나머지는 직접 연결
[Rule]
DOMAIN,api.example.com,PROXY
DOMAIN-SUFFIX,example.net,PROXY
FINAL,DIRECT
이 규칙은 명시적인 허용 목록을 표현합니다. 정확히 지정된 API 도메인과 도메인 계열만 PROXY를 사용하고 나머지 요청은 DIRECT로 처리됩니다. 대상 범위가 명확하고 지속적으로 관리할 수 있는 경우에 적합합니다. 앱이 다른 리소스 도메인에도 의존한다면 해당 요청은 FINAL,DIRECT에 매칭됩니다. API는 작동하지만 이미지나 로그인이 실패하면 기존 규칙을 반복해서 작성하기보다 누락된 도메인이 있는지 먼저 확인하세요.
이런 설정을 관리할 때는 웹페이지 주소 표시줄만 보지 말고 업무상 의존하는 항목을 기록하세요. 로그인 인증, 정적 리소스, 파일 업로드가 서로 다른 호스트 이름을 사용할 수 있습니다. 도메인을 추가할 때는 필요한 최소 범위를 유지하고 같은 업무 흐름에 속하는지 확인한 뒤 DOMAIN과 DOMAIN-SUFFIX 중에서 선택하세요. 관찰 없이 범위가 넓은 키워드를 추가하면 다른 앱의 경로까지 바뀔 수 있습니다.
일부는 직접 연결하고 나머지는 프록시로 처리
[Rule]
DOMAIN,router.example.net,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY
이 예시는 호스트 이름이 명확한 직접 연결 예외를 먼저 두고, 사설 주소와 GEOIP 분류를 처리한 뒤 마지막에 프록시를 기본값으로 사용합니다. 앞의 예시와 주된 차이는 줄 수가 아니라 “목록에 없는 대상”에 적용되는 정책입니다. 설정을 평가하기 전에 FINAL부터 확인하세요. 기본 규칙은 새로 추가된 업무 대상, 알 수 없는 도메인, 매칭되지 않은 주소의 기본 동작을 결정합니다.
이 규칙은 모든 로컬 네트워크를 완전히 다루는 설정이 아닙니다. 네트워크마다 다른 사설 주소 대역을 사용할 수 있고 IPv6도 별도로 고려해야 합니다. 시스템 및 General의 우회 동작이 먼저 적용될 수도 있습니다. 내부 서비스에 접근해야 한다면 실제 주소와 호스트 이름을 기준으로 규칙을 추가하세요. 확인되지 않은 대역 목록을 그대로 복사한 뒤 로컬 네트워크 문제가 해결됐다고 판단하지 마세요.
접미사 규칙 안에서 정확한 예외 지정
[Rule]
DOMAIN,login.example.com,DIRECT
DOMAIN,metrics.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
FINAL,PROXY
로그인 및 통계 API 예외를 먼저 작성한 다음 나머지 도메인 계열에 동일한 정책을 적용합니다. 이 예시의 REJECT는 예외 배치 방법을 보여 줄 뿐, 실제 업무에서 해당 API를 안전하게 거부해도 된다는 뜻은 아닙니다. 실제 서비스에서는 통계, 초기화, 필수 기능이 하나의 호스트 이름에 통합되어 있을 수 있습니다. 호스트 전체를 거부하면 다른 기능에 영향을 줄 수 있으므로 역할을 먼저 확인한 뒤 유지 여부를 결정하세요.
같은 도메인에서 경로별로 다른 처리가 필요하더라도 DOMAIN은 경로를 구분할 수 없습니다. 동일한 도메인을 여러 줄 추가해도 달라지지 않습니다. 경로별 처리가 꼭 필요한지 요구 사항부터 다시 검토하고 도메인 필드에 슬래시를 추가하지 마세요. 분할 라우팅 규칙과 URL Rewrite는 기능 범위가 다르므로 문법을 이어 붙여 한 종류의 규칙을 다른 종류로 바꿀 수는 없습니다.
설정을 합칠 때 판단 순서를 유지하세요
두 규칙 목록을 합친다고 해서 두 파일을 그대로 이어 붙이면 되는 것은 아닙니다. 중복된 섹션 제목과 중간에 들어간 FINAL을 제거한 뒤 업무 예외, 도메인 그룹, 주소 범위, 기본 규칙 순으로 다시 검토하세요. 완전히 같은 줄의 중복은 보통 읽기만 불편하게 합니다. 반면 같은 조건에 서로 다른 정책이 적용되면 실제 충돌이 발생합니다. 앞선 항목이 적용되므로 뒤의 항목은 유지 관리 담당자에게 잘못된 기대를 줄 수 있습니다.
구독 그룹 관리와 규칙 기반 분할 라우팅도 따로 관리해야 합니다. 구독 이름이 바뀌었다고 접속 경로를 설명할 수 없어서는 안 되며, 구독을 삭제하기 전에는 현재 선택한 프록시가 여전히 유효한지 확인하세요. 여러 출처의 서버 항목을 정리하는 방법은 여러 구독의 그룹화, 업데이트 및 중복 항목 정리를 참고하세요. 서버 목록을 정리한 뒤 규칙이 예상한 경로를 계속 참조하는지도 별도로 확인하세요.
한 번에 조합 목표 하나만 추가하는 것을 권장합니다. 예를 들어 먼저 내부 주소의 직접 연결을 설정하고, 다음에 특정 도메인의 프록시 연결을 처리한 뒤, 마지막으로 거부 예외를 추가하세요. 각 단계마다 성공 사례와 반례를 하나씩 기록합니다. 설정이 짧더라도 각 항목의 필요성을 설명할 수 있고, 문제가 생기면 전체 규칙을 다시 만들지 않고 최근 변경 사항만 빠르게 되돌릴 수 있습니다.
08 규칙 검증, 문제 진단 및 유지 관리
분할 라우팅 검증은 웹페이지가 열리는지 확인하는 데 그치지 않습니다. 요청 대상, 매칭된 규칙, 적용 정책, 최종 연결 결과를 서로 연결해 확인해야 합니다. 페이지가 열리는 것은 캐시 때문일 수 있고 실패는 서버나 대상 서비스 문제일 수 있으므로 어느 쪽도 규칙이 올바르다는 증거가 되지 않습니다. 확인하기 쉬운 현재 상태에서 시작해 연결 처리 과정을 따라 범위를 단계적으로 좁히고 서로 다른 문제를 한꺼번에 수정하지 마세요.
1단계: 테스트 조건 고정
현재 네트워크, 선택한 서버, Global Routing 모드, Config 파일 이름을 기록하세요. 연결 스위치가 켜져 있고 현재 모드가 Config인지 확인한 다음 예상 경로를 명확히 설명할 수 있는 대상을 선택합니다. 우선 서버를 여러 번 바꾸거나 구독을 다시 가져오지 마세요. 테스트 조건이 계속 바뀌면 다음번 성공이 규칙 수정 때문인지 네트워크 복구 때문인지 판단할 수 없습니다.
설정이 저장되고 활성화되었는지, 원격 새로 고침으로 로컬 수정 사항이 덮어써지지 않았는지 확인하세요. 새 규칙을 테스트하려면 새 연결을 만들고 기존 세션을 재사용하지 않도록 합니다. 브라우저에서는 관련 페이지를 닫았다가 다시 열고, 독립 앱은 종료 후 재시도할 수 있습니다. 처음부터 시스템 네트워크를 초기화할 필요는 없습니다. 모든 조치는 특정 변수를 제거하는 데 도움이 되어야 합니다.
2단계: 대상과 첫 매칭 규칙 확인
앱에서 제공하는 연결 기록이나 진단 정보에서 이번 요청의 도메인, 대상 IP, 규칙, 정책을 확인하세요. 기록에 표시된 API 도메인은 페이지 주소와 다를 수 있으므로 실제 요청을 기준으로 판단합니다. 먼저 요청이 현재 설정에 들어왔는지 확인한 다음, 앞선 접미사, 키워드, 주소 규칙 또는 거부 예외에 가로채였는지 살펴보세요. 방금 추가한 줄만 검색하지 마세요.
예상한 도메인이 보이지 않는다면 요청에 주소만 포함되었거나 암호화 연결에서 확인할 수 있는 정보가 제한되었거나, 앱이 다른 호스트 이름을 사용하거나, 기록 범위가 다를 수 있습니다. 추측만으로 도메인을 수십 개 추가하지 마세요. 같은 규칙 유형으로 관찰하기 쉬운 테스트 대상을 만들어 기본 매칭부터 확인한 다음 원래 앱을 살펴보세요. USER-AGENT는 특히 해당 식별자를 실제로 확인할 수 있는지 먼저 검증해야 합니다.
3단계: 정책 적용과 연결 성공을 분리해 확인
| 관찰 결과 | 우선 확인할 항목 | 다음 단계 |
|---|---|---|
| 예상치 못한 REJECT에 매칭됨 | 키워드 범위, 정확한 예외의 순서 | 규칙 범위를 좁히고 새 연결 생성 |
| PROXY에 매칭됐지만 연결 실패 | 서버 선택, 인증, 대상 접근 가능성 | Proxy 모드에서 같은 대상과 비교 |
| DIRECT에 매칭됐지만 연결 실패 | 기기 네트워크, DNS, 내부 라우팅 | 실제 대상 주소와 네트워크 조건 비교 |
| 항상 FINAL로 처리됨 | 대상 필드, 규칙 유형, 확인 가능한 정보 | 도메인과 주소가 조건에 맞는지 확인 |
| 수정해도 동작이 바뀌지 않음 | 선택된 파일, 캐시, 기존 연결 | 저장 및 활성화 여부를 확인한 뒤 새 요청 전송 |
Connectivity Test는 서버 연결 상태를 확인하는 데 도움이 되지만 특정 업무 대상에 대한 전체 접속 테스트를 대신하지는 않습니다. 테스트 주소와 실제 대상이 다를 수 있고, 사용되는 프로토콜 기능과 요청 유형도 다를 수 있습니다. 마찬가지로 Data에 업로드 및 다운로드 수치가 표시되어도 해당 통계 범위에 트래픽이 있었다는 뜻일 뿐, 트래픽 양만으로 특정 규칙의 매칭 여부를 판단할 수는 없습니다. 통계 화면의 의미는 Data 페이지 트래픽 통계 설명을 참고하세요.
4단계: 기록을 보존하고 최소한으로 되돌리기
설정을 추가한 뒤 문제가 발생하면 최근에 추가한 규칙 그룹이나 재작성을 먼저 비활성화하고 저장해 둔 이전 설정과 비교하세요. 이전 설정에서 문제가 해결되면 모든 설정을 초기화하지 말고 항목을 하나씩 다시 적용합니다. 기록에는 대상, 예상 정책, 실제 첫 매칭, 오류가 발생한 단계를 포함하세요. 이런 정보가 “가끔 열리지 않음”이라는 설명보다 순서, 이름 해석, 프록시 연결 문제를 판단하는 데 유용합니다.
문제 해결 자료를 공유할 때는 구독 링크, 인증 필드, 액세스 토큰, 개인 정보가 포함된 쿼리 매개변수를 삭제하세요. 문법과 구조를 설명할 때는 실제 인증 정보를 공개할 필요 없이 example.com과 예약 주소를 사용할 수 있습니다. 규칙 예시의 도메인은 대체로 민감하지 않지만 연결 기록에는 전체 경로와 세션 정보가 포함될 수 있으므로 설정 전체를 그대로 전달하지 말고 항목별로 확인하세요.
반복 가능한 유지 관리 점검 절차 만들기
규칙을 업데이트할 때마다 최소한 프록시 대상 하나, 직접 연결 대상 하나, 제외되어야 하는 반례 하나를 다시 테스트하세요. REJECT를 사용한다면 거부 범위가 넓어지지 않았는지도 확인합니다. 네트워크를 바꾼 뒤에는 내부 주소와 DNS를, 서버를 바꾼 뒤에는 프록시 경로를, 설정을 업데이트한 뒤에는 규칙 순서와 새 섹션을 중점적으로 확인하세요. 테스트 항목은 적어도 좋지만 고정되어 있어야 하며 실제 사용 목적을 다룰 수 있어야 합니다.
첫 연결 절차에 관한 문제라면 빠른 시작 튜토리얼에서 다시 확인하세요. 설치 파일이나 시스템 허용 절차는 다운로드 페이지의 설치 및 실행 허용 안내를 참고하고, 자주 묻는 사용 문의는 질문과 답변에서 확인할 수 있습니다. 규칙 참고 자료의 목표는 규칙을 계속 추가해 우연히 접속에 성공하는 것이 아니라, 각 결과에 영향을 준 조건을 추적할 수 있도록 하는 것입니다.