이 글의 목차
도메인 패턴 검증 실패인지 먼저 확인
이 글은 명확한 증상 한 가지를 다룹니다. 같은 구성이 Mihomo v1.19.29 또는 이전 버전에서는 시작되지만 v1.19.30으로 업그레이드한 뒤 Parse config error: invalid domain이 표시되고 코어가 구성을 불러오는 단계에서 바로 종료됩니다.
공식 issue #3116에는 Linux Docker 환경에서 발생한 이 변경이 기록되어 있으며 최종 원인은 sniffer.skip-domain 및 dns.fake-ip-filter의 도메인 패턴으로 확인되었습니다. v1.19.30에는 더 엄격한 Clash 스타일 도메인 와일드카드 검증이 포함되었습니다. 이는 노드 실패가 아니며 프록시 모드를 Direct로 바꿔 피할 수 있는 연결 문제도 아닙니다.
로그에 Invalid YAML, unsupported field, proxy not found가 표시되거나 코어는 시작되었지만 웹페이지가 열리지 않는다면 장애가 다른 단계에서 발생한 것입니다. 해당 오류부터 점검해야 하며 모든 구성 실패를 이 글의 와일드카드 방식으로 바꾸면 안 됩니다.
첫 오류에 따라 먼저 분기
| 로그 또는 증상 | 가능성이 높은 단계 | 이 글 적용 여부 |
|---|---|---|
| Parse config error: invalid domain | 도메인 패턴 검증 | v1.19.30으로 업그레이드한 뒤 발생했다면 적용 |
| Invalid YAML 또는 들여쓰기 오류 | YAML 텍스트 구조 | 적용하지 말고 문법부터 수정 |
| proxy / group not found | 정책 그룹 또는 규칙 참조 | 적용하지 말고 누락된 참조부터 추가 |
| 코어가 시작되었고 특정 도메인만 실패함 | DNS, 규칙 또는 네트워크 | 적용하지 말고 연결 기록부터 확인 |
사용 가능한 구성과 생성 출처부터 저장
별표를 검색하기 전에 현재 최종 구성, 클라이언트 Profile, Merge 또는 덮어쓰기 및 구독 변환 템플릿을 각각 저장하세요. 실행 디렉터리의 config.yaml만 백업하면 부족합니다. 다음 구독 업데이트 때 소스의 잘못된 패턴이 수정 내용을 다시 덮어쓸 수 있습니다.
이전 코어가 계속 트래픽을 전달하고 있다면 서비스를 먼저 다시 시작하거나 구독을 연속으로 새로 고치지 마세요. 현재 사용할 수 있는 상태를 보존한 뒤 오류 로그, 클라이언트 버전 및 실제 Mihomo 버전을 복사하세요. 스크린샷과 구성 사본에서는 구독 token, 노드 비밀번호, 컨트롤러 secret 및 비공개 도메인을 제거해야 합니다.
롤백 경로 준비
실제 코어 버전 기록
클라이언트 정보 페이지, 시작 로그 또는 mihomo -v에서 실행 중인 버전이 v1.19.30인지 확인하고 ‘최신 버전’이라는 표현으로 버전 번호를 대신하지 마세요.
최종 구성 내보내기
코어가 실제로 불러온 YAML을 저장하고 Profile, Merge, 덮어쓰기 또는 변환 템플릿도 별도로 저장하세요.
이전 코어 버전 보존
공식 Release에서 받은 파일 중 현재 시스템에서 사용 가능함을 확인한 v1.19.29 파일만 임시 롤백용으로 보존하세요.
다른 변수 고정
점검 중에는 구독, 노드, DNS 모드 또는 TUN 설정을 동시에 바꾸지 않아 두 번째 장애가 생기지 않도록 합니다.
첫 번째 잘못된 도메인 패턴 찾기
실제로 실행할 v1.19.30으로 최종 구성을 먼저 테스트하세요. 공식 issue에서 사용한 명령은 mihomo -t -f입니다. 테스트 모드 성공은 현재 코어에서 구성을 파싱하고 초기화할 수 있다는 뜻일 뿐 프록시를 시작하지 않으며 노드 사용 가능 여부도 증명하지 않습니다.
v1.19.30 안정 버전은 포괄적인 invalid domain만 반환할 수 있습니다. 이 경우 최종 YAML과 참조하는 로컬 파일에서 별표를 검색하고 issue에서 문제가 확인된 sniffer.skip-domain 및 dns.fake-ip-filter를 먼저 점검하세요. 항목 하나를 수정할 때마다 다시 테스트해 코어가 다음 오류를 표시하도록 합니다.
mihomo -v
mihomo -t -f /path/to/config.yamlgrep -R -n '\*' /path/to/config.yaml /path/to/rules 2>/dev/nullrrn-sw-*, a*.example.com 또는 *a.example.com
별표가 같은 레이블의 다른 문자와 섞인 패턴으로 v1.19.30에서 명확히 거부됩니다.
*.example.com 또는 time.*.com
별표가 레이블 전체를 단독으로 차지하므로 형식 자체는 올바릅니다. 다음 항목을 계속 찾으세요.
example.com., a..example.com 또는 앞뒤에 공백이 있는 값
마지막 점, 빈 레이블 및 앞뒤 공백도 엄격한 검증에서 거부됩니다.
별표를 전혀 찾을 수 없음
더하기 기호, 마지막 점, 빈 레이블 및 클라이언트가 생성한 최종 구성을 확인하고 구독 원문만 검색하지 마세요.
올바른 도메인 와일드카드 세 가지부터 구분
Mihomo 문서에서는 이 문법을 Clash 스타일 도메인 와일드카드라고 부르며 라우팅 규칙의 DOMAIN-WILDCARD와 다른 문법임을 명시합니다. 규칙 가이드의 비슷해 보이는 별표 표현식을 fake-ip-filter나 skip-domain에 그대로 복사하면 안 됩니다.
중요한 점은 별표가 앞이나 뒤에 있는지가 아니라 점으로 구분된 레이블 전체를 별표가 단독으로 차지해야 한다는 것입니다. time.*.com은 가운데 레이블이 별표 하나이므로 올바르고 rrn-sw-*는 별표와 rrn-sw-가 같은 레이블에 섞여 있으므로 올바르지 않습니다.
실제 매칭 범위에 맞는 문법 선택
| 올바른 문법 | 매칭 범위 | 매칭되지 않는 항목 |
|---|---|---|
| *.example.com | a.example.com처럼 정확히 한 단계의 하위 도메인 | example.com、b.a.example.com |
| +.example.com | 루트 도메인과 모든 단계의 하위 도메인 | 다른 접미사 |
| .example.com | 모든 단계의 하위 도메인 | example.com 루트 도메인 |
| time.*.com | 가운데 정확히 하나의 전체 레이블 | time.com、time.a.b.com |
| * | 점이 없는 단일 레이블 호스트 이름 | 점이 포함된 전체 도메인 이름 |
rrn-sw-*
a*.example.com
*a.example.com
a*b.example.com실제 의도에 맞춰 다시 작성하고 기계적으로 치환하지 않기
고정 루트 도메인 아래의 한 단계 또는 여러 단계 하위 도메인을 매칭하려는 경우 별표, 더하기 기호 및 점 접두사 중에서 선택할 수 있습니다. 원래 의도가 rrn-sw-로 시작하는 여러 LAN 호스트를 매칭하는 것이라면 Clash 스타일 도메인 목록에는 rrn-sw-*와 같은 부분 레이블 와일드카드가 없습니다. 실제 호스트 이름을 나열하는 방법이 가장 안전합니다.
rrn-sw-*를 기계적으로 *.rrn-sw, rrn-sw.* 또는 +.rrn-sw로 바꾸지 마세요. 서로 다른 레이블 구조를 뜻하므로 검증을 통과해도 원래 대상 호스트와 매칭되지 않을 수 있습니다. 실제 조회 이름을 먼저 나열하고 각 구성이 포괄하는 범위를 설명할 수 있어야 합니다.
sniffer:
skip-domain:
- "rrn-sw-01"
- "rrn-sw-02"
dns:
fake-ip-filter:
- "+.example.com"
- "time.*.com"잘못된 문법과 실행 가능한 처리 방법
| 원래 의도 | 이렇게 바꾸지 마세요. | 실행 가능한 처리 |
|---|---|---|
| rrn-sw-로 시작하는 짧은 호스트 이름 매칭 | rrn-sw-*를 계속 사용 | rrn-sw-01, rrn-sw-02 등 실제 호스트 이름 나열 |
| example.com의 한 단계 하위 도메인 매칭 | a*.example.com | *.example.com 사용 |
| 루트 도메인과 모든 하위 도메인 매칭 | *example.com | +.example.com 사용 |
| 루트 도메인을 제외한 모든 하위 도메인만 매칭 | *.example.com을 사용하고 여러 단계까지 포함한다고 잘못 판단 | .example.com 사용 |
같은 v1.19.30에서 수정 검증
후보 사본을 저장한 뒤 같은 v1.19.30으로 구성 테스트를 다시 실행하세요. invalid domain이 계속 표시되면 다음 항목을 처리하고 첫 오류가 사라졌다는 이유로 유일하게 사용할 수 있는 구성을 바로 덮어쓰지 마세요. 모든 오류가 사라진 뒤에만 클라이언트에서 후보를 불러오고 코어를 다시 시작합니다.
코어 시작은 첫 번째 검증 단계일 뿐입니다. fake-ip-filter와 매칭되어야 하는 도메인, sniffer에서 건너뛰어야 하는 도메인 및 일반 공용 도메인에 각각 접속하고 DNS 결과와 연결 기록을 확인하세요. 문법 검증을 통과해도 매칭 범위가 잘못되었다면 수정이 끝난 것이 아닙니다.
롤백 가능한 순서로 후보 적용
후보 사본 테스트
v1.19.30에서 구성 테스트 성공이 명확히 반환될 때까지 mihomo -t -f를 실행합니다.
원본을 저장한 뒤 교체
이전의 사용 가능한 YAML을 보존하고 클라이언트 실행 중에 유일한 원본을 덮어쓰지 않습니다.
코어 다시 불러오기 또는 다시 시작
로그에 v1.19.30이 시작되었다고 표시되고 이전 프로세스나 구성을 계속 읽지 않는지 확인합니다.
실제 매칭 다시 테스트
확실한 도메인 요청으로 DNS, 스니핑, 규칙 매칭 및 최종 페이지 접속을 확인합니다.
수정 완료 기준
- v1.19.30의 최종 구성 테스트 모드 통과
- 새 구성 파싱 오류 없이 코어가 시작되어 계속 실행됨
- 나열한 LAN 호스트에서 스니핑 또는 Fake-IP를 예상대로 건너뜀
- 한 단계, 모든 단계 및 루트 도메인의 매칭 범위가 선택한 문법과 일치함
- 일반 공용 도메인과 노드 연결이 넓어진 규칙으로 잘못 처리되지 않음
- 원본 구성, 생성 출처 및 이전 코어 롤백 파일을 계속 찾을 수 있음
업데이트 후 재발하면 생성 출처 수정
직접 수정한 뒤에는 시작되지만 구독을 새로 고치거나 Profile을 전환하거나 클라이언트를 다시 시작하면 같은 오류가 다시 나타난다면 잘못된 패턴이 변환 템플릿, 원격 구성, Merge 또는 덮어쓰기에서 온 것입니다. 임시 실행 파일을 반복해서 편집하지 말고 수정 전후의 최종 YAML을 비교해 어느 계층에서 이전 값을 다시 쓰는지 찾으세요.
구독이나 변환기를 제어할 수 있다면 템플릿을 직접 수정하고 다시 생성하세요. 클라이언트만 제어할 수 있다면 관리되는 Merge 또는 덮어쓰기에서 전체 목록을 교체하고 업데이트 후 최종 구성도 올바른지 확인합니다. token이 포함된 구독을 알 수 없는 변환 사이트에 업로드하거나 지나치게 넓은 접미사 하나로 모든 미확인 상황을 덮지 마세요.
구독을 업데이트할 때마다 재발함
구독 변환 템플릿 또는 업스트림 구성을 수정한 뒤 후보를 다시 생성
Profile 전환 후 재발함
각 Profile의 Merge, Script 및 로컬 덮어쓰기를 각각 확인
디스크 파일을 수정했지만 코어에 이전 값이 계속 표시됨
실제 로딩 경로, 프로세스 및 클라이언트가 생성한 최종 구성 확인
넓은 접미사를 사용해야만 시작할 수 있음
필요한 호스트를 먼저 나열하고 누락 항목을 기록하며 넓어진 범위를 장기 해결책으로 사용하지 않음
즉시 수정할 수 없으면 안전하게 롤백
제어할 수 없는 출처에서 구성이 계속 생성되어 단기간에 수정할 수 없다면 TUN 또는 시스템 프록시를 끄고 시스템 직접 연결을 복원한 뒤 백업 구성을 되돌릴 수 있습니다. 꼭 필요한 서비스가 있다면 현재 시스템에서 검증한 v1.19.29로 잠시 돌아가고 생성 출처를 수정한 뒤 v1.19.30을 다시 테스트하세요.
롤백은 서비스를 복구하기 위한 용도일 뿐 이전 문법이 올바르다는 증거가 아닙니다. v1.19.30의 엄격한 검증 커밋은 현재 안정 버전에 포함되었고 더 자세한 오류 경로 커밋은 그 이후에 추가되었습니다. ‘이전 버전에서 오류가 없음’과 ‘새 Alpha에서 위치를 더 쉽게 찾음’을 장기 버전 전략으로 섞지 마세요.
사용 가능하다고 확인된 상태 복원
실패한 코어의 재시도 중지
시스템 트래픽이 실행되지 않는 로컬 포트를 계속 가리키지 않도록 클라이언트의 트래픽 처리부터 끕니다.
구성 백업 복원
Profile, 최종 YAML 및 필요한 덮어쓰기를 복원하고 출처를 알 수 없는 전체 디렉터리는 가져오지 않습니다.
필요하면 코어를 이전 버전으로 임시 롤백
공식 v1.19.29와 현재 시스템에서 검증한 아키텍처만 사용하고 롤백 이유와 날짜를 기록합니다.
같은 버전의 재테스트 일정 마련
생성 출처를 수정한 뒤 v1.19.30으로 돌아가 구성 테스트, 시작 및 실제 도메인 검증을 반복합니다.