설정 필드config.yaml

mihomo 설정 필드 가이드

먼저 설정을 가져오고 트래픽 가로채기를 켠 다음 연결을 확인하세요. 입문 가이드를 따라 진행하면 됩니다. 이미 연결에 성공했고 특정 키를 어느 단계에 넣어야 하는지 궁금하거나, 구독을 업데이트한 뒤 사용자 규칙을 다시 적용하려면 이 안내서를 참고하세요. 예제는 단독으로 실행할 수 있는 직결 설정부터 시작합니다. 뒤에 나오는 설정 조각은 각 장에 따라 교체하거나 추가하세요. 같은 최상위 키를 여러 번 붙여 넣으면 안 됩니다.

YAML 구조와 최소 설정

매핑, 시퀀스, 스칼라 구분하기

설정 파일의 최상위에는 필드가 나열됩니다. 콜론 왼쪽은 키이고, 오른쪽에는 값이나 하위 구조가 올 수 있습니다. 포트 번호, 모드 이름, 불리언 스위치는 단일 값입니다. dns는 하위 매핑이고, proxies, proxy-groups, rules는 순서가 있는 목록입니다. 노드 목록의 각 항목은 다시 매핑이고, 규칙 목록의 각 항목은 보통 한 줄짜리 문자열입니다. 노드와 규칙이 모두 하이픈으로 시작한다고 해서 노드 속성을 여러 목록 항목으로 나누어 쓰면 안 됩니다. YAML 문법상 유효할 수는 있어도, 코어가 읽어야 하는 구조와 달라집니다.

공백으로 들여쓰고 각 단계에 공백 두 칸을 쓰면 구조를 맞추기 쉽습니다. 탭 문자는 사용하지 마세요. 콜론 뒤 공백과 따옴표 안의 콜론을 구분해야 합니다. 값에 콜론과 공백이 함께 들어간 이름은 값 전체를 따옴표로 묶으세요. 그렇지 않으면 파서가 다른 키-값 쌍으로 오해할 수 있습니다. 주석은 따옴표로 묶이지 않았고 앞에 공백으로 구분된 샵 기호가 있을 때 시작합니다. 이름에 샵 기호나 앞자리 0이 포함되면 값을 따옴표로 묶으세요. 포트는 정수로, 스위치는 true 또는 false로 작성하고 모든 값을 무조건 문자열로 바꾸지는 마세요.

단독 실행 가능한 직결 설정

config.yaml
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []
proxy-groups:
  - name: LOCAL
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,LOCAL

이 설정은 구독, 지리 데이터베이스, 원격 규칙에 의존하지 않습니다. 요청은 로컬 혼합 포트로 들어오고, 마지막 규칙에 따라 LOCAL로 전달됩니다. 그룹에는 유일한 아웃바운드인 DIRECT가 지정되어 있습니다. 여기서 직결이란 로컬 코어를 거치되 원격 프록시를 거치지 않는다는 뜻입니다. 이 설정으로 원격 서비스, 인증 정보, 속도 측정 주소의 영향을 먼저 배제할 수 있습니다. 이 설정도 시작되지 않으면 실행 디렉터리, 설정 파일 권한, 포트 사용 여부부터 확인하세요. 더 긴 구독 파일로 바꾸면 문제 범위만 넓어집니다.

최상위 키의 작성 위치는 실행 순서를 뜻하지 않습니다. rules를 파일 첫 줄로 옮겨도 규칙이 노드 초기화보다 먼저 실행되지는 않습니다. 실제 순서가 중요한 것은 규칙이 위에서 아래로 매칭되는 경우나 수동 선택 그룹에 멤버가 표시되는 순서처럼 목록 내부입니다. 참조는 위치가 아니라 이름을 기준으로 합니다. 예제에서 LOCAL은 규칙과 그룹 정의에서 정확히 같은 이름이어야 합니다. 편집할 때는 편집기에서 이름을 검색해 참조된 위치를 모두 확인한 뒤 한꺼번에 바꾸는 편이 좋습니다. 표시 이름만 바꾸고 해당 그룹을 가리키는 규칙을 수정하지 않으면 설정 참조가 끊깁니다.

빈 값, 중복 키, 오류 행 번호

proxies: []는 빈 목록을 명시합니다. 하위 항목 없이 proxies:만 쓰면 보통 빈 값으로 해석됩니다. 빈 값, 빈 목록, 키 자체를 생략하는 것은 서로 다르며 덮어쓰기에서 차이가 특히 분명합니다. 파일 끝에 rules:를 다시 추가해 앞에 있는 목록에 규칙을 덧붙이지 마세요. 파서에 따라 중복 키를 거부하거나 값 하나만 남길 수 있습니다. 기존 목록을 늘리려면 원래 키 아래에 항목을 추가하거나 클라이언트가 제공하는 목록 병합 기능으로 명시적으로 추가하세요.

문제 해결은 첫 번째 오류부터 시작하세요. 특정 행에서 예상한 콜론을 찾을 수 없다는 오류가 나더라도, 원인은 앞 행에서 따옴표를 닫지 않았거나 상위 블록의 들여쓰기가 빠진 것일 수 있습니다. 오류 행의 앞뒤 몇 줄을 먼저 살펴보세요. 문법 분석을 통과하면 코어가 노드 유형, 대상 이름, 필드 값을 확인합니다. 편집기에서 구문 강조가 된다고 코어가 설정을 불러올 수 있는 것은 아니며, 설정 로드에 성공해도 트래픽이 프록시로 전달된다는 뜻은 아닙니다. 실행 가능한 기본 설정을 따로 보관하고 이후에는 한 번에 필드 블록 하나만 수정하세요. 구조가 잘못된 경우와 구조는 맞지만 네트워크 경로가 연결되지 않는 경우를 구분하기 쉽습니다.

다운로드한 것이 구독 주소, 인코딩된 텍스트, 클라이언트 전용 공유 링크라면 먼저 가져오기 메뉴에서 형식을 확인하세요. 확장자만 바꿔 코어에 넘기면 안 됩니다. 다른 유형의 파일로는 payload만 있거나 노드 목록만 들어 있는 것이 있습니다. 이런 파일은 다른 필드에서 참조하는 리소스이지 완전한 설정이 아닙니다. 파일 앞부분의 구조를 확인한 다음 클라이언트에서 새 설정을 만들지, 하위 매핑을 교체할지, 프로바이더 소스로 등록할지 결정하세요. 화면에 표시되는 설정 이름과 디스크의 파일 경로는 다를 수 있으므로 문제를 해결할 때 실제로 편집 중인 파일을 확인해야 합니다.

