Mihomo rule-providers 고급 설정: GitHub 호스팅과 CI 검증
Mihomo rule-providers로 사용자 규칙을 GitHub에서 관리하는 이유
Mihomo 프로필에 도메인 규칙을 계속 추가하다 보면 rules가 길어지고, 같은 목록을 여러 기기에 복사하면서 내용이 서로 달라지기 쉽습니다. 회사 서비스나 개발 도구처럼 자주 바뀌는 도메인을 관리할 때는 규칙 한 줄의 누락이 연결 오류로 이어지기도 합니다. Mihomo rule-providers를 사용하면 규칙 목록을 별도 YAML 파일로 분리하고, GitHub 저장소에서 변경 이력과 검토 과정을 관리할 수 있습니다.
이 방식에서 로컬 프로필은 정책의 뼈대를 유지하고, 자주 바뀌는 도메인·IP 목록은 원격 제공자 파일에서 가져옵니다. 변경 내용을 커밋하기 전에 CI에서 YAML 문법과 Mihomo 설정을 확인하면, 잘못된 들여쓰기나 누락된 프록시 그룹 이름이 실제 기기에 반영되는 일을 줄일 수 있습니다. 여기서 CI는 규칙이 의도대로 사이트를 분류하는지까지 자동 증명하는 도구는 아닙니다. 구문 검증과 실행 가능한 설정 확인을 먼저 자동화하고, 실제 매칭은 Mihomo 로그와 연결 테스트로 별도 확인해야 합니다.
제공자 YAML과 프로필 연결 구조 설계
먼저 규칙 파일의 책임을 작게 나누세요. 예를 들어 개발 관련 도메인 목록과 미디어 서비스 목록을 각각 제공자로 만들면, 변경 검토 때 어떤 용도의 규칙인지 분명해집니다. 도메인 전용 목록이라면 behavior: domain, IP 대역 목록이라면 behavior: ipcidr를 선택하고, 여러 규칙 종류를 한 파일에서 함께 써야 할 때는 behavior: classical을 검토합니다. 파일의 실제 항목 형식과 behavior가 맞지 않으면 가져오기는 성공해도 규칙 해석에서 문제가 생길 수 있습니다.
다음은 공개 저장소의 Raw 파일을 가져오는 기본 형태입니다. 저장소 이름과 브랜치, 파일 경로, 프록시 그룹은 실제 환경에 맞게 바꾸세요. 예시의 rule-providers와 rules는 기존 프로필의 해당 키 아래에 병합해야 하며, 같은 최상위 키를 중복 선언하면 안 됩니다.
rule-providers:
dev-domains:
type: http
behavior: domain
format: yaml
path: ./providers/dev-domains.yaml
url: https://raw.githubusercontent.com/example/net-rules/main/providers/dev-domains.yaml
interval: 86400
rules:
- RULE-SET,dev-domains,Developer
- MATCH,Proxy
제공자 파일은 behavior: domain에 맞춰 다음처럼 도메인 항목을 나열할 수 있습니다. 파일 이름과 디렉터리 구조를 저장소 전반에서 일관되게 정하면 여러 프로필에서 재사용하기 쉽습니다.
payload:
- DOMAIN-SUFFIX,github.com
- DOMAIN,api.example.com
interval은 원격 파일을 다시 확인하는 주기(초)입니다. 짧은 값은 변경 반영이 빨라질 수 있지만 업데이트 요청도 잦아집니다. 규칙이 매일 여러 번 바뀌지 않는다면 하루 단위처럼 합리적인 주기로 시작하고, 저장소 제공량과 사용 환경에 맞춰 조정하세요. path는 다운로드한 파일을 저장할 위치이므로 Mihomo 실행 환경에서 쓰기 가능한 경로인지 확인해야 합니다. GitHub raw 주소가 네트워크 정책상 접근되지 않거나 일시적으로 실패할 수 있으므로, 업데이트 실패 시 기존 파일을 유지하는지와 로그에 오류가 기록되는지도 실제 클라이언트에서 점검하는 편이 좋습니다.
RULE-SET 참조 하나만 연결해 테스트하세요. 여러 제공자를 한꺼번에 추가하면 파일 형식 오류와 규칙 순서 문제를 구분하기 어려워집니다.GitHub 저장소와 CI 검증 흐름 만들기
저장소에는 규칙 파일뿐 아니라 목적과 변경 기준도 함께 기록하세요. README에 각 제공자의 용도, 예상되는 항목 형식, 검토 담당자, 규칙을 추가하거나 제거하는 기준을 적으면 팀원이 임의로 넓은 접미사를 넣는 일을 줄일 수 있습니다. 브랜치 보호를 켜고 Pull Request 검토를 요구하면, 규칙 변경이 직접 기본 브랜치에 들어가는 일을 막을 수 있습니다. 공개 목록이라도 출처와 확인 날짜를 기록하면 오래된 도메인이나 잘못된 항목을 정리하기 쉽습니다.
CI의 첫 단계는 YAML 파서와 린터로 문법을 검사하는 것입니다. 다음 단계에서는 고정한 버전의 Mihomo 실행 파일로 실제 프로필을 테스트합니다. 아래 워크플로는 개념 예시이며, 사용 중인 GitHub Actions 환경과 Mihomo 배포 파일의 이름·아키텍처에 맞게 설치 단계를 조정해야 합니다. 자동 업데이트되는 최신 바이너리를 매번 무조건 가져오기보다, 검증한 릴리스 버전을 고정하고 의도적으로 올리는 편이 재현성에 유리합니다.
name: Validate rules
on:
pull_request:
push:
branches: [main]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Check YAML files
run: |
yamllint providers/
- name: Test Mihomo configuration
run: |
mihomo -t -f ./config-ci.yaml
CI에서 테스트할 config-ci.yaml은 저장소의 규칙 제공자를 참조하는 검증용 프로필로 준비합니다. 실사용 프로필 전체를 복사해 비밀 값이나 개인 구독 주소까지 저장소에 넣을 필요는 없습니다. 테스트 구성에는 유효한 프록시 그룹 이름과 필요한 최소한의 필드만 두고, PR에서 바뀐 규칙 파일이 그 구성으로 읽히는지 확인하세요. yamllint는 들여쓰기·문서 형식 같은 문제를 찾고, mihomo -t는 Mihomo가 설정을 파싱할 수 있는지 확인합니다. 둘은 서로 다른 검증이므로 한 단계만 통과했다고 나머지를 생략하지 마세요.
원격 URL을 CI에서 직접 가져오도록 설정하면 네트워크 장애나 외부 저장소 변경까지 빌드 결과에 영향을 줄 수 있습니다. 가능하면 PR 검증에서는 체크아웃한 저장소의 규칙 파일을 이용해 구성을 검사하고, 별도의 주기 작업이나 배포 전 점검에서 공개 Raw URL의 접근성과 실제 내려받은 파일을 확인하세요. 외부 서비스 토큰이 꼭 필요한 경우에만 GitHub Secrets를 사용하고, 공개 규칙을 읽는 데 불필요한 쓰기 권한 토큰을 추가하지 마세요.
규칙 순서와 실제 매칭 결과 확인
YAML 검증이 통과해도 기대한 프록시 그룹을 타지 않을 수 있습니다. Mihomo는 rules를 위에서부터 평가하므로, 넓은 GEOIP나 MATCH 규칙이 제공자 참조보다 앞에 있으면 해당 요청은 먼저 종료될 수 있습니다. 일반적으로 구체적인 사용자 규칙을 넓은 지역 규칙이나 최종 MATCH보다 위에 두되, 기존 프로필의 정책과 충돌하지 않는지 확인하세요. 규칙 파일을 분리했다고 해서 순서 문제가 자동으로 해결되는 것은 아닙니다.
| 확인 항목 | 흔한 문제 | 점검 방법 |
|---|---|---|
| 제공자 다운로드 | URL 오타, 브랜치명 변경, raw 접근 실패 | 클라이언트 로그와 URL 응답 상태 확인 |
| YAML 형식 | 들여쓰기 오류, 잘못된 payload 구조 |
린터와 Mihomo 설정 테스트 실행 |
| 규칙 종류 | behavior와 항목 형식 불일치 |
도메인·IP·클래식 규칙 형식을 대조 |
| 규칙 순서 | 더 넓은 규칙이 먼저 일치 | RULE-SET을 앞뒤 규칙과 함께 확인 |
| 프록시 그룹 | 참조한 그룹 이름이 프로필에 없음 | proxy-groups의 이름과 철자 비교 |
테스트할 때는 브라우저에서 접속이 되는지만 보지 말고, Mihomo의 연결 또는 규칙 로그에서 요청 도메인과 매칭된 규칙, 선택된 정책 그룹을 함께 확인하세요. 예상한 제공자 규칙이 아니라 다른 규칙이 표시되면 순서나 도메인 범위를 살펴봅니다. 도메인 접미사 규칙은 하위 도메인까지 영향을 줄 수 있으므로, 너무 넓은 항목을 추가하기 전에 실제 요청 로그에서 필요한 호스트를 확인하는 것이 좋습니다. DNS 결과가 예상과 다르거나 앱이 IP 주소로 직접 접속하는 경우에는 도메인 규칙만으로 분류되지 않을 수 있으므로 DNS 모드와 앱의 연결 방식을 함께 점검해야 합니다.
업데이트 직후만 문제가 생긴다면 제공자 파일이 새로 내려왔는지, 클라이언트가 해당 파일을 다시 읽었는지, 이전 캐시가 남아 있는지 순서대로 구분합니다. 규칙이 적용되지 않는다고 곧바로 업데이트 주기를 아주 짧게 줄이면 원인을 가리기 어렵습니다. 먼저 같은 도메인을 포함하는 중복 규칙, 잘못된 정책 그룹 이름, 대소문자나 공백이 포함된 항목, 규칙 앞쪽의 광범위한 매칭을 확인하세요. 변경 전후의 로그와 파일 버전을 기록하면 문제를 재현하고 롤백하기도 편해집니다.
변경 검토·배포·롤백을 안정적으로 운영하기
GitHub에서 규칙을 관리할 때 중요한 것은 자동 갱신 자체보다 변경을 예측 가능하게 만드는 일입니다. 한 PR에는 한 목적의 수정만 담고, 어떤 도메인을 왜 추가했는지 설명을 남기세요. CI 실패 시 기본 브랜치에 병합하지 않고, 검증이 통과한 뒤에도 먼저 테스트 기기나 별도 프로필에서 실제 요청을 확인하면 영향 범위를 좁힐 수 있습니다. 여러 기기가 같은 규칙을 쓰더라도 업데이트 시점은 다를 수 있으므로, 배포 후에는 각 클라이언트의 제공자 상태와 마지막 업데이트 시각을 확인하세요.
문제가 발생하면 마지막으로 정상 동작한 커밋으로 되돌리고, Mihomo에서 제공자 파일을 다시 읽었는지 확인합니다. Git의 변경 이력은 어떤 줄이 언제 바뀌었는지 추적하고 되돌리는 데 유용하지만, 원격 파일 URL이나 네트워크 경로가 바뀐 문제까지 자동 복구하지는 않습니다. 그래서 저장소에는 파일의 변경 이력뿐 아니라 테스트 방법, 사용 중인 Mihomo 버전, 롤백 절차도 간단히 남겨야 합니다. 정기적으로 사용하지 않는 항목을 제거하고, 만료되거나 소유자가 불분명한 도메인은 재검토하면 rule-provider가 무한히 커지는 것을 막을 수 있습니다.
일부 동종 클라이언트나 단순한 VPN 앱은 규칙 목록을 여러 장치에서 일관되게 검토하고, 변경 이유를 추적하거나 적용 전에 YAML을 자동 검증하는 흐름이 제한적일 수 있습니다. 그 때문에 목록을 수동 복사하거나 오류가 난 뒤에야 원인을 찾는 경우가 생깁니다. Mihomo rule-providers는 GitHub의 버전 관리와 CI 검증을 조합해 규칙 배포를 명확하게 만들고, 실제 매칭 로그로 결과를 확인할 수 있다는 장점이 있습니다. 사용자 규칙을 체계적으로 관리하고 싶다면 다운로드 페이지에서 사용 환경에 맞는 클라이언트를 확인해 보세요.