mihomo 고급 설정

프록시 그룹 유형과 활용

규칙의 대상과 실제 연결 출구를 구분하세요

규칙은 연결을 어떤 대상으로 보낼지 정하고, 프록시 그룹은 그 대상이 최종적으로 어떤 출구를 사용할지 결정합니다. 규칙에 적은 이름은 프록시, 프록시 그룹 또는 내장 정책의 이름과 정확히 일치해야 합니다. 대소문자와 공백도 이름의 일부입니다. 먼저 안정적으로 유지할 업무별 그룹 이름을 정하고, 구독 업데이트는 그룹 안의 구성원에만 영향을 주도록 구성하세요. 그러면 프록시 항목이 바뀌어도 규칙은 같은 그룹을 계속 가리키므로 모든 규칙을 다시 작성할 필요가 없습니다.

select는 사용자가 직접 출구를 선택할 때 적합합니다. 구성원 하나를 일시적으로 사용할 수 없게 되어도 다른 구성원으로 자동 전환되지 않습니다. 클라이언트 패널에서 선택한 항목은 보통 저장되지만, 설정 이름과 클라이언트 구현에 따라 유지 여부가 달라질 수 있습니다. 문제를 진단할 때는 그룹 이름만 보지 말고 실제 프록시까지 펼쳐 현재 선택된 구성원을 확인하세요. 새 연결이 사용하는 전체 정책 경로도 살펴봐야 합니다. 이미 연결된 장시간 연결은 즉시 다른 경로로 전환되지 않는 경우가 많습니다.

목적에 맞는 자동 선택 정책

url-test는 테스트 결과에 따라 구성원을 선택하므로 출구가 바뀌어도 괜찮은 트래픽에 적합합니다. 측정 결과는 지정한 주소에 접속했을 때의 성능이며, 모든 웹사이트나 프로토콜의 체감 품질을 의미하지는 않습니다. 테스트 주소에서는 빠른 구성원도 특정 서비스에서는 제한될 수 있습니다. tolerance는 작은 차이로 인한 잦은 전환을 줄여 주지만, 출구를 고정해 주지는 않습니다. 세션의 연결 상태를 유지해야 하는 서비스에는 별도의 수동 선택 그룹을 사용하세요.

fallback은 구성원 순서를 중시합니다. 상태 확인에서 사용 가능하다고 판단된 구성원 중 앞에 배치된 출구를 우선 사용합니다. 주 출구와 보조 출구의 우선순위가 명확한 경우에 적합하며, 매번 테스트 시간이 가장 짧은 출구를 고르는 방식은 아닙니다. load-balance는 여러 구성원에 연결을 분산하지만, 다운로드 연결 하나에 여러 출구의 대역폭을 합쳐 주지는 않습니다. 로그인, 결제 또는 접속 원본 주소에 제약이 있는 서비스에는 순환 분배 정책을 바로 적용하지 않는 편이 좋습니다.

수동 선택과 자동 테스트를 2단계로 분리하세요

실용적인 구성은 바깥쪽에 수동 그룹을 두고 안쪽에 자동 그룹을 두는 방식입니다. 바깥 그룹에는 자동 선택, 고정 프록시, 직접 연결 등의 선택지를 제공하고, 안쪽 그룹에는 테스트할 프록시만 포함합니다. 바깥 그룹을 다시 안쪽 그룹에 넣으면 순환 참조가 발생하므로 피하세요. 단계도 지나치게 늘리지 않는 것이 좋습니다. 규칙 대상에서 실제 출구까지 두세 단계 안에 확인할 수 있는 구성이 복잡하게 중첩된 구성보다 관리하기 쉽습니다.

아래 예제는 내장 정책인 DIRECT만 참조합니다. 그룹 간 참조 방식을 이해하기 위한 예제로, 원격 프록시 출구가 구성되어 있다는 뜻은 아닙니다. 실제로 사용할 때는 자동 그룹의 구성원 목록에 현재 설정에 존재하는 프록시 이름을 추가하고, 필요에 따라 직접 연결 항목을 유지하거나 삭제하세요. 테스트 주소는 HTTPS를 사용하며, 테스트 간격의 단위는 초입니다. 테스트 주소에 접속할 수 있는지도 상태 확인 결과에 영향을 줍니다.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - AUTO
      - DIRECT
  - name: AUTO
    type: url-test
    proxies:
      - DIRECT
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - MATCH,DIRECT

프록시가 proxy-providers에서 제공된다면 프록시 그룹에서 use를 사용해 제공자를 참조하면 구성원 이름을 길게 복사하지 않아도 됩니다. 먼저 제공자가 정상적으로 로드되는지 확인한 다음 그룹에 예상한 구성원이 포함되어 있는지 살펴보세요. 필터 표현식은 넓은 조건부터 시작해 점차 좁히는 방식으로 추가하는 것이 좋습니다. 조건이 너무 좁으면 구독 업데이트는 성공해도 그룹에 사용할 수 있는 구성원이 하나도 남지 않을 수 있습니다. 이 경우 테스트 매개변수를 조정해도 빈 그룹 문제는 해결되지 않습니다.

프록시 그룹을 확인할 때는 먼저 패널에서 그룹 유형, 후보 구성원과 현재 선택을 확인한 다음 새로운 서비스 연결을 시도하세요. 로그에 테스트 성공이 표시되어도 상태 확인 경로가 작동한다는 뜻일 뿐, 실제 서비스 연결이 검증된 것은 아닙니다. 그룹을 바꾼 후에도 페이지가 달라지지 않는다면 해당 앱의 기존 연결을 끊거나 앱을 다시 열어 테스트하세요. 모든 네트워크 서비스를 바로 재시작할 필요는 없습니다. 모드 선택의 기본 차이는 프록시 모드 설명을 참고하세요.

규칙 세트 구독 관리

규칙은 순서를 정하고, 규칙 세트는 조건을 제공합니다

