Clash rule-providers 고급 설정과 GitHub 자동화 가이드

Clash 규칙을 기능별 YAML 파일로 나누고 GitHub Actions로 검증 및 자동 갱신하는 실전 방법을 소개합니다. 캐시 정책, 우선순위 설계, 업데이트 오류 분석까지 다룹니다.

Clash 또는 Mihomo 설정이 커질수록 모든 규칙을 하나의 rules 배열에 직접 작성하는 방식은 관리하기 어려워집니다. 광고 차단, 업무용 도메인, 국내 서비스, 해외 서비스, 개인 예외 규칙이 한 파일에 섞이면 변경 범위를 파악하기 어렵고, 작은 오타 하나가 전체 설정 로드 실패로 이어질 수 있습니다. rule-providers는 이런 규칙 집합을 별도의 파일로 분리하고 필요한 시점에 내려받아 캐시하는 기능입니다.

여기에 GitHub Actions를 연결하면 규칙 파일의 YAML 문법을 자동으로 검사하고, 예약된 시간에 원격 소스를 갱신하며, 변경 내역을 기록할 수 있습니다. 다만 자동화의 목표는 무조건 최신 파일을 가져오는 것이 아닙니다. 규칙의 형식, 코어가 지원하는 필드, 업데이트 실패 시 사용할 캐시, 기존 규칙과의 우선순위를 함께 설계해야 안정적인 구성이 됩니다.

rule-providers의 구조와 각 필드 이해하기

rule-providers는 이름이 지정된 규칙 공급자 목록입니다. 각 공급자는 원격 주소, 파일 형식, 규칙의 의미와 저장 경로를 정의합니다. rules 섹션에서는 긴 규칙을 다시 작성하는 대신 RULE-SET으로 해당 공급자를 참조합니다. 공급자 이름은 YAML의 키이면서 규칙에서 사용하는 식별자이므로 공백이나 특수문자를 피하고 짧고 일관된 이름을 쓰는 편이 좋습니다.

rule-providers:
  ads:
    type: http
    behavior: domain
    format: yaml
    url: https://rules.example.invalid/ads.yaml
    path: ./rules/ads.yaml
    interval: 86400

  work:
    type: http
    behavior: classical
    format: yaml
    url: https://rules.example.invalid/work.yaml
    path: ./rules/work.yaml
    interval: 43200

rules:
  - RULE-SET,ads,REJECT
  - RULE-SET,work,Work-Proxy
  - MATCH,Final

type: http는 HTTP 또는 HTTPS 주소에서 규칙 파일을 가져온다는 뜻입니다. path는 내려받은 파일을 저장할 로컬 경로이며, 클라이언트와 코어가 해당 디렉터리에 쓰기 권한을 가져야 합니다. 상대 경로를 사용할 때는 실행 환경의 작업 디렉터리가 클라이언트마다 다를 수 있으므로, 실제 로그에 표시되는 저장 위치를 확인해야 합니다.

interval은 자동 갱신 간격을 초 단위로 지정합니다. 하루마다 갱신하려면 86400, 12시간마다 갱신하려면 43200을 사용할 수 있습니다. 이 값이 작다고 항상 좋은 것은 아닙니다. 규칙 공급자 서버에 불필요한 요청이 반복되고, 변경되지 않은 파일을 계속 내려받게 됩니다. 광고 목록처럼 자주 바뀌는 데이터와 거의 변하지 않는 사내 도메인 목록에 서로 다른 간격을 적용하세요.

behavior와 format을 혼동하지 않기

behavior는 규칙을 어떤 의미로 해석할지 결정합니다. domain은 도메인 목록을 위한 유형이고, ipcidr은 IP 대역 목록에 적합하며, classical은 DOMAIN-SUFFIX, IP-CIDR, PROCESS-NAME 같은 완전한 Clash 규칙을 담을 때 사용합니다. 반면 format은 파일이 YAML인지 일반 텍스트인지 나타냅니다. YAML 파일이라고 해서 모두 같은 behavior를 사용할 수 있는 것은 아닙니다.

payload:
  - DOMAIN-SUFFIX,example.com
  - DOMAIN,api.example.net

위와 같은 파일은 완전한 규칙 표현을 포함하므로 일반적으로 classical 유형으로 설계하는 편이 알기 쉽습니다. 도메인 공급자는 코어가 기대하는 구조에 맞춰 도메인 목록을 구성해야 합니다. 공급자 파일의 루트 키, 확장자와 behavior가 서로 맞지 않으면 공급자 다운로드 자체는 성공해도 규칙이 매칭되지 않을 수 있습니다.

기능별 분리와 규칙 우선순위 설계

