GitHub에 rule-providers 구축하기: Mihomo YAML 규칙 관리 가이드

규칙을 rule-providers로 분리해야 하는 이유

Mihomo 설정에 도메인 규칙을 계속 직접 추가하면 처음에는 간단해 보여도 목록이 커질수록 관리가 번거로워집니다. AI 서비스, 개발 도구, 업무용 사이트의 규칙을 메인 YAML 한곳에 쌓아 두면 어떤 항목이 어떤 목적으로 추가됐는지 파악하기 어렵고, 오타 하나를 고치거나 기기별 설정을 맞출 때마다 전체 파일을 수정해야 합니다.

rule-providers는 규칙 목록을 별도의 파일로 두고 메인 설정에서 불러오는 기능입니다. 메인 YAML에는 규칙 세트의 이름과 다운로드 위치, 형식, 업데이트 간격을 선언하고, 실제 도메인이나 IP 목록은 GitHub 같은 호스팅 장소에서 관리합니다. 이렇게 나누면 프록시 그룹과 기본 동작은 메인 설정에 유지하면서, 자주 바뀌는 규칙만 별도로 편집할 수 있습니다.

예를 들어 AI 서비스용 도메인 세트와 개발 도구용 도메인 세트를 각각 관리하면, 새 도메인을 추가할 때 해당 파일만 수정하면 됩니다. 여러 기기에서 같은 규칙을 쓰고 싶을 때도 하나의 원본 파일을 공유할 수 있습니다. 단, 원격 규칙을 쓴다고 메인 설정 자체가 자동으로 안전해지는 것은 아닙니다. 규칙 파일을 변경할 수 있는 사람과 저장소의 공개 범위도 함께 관리해야 합니다.

GitHub에 규칙 파일 만들기

먼저 GitHub에 공개 저장소를 만들고 규칙 파일을 추가합니다. 저장소는 공개로 설정해야 Mihomo가 인증 정보 없이 원격 파일을 가져올 수 있습니다. 규칙 목록을 저장소에 공개해도 괜찮은지 확인하고, 개인용 또는 민감한 도메인 목록이라면 공개 저장소에 올리지 마세요. 비공개 저장소 URL에 개인 액세스 토큰을 그대로 붙이는 방법도 권장하지 않습니다. 토큰이 설정 파일이나 로그에 노출되면 저장소 접근 권한까지 유출될 수 있습니다.

YAML 형식을 사용할 경우 파일은 payload 목록을 포함하도록 구성합니다. 아래 예시는 도메인 규칙을 담는 간단한 형태입니다. 실제 도메인은 본인이 이용하는 서비스의 공식 도메인과 리디렉션 주소를 확인해 추가하고, 불필요하게 넓은 와일드카드나 다른 서비스의 도메인을 섞지 않는 편이 좋습니다.

payload:
  - DOMAIN-SUFFIX,openai.com
  - DOMAIN-SUFFIX,chatgpt.com
  - DOMAIN-SUFFIX,oaistatic.com

파일을 저장한 뒤 GitHub에서 해당 파일을 열고 Raw 버튼을 눌러 원본 파일 주소를 확인합니다. Mihomo 설정의 URL에는 저장소 페이지 주소가 아니라 원시 파일을 내려받는 주소를 사용해야 합니다. 보통 공개 저장소의 원본 주소는 raw.githubusercontent.com 도메인으로 시작합니다. 브라우저에서 주소를 열었을 때 GitHub 화면이 아니라 파일 내용이 표시되는지 확인하세요.

운영 중인 규칙의 변경 이력을 확인하기 쉽도록 저장소와 파일 이름을 목적에 맞게 정하고, 변경 이유를 커밋 메시지에 남겨 두면 문제가 생겼을 때 이전 버전과 비교하기 편합니다. 규칙 파일을 크게 개편하기 전에는 현재 작동하는 버전의 커밋을 기록하거나 파일을 별도로 백업해 두세요.

Mihomo YAML에 provider와 규칙 연결하기

다음 예시는 원격 YAML 파일을 규칙 provider로 등록하고, 해당 세트를 지정한 프록시 그룹으로 보내는 구성입니다. url은 앞에서 확인한 Raw 주소로 바꾸고, PROXY는 실제 설정에 존재하는 프록시 그룹 이름으로 바꾸세요. 그룹 이름은 대소문자와 기호까지 일치해야 합니다.

rule-providers:
  AI-SERVICES:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/ai-services.yaml
    url: https://raw.githubusercontent.com/USER/REPO/main/rules/ai-services.yaml
    interval: 86400

rules:
  - RULE-SET,AI-SERVICES,PROXY
  - MATCH,DIRECT

type: http는 원격 파일을 가져오는 방식이며, path는 내려받은 파일을 로컬에 저장할 경로입니다. 상대 경로는 실행 환경과 설정 파일의 위치에 따라 달라질 수 있으므로, 여러 프로필을 사용하는 경우 현재 활성 설정을 기준으로 경로가 올바른지 확인하세요. interval: 86400은 86,400초, 즉 하루 간격으로 업데이트를 확인한다는 뜻입니다. 규칙이 자주 바뀌지 않는다면 지나치게 짧은 간격을 설정할 필요는 없습니다.

