Shadowrocket 설정 파일 .conf 구조와 사용법: General·Rule·Host·URL Rewrite 설명

이 글 한눈에 보기

Shadowrocket 설정 파일을 읽을 때는 전역 매개변수, 요청 라우팅, 도메인 매핑, URL 변경을 구분한 뒤 현재 활성화된 파일을 확인하세요. 연결 정보를 이미 보유하고 .conf 파일을 편집하려는 사용자를 위해 각 섹션의 예제로 문법과 검증 방법을 설명합니다. 예시 도메인과 주소는 구조 설명용이며, 그대로 사용할 수 있는 완성된 설정이 아닙니다.

.conf 파일의 역할과 적용 위치 확인하기

Shadowrocket의 .conf는 텍스트 설정 파일로, 대괄호로 섹션을 구분하며 각 섹션은 해당 유형의 설정만 처리합니다. [General]에는 보통 키-값 매개변수가, [Rule]에는 한 줄씩 규칙이 들어갑니다. 같은 줄 형식을 모든 섹션에 복사할 수는 없습니다. 파일 확장자가 올바르더라도 모든 매개변수가 유효하다는 뜻은 아닙니다.

읽기 전에 Config에서 현재 선택된 설정 파일을 확인하고, Home → Global Routing에서 라우팅 모드를 점검하세요. 파일의 라우팅 규칙을 검증하려면 Config를 사용해야 합니다. Proxy 또는 Direct 상태에서 관찰한 연결 결과만으로 [Rule] 작성이 올바른지 판단할 수는 없습니다. Scene을 사용한다면 해당 Scene에 실제로 연결된 설정도 확인하세요.

원본 파일 백업 섹션 확인 설정 파일 선택 라우팅 모드 확인 요청 검증

연결 정보와 라우팅 설정은 별개의 항목입니다. 기존 구독을 업데이트하면 주로 해당 연결 정보가 바뀌므로, 로컬 .conf 파일도 함께 수정된다고 볼 수 없습니다. 원격 설정 파일을 업데이트하면 로컬 편집 내용이 덮어써질 수도 있습니다. 테스트 전에 원본을 보관하고 복사본에서 항목별로 수정하세요.

General: 키-값 매개변수로 전역 동작 제어

[General]은 key = value 형식을 사용합니다. 먼저 키 이름을 확인하고 값의 유형을 살펴보세요. 불리언 값을 받는 키도 있고, 주소나 목록을 받는 키도 있습니다. 등호와 쉼표를 한국어 문장부호로 바꾸지 말고, 규칙 행을 이 섹션에 넣지 마세요. 아래는 서로 독립적인 설정 두 가지 예시이며, 모든 네트워크에서 이 값을 사용해야 한다는 뜻은 아닙니다.

[General]
dns-server = system
ipv6 = false

dns-server = system은 시스템 DNS를 사용한다는 뜻이며, 모든 네트워크 환경에서 이름 조회가 정상적으로 된다는 보장은 없습니다. ipv6 = false는 전역 IPv6 관련 설정이지 도메인 라우팅 규칙이 아니며, 서버 측 IPv6 연결 상태를 확인하는 절차를 대신할 수도 없습니다. 문제가 생기면 원래 값을 보존해 비교하고, DNS 변경과 IPv6 조정, 규칙 순서 변경을 한꺼번에 하지 마세요.

General 점검 항목

섹션 이름: [General]
행 형식: key = value
DNS 예시: dns-server = system
IPv6 예시: ipv6 = false

먼저 현재 앱에서 매개변수를 인식하는지 확인한 다음, 변경 전후의 동작을 비교하세요.

Rule 점검 항목

섹션 이름: [Rule]
도메인 매칭: DOMAIN-SUFFIX,example.com,DIRECT
IP 매칭: IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
마지막 정책: FINAL,PROXY

규칙 행은 키-값 매개변수가 아니므로 순서와 마지막 정책을 각각 확인해야 합니다.

Rule: 먼저 매칭되는 규칙 적용, FINAL은 마지막에 배치

[Rule]에서 중요한 것은 규칙 개수가 아니라 배치 순서입니다. 일반적인 규칙 행은 유형, 매칭 대상, 정책으로 구성되며 FINAL에는 매칭 대상이 필요하지 않습니다. 앞쪽 규칙이 요청과 일치하면 같은 요청에 대해 뒤쪽 규칙으로 정책을 다시 선택하지 않습니다. 따라서 구체적인 예외 규칙을 포괄적인 조건보다 앞에 배치하세요.

[Rule]
DOMAIN-SUFFIX,example.com,DIRECT
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

