마이그레이션 예상 읽기 시간 14분

Clash rule-providers 설정: GitHub 규칙집 제작·자동 갱신 가이드

GitHub, npm, Docker Hub용 Clash 사용자 규칙을 rule-providers로 관리하는 방법을 알아보세요. YAML 형식과 규칙 우선순위부터 GitHub 호스팅, 자동 갱신, 검증 절차까지 실전 예제로 설명하고 Mihomo에서 자주 발생하는 호환성 문제도 다룹니다.

rule-providers가 필요한 상황과 기본 구조

도메인 규칙이 몇 개뿐이라면 설정의 rules에 직접 적어도 관리하기 어렵지 않습니다. 하지만 차단 목록, 업무용 도메인, 스트리밍 서비스처럼 목적별 규칙이 늘어나면 설정 파일이 길어지고, 작은 수정에도 전체 설정을 다시 배포해야 합니다. mihomo의 rule-providers는 규칙 목록을 별도 파일로 분리하고, 로컬에 저장하거나 원격 주소에서 주기적으로 가져오도록 구성하는 기능입니다. 구독의 프록시 노드 목록을 불러오는 proxy-providers와는 역할이 다릅니다. rule-providers는 트래픽을 어느 정책으로 보낼지 결정하는 규칙 모음을 제공합니다.

작동 흐름은 세 부분으로 나뉩니다. rule-providers에서 제공자 이름과 파일의 위치, 형식, 갱신 간격을 정의하고, rules에서 RULE-SET으로 해당 제공자를 호출합니다. 마지막으로 규칙에 지정된 정책 그룹이 실제 트래픽을 처리합니다. 따라서 파일을 성공적으로 내려받았더라도 rules에서 참조하지 않거나 정책 그룹 이름이 일치하지 않으면 기대한 분기가 이루어지지 않습니다.

rule-providers:
  work-sites:
    type: http
    behavior: domain
    format: yaml
    url: "https://규칙파일의-원격주소/work-sites.yaml"
    path: ./ruleset/work-sites.yaml
    interval: 86400

rules:
  - RULE-SET,work-sites,업무용
  - MATCH,기본

이 예제에서 type: http는 원격 HTTP 또는 HTTPS 주소에서 파일을 가져온다는 뜻이며, path는 내려받은 파일을 클라이언트의 데이터 디렉터리에 저장할 위치입니다. interval은 초 단위이므로 86400은 하루입니다. 규칙 파일을 제공하는 서버가 변경되지 않은 파일에 안정적인 응답을 반환해야 하고, 클라이언트가 해당 URL에 접근할 수 있어야 합니다. 정책 그룹인 업무용은 설정의 proxy-groups에 실제로 존재하는 이름으로 바꾸세요.

규칙 형식과 파일 구조를 정하기

규칙 제공자의 behavior는 파일 안의 각 항목을 어떤 규칙으로 해석할지 정합니다. 도메인만 간단히 관리한다면 domain, 도메인·IP·키워드 등 여러 종류의 규칙을 한 파일에 넣고 싶다면 classical을 선택할 수 있습니다. IP 범위가 중심인 목록에는 ipcidr이 적합합니다. 제공자 설정의 behavior와 실제 파일의 문법이 서로 맞지 않으면 다운로드에 성공해도 규칙을 읽지 못하거나 일부 항목이 적용되지 않을 수 있습니다.

도메인 전용 목록

behavior: domain은 도메인 목록을 별도 파일로 관리할 때 사용합니다. YAML 형식으로 배포한다면 최상위에 payload를 두고 그 아래에 도메인 항목을 나열합니다. 예를 들어 정확한 호스트만 대상으로 삼을지, 해당 도메인의 하위 도메인도 포함할지 규칙의 의도를 먼저 정해야 합니다. 하위 도메인 포함 여부를 분명히 하려면 mihomo가 인식하는 도메인 항목 문법을 확인하고, 테스트용 도메인으로 실제 매칭을 검증하세요.

payload:
  - "example.com"
  - "+.service.example"
  - "+.video.example"

도메인 목록은 관리하기 쉽지만 IP 대역이나 키워드 규칙을 같은 파일에 섞기에는 적합하지 않습니다. 또한 도메인 이름을 잘못 입력하거나 불필요한 와일드카드 형태를 사용하면 의도보다 넓은 트래픽이 분기될 수 있습니다. 실제 운영 목록을 만들기 전에 대표 도메인, 하위 도메인, 목록에 포함되지 않은 도메인을 각각 확인하는 편이 좋습니다.

여러 규칙 유형을 함께 관리하기

behavior: classical은 일반적인 Clash 규칙 항목을 파일에 모아 두는 방식입니다. 이 형식에서는 규칙 유형과 매개변수를 항목별로 작성할 수 있어 도메인뿐 아니라 IP 범위나 키워드도 함께 관리할 수 있습니다. 예를 들어 다음 파일은 특정 도메인과 IP 대역을 하나의 제공자에 포함합니다.

payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,login.example.net
  - IP-CIDR,198.51.100.0/24,no-resolve

no-resolve는 IP 규칙을 검사하기 위해 도메인 이름을 추가로 DNS 조회하지 않도록 하는 옵션입니다. 모든 IP 규칙에 무조건 붙이는 항목은 아니므로, 이름 기반 주소를 해석해야 하는 규칙인지에 따라 선택하세요. 규칙을 파일로 분리해도 우선순위가 사라지는 것은 아닙니다. 최종 설정의 rules는 위에서부터 순서대로 평가되므로, 넓은 조건이나 MATCH를 규칙 세트보다 앞에 배치하면 뒤에 있는 제공자 규칙까지 도달하지 못할 수 있습니다.