공통 필드: 리스닝 포트와 실행 모드

요청 진입점을 정한 다음 아웃바운드를 선택하세요

리스닝 포트는 애플리케이션이 요청을 어디로 보낼지 정하고, 실행 모드는 코어가 요청을 받은 뒤 어디로 보낼지 정합니다. 둘은 서로 다른 설정입니다. 일반적으로 쓰는 mixed-port는 HTTP 프록시와 SOCKS 연결을 모두 받아 로컬 애플리케이션에 진입점을 하나만 설정하면 될 때 적합합니다. port는 HTTP 프록시 진입점, socks-port는 SOCKS 진입점을 각각 제공합니다. 호출 방식을 분리해야 할 때만 사용하세요. 두 리스너에 같은 포트를 지정해도 자동으로 포트를 공유하지는 않습니다. 클라이언트가 코어의 포트를 할당한다면 시작 로그와 화면에 표시된 실제 값을 기준으로 하세요.

필드기능확인할 항목
mixed-portHTTP와 SOCKS가 함께 사용하는 인바운드포트가 비어 있는지 확인하고 애플리케이션 설정이 실제 리스닝 주소를 가리키는지 확인
allow-lan다른 LAN 기기에서 프록시 진입점을 사용할 수 있는지로컬에서만 쓴다면 끄기
mode규칙, 전역 또는 직결 모드 선택규칙을 확인할 때는 먼저 rule로 전환
log-level로그 상세 수준 조정평소에는 info를 사용하고 문제를 찾을 때만 잠시 상세 수준을 높이기
external-controller애플리케이션 프록시 진입점이 아닌 제어 API필요할 때만 활성화하고 신뢰할 수 있는 접근 범위로 제한

로컬 애플리케이션은 보통 루프백 주소 127.0.0.1와 혼합 포트를 사용합니다. 제어 API 주소를 시스템 프록시에 입력하지 마세요. 둘 다 로컬 포트를 사용할 수 있지만 제공하는 서비스는 완전히 다릅니다. 제어 API는 실행 상태를 확인하고 설정을 변경할 수 있으므로 외부에 공개하지 않아야 합니다. 로컬에서만 사용할 경우 루프백 주소에 바인딩하고 클라이언트 방식에 따라 접근 인증 정보를 관리하세요. 다른 기기에서 로컬 프록시를 사용하려면 allow-lan, 리스닝 주소, 방화벽, 접근 제어를 각각 확인하세요. 로컬에서 연결된다고 같은 네트워크의 다른 기기도 연결되는 것은 아닙니다.

세 가지 모드와 화면 상태

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

rule은 규칙 순서에 따라 아웃바운드를 결정합니다. global은 전역 정책에서 선택한 아웃바운드로 보내며 사용자 지정 분할 규칙을 하나씩 적용하지 않습니다. direct는 코어가 받은 요청을 직결로 보냅니다. 직결로 전환해도 클라이언트가 종료되는 것은 아니며, 시스템 프록시나 가상 네트워크 인터페이스가 계속 트래픽을 받을 수 있습니다. 전역 또는 직결 모드로 문제를 확인할 때는 원래 모드와 선택을 기록하고 테스트 후 복원하세요. 세 경로의 차이는 규칙·전역·직결 모드 안내의 사례를 참고하세요.

설정 파일의 mode는 파일에 지정된 값이며, 현재 화면의 상태와 다를 수 있습니다. 클라이언트가 시작 후 이전 선택을 복원하거나 중간 설정을 만들어 코어에 전달할 수도 있습니다. 파일을 수정했는데도 전역 모드로 작동한다면 방금 편집한 파일이 실제로 로드되는지, 화면에서 여전히 전역 모드를 선택했는지 확인하세요. 반대로 화면에서 모드를 임시로 바꿔도 원본 파일에 저장되지 않을 수 있습니다. 구독 업데이트와 재시작 후에도 변경 사항을 유지하려면 실행 상태만 바꾸지 말고 클라이언트가 지원하는 영구 설정 경로를 찾으세요.

포트 리스닝 성공이 시스템 트래픽 가로채기 성공을 뜻하지는 않습니다

시스템 프록시는 애플리케이션이 시스템 설정을 읽어야 하며, 보통 브라우저처럼 프록시를 지원하는 프로그램에 적합합니다. 가상 네트워크 인터페이스 모드는 시스템 라우팅을 통해 일치하는 트래픽을 받으므로 클라이언트 설정뿐 아니라 권한, 라우팅 충돌, 이름 확인도 고려해야 합니다. 두 옵션을 함께 켠다고 항상 더 많은 트래픽을 처리하는 것은 아닙니다. 특정 애플리케이션이 연결되지 않으면 우선 한 가지 방식만 켜고 진입점, 대상, 결과를 기록한 다음 다른 방식으로 바꿔 비교하세요. 작동 방식의 차이는 TUN과 시스템 프록시 비교에서 확인할 수 있습니다.

기기마다 권한 설정이 다르므로 데스크톱의 시스템 프록시 설정을 휴대폰에 그대로 적용할 필요는 없습니다. 처음 설치한다면 다운로드 페이지에서 플랫폼에 맞는 패키지를 고르세요. 그래픽 인터페이스를 먼저 사용해 보고 싶다면 우선 추천 클라이언트인 Clash Plus부터 시작하고, 세부 기능은 클라이언트에서 실제로 지원하는지 확인하세요. 포트가 사용 중이어도 정체를 알 수 없는 프로세스를 바로 종료하지 마세요. 다른 클라이언트나 이전 코어가 실행 중인지 먼저 확인하세요. 새 설정에서 포트를 바꿨다면 브라우저, 터미널, 시스템에 남아 있는 이전 포트 설정도 함께 바꿔야 합니다.

애플리케이션 하나만 확인한다면 전체 시스템 설정을 바꾸는 것보다 해당 애플리케이션이 혼합 포트를 직접 사용하도록 설정하는 편이 되돌리기 쉽습니다. 이 단계에서 코어 진입점, 규칙, 아웃바운드의 전체 경로를 확인할 수 있습니다. 성공하면 시스템 트래픽 가로채기를 켜고, 결과가 달라진다면 애플리케이션 설정이나 시스템 라우팅으로 범위를 좁히세요. 로그 수준을 잠시 높였다면 명확한 요청 하나만 다시 실행하세요. 인바운드, 대상, 아웃바운드를 확인한 뒤 평소 수준으로 되돌리세요. 여러 요청을 동시에 보내면 유용한 기록을 찾기 어려워집니다.

