Shadowrocket
규칙 및 설정 가이드

[General]

설정 파일 구조와 적용 범위

Shadowrocket 설정 파일은 도메인 목록만 담는 파일이 아닙니다. 실행 매개변수, 요청 라우팅, 이름 해석 매핑, URL 처리를 각각 다른 섹션에 배치하며, 각 섹션 이름은 영문 대괄호로 묶습니다. 파일을 읽을 때는 먼저 섹션 이름을 확인하고, 다음 섹션이 나올 때까지 각 줄이 어떤 문법에 해당하는지 살펴보세요. 도메인이 포함되어 있다고 해서 두 줄을 같은 섹션에 넣을 수 있는 것은 아닙니다. 예를 들어 Rule의 도메인은 정책을 결정하고 Host의 도메인은 이름 매핑을 결정하므로 역할이 다릅니다.

최소 설정으로 검증 가능한 기준 만들기

사용할 수 있는 서버가 이미 있다면 아래 예제로 설정 구조를 먼저 살펴보세요. 여기서 General은 일부 시스템 트래픽을 우회할지 여부만 설명하고, Rule은 로컬 네트워크와 최종 정책을 지정합니다. 모든 네트워크에 적용되는 완성된 템플릿이 아니며 서버 인증 정보도 포함하지 않습니다. 실제로 수정할 때는 현재 Config를 복사해 원본을 보존하고 복사본에서 항목별로 바꾸세요. 예제를 적용하려고 기존 DNS, 규칙 또는 네트워크 관련 매개변수를 삭제하지 마세요.

[General]
bypass-system = true

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
FINAL,PROXY

bypass-system = true는 일부 시스템 트래픽을 클라이언트가 처리할지에 영향을 줍니다. 그렇다고 모든 시스템 요청이 연결 기록에 표시된다고 볼 수는 없습니다. 규칙 로그에는 클라이언트가 실제로 처리하고 식별할 수 있는 요청만 나타납니다. 시스템 기능의 기록이 보이지 않는다면 Rule이 잘못됐다고 단정하기 전에 해당 트래픽이 처리 범위에 들어오는지 확인하세요. 곧바로 범위가 지나치게 넓은 도메인 규칙을 추가하지 마세요.

설정 파일, 서버 목록, 현재 연결 구분하기

Config의 파일은 트래픽 처리 방식을 지정하고, Home에 등록된 서버는 연결 대상을 제공합니다. 규칙에 PROXY를 썼다고 서버 주소가 설정 파일에 입력되는 것은 아니며, 클라이언트가 사용 가능한 연결을 선택했다는 뜻도 아닙니다. 문제를 확인할 때는 현재 활성화된 설정 파일, Global Routing 상태, Home에서 선택한 항목을 각각 확인하세요. 파일 이름이 비슷하거나 가져오기에 성공했다는 사실만으로 이번 요청이 방금 수정한 내용을 사용한다고 판단할 수 없습니다.

수정한 뒤 저장하고 Config로 돌아가 대상 파일이 선택되어 있는지 확인한 다음, 앱 화면의 안내에 따라 연결 설정을 다시 적용하세요. 원격 설정이라면 로컬 수정 내용과 원본 업데이트의 관계도 확인해야 합니다. 다시 다운로드하면 로컬 수정이 덮어써질 수 있고, 복사본으로 저장하면 원래 설정을 자동으로 따라가지 않을 수 있습니다. 복사본에는 용도를 알아볼 수 있는 이름을 붙이고 파일 첫 부분에 수정 이유를 적으세요. 비슷한 버전을 숫자로만 구분하지 않는 것이 좋습니다.

문법은 문자와 해당 섹션부터 확인

규칙 필드는 영문 쉼표를 사용하고, 키-값 항목에는 보통 영문 등호를 사용합니다. 섹션 이름과 정책 이름은 영문 그대로 유지하세요. 한글 문장 부호, 복사 과정에서 포함된 보이지 않는 문자, 줄바꿈으로 나뉜 불완전한 규칙은 파싱 오류를 일으킬 수 있습니다. 한 줄에 유효한 항목 하나만 작성하고, 설명은 별도 줄에서 #으로 시작하세요. 필드 중간에 설명을 넣거나 웹 페이지에 표시된 줄 번호를 파일에 복사하지 마세요.

저장할 수 있는 파일이라고 해서 의도한 대로 작동하는 것은 아닙니다. 저장은 텍스트와 문법 오류만 해결할 뿐, 실제 적용 여부는 현재 파일과 모드, 트래픽 처리 범위, 서버 상태에도 달려 있습니다. 유지 관리할 때는 정상적으로 접속되는 기준 설정을 보관하고 한 번에 한 종류의 설정만 변경한 뒤 같은 요청으로 다시 확인하세요. 문제가 생겨도 어느 단계로 되돌릴지 명확해져 여러 섹션의 변경 사항을 한꺼번에 추적할 필요가 없습니다.

[Rule]

도메인 규칙의 범위와 경계

도메인 라우팅은 “이 서비스에 어떤 정책을 적용할지” 표현하는 데 적합하지만, 먼저 매칭 범위를 정확히 선택해야 합니다. Rule에서 자주 쓰는 도메인 키워드는 DOMAIN, DOMAIN-SUFFIX, DOMAIN-KEYWORD입니다. 이 키워드들은 전체 URL을 매칭하지 않습니다. 프로토콜, 경로, 쿼리 매개변수, 포트를 도메인 필드에 넣을 수 없으며 브라우저 주소창의 전체 주소를 호스트 이름 대신 사용할 수도 없습니다. 판단할 때 요청을 프로토콜, 호스트, 포트, 경로로 나눈 다음 호스트 부분을 확인하세요.

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

