Shadowrocket 설정 파일 사용법: .conf의 General·Rule·Host·URL Rewrite 섹션

Shadowrocket .conf 파일의 섹션 구조와 [General], [Rule], [Host], [URL Rewrite]의 역할, 규칙의 위에서 아래로 적용되는 순서를 정리합니다.

이 글의 핵심

이 글은 Shadowrocket 로컬 설정 파일을 확인하거나 수정하려는 사용자를 위한 안내입니다. 현재 활성화된 파일과 Global Routing을 먼저 확인한 뒤, 증상에 맞는 섹션을 살펴보세요. 연결 경로가 잘못되면 [Rule], 도메인이 잘못된 주소로 해석되면 [Host]와 [General], URL 경로에 따라 리디렉션해야 하면 [URL Rewrite]를 확인합니다.

.conf 섹션과 작성법

대괄호 안의 섹션 이름에 따라 다음 행을 해석하는 문법이 정해지며, 다음 섹션 이름이 나올 때까지 이어집니다. [General]과 [Host]에는 모두 등호가 쓰이지만, 등호 왼쪽의 의미는 다릅니다. 전자는 설정 항목이고 후자는 호스트 이름입니다. [Rule]은 보통 영문 쉼표로 유형, 매칭 값, 정책을 구분합니다. [URL Rewrite]의 리디렉션 항목은 공백으로 매칭 표현식, 대상 URL, 동작을 구분합니다.

4개 섹션
이 글에서 다루는 설정 섹션
3개 필드
DOMAIN 규칙 예시: 유형, 도메인, 정책
2개 필드
FINAL 규칙: 키워드, 정책

기존 파일에 규칙을 추가하려면 먼저 기존 [Rule] 섹션을 찾은 뒤 삽입 위치를 정하세요. 예시 전체를 파일 끝에 붙이지 마세요. 파일 끝에는 다른 섹션이 있을 수 있어 새 행이 규칙처럼 보여도 규칙을 읽는 위치에 들어가지 않을 수 있습니다.

Config에서 파일 편집 및 활성화

설정 목록에 파일이 표시된다고 해서 현재 연결에 사용 중인 파일이라는 뜻은 아닙니다. 아래 단계는 iPhone / iPad 인터페이스의 메뉴 이름을 기준으로 설명합니다. 처음 수정할 때는 한 줄만 변경하고, 수정 전 파일을 복사해 두세요. 같은 테스트 조건으로 되돌려 확인할 수 있습니다.

  1. 파일 확인

    Config를 열고 편집할 파일 이름을 확인한 다음, 수정 전 파일을 복사해 저장합니다. 원격 설정 파일이 업데이트될 수 있다면 테스트에는 로컬 복사본을 사용하세요. 새로고침 후 변경 사항이 덮어써지는 것을 방지할 수 있습니다.

  2. 원문 편집

    Config에서 파일 이름을 누르고 Edit Plain Text를 선택합니다. 해당 섹션을 찾아 설정 한 줄만 추가하거나 수정하고, 기존 영문 문장 부호와 구분 기호를 그대로 유지한 뒤 저장합니다.

  3. 설정 활성화

    Config로 돌아가 수정한 파일 이름을 누른 다음 Use Config를 선택합니다. 되돌리기용 복사본이 아니라 수정한 파일이 활성화됐는지 확인하세요.

  4. 요청 다시 보내기

    Home → Global Routing → Config로 이동합니다. 같은 대상을 지정해 새 연결을 만드세요. 앱이 기존 연결을 재사용한다면 먼저 기존 연결을 종료한 다음 테스트합니다.

Config는 설정 화면의 이름이면서 Global Routing에서 선택하는 모드 중 하나이기도 합니다. 앞의 화면에서는 파일을 선택하고, 뒤의 모드에서는 해당 파일의 규칙에 따라 트래픽을 분기할지 정합니다. [Rule] 문제를 확인할 때는 두 곳을 모두 살펴보세요.

