#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

更新后行为没有变化

确认更新是否真的替换了正确路径下的文件——如果客户端配置文件所在目录和内核实际使用的工作目录不是同一个,更新脚本写入的位置和内核读取的位置可能对不上,表现就是"更新了但没变化"。回到第二节确认路径优先级,通常能定位到问题所在。

把这几类问题按顺序过一遍,基本能定位到是网络、配置字段、文件路径还是规则集格式四类原因中的哪一种,再针对性处理即可,不需要重装客户端或重写整份配置文件。