규칙을 파일별로 나누는 기준은 파일 크기보다 변경 주기와 정책 목적이어야 합니다. 광고 차단 목록, 업무용 도메인, 직접 연결할 국내 서비스, 프록시가 필요한 해외 서비스, 사용자가 직접 관리하는 예외 목록을 분리하면 변경 원인을 추적하기 쉬워집니다. 반대로 서로 다른 정책을 하나의 대형 공급자에 합치면 공급자 하나의 오류가 여러 서비스의 라우팅에 동시에 영향을 줍니다.

공급자 예시 권장 behavior 적용 정책 관리 기준
ads domain 또는 classical REJECT 차단 오탐 여부를 자주 검토
direct domain DIRECT 국내 서비스와 예외 도메인 관리
proxy domain 또는 classical 프록시 그룹 접속 대상과 정책 그룹을 함께 점검
private-ip ipcidr DIRECT 로컬 네트워크와 사설 주소 보호

Clash 규칙은 위에서 아래로 검사되며, 먼저 일치한 규칙에서 처리가 끝납니다. 그러므로 구체적인 예외를 넓은 규칙보다 위에 배치해야 합니다. 예를 들어 특정 도메인을 직접 연결해야 하지만 그 도메인이 해외 서비스 전체 목록에도 포함되어 있다면, 예외용 DOMAIN 또는 DOMAIN-SUFFIX 규칙을 해외 목록보다 먼저 두어야 합니다.

rules:
  - DOMAIN,login.example.com,DIRECT
  - RULE-SET,ads,REJECT
  - RULE-SET,direct,DIRECT
  - RULE-SET,proxy,Proxy
  - GEOIP,private,DIRECT,no-resolve
  - MATCH,Final

MATCH는 최종 대체 규칙이므로 반드시 마지막에 두어야 합니다. MATCH 뒤에 추가한 공급자 규칙은 실행되지 않습니다. 또한 차단 목록을 너무 앞에 배치하면 사용자가 허용하려는 예외까지 차단될 수 있습니다. 예외 규칙을 별도의 작은 공급자로 만들고 차단 공급자보다 먼저 참조하면 수정과 검토가 쉬워집니다.

직접 구성하고 검증하는 실전 작업 순서

자동화부터 시작하지 말고 먼저 작은 공급자 하나를 수동으로 검증하세요. 운영 중인 전체 설정을 한 번에 바꾸면 다운로드 오류, YAML 문법 오류, 규칙 우선순위 오류를 구분하기 어렵습니다. 다음 순서는 로컬 테스트와 저장소 자동화를 연결할 때 사용할 수 있는 기본 흐름입니다.

  1. 규칙 목적을 정합니다. 광고 차단인지 직접 연결인지 프록시 전송인지 먼저 결정하고, 하나의 파일에 여러 정책을 섞지 않습니다.
  2. 파일 형식을 고릅니다. 도메인 목록이면 domain 계열, 완전한 Clash 규칙이면 classical, IP 대역이면 ipcidr을 선택합니다.
  3. 로컬 파일을 먼저 작성합니다. 비공개 정보와 인증 토큰을 규칙 파일에 넣지 말고, 테스트에 필요한 소수의 항목만 남깁니다.
  4. 코어에서 공급자를 로드합니다. 클라이언트의 설정 재로드 또는 코어 재시작 후 공급자 상태와 파일 저장 경로를 확인합니다.
  5. 실제 연결을 확인합니다. 테스트 도메인에 접속하고 연결 기록에서 매칭된 RULE-SET 이름과 정책 그룹을 확인합니다.
  6. 그다음 자동 갱신을 추가합니다. 로컬 검증이 끝난 뒤 원격 URL과 GitHub Actions를 연결해야 실패 원인을 좁힐 수 있습니다.

로컬에서 YAML의 들여쓰기와 키 이름을 확인할 때는 일반 YAML 파서만 사용해서는 부족할 수 있습니다. YAML 문법이 맞아도 사용 중인 코어가 해당 필드를 지원하지 않거나, 공급자 파일의 behavior가 실제 데이터와 다르면 실행 단계에서 문제가 발생합니다. 따라서 일반 설정 파일의 파싱 검사, 공급자 파일의 형식 검사, 실제 코어 로드 테스트를 서로 다른 단계로 나누는 것이 안전합니다.

rules/
  ads.yaml
  direct.yaml
  proxy.yaml
config.yaml
.github/
  workflows/
    validate-rules.yml

저장소에는 규칙 파일과 검증 스크립트만 두고, 개인 구독 URL, 서버 인증 정보, 외부 제어 인터페이스의 비밀 키는 커밋하지 마세요. 공개 저장소에서 사용하는 자동화라면 로그에 환경 변수 값이 출력되지 않는지도 확인해야 합니다.

