Mihomo自定义规则集进阶配置:Rule Providers托管与自动校验
为什么把自定义规则拆成 Rule Providers
当配置里的 rules 越写越长,改一条域名就要重新检查整份主配置;如果几台设备共用规则,还得在每份 YAML 里重复维护。Mihomo 的 rule-providers 可以把规则内容拆成独立文件,由主配置声明来源、类型和更新间隔,再通过 RULE-SET 在规则列表中引用。这样做的价值不只是「少写几行」:规则可以单独审阅、版本管理和回滚,配置主体也更容易读懂。
Rule Provider 不会替你决定流量走向。它提供的是一组规则,最终命中哪条、使用哪个策略,仍由主配置的 rules 顺序和 RULE-SET 后面的策略名决定。把这两层职责分开,才能在连接日志里判断问题究竟来自规则内容、规则顺序,还是策略组本身。本文用一个托管在 GitHub 的 YAML 规则集演示完整流程,并加入基础 CI 检查,帮助尽早发现格式错误和引用遗漏。
先读懂 rule-providers 的关键字段
一个远程 Provider 至少要说清楚规则从哪里来、规则采用什么匹配语义,以及 Mihomo 将规则文件保存在哪里。下面的示例把开发站点域名作为一个独立集合;实际使用时,应根据自己的连接日志和需求替换域名,避免直接复制未经核验的清单。
rule-providers:
dev-sites:
type: http
behavior: domain
format: yaml
url: https://raw.githubusercontent.com/example-org/mihomo-rules/main/providers/dev-sites.yaml
path: ./ruleset/dev-sites.yaml
interval: 86400
type: http 表示从 HTTP(S) 地址获取规则,适合 GitHub Raw 等静态文件托管;behavior 则声明规则按什么类型解释。常见取值包括 domain、ipcidr 和 classical:域名集合用于域名匹配,IP 集合用于地址段匹配,经典规则可包含多种 Mihomo 规则类型。选择时应与文件内容一致,不能把普通域名列表标成 IP 段集合。
format: yaml 表示文件采用 YAML 规则集格式。规则文件可写成如下结构:
payload:
- DOMAIN,developer.example
- DOMAIN-SUFFIX,docs.example
- DOMAIN-KEYWORD,packages
其中规则类型应符合 Mihomo 对应版本支持的语法。若 Provider 的 behavior 是 domain,更适合使用域名或域名后缀条目;若希望在一个集合里混合更丰富的规则类型,可评估使用 classical,并按 Mihomo 文档要求组织内容。不要仅凭 YAML 能被解析就判断规则一定有效:语法正确、行为类型匹配、目标域名准确,是三个不同的检查层次。
path 是内核保存下载文件的位置。相对路径通常以配置文件所在位置为基准,但不同客户端可能会复制、转换或在自己的配置目录中运行文件。初次部署时建议检查客户端实际使用的配置路径,并确认该目录可写;如果规则更新失败,日志中出现路径不存在或权限错误,首先检查这里,而不是贸然更换规则 URL。interval 以秒计,86400 表示约一天更新一次。设置过短会增加请求频率,却不一定让规则更及时;对稳定维护的集合,每日或每几小时检查通常比每分钟拉取更合理。
用 GitHub 托管规则集并建立可回滚的发布流程
建议为规则集合单独建仓库,至少区分 Provider 文件、校验脚本和文档。例如仓库中保留 providers/dev-sites.yaml、scripts/validate.py 与 README.md。这样规则改动的差异清晰,不会和个人主配置、订阅链接或设备信息混在一起。仓库可以公开托管不含敏感信息的通用规则;不要把访问令牌、私有订阅、内网域名清单或个人 IP 地址写入公开文件。
示例 URL 使用 main 分支,优点是更新后客户端可以按间隔获取最新内容,缺点是分支内容变化会直接影响所有使用者。正式使用时可以采取「提交到主分支、CI 校验通过、再创建版本标签」的流程,并在发布说明中记录变更内容。若希望每次变更都自动生效,就要把快速修复和误发布风险一并纳入考虑;若更看重可复现性,则可将 Provider URL 指向固定版本或发布资产,并在确认后更新到新版本。
GitHub Raw 适合发布体积较小、静态且不需要鉴权的规则文件,但它不是完整的发布治理方案。生产使用中要检查仓库与分支名称是否正确、文件路径大小写是否匹配、URL 是否能返回原始 YAML,而不是 GitHub 网页 HTML。可以在浏览器或命令行打开该地址确认响应内容;如果返回 404,先核对分支和文件路径。如果访问受到网络环境限制,则即使本地 YAML 完全正确,客户端也可能因无法取回远程文件而无法更新。
为方便审计,每次变更尽量使用小而明确的提交:新增域名与删除过时条目分开提交,说明依据和影响范围。发现误分流时,可以对照版本记录定位最近改动,再回滚对应提交,而不必从一长串订阅规则中猜测哪个条目改变了行为。多人共同维护时,保护主分支并要求变更经过校验,也比直接在默认分支上编辑更容易控制风险。
在主配置中引用,并把规则放在正确位置
Provider 声明完成后,还要在主配置的 rules 中引用它。假设策略组名称为 开发代理,最小示例如下:
rules:
- RULE-SET,dev-sites,开发代理
- GEOIP,CN,DIRECT
- MATCH,开发代理
RULE-SET 的第一个参数应与 rule-providers 下的键名完全一致,第三个参数应是主配置中实际存在的策略名。名称拼写不一致、大小写不一致,或策略组并未定义,都可能让配置校验失败或产生非预期结果。规则按从上到下的顺序匹配,因此 Provider 需要放在可能提前接住同一流量的宽泛规则之前。若一个域名先命中更早的通用集合,后面的自定义 Provider 就没有机会生效。
建议先把自定义集合放在 GEOIP、国内外大集合和兜底规则之前,再用连接日志确认实际命中结果。不要把所有规则都放到最前面:优先级过高的关键词或宽泛域名后缀也可能误伤无关服务。对关键业务,可以先使用明确的完整域名或已验证的后缀,观察一段时间后再扩大范围。对于 IP 类型 Provider,还应考虑 DNS 解析、IPv4/IPv6 和规则命中对象之间的关系,不能只凭域名访问失败就断定 IP 集合没有生效。
修改后不要只看客户端是否显示「已连接」。分别核对配置解析状态、Provider 下载状态和具体连接的命中规则:如果主配置能启动但 Provider 报下载错误,问题多半在远程 URL、网络或文件路径;如果 Provider 已加载但流量仍走错策略,应检查规则顺序、规则类型和策略名称。将这三类状态拆开看,比反复切换全局模式更容易定位原因。
用 CI 校验 YAML、规则条目与主配置引用
人工检查容易漏掉缩进、重复规则和名称拼写。把基础检查放进 GitHub Actions,可以在每次提交或合并请求时自动拒绝明显错误。下面的 Python 示例使用 PyYAML 解析 Provider 文件,检查顶层结构、规则列表和常见规则前缀;它是轻量门禁,不是 Mihomo 规则语义的完整实现。
import sys
import yaml
ALLOWED_PREFIXES = {
"DOMAIN", "DOMAIN-SUFFIX", "DOMAIN-KEYWORD",
"IP-CIDR", "IP-CIDR6", "GEOIP", "PROCESS-NAME",
"SRC-IP-CIDR", "DST-PORT", "NETWORK"
}
def main(path):
with open(path, "r", encoding="utf-8") as file:
data = yaml.safe_load(file)
if not isinstance(data, dict) or not isinstance(data.get("payload"), list):
raise ValueError("expected a YAML mapping with a payload list")
seen = set()
for number, rule in enumerate(data["payload"], start=1):
if not isinstance(rule, str) or not rule.strip():
raise ValueError(f"payload item {number} must be a non-empty string")
prefix = rule.split(",", 1)[0].strip().upper()
if prefix not in ALLOWED_PREFIXES:
raise ValueError(f"unsupported rule prefix at item {number}: {prefix}")
if rule in seen:
raise ValueError(f"duplicate rule at item {number}: {rule}")
seen.add(rule)
if __name__ == "__main__":
try:
main(sys.argv[1])
except Exception as error:
print(error, file=sys.stderr)
sys.exit(1)
在仓库中添加 requirements.txt,内容声明 PyYAML 依赖;再配置工作流安装 Python 依赖并运行脚本。检查器中的规则前缀只是示例白名单,应依据你实际使用的 Mihomo 版本和 Provider 类型调整。尤其是 classical 集合,可能包含与域名列表不同的规则表达式,不能套用只检查域名集合的假设。严谨做法是按不同 behavior 编写对应校验逻辑,并为每类规则准备有效与无效样例。
结构检查之外,还应验证主配置是否引用了已定义的 Provider。可以在 CI 中解析主配置的 rule-providers 与 rules,收集所有 RULE-SET 使用的名称,并检查两边集合一致;同时核对每个 Provider 的策略名称是否出现在 proxy-groups 或合法的内置策略中。由于配置可能包含客户端模板变量、订阅生成字段或 Mihomo 特有语法,通用 YAML 解析器未必能够完整验证最终配置,因此这类静态检查应与目标 Mihomo 版本的配置测试配合,而不能互相替代。
更新策略、故障定位与长期维护
Provider 更新失败时,按链路逐层排查。首先确认主配置能够解析,随后查看 Mihomo 日志中是否出现对应 Provider 名称和请求错误,再检查 URL 是否能直接返回 YAML、客户端运行目录是否可写,以及更新间隔是否已经到期。若刚修改远端文件,客户端并不一定立刻重新请求;可以等待下一次更新周期,或按客户端提供的方式触发配置重载、内核重启或手动更新。不要在未保存备份的情况下频繁删除缓存文件,否则可能把可诊断的问题变成无法复现的状态。
规则更新后出现误分流,优先比较新旧版本的差异,而不是马上清空全部规则。检查新增后缀是否覆盖了不相关子域,关键词是否过宽,IP 段是否过期,以及规则是否被移动到更高优先级。对于服务商会动态调整 CDN 或 API 域名的应用,规则列表应以实际连接日志为依据,定期清理失效条目;静态规则集并不意味着它可以永久免维护。
还要为规则集制定简单的变更纪律:保留可读的提交记录,给关键版本打标签,记录规则来源与用途,不把临时排障条目长期留在公共集合里。对不同设备或不同环境有差异的规则,可以拆成多个 Provider,而不是用一份含有大量例外的集合承担所有职责。拆分也不宜过度;每个集合都应有清晰目的、稳定命名和对应的测试,否则维护成本会从主配置转移到一堆难以追踪的小文件上。
与部分同类客户端把规则与策略固化在界面、更新过程不透明的做法相比,Mihomo 的 Rule Providers 可以将规则源、匹配行为、缓存路径和更新周期显式写入 YAML,并借助 GitHub 的提交记录与 CI 把错误挡在发布之前。它需要一定的配置和维护意识,却能让个人设备与团队环境共享一套可审计、可回滚的规则流程。若你希望先获取兼容 Mihomo 的客户端,再按本文搭建自己的规则集,可以前往客户端下载页查看可用版本。