DNS: 업스트림, 도메인 정책, 강화 모드

DNS 조회와 연결 요청은 따로 살펴보기

도메인 조회는 “이 이름에 해당하는 주소가 무엇인가”에 답하고, 연결 규칙은 “이번 접속을 어떤 아웃바운드로 보낼 것인가”를 결정합니다. 접속 중 서로 영향을 주지만 같은 설정은 아닙니다. dns.enable은 코어의 DNS 모듈을 켭니다. 이 스위치 하나만으로 시스템의 모든 DNS 조회를 가로채지는 않습니다. 브라우저 자체의 암호화 DNS, 시스템 캐시, 클라이언트에 설정된 DNS 가로채기가 요청 경로를 바꿀 수 있습니다. 문제를 해결하기 전에 누가 조회를 시작하는지, 어떤 주소를 조회하는지, 코어가 도메인 이름을 받는지 이미 해석된 주소를 받는지 확인하세요.

dns:
  enable: true
  enhanced-mode: redir-host
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.google/dns-query
  nameserver-policy:
    '+.example.org':
      - 1.1.1.1

예제에서는 암호화된 업스트림으로 일반 도메인을 처리하고, example.org와 그 하위 도메인은 별도의 리졸버로 보냅니다. default-nameserver는 DNS 업스트림 자체의 도메인 이름을 조회할 때 사용하며 보통 IP 주소로 지정합니다. 일반 도메인 조회가 실패했을 때 사용하는 범용 대체 목록은 아닙니다. 현재 네트워크에서 예제의 공용 DNS 서비스에 접근할 수 없다면 네트워크가 허용하고 직접 연결할 수 있는 업스트림으로 바꿔 테스트하세요. 정책 적용 여부를 확인하려면 요청 두 개를 비교하세요. 하나는 정책 범위에 포함하고 다른 하나는 범위 밖에 둡니다.

클라이언트 내장 DNS와 시스템의 기본 설정 DNS는 같은 설정이 아닙니다. 애플리케이션이 코어의 DNS 리스너에 직접 질의해야 한다면 dns.listen을 별도로 설정한 다음 애플리케이션이 실제로 해당 주소로 질의하도록 하세요. 리스너를 설정한다고 시스템의 기존 DNS 질의가 자동으로 이동하지는 않습니다. 특히 공유 네트워크에서는 편의를 위해 모든 인터페이스에 바인딩하지 마세요. 문제를 확인할 때는 지정한 리졸버에 직접 질의한 뒤 원래 애플리케이션에서 접속을 재현하세요. 두 진입점의 결과를 같은 테스트 결과로 혼동하지 않도록 합니다.

redir-host와 fake-ip 중 무엇을 선택할까

redir-host는 실제 주소를 반환하므로 호환성 문제를 확인할 때 좋은 출발점입니다. fake-ip는 처리 대상 도메인에 합성 주소를 할당합니다. 이후 코어가 해당 주소로 연결 요청을 받으면 매핑을 통해 도메인을 찾아 규칙을 적용할 수 있습니다. 합성 주소는 대상 서버의 공인 IP가 아닙니다. 정적 호스트 파일에 복사하거나 원격 서비스의 주소가 바뀌었는지 판단하는 데 사용하지 마세요. 애플리케이션이 해당 트래픽 가로채기 경로를 우회하거나 매핑 정보가 없는 다른 기기에 합성 주소를 전달하면 조회는 성공해도 대상에 연결되지 않을 수 있습니다.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.local'
  nameserver:
    - 1.1.1.1

이 설정 조각은 앞서 나온 dns 하위 매핑 전체를 교체합니다. 필터 항목은 지정한 도메인에 합성 주소를 할당하지 않도록 합니다. 기기 검색이나 실제 주소가 필요한 서비스가 대표적인 사용 사례입니다. 필터를 적용한다고 도메인이 직결 규칙을 따르는 것은 아니며 멀티캐스트 조회 기능이 생기는 것도 아닙니다. LAN 서비스가 여전히 열리지 않으면 서비스 이름을 조회할 수 있는 실제 로컬 경로가 있는지, 반환된 주소가 올바른 서브넷으로 라우팅되는지 확인하세요. 실제 주소 모드로 전환해 비교할 때는 애플리케이션이 이전 주소를 저장했을 수 있으므로 필요하면 애플리케이션을 재시작하고 다시 조회하세요.

일반 도메인과 노드 도메인 조회 분리하기

아웃바운드 노드의 server에 도메인을 지정했다면 노드가 연결되기 전에 해당 이름도 조회해야 합니다. 노드 도메인에는 proxy-server-nameserver를 지정할 수 있습니다. 규칙에 따라 DNS 경로를 정한다면 특히 노드 연결 자체에 의존하지 않는 조회 경로를 확보해야 합니다. 그렇지 않으면 요청이 노드를 거쳐야 하는데 노드는 그 요청이 완료되어야 주소를 얻는 순환이 발생합니다. 모든 노드가 동시에 시간 초과되고 IP 주소는 직접 연결되지만 도메인으로 지정한 노드는 모두 실패한다면 노드 멤버를 전부 삭제하고 다시 만들기 전에 이 의존 관계부터 확인하세요.

같은 이름이 여러 주소를 반환한다고 해서 반드시 오류는 아닙니다. 주소는 지역, 캐시, 레코드 유형에 따라 달라질 수 있습니다. 보다 정확하게 확인하려면 테스트 조건을 고정하세요. 같은 클라이언트, 같은 트래픽 가로채기 방식, 같은 도메인을 유지하고 조회 진입점, 반환된 레코드 유형, 애플리케이션이 실제로 연결한 주소를 기록합니다. IPv6 결과만 실패한다면 시스템과 아웃바운드 경로가 모두 해당 주소 패밀리를 지원하는지 확인하세요. DNS 옵션을 끄면 반환 내용은 달라질 수 있지만, 네트워크에 해당 경로가 있는지 확인하는 작업을 대신하지는 못합니다.

프록시 노드: 프로토콜, 원격 주소, 프로바이더

노드는 아웃바운드이며 로컬 리스너가 아닙니다