GitHub Actions로 검증과 자동 갱신 구성하기

GitHub Actions는 저장소에 변경이 올라왔을 때 검증을 실행하거나, 예약된 시간에 규칙 파일을 갱신하는 작업에 사용할 수 있습니다. 중요한 점은 다운로드와 커밋을 하나의 무조건적인 작업으로 취급하지 않는 것입니다. 먼저 임시 디렉터리에 파일을 내려받고 HTTP 응답 코드, 파일 크기, 예상되는 구조를 확인한 뒤 기존 파일을 교체해야 합니다.

name: Validate rule providers

on:
  push:
    paths:
      - "rules/**"
      - "scripts/**"
      - ".github/workflows/**"
  schedule:
    - cron: "17 3 * * *"
  workflow_dispatch:

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check files
        run: |
          test -s rules/ads.yaml
          test -s rules/direct.yaml
          python scripts/check_rules.py

      - name: Show changes
        run: git diff --check

위 예시는 구조를 설명하기 위한 뼈대입니다. 실제 운영에서는 사용하는 Actions 실행기와 검증 도구의 버전을 고정하고, 외부 명령이 내려받은 파일을 바로 실행하지 않도록 해야 합니다. 예약 실행은 UTC 기준으로 해석되므로 원하는 지역 시간과 실제 실행 시간이 다를 수 있습니다. 너무 짧은 주기로 실행하면 외부 서버의 속도 제한이나 일시적인 장애가 자동 커밋으로 반복될 수 있습니다.

자동 업데이트를 안전하게 만드는 조건

원격 공급자에서 HTTP 200 응답이 왔다는 사실만으로 유효한 규칙 파일이라고 판단해서는 안 됩니다. 서버가 장애 페이지를 정상 응답 코드로 반환하거나, 빈 파일을 보내거나, JSON 오류 메시지를 YAML 파일처럼 내려줄 수 있습니다. 최소한 파일 크기, 예상 루트 구조, 허용된 규칙 접두어를 확인하고 실패하면 기존 파일을 보존해야 합니다.

  • 임시 파일에 먼저 다운로드한 뒤 검사를 통과하면 교체합니다.
  • 빈 파일, 지나치게 작은 파일, HTML 오류 페이지를 거부합니다.
  • 검사에 실패하면 기존의 마지막 정상 파일을 삭제하지 않습니다.
  • 변경 내용이 지나치게 크면 자동 커밋 대신 검토 대기 상태로 둡니다.
  • 예약 작업이 중복 실행되지 않도록 동시 실행 정책을 확인합니다.

자동 커밋을 사용할 때는 변경 이유가 커밋 메시지에 드러나야 합니다. 예를 들어 공급자 이름과 갱신 날짜를 포함하면 나중에 특정 시점부터 문제가 시작되었는지 찾기 쉽습니다. 더 엄격한 운영 환경에서는 Actions가 직접 기본 브랜치에 쓰지 않고 변경 요청을 생성하게 하여 사람이 diff를 확인한 뒤 병합하도록 구성할 수 있습니다.

캐시 정책과 업데이트 오류 분석

rule-provider의 로컬 파일은 단순한 임시 다운로드가 아니라 네트워크 장애 시 사용할 수 있는 캐시 역할을 합니다. 원격 서버가 잠시 응답하지 않거나 DNS 조회가 실패해도 마지막으로 정상 저장된 규칙을 유지하면 기존 라우팅을 계속 사용할 수 있습니다. 반대로 자동화 스크립트가 갱신 실패 때 기존 파일을 빈 파일로 덮어쓰면, 장애가 발생했을 때 광고 차단이나 업무 라우팅이 동시에 무너질 수 있습니다.

캐시를 점검할 때는 세 가지 시간을 구분해야 합니다. 첫째는 원격 파일이 실제로 변경된 시점, 둘째는 코어가 파일을 확인하고 갱신한 시점, 셋째는 GitHub Actions가 저장소 파일을 갱신한 시점입니다. 저장소의 커밋이 최신이어도 실행 중인 코어가 아직 새 파일을 읽지 않았을 수 있고, 반대로 코어가 직접 원격 파일을 갱신하면 저장소 커밋과 실행 상태가 달라질 수 있습니다.

증상 가능한 원인 확인할 항목
공급자 다운로드 실패 URL, DNS, 인증 또는 외부 서버 장애 코어 로그와 URL 응답
다운로드는 성공하지만 매칭 안 됨 behavior, format 또는 파일 구조 불일치 공급자 파일의 실제 내용
예상보다 넓게 차단됨 규칙 공급자 순서 또는 과도한 suffix 규칙 연결 기록과 예외 규칙 위치
Actions만 실패 경로, 권한, 검사 스크립트 또는 실행 시간대 문제 작업 로그와 파일 diff

