rule-providers로 룰셋을 분리하는 이유

rule-providers는 여러 도메인 규칙을 메인 프로필 밖의 파일로 분리해 불러오는 기능입니다. 예를 들어 업무용 SaaS, 개발 도구, 스트리밍 서비스의 라우팅 규칙을 각각 별도 파일로 관리하면, 프로필 전체를 다시 편집하지 않고도 해당 룰셋만 수정하고 갱신할 수 있습니다. 여러 기기에서 같은 규칙을 쓰거나, GitHub에서 변경 이력을 검토하고 싶은 경우에도 유용합니다.

다만 Clash라는 이름을 사용하는 모든 클라이언트와 코어가 같은 문법을 지원하는 것은 아닙니다. 특히 type: http, format: yaml, behavior: domain의 지원 여부와 허용되는 값은 코어 버전에 따라 달라질 수 있습니다. Clash Verge Rev나 Mihomo 기반 앱에서는 설정 검증 결과와 코어 버전을 먼저 확인하세요. 설정이 저장되더라도 코어가 해당 필드를 이해하지 못하면 프로바이더를 불러오지 못하거나, 프로필 자체가 시작되지 않을 수 있습니다.

처음에는 프로필을 복사해 테스트용으로 보관하고, 규칙 하나만 작은 외부 파일로 옮기는 것이 안전합니다. 구독 제공자가 내려주는 프로필을 직접 수정하면 다음 업데이트에서 변경 사항이 덮어써질 수 있으므로, 수정 권한이 있는 로컬 프로필이나 별도 오버라이드 방식을 사용하는지도 확인해야 합니다. 프로바이더는 룰을 재사용하기 쉽게 만드는 도구이지, 기존 프로필의 규칙 우선순위를 자동으로 개선해 주는 기능은 아닙니다.

도메인 룰셋 형식과 규칙 작성

룰셋의 behavior는 파일 안에 어떤 종류의 규칙을 넣을지 정합니다. 서비스 도메인만 관리한다면 domain 형식이 간단하고, DOMAIN이나 DOMAIN-SUFFIX 같은 완성된 규칙을 보관하려면 코어가 지원하는 경우 classical 형식을 검토할 수 있습니다. IP 대역을 다루는 ipcidr는 도메인 목록과 목적이 다르므로 한 파일에 섞지 않는 편이 관리하기 쉽습니다.

아래 예시는 Mihomo 계열 코어에서 사용하는 YAML 형식의 도메인 프로바이더 구조를 보여 줍니다. 실제로 적용하기 전에 사용 중인 코어의 문서에서 format 지원과 payload 문법을 확인하세요. 예시 도메인은 설명용이므로 자신의 서비스에 맞는 실제 호스트로 바꿔야 합니다.

payload:
  - '+.example.dev'
  - '+.api.example.dev'
  - 'login.example.net'

+.example.dev처럼 하위 도메인까지 포함하는 표기와 호스트 하나만 지정하는 표기는 범위가 다릅니다. 넓은 도메인 접미 규칙을 추가하면 같은 서비스의 정적 파일이나 인증 호스트도 함께 매칭될 수 있습니다. 반대로 루트 도메인만 넣었을 때 하위 호스트가 포함되는지는 코어의 패턴 해석과 항목 유형을 확인해야 합니다. 처음에는 연결 로그에서 실제로 관찰한 도메인만 넣고, 필요한 범위가 확인된 뒤에 접미 규칙으로 확장하는 편이 예측하기 쉽습니다.

주석에는 룰의 목적과 확인 날짜를 적어 두면 시간이 지난 뒤에도 항목을 정리하기 좋습니다. 단, 제공자 파일이 주석이나 특정 YAML 문법을 허용하는지는 사용 중인 코어에 따라 다르므로, 최소한의 문법으로 시작하고 파싱 결과를 확인하세요. 사용하지 않는 도메인을 계속 쌓아 두면 어떤 항목이 매칭됐는지 찾기 어려워집니다.

GitHub에 파일을 올리고 프로필에서 불러오기