rules는 실행 순서이고 rule-providers는 재사용할 수 있는 매칭 조건입니다. 도메인 목록을 규칙 세트로 옮겨도 기본 설정에서 RULE-SET으로 해당 세트를 참조하고 일치 후 사용할 정책을 지정해야 합니다. 규칙 세트를 선언하기만 하면 트래픽 분기에 자동으로 쓰이는 것은 아닙니다. mihomo는 보통 위에서 아래로 규칙을 확인하고 처음 일치하는 항목을 적용합니다. 따라서 파일을 몇 개로 나누느냐보다 로컬 예외, 서비스 규칙, 최종 기본 규칙의 순서가 더 중요합니다.

먼저 개발 서비스, 로컬 네트워크 주소, 별도 출구가 필요한 서비스처럼 의미가 분명한 소규모 세트를 만드세요. 분류를 빠짐없이 채우려는 이유로 같은 도메인 목록을 여러 세트에서 중복 관리하지 마세요. 중복이 불가피하다면 기본 규칙에서 어떤 세트가 우선하는지 명시하고 이유를 기록하세요. 예외 규칙을 추가할 때는 무엇과 일치하는지, 어떤 정책으로 보낼지, 왜 그 위치에 두는지 설명할 수 있어야 합니다. 이유가 명확하지 않으면 이후 업데이트 때 삭제 여부를 판단하기 어렵습니다.

behavior와 파일 내용을 일치시키세요

behavior: domain은 도메인 항목에, ipcidr은 IP 주소 대역에, classical은 규칙 유형이 포함된 기존 형식의 규칙에 사용합니다. 이 세 가지는 서로 바꿔 쓸 수 있는 라벨이 아닙니다. 도메인 세트에 DOMAIN-SUFFIX 형식의 완전한 규칙을 넣거나, classical 세트에 도메인만 입력하면 로드에 실패하거나 예상과 다른 결과가 나올 수 있습니다. 파일 이름으로 형식을 추측하지 말고 실제 내용을 확인한 뒤 동작 유형을 선택하세요.

format도 실제 데이터 형식과 일치해야 합니다. YAML 규칙 세트는 보통 payload 배열을 사용하고, 텍스트 형식은 줄 단위로 읽습니다. 바이너리 규칙 세트는 별도의 생성 과정이 필요하므로 확장자만 바꿔서는 사용할 수 없습니다. 같은 도메인 목록을 여러 형식으로 제공한다면 mihomo에서 지원하는 형식을 선택하고, 파일 확장자도 실제 내용에 맞추세요. 브라우저에서 다운로드 주소가 열리는지보다 로드 로그의 파싱 오류가 문제를 더 정확히 보여 줍니다.

# 기본 설정에 병합하세요. rules의 위치는 기존 규칙에 맞게 조정해야 합니다
rule-providers:
  development:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/development.yaml

rules:
  - RULE-SET,development,PROXY
  - MATCH,DIRECT

# mihomo 설정 작업 디렉터리의 rules/development.yaml에 저장하세요
payload:
  - '+.github.com'
  - '+.githubusercontent.com'

로컬 검증 후 원격 업데이트 적용하기

위 예제에서는 PROXY라는 정책이 이미 있다고 가정합니다. 상대 경로는 보통 mihomo 작업 디렉터리를 기준으로 하며, 편집기에서 현재 열어 둔 파일의 위치를 기준으로 하지 않을 수 있습니다. 로컬 파일로 동작 유형과 매칭 방식을 먼저 확인한 뒤 원격 구독으로 전환하면 형식 문제와 네트워크 문제를 구분할 수 있습니다. 테스트할 때는 규칙 세트에 포함된 도메인 하나를 골라 새 연결을 만들고, 연결 상세 정보에서 같은 출구를 사용하는 기본 규칙이 아니라 해당 규칙 세트가 적용됐는지 확인하세요.

원격 소스에는 type: http를 사용하고 소스 주소, 캐시 경로와 업데이트 간격을 설정합니다. 주소는 실제로 관리자가 제공한 것이어야 하며, 웹에서 보이는 안내 페이지를 원본 규칙 파일 주소로 사용하면 안 됩니다. 업데이트 주기는 소스가 변경되는 속도에 맞추세요. 며칠에 한 번 바뀌는 목록을 자주 가져오면 요청과 문제 진단 기록만 늘어나는 경우가 많습니다. 계정 정보가 포함된 주소는 로컬 설정에만 저장하고 공개 스크린샷, 공유 저장소, 문제 보고 내용에 넣지 마세요.

규칙 업데이트가 실패하면 먼저 다운로드 실패, 내용 파싱 실패, 참조 오류를 구분하세요. 다운로드 실패라면 소스에 접속할 수 있는지와 다운로드에 사용되는 출구를 확인합니다. 파싱 실패라면 응답이 웹페이지, 오류 메시지 또는 다른 형식으로 바뀌지 않았는지 살펴보세요. 참조 오류라면 제공자 이름과 RULE-SET 이름이 일치하는지 확인합니다. 기존 캐시 덕분에 트래픽이 잠시 정상 작동할 수 있지만, 그것만으로 업데이트가 정상이라고 판단해서는 안 됩니다. 업데이트 시각과 로드 로그도 함께 확인하세요.

도메인 규칙은 대상 주소 조회가 필요한 지리적 위치 또는 IP 대역 규칙보다 앞에 두는 것이 좋습니다. 추가 조회를 피해야 하는 주소 규칙에는 문법에 맞게 no-resolve를 사용할 수 있지만, 모든 규칙에 붙이는 일반적인 접미사는 아닙니다. 실제 주소를 이미 알고 있는 연결은 주소 규칙과 일치할 수 있습니다. 도메인만 있고 실제 조회 결과가 없는 연결은 관련 판단을 건너뛸 수 있습니다. 이 매개변수를 조정하기 전에 생략하려는 조회가 무엇인지 먼저 확인하세요.