DOMAIN,example.com,PROXY는 지정한 도메인과 매칭하며 api.example.com까지 자동으로 포함하지 않습니다. 특정 호스트에 예외를 적용해야 한다면 DOMAIN을 사용하는 편이 넓은 범위의 규칙보다 검토하기 쉽습니다. 같은 서비스라도 기본 사이트와 파일 API에 서로 다른 정책을 적용할 수 있습니다. 정확한 호스트를 별도 항목으로 먼저 지정하면 나중에 추가하는 전체 사이트 규칙이 예외를 덮는 일을 막을 수 있습니다. 도메인은 대소문자를 구분하지 않는 경우가 많지만, 관리할 때 소문자로 통일하면 중복을 확인하기 쉽습니다.

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

이 예제는 나열한 호스트 세 개만 처리하고 나머지는 FINAL에 따릅니다. 페이지에서 이미지나 API 데이터가 계속 누락된다면 DOMAIN이 작동하지 않는 것이 아니라 페이지가 목록에 없는 다른 도메인을 참조하는 문제일 수 있습니다. 페이지를 열면 여러 연결이 발생할 수 있으므로 확인할 때 실패한 리소스의 호스트와 기본 문서의 호스트를 구분하세요. 주소창에 보이는 이름 하나만으로 모든 리소스의 연결 경로를 판단하지 마세요.

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

같은 도메인 체계의 서비스에 동일한 정책을 적용하려면 DOMAIN-SUFFIX,example.com,PROXY를 사용할 수 있습니다. 이 규칙은 example.com과 api.example.com 같은 하위 도메인을 포함합니다. 임의의 문자열 끝부분을 검사하는 규칙으로 이해하면 안 됩니다. otherexample.com은 example.com의 하위 도메인이 아닙니다. 규칙 필드에는 도메인 접미사만 쓰고 앞에 별표를 붙이거나 https://를 넣지 마세요.

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

이 예제에서는 정확한 호스트를 접미사 규칙보다 먼저 배치했으므로 local.example.com에는 DIRECT를 적용하고, 해당 접미사에 매칭되는 나머지 요청에는 PROXY를 적용합니다. 두 줄의 순서를 바꾸면 접미사 규칙이 먼저 호스트를 처리해 뒤에 있는 예외에 도달하지 못합니다. 규칙이 자동으로 더 정확한 항목을 찾아주는 것은 아닙니다. ‘정확한 규칙을 앞에 둔다’는 것은 파일 작성자가 직접 정하는 방식입니다.

DOMAIN-KEYWORD: 넓은 범위의 매칭은 추가 검토 필요

DOMAIN-KEYWORD는 도메인에 포함된 키워드를 기준으로 매칭하며 도메인 소유권 경계를 따르지 않습니다. 예를 들어 DOMAIN-KEYWORD,example,PROXY는 example.com뿐 아니라 example이 들어간 여러 이름에 적용될 수 있습니다. 넓은 범위의 매칭이 명확히 필요한 경우에 적합하며, 간단히 작성할 수 있다는 이유만으로 DOMAIN-SUFFIX를 대체하는 데 쓰지 않는 것이 좋습니다. 키워드가 짧을수록 의도와 관계없는 대상까지 매칭될 가능성이 커집니다.

사이트 소유를 추측하지 말고 도메인 출처 확인

클라이언트가 도메인 규칙을 적용할 수 있는지는 이번 연결에서 사용할 수 있는 도메인 정보가 있는지에 달려 있습니다. 앱이 IP에 직접 연결하거나 기존 연결을 재사용하거나 별도의 방식으로 이름을 해석하면 기록에 표시되는 정보가 브라우저에 입력한 내용과 다를 수 있습니다. 먼저 요청 기록에 표시된 대상과 매칭 규칙을 확인한 뒤 도메인 조건과 IP 조건 중 무엇을 사용할지 결정하세요. 앱 전체를 프록시로 보내려고 너무 짧은 키워드를 사용해 범위를 넓히지 마세요. 예상하기 어려운 우회 효과가 생길 수 있습니다.

국제화 도메인은 화면에 표시되는 문자와 실제 요청에 사용되는 인코딩이 다를 수 있으므로 기록에 표시된 호스트 이름을 기준으로 확인하세요. 검색 결과의 리디렉션 링크를 최종 사이트 주소로 간주하지 마세요. 한 번의 리디렉션에 여러 도메인이 포함될 수 있고 새 연결마다 규칙이 다시 적용됩니다. “특정 사이트는 PROXY, 나머지는 DIRECT”가 목적이라면 DOMAIN-SUFFIX 및 FINAL,DIRECT 시나리오 안내를 참고하세요. 먼저 명확한 도메인 목록을 만든 다음 범위를 넓히세요.

[IP]

IP, GEOIP 및 USER-AGENT

도메인 규칙은 서비스 이름을, IP 규칙은 대상 주소 범위를 다룹니다. 서로 대체할 수 있는 표현은 아닙니다. 하나의 도메인이 여러 주소로 해석될 수 있고, 하나의 주소에서 여러 서비스가 운영될 수도 있습니다. 특정 웹사이트를 안정적으로 지정하려면 도메인 조건을 우선 고려하세요. 사무실 네트워크 대역이나 특정 기기를 직접 연결하려면 IP-CIDR로 명확하게 표현할 수 있습니다. 조건을 선택하기 전에 제어할 대상이 ‘이름 집합’인지 ‘주소 집합’인지 먼저 정하세요.

IP-CIDR 및 프리픽스 길이

IPv4 CIDR은 네트워크 주소와 슬래시 뒤의 프리픽스 길이로 구성됩니다. 프리픽스가 길수록 포함되는 주소 수가 적습니다. /32는 IPv4 주소 하나를, 192.168.0.0/16은 비교적 넓은 사설 주소 범위를 나타냅니다. CIDR 필드에 포트를 넣거나 네트워크 주소 대신 도메인을 사용하지 마세요. 기기 한 대만 처리하려면 사설 네트워크 전체를 포함하는 대신 해당 주소를 정확히 지정하세요.

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