behavior는 파일에 담긴 규칙 종류와 맞춰야 합니다. 도메인 목록에는 domain, IP 대역 목록에는 ipcidr, 여러 종류의 규칙 문법을 함께 사용하는 세트에는 classical을 선택할 수 있습니다. YAML 형식의 파일에는 payload 구조를 사용하고, 텍스트 형식의 규칙 파일을 쓸 때는 해당 Mihomo 버전에서 지원하는 format과 파일 문법을 함께 확인해야 합니다. 파일 형식과 behavior가 맞지 않으면 설정을 읽지 못하거나 규칙이 예상대로 매칭되지 않을 수 있습니다.

rules는 위에서 아래로 평가되며 먼저 일치한 규칙이 적용됩니다. 따라서 AI 서비스 규칙 세트를 넓은 범위의 일반 규칙이나 마지막 MATCH보다 앞에 배치해야 합니다. 위 예시에서 세트에 포함된 도메인은 PROXY로 보내고, 다른 트래픽은 MATCH,DIRECT로 처리합니다. 마지막 규칙은 예시일 뿐이므로 기존 설정의 기본 정책을 확인하고, 모든 트래픽을 직접 연결하는 구성이 적절한지 판단하세요. 다른 provider를 추가할 때도 세트 이름이 중복되지 않게 하고, 실제 RULE-SET 항목에서 선언한 이름과 동일하게 사용해야 합니다.

업데이트 확인과 오류 진단

설정을 저장한 뒤 곧바로 실제 트래픽에 적용하기 전에 YAML 문법 검사와 Mihomo의 설정 검증을 진행하세요. 사용 중인 클라이언트에서 설정 검사 기능을 제공한다면 먼저 실행하고, 오류가 있으면 줄 번호와 필드 이름을 확인합니다. 특히 들여쓰기, 콜론 뒤 공백, 그룹 이름, URL의 철자, behavior와 파일 형식의 조합을 살펴보세요. YAML은 들여쓰기가 구조를 결정하므로 탭과 공백을 섞지 않는 것이 안전합니다.

provider가 갱신되지 않으면 다음 순서로 원인을 좁혀 볼 수 있습니다.

• 원본 주소 확인: Raw URL을 브라우저에서 열어 파일 내용이 나오는지 확인합니다. 404 오류라면 저장소, 브랜치, 파일 경로의 대소문자를 점검합니다.
• 네트워크 접근 확인: 실행 중인 장치에서 GitHub 원본 파일에 접속할 수 있는지 확인합니다. DNS 오류, TLS 인증서 오류, 시간 설정 문제, 네트워크 차단은 모두 다운로드 실패로 이어질 수 있습니다.
• 형식과 필드 확인: YAML provider라면 파일의 루트에 유효한 payload가 있는지 보고, 각 규칙 문법이 지정한 behavior와 일치하는지 확인합니다.
• 로컬 저장 경로 확인: path가 실제 실행 환경에서 사용할 수 있는 위치인지 점검하고, 클라이언트 로그에서 파일 저장 또는 읽기 오류가 발생하는지 확인합니다.
• 매칭 순서 확인: 규칙 로그에서 요청 도메인이 어떤 규칙과 그룹에 매칭되는지 살펴봅니다. provider가 정상이어도 앞선 규칙이 요청을 처리하면 뒤쪽 세트에는 도달하지 않습니다.

새 규칙을 추가한 뒤 예상과 다른 그룹으로 연결된다면, 먼저 provider가 성공적으로 로드됐는지와 규칙 목록에 해당 도메인이 들어 있는지를 분리해 확인하세요. 파일 내용이 정상인데도 동작하지 않는 경우에는 도메인이 실제 접속 주소와 다른지, 더 구체적인 도메인 규칙이 필요한지, 브라우저나 앱이 별도의 연결 경로를 사용하는지 살펴볼 수 있습니다. 로그에는 접속 도메인이나 로컬 경로가 표시될 수 있으므로, 외부에 공유할 때는 민감한 정보를 가리는 것도 잊지 마세요.

정기적인 업데이트는 편리하지만, 원격 파일이 바뀌면 클라이언트의 라우팅 결과도 달라질 수 있습니다. 규칙을 수정한 뒤에는 커밋 이력과 Mihomo 로그를 확인하고, 업무에 필요한 서비스가 의도한 그룹으로 연결되는지 테스트하세요. 수동으로 자주 고치는 단일 설정 파일은 변경 지점과 되돌리기가 불분명해지기 쉽지만, rule-providers를 쓰면 규칙 파일과 기본 정책을 나누고 GitHub에서 변경 이력을 확인할 수 있습니다. 규칙 관리와 업데이트 동작을 직접 확인해 보고 싶다면, 사용 중인 플랫폼에 맞는 Clash 클라이언트를 지금 Clash 받기에서 살펴보세요.