유지 관리 시 검증된 로컬 예외 세트를 별도로 보관하고 구독 내용은 외부에서 들어오는 데이터로 취급하세요. 구독을 개인 규칙 전체의 유일한 원본으로 삼지 않는 것이 좋습니다. 업데이트 후 대표적인 연결 몇 가지를 먼저 테스트하고 사용 범위를 점차 넓히세요. 잘못된 분기를 발견하면 적용된 규칙과 대상 정책을 기록한 뒤 세트를 수정할지 순서를 바꿀지 결정합니다. MATCH를 다른 출구로 바꾸면 문제를 가릴 수는 있지만, 기존에 정상 작동하던 연결도 대거 바뀔 수 있습니다.

DNS 설정 최적화

조회 대상별로 DNS 경로를 분리하세요

DNS를 최적화하려면 먼저 누가 무엇을 조회하고 요청이 어디에서 나가는지 구분해야 합니다. 앱은 시스템 DNS를 사용할 수도 있고 자체적으로 암호화 DNS 요청을 보낼 수도 있습니다. mihomo는 프록시 서버의 도메인도 조회해야 합니다. 세 요청이 같은 업스트림에 연결되더라도 처리 경로가 같다는 뜻은 아닙니다. 문제를 진단할 때 앱에서 mihomo로, mihomo에서 업스트림으로, mihomo에서 프록시 서버로 이어지는 관계를 먼저 정리한 다음 필드를 변경하면 초기 조회와 서비스 조회를 혼동하지 않을 수 있습니다.

default-nameserver는 주로 DNS 업스트림의 도메인을 조회해 암호화 DNS 연결의 시작점을 마련합니다. nameserver는 일반 조회에 사용할 업스트림이고, proxy-server-nameserver는 프록시 서버 도메인에 사용할 조회기를 지정할 수 있습니다. 프록시 연결이 아직 수립되지 않은 상태에서 시작 의존성을 처리할 때 특히 유용합니다. 프록시 도메인 조회 요청까지 해당 프록시를 거쳐야 한다면 순환 의존이 생길 수 있으며, 설정은 로드됐지만 출구 연결을 수립하지 못하는 증상이 나타날 수 있습니다.

설명하기 쉬운 최소 DNS 설정부터 구성하세요

아래 설정은 로컬에서 수신하고 Fake-IP를 사용하는 기본 구조를 보여 줍니다. 일반 UDP 업스트림과 HTTPS 업스트림은 네트워크 경로가 다르고, UDP 업스트림은 전송 암호화도 제공하지 않습니다. 이 예제는 조회 시작 단계와 일반 서비스 조회 단계의 역할을 설명하기 위한 것으로, 모든 네트워크에 그대로 적용할 정답은 아닙니다. 먼저 현재 네트워크에서 선택한 DNS 서버에 접속할 수 있는지 확인한 후 암호화 방식, 정책 라우팅, 대체 서버를 고려하세요. 업스트림 주소가 많다고 결과가 더 안정적인 것은 아닙니다.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - '*.lan'
    - '*.local'

DNS를 127.0.0.1:1053에서 수신하도록 설정해도 mihomo가 로컬 DNS 서비스를 제공한다는 뜻일 뿐, 시스템이 자동으로 그 서비스를 사용한다는 의미는 아닙니다. 일반적인 시스템 DNS 설정에는 임의의 포트를 지정할 수 없으므로 클라이언트의 DNS 가로채기, TUN 리디렉션 또는 별도의 명시적 전달 경로가 필요합니다. 시스템이 기존 DNS 서버를 계속 사용한다면 nameserver를 바꿔도 차이가 보이지 않는 것이 이상하지 않습니다. 먼저 조회가 실제로 mihomo에 들어오는지 확인한 뒤 업스트림 결과를 비교하세요.

도메인별 DNS 서버를 지정하고 대체 로직은 신중하게 추가하세요

nameserver-policy는 도메인 등의 조건에 따라 DNS 서버를 지정하는 설정입니다. 사내 도메인, 홈 네트워크 기기 도메인 또는 명확한 DNS 요구사항이 있는 서비스에 적합합니다. 내부 도메인은 내부 IP를 반환할 수 있는 DNS 서버로 보내야 하며, 공용 DNS 서버에 전송해서는 안 됩니다. 도메인 정책은 어떤 DNS 서버를 사용할지 정할 뿐, 최종 연결에 사용할 출구를 정하지는 않습니다. 올바른 주소를 조회한 다음에도 연결은 규칙과 프록시 그룹을 거쳐야 하므로 두 단계를 각각 확인하세요.

fallback은 기본 DNS 서버가 시간 초과된 뒤에만 사용하는 두 번째 주소라고 단순하게 이해해서는 안 됩니다. fallback-filter와 함께 결과 판정에 참여해 추가 조회가 발생할 수 있습니다. 현재 네트워크에 적합하지 않은 필터 조건을 설정하면 정상 결과가 부적절한 다른 결과로 바뀔 수도 있습니다. 어떤 응답을 바꿔야 하는지 설명할 수 있을 때만 이 단계를 추가하세요. 그렇지 않다면 신뢰할 수 있는 업스트림 몇 개로 기준을 먼저 정하는 편이 문제 원인을 파악하기 쉽습니다.

respect-rules를 활성화하면 DNS 업스트림 연결에도 라우팅 규칙이 적용될 수 있지만, 프록시 서버 도메인 조회와 같은 시작 단계의 의존성도 함께 처리해야 합니다. 아직 사용할 수 없는 프록시 그룹으로 모든 DNS 요청을 보내지 마세요. 테스트할 때 업스트림 연결의 출구와 서비스 연결의 출구를 각각 기록하세요. 두 출구는 다를 수 있으며, 실제로 달라야 하는 경우도 많습니다. 이 필드와 대체 DNS 설정의 자세한 내용은 DNS 필드 상세 설명을 참고하세요.