Config

권장

선택한 설정 파일의 규칙에 따라 연결 정책을 정합니다. 예외 규칙, 접미사 규칙, FINAL의 순서가 결과에 영향을 줍니다.

적합한 경우: 활성화된 설정의 규칙이 적용되는지 확인할 때

Direct

직접 연결 모드를 사용합니다. 직접 연결에 성공해도 현재 네트워크에서 대상에 직접 연결할 수 있다는 뜻일 뿐, 설정 파일의 특정 DIRECT 규칙이 적용됐다는 의미는 아닙니다.

적합한 경우: 같은 대상을 사용해 직접 연결이 가능한지 따로 확인할 때

Proxy

클라이언트가 처리하는 연결에 프록시 모드를 적용합니다. 테스트 전에 Home에서 사용할 서비스를 선택했는지 확인하고, 같은 대상을 지정해 새 연결을 만드세요.

적합한 경우: 트래픽 분기 규칙과 별개로 프록시 경로를 확인할 때

[General]과 [Host]: DNS 설정과 단일 도메인 매핑

[General]에는 설정 파일 전체에 적용되는 옵션을 지정합니다. 예를 들어 dns-server = system은 시스템 DNS를 사용하도록 설정합니다. [Host]에서는 특정 호스트 이름에 주소를 지정할 수 있습니다. 전자는 기본 DNS 설정을, 후자는 Shadowrocket이 이름을 해석할 때 별도 매핑을 적용할지 결정합니다. 어느 쪽도 연결 정책을 선택하는 [Rule]을 대신하지 않습니다.

[General]
dns-server = system

[Host]
docs.example.com = 192.0.2.10

192.0.2.10은 문서용 예시 주소이며 연결 테스트에 사용하지 않습니다. 위 매핑에는 docs.example.com만 있고 api.example.com은 없습니다. 매핑을 확인할 때는 원래 호스트 이름으로 요청하세요. 브라우저 주소를 IP로 바꾸면 요청에 사용되는 호스트 이름이 달라지고 HTTPS 인증서 검증 조건도 달라질 수 있습니다.

문제 범위에 따라 확인할 항목 선택

여러 도메인에서 이름 해석 오류
  • [General]의 dns-server를 확인하고, 문제가 특정 네트워크에서만 발생하는지 기록하세요.
  • 같은 설정으로 두 네트워크에서 각각 새 요청을 보내고, 현상이 시스템 DNS가 사용하는 네트워크에 따라 달라지는지 확인합니다.
호스트 이름 하나에서만 오류 발생
  • [Host]에 해당 호스트 이름 전체가 입력되어 있는지 확인하세요. 특히 www 및 다른 서브도메인도 살펴봅니다.
  • 복사본에서 해당 매핑을 삭제한 뒤 같은 이름으로 다시 요청해 기존 연결이나 캐시의 영향을 배제하세요.

먼저 이름 해석이 잘못된 것인지, 주소는 맞지만 연결에 실패하는 것인지 구분하세요. 두 경우에 확인할 항목은 다릅니다.

[Rule]: 위에서 아래로 확인하고 첫 번째로 일치한 규칙 적용

규칙은 더 구체적인 항목을 자동으로 앞에 배치하지 않습니다. 특정 호스트 이름을 접미사 규칙의 예외로 두려면 해당 호스트 이름의 DOMAIN을 먼저 작성하고, 적용 범위가 더 넓은 DOMAIN-SUFFIX를 뒤에 둡니다. 앞선 규칙과 일치하지 않는 연결은 마지막의 FINAL로 처리합니다.

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

