Skip to content
English下载

分流规则 ​

在 route-mode = "rule" 下,每条连接按 [route].rules 自上而下匹配,第一条命中的规则决定连接去向。 一条都没命中时,由 FINAL 决定。

toml
[route]
rules = [
  "DOMAIN-SUFFIX,corp.example.com,office",
  "PROCESS-NAME,cargo,work",
  "IP-CIDR,10.0.0.0/8,DIRECT",
  "FINAL,DIRECT",
]

本页的示例都是 [route] 的片段:work、office 代表你在 Profile 里定义的节点或代理组。

一条连接怎么分流 ​

  1. bypass。 目标在绕过列表里就直接 DIRECT,后面什么都不看。
  2. 路由模式。 direct 全部直连,global 全部交给 global-proxy。只有 rule 模式才读规则列表。
  3. 规则,自上而下,第一条命中的生效。
  4. FINAL;设置了 final-mixed / final-enhanced 时用它们。

列表里的先后顺序是唯一的优先级。域名规则不会因为是域名规则就压过 IP 规则,谁在前谁生效。

语法 ​

text
TYPE,payload,target
TYPE,payload,target,option
TYPE,payload,target,option,option
FINAL,target
  • 一条规则最多五个字段,多了加载失败。
  • 规则按括号外的逗号拆分。括号里的逗号属于 payload,所以逻辑规则和 ^(a{1,3})$ 这样的正则可以正常写; 括号外的逗号会截断 payload:DOMAIN-REGEX,^a{1,3}$,X 无法加载。括号必须成对。
  • 每个字段首尾的空格会被去掉。
  • TYPE 和选项不区分大小写。MATCH 是 FINAL 的别名。
  • target 是 DIRECT、REJECT、某个 [[proxy]] 的 name 或某个 [[proxy-group]] 的 name, 区分大小写:direct 不等于 DIRECT。
  • FINAL 不带 payload,也不带选项;它必须是最后一条,规则列表不为空时必须有它。完全不写规则时,连接走 final-mixed / final-enhanced(如果设置了),否则走 DIRECT。
  • 带反斜杠的规则(正则、Windows 路径)最好写成单引号的 TOML 字面量字符串: 'DOMAIN-REGEX,^ci-[0-9]+\.example\.com$,work'。写在双引号里时每个反斜杠都要写两次 ("...\\.example...");只写一个 \. 是非法的 TOML 转义,整个文件都会加载失败。

选项 ​

选项作用
include-children规则同时匹配命中进程启动的子程序。只能写在检查进程的规则上(包括含进程条件的 AND/OR/NOT)和 RULE-SET 上。见进程规则
no-resolve可以写、会被保留,但当前版本没有任何效果。Specola 从不为了测试 IP 规则而解析域名(resolve-unknown-domains 除外)

每个选项只能出现一次。第四、五个字段写了其他内容会报错。

规则类型 ​

域名 ​

类型匹配示例
DOMAIN完全等于这个域名DOMAIN,api.github.com,work
DOMAIN-SUFFIX这个域名及其所有子域名DOMAIN-SUFFIX,github.com,work
DOMAIN-KEYWORD域名中任意位置包含这段文字DOMAIN-KEYWORD,tracker,REJECT
DOMAIN-WILDCARD对整个域名做通配符匹配DOMAIN-WILDCARD,*.cdn.example.com,DIRECT
DOMAIN-REGEXPCRE2 正则表达式'DOMAIN-REGEX,^ci-[0-9]+\.example\.com$,work'
GEOSITEGeoSite 文件中的一个分类GEOSITE,github,work

匹配细节:

  • 所有域名类型都不区分大小写,域名和模式都按小写比较。
  • DOMAIN-SUFFIX,github.com 匹配 github.com 和 api.github.com,不匹配 notgithub.com。
  • DOMAIN-WILDCARD:* 匹配任意长度的字符,包括点;? 匹配一个字符。模式要覆盖整个域名, 所以 *.example.com 匹配 a.example.com 和 a.b.example.com,但不匹配 example.com 本身。
  • DOMAIN-REGEX 在域名的任意位置查找:REGEX,ads 也会命中 uploads.example.com。要整体匹配请用 ^ 和 $ 锚定。匹配忽略大小写。正则写错时加载失败。
  • GEOSITE 分类名不区分大小写。一个分类里有完整域名、后缀、关键字和正则,分别按上面的方式匹配。 不支持 cn@ads 这类属性过滤,会报 Unknown GeoSite category。
  • 没有域名、只有 IP 的连接不会命中任何域名规则。