암호화 DNS 실패는 증상에 따라 나눠서 진단하세요. 도메인 조회 실패라면 먼저 초기 DNS 조회를 확인합니다. 주소를 얻었지만 핸드셰이크에 실패했다면 시스템 시간, 인증서 신뢰 여부와 연결 경로를 확인하세요. 업스트림 연결은 성공했지만 응답이 이상하다면 도메인 정책과 서비스 응답을 살펴봅니다. 네트워크나 시간 문제를 감추기 위해 인증서 검증을 끄지 말고, 근거 없이 여러 업스트림을 연달아 바꾸지도 마세요. 한 번에 변수 하나만 바꾸고 재현할 수 있는 조회 대상을 유지하세요.

캐시 때문에 설정 변경 결과가 바로 보이지 않을 수 있습니다. 시스템, 브라우저, mihomo가 조회 결과를 저장할 수 있고 앱이 기존 연결을 재사용할 수도 있습니다. 검증하기 전에 대상 앱의 기존 연결을 끊고 클라이언트에서 제공하는 방법으로 관련 캐시를 비운 다음 다시 조회하세요. 명령줄에서 로컬 DNS 수신기에 직접 질의하는 것과 브라우저로 웹페이지를 여는 것은 서로 다른 경로를 확인합니다. 결과가 다르면 먼저 브라우저가 별도의 DNS 조회를 사용하는지 확인하세요. 바로 mihomo 설정이 적용되지 않았다고 판단할 필요는 없습니다.

마지막으로 주소 체계를 확인하세요. DNS 응답에서 IPv6를 비활성화해도 시스템 전체의 IPv6 통신이 꺼지는 것은 아닙니다. 앱이 캐시된 주소를 사용하거나 자체적으로 조회할 수 있습니다. 반대로 IPv6 응답을 허용하려면 실제 네트워크에도 작동하는 경로가 있어야 합니다. 일부 사이트가 한참 기다린 뒤에 열리면 IPv4와 IPv6 연결 결과를 각각 확인한 후 어느 계층을 조정할지 결정하세요. DNS 설정의 목표는 필드를 최대한 많이 채우는 것이 아니라 현재 경로에 맞는 결과를 얻는 것입니다.

TUN 트래픽 가로채기와 Fake-IP 매핑

Fake-IP는 도메인을 연결하는 기능이지 원격 출구가 아닙니다

Fake-IP 모드에서는 mihomo가 앱에 매핑 주소를 반환하고 해당 주소와 도메인의 관계를 저장할 수 있습니다. 앱이 매핑 주소로 연결하면 mihomo가 도메인을 복원한 뒤 라우팅과 출구 처리를 진행합니다. 매핑 주소는 대상 서버의 공인 IP도, 프록시 서버 주소도 아닙니다. 198.18.0.0/16 대역의 결과가 보여도 곧바로 DNS 오류라고 판단하지 마세요. 연결이 mihomo에 들어왔는지, 예상한 도메인이 복원됐는지를 함께 확인해야 합니다.

Fake-IP와 TUN은 서로 다른 기능입니다. Fake-IP는 DNS 조회와 도메인 연결 정보를 처리하고, TUN은 가상 네트워크 인터페이스를 통해 트래픽을 받습니다. 두 기능을 함께 사용하는 경우가 많지만 서로 대체할 수는 없습니다. Fake-IP만 켜서는 모든 앱이 자동으로 프록시를 거치지 않고, TUN만 켜도 모든 연결에 도메인 정보가 생기는 것은 아닙니다. 하나의 스위치만으로 전체 네트워크를 가로챌 수 있다고 생각하지 말고 DNS 진입점, 가상 인터페이스와 규칙 처리를 연결해 검증하세요.

권한, 라우팅, DNS 순서에 따라 TUN을 활성화하세요

TUN은 관리자 권한, 서비스 구성 요소 또는 시스템 승인이 필요한 경우가 많습니다. Clash Plus, Clash Verge Rev, FlClash 등 클라이언트마다 메뉴 위치와 권한 처리 방식이 다르므로 현재 사용하는 클라이언트의 안내에 따라 필요한 구성 요소를 설치하세요. 설정 파일의 enable: true는 mihomo에 요청을 보내는 것뿐입니다. 시스템이 인터페이스 생성이나 라우트 추가를 거부하면 트래픽을 가로챌 수 없습니다. 스위치를 반복해서 누르기보다 로그에서 인터페이스와 라우트가 생성됐는지 확인하세요.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

이 설정은 활성화된 dns 설정과 함께 사용해야 합니다. auto-route는 mihomo에 관련 경로 설정을 요청하고, auto-detect-interface는 출구 인터페이스를 찾는 데 도움을 줍니다. dns-hijack은 조건에 맞는 일반 DNS 트래픽을 mihomo로 보냅니다. 모든 HTTPS 암호화 DNS를 자동으로 가로채는 것은 아니므로 앱 자체의 암호화 DNS는 별도로 확인해야 합니다. 플랫폼과 네트워크 스택별 지원 범위는 실행 로그와 현재 mihomo 문서를 기준으로 판단하세요.

system, gvisor, mixed는 네트워크 스택을 선택하는 옵션이지 품질 순위가 아닙니다. 프로토콜 처리, 시스템 통합과 호환성에서 각각 장단점이 다릅니다. 특정 앱에서 문제가 발생하면 다른 설정은 그대로 둔 채 네트워크 스택만 바꿔 비교할 수 있습니다. DNS, 라우팅, MTU를 동시에 변경하지 마세요. 한 번에 변수 하나만 바꿔야 개선이 네트워크 스택 때문인지 다른 설정 때문인지 판단할 수 있습니다.

로컬 네트워크, VPN, 매핑 예외 처리

프린터, 화면 전송 기기, 내부 관리 페이지처럼 로컬 네트워크 기기는 보통 실제 IP 주소로 직접 접속해야 합니다. fake-ip-filter를 사용하면 지정한 도메인에는 매핑 주소를 할당하지 않지만, 해당 연결이 자동으로 직접 연결되는 것은 아닙니다. DNS 서버가 올바른 내부 주소를 반환하도록 하고 규칙에서 적절한 출구도 지정해야 합니다. 올바른 내부 DNS 없이 필터만 추가하면 매핑 주소는 사라졌지만 기기에 계속 접속할 수 없는 상황이 흔히 발생합니다.

