分流规则
在 route-mode = "rule" 下,每条连接按 [route].rules 自上而下匹配,第一条命中的规则决定连接去向。 一条都没命中时,由 FINAL 决定。
[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 里定义的节点或代理组。
一条连接怎么分流
bypass。 目标在绕过列表里就直接DIRECT,后面什么都不看。- 路由模式。
direct全部直连,global全部交给global-proxy。只有rule模式才读规则列表。 - 规则,自上而下,第一条命中的生效。
FINAL;设置了final-mixed/final-enhanced时用它们。
列表里的先后顺序是唯一的优先级。域名规则不会因为是域名规则就压过 IP 规则,谁在前谁生效。
语法
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-REGEX | PCRE2 正则表达式 | 'DOMAIN-REGEX,^ci-[0-9]+\.example\.com$,work' |
GEOSITE | GeoSite 文件中的一个分类 | 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-CIDR | IPv4 网段 | IP-CIDR,10.0.0.0/8,DIRECT |
IP-CIDR6 | IPv6 网段 | IP-CIDR6,fd00::/8,DIRECT |
IP-SUFFIX | 地址文本的结尾 | IP-SUFFIX,.255,REJECT |
IP-ASN | 某个自治系统的地址 | IP-ASN,13335,DIRECT |
GEOIP | GeoIP 文件中的一个国家或分类 | 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-b | DST-PORT,22,DIRECT、DST-PORT,6881-6889,DIRECT |
NETWORK | 传输协议:TCP、UDP 或 ICMP | NETWORK,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-b | SRC-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] 里有两个可选键,可以按入口替换它:
[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-enhanced | TUN 或 eBPF 接管的连接,以及它们的 DNS 决策 | ""(用 FINAL) |
- 值可以是
DIRECT、REJECT、节点或代理组。 - 写了不存在的名字会被静默忽略,改用
FINAL,不会有任何提示。请检查拼写。 - 在 Linux eBPF 上,
final-enhanced还决定没有规则命中的流量是否会被接管,见 eBPF 捕获哪些连接。 - 规则页的测试和规则列表里的
FINAL行显示的始终是FINAL规则本身。
bypass
[route]
bypass = ["localhost", "*.local", "127.0.0.0/8", "192.168.0.0/16", "::1/128"]目标在绕过列表里时,会在读取路由模式和规则之前直接走 DIRECT,对本地端口、TUN 和 eBPF 都生效, 任何路由模式下都生效,包括 global。
| 条目 | 匹配 |
|---|---|
localhost | 恰好这个域名(忽略大小写和末尾的点) |
*.local | local 下的域名,不含 local 本身 |
10.1.2.3、fd00::1 | 这个地址 |
192.168.0.0/16、fd00::/8 | 网段内的地址 |
不属于以上任何一种的条目会导致加载失败。用 IP 字面量当主机名时,也会拿去和网段比较。增强模式下,Fake-IP 连接按它对应的域名检查。
顺序
首条命中生效,所以把范围窄的规则放在范围宽的规则前面:
[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
[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 需要读取数据文件。
[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 |
type | local 或 remote;写了 url 时默认 remote,否则 local |
path | 文件路径,相对路径相对于 Profile 所在目录。远程文件则是下载后存放的位置 |
url | 下载地址(仅远程) |
proxy | 经这个节点下载。必须是 Profile 里的 [[proxy]],不能是代理组、DIRECT 或 REJECT |
asn | ASN 数据表的路径,普通字符串 |
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 … 并列出查找过的每个位置:
- 配置的
path(相对于 Profile 所在目录);path为空时跳过; - 数据目录下的同一相对路径,或
geoip.dat/geosite.dat/asn.txt; - 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 里写成一个内联表:
[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 |
type | inline、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 | 每行格式 | 对应 |
|---|---|---|
classical | TYPE,payload,如 DOMAIN-SUFFIX,example.com 或 AND,((DOMAIN,a.com),(NETWORK,TCP)) | 原样作为规则 |
domain | example.com | DOMAIN-SUFFIX |
full:example.com | DOMAIN | |
domain:example.com | DOMAIN-SUFFIX | |
keyword:example | DOMAIN-KEYWORD | |
regexp:^ads\. | DOMAIN-REGEX | |
ipcidr | 10.0.0.0/8、fd00::/8 | IP-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 payload | payload 里有括号外的多余逗号 |
unsupported route rule option: X | 第四或第五个字段不是 no-resolve 或 include-children |
Unsupported rule type 'X' | 类型拼错 |
Rule references unknown outbound: X | X 不是 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 |
规则能加载却从不命中,通常是下面几种情况:
