#GeoIP·GeoSite 데이터베이스 업데이트 방법: 저장 경로, 자동 업데이트 설정, 오류 대응

##GeoIP와 GeoSite는 각각 무엇을 해결하는가

분리 규칙을 작성해 본 사람이라면 아래 두 문장을 본 적이 있을 것입니다.

GEOIP,CN,DIRECT
RULE-SET,geosite-cn,DIRECT

첫 번째 규칙은 IP 주소로 소속 지역을 판단하고, 두 번째 규칙은 도메인 목록으로 사이트 소속을 판단합니다. 이 두 규칙은 각각 서로 다른 데이터 파일에 의존하며, 이 차이를 이해하는 것이 규칙 미적용 문제를 진단하는 전제 조건입니다.

geoip.metadb는 IP 주소 대역을 국가 코드로 매핑한 표로, MMDB 바이너리 형식으로 저장됩니다. 규칙이 GEOIP,CN,DIRECT로 작성되면 mihomo 코어는 연결 대상 IP를 이 표에서 조회해 국가 코드가 CN이면 직접 연결로 매칭합니다. 이 표가 다루는 것은 IPv4·IPv6 주소 대역 구분이며 도메인 자체와는 직접적인 관계가 없습니다. 같은 도메인이 해석하는 IP가 오늘은 특정 지역에, 내일은 다른 지역 노드로 바뀔 수 있으며, 이것이 순수 IP 기반 판단이 간혹 흔들리는 이유 중 하나입니다.

geosite.dat는 분류별로 정리된 도메인 목록으로, Protobuf 형식으로 압축 저장됩니다. 흔한 분류로는 cn, google, netflix, category-ads-all 등이 있습니다. 규칙 세트 작성법은 보통 rule-providers에서 geosite 기반 규칙 세트를 선언한 뒤 rules에서 참조하거나, 일부 코어에서는 GEOSITE,cn,DIRECT 같은 축약 문법도 지원합니다. 도메인 매칭은 DNS 해석이나 요청 발신 전에 이루어지며 판단 기준은 해석 결과가 아닌 도메인 문자열 자체이므로, IP가 수시로 바뀌는 CDN 사이트에 대해서는 geosite가 geoip보다 대체로 더 안정적으로 판단합니다.

두 방식을 함께 쓰는 것이 일반적인 방법입니다. 도메인이 매칭되는 트래픽은 geosite로 판단하고, 도메인으로 매칭되지 않는 나머지 트래픽은 geoip로 목적지 IP의 소속 지역을 기준으로 분류합니다. 둘 중 하나의 파일이라도 없거나 오래된 경우, 해당 유형의 규칙이 전체적으로 작동하지 않게 되는데 이때 별도의 오류 메시지가 뜨지 않는 경우가 많아 문제를 바로 알아차리기 어렵습니다.

##데이터베이스 파일의 저장 경로와 디렉터리 구조

mihomo 코어는 시작 시 정해진 순서대로 이 두 파일을 찾습니다. 경로를 무작정 외우기보다 탐색 로직을 이해하는 것이 더 유용합니다.

1. 코어 작업 디렉터리(Home Dir)가 우선입니다. 대부분의 그래픽 클라이언트는 코어에 전용 작업 디렉터리를 지정하며, geoip.metadb·geosite.dat·country.mmdb(일부 버전에서는 geoip.metadb 대신 이 파일명을 사용)는 이 디렉터리의 최상위에 config.yaml과 같은 레벨로 다운로드되며 하위 폴더로 흩어지지 않습니다.
2. 설정 파일이 위치한 디렉터리가 그다음입니다. 별도의 작업 디렉터리가 지정되지 않았다면 코어는 현재 설정 파일이 있는 폴더에서 이 두 파일을 찾고, 찾지 못하면 최초 다운로드가 시작됩니다.
3. 시스템 기본 디렉터리는 최후의 대안입니다. Linux에서는 보통 ~/.config/clash/나 ~/.config/mihomo/, Windows에서는 클라이언트 설치 디렉터리 안의 data 하위 폴더, macOS에서는 클라이언트의 Application Support 디렉터리에 위치하는 경우가 많습니다. 클라이언트마다 이 기본 디렉터리 명칭이 완전히 통일되어 있지는 않으므로, 파일을 찾지 못할 때는 클라이언트의 「설정」이나 「정보」 페이지에서 실제 작업 디렉터리 경로를 먼저 확인하는 것이 파일 시스템을 뒤지는 것보다 빠릅니다.