proxies는 참조할 수 있는 아웃바운드 목록을 정의합니다. 각 노드의 name은 설정에서 사용하는 참조 이름이고, type은 이후 필드를 어떤 프로토콜로 해석할지 결정합니다. server와 port는 실제로 연결할 원격 서버를 지정합니다. 노드 포트는 로컬 mixed-port와 관련이 없습니다. 클라이언트의 로컬 포트를 노드 항목에 복사하면 연결이 안 되거나, 자기 자신을 가리켜 순환이 생길 수 있습니다. 설정에 넣기 전에 제공업체에서 프로토콜, 주소, 포트를 확인하세요. 노드 이름의 지역명이나 메모를 보고 필드를 추측하면 안 됩니다.

proxies:
  - name: LAB-SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false

proxy-groups:
  - name: LAB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - MATCH,LAB

이 필드 블록은 직결 기본 설정의 같은 이름을 가진 최상위 필드 세 개를 교체할 수 있습니다. 로컬에서 제어하는 SOCKS5 서비스가 1080 포트를 리스닝해야 합니다. 서비스가 없다면 그룹의 DIRECT와 비교하는 것만 가능합니다. 테스트 전에 이 서비스가 현재 코어의 다른 진입점이 아닌지, 트래픽을 다시 현재 코어로 보내지 않는지 확인하세요. 이 노드에서 UDP를 끈 것은 최초 테스트에서 TCP만 확인하기 위해서입니다. 애플리케이션이 UDP를 명시적으로 필요로 한다면 프로토콜, 노드 설정, 서버 지원, 트래픽 진입 방식이 모두 이를 지원해야 합니다.

노드 이름은 한국어로 지어도 되지만 문제 해결을 위해서는 짧고 안정적이며 검색하기 쉬운 이름을 권장합니다. 노드끼리 이름이 같거나 노드와 그룹 이름이 겹치면 참조가 모호해지고, 일부 설정은 코어에서 거부됩니다. 같은 서버를 프로토콜이나 포트를 달리해 여러 번 등록한다면 목록 순서로 구분하지 말고 각각 다른 이름을 지정하세요. 구독 업데이트 때 표시 이름이 자주 바뀐다면 많은 규칙이 개별 이름에 직접 의존하게 하지 마세요. 안정적인 로컬 그룹을 규칙에 연결하고 그룹 멤버를 관리하는 편이 좋습니다.

프로토콜 간 매개변수를 그대로 복사하지 마세요

프로토콜마다 인증 필드가 다릅니다. 예를 들어 SOCKS5는 서버 설정에 따라 사용자 이름과 비밀번호를 입력할 수 있고, Shadowsocks 노드는 서버 정보를 기준으로 암호화 방식과 비밀번호를 지정합니다. 필드를 채우려고 한 프로토콜의 인증 블록을 다른 프로토콜에 그대로 복사하면 안 됩니다. TLS를 사용하는 노드는 서버가 요구하는 이름, 전송 방식, 관련 옵션도 확인하세요. 서버 주소와 TLS에서 상대를 식별하는 이름은 서로 다를 수 있습니다. 핸드셰이크가 실패하면 인증서 검증을 완화해 장기적으로 해결하려 하지 말고 프로토콜과 서버 정보를 먼저 확인하세요.

아웃바운드 연결이 되지 않는다면 세 가지 신호를 구분하세요. 노드 도메인 조회 실패는 보통 핸드셰이크 전에 오류가 발생합니다. 대상 포트에 접근할 수 없으면 연결 거부나 시간 초과가 나타납니다. 프로토콜이나 인증이 맞지 않으면 연결이 성립한 뒤 실패하는 경우가 많습니다. 포트에서 응답을 받았다는 것은 어떤 리스닝 서비스에 도달했다는 뜻일 뿐, 해당 서비스가 현재 프로토콜을 승인한다는 뜻은 아닙니다. 추가 전송 계층을 사용하는 노드는 해당 경로나 서비스 식별자도 확인해야 합니다. 서버가 같은 설정을 사용한다고 명시한 경우에만 해당 옵션이 유효합니다.

교체 가능한 노드 목록을 프로바이더에 맡기기

proxy-providers:
  lab:
    type: file
    path: ./providers/lab.yaml

proxy-groups:
  - name: LAB
    type: select
    use:
      - lab
    proxies:
      - DIRECT

rules:
  - MATCH,LAB

로컬 파일 프로바이더를 사용하면 그룹 정의와 노드 소스를 분리할 수 있습니다. 먼저 코어의 작업 디렉터리에 providers/lab.yaml을 준비하세요. 파일에는 앞의 예제에서 proxies 블록만 있으면 됩니다. 기본 설정에는 공통 필드를 남겨 두고 위 블록으로 그룹과 규칙을 정의하세요. 상대 경로는 코어 작업 디렉터리를 기준으로 하며 GUI에서 방금 연 YAML 파일의 위치와 다를 수 있습니다. 경로 오류가 발생하면 클라이언트가 코어에 지정한 실제 디렉터리와 코어 실행 사용자에게 파일 읽기 권한이 있는지 확인하세요.

원격 프로바이더에서 가져오는 내용도 코어가 예상하는 형식이어야 합니다. 임의의 공유 링크를 노드 목록 주소로 사용할 수는 없습니다. 업데이트에 실패하면 먼저 가져오기 과정에서 오류가 났는지, 가져온 내용을 파싱할 수 없는지 구분하세요. 후자의 경우 서버가 일반 웹페이지를 반환했을 수 있습니다. 문제 해결 자료를 공유할 때는 오류 유형과 필드 구조만 남기고 구독 주소, 인증 정보, 연결 로그의 불필요한 개인 주소는 지우세요. 개념을 더 살펴보려면 용어 가이드의 구독, 노드, 정책 그룹 항목을 참고하세요.

정책 그룹: 선택, 속도 측정, 장애 전환

규칙은 안정적인 그룹 이름을 참조합니다

정책 그룹은 “어떤 요청을 이쪽으로 보낼지”와 “현재 어떤 출구를 선택할지”를 분리합니다. 규칙은 그룹 이름을 참조하고 그룹은 노드, 다른 그룹, 내장 아웃바운드를 참조합니다. 따라서 노드를 바꿔도 웹사이트 규칙을 다시 작성할 필요 없이 그룹 멤버만 바꾸면 됩니다. 가장 확인하기 쉬운 구조는 업무별 그룹 한 단계와 후보 아웃바운드 한 단계로 구성됩니다. 자동 선택 단계를 추가하더라도 참조 방향은 한쪽으로 유지하세요. 예를 들어 수동 그룹이 자동 그룹을 참조할 수는 있지만, 자동 그룹이 수동 그룹을 다시 참조하면 최종 아웃바운드를 결정할 수 없습니다.