기업 VPN, 가상 머신, 컨테이너, 다른 프록시 프로그램도 라우트를 추가할 수 있습니다. 동시에 활성화하기 전에 각 네트워크 대역을 기록하고 Fake-IP 주소 대역과 겹치는지 특히 확인하세요. 여러 네트워크 카드가 있는 환경에서는 자동 인터페이스 감지가 적절하지 않은 출구를 선택할 수도 있습니다. 이때는 실제 인터페이스와 라우트를 기준으로 조정하고 다른 기기의 인터페이스 이름을 그대로 복사하지 마세요. 기업 내부 네트워크를 변경하기 전에는 기기 관리 규정을 따르고 기존 접근 범위를 훼손하지 않도록 주의하세요.

일부 프로그램은 조회된 주소를 프로토콜 검증, 로컬 네트워크 검색, 주소 표시 등에 사용하므로 매핑 결과를 받아들이지 못할 수 있습니다. 이 문제는 범위를 좁혀 처리하세요. 먼저 문제가 발생한 도메인을 확인하고 필요한 항목만 필터에 추가한 다음 정상 도메인도 계속 예상대로 매핑되는지 테스트합니다. 모든 도메인을 필터에 넣으면 간단해 보이지만 도메인 복원 방식을 통째로 바꾸게 됩니다. 그 결과 도메인 규칙으로 처리되던 연결이 실제 IP 주소와 스니핑에 의존하게 될 수 있습니다.

다음 순서로 검증하는 것이 좋습니다. 먼저 TUN을 끈 상태에서 시스템 프록시가 작동하는지 확인한 다음 TUN을 켜고 인터페이스와 라우트를 확인합니다. 이후 DNS 요청이 mihomo로 들어오는지 확인하고, 마지막으로 시스템 프록시를 따르지 않는 앱을 테스트하세요. 문제가 발생하면 반대 순서로 되돌립니다. 브라우저는 시스템 프록시를 계속 사용할 수 있으므로 브라우저에서 접속된다는 사실만으로 시스템 전체의 트래픽이 가로채졌다고 판단하지 마세요. 매핑 주소 조회 결과 하나만으로 모든 트래픽이 mihomo에 들어왔다는 뜻도 아닙니다.

도메인 스니핑과 규칙 보완

스니핑은 정보를 보완할 뿐 DNS를 대체하지 않습니다

연결이 mihomo에 들어올 때 대상 IP만 있고 사용할 수 있는 도메인 정보는 없을 수 있습니다. 앱이 자체 DNS를 사용하거나 투명 프록시를 통해 연결되거나, 프로그램이 캐시된 주소를 직접 쓰는 경우가 그렇습니다. 도메인 스니핑은 일부 프로토콜의 초기 데이터에서 호스트 정보를 추출해 mihomo가 도메인 규칙을 적용할 수 있도록 합니다. 이는 누락된 정보를 보완하는 기능이지 모든 트래픽에서 도메인을 찾아내는 기능은 아닙니다. 암호화된 연결의 모든 내용을 읽을 수 있다는 뜻도 아닙니다.

HTTP에는 호스트 필드가 포함될 수 있고, 조건이 맞으면 TLS 핸드셰이크에서 서버 이름을 확인할 수 있습니다. QUIC은 관련 핸드셰이크 내용을 인식하는 기능이 필요합니다. 클라이언트가 서버 이름을 숨기거나 mihomo에서 지원하지 않는 프로토콜을 사용하거나 식별에 필요한 데이터가 부족하면 스니핑에 실패할 수 있습니다. 이때는 주소 규칙이나 기본 경로로 연결이 처리되도록 하고, 스니핑 실패를 프록시 출구 사용 불가와 혼동하지 마세요. 프로토콜에서 노출되지 않은 정보는 포트 범위를 늘려도 얻을 수 없습니다.

제어 가능한 포트 범위부터 시작하세요

아래 설정은 HTTP, TLS, QUIC에서 흔히 사용하는 서비스 포트의 스니핑을 활성화하고, 스니핑한 도메인에 따라 목적지 주소를 바꾸는 동작은 비활성화합니다. 먼저 인식 결과를 확인한 후 대상 주소 조회를 추가로 가로챌지 결정하기에 적합합니다. 병합할 때 클라이언트가 sniffer 필드를 이미 생성했는지 확인해 같은 최상위 키가 중복되지 않도록 하세요. 명확한 웹 요청 한두 개만 테스트하고 로그에서 도메인 정보의 출처가 달라지는지 확인한 뒤 적용 범위를 넓히세요.

sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443

parse-pure-ip를 사용하면 도메인 정보가 없는 연결에서도 식별을 시도할 수 있어 일부 트래픽을 처리하는 데 도움이 됩니다. 다만 항상 성공하는 것은 아닙니다. force-dns-mapping은 해당 DNS 매핑 상황에서 스니핑을 계속 시도하는 설정이며, DNS 수신이나 전달 설정을 대신하지 않습니다. 필드 이름만 보고 모든 앱이 mihomo DNS를 강제로 사용한다고 생각하지 마세요. 요청이 DNS 처리 모듈에 들어오는지는 실제 네트워크 경로에 따라 달라집니다.

override-destination은 동작을 따로 검토한 뒤 사용해야 합니다. 활성화하면 mihomo가 스니핑한 도메인을 바탕으로 후속 목적지 처리를 바꿀 수 있습니다. 단순히 매칭 정보를 보완하는 데 그치지 않습니다. 특수한 DNS 조회, 고정 주소, 특정 진입 경로에 의존하는 앱은 기존 연결 경로가 바뀔 수 있습니다. 먼저 비활성화 상태로 두어 변수를 줄이세요. 서비스에 필요한지 확인하고 재조회와 라우팅에 미치는 영향을 이해한 후 도메인이나 프로토콜 범위를 좁혀 조정하세요.

도메인 정보의 출처를 비교해 스니핑이 필요한지 판단하세요