IP ​

类型匹配示例
IP-CIDRIPv4 网段IP-CIDR,10.0.0.0/8,DIRECT
IP-CIDR6IPv6 网段IP-CIDR6,fd00::/8,DIRECT
IP-SUFFIX地址文本的结尾IP-SUFFIX,.255,REJECT
IP-ASN某个自治系统的地址IP-ASN,13335,DIRECT
GEOIPGeoIP 文件中的一个国家或分类GEOIP,private,DIRECT
  • 一定要写前缀长度。 IP-CIDR,1.2.3.4,X 能加载,但永远不会命中;请写 IP-CIDR,1.2.3.4/32,X。 IP-CIDR6 同理。(在 AND/OR/NOT 里省略前缀表示单个地址。)
  • IP-CIDR 只接受 IPv4 网段,IP-CIDR6 只接受 IPv6 网段,写反了加载失败。
  • IP-SUFFIX 比较的是文本,不是数值:IP-SUFFIX,.255 匹配 10.0.0.255;IP-SUFFIX,1 会匹配所有以数字 1 结尾的地址。作为顶层规则时它只检查 IPv4 地址,并支持 *、? 通配符(IP-SUFFIX,10.*.0.1)。
  • IP-ASN 写 13335 或 AS13335 都可以,需要 ASN 数据表,见 Geo 数据。
  • GEOIP 分类名不区分大小写(CN、cn、private)。
  • IP 规则只在连接带有地址时才会匹配,见 IP 规则与域名。

端口与网络 ​

类型匹配示例
DST-PORT目标端口或范围 a-bDST-PORT,22,DIRECT、DST-PORT,6881-6889,DIRECT
NETWORK传输协议:TCP、UDP 或 ICMPNETWORK,UDP,DIRECT
  • DST-PORT 只能写一个端口或一个范围,不支持列表;需要多个时用 OR 组合。
  • NETWORK 不区分大小写,可以用 / 写多个值(TCP/UDP)。写其他单词能加载,但永远不会命中。
  • 本地 HTTP/SOCKS5 端口只承载 TCP,所以 NETWORK,UDP 只对增强模式和网关流量起作用。

来源 ​

来源规则按发起连接的客户端匹配。

类型匹配示例
SRC-IP-CIDR客户端的 IPv4 网段SRC-IP-CIDR,192.168.1.0/24,DIRECT
SRC-IP-CIDR6客户端的 IPv6 网段SRC-IP-CIDR6,fd00::/8,DIRECT
SRC-PORT客户端源端口或范围 a-bSRC-PORT,50000-60000,DIRECT
SRC-MAC客户端 MAC 地址,aa:bb:cc:dd:ee:ff 或 aa-bb-…SRC-MAC,aa:bb:cc:dd:ee:01,DIRECT
SRC-DEVICE设备名或设备分组(不区分大小写)SRC-DEVICE,tv,STREAMING

适用范围:

  • 路由器网关(--gateway,仅限带网关功能的 Linux 构建):客户端就是局域网设备。SRC-MAC 和 SRC-DEVICE 依据网关的 DHCP 租约、设备列表和 ARP 表。来源规则同样决定该设备收到的 DNS 应答。
  • TUN 和 eBPF:来源是本机自己的地址和端口,SRC-MAC、SRC-DEVICE 永远不会命中。
  • 本地 HTTP/SOCKS5 端口:规则拿不到任何来源信息,来源规则永远不会命中,即使开了 allow-lan 的局域网客户端也一样。

进程 ​

进程规则按发起连接的程序分流,完整说明见进程规则:名称和路径怎么匹配、各平台报告的是什么、 哪些连接带有进程信息、include-children,以及 Linux eBPF 下代理组成员的固定。