앞의 두 규칙 순서를 바꾸면 docs.example.com이 먼저 DOMAIN-SUFFIX와 일치해 뒤에 있는 정확한 호스트 규칙은 적용되지 않습니다. 예시의 FINAL,DIRECT는 이 설정 파일의 기본 처리 방식일 뿐입니다. 기존 파일을 수정할 때는 원래의 기본 정책부터 확인하세요. 예외 규칙 하나를 추가하면서 다른 연결의 처리 방식까지 바꾸지 않도록 주의합니다.

IP-CIDR은 대상 IP가 속한 네트워크 대역으로 매칭합니다. 예: IP-CIDR,192.0.2.0/24,DIRECT. GEOIP은 IP의 지리적 위치 정보로 매칭하며 도메인 접미사로 판단하지 않습니다. 도메인 요청 문제를 확인할 때는 먼저 앞쪽 도메인 규칙이 적용되는지 살펴보고, 이어서 IP 규칙에 매칭에 필요한 대상 주소가 전달됐는지 확인하세요.

[URL Rewrite]: URL 경로에 따른 리디렉션

[Rule]은 연결 경로를 결정하고, [URL Rewrite]는 클라이언트가 처리할 수 있는 HTTP 요청 URL을 매칭합니다. 아래 예시는 프로토콜, 호스트 이름, 경로를 모두 지정하고 302로 새 주소에 연결합니다. 문법을 보여주는 예시이며, 예시 도메인에서 실제 페이지를 제공하지는 않습니다.

[URL Rewrite]
^http://docs\.example\.com/old$ http://docs.example.com/new 302

HTTPS 요청의 경로는 암호화된 콘텐츠에 포함되므로 호스트 이름만으로 경로를 매칭할 수 없습니다. 테스트 도구가 요청을 보내기 전에 HTTP를 HTTPS로 업그레이드하면 위 표현식은 그대로 일치하지 않습니다. 먼저 실제로 전송된 프로토콜과 URL을 확인한 뒤 표현식을 수정할지 결정하세요.

저장 후 적용되지 않는 흔한 원인

DIRECT를 설정했는데 왜 프록시로 연결되나요?

먼저 Home → Global Routing이 Config로 설정되어 있는지 확인한 다음, 현재 활성화된 파일의 [Rule]을 살펴보세요. 위쪽에 해당 호스트 이름을 포함하는 DOMAIN-SUFFIX가 있다면 정확히 일치하는 예외 DOMAIN을 그 앞에 옮긴 뒤 새 연결을 만들어 확인합니다.

새 규칙을 FINAL 아래에 바로 붙여도 되나요?

일반 규칙을 기본 처리 규칙 아래에 두지 마세요. FINAL이 있다면 새 규칙을 그 앞에 삽입한 다음, 위쪽에 해당 대상을 포함하는 규칙이 있는지 확인합니다. 저장한 후에는 규칙과 일치해야 하는 대상과 기본 처리 규칙으로 넘어가야 하는 대상을 각각 테스트하세요.

Host에서 주소를 바꿨는데 브라우저 주소창은 왜 그대로인가요?

[Host]는 호스트 이름에 연결되는 주소를 바꿉니다. 주소창에 기존 URL이 계속 표시되는 것은 정상입니다. 매핑을 확인하려면 직접 관리하는 대상 서비스를 사용해 새 연결이 예상한 주소에 도달하는지 확인하세요. /old를 /new로 바꾸려는 경우에는 호스트 매핑이 아니라 리디렉션을 확인해야 합니다.

원래 파일로 되돌린 뒤 어떤 변경으로 문제가 생겼는지 어떻게 찾나요?

같은 네트워크에서 원본 파일과 수정한 복사본으로 동일한 요청을 보내고, Global Routing과 선택한 서비스는 그대로 유지합니다. 복사본에서만 문제가 발생하면 가장 최근에 수정한 섹션부터 한 줄씩 원래대로 되돌리고, 매번 한 곳만 바꾼 뒤 다시 테스트하세요. 문제가 재현되지 않게 되는 항목을 찾을 때까지 반복합니다.

Shadowrocket 전 플랫폼 다운로드