Skip to content
English下载

模块 ​

模块是一个 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 来显示。

手动使用模块 ​

  1. 在 Profiles 目录里建一个 modules 文件夹,把模块文件放进去。

  2. 在 Profile 旁边创建 <Profile 文件名>.modules,例如 work.toml.modules,每行写一个模块文件名,按合并顺序排列:

    text
    home-lan.toml
    my-rules.toml
  3. 重新激活这个 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 页。

另见分流规则、代理,以及介绍如何复用节点和规则列表的 Provider。