模块
模块是一个 TOML 文件,Profile 加载时 Specola 把它合并到 Profile 之上。适合放两类改动:想在多个 Profile 里共用的, 或者想和某个会被整体替换的 Profile 分开保存的。比如你自己的规则、家里的节点、额外的 DNS hosts。
text
profiles/
├── work.toml the profile
├── work.toml.modules "home-lan.toml" — the modules work.toml applies
└── modules/
└── home-lan.toml the module模块的写法和 Profile 一样,只写它要新增或修改的内容:
toml
# modules/home-lan.toml
[[proxy]]
name = "home"
type = "socks5"
server = "nas.example.org"
port = 1080
[route]
rules = [
"DOMAIN-SUFFIX,home.arpa,DIRECT",
"DOMAIN-SUFFIX,media.example.org,home",
]
[dns]
hosts = { "nas.home.arpa" = "192.168.1.10" }这是一个片段:只有合并进一个规则以 FINAL 结尾的 Profile 后才能加载。
在应用里使用模块
在 Profiles 页选中一个 Profile,Modules(模块)列表会显示 modules 目录里的所有模块。
- New module(新建模块)创建一个空的模块文件。你输入的名字就是文件名(
Home LAN会变成Home LAN.toml)。 - 打开某个模块的开关,就把它应用到当前 Profile。拖动模块可以调整合并顺序:从上到下依次应用,靠后的覆盖靠前的。
- Apply and reload(应用并重新加载)保存列表;如果这个 Profile 正在使用,会重新加载它。
- Open the module file(打开模块文件)用编辑器打开文件。在 Rules 页也可以编辑和关闭模块里的规则: 它们排在 Profile 自己的规则前面,并标出模块名。
- Delete module(删除模块)把文件移到
modules/.removed/,并把它从所有 Profile 的列表中去掉。
应用创建的模块开头带一个 [metadata] 表,里面是显示名称。Core 会忽略模块里的 [metadata],只有应用读取其中的 name 来显示。
手动使用模块
在 Profiles 目录里建一个
modules文件夹,把模块文件放进去。在 Profile 旁边创建
<Profile 文件名>.modules,例如work.toml.modules,每行写一个模块文件名,按合并顺序排列:texthome-lan.toml my-rules.toml重新激活这个 Profile。
各平台的 Profiles 目录见快速开始。
列表文件的规则:
- 每行是
modules/里的一个文件名,必须以.toml结尾,不能以.开头,不能包含/、\或:。不符合的行会被跳过, 重复的名字也会被跳过。没有注释语法。 - 列出了但文件不存在的模块会被跳过,并告警
Module '<名字>' is missing; it was skipped。 - 不是合法 TOML 的模块会导致 Profile 加载失败:
Module '<名字>': <错误>。 - 列表为空或没有列表文件时,不应用任何模块。
同一个模块可以被任意多个 Profile 列出。
合并规则
模块按列表顺序逐个应用,每个都叠加在此前的结果之上。最后,合并结果像一个普通 Profile 文件一样加载。
| 内容 | 合并方式 |
|---|---|
[[proxy]] | 按 name:与已有节点同名时,整体替换它,位置不变;新名字追加到末尾 |
[[proxy-group]] | 按 name,方式同上 |
[route] rule-set | 按 name,方式同上 |
[route] rules | 模块的规则插到此前所有规则的前面 |
表([general]、[dns]、[route]、[sniffer]、[enhanced-mode],以及其中的子表,如 dns.listener、dns.hosts、enhanced-mode.tun) | 逐个键合并;模块里写了的键覆盖原值 |
其他数组(bypass、nameserver-proxy、routes、protocols 等) | 整体替换 |
| 其他值 | 替换 |
模块顶层的 [metadata]、module、modules | 忽略 |
由此可以推出:
- 靠后的模块优先。 靠后的模块覆盖靠前模块的值,它的规则也排在更前面,按「第一条命中的生效」同样占先。 列表是
a.toml、b.toml时,最终规则顺序为:b的规则、a的规则、Profile 的规则。 - 节点、代理组、规则集是整体替换的。 想改 Profile 里某个节点的一个字段,模块里必须写出完整的节点。
- 表会合并,数组不会。 模块的
dns.hosts条目会加到 Profile 的条目里;模块的bypass列表则会替换 Profile 的列表。 - 模块文件可以用数组写节点:
proxies = [ { name = "...", ... } ],代替[[proxy]]表。同一个文件里不要两种写法混用。
常见的坑
- 不要在模块里写
FINAL,如果它要应用到一个有规则的 Profile 上。模块的规则排在前面,它的FINAL就会落到中间, Profile 加载失败,提示FINAL must be the last rule。 - 名字必须保持唯一。 模块里的节点和 Profile 里的代理组同名(或反过来)会校验失败。只有真想替换时才用相同的名字。
- 相对路径以 Profile 所在目录为基准,而不是
modules/。模块里写path = "rule-sets/mine.txt"的本地规则集, 会先在 Profile 旁边找,再到数据目录、Core 旁边的resources/找。 - 合并结果作为整体检查。 未知字段、指向不存在节点的规则、Core 不接受的段落,不管来自哪个文件都会让 Profile 加载失败, 而错误信息不会指出是哪个文件。
- 改动在激活时生效。 编辑模块或列表对正在运行的 Core 没有影响,要重新激活 Profile 才会生效;和其他 Profile 改动一样就地应用。
- 被关闭的规则(
<profile>.disabled-rules)按规则文本匹配,所以文本相同的模块规则同样会被关闭。
检查合并结果
--test-config 合并模块的方式和激活时完全一样:
bash
specola-core --test-config --config work.toml缺失的模块会在日志输出里显示告警 Config: Module '...' is missing; it was skipped。想看最终的规则顺序, 激活 Profile 后打开应用的 Rules 页。