select는 수동 선택 그룹으로, 처음 연결을 확인하거나 특정 출구를 고정하고 예비 항목을 남겨 둘 때 적합합니다. 목록 순서는 조작하기 편하도록 표시되는 순서일 뿐, 첫 번째 항목이 매번 강제로 선택된다는 뜻은 아닙니다. 클라이언트가 이전 상태를 복원할 수 있습니다. 문제 해결 중에는 그룹 화면에서 원하는 멤버를 직접 선택하고 연결 로그에서 실제로 사용된 출구를 확인하세요. 그룹에 DIRECT를 추가해도 자동 직결 전환이 되는 것은 아니며 선택 가능한 출구가 하나 늘어날 뿐입니다.

proxy-groups:
  - name: WEB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,WEB
  - MATCH,DIRECT

이 설정은 앞 장에서 정의한 LAB-SOCKS 노드에 의존합니다. 지정한 도메인만 수동 그룹으로 보내고 나머지 요청은 직결로 보냅니다. 멤버를 수동으로 바꾼 뒤에는 새 연결로 확인하세요. 기존 세션이 자동으로 이동한다고 기대하면 안 됩니다. 브라우저가 연결을 재사용하거나 애플리케이션이 장시간 연결을 유지할 수 있습니다. 화면에는 다른 노드가 선택된 것으로 표시되는데 동작이 바뀌지 않는다면 테스트 애플리케이션의 기존 세션을 끊은 뒤 새 연결의 규칙 매칭과 실제 아웃바운드를 확인하세요. 그러면 선택이 저장되지 않은 경우와 연결이 아직 새로 생성되지 않은 경우를 구분할 수 있습니다.

자동 그룹의 탐색 결과는 탐색 대상만 나타냅니다

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,AUTO
  - MATCH,DIRECT

url-test는 탐색 URL을 이용해 후보 아웃바운드를 비교하므로 자동 선택을 허용하는 트래픽에 적합합니다. 여기서 interval은 초 단위이고 tolerance는 밀리초 단위입니다. 작은 지연 차이로 선택이 자주 바뀌는 것을 줄여 줍니다. 화면에 표시되는 값은 지정한 URL을 대상으로 한 한 번 또는 여러 번의 탐색 결과이지 실제 서비스의 지연 시간이나 대역폭이 아닙니다. 예제에 직결을 넣은 것은 테스트 편의를 위해서입니다. 업무상 프록시를 반드시 사용해야 한다면 직결을 자동 후보에 추가하지 마세요. 탐색이 더 빠르다는 이유로 직결이 선택될 수 있습니다.

fallback은 지연 시간이 가장 낮은 멤버를 찾기보다 우선순위에 따라 현재 사용 가능한 멤버를 선택하는 방식에 가깝습니다. 기본 출구를 유지하려면 자주 쓰는 멤버를 앞에 두고 예비 멤버를 뒤에 배치한 다음, 해당 멤버들이 안정적으로 접근할 수 있는 탐색 URL을 설정하세요. 두 자동 그룹 모두 탐색 주소, 연결 시간 초과, 실행 주기의 영향을 받습니다. 실제 업무 사이트에는 접속되는데 탐색 주소만 열리지 않는다면 그룹의 가용성 판단은 실제 요구와 다를 수 있습니다. 탐색 URL을 바꿀 때는 대상 네트워크의 안정성과 연결 성립 여부를 확인할 수 있는 응답인지 함께 고려하세요.

멤버 소스와 복구 전략

proxies는 정의된 노드나 다른 선택 가능한 아웃바운드를 이름으로 참조하고, use는 프로바이더의 멤버를 가져옵니다. 구독 업데이트 때 노드 이름이 바뀐다면 그룹에 긴 이름 목록을 직접 적는 것보다 use를 사용하는 편이 관리하기 쉽습니다. 두 방식을 함께 사용하면 로컬 고정 예비 항목과 업데이트되는 원격 후보를 한 그룹에 둘 수 있습니다. 이름은 표시되는데 선택 가능한 노드가 없다면 참조한 프로바이더가 로드되었는지, 목록에 실제 노드가 있는지, 클라이언트가 추가 필터를 적용했는지 확인하세요. 속도 측정 결과만 새로고침하지 마세요.

고정 출구가 불안정한 문제라면 먼저 허용할 대체 경로를 정한 다음 그룹 유형을 선택하세요. 로그인 세션이나 출발지 주소를 유지해야 한다면 지연 시간을 자주 비교하는 방식보다 수동 그룹이 적합할 수 있습니다. 첫 번째 후보가 실패한 뒤에만 전환하려면 장애 전환 그룹을 사용하세요. 어디로 보낼지 확실하지 않은 트래픽이 모르게 “예비 프록시 사용”에서 “직결”로 바뀌지 않도록 하세요. 새 노드를 테스트할 때는 수동 비교용 그룹을 남겨 두고 연결, DNS 조회, 애플리케이션 요청을 모두 확인한 뒤 자동 선택에 포함하세요. 문제가 생겨도 직전의 명확한 선택으로 빠르게 돌아갈 수 있습니다.

프로바이더의 상태 검사와 그룹 자체의 속도 측정 설정도 따로 확인해야 합니다. 프로바이더에서 노드가 사용 가능하다고 표시되더라도 그룹의 탐색 URL에 접근할 수 있다는 뜻은 아닙니다. 반대로 일시적인 오류만으로 노드를 모든 그룹에서 제거할 필요도 없습니다. 같은 대상과 같은 전송 경로를 사용해 다시 확인한 뒤 수정할 곳이 후보 목록인지, 탐색 설정인지, 실제 아웃바운드인지 판단하세요. 한 번 측정한 지연 시간보다 판단 근거를 기록하는 편이 유용합니다.

규칙 문법: 매칭 순서, 대상, 리소스 집합

처음 일치한 규칙이 경로를 결정합니다