위의 세 범위는 일반적인 사설 IPv4 주소 공간이며 현재 네트워크가 실제로 이 범위를 사용한다는 뜻은 아닙니다. 실제 네트워크에 중복 경로나 원격 내부망, 전용 액세스 요구 사항이 있다면 자체 주소 계획에 맞춰 조정해야 합니다. 규칙에서 DIRECT를 선택해도 프록시 정책을 거치지 않을 뿐입니다. 시스템에 없는 경로를 만들거나 네트워크 권한이 없는 주소에 연결할 수 있게 해주지는 않습니다.

IP-CIDR6 및 듀얼 스택 요청

IPv6에는 IP-CIDR6,fd00::/8,DIRECT와 같이 IP-CIDR6을 사용합니다. IPv4 주소와 IPv6 주소를 같은 키워드 뒤에 넣지 마세요. 기기에서 두 주소를 모두 받을 수 있고 앱이 한쪽 주소를 우선해 연결할 수도 있습니다. 따라서 IPv4 규칙만 수정해도 실제 연결 경로가 바뀌지 않을 수 있습니다. 테스트할 때는 한 번의 DNS 조회 결과만 보지 말고 해당 연결에 사용된 주소 체계를 확인하세요.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR6,fd00::/8,DIRECT
GEOIP,CN,DIRECT
FINAL,PROXY

이 설정은 서로 다른 주소 조건의 조합을 표현할 뿐 모든 로컬 네트워크 환경에서 작동한다고 보장하지 않습니다. IPv6의 링크 범위, 네트워크 인터페이스, 시스템 경로에는 별도의 제약이 있습니다. 기록에 IPv6 대상이 표시되는데 설정에 IPv4 항목만 있다면 먼저 의도한 동작을 확인한 뒤 필요한 범위를 추가하세요. 전체 주소 공간을 DIRECT로 지정하는 방식으로 일반적인 문제를 해결하려 하지 마세요.

GEOIP는 주소의 위치 정보 데이터를 기준으로 판단

GEOIP,CN,DIRECT는 클라이언트가 사용하는 IP 위치 정보 데이터베이스를 기준으로 대상 주소를 판단합니다. 웹페이지 언어, 도메인 등록 국가, 계정 지역을 판별하는 규칙이 아닙니다. 콘텐츠 전송 네트워크는 위치에 따라 서로 다른 주소를 반환할 수 있고 데이터베이스 정보가 실제 배포 환경과 다를 수도 있습니다. 따라서 GEOIP는 넓은 범위의 정책 중 하나로 활용해야 하며 특정 웹사이트의 위치를 판단하는 유일한 근거로 삼지 마세요. 중요한 서비스에는 GEOIP보다 앞서 명확한 도메인 규칙을 추가할 수 있습니다.

도메인 요청이 대상 주소를 필요로 하는 규칙과 만나는 경우 이름 해석이 필요할 수 있습니다. 선택 항목인 no-resolve는 IP 규칙이 도메인 매칭을 위해 추가 조회를 요청하지 않도록 할 때 사용합니다. 예: IP-CIDR,192.168.0.0/16,DIRECT,no-resolve. 이 옵션은 앱 전체의 DNS를 끄지 않으며 이미 알고 있는 IP의 매칭을 막지도 않습니다. 사용 여부는 이름 해석 의도에 따라 결정하세요. 항상 속도를 높이는 스위치로 간주하면 안 됩니다.

USER-AGENT 정보 확인의 한계

USER-AGENT,ExampleApp*,DIRECT는 확인 가능한 User-Agent 정보를 기준으로 매칭하며, 예시의 별표는 뒤에 이어지는 문자를 포함합니다. 여기서 매칭하는 것은 요청 식별자이지 운영체제의 앱 설치 파일 이름이 아닙니다. 여러 프로그램이 같은 식별자를 사용할 수 있고 하나의 프로그램도 요청마다 다른 식별자를 보낼 수 있으므로 신뢰할 수 있는 프로세스별 라우팅 수단으로 대체해서는 안 됩니다.

암호화된 요청은 클라이언트가 HTTP 요청 헤더를 읽지 못할 수 있습니다. Rule에 USER-AGENT를 추가한다고 해서 해당 정보가 자동으로 제공되는 것은 아니며, 이를 위해 인증서 설정을 무작정 바꾸어서도 안 됩니다. 기록에 해당 필드가 없다면 정보를 확인할 수 없다는 점을 받아들이고 관찰 가능한 도메인이나 주소 조건을 사용하세요. 경로나 요청 헤더가 필요한 요구 사항은 일반 연결 라우팅과 별도로 검토해야 합니다. 규칙이 완성된 것처럼 보여도 실제로 매칭될 수 없는 상황을 피하세요.

[Policy]

정책과 Global Routing의 관계

규칙은 “이 조건에 매칭되는가”를 판단하고, 정책은 “매칭된 뒤 어떻게 처리할 것인가”를 정합니다. PROXY, DIRECT, REJECT는 정책 이름이지 프로토콜 유형이나 서버 주소가 아닙니다. Shadowsocks, VMess, VLESS, Trojan, Hysteria2, WireGuard 등의 이름은 연결 방식을 나타냅니다. PROXY를 지정한 규칙은 현재 사용할 수 있는 프록시 연결을 통해 처리할 수 있습니다. 서버를 설정하려고 정책 이름을 프로토콜 이름으로 바꾸면 안 됩니다.

PROXY: 요청을 현재 프록시 경로로 전달

규칙이 PROXY를 선택하려면 설정되어 있고 사용할 수 있는 프록시 대상이 있어야 합니다. 주소, 포트, 인증, 전송 방식, TLS 등의 설정이 올바른지는 연결 설정 문제이고 도메인이 이 규칙에 매칭되는지는 라우팅 문제입니다. 두 가지는 각각 성공하거나 실패할 수 있습니다. 로그에 PROXY 매칭이 표시되는데도 웹페이지가 열리지 않는다면 규칙이 작동하지 않는다는 뜻은 아닙니다. 선택된 서버에 연결할 수 없거나 인증이 잘못됐거나 서버가 대상에 접속하지 못하는 경우일 수 있습니다.