경로를 확인한 뒤에는 파일 속성의 수정 시간을 보는 것이 데이터베이스가 "오래 업데이트되지 않았는지"를 판단하는 가장 직접적인 방법입니다. 클라이언트를 반복해서 재시작하며 추측하는 것보다 훨씨 확실합니다.

##geodata-mode와 geo-auto-update 설정법

지리 데이터베이스를 사용할지, 업데이트를 얼마나 자주 자동 확인할지는 config.yaml 안의 몇 가지 필드로 제어됩니다. 전형적인 작성 예는 다음과 같습니다.

geodata-mode: true
geodata-loader: standard
geo-auto-update: true
geo-update-interval: 24
geox-url:
  geoip: "https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/geoip.metadb"
  geosite: "https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/geosite.dat"
  mmdb: "https://github.com/MetaCubeX/meta-rules-dat/releases/latest/download/country.mmdb"

각 필드의 의미는 다음과 같습니다.

• geodata-mode: 지리 데이터베이스 기반 매칭을 사용할지 여부입니다. false이면 GEOIP·geosite 관련 규칙이 로드되지 않아, 규칙 파일에 적어 두어도 빈 규칙과 같은 취급을 받습니다. 지리 규칙이 명확히 필요 없는 경우가 아니라면 true로 두는 것을 권장합니다.
• geodata-loader: 데이터베이스 로딩 전략입니다. standard는 메모리에 전체를 올려 조회 속도가 빠르지만 메모리 사용량이 다소 높고, 일부 버전은 memconservative 같은 저메모리 모드를 제공해 리소스가 제한된 라우터 장비에 적합합니다.
• geo-auto-update: 코어 실행 중 데이터베이스 업데이트를 자동으로 확인할지 여부입니다. 기본값이 꺼져 있는지 켜져 있는지는 클라이언트 버전에 따라 다르므로, 현재 값을 한 번 직접 확인하는 것을 권장합니다.
• geo-update-interval: 자동 업데이트 확인 간격으로 단위는 시간입니다. 너무 짧게 설정하면 불필요한 네트워크 요청이 늘어나므로 일반적으로 24~72시간 사이가 적절합니다.
• geox-url: 세 파일 각각의 다운로드 주소입니다. 기본 소스가 사용 중인 네트워크 환경에서 느리다면 동일 프로젝트의 미러 주소로 바꿀 수 있지만, 파일 내용과 형식 버전이 서로 맞아야 하며 서로 다른 프로젝트의 규칙 데이터베이스를 섞어 쓰면 해석 오류가 나기 쉽습니다.

한 가지 주의할 점은 geo-auto-update는 코어가 계속 실행 중일 때만 의미가 있다는 것입니다. 클라이언트가 종료될 때마다 코어 프로세스도 함께 꺼진다면, 다음 실행 시 업데이트를 다시 확인할지는 클라이언트 자체의 실행 로직에 따라 달라지며 이 필드의 동작과 완전히 같지는 않습니다.

##수동 업데이트 절차

대부분의 그래픽 클라이언트는 설정 파일을 직접 건드릴 필요가 없습니다. 업데이트 진입점은 보통 설정 화면에 있으며, 흔한 형태는 "GeoIP 데이터베이스 업데이트" 또는 "지리 데이터 업데이트" 버튼입니다. 클릭하면 클라이언트가 코어가 노출한 API를 호출해 다운로드를 시작하며, 네트워크 상태에 따라 몇 초에서 수십 초 내에 완료됩니다.

클라이언트에 그래픽 진입점이 없거나 업데이트가 실제로 적용되었는지 확인하고 싶다면 아래 절차를 따를 수 있습니다.