규칙 모드에서 코어는 rules를 위에서 아래로 확인하고 첫 번째로 일치한 규칙의 대상을 사용합니다. 더 구체적인 규칙을 계속 찾지는 않습니다. 대부분의 규칙은 유형, 매칭 값, 대상으로 구성되며 영문 쉼표로 구분합니다. MATCH에는 매칭 값이 없고 아웃바운드 대상만 지정합니다. 구체적인 예외를 넓은 범위의 분류보다 앞에 두고 마지막에 기본 규칙을 배치하세요. 규칙을 알파벳순으로 정렬하지 말고 개인 규칙을 기본 규칙 뒤에 추가하지도 마세요. 파일에 적혀 있어도 실행될 기회가 없습니다.

rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

이 규칙 목록은 직결 기본 설정의 규칙을 교체할 수 있으며 LOCAL 그룹은 유지해야 합니다. 첫 번째 줄은 정확히 일치하는 도메인에만 적용되고, 두 번째 줄은 기본 도메인과 하위 도메인을 모두 포함합니다. 현재 두 대상이 모두 직결로 이어지더라도 연결 로그를 보면 정확한 도메인 규칙이 DIRECT에 일치했는지, 하위 도메인 규칙이 LOCAL에 일치했는지 구분할 수 있습니다. 두 줄의 순서를 바꾸면 정확한 도메인도 먼저 하위 도메인 규칙에 걸립니다. 단순한 대상을 사용해 비교하면 원격 네트워크의 영향을 배제하고 규칙 순서를 검증할 수 있습니다.

도메인 규칙의 값은 전체 웹 주소가 아닙니다. 프로토콜, 경로, 포트, 쿼리 매개변수를 붙이지 마세요. 매칭 대상은 브라우저 주소창의 전체 문자열이 아니라 코어가 받는 호스트 이름입니다. 리디렉션으로 새 대상에 접속하거나 페이지가 다른 도메인을 비동기로 요청할 수도 있습니다. 사용자에게는 같은 페이지처럼 보여도 로그에는 여러 연결이 남을 수 있습니다. 알려진 호스트 이름 하나만 테스트하고 로그에서 대상과 일치한 규칙을 확인하세요. 다른 곳에서 복사한 규칙을 붙일 때는 전각 쉼표나 보이지 않는 공백도 확인해야 합니다.

주소 매칭은 DNS 조회를 유발할 수 있습니다

IP-CIDR은 IPv4 주소 범위를 확인하고 IPv6에는 IP-CIDR6을 사용합니다. GEOIP는 주소와 지리 데이터를 비교하며 실행 환경에 해당 데이터가 있어야 합니다. 둘 다 도메인 접미사 규칙은 아닙니다. 도메인 대상은 주소 규칙을 판정하기 위해 먼저 조회해야 할 수 있습니다. 일부 주소 규칙은 끝에 no-resolve를 붙여 해당 규칙이 추가 조회를 시작하지 않도록 할 수 있습니다. 그렇다고 이미 확보한 대상 주소를 사용하지 않는다는 뜻은 아닙니다. 매칭할 주소를 얻지 못하면 주소 규칙이 반드시 일치한다고 볼 수 없으므로 이후 규칙에서 적절한 경로를 제공해야 합니다.

같은 업무 요청이 도메인 규칙에 걸렸다가 주소 규칙에 걸리는 식으로 달라진다면 연결을 시작하는 애플리케이션이 항상 같은 방식으로 대상을 전달하는지 확인하세요. 어떤 애플리케이션은 도메인을 전달하고 다른 애플리케이션은 캐시된 주소에 직접 연결합니다. 같은 도메인도 여러 주소로 해석될 수 있고 지리 데이터 판정도 실제 주소나 데이터 내용에 따라 달라집니다. 지리 규칙으로 업무 도메인 목록을 대신하지 마세요. 중요한 업무는 명확한 예외를 먼저 정한 다음 남은 요청에 주소 범위나 지리 분류를 적용하고 실제 대상 정보와 규칙 매칭 결과를 로그에서 확인하세요.

외부 규칙은 프로바이더 유형을 지정하세요

rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,local-domains,LOCAL
  - MATCH,DIRECT

그다음 코어 작업 디렉터리의 rules/local-domains.yaml에 payload 목록을 작성합니다:

payload:
  - '+.example.net'

domain 리소스 집합에는 도메인 표현식을 작성하고, ipcidr에는 주소 범위를 지정합니다. classical에는 매칭 유형을 포함한 일반 규칙을 넣을 수 있습니다. 동작 유형은 파일 내용과 일치해야 하며, 프로바이더 파일의 각 항목에 아웃바운드를 따로 지정하지 마세요. 경로는 기본 설정의 RULE-SET이 지정합니다. RULE-SET도 목록에서의 위치에 따라 우선순위가 달라집니다. 개인 예외 규칙으로 리소스 집합보다 먼저 매칭시키려면 참조 줄보다 앞에 배치하세요. 리소스 파일의 순서를 바꾸는 방식은 적절하지 않습니다.

규칙 리소스를 업데이트한 뒤 정책이 크게 달라졌다면 리소스 유형, 업데이트 전후의 매칭 범위, 기본 규칙의 우선순위를 먼저 비교하세요. 작업 디렉터리의 로컬 리소스를 임시로 사용해 다운로드 실패인지, 형식 오류인지, 실제로 더 넓은 범위에 매칭된 것인지 구분할 수 있습니다. 사용자 규칙을 추가할 때는 가장 범위가 좁은 유효 조건을 앞에 넣고 일치해야 하는 요청과 일치하면 안 되는 요청을 각각 테스트하세요. 두 결과가 모두 예상과 맞아야 경계를 검증한 것입니다. 이번에 사이트를 열 수 있었다는 사실만으로는 충분하지 않습니다.

덮어쓰기와 병합: 구독 파일에서 최종 설정까지

수정해야 할 설정 단계 찾기

그래픽 클라이언트는 원격 구독, 사용자 덮어쓰기, 화면에서 선택한 설정, 코어에 전달하는 최종 파일을 따로 저장하는 경우가 많습니다. 구독 캐시를 직접 수정하면 당장은 적용될 수 있지만 다음 업데이트에서 덮어써집니다. 임시 출력 파일을 편집하면 다시 불러올 때 변경 사항이 사라질 수 있습니다. 개인 규칙을 업데이트 후에도 유지하려면 클라이언트에 덮어쓰기, 확장 설정, 스크립트 진입점이 있는지와 적용 순서를 먼저 확인하세요. 코어는 처리가 끝난 결과를 읽습니다. 원본 파일에 “덮어쓰기”라는 문구가 있다고 두 파일을 자동으로 합치지는 않습니다.