먼저 GitHub 저장소에 룰셋 전용 파일을 만들고, 위와 같은 payload 구조로 저장합니다. 공개 저장소라면 파일 화면의 일반 페이지 주소가 아니라 원본 파일을 반환하는 Raw URL을 사용해야 합니다. 보통 주소는 raw.githubusercontent.com으로 시작하며, 브랜치 이름과 저장소 경로가 정확해야 합니다. 저장소를 비공개로 두면 인증이 필요할 수 있으므로, 토큰을 프로필 YAML이나 공개 이슈·스크린샷에 평문으로 넣지 마세요.

메인 프로필에는 다음처럼 프로바이더를 선언할 수 있습니다. url은 GitHub의 실제 Raw 주소로 교체하고, path는 코어가 파일을 보관할 로컬 경로로 지정합니다. 경로가 다른 프로바이더와 겹치지 않도록 고유한 파일명을 쓰고, 디렉터리 표기와 쓰기 권한도 확인하세요.

rule-providers:
  custom-services:
    type: http
    behavior: domain
    format: yaml
    url: "https://raw.githubusercontent.com/OWNER/REPO/main/rules/services.yaml"
    path: ./rule-providers/custom-services.yaml
    interval: 86400

rules:
  - RULE-SET,custom-services,PROXY
  - MATCH,DIRECT

OWNER와 REPO는 저장소 소유자와 이름으로 바꿔야 합니다. interval: 86400은 일반적으로 초 단위로 갱신 주기를 지정하는 예시이며, 코어가 지원하는 최소값이나 갱신 동작은 버전에 따라 확인해야 합니다. 너무 짧게 설정하면 불필요한 요청이 늘고, 너무 길면 GitHub에서 수정한 룰이 클라이언트에 반영되는 데 시간이 걸립니다. 급히 변경을 확인할 때는 클라이언트의 프로바이더 업데이트 기능을 사용하고, 다운로드 시각과 갱신 결과를 기록해 자동 갱신과 수동 갱신을 구분하세요.

규칙 순서도 중요합니다. RULE-SET은 해당 룰셋이 매칭되면 지정한 정책 그룹으로 보내고, 이후 규칙은 더 이상 평가되지 않습니다. 따라서 넓은 MATCH나 일반적인 도메인 규칙보다 구체적인 룰셋을 앞에 두어야 합니다. 이미 앞쪽 규칙이 같은 도메인을 DIRECT로 처리한다면, 뒤에 추가한 프로바이더 규칙은 도달하지 못합니다. 기존 규칙의 의미를 확인하지 않은 채 파일 끝에 한 줄만 덧붙이는 방식은 피하세요.

서비스별 라우팅과 GitHub 변경 관리

서비스별 룰셋은 하나의 큰 파일로 시작해도 되지만, 규모가 커지면 목적에 따라 나누는 것이 좋습니다. 예를 들어 개발 관련 호스트는 개발 도구용 프록시 그룹으로, 로컬 서비스는 DIRECT로, 지역에 따라 접근 경로를 달리해야 하는 항목은 별도 그룹으로 분리할 수 있습니다. 다만 그룹 이름은 메인 프로필의 proxy-groups에 실제로 존재해야 합니다. 존재하지 않는 그룹을 참조하면 설정 검증 오류가 나거나 해당 규칙을 사용할 수 없습니다.

관리 대상 룰셋 구성 예 확인할 점
개발 서비스 도메인 항목을 별도 룰셋으로 관리 API 호스트와 로그인 호스트가 모두 필요한지 로그로 확인
내부·로컬 서비스 접미 규칙과 직접 연결 정책을 분리 넓은 도메인 패턴이 외부 트래픽까지 포함하지 않는지 점검
테스트 대상 임시 브랜치나 별도 파일로 변경 검증 검증 후 기본 브랜치에 병합하고 클라이언트에서 갱신