“파일을 찾을 수 없음” 오류는 URL 문제와 로컬 path 문제를 구분해야 합니다. 원격 다운로드가 성공했지만 코어가 파일을 읽지 못한다면 저장 디렉터리의 상대 경로, 권한, 클라이언트가 실제로 사용하는 설정 파일을 확인하세요. “지원하지 않는 behavior” 또는 “파싱 실패”가 나타나면 코어 버전과 공급자 파일 형식을 먼저 맞춰야 합니다.

운영 전 최종 점검 목록

자동화가 작동한다고 해서 규칙 설계가 끝난 것은 아닙니다. 규칙 공급자는 외부 데이터에 의존하므로 데이터의 품질과 정책 결과를 정기적으로 확인해야 합니다. 특히 차단 목록은 시간이 지나면서 오탐이 늘어날 수 있고, 서비스 도메인이 변경되면 직접 연결 또는 프록시 목록이 예상과 다르게 동작할 수 있습니다.

  • 실행 중인 코어가 rule-providers와 사용한 behavior를 지원하는지 확인합니다.
  • 각 공급자의 이름이 RULE-SET 참조와 정확히 일치하는지 확인합니다.
  • MATCH가 마지막에 있고 예외 규칙이 넓은 규칙보다 앞에 있는지 확인합니다.
  • 원격 URL이 HTTPS인지, 인증 정보가 공개 설정에 포함되지 않았는지 확인합니다.
  • 갱신 실패 때 기존 캐시가 유지되는지 테스트합니다.
  • 실제 연결 기록에서 도메인, 적용 규칙, 최종 정책 그룹을 확인합니다.
  • GitHub Actions 로그에 비밀 값이나 구독 식별자가 노출되지 않는지 확인합니다.
  • 규칙 파일 변경량이 갑자기 커졌을 때 자동 배포를 멈출 수 있는 절차를 마련합니다.

가장 안정적인 운영 방식은 모든 규칙을 자동으로 받아들이는 것이 아니라, 자동 검증과 수동 검토의 경계를 정하는 것입니다. 형식 검사와 작은 변경은 자동으로 처리하되, 대규모 변경이나 정책 영향이 큰 공급자는 변경 내역을 확인한 뒤 적용하세요. 이렇게 하면 GitHub Actions가 네트워크 장애를 숨기는 도구가 아니라, 규칙 데이터의 상태를 기록하고 반복 작업을 줄이는 검증 시스템으로 작동합니다.

자주 묻는 질문

rule-providers를 사용하면 모든 규칙을 외부 URL에 둘 수 있나요?

기술적으로는 외부 공급자를 사용할 수 있지만, 모든 규칙을 외부 데이터에 의존하는 것은 권장하지 않습니다. 개인 예외, 내부 도메인, 보안상 중요한 직접 연결 규칙은 로컬 파일이나 신뢰할 수 있는 비공개 저장소에서 관리하고, 공개 공급자는 내용과 변경 이력을 검토할 수 있는 경우에만 사용하세요.

interval을 짧게 설정하면 규칙이 더 정확해지나요?

반드시 그렇지는 않습니다. 공급자 자체가 자주 변경되지 않는다면 짧은 interval은 서버 요청과 클라이언트 작업만 늘립니다. 변경 빈도, 파일 크기, 서버 제한, 장애 시 캐시 유지 여부를 함께 고려해 수 시간에서 하루 이상의 간격을 선택하는 것이 일반적입니다.

GitHub Actions에서 파일을 갱신했는데 Clash에 바로 반영되지 않습니다.

저장소 파일과 실행 중인 코어의 캐시는 별개일 수 있습니다. 클라이언트에서 공급자 업데이트를 수동 실행하거나 설정을 다시 로드하고, 공급자 상태의 마지막 갱신 시간과 저장 경로를 확인하세요. 클라이언트가 다른 설정 파일을 실행 중인 경우에도 저장소 변경이 반영되지 않습니다.

다운로드 성공 후에도 RULE-SET이 매칭되지 않는 이유는 무엇인가요?

가장 흔한 원인은 behavior와 실제 파일 구조가 맞지 않는 경우입니다. 그 밖에 공급자 이름의 오타, rules에서의 참조 오류, 더 앞에 있는 규칙의 선행 매칭, DNS 또는 스니핑 조건도 확인해야 합니다. 연결 기록에서 실제 매칭 규칙을 확인하면 문제 범위를 빠르게 좁힐 수 있습니다.

Clash 다운로드