테스트 전에 대상 앱의 기존 연결을 끊고 새 연결을 만든 다음 연결 상세 정보에서 도메인, 목적지 주소, 적용된 규칙을 확인하세요. 스니핑을 켜도 이미 연결된 세션에서 핸드셰이크가 다시 시작되지는 않습니다. 연결이 이미 Fake-IP를 통해 도메인을 복원한 상태라면 스니핑을 켜기 전후에 규칙이 동일하게 적용되는 것이 정상입니다. 이런 경우 스니핑을 추가해도 얻는 이점이 적을 수 있으므로 모든 옵션을 무조건 활성화할 필요는 없습니다.

활성화 후 특정 서비스에 문제가 생기면 DNS 설정 전체를 바꾸기보다 해당 서비스에서 스니핑을 끈 상태와 비교하세요. mihomo에서 지원하는 도메인 제외 등의 범위 설정을 이용해 처리 대상을 좁힐 수 있지만, 예외는 실제로 관찰한 도메인에 맞춰야 합니다. 다른 설정을 통째로 복사하지 마세요. 강제 적용 범위가 너무 넓으면 더 많은 트래픽이 프로토콜 식별을 기다릴 수 있고, 제외 범위가 너무 넓으면 도메인 규칙이 필요한 연결도 주소 기반 분기로 돌아갈 수 있습니다.

포트만으로 프로토콜을 확정할 수는 없습니다. 일부 앱은 일반 웹 포트에서 자체 프로토콜을 사용하고, 비표준 포트에서 TLS를 제공하는 서비스도 있습니다. 포트 범위를 제한하면 처리 대상을 줄일 수 있지만 범위 안의 모든 연결을 식별할 수 있다는 보장은 없습니다. 사용자 정의 서비스는 실제 프로토콜을 확인한 다음 포함 여부를 결정하세요. 모든 포트를 추가해도 조사 범위만 늘어날 뿐, 핸드셰이크 데이터가 숨겨졌거나 프로토콜 인식이 지원되지 않는 문제는 해결되지 않습니다.

QUIC은 보통 UDP를 사용하며, 조건이 맞지 않으면 TCP로 전환하는 앱도 있습니다. 웹페이지가 열리는지만 확인하면 프로토콜이 바뀐 사실을 놓칠 수 있습니다. 연결 기록에서 실제로 사용된 전송 방식을 확인한 뒤 스니핑 결과와 적용 규칙을 비교하세요. 로그를 보기 좋게 만들려고 UDP 전체를 차단하지 마세요. 음성 통화, 실시간 통신과 일부 앱은 UDP에 의존할 수 있으므로 로그의 모양이 아니라 실제 서비스에 맞춰 처리해야 합니다.

스니핑 결과에는 개인정보 보호와 디버깅 범위도 고려해야 합니다. 추출된 도메인은 연결 기록이나 디버그 로그에 표시될 수 있으므로 스크린샷이나 문제 보고를 공유하기 전에 내부 서비스 이름이 포함되어 있는지 확인하세요. 일반적인 문제라면 규칙 유형, 정책 경로와 익명화한 대상 정보만으로도 충분한 경우가 많으며 전체 접속 기록을 올릴 필요는 없습니다. 로그가 많다고 문제가 자동으로 쉽게 해결되는 것은 아닙니다. 활성화 전후의 차이를 명확하게 기록하는 편이 데이터를 쌓아 두는 것보다 유용합니다.

로컬 오버라이드와 여러 구독 병합

최종 실행 설정을 기준으로 확인하세요

GUI 클라이언트는 구독 내용, 전역 설정과 로컬 오버라이드를 병합해 mihomo에 전달하는 경우가 많습니다. 편집 화면에 표시되는 것은 입력값이고, 실행 설정이 최종 결과입니다. 같은 DNS 필드가 구독과 클라이언트 설정에 모두 있다면 병합 순서에 따라 실제로 적용되는 값이 달라집니다. 문제를 진단하기 전에 클라이언트에서 제공하는 실행 설정 미리보기나 내보내기 기능을 찾아 mihomo가 실제로 받은 내용을 확인하세요. 나중에 덮어쓰일 파일만 반복해서 수정하지 않도록 주의해야 합니다.

역할별로 설정을 나누는 것이 좋습니다. 구독에는 프록시와 필요한 제공자 정보를 두고, 로컬 설정에는 업무별 그룹, 규칙 우선순위, DNS, 기기별 설정을 관리하세요. 기기별 설정에는 수신 주소와 포트, TUN, 컨트롤러가 포함되며 서로 다른 운영체제에서 그대로 동기화하기에는 적합하지 않습니다. 동기화 전에 재사용할 수 있는 설정 의도와 현재 기기에만 해당하는 환경값을 구분하세요. 파일을 가져올 수 있다고 해서 다른 기기에서도 라우팅과 권한이 똑같이 작동하는 것은 아닙니다.

모든 병합 도구의 처리 방식이 같다고 가정하지 마세요

맵, 배열, 스칼라는 클라이언트에 따라 병합 방식이 다를 수 있습니다. 맵은 계층별로 병합되기도 하고 전체가 교체되기도 하며, 배열은 기존 항목 뒤에 추가되거나 앞에 삽입되거나 완전히 덮어쓰일 수 있습니다. mihomo가 클라이언트마다 다른 병합 방식을 통일해 주지는 않습니다. 특히 rules 배열에서 로컬 예외가 기존 설정의 MATCH 뒤에 추가되면 해당 예외는 적용되지 않습니다. 화면에 저장됐다고 표시되는지만 보지 말고 최종 규칙 순서를 반드시 확인하세요.

아래는 오버라이드 기능으로 적용할 수 있는 부분 설정 예제입니다. 로컬 수신 주소와 규칙 모드를 고정하고 선택 상태를 저장하도록 요청합니다. 모든 클라이언트에서 사용할 수 있는 공통 오버라이드 파일 형식은 아니므로 현재 클라이언트가 지원하는 YAML 병합 메뉴에 필드를 넣으세요. 메뉴에서 스크립트나 전용 형식을 요구한다면 해당 규칙을 따르고 YAML을 스크립트 편집기에 붙여 넣지 마세요. profile의 적용 여부도 재시작 후 실제 상태로 확인해야 합니다.