类型匹配示例
PROCESS-NAME可执行文件名;含 * 或 ? 时按通配符PROCESS-NAME,cargo,work
PROCESS-PATH可执行文件完整路径;含 * 或 ? 时按通配符PROCESS-PATH,/usr/bin/git,work
PROCESS-NAME-WILDCARD可执行文件名,通配符PROCESS-NAME-WILDCARD,python*,work
PROCESS-PATH-WILDCARD可执行文件完整路径,通配符PROCESS-PATH-WILDCARD,/opt/tools/*,work
PROCESS-NAME-REGEX可执行文件名,正则表达式PROCESS-NAME-REGEX,^python3(\.[0-9]+)?$,work
PROCESS-PATH-REGEX可执行文件完整路径,正则表达式PROCESS-PATH-REGEX,^/opt/tools/,work

匹配不区分大小写。Windows 上的名称带 .exe(chrome.exe);macOS 上是应用包里的可执行文件(Google Chrome), 不是 .app。

规则集 ​

类型匹配示例
RULE-SET指定规则集中的任意一项RULE-SET,ads,REJECT

规则集里的所有条目共用这条 RULE-SET 规则的位置和出站。见下文规则集。

逻辑 ​

AND、OR、NOT 用来组合其他条件。每个条件不写出站,用括号包起来;AND 和 OR 至少两个条件, NOT 恰好一个,可以嵌套。

类型匹配示例
AND所有条件都满足AND,((PROCESS-NAME,curl),(DOMAIN-SUFFIX,example.com)),work
OR任一条件满足OR,((DOMAIN,a.example.com),(DOMAIN,b.example.com)),work
NOT条件不满足AND,((DST-PORT,443),(NOT,((PROCESS-NAME,updater)))),work
  • 整个条件列表外面还要再包一层括号:AND,( … ),target。
  • 条件可以是 DOMAIN、DOMAIN-SUFFIX、DOMAIN-KEYWORD、DOMAIN-WILDCARD、DOMAIN-REGEX、IP-CIDR、 IP-CIDR6、IP-SUFFIX、IP-ASN、DST-PORT、NETWORK、来源类型、进程类型,或者嵌套的 AND/OR/NOT。 GEOIP、GEOSITE 和 RULE-SET 不能写在逻辑规则里。
  • 逻辑规则里的 IP-SUFFIX 不支持通配符,但也会检查 IPv6 地址。

不支持 SUB-RULE。

FINAL 与按入口的兜底出站 ​

FINAL,target 是没有任何规则命中时的去向。[route] 里有两个可选键,可以按入口替换它:

toml
[route]
rules = ["DOMAIN-SUFFIX,corp.example.com,office", "FINAL,DIRECT"]
final-mixed = "work"      # 本地 HTTP/SOCKS5 端口
final-enhanced = ""       # 增强模式(TUN、eBPF);留空 = 用 FINAL
键作用于默认值
final-mixed来自本地 HTTP/SOCKS5 端口的连接""(用 FINAL)
final-enhancedTUN 或 eBPF 接管的连接,以及它们的 DNS 决策""(用 FINAL)
  • 值可以是 DIRECT、REJECT、节点或代理组。
  • 写了不存在的名字会被静默忽略,改用 FINAL,不会有任何提示。请检查拼写。
  • 在 Linux eBPF 上,final-enhanced 还决定没有规则命中的流量是否会被接管,见 eBPF 捕获哪些连接。
  • 规则页的测试和规则列表里的 FINAL 行显示的始终是 FINAL 规则本身。

bypass ​

toml
[route]
bypass = ["localhost", "*.local", "127.0.0.0/8", "192.168.0.0/16", "::1/128"]

目标在绕过列表里时,会在读取路由模式和规则之前直接走 DIRECT,对本地端口、TUN 和 eBPF 都生效, 任何路由模式下都生效,包括 global。

条目匹配
localhost恰好这个域名(忽略大小写和末尾的点)
*.locallocal 下的域名,不含 local 本身
10.1.2.3、fd00::1这个地址
192.168.0.0/16、fd00::/8网段内的地址

不属于以上任何一种的条目会导致加载失败。用 IP 字面量当主机名时,也会拿去和网段比较。增强模式下,Fake-IP 连接按它对应的域名检查。

顺序 ​

首条命中生效,所以把范围窄的规则放在范围宽的规则前面:

toml
[route]
rules = [
  "DOMAIN,status.corp.example.com,DIRECT",   # 例外放前面
  "DOMAIN-SUFFIX,corp.example.com,office",   # 一般情况放后面
  "FINAL,DIRECT",
]

规则较多时,比较好读的排列是:拦截(REJECT)、进程规则、域名、规则集、IP 与 GeoIP 规则,最后 FINAL。

IP 规则与域名 ​

规则能看到什么,取决于连接从哪里来:

入口域名地址
本地端口,按域名请求(CONNECT github.com:443)有无
本地端口,按地址请求无有
增强模式,Fake-IP 连接有无(Fake-IP 不参与规则匹配)
增强模式,连到 Core 应答过或嗅探到域名的真实地址有有
增强模式,连到 Core 一无所知的地址无有

所以本地端口上的 CONNECT example.cn:443 不会命中 GEOIP,CN,DIRECT,增强模式下用 Fake-IP 应答过的域名也不会。 按域名分流请用域名或 GeoSite 规则。增强模式什么时候发 Fake-IP,见 DNS。

resolve-unknown-domains ​

toml
[route]
resolve-unknown-domains = true   # 默认 false

这个选项让本地 SOCKS5 端口上的域名也能用 IP 规则匹配。只有同时满足下面几条时才会生效:

  • 请求从本地端口以 SOCKS5 方式、按域名进来(HTTP 代理请求从不查询);
  • 这个域名本身没有命中任何规则;
  • Profile 里有 IP 规则(IP-CIDR、IP-CIDR6、IP-SUFFIX、GEOIP、IP-ASN,或包含它们的逻辑规则);
  • Core 的 DNS 模块在运行:开启了增强模式、启用了 [dns].listener,或 Core 以网关方式运行。否则这个选项不会做任何事, 也没有提示。

满足时,Core 同时向系统 DNS 服务器直接查询、并经 FINAL 出站向 nameserver-proxy 查询该域名的地址,取最先返回的可用结果, 最多等 1.5 秒。然后用每个地址重新匹配规则,最靠前的命中规则生效。如果是 DIRECT,Core 直接连这个地址;如果是代理, 发给代理的仍然是域名。都没命中则走 FINAL。

这个选项需要有规则列表(否则报 route.resolve-unknown-domains requires a rule list with FINAL)。 通常直接写一条域名规则比开启查询更好。

Geo 数据 ​

GEOIP、GEOSITE 和 IP-ASN 需要读取数据文件。

toml
[route]
rules = [
  "GEOIP,private,DIRECT",
  "GEOSITE,github,work",
  "IP-ASN,13335,DIRECT",
  "FINAL,DIRECT",
]
geoip = { path = "geoip.dat" }
geosite = { url = "https://example.org/geosite.dat", proxy = "work" }
asn = "asn.txt"
geo-update = "weekly"

这里的 work 必须是一个 [[proxy]],不能是代理组;geoip.dat 和 asn.txt 必须存在。

键说明
geoip、geosite内联表,字段为 type、path、url、proxy
typelocal 或 remote;写了 url 时默认 remote,否则 local
path文件路径,相对路径相对于 Profile 所在目录。远程文件则是下载后存放的位置
url下载地址(仅远程)
proxy经这个节点下载。必须是 Profile 里的 [[proxy]],不能是代理组、DIRECT 或 REJECT
asnASN 数据表的路径,普通字符串
geo-update下载来的 GeoIP/GeoSite 文件最长用多久:daily、weekly(默认)、monthly 或 never

文件格式。 geoip.dat 和 geosite.dat 是 V2Ray 格式,即 v2fly 和 Loyalsoldier 发布的那种。ASN 数据表是文本, 每行一条 AS<编号>,<网段>(AS13335,1.1.1.0/24;可以写 IPv6 网段;# 开头为注释)。空表加载失败。

什么时候需要文件。 只有规则用到 GEOIP / GEOSITE 时(写在 [route].rules 或内联规则集里)才会查找本地的 geoip.dat / geosite.dat;只有用到 IP-ASN 时才查找 ASN 数据表。这时找不到文件就加载失败,报 route.geoip file does not exist; tried … 并列出查找过的每个位置:

  1. 配置的 path(相对于 Profile 所在目录);path 为空时跳过;
  2. 数据目录下的同一相对路径,或 geoip.dat / geosite.dat / asn.txt;
  3. Specola 可执行文件旁的 resources/。

数据目录:Windows 为 %LOCALAPPDATA%\Specola(以服务运行时为 %ProgramData%\Specola),macOS 为 ~/Library/Application Support/com.specola.Specola,Linux 为 ~/.config/specola。

远程文件。 加载 Profile 时,如果远程 GeoIP/GeoSite 文件还没有副本,或副本比 geo-update 规定的更旧,就会下载 (never:只在没有副本时下载)。即使没有规则用到它也会下载。没写 path 时存到数据目录下的 geoip.dat / geosite.dat。 Core 运行期间每小时检查一次,副本过期就重新加载当前 Profile。下载失败或超过 30 秒时保留原有副本并给出警告; 没有副本则加载失败。单个下载最大 32 MB。

不要把 GEOIP、GEOSITE 或 IP-ASN 条目写进规则集文件:只有 Profile 里的规则和内联规则集才会去查找数据文件。

规则集 ​

规则集是一组带名字的条件,通过 RULE-SET 使用。每个规则集在 [route] rule-set 里写成一个内联表:

toml
[route]
rules = [
  "RULE-SET,ads,REJECT",
  "RULE-SET,internal,office",
  "RULE-SET,dev-tools,work,include-children",
  "RULE-SET,lan,DIRECT",
  "FINAL,DIRECT",
]
rule-set = [
  { name = "ads", behavior = "domain", url = "https://lists.example.org/ads.txt" },
  { name = "internal", behavior = "classical", path = "internal-rules.txt" },
  { name = "dev-tools", rules = ["PROCESS-NAME,cargo", "PROCESS-NAME,go"] },
  { name = "lan", rules = ["IP-CIDR,192.168.0.0/16", "DOMAIN-SUFFIX,lan"] },
]

这里的 internal-rules.txt 必须放在 Profile 旁边。

字段说明
name必填且不能重复;即 RULE-SET 的 payload
typeinline、local 或 remote;省略时:有 rules → inline,有 url → remote,否则 local
rules内联条目:TYPE,payload,不写出站
path文件路径,相对路径相对于 Profile 所在目录。远程规则集则是下载后存放的位置
url下载地址
behavior文件格式:classical(默认)、domain 或 ipcidr。内联条目总是 classical
proxy经这个节点下载;必须是 Profile 里的 [[proxy]],不能是代理组
update_interval可以写但不会使用:没有定时刷新

条目。

  • 条目写成 TYPE,payload,不写出站,也不写选项。出站由 RULE-SET 规则决定;内联条目上写了出站会被忽略。
  • include-children 写在 RULE-SET 规则上(RULE-SET,dev-tools,work,include-children),对规则集里的每个进程条目生效。 写在条目上会加载失败。
  • FINAL/MATCH、RULE-SET 和 SUB-RULE 不能作为条目。
  • 内联规则集至少要有一个条目。

来源。

  • 内联:条目直接写在 Profile 里。
  • 本地:加载 Profile 时文件必须存在,即使没有规则用到这个规则集。没写 path 时,在数据目录和可执行文件旁的 resources/ 下找 rule-sets/<name>.txt。
  • 远程:每次加载 Profile 都会下载,在应用里每改一次规则也算一次加载。没写 path 时存为数据目录下的 rule-sets/<name>.txt。下载失败时使用已保存的副本并给出警告;没有副本则加载失败。

规则集文件格式 ​

文件是纯文本,每行一个条目。空行和以 # 或 // 开头的行会被跳过。没有任何条目的文件加载失败。 不支持 YAML 格式的 rule provider,也不支持二进制的 .mrs / .srs 文件。

behavior每行格式对应
classicalTYPE,payload,如 DOMAIN-SUFFIX,example.com 或 AND,((DOMAIN,a.com),(NETWORK,TCP))原样作为规则
domainexample.comDOMAIN-SUFFIX
full:example.comDOMAIN
domain:example.comDOMAIN-SUFFIX
keyword:exampleDOMAIN-KEYWORD
regexp:^ads\.DOMAIN-REGEX
ipcidr10.0.0.0/8、fd00::/8IP-CIDR 或 IP-CIDR6
  • classical 文件里,第一个逗号之后的全部内容都是 payload。末尾的 ,no-resolve 会被去掉;其他第三个字段(例如出站)会报错。
  • domain 文件里的前缀必须小写。Clash 风格的 +.example.com、.example.com、*.example.com 不被识别,永远不会命中; 请写成 example.com。
  • ipcidr 和 classical 文件里要写前缀长度(1.2.3.4/32):只写地址能加载,但永远不会命中。

在应用的规则页里,可以浏览所有规则集、编辑内联规则集的条目、修改远程规则集的 URL。本地和远程规则集的条目在那里是只读的; 新的规则集要在 Profile 里声明。

测试规则 ​

规则页有一个测试功能:输入主机名或 IP(可带 :端口),选择 TCP 或 UDP,就会显示决定去向的规则或 FINAL, 以及目标是否先被 bypass 拦下。

测试只看目标:

  • 域名就按域名匹配,不会解析,所以 IP 和 GeoIP 规则不会命中它。
  • 没有进程,进程规则永远不命中;没有客户端,来源规则永远不命中。
  • 显示的是 FINAL 规则,不是 final-mixed / final-enhanced。

修改如何生效 ​

在应用里保存规则,或者编辑文件后重新激活 Profile,修改会就地生效。Core 不会重启,已有连接继续运行。

  • 新规则表立即替换旧表。仍然存在的代理组会保留原来的选择。
  • 缓存的 DNS 应答会被清空,因为里面带着分流决策;Fake-IP 映射保留。
  • 在 Linux eBPF 上,接管范围按新规则重新生成。
  • 远程规则集重新下载;远程 geo 文件只在到期时下载。
  • 新 Profile 加载失败时,正在运行的配置保持不变,并显示错误。

在应用里关闭的规则保存在 Profile 旁的 <profile>.disabled-rules 文件里,Profile 本身不会被修改。 关闭的规则在列表和统计里保留原来的序号。

排错 ​

[route].rules 里的错误会给出文件、行号和列号、条目序号以及规则原文,例如 work.toml:12:3: route.rules entry #4: route rule has too many fields; rule="…"。

报错原因
route rule is missing payload or target少于三个字段,例如 DOMAIN,example.com
route rule has too many fields超过五个字段,常见于正则里括号外的逗号
Rule requires one nonempty payloadpayload 里有括号外的多余逗号
unsupported route rule option: X第四或第五个字段不是 no-resolve 或 include-children
Unsupported rule type 'X'类型拼错
Rule references unknown outbound: XX 不是 DIRECT、REJECT、节点或代理组;注意大小写
FINAL must be the last rule把 FINAL 移到最后,并且只保留一条
Rule list requires an explicit FINAL target加上 "FINAL,<出站>"
RULE-SET references unknown cache: X[route] rule-set 里没有 name = "X" 的条目
include-children only applies to rules that match a process, or to a RULE-SET选项写在了不含进程条件的规则上
route.geoip file does not exist; tried …列出的位置都没有 GeoIP 文件
Unknown GeoIP category: X / Unknown GeoSite category: X文件里没有这个分类
IPv4 CIDR predicate requires an IPv4 address逻辑规则里的 IP-CIDR 写了 IPv6 网段;请用 IP-CIDR6

规则能加载却从不命中,通常是下面几种情况:

  1. 前面的规则先命中了。 「连接」页面会显示每条连接是被哪条规则决定的。
  2. 连接没有域名,或没有地址。 见 IP 规则与域名。
  3. IP 规则没写前缀长度,如 IP-CIDR,1.2.3.4,X。加上 /32。
  4. final-mixed / final-enhanced 拼错了,被静默替换成了 FINAL。
  5. 增强模式下,应用自己解析了域名(例如用 DNS over HTTPS),Core 根本没看到。见 DNS 和 嗅探。

另见进程规则、DNS 和嗅探。