1. 코어의 RESTful API 포트와 키를 확인합니다(보통 config.yaml의 external-controller와 secret 필드에 있음). 이 두 값이 코어 인터페이스를 호출하는 전제입니다.
2. 인터페이스를 통해 업데이트를 트리거합니다. 일반적인 요청 형태는 코어의 /configs/geo(버전에 따라 경로가 다소 다를 수 있음)로 업데이트 지시를 보내는 것이며, 정확한 경로는 사용 중인 코어 버전의 인터페이스 문서를 기준으로 합니다.
3. 업데이트가 끝난 뒤 클라이언트 로그나 코어 로그를 확인해 "GeoIP database update completed" 같은 문구나 명확한 다운로드 성공 안내가 나타나는지 확인합니다. 화면에 오류가 안 보인다는 것만으로 성공을 판단하지 않습니다.
4. 코어나 클라이언트를 한 번 수동으로 재시작해 업데이트된 데이터베이스 파일을 규칙에 다시 로드시킵니다. 일부 상황에서는 업데이트는 완료되었지만 규칙 매처가 즉시 다시 로드되지 않는 경우가 있어, 재시작이 가장 확실한 방법입니다.

자동화 진입점을 정말 찾을 수 없다면 파일을 직접 다운로드해 교체하는 방법도 가능합니다. 데이터베이스 출처 저장소의 Releases 페이지에서 최신 geoip.metadb와 geosite.dat를 내려받아 작업 디렉터리 안의 기존 파일을 교체한 뒤 코어를 재시작합니다. 교체 전에는 기존 파일을 백업해 두는 것을 권장하며, 새 파일이 손상되었거나 형식이 맞지 않을 경우 곧바로 되돌릴 수 있습니다.

##자주 나타나는 오류와 규칙 미적용 점검 순서

이 종류의 문제는 대부분 눈에 띄는 오류 메시지 없이 "규칙이 안 적용되는 것 같다"는 형태로 나타납니다. 아래 순서대로 하나씩 확인하면 무작정 시도해 보는 것보다 훨씬 효율적입니다.

다운로드 실패 또는 시간 초과

로그에 연결 시간 초과, TLS 핸드셰이크 실패 같은 문구가 보인다면 대개 네트워크 경로 문제입니다. 아직 프록시가 연결되지 않은 상태라면 코어가 직접 다운로드 소스에 접근하는 것 자체가 네트워크 환경 때문에 제한될 수 있습니다. 우선 geox-url의 주소를 미러 소스로 임시 변경하거나, 프록시가 정상적으로 연결된 뒤에 다시 수동으로 업데이트를 시도해 볼 수 있습니다.

파일은 다운로드되었지만 규칙이 여전히 매칭되지 않음

먼저 geodata-mode가 true인지 확인합니다. 이 항목이 가장 쉽게 간과됩니다. 그다음 규칙에 적은 지역 코드나 분류 명칭이 현재 버전의 데이터베이스에 실제로 존재하는지 확인합니다. 예를 들어 geosite-cn 같은 분류 명칭은 규칙 세트 프로젝트 버전에 따라 이름이 바뀌거나 분리되는 경우가 있어, 예전 설정을 그대로 가져다 쓰면 이 문제를 겪기 쉽습니다.

규칙 세트 로드 오류 "rule provider not found" 또는 형식 오류

이런 오류는 rule-providers의 behavior 필드가 실제 파일 형식과 맞지 않을 때 흔히 발생합니다. geosite 계열 규칙 세트는 behavior: domain으로, IP 대역 기반 규칙 세트는 behavior: ipcidr로 작성해야 합니다. 반대로 쓰면 코어가 파일 내용을 올바르게 해석하지 못해 형식 오류가 발생합니다.

rule-providers:
  geosite-cn:
    type: http
    behavior: domain
    url: "https://example.com/geosite-cn.txt"
    path: ./rule-providers/geosite-cn.yaml
    interval: 86400

업데이트 후에도 동작이 바뀌지 않음

업데이트가 실제로 올바른 경로의 파일을 교체했는지 확인합니다. 클라이언트 설정 파일이 있는 디렉터리와 코어가 실제로 사용하는 작업 디렉터리가 서로 다르면, 업데이트 스크립트가 기록한 위치와 코어가 읽는 위치가 어긋나 "업데이트는 됐는데 바뀐 게 없다"는 결과로 나타납니다. 앞의 두 번째 절로 돌아가 경로 우선순위를 다시 확인하면 대체로 원인을 찾을 수 있습니다.

이 네 가지 항목을 순서대로 확인하면 네트워크, 설정 필드, 파일 경로, 규칙 세트 형식 중 어디에 원인이 있는지 대체로 짚어낼 수 있으며, 클라이언트를 다시 설치하거나 설정 파일 전체를 새로 쓸 필요는 없습니다.