mixed-port: 7890
allow-lan: false
mode: rule

profile:
  store-selected: true
  store-fake-ip: true

YAML의 같은 맵 안에 중복 키가 있는 것은 제거해야 할 문제입니다. 일부 파서는 오류를 보고하고, 일부는 나중에 나온 값을 유지할 수 있으므로 이런 차이를 덮어쓰기 방법으로 이용해서는 안 됩니다. 들여쓰기에는 공백을 사용하고 특수한 문법으로 해석될 수 있는 문자열은 따옴표로 감싸세요. 수정 후에는 먼저 문법 검사를 진행한 다음 실행 환경에 적용하세요. YAML 파싱에 성공했다는 것은 문법이 맞다는 뜻일 뿐, 정책 참조와 파일 경로, 규칙 동작은 별도로 확인해야 합니다.

여러 구독은 출처를 분리한 뒤 이름과 참조를 정리하세요

여러 소스에 같은 이름의 프록시, 프록시 그룹, 제공자가 포함될 수 있습니다. 그대로 이어 붙이면 이름이 충돌하거나 규칙이 의도하지 않은 대상을 참조할 수 있습니다. 소스별로 구분되는 제공자 네임스페이스를 만들고 로컬 프록시 그룹에서 use로 구성원을 선택하는 방법이 더 안전합니다. 프록시 이름을 변경해야 한다면 관련된 참조도 모두 함께 수정하세요. 목록에 표시되는 이름만 바꾸고 그룹 안의 참조를 그대로 두면 시작 오류가 발생하거나 구성원이 비어 있을 수 있습니다.

여러 소스를 병합한다고 DNS와 규칙 설정 전체를 여러 벌 복사할 필요는 없습니다. 최종 설정을 결정할 소스를 먼저 정하고 나머지는 프록시 데이터를 제공하는 입력으로 취급하세요. 구독에 반드시 보존해야 할 전용 규칙이 있다면 별도로 검토해 명확한 위치에 배치하고 로컬 정책 전체를 덮어쓰게 하지 마세요. 소스가 늘어날수록 삭제 및 비활성화 방법도 분명해야 합니다. 제공자를 비활성화했을 때 이를 참조하는 그룹이 계속 작동하는지 미리 판단할 수 있어야 합니다.

터미널 환경에서는 배포 전에 mihomo의 설정 테스트 기능을 사용할 수 있습니다. 명령에 포함된 디렉터리는 실제 설정 작업 디렉터리로 바꿔야 합니다. 아래 명령은 현재 디렉터리에 설정과 관련 파일이 있는 경우에 사용할 수 있습니다. 테스트가 실제 네트워크 접속을 대신하지는 않지만 필드, 참조, 파일 로드 문제를 미리 찾는 데 도움이 됩니다. GUI 클라이언트에 설정 검사 기능이 있다면 먼저 검사한 뒤 다시 로드하세요. 아직 검증하지 않은 설정을 바로 시작 기본값으로 적용하지 마세요.

mihomo -t -d . -f ./config.yaml

구독이 자동 업데이트된 뒤에는 최종 설정에서 수신 포트, 규칙 앞부분, 마지막 기본 규칙, 주요 그룹 구성원을 표본으로 확인하세요. 이 항목들은 병합 관계가 바뀌었는지 드러나기 쉽습니다. 업데이트 후 문제가 생기면 직전의 정상 입력으로 되돌린 뒤 생성 결과를 비교하세요. 자동 업데이트를 즉시 완전히 끄고 방치하지 마세요. 어떤 도메인 예외를 추가했는지, 어떤 그룹의 구성원 출처를 바꿨는지처럼 이해할 수 있는 변경 기록을 남기면 이후 문제 진단에 도움이 됩니다.

기기 간 동기화에는 필요한 파일만 포함하고 로그, 캐시, 기기에서 생성한 임시 설정은 제외하세요. 구독 주소와 프록시 인증 정보는 민감한 데이터이므로 공개 저장소에 넣지 마세요. 자세한 방법은 여러 기기 설정 동기화를 참고하세요. 포트가 충돌하면 로컬 오버라이드뿐 아니라 시스템 프록시와 앱 설정도 함께 조정해야 합니다. 구체적인 진단 절차는 포트 점유 문제 해결을 확인하세요.

외부 컨트롤러와 검증 절차

컨트롤러 포트와 프록시 포트를 구분하세요

external-controller는 패널에서 상태를 확인하고 정책을 바꾸거나 관리 작업을 수행할 수 있도록 mihomo 관리 인터페이스를 제공합니다. 일반 프록시 트래픽을 받는 mixed-port를 대신하지는 않습니다. 브라우저 프록시 설정에는 프록시 수신 포트를 입력하고, 패널 연결 설정에는 컨트롤러 주소를 입력하세요. 두 포트를 혼동하면 브라우저에서 인터넷에 접속할 수 없거나 패널 연결에 실패할 수 있지만, mihomo 자체는 계속 실행 중일 수 있습니다.

컨트롤러 인터페이스는 실제 네트워크 동작에 영향을 줄 수 있으므로 우선 로컬 루프백 주소에만 바인딩하세요. 아래 설정은 로컬에서만 사용하는 기본 환경의 로컬 컨트롤러 주소와 패널 디렉터리를 보여 줍니다. 패널 파일은 mihomo 작업 디렉터리의 ui 폴더에 미리 넣어야 하며, 이 경로를 지정한다고 웹페이지가 자동 생성되지는 않습니다. 클라이언트에 컨트롤러와 패널 관리 기능이 내장되어 있다면 중복으로 수신 포트를 만들지 말고 해당 기능을 우선 사용하세요.

external-controller: 127.0.0.1:9090
external-ui: ./ui