먼저 Home에서 선택된 항목을 확인하고 Connectivity Test로 연결 상태를 살펴보세요. 테스트 결과는 해당 조건에서의 상태만 보여주며 모든 사이트, 포트, 프로토콜의 작동을 보장하지 않습니다. Trojan의 비밀번호, SNI, TLS 필드를 확인해야 한다면 Trojan 매개변수별 안내를 참고하세요. 원격 인증 실패를 도메인 규칙 추가로 감추지 마세요.

DIRECT 및 REJECT의 적용 범위

DIRECT는 대상 연결이 프록시 정책을 거치지 않는다는 뜻이며 로컬 네트워크, 시스템 권한, DNS, 경로, 대상 서비스의 영향을 계속 받습니다. 직접 연결에 실패했다고 해서 반드시 프록시로 바꿔야 하는 것은 아니며 클라이언트가 요청을 차단했다고 단정할 수도 없습니다. REJECT는 매칭된 요청을 거부할 때 사용하며 차단이 필요하다고 확인된 대상에 적합합니다. 다른 연결로 자동 전환하거나 프록시 연결 실패 시 임시로 대체 경로를 선택한다는 뜻이 아닙니다.

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

이 예제는 거부 조건을 앞에 두고 내부 서비스를 다음에 배치한 뒤 접미사 규칙으로 나머지 하위 도메인을 처리합니다. REJECT 이후 클라이언트가 앱에 실패를 표시하는 방식은 요청 유형에 따라 다를 수 있으므로 오류 페이지 모양만으로 규칙 매칭 여부를 판단하지 마세요. 대상, 정책, 규칙 기록이 일치하는지를 확인하는 편이 더 정확합니다.

Global Routing의 세 가지 모드

Global Routing의 Config / Proxy / Direct는 각각 인터페이스에 표시되는 Config / Proxy / Direct 항목에 해당합니다. Config는 현재 설정 파일에 따라 라우팅하며 Rule을 확인할 때 주로 사용합니다. Proxy와 Direct는 처리 범위 내 연결 전체를 각각 프록시 또는 직접 연결 경로로 보내는 모드입니다. 이 모드에서는 일반 Rule이 Config와 같은 방식으로 한 줄씩 실행된다고 가정할 수 없습니다. 여기서 말하는 전체 연결도 시스템의 트래픽 처리 범위에 제한되며 기기의 모든 트래픽이 반드시 같은 경로를 거친다는 뜻은 아닙니다.

모드 비교는 문제 진단용이며 여러 설정을 동시에 바꾸지 마세요

Config에서는 실패하지만 Proxy에서는 성공한다면 라우팅 방향이나 이름 해석 경로를 의심할 수 있습니다. 그래도 기록을 확인해야 합니다. 둘 다 실패하면 Rule 범위를 넓히기 전에 프록시 연결과 대상 서비스를 확인하세요. Direct에서는 성공하지만 Proxy에서는 실패한다면 프록시 서버가 해당 대상과 포트를 지원하는지 살펴보세요. 모드를 바꾼 뒤에는 요청을 새로 시작해 테스트하세요. 기존 연결이 재사용된 결과를 새 모드의 동작으로 오해하지 않도록 주의하세요.

On Demand는 네트워크 조건에 따라 언제 연결을 시작할지 결정하며, 특정 도메인이 최종적으로 PROXY와 DIRECT 중 어디에 매칭되는지와는 다른 단계입니다. 자동 연결이 시작됐다고 정책이 올바르다는 뜻은 아니며, 자동 연결이 시작되지 않았다고 Rule로 트리거 조건을 해결할 수도 없습니다. 연결 스위치, Global Routing, Config, 서버 선택을 네 가지 항목으로 나눠 확인하면 문제를 더 빠르게 좁힐 수 있습니다. 관련 인터페이스 용어는 용어 안내에서 확인하세요.

[Priority]

매칭 순서와 자주 쓰는 규칙 작성법

Rule의 핵심 원칙은 위에서 아래로 확인해 처음 매칭된 유효 조건의 정책을 적용하는 것입니다. 모든 매칭 항목을 모은 뒤 가장 구체적으로 보이는 항목을 고르지 않으며 뒤에 쓴 항목이 앞의 항목을 자동으로 덮어쓰지도 않습니다. 파일을 정리할 때는 명확한 예외를 넓은 범위의 조건보다 앞에 두고 FINAL은 끝에 배치하세요. 키워드를 많이 외우는 것보다 이 원칙을 이해하는 것이 중요합니다. 많은 ‘규칙이 작동하지 않는’ 문제는 앞선 조건이 이미 대상을 포함한 경우입니다.

지정한 도메인은 PROXY, 나머지는 DIRECT

프록시 적용 범위를 명확히 제한하고 나머지 요청은 로컬 네트워크로 연결하려는 경우에 적합한 방식입니다. 정확한 예외를 먼저 나열하고 도메인 접미사를 배치한 다음 FINAL,DIRECT를 사용하세요. 이 규칙은 웹사이트가 의존하는 모든 서비스를 자동으로 찾아주지 않습니다. 로그인, 이미지, API가 다른 도메인을 사용한다면 요청 기록을 보고 하나씩 확인해야 합니다. 페이지가 완전히 표시되지 않는다는 이유만으로 DOMAIN-KEYWORD로 범위를 넓히거나 FINAL을 PROXY로 바꾸지 마세요.

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

테스트할 때는 적어도 세 종류의 대상을 준비하세요. 프록시를 사용해야 하는 호스트, 직접 연결 예외로 남겨야 하는 호스트, 목록에 전혀 없는 호스트입니다. 각각의 매칭 규칙과 정책을 확인해야 설정 의도 전체를 검증할 수 있습니다. example.com 하나가 정상이라고 해서 local.example.com 예외나 FINAL의 방향도 올바르다는 뜻은 아닙니다.