GitHub에서는 작은 단위로 커밋하고 변경 이유를 남기세요. 예를 들어 “로그인 호스트 추가”처럼 변경 목적을 설명하면, 연결 문제가 생겼을 때 마지막 수정과 관련성을 빠르게 살펴볼 수 있습니다. 먼저 테스트 브랜치에서 도메인을 추가한 뒤 YAML 문법과 Clash 설정 검증을 진행하고, 실제 요청이 의도한 그룹으로 향하는지 확인한 후 기본 브랜치에 반영하는 흐름이 안전합니다. 여러 사람이 저장소를 관리한다면 수정 전에 기존 목록을 확인하고, 같은 도메인을 중복 추가하거나 서로 다른 정책으로 정의하지 않도록 검토 절차를 둡니다.

GitHub에 올린 파일은 누구나 가져갈 수 있는 공유 설정이 될 수 있습니다. 구독 URL, 인증 토큰, 개인 IP, 내부 호스트명, 계정 식별 정보는 룰셋에 넣지 마세요. 비공개 저장소를 선택하더라도 클라이언트가 인증 헤더를 안전하게 지원하는지 확인해야 합니다. 지원 여부가 불확실하다면 민감한 데이터를 포함하지 않는 공개 룰셋과 로컬 비공개 설정을 분리하는 편이 낫습니다.

갱신 실패와 룰 미매칭을 로그로 확인하기

프로바이더가 동작하지 않을 때는 오류를 세 단계로 나눠 확인하세요. 첫째, 파일을 내려받지 못한 경우입니다. Raw URL 오타, 저장소 공개 범위, 네트워크 연결, DNS 또는 GitHub 접근 실패를 점검합니다. 둘째, 다운로드는 됐지만 파싱에 실패한 경우입니다. YAML 들여쓰기와 따옴표, behavior와 파일 형식의 조합, 코어 버전의 기능 지원을 확인하세요. 셋째, 프로바이더는 정상인데 트래픽이 예상한 경로로 가지 않는 경우입니다. 이때는 규칙 순서, 그룹 이름, 실제 요청의 호스트가 룰셋 항목과 일치하는지 봐야 합니다.

Clash Verge Rev 등 클라이언트에서 코어 로그와 연결 로그를 같은 시각에 열어 두면 원인 범위를 좁히기 쉽습니다. 실패한 앱에서 요청을 한 번 재현하고, 로그에 표시된 도메인과 최종 매칭 규칙, 선택된 정책 그룹을 확인하세요. 도메인이 전혀 보이지 않는다면 앱이 다른 네트워크 경로를 사용하거나 IP 주소로 직접 접속했을 수 있습니다. 룰셋 항목이 있는데도 다른 규칙이 선택된다면, 그 항목보다 앞에 있는 규칙이 먼저 매칭됐는지 확인해야 합니다.

규칙을 바꾼 뒤에는 프로필을 다시 불러오거나 코어를 재시작하고, 프로바이더의 마지막 업데이트 시각도 확인하세요. 저장소 파일은 수정됐지만 클라이언트의 로컬 캐시가 남아 있으면 이전 목록이 계속 사용될 수 있습니다. 반대로 업데이트를 여러 번 반복해도 다운로드 오류가 해결되지 않는다면, 같은 파일을 브라우저에서 열어 실제 응답이 YAML인지 확인하세요. 로그인 페이지나 오류 안내 HTML을 YAML로 해석하려다 파싱 실패가 나는 경우도 있습니다.

마지막으로 룰셋을 주기적으로 정리하세요. 서비스에서 폐기한 호스트, 더 이상 필요하지 않은 임시 규칙, 지나치게 넓은 접미 규칙은 검토 대상입니다. 변경 전후에 대표 도메인의 연결 로그를 비교하면 라우팅이 의도와 달라졌는지 확인할 수 있습니다. GUI에서 규칙을 하나씩 수동 편집하는 방식은 당장 간단해 보이지만, 여러 기기에서 변경 이력을 맞추기 어렵습니다. 반면 GitHub 기반 룰셋은 리뷰와 롤백이 가능하고, Clash의 규칙 로그로 실제 매칭 결과를 검증할 수 있어 재사용과 추적에 유리합니다. 이 흐름을 새로 구성하거나 기존 클라이언트를 설치해야 한다면 지원 플랫폼을 확인한 뒤 다운로드 안내를 참고하세요.

다운로드 →