키의 값 유형에 따라 병합 방식을 결정하세요. 포트와 모드는 스칼라 값이므로 보통 최종 값 하나만 남습니다. DNS는 매핑이므로 하위 키 하나만 바꿀 수도 있고 도구가 블록 전체를 교체할 수도 있습니다. 규칙과 정책 그룹은 시퀀스이며 도구에 따라 전체 교체, 앞에 추가, 뒤에 추가, 이름을 기준으로 처리하는 방식이 다릅니다. YAML 자체에는 클라이언트가 두 설정의 시퀀스를 어떻게 합쳐야 하는지 규정이 없습니다. 도구를 사용하기 전에 규칙 두 줄로 실험해 최종 파일의 순서를 확인하세요. 다른 클라이언트의 덮어쓰기 필드를 그대로 적용하지 마세요.

덮어쓰기 항목은 용도와 함께 기록하는 편이 좋습니다. 특정 도메인을 로컬 그룹으로 보내기만 하면 된다면 포트, 로그, 노드 목록 전체를 함께 복사하지 마세요. 관련 없는 필드가 나중에 상위 설정의 변경을 덮어쓸 수 있습니다. 반대로 DNS 설정 블록 전체를 교체해야 한다면 반드시 유지해야 할 업스트림과 정책을 먼저 정리하세요. 노드 도메인 조회용 전용 진입점까지 삭제하지 않도록 주의해야 합니다. 덮어쓰기를 짧게 유지하면 검토하기 쉽지만 필요한 기능 블록의 다른 필드를 무시해서는 안 됩니다.

입력과 출력으로 병합 방식 확인하기

# 원격 설정에 있던 기존 규칙
rules:
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT
# 예외 규칙을 앞에 추가한 최종 규칙
rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT

이 두 블록은 입력과 예상 출력의 예시이며 동시에 활성화할 설정이 아닙니다. 예외 규칙이 하위 도메인 규칙보다 앞에 있고 기존 기본 규칙이 마지막에 남아 있는지 확인하세요. 클라이언트가 규칙 목록 교체만 지원한다면 최종 출력의 전체 목록을 사용하세요. 앞부분에 항목을 추가하는 기능을 지원한다면 해당 설정 경로에 첫 번째 예외 규칙만 작성하면 됩니다. 출력에 있는 규칙과 로그를 대조하고 LOCAL의 정의가 여전히 있는지도 확인하세요. 정책 그룹 이름을 바꿀 때는 덮어쓰기 도구가 원래 그룹을 교체하는 대신 같은 이름의 그룹 두 개를 추가하지 않았는지 확인해야 합니다.

JSON 형식의 인라인 목록과 여러 줄 목록은 대체로 같은 값을 표현할 수 있지만, 여러 줄로 펼치면 항목이 추가된 위치를 비교하기 쉽습니다. 보기 좋게 정리하려고 규칙을 자동 정렬하게 두지 마세요. 매핑 키 정렬은 읽기에만 영향을 줄 수 있지만 목록 정렬은 의미를 바꿉니다. 필드를 삭제할 때도 “기존 값 상속”과 “명시적으로 비우기”를 구분하세요. 키를 생략하면 덮어쓰기에 참여하지 않는다는 뜻일 수 있고, 빈 목록은 항목이 없는 값으로 덮어쓴다는 뜻일 수 있습니다. 실제 동작은 도구의 규칙에 따라 달라집니다. 콜론 뒤를 비워 두면 코어가 예상치 못한 빈 값으로 해석할 수도 있습니다.

앵커 재사용과 업데이트 후 회귀 테스트

YAML 앵커와 별칭은 같은 파일 안에서 구조를 재사용할 때 적합하며 설정 간 가져오기 기능은 아닙니다. 매핑 병합 문법 지원 여부는 클라이언트의 전처리기와 파서에 따라 다릅니다. 특히 이 기능으로 시퀀스가 항목별로 병합될 것이라고 가정하지 마세요. 다른 클라이언트에서도 사용할 파일이라면 펼쳐진 상태로 단독 해석이 가능한 버전을 유지하는 편이 좋습니다. 로그에 별칭을 찾을 수 없다고 나오면 규칙부터 수정하지 말고 전처리 과정에서 앵커가 이동되거나 삭제되었는지 확인하세요.

구독을 업데이트하기 전에 마지막으로 정상 작동했던 로컬 스냅샷을 보관하고 사용자 덮어쓰기도 별도로 저장하세요. 업데이트 후에는 노드 이름과 대상 그룹을 계속 참조할 수 있는지, 목록이 비어 있지 않은지, 기본 규칙과 DNS 및 실행 모드가 달라지지 않았는지 순서대로 확인하세요. 회귀 테스트가 실패하면 먼저 덮어쓰기를 비활성화하고 원래 구독만 실행한 뒤 덮어쓰기를 단독으로 적용해 비교할 수 있습니다. 두 경우 모두 실패한다면 병합이 원인이라고 단정할 수 없습니다. 덮어쓰기를 켰을 때만 실패한다면 블록을 나눠 복구해 처음으로 동작을 바꾼 블록을 찾으세요.

유효한 설정을 비교용으로 저장할 때 인증 정보가 들어 있는 파일 전체를 공개 토론 게시판에 붙여 넣지 마세요. 로컬 파일을 비교할 때는 변경된 경로, 순서, 참조 관계를 중점적으로 확인하세요. 공유할 때는 필요한 조각만 남기고 정의와 참조를 일관된 가상 이름으로 바꾸세요. 구조를 재현하면서도 문제를 도와주는 사람이 순서가 잘못됐는지, 이름이 중복됐는지, 파일 생성 후 다시 로드되지 않았는지 확인할 수 있습니다.

검증과 문제 해결: 설정 로드 결과부터 연결 로그까지

설정을 먼저 검증하고 리스너를 확인하세요

명령줄 코어로 설정을 먼저 테스트하면 실행 중인 환경을 바로 교체할 필요가 없습니다. 현재 디렉터리를 테스트용 디렉터리로 바꾸고 유효한 설정을 config.yaml로 저장하세요. 로컬 프로바이더나 규칙 리소스를 사용한다면 설정에 맞춰 같은 테스트 디렉터리에 하위 디렉터리를 준비합니다. 다음 명령은 mihomo가 실행 파일 검색 경로에 있고 curl도 바로 실행할 수 있다고 가정합니다. 첫 번째 명령을 단독으로 실행해 성공 여부를 확인한 뒤 터미널 하나에서 두 번째 명령을 실행하고 다른 터미널에서 요청을 보내세요.