사설 주소는 직접 연결, 나머지는 PROXY

다른 유형의 설정은 로컬 기기 접속을 유지하고 나머지 요청을 PROXY로 보냅니다. 여기서 ‘나머지’에는 목록에 없는 업무용 도메인과 앱 연결도 폭넓게 포함되므로 먼저 서버가 사용 가능한지 확인하고 원격 연결에 따른 경로 변화를 이해해야 합니다. 사설 주소 항목도 실제 네트워크에 맞아야 합니다. 원격 사설 네트워크에서 같은 주소 대역으로 프록시 접속해야 한다면 일반적인 로컬 네트워크 직접 연결 규칙과 충돌할 수 있습니다.

[Rule]
IP-CIDR,192.168.0.0/16,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR,172.16.0.0/12,DIRECT
IP-CIDR6,fd00::/8,DIRECT
FINAL,PROXY

이 예제는 의도를 명확하게 유지하기 위해 GEOIP를 추가하지 않았습니다. 여기에 GEOIP,CN,DIRECT를 넣으면 더 넓은 범위의 다른 라우팅 구성이 됩니다. 두 방식 모두 요구 사항을 표현할 수 있지만 조건을 추가하는 일을 동작에 영향이 없는 장식처럼 취급하지 마세요. 모든 줄은 설명할 수 있는 역할이 있어야 하며 검증 가능한 요청과 연결되어야 합니다.

FINAL은 연결 실패 시 사용하는 대체 경로가 아님

FINAL은 앞선 조건에 하나도 매칭되지 않을 때 적용하는 정책이지 앞선 연결이 실패한 뒤 전환되는 정책이 아닙니다. 요청이 PROXY에 매칭된 뒤 시간 초과가 발생해도 일반적으로 FINAL,DIRECT를 계속 시도하지 않습니다. 사용 가능성에 따라 경로를 전환하려면 관련 정책 설정을 별도로 이해해야 합니다. FINAL을 여러 줄 나란히 써서 전환을 구현할 수는 없습니다. 유지 관리할 때는 같은 키워드를 여러 번 쌓기보다 명확한 FINAL 하나를 두는 편이 검토하기 쉽습니다.

[Rule]
# 먼저 단일 호스트 예외 지정
DOMAIN,download.example.com,DIRECT
# 그런 다음 나머지 하위 도메인 포함
DOMAIN-SUFFIX,example.com,PROXY
# 마지막으로 앞서 매칭되지 않은 요청 처리
FINAL,DIRECT

설정 병합 전 가림 관계부터 정리

두 규칙을 합치기 전에 각각의 FINAL, 광범위한 도메인 조건, 넓은 IP 범위를 비교하세요. 첫 번째 파일의 FINAL이 중간에 남아 있으면 두 번째 파일의 문법이 맞더라도 검사되지 않을 수 있습니다. 마찬가지로 example.com 전체를 포함하는 접미사 규칙이 아래쪽의 개별 호스트 여러 개를 가릴 수 있습니다. 중복 항목은 뒤에 작성한 수정 사항이 적용됐다고 착각하게 만들기도 합니다.

‘명확한 거부, 구체적인 예외, 서비스 도메인, 주소 범위, 지역 조건, 최종 정책’ 순서로 검토하는 방법을 권장합니다. 이는 정리 방법일 뿐 클라이언트가 강제하는 우선순위는 아닙니다. 업무상 IP 조건을 도메인 조건보다 먼저 적용해야 한다면 순서를 명시적으로 조정하고 이유를 기록하세요. 키워드를 알파벳순으로 기계적으로 정렬하지 마세요. 처음 매칭되는 결과가 달라질 수 있습니다.

공유 서비스에서는 특히 한 번의 조회로 얻은 IP를 장기적인 도메인 규칙 대신 사용하지 마세요. 주소가 바뀔 수 있고 관계없는 서비스가 같은 주소를 사용할 수도 있습니다. 이 주소를 규칙 앞에 배치하면 다른 요청에도 영향을 줍니다. 수정 전후의 차이를 기록하고 되돌릴 수 있는 파일을 보관하는 편이 ‘항목을 많이 넣을수록 완전하다’고 생각하는 것보다 복잡한 설정을 안정적으로 관리하는 방법입니다. 자주 발생하는 증상별 추가 안내는 자주 묻는 질문에서 확인하세요.

[Host]

Host 매핑 및 DNS 경로

Host와 Rule은 한 설정 파일에 함께 들어가는 경우가 많지만 해결하는 문제는 다릅니다. Host는 이름에 대응하는 주소를 지정하고 Rule은 요청에 적용할 정책을 결정합니다. 도메인을 IP에 매핑해도 DIRECT가 지정되는 것은 아닙니다. 도메인에 PROXY를 지정해도 DNS 결과가 고정되는 것은 아닙니다. 도메인 접속 문제를 확인할 때는 ‘이름이 어떻게 주소를 얻는가’와 ‘연결이 대상에 어떻게 도달하는가’를 구분하세요. 그렇지 않으면 잘못된 섹션을 계속 수정하게 됩니다.

정적 매핑 기본 문법

아래 Host 예제는 문서용 주소로 등호 양쪽의 구성을 보여줍니다. 왼쪽은 전체 호스트 이름이고 오른쪽은 대상 IP입니다. 프로토콜이나 URL 경로는 포함하지 않습니다. 실제 환경에 적용할 때는 직접 관리하거나 사용할 권한이 있는 대상 주소로 바꾸세요. 예제 주소로 연결을 테스트하거나 출처가 불분명한 주소를 자주 사용하는 서비스에 영구적으로 고정하지 마세요.

[Host]
portal.example.com = 192.0.2.20

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