키워드	예시 의미	확인할 점
`DOMAIN-SUFFIX`	example.com과 그 하위 도메인을 매칭해 DIRECT를 사용합니다.	도메인만 입력하세요. 프로토콜 헤더, 포트, 경로는 넣지 않습니다.
`IP-CIDR`	192.0.2.0/24 주소 범위를 매칭합니다.	`no-resolve`는 이 규칙과 일치할 때 추가 도메인 조회를 수행하지 않는다는 뜻입니다.
`GEOIP`	IP 지리 데이터베이스를 기준으로 CN에 해당하는지 판단합니다.	웹사이트의 표시 언어나 도메인 접미사를 확인하는 방식이 아닙니다.
`FINAL`	앞선 규칙에 일치하지 않으면 PROXY를 사용합니다.	마지막에 배치하고 프록시 연결이 정상적으로 작동하는지 확인하세요.

예시에 사용된 192.0.2.0/24는 문서용 주소 범위이며, 실제 서비스 주소가 아닙니다. DIRECT는 직접 연결을, PROXY는 프록시 연결을 뜻합니다. 사용자 지정 정책 이름을 사용하는 경우 현재 설정에 해당 이름이 실제로 정의되어 있어야 합니다. 철자가 비슷하다고 같은 정책인 것은 아니며, 프로토콜 이름을 이미 존재하는 정책처럼 사용해서도 안 됩니다.

판단 방법: 가장 먼저 일치하는 규칙 찾기

규칙을 추가해도 결과가 바뀌지 않으면 먼저 그 위에 더 포괄적인 규칙이 있는지 확인하세요. 곧바로 FINAL을 다른 정책으로 바꾸지는 마세요. 특정 도메인을 기준으로 비교해 어떤 규칙이 먼저 일치하는지 확인한 다음 순서를 조정하세요.

Host: 이름 해석 매핑을 바꾸며 요청 주소는 바꾸지 않음

[Host]는 특정 도메인의 로컬 이름 해석 매핑을 지정하며, 일반적인 형식은 도메인 = IP입니다. 이는 “이 이름을 어떤 주소로 해석할지”를 설정하는 항목이지 “트래픽을 어떤 경로로 보낼지”를 지정하는 항목이 아닙니다. 도메인을 고정 주소에 매핑해도 실제 요청은 현재 적용 중인 라우팅 설정에 따라 전송됩니다.

[Host]
lab.example.com = 192.0.2.10

키에는 도메인 입력: lab.example.com처럼 입력하세요. https://나 경로가 포함된 전체 URL은 입력하지 마세요.
값에는 주소 입력: 192.0.2.10은 문법 설명을 위한 예시입니다. 실제로는 사용 권한이 있고 접속할 수 있는 주소로 바꿔야 합니다.
포트는 변경되지 않음: 원래 요청이 HTTPS 기본 포트 443을 사용한다면 Host 매핑만으로 8443으로 바뀌지 않습니다.
인증서 이름은 변경되지 않음: HTTPS 연결은 여전히 원래 도메인에 해당하는 인증서를 확인합니다. 다른 서버로 매핑했다고 인증서 검증을 통과하는 것은 아닙니다.

문제를 확인할 때는 “도메인 해석이 잘못된 경우”와 “대상 주소에 연결할 수 없는 경우”를 구분하세요. 앱이 IP에 직접 접속하거나 자체적인 이름 해석 방식으로 주소를 얻는다면 Host 매핑 한 줄만으로 요청이 반드시 해당 매핑을 사용한다고 단정할 수 없습니다. 수정 후 요청을 다시 보내고, 필요하면 기존 연결을 종료한 뒤 테스트하세요. 기존 연결이 재사용된 결과를 새 설정의 결과로 오해하지 않도록 주의해야 합니다.

URL Rewrite: 정규식으로 요청 주소 매칭

[URL Rewrite]는 앱이 인식할 수 있는 HTTP 요청 주소를 처리합니다. 아래 예시는 정규식으로 특정 HTTP URL을 매칭하고 302 리디렉션을 반환합니다. 매칭 표현식, 대상 주소, 동작의 세 부분은 공백으로 구분합니다. Rule의 쉼표 형식과는 다릅니다.

[URL Rewrite]
^http://example\.com/guide$ https://example.com/guide 302

^는 문자열의 시작을 지정해 주소 중간에 있는 비슷한 문자열까지 매칭되는 것을 방지합니다.
example\.com의 백슬래시는 점을 문자 그대로 매칭하도록 합니다. 정규식에서 이스케이프하지 않은 점은 다른 문자와도 일치할 수 있습니다.
/guide$는 경로 끝을 지정합니다. 쿼리 매개변수가 붙은 /guide?from=test는 이 정규식 전체와 일치하지 않습니다.
302는 리디렉션 동작을 뜻합니다. 클라이언트가 리디렉션을 따르는지는 요청을 보낸 앱에서 확인해야 합니다.