mihomo -t -d . -f ./config.yaml
mihomo -d . -f ./config.yaml
curl --noproxy "" --proxy http://127.0.0.1:7890 https://example.org/

그래픽 클라이언트와 테스트용 코어가 같은 포트를 동시에 사용하지 않도록 하세요. 시작하기 전에 기존 점유 프로세스를 종료하거나 테스트 설정에 다른 빈 포트를 지정하고 명령의 포트 번호도 바꾸세요. 일부 환경에서 curl은 터미널 별칭일 수 있습니다. 해당 플랫폼에서 실제 실행 파일을 사용하세요. 명시적 프록시 옵션을 쓰는 이유는 이번 요청을 지정한 진입점으로 보내 시스템 프록시 설정과 프록시 환경 변수의 영향을 줄이기 위해서입니다. 테스트 성공은 해당 진입점이 요청을 한 번 받았다는 뜻일 뿐, 모든 애플리케이션이 같은 설정을 읽는다는 뜻은 아닙니다.

설정 테스트가 실패하면 파일을 찾았는지, 문법 오류가 있는지, 필요한 리소스를 읽을 수 있는지 먼저 확인하세요. 테스트에는 성공했지만 시작에 실패하면 포트 충돌, 권한 부족, 테스트 때와 다른 실제 작업 디렉터리 등 실행 환경을 확인해야 합니다. 시작은 되지만 연결되지 않을 때 연결 경로를 살펴보세요. 이 단계에서는 완전한 오류 메시지 한 건을 기록하면 충분합니다. 같은 오류가 반복된다고 설정의 열 군데 이상이 동시에 잘못된 것은 아닙니다. 애플리케이션이 계속 재시도하고 있을 수 있습니다.

연결 정보로 문제 범위 좁히기

증상먼저 확인다음 단계
프록시 포트 연결이 거부됨코어가 예상한 주소와 포트에서 리스닝 중인지시작 로그와 애플리케이션 설정 비교
애플리케이션에서 요청했지만 코어에 기록이 없음애플리케이션이 실제로 프록시 진입점을 거치는지명시적 프록시와 시스템 트래픽 가로채기를 각각 검증
기록은 있지만 대상이 잘못 매칭됨모드, 규칙 순서, 실제 대상그룹의 현재 선택과 적용된 설정 확인
프록시 규칙에 매칭된 뒤에도 시간 초과노드 조회, 연결, 원격 핸드셰이크멤버 하나만 바꿔 재시도하고 오류가 발생한 단계 기록

연결 기록이 없을 때는 DNS 정책을 수정하거나 노드에 매개변수를 추가하지 마세요. 진입점을 명시한 요청으로 먼저 비교하세요. 해당 요청이 규칙에 매칭된다면 애플리케이션이 시스템 프록시 설정을 읽지 않거나 트래픽 가로채기 경로가 프로세스의 트래픽을 받지 못하는 문제일 가능성이 큽니다. 브라우저와 터미널도 따로 확인해야 합니다. 브라우저에는 프록시 확장 프로그램이 있을 수 있고 터미널은 환경 변수나 도구 자체 설정을 읽을 수 있습니다. 자세한 내용은 브라우저와 터미널에서 시스템 프록시가 작동하지 않을 때 확인할 사항을 참고하세요.

연결 기록은 있지만 경로가 잘못됐다면 모드, 대상 이름, 매칭된 규칙, 최종 아웃바운드 네 가지를 기록하세요. 예를 들어 규칙이 자동 그룹을 가리켜도 예상한 프록시로 나간다는 뜻은 아닙니다. 후보에 포함된 직결이 실제로 선택되었을 수 있습니다. 기존 세션 상태만 이상하다면 해당 세션을 닫고 다시 연결하세요. 새 세션에서도 재현된다면 실행 중인 옵션이 파일 설정을 덮어쓰는지 확인하세요. 현재 연결의 기록을 기준으로 판단하고 이전 테스트의 화면 캡처로 결론 내리지 마세요.

반복 가능한 회귀 테스트로 검증 기록 남기기

수정할 때마다 최소 세 가지 대상을 비교하세요. 직결되어야 하는 대상, 사용자 지정 규칙에 매칭되어야 하는 대상, 기본 규칙으로 가야 하는 대상입니다. 먼저 최소 설정이 실행되는지 확인한 다음 노드, 정책 그룹, DNS, 외부 리소스를 순서대로 다시 추가하세요. 어느 단계에서든 실패하면 방금 추가한 블록으로 원인을 좁힐 수 있습니다. 간헐적인 문제가 있다면 발생 당시의 네트워크 환경과 진입 방식도 기록하세요. 유선에서 무선으로 바꾸거나 데스크톱에서 휴대폰으로 바꾸면 시스템 트래픽 가로채기와 업스트림 조회가 달라질 수 있으므로 두 결과를 같은 조건으로 비교하면 안 됩니다.

처음 가져올 때 설정이 실패한다면 입문 가이드로 돌아가 가져오기, 모드, 연결 순서로 다시 확인하세요. 특정 필드까지 원인을 좁혔다면 예상 동작, 실제 동작, 최소 설정 조각을 기록해 독립적으로 재현하세요. 운영 환경으로 돌아가기 전에 임시로 높인 로그 수준, 테스트 포트, 임시 트래픽 가로채기 설정을 원래대로 복원하세요. 그러면 다음에 “수정했더니 인터넷이 안 된다”는 문제가 생겨도 처음부터 다시 추측하지 않고 마지막으로 정상 작동했던 설정과 재현 가능한 요청부터 확인할 수 있습니다.

마지막으로 다시 불러온 뒤와 재시작한 뒤의 결과를 비교하세요. 다시 불러오면 코어가 파일 변경을 적용했는지 확인할 수 있고, 재시작하면 클라이언트가 이전 선택을 복원하는지, 설정을 다시 생성하는지, 시작할 때 구독을 가져오는지 확인할 수 있습니다. 두 결과가 다르면 차이가 발생한 단계를 기록하고 덮어쓰기와 병합으로 돌아가 설정 출처를 확인하세요. 장기적으로 유용한 것은 디버그 로그를 더 많이 남기는 일이 아니라 되돌릴 수 있는 파일, 다시 테스트할 수 있는 요청, 매칭되어야 하는 규칙을 아는 것입니다.