이 예제에서는 DOMAIN으로 DIRECT를 명시하고 Host에서 주소를 지정해 두 가지 판단을 따로 설명합니다. 대상이 192.0.2.20으로 올바르게 해석되더라도 현재 네트워크에서 연결할 수 있다는 뜻은 아닙니다. 경로, 포트 수신 상태, 액세스 권한, 서버 상태도 정상이어야 합니다. 실제 테스트에는 유효한 본인 주소를 사용하세요. 기록에서 매핑이 적용됐는지와 서비스 접속이 성공했는지는 별도로 확인해야 합니다.

고정 주소를 지정해도 인증서의 도메인 이름은 바뀌지 않습니다

HTTPS 접속은 계속 원래 도메인 이름으로 인증하며 서버는 보통 SNI에 따라 인증서와 사이트를 선택합니다. Host는 이름에 대응하는 주소만 바꿉니다. 잘못된 인증서를 올바르게 바꾸거나 해당 도메인을 제공하지 않는 서버가 올바른 내용을 보여주게 만들지는 않습니다. 매핑한 뒤 인증서 오류가 발생하면 인증서 검증을 느슨하게 해 문제를 감추지 말고 서버가 실제로 해당 도메인의 서비스를 제공하는지 확인하세요.

마찬가지로 브라우저에서 IP에 직접 접속하는 경우와 도메인에 Host 매핑을 적용해 접속하는 경우는 같은 결과를 보장하지 않습니다. 요청의 호스트 정보가 다를 수 있고 서버의 가상 사이트도 서로 다를 수 있습니다. 문제를 확인할 때는 원래 도메인과 접속 경로를 유지하고 검증하려는 매핑 항목만 변경하세요. 여러 차이가 겹치면 어떤 변경이 결과에 영향을 줬는지 알 수 없습니다.

General의 이름 해석 매개변수는 따로 확인

General에는 dns-server = system과 같은 DNS 설정이 포함될 수 있으며, 이는 시스템의 이름 해석 경로를 사용한다는 뜻입니다. 기본 경로를 설명하는 간단한 예일 뿐 모든 환경에서 이 값을 사용해야 한다는 의미는 아닙니다. 네트워크 자체, 앱의 독립적인 이름 해석 방식, 프록시 서버의 처리 방식이 모두 최종적으로 관찰되는 과정에 영향을 줄 수 있습니다. DNS 서버 변경을 모든 문제에 적용되는 해결책으로 보지 마세요.

[General]
dns-server = system

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

이 예제에는 정적 매핑이 없어 Host 설정과 비교하기 쉽습니다. 이전 매핑이 계속 적용되고 있다면 DNS 서버를 바꿔도 해당 호스트의 주소가 달라지지 않을 수 있습니다. 앱이 기존 연결을 재사용한다면 DNS를 다시 조회해도 현재 연결은 바뀌지 않을 수 있습니다. Host 항목이 있는지와 새 연결이 생성됐는지 먼저 확인한 다음 이름 해석 설정이 영향을 주었는지 판단하세요.

캐시, 앱의 이름 해석 및 복수 주소 결과

DNS 결과는 시스템, 클라이언트, 앱의 캐시에 남을 수 있으며 웹사이트 연결도 오랫동안 재사용될 수 있습니다. 설정을 바꾼 직후 페이지를 새로 고쳐도 새 이름 해석이 완전히 시작된다고 볼 수는 없습니다. 먼저 진행 중인 작업을 중지하고 연결 설정을 다시 적용한 다음 대상을 다시 여세요. 필요한 경우 앱에서 제공하는 캐시 작업을 이용하세요. 특정 대상의 오래된 결과를 지우려고 모든 설정과 네트워크 설정을 함께 초기화하지 마세요.

같은 이름에서 IPv4와 IPv6 주소가 모두 반환된다면 한 주소만 고정하거나 한 종류의 조회 결과만 확인해도 모든 연결이 예상대로 처리된다는 뜻은 아닙니다. 연결 기록에 표시된 실제 주소를 기준으로 주소 체계, 매칭 규칙, 정책을 각각 확인하세요. 내부망 이름은 사무실 네트워크와 다른 네트워크에서 따로 테스트해야 합니다. 사무실 밖에서는 기존 DNS 검색 도메인과 사설 주소 경로를 사용할 수 없을 수 있습니다.

유지 관리할 때는 각 고정 매핑의 용도를 분명히 기록하고 서버가 여전히 해당 도메인을 처리하는지 주기적으로 확인하세요. 임시 점검이 끝났다면 더 이상 필요하지 않은 매핑을 삭제하고 기준 설정으로 되돌리세요. 몇 달 뒤 만료된 주소를 규칙 오류로 오해할 수 있습니다. 확인할 수 없는 요청에 대해 추측으로 Host를 추가하지 마세요. 먼저 요청 호스트, 대상 주소, 오류 유형을 수집한 다음 수정할 위치를 정하세요.

[URL Rewrite]

URL Rewrite의 표현식과 한계

URL Rewrite는 식별 가능한 URL을 처리합니다. Rule에서 호스트나 주소에 따라 연결 정책을 정하는 것과는 다릅니다. 명확한 주소 변경이나 리디렉션이 필요한 경우에 사용하며 앱 전체의 라우팅 스위치로 취급하면 안 됩니다. 추가하기 전에 무엇을 바꾸려는지 확인하세요. 연결 경로, 이름에 대응하는 주소, 요청 URL 중 어떤 항목을 바꿔야 하나요? 앞의 두 가지는 각각 Rule과 Host를 우선 고려하고, 세 번째인 경우에만 이 섹션의 방법을 검토하세요.

관찰 가능한 HTTP 리디렉션부터 확인

아래 설정은 매칭된 평문 HTTP 주소를 같은 도메인의 HTTPS 주소로 리디렉션하며, 302는 임시 리디렉션을 의미합니다. 문법 구조만 보여주는 예제이며 대상 사이트에서 HTTPS 서비스를 제공한다는 뜻은 아닙니다. 왼쪽에는 원래 주소를 매칭하는 표현식, 가운데에는 대체할 주소, 마지막에는 처리 방식을 씁니다. 각 부분을 구분하는 공백을 한글 문장 부호로 바꾸지 마세요.

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