GitHub 저장소에서 규칙 파일 배포하기

GitHub를 규칙 파일의 공개 배포처로 사용하려면 먼저 규칙 파일만 담는 저장소를 만들고, 목적별 파일을 나누어 관리하는 것이 좋습니다. 예를 들어 rules/work-sites.yaml, rules/streaming.yaml, rules/blocklist.yaml처럼 이름을 정하면 파일이 늘어나도 용도를 파악하기 쉽습니다. 저장소의 기본 브랜치와 폴더 구조를 확정한 다음 YAML 파일을 추가하고 커밋하세요. mihomo의 url에는 GitHub 저장소의 파일 보기 화면 주소가 아니라 파일 내용을 직접 반환하는 원시 파일 주소를 넣어야 합니다. 주소는 저장소 소유자, 저장소 이름, 브랜치, 파일 경로에 맞춰 작성하며 브랜치나 파일명을 바꾸면 설정의 주소도 함께 갱신해야 합니다.

공개 저장소라면 클라이언트에서 인증 정보 없이 원격 파일을 가져올 수 있습니다. 비공개 저장소는 일반적인 공개 원시 파일 주소만으로 접근할 수 없으며, 토큰을 설정 YAML에 넣으면 설정 공유나 로그 노출 시 저장소 접근 권한까지 유출될 수 있습니다. 비공개 규칙이 필요하다면 인증을 안전하게 처리할 수 있는 별도 배포 방법을 검토하세요. 규칙 파일은 대체로 민감한 정보가 아니므로, 특별한 이유가 없다면 공개 저장소와 토큰 없는 읽기 주소를 사용하는 편이 단순합니다.

파일을 게시한 뒤에는 클라이언트에서 곧바로 자동 갱신만 기다리지 말고 원격 원시 파일 주소에 접근해 실제 응답을 점검하세요. 브라우저에서 열었을 때 GitHub의 HTML 페이지가 아니라 YAML 텍스트가 보여야 합니다. 명령줄을 사용할 수 있다면 응답 코드와 저장된 내용을 별도로 확인할 수 있습니다. 주소를 테스트할 때 비공개 토큰이나 계정 인증 정보가 포함되어 있다면 명령 기록과 출력 내용을 외부에 공유하지 마세요.

  1. 저장소에 규칙 파일을 추가하고 기본 브랜치에 커밋합니다.
  2. 웹 화면의 파일 보기 주소가 아닌 원시 파일 주소를 확인합니다.
  3. 주소를 YAML의 url에 넣고, path에는 로컬 캐시 파일 위치를 지정합니다.
  4. 클라이언트에서 설정을 다시 불러오거나 규칙 제공자를 수동 갱신합니다.
  5. 코어 로그와 규칙 제공자 상태에서 가져오기 결과를 확인합니다.

갱신, 적용 및 오류 검증

interval은 규칙 제공자를 다시 확인하는 주기를 초 단위로 지정합니다. 하루에 한 번 갱신하면 86400, 6시간 간격이면 21600입니다. 파일을 자주 바꾸지 않는 개인 규칙이라면 너무 짧은 간격을 설정할 이유가 적습니다. 짧은 주기는 원격 서버의 요청 수를 늘리고, 네트워크 오류가 반복될 때 로그를 복잡하게 만들 수 있습니다. 반대로 보안 차단 목록처럼 변경이 잦은 규칙은 업데이트 필요성과 서버의 요청 제한을 함께 고려해 간격을 정하세요.

갱신을 확인할 때는 세 가지 결과를 구분해야 합니다. 원격 파일에 접근할 수 있는지, 코어가 파일 형식을 파싱했는지, 규칙이 실제 트래픽을 원하는 정책으로 보냈는지입니다. 다운로드 오류가 없다는 사실만으로 마지막 단계까지 성공했다고 볼 수는 없습니다. 클라이언트가 제공자 상태를 표시한다면 마지막 업데이트 시각과 오류 메시지를 확인하고, 연결 로그나 규칙 매칭 정보를 통해 테스트 도메인이 RULE-SET에 의해 선택되었는지도 확인하세요.

규칙을 수정할 때는 큰 목록을 한 번에 교체하기보다 작은 변경 단위로 커밋하는 방식이 문제를 찾기 쉽습니다. 잘못된 항목이 배포되면 이전 커밋으로 되돌리고 클라이언트에서 제공자를 다시 갱신할 수 있습니다. 목록에 중복 규칙이 있다고 반드시 오류가 발생하는 것은 아니지만, 중복을 줄이면 검토가 쉬워지고 불필요한 규칙 충돌 가능성도 낮아집니다. 특히 MATCH 같은 최종 포괄 규칙은 제공자 호출보다 뒤에 두고, 중요한 도메인과 IP 대역을 각각 테스트한 다음 다른 네트워크에서도 동작을 확인하세요.

마지막으로 원격 규칙은 로컬 설정과 별도로 장애 지점을 하나 더 추가합니다. GitHub 접근이 차단되거나 인터넷 연결이 끊기면 새 규칙을 가져오지 못할 수 있으므로, 로컬 캐시가 남아 있는 동안 기존 규칙이 어떻게 동작하는지 실제 코어와 클라이언트에서 확인해 두는 것이 좋습니다. 운영에 중요한 규칙이라면 변경 전 백업 파일을 보관하고, 업데이트가 실패했을 때 적용되는 동작을 로그에서 확인하세요. 이렇게 원본 파일, 원격 배포, mihomo 파싱, 최종 정책 매칭을 단계별로 점검하면 규칙 목록을 안정적으로 관리할 수 있습니다.

FlClash 다운로드 플랫폼별 클라이언트 보기