루프백 수신은 원격 접속을 제한하지만 보안 설정이 모두 끝났다는 뜻은 아닙니다. 로컬 컴퓨터의 다른 프로세스는 해당 포트에 접근할 수 있습니다. 클라이언트가 지원하는 방식으로 컨트롤러 전용 secret을 설정하고 패널의 연결 설정에 같은 값을 입력하세요. 실제 인증 키를 공개 파일이나 예제에 쓰지 말고, 인증 정보가 포함된 패널 링크를 다른 사람에게 보내지 마세요. 프록시 계정 비밀번호를 컨트롤러 키로 사용해서도 안 됩니다. 변경 후 패널에 다시 연결해 이전 인증 정보가 더 이상 유효하지 않은지 확인하세요.

인터페이스 응답을 먼저 확인한 뒤 브라우저 패널을 점검하세요

패널이 열리지 않으면 먼저 mihomo가 실행 중인지, 컨트롤러 포트가 수신 중인지 확인한 다음 정적 웹페이지 디렉터리를 살펴보세요. 인증을 사용하지 않는 기본 로컬 환경에서는 아래 명령으로 설정 인터페이스가 응답하는지 확인할 수 있습니다. 이미 인증을 활성화했다면 클라이언트에서 지원하는 진입 방법을 사용하거나 로컬 요청에 인증 정보를 제공하세요. 테스트를 위해 컨트롤러를 모든 네트워크 인터페이스에 임시로 노출하지 마세요. 요청이 거부된 경우와 포트에 연결조차 할 수 없는 경우는 서로 다른 문제입니다.

curl --noproxy '*' http://127.0.0.1:9090/configs

인터페이스에는 접속되지만 패널이 작동하지 않는다면 패널에 저장된 컨트롤러 주소, 인증 정보와 브라우저 오류를 확인하세요. HTTPS로 열린 웹페이지에서 로컬 HTTP 인터페이스에 연결하면 혼합 콘텐츠나 브라우저의 로컬 네트워크 접근 제한이 발생할 수 있습니다. 다른 출처에서 연결하는 경우 컨트롤러의 출처 정책도 관련될 수 있습니다. 일반적인 해결책이라며 모든 출처를 허용하지 말고, 클라이언트 내장 패널이나 동일 출처의 로컬 페이지를 우선 사용한 뒤 필요한 출처만 허용하세요.

원격 관리를 위해 수신 주소를 모든 인터페이스로 바꾸는 것만으로 설정을 마쳐서는 안 됩니다. 인증, 네트워크 접근 범위, 암호화된 전송, 방화벽 규칙을 함께 설계해야 합니다. 제어된 로컬 포워딩이나 관리 네트워크를 통해 작업할 수 있다면 컨트롤러 인터페이스를 공용 네트워크에 직접 공개할 필요가 없는 경우가 많습니다. 패널 페이지가 열리더라도 관리 연결이 보호된 것은 아닙니다. 페이지와 인터페이스가 서로 다른 주소나 전송 방식을 사용할 수 있으므로 각각 확인해야 합니다.

연결 기록으로 검증을 마무리하세요

패널은 새 연결 하나가 처리되는 과정을 추적할 때 가장 유용합니다. 출발 앱, 대상 도메인이나 주소, 적용 규칙, 정책 경로와 최종 출구를 확인하세요. 검증할 때는 명확한 대상을 하나 정하고 새 요청을 한 번 발생시켜 여러 연결이 동시에 오가는 상황에서 추측하지 않도록 합니다. 그룹 이름이 보인다고 바로 실제 출구인 것은 아니므로 그룹 안의 선택 항목까지 확인하세요. 규칙은 올바르게 적용됐는데 연결이 실패한다면 규칙 순서를 계속 바꾸기보다 실제 프록시와 DNS 조회를 확인해야 합니다.

패널에 표시되는 정책 선택은 설정 파일의 기본 구성원과 다를 수 있습니다. 선택 상태 저장이 활성화되어 있으면 설정을 다시 불러와도 이전 선택이 복원될 수 있고, 그룹 안의 순서를 바꿔도 현재 출구가 달라지지 않을 수 있습니다. 문제를 진단할 때는 패널의 실제 상태를 기록한 뒤 직접 선택을 변경하세요. 설정을 다시 불러와도 기존 연결이 모두 종료되는 것은 아니므로 새 연결을 기준으로 테스트해야 합니다. 계속 실행되어야 하는 앱은 연결을 직접 종료할 때 작업이 중단되는지 먼저 확인하세요.

다음 순서로 전체 점검을 진행하는 것이 좋습니다. 설정 문법과 참조를 테스트하고, 혼합 프록시 포트와 컨트롤러 포트가 정상적으로 수신되는지 확인합니다. 일반 모드에서 연결을 만든 다음 DNS 조회가 예상한 모듈로 들어오는지 살펴보고 규칙이 올바르게 적용되는지 확인하세요. 프록시 그룹을 펼쳐 실제 출구를 확인한 뒤 필요할 때 TUN과 스니핑을 활성화합니다. 모듈을 하나 추가할 때마다 결과를 기록하면 문제가 되돌아왔을 때 모든 설정을 다시 바꾸지 않고 가장 최근에 정상 작동한 상태로 돌아갈 수 있습니다.

문제 기록은 간결하면서도 필요한 정보를 포함해야 합니다. 운영체제, 클라이언트 이름, TUN 사용 여부, 문제가 발생한 대상 유형, 적용 규칙, 주요 오류 메시지를 적으세요. 전체 구독, 인증 정보, 모든 접속 기록은 공개하지 마세요. 기본적인 문제는 자주 묻는 질문을 참고하세요. 연결은 됐지만 웹페이지가 열리지 않는다면 단계별 점검 목록에 따라 시스템 프록시부터 DNS와 방화벽까지 확인할 수 있습니다. 설정을 유지 관리하기 쉽다는 것은 연결이 왜 해당 경로로 처리되는지 설명하고, 실패했을 때 어디까지 되돌릴지 분명히 알 수 있다는 뜻입니다.