^는 문자열의 시작 부분에서 매칭하도록 제한하고 \.은 도메인의 실제 점을 나타냅니다. (.*)은 뒤에 오는 내용을 캡처하며 $1은 대체 주소에서 첫 번째 캡처 그룹을 참조합니다. 도메인의 점을 정규식에서 임의의 문자로 쓰면 표현식 범위가 예상보다 넓어집니다. 캡처 참조를 빠뜨리면 원래 경로가 사라져 다른 페이지로 이동할 수 있습니다.

호스트와 경로를 제한해 매칭 범위를 넓히지 않기

안전한 규칙은 보통 특정 단어가 포함된 모든 URL을 바꾸기보다 프로토콜, 호스트, 경로 접두사를 명확히 제한합니다. 도메인과 경로에 같은 키워드가 들어갈 수 있고 기준점이 없는 표현식은 쿼리 매개변수에서 예상치 않게 매칭될 수 있습니다. 작성할 때는 매칭되어야 하는 주소 하나와 비슷하지만 매칭되면 안 되는 주소를 몇 개 준비해 경계 사례를 테스트하세요. 성공 사례 하나만 확인하지 마세요.

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

이 예제는 지정한 호스트의 old 경로 접두사만 처리하며 다른 사이트나 경로까지 함께 바꾸지 않습니다. 원래 주소에 쿼리 매개변수가 있다면 캡처한 뒤 대체된 결과도 예상과 일치하는지 확인하세요. 로그인 상태, 임시 권한, 제출 작업이 포함된 URL은 특히 주의해야 합니다. 경로나 리디렉션 방식을 바꾸면 서버가 요청을 해석하는 방식이 달라질 수 있습니다.

HTTPS에서 내용을 읽을 수 있는 것은 규칙 한 줄로 해결되지 않습니다

HTTPS는 암호화된 연결로 요청 내용을 보호하므로 전체 URL 경로와 요청 헤더를 클라이언트가 직접 읽지 못할 수 있습니다. 규칙에 HTTPS 표현식을 추가해도 모든 암호화 요청에 적용되는 것은 아닙니다. 처리 가능한 정보가 있는지는 실제 연결 방식과 관련 설정에 달려 있습니다. Rewrite를 추가하는 것과 요청 내용을 확인할 수 있게 되는 것을 혼동하지 마세요. 예제가 매칭되게 하려고 인증서 관련 설정을 무작정 활성화하지 마세요.

일부 앱은 추가 인증서 제약이나 별도의 네트워크 구현을 사용할 수 있으므로 브라우저에서 적용되는 방법이 해당 앱에서도 통한다는 보장은 없습니다. 특정 사이트를 PROXY로 보내려는 목적이라면 도메인 Rule로 충분히 표현할 수 있으며 암호화된 내용을 읽을 필요는 없습니다. 필요한 연결 계층만 대상으로 삼으면 추가 의존성을 줄이고 설정의 영향 범위도 쉽게 확인할 수 있습니다.

리디렉션 반복과 캐시로 인한 오판

클라이언트가 A를 B로 바꾸고 서버가 다시 B를 A로 보내면 리디렉션이 반복됩니다. 페이지가 계속 로드되거나 리디렉션 횟수 초과가 발생하거나 페이지가 완료되지 않을 수 있지만 어떤 Rewrite가 원인인지 명확하게 표시되지 않을 수도 있습니다. 문제를 확인할 때는 새로 추가한 규칙 하나만 비활성화하고 Rule은 그대로 둔 채 반복이 사라지는지 살펴보세요. Global Routing까지 동시에 바꾸면 어떤 변경이 결과에 영향을 줬는지 알 수 없습니다.

브라우저가 서버의 리디렉션이나 강제 전송 정책을 기억해 평문 주소를 요청하기도 전에 HTTPS로 변경할 수 있습니다. 이 경우 HTTP 규칙이 매칭되지 않는다고 해서 반드시 표현식 문법 오류인 것은 아닙니다. 제어 가능한 테스트 주소와 새로운 접속으로 확인하고 실제 요청 프로토콜과 리디렉션 경로를 살펴보세요. 실제 서비스에서 제출 작업이 포함된 요청을 반복해서 재전송하지 마세요. 같은 동작이 중복 실행될 수 있습니다.

한 번의 접속에서 Rewrite와 Rule이 함께 적용될 수 있습니다. 원래 주소가 바뀐 뒤 새 요청은 실제 대상에 따라 연결 처리를 다시 받습니다. 따라서 ‘최종적으로 어떤 정책을 사용하는지’ 확인하려면 처음 입력한 URL이 아니라 최종 요청을 살펴봐야 합니다. 유지 관리할 때는 리디렉션의 목적과 예상 입력·출력을 기록하고 테스트 후 임시 항목을 삭제하세요. 인증이나 결제처럼 민감한 절차에서는 서비스가 원래 제공하는 주소 동작을 유지하고 일반 예제를 실제 업무에 그대로 적용하지 마세요.

[Diagnostics]

검증, 유지 관리 및 문제 진단

설정을 검증하려면 ‘예상한 조건에 매칭되는지’와 ‘연결이 예상한 경로로 완료되는지’를 모두 확인해야 합니다. 페이지가 열린다는 사실만으로는 충분하지 않습니다. 페이지가 캐시에서 표시되거나 기존 연결을 통해 로드됐을 수 있고, 테스트 도구에서 연결할 수 있다고 나와도 대상 서비스가 요청을 받아들인다는 뜻은 아닙니다. 반복 가능한 테스트 동작을 하나 정하고 한 번에 한 가지 설정만 바꾸세요. 대상 호스트와 주소, 매칭된 규칙, 정책, 결과를 기록하는 것이 좋습니다.