이 예시를 “모든 HTTPS 주소를 바로 변경할 수 있다”는 뜻으로 이해하면 안 됩니다. 일반적인 암호화 터널은 연결에 필요한 정보만 노출하며, HTTPS의 전체 경로를 자동으로 제공하지 않습니다. HTTPS 콘텐츠를 매칭하려면 MITM, 대상 호스트 범위, 인증서 신뢰 및 앱 자체의 제한을 고려해야 합니다. 이 예시는 평문 HTTP 요청으로 시작하므로 복호화 범위를 넓힐 필요가 없습니다.

네 섹션 함께 사용하기: 한 번에 한 가지 변경만 검증

네 섹션을 모두 활성화해야 하는 것은 아닙니다. 도메인 라우팅만 필요하다면 우선 General과 Rule을 확인하세요. 고정 주소로 해석할 필요가 없다면 Host를 추가하지 않아도 되고, 주소를 바꿀 이유가 명확하지 않다면 URL Rewrite를 추가하지 않아도 됩니다. 출처가 불분명한 설정을 많이 넣는 것보다 필요한 설정만 사용하는 편이 문제를 파악하기 쉽습니다.

기준 상태 보존: Config에서 원래 설정을 유지하고, Home → Global Routing에서 현재 선택한 항목과 기존에 접속할 수 있었던 테스트 대상을 기록하세요.
먼저 규칙 수정: 구체적인 도메인 규칙 하나만 추가하고 저장한 뒤 수정한 설정을 선택하세요. Config 라우팅 모드에서 테스트합니다.
그다음 이름 해석 테스트: 고정 주소가 꼭 필요한 경우에만 Host를 추가하세요. 대상 도메인, 예상 IP, 포트를 기록하고 이름 해석 오류와 연결 실패를 구분합니다.
마지막으로 Rewrite 테스트: 명확한 HTTP 경로로 정규식을 검증하세요. 변수를 여러 개 섞지 않도록 HTTPS 복호화 설정은 동시에 추가하지 마세요.
테스트 기록 보관: 앱에서 확인할 수 있는 요청 기록을 참고해 도메인, 매칭된 규칙, 실제 적용된 정책을 확인하세요. 실패하면 방금 변경한 항목만 되돌린 뒤 같은 요청으로 다시 테스트합니다.

Settings → On Demand는 필요 시 연결 동작을 제어하며 규칙 문법을 고쳐 주지는 않습니다. 수동으로 연결을 끊은 뒤 자동으로 다시 연결된다면 이 메뉴의 트리거 설정을 확인하세요. 그렇다고 .conf 파일이 저장되지 않았다고 단정해서는 안 됩니다. 테스트 중에는 연결 방식을 일관되게 유지해야 같은 규칙의 변경 전후 결과를 비교할 수 있습니다.

자주 묻는 질문: 저장했는데 왜 예상대로 작동하지 않나요?

파일을 저장했는데 트래픽이 Rule에 따라 라우팅되지 않는 이유는 무엇인가요?

먼저 Config에서 방금 수정한 파일이 선택되어 있는지 확인한 다음, Home → Global Routing에서 Config가 선택되어 있는지 살펴보세요. 테스트 요청을 다시 보내고 대상이 앞쪽 규칙과 먼저 일치했는지도 확인합니다. 저장했다는 사실만으로 현재 라우팅에 해당 파일이 사용 중이라고 볼 수는 없습니다.

Host에 고정 IP를 입력했는데 HTTPS 오류가 계속 발생하는 이유는 무엇인가요?

먼저 해당 IP가 대상 도메인의 서비스를 제공하며 해당 포트에 연결할 수 있는지 확인하세요. Host는 이름 해석 매핑만 바꾸며 서버에 일치하는 인증서를 만들어 주거나 서버 측 가상 호스트 설정을 바꾸지 않습니다. 매핑을 제거한 뒤 다시 테스트하면 고정 주소가 오류의 원인인지 판단하는 데 도움이 됩니다.

매개변수가 포함된 URL에 URL Rewrite가 적용되지 않으면 어디를 수정해야 하나요?

실제 URL과 정규식을 먼저 구간별로 비교하세요. 이 글의 예시는 /guide$로 끝나므로 쿼리 매개변수가 있으면 일치하지 않습니다. 실제로 필요한 매개변수 범위를 명확히 정한 뒤 매칭 여부를 확인하세요. 경계 조건을 전부 없애 관련 없는 요청까지 변경하지 않도록 주의합니다.

기존 구독을 업데이트했는데 원래 규칙이 바뀌지 않는 이유는 무엇인가요?

연결 정보가 업데이트되는 대상과 Config에서 선택한 설정 파일을 각각 확인하세요. 연결 정보 업데이트가 로컬 Rule을 수정하는 것은 아닙니다. 원격 설정을 사용한다면 해당 설정 자체가 업데이트되었는지도 확인하세요. 중요한 변경은 복사본에 먼저 저장해 다음 업데이트에서 로컬 수정 사항이 덮어써지지 않도록 합니다.