정해진 순서로 확인할 여섯 가지 항목

1. 클라이언트 연결이 켜져 있는지, 현재 네트워크가 방금 전환되지 않았는지 확인합니다.
2. 이번 테스트에 필요한 Global Routing이 Config인지 확인합니다. 이전에 설정한 Proxy 또는 Direct가 남아 있지 않은지도 살펴보세요.
3. Config에서 현재 선택된 파일을 확인하고 파일을 열어 수정 내용이 저장됐는지 살펴봅니다.
4. Home에서 선택된 서버를 확인하고 연결 매개변수와 기본 연결 상태를 각각 점검합니다.
5. 대상 요청을 새로 시작하고 실제 도메인, 주소, 매칭 정책을 확인해 기존 연결 재사용 여부를 배제합니다.
6. 관찰 결과와 직접 관련된 설정 하나만 변경한 뒤 같은 동작으로 다시 테스트하고 차이를 기록합니다.

이 순서는 연결 계층과 규칙 계층을 분리합니다. 첫 번째 단계가 정상적이지 않다면 DOMAIN-SUFFIX를 수정해도 의미가 없습니다. 현재 파일이 올바르지 않다면 문법이 정확해도 요청에 영향을 줄 수 없습니다. 가져오기 절차가 익숙하지 않다면 먼저 사용 방법 안내로 돌아가 연결에 성공한 뒤 규칙을 세부 조정하세요. 빈 설정에서 서버와 라우팅을 동시에 조정하는 것보다 원인을 파악하기 쉽습니다.

증상에 따라 점검 항목 선택

기록에 예상과 다른 규칙이 매칭되면 파일에서 위쪽으로 이동하며 먼저 적용된 범위 조건을 확인하세요. 기록에 예상한 정책이 표시된다면 연결과 대상 서비스를 살펴보세요. 같은 도메인의 요청마다 결과가 다르다면 주소 체계, 포트, 실제 주소, 연결 생성 시각도 비교해야 합니다. 서로 다른 조건을 한데 묶어 ‘규칙이 될 때도 있고 안 될 때도 있다’고만 결론 내리지 마세요.

설정을 전부 삭제하지 말고 작은 설정으로 재현

복잡한 파일에서 원인을 찾기 어렵다면 현재 설정을 복사하고 복사본에 필요한 General, 대상 조건 하나, FINAL만 남겨 단계별로 재현하세요. 원본은 복구용으로 보관하고 바로 비우지 마세요. 아래 예제는 도메인 조건이 매칭되는지 확인하는 데 적합합니다. 사용할 때 테스트 대상을 이미 보유한 서비스로 바꾸세요. example.com 접속 결과를 자신의 서버 상태로 간주하지 마세요.

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

최소 설정이 예상대로 작동한다면 기존 규칙을 그룹별로 복구하면서 차이가 생기는 시점을 확인하세요. 이를 통해 다른 규칙에 가려진 항목, 범위가 지나치게 넓은 키워드, 앞쪽에 배치된 FINAL을 찾을 수 있습니다. 복구할 때는 General과 이름 해석 조건도 동일하게 유지해야 합니다. 동작 변화가 새로 추가한 Rule이 아니라 DNS 경로에서 비롯됐을 수 있습니다. 한 번 성공했다고 전체 파일이 올바르다고 판단하지 말고 프록시, 직접 연결, 거부, 기본 정책에 해당하는 테스트 사례를 각각 확인하세요.

구독 업데이트와 로컬 설정은 따로 관리

Subscribe 업데이트는 주로 기존 서버 정보를 다루고 Config 업데이트는 규칙과 처리 방식을 다룹니다. 서로 다른 위치에서 제공되거나 새로 고치는 방식이 다를 수 있습니다. 업데이트 후에는 실제로 무엇이 바뀌었는지 확인하세요. 서버 목록을 새로 고쳤다고 로컬 규칙까지 함께 수정됐다고 가정하지 마세요. 구독 링크는 이용 중인 서비스 제공업체에서 받으세요. 개별 공유 링크와 구독의 차이는 공유 링크 형식 안내에서 확인할 수 있습니다.

설정 파일, 내보낸 파일, 로그에는 서버 주소와 계정 정보, 인증 매개변수가 포함된 링크가 들어갈 수 있습니다. 다른 사람에게 문제를 설명할 때는 필요한 규칙과 비식별 처리된 기록만 남기고 인증 정보와 전체 구독 주소를 삭제하세요. 규칙 예제의 도메인은 공개적으로 논의해도 되지만 실제 접속 기록에는 사용 습관이 드러날 수 있습니다. 파일 전체를 바로 보내지 말고 공유 전에 항목별로 확인하세요.

수정 후 회귀 테스트

마지막으로 자주 사용하는 네트워크에서 대상 서비스와 로컬 네트워크 접속, 기존에 정상 작동한 다른 앱을 각각 확인해 새 규칙의 영향이 넓어지지 않았는지 살펴보세요. On Demand를 설정했다면 네트워크 전환 후 연결이 시작되는지도 별도로 확인하세요. 도메인 매칭과 함께 테스트하지 마세요. 수정 전 파일과 변경 사항, 테스트 사례를 보관하면 나중에 문제가 생겼을 때 설정 문제, 서버 변경, 대상 서비스 변경을 구분할 수 있습니다.

이 페이지에서는 설정 원리와 규칙 범위를 설명합니다. 설치 및 다운로드 경로는 다운로드 안내, 자주 발생하는 오류는 자주 묻는 질문, 용어 설명은 용어 안내에서 확인하세요. 새로운 증상이 나타나면 먼저 관찰 가능한 사실을 수집한 뒤 관련 섹션을 살펴보세요. 설정 유지 관리의 목표는 모든 규칙에 명확한 목적을 두고, 변경 사항을 검증하며, 문제가 생기면 되돌릴 수 있게 하는 것입니다. 파일을 계속 길게 만드는 것이 목적은 아닙니다.