配置参考

简体中文

English

简体中文

English

外观

[Plugin] 插件 ​

本节用于配置插件。插件内容采用标准 INI 格式，与主配置文件格式完全相同。系统支持通过插件拆分配置，并支持根据网络环境（如 Wi-Fi 或蜂窝网络）条件启用。

基本原理 ​

text
┌────────────────────────────────────────────────────────┐
│ 插件 1 (高优先级，例如匹配特定 SSID 的办公网络配置)       │
├────────────────────────────────────────────────────────┤
│ 插件 2 (低优先级，例如通用远程配置)                      │
├────────────────────────────────────────────────────────┤
│ 主配置文件 (基底配置，优先级最低)                        │
└────────────────────────────────────────────────────────┘
                           │
                           ▼ 执行配置合并 (Merge)
┌────────────────────────────────────────────────────────┐
│ 运行时有效配置                                         │
└────────────────────────────────────────────────────────┘
  1. 配置格式相同 插件内容格式与主配置文件完全相同（标准 INI 格式）。
  2. 多插件合并 主配置作为基底，启用的插件按照声明顺序生效，声明靠前优先级高于靠后；系统合并时以主配置为基底，由低优先级至高优先级依次应用。
  3. 网络条件激活 插件启用状态取决于全局开关与 subnet 网络匹配条件。网络环境变动时，系统自动更新匹配状态并动态加载或卸载相应插件配置。

语法声明 ​

[Plugin] 章节中每行定义一个独立的插件项：

ini
name = source, [options...]

语法要素说明 ​

  • name：插件的唯一标识名称。同一主配置文件内必须唯一。
  • source：插件文件的来源。支持本地文件路径与远程网络地址：
    • 本地路径：支持绝对路径，或相对于当前主配置文件所在目录的相对路径（如 ./plugins/office.conf）。
    • 远程地址：以 http:// 或 https:// 开头的 URL。包含英文逗号或等号时，需使用双引号整体包裹。
  • options：可选参数列表，多个参数以英文逗号分隔，采用键值对格式（key=value）。

参数详解 ​

  • source（本地路径或 HTTP/HTTPS URL，必填） 插件配置文件的获取源。相对路径以主配置文件所在目录为基准。
  • subnet（网络条件字符串，未设置） 激活该插件所需的网络环境匹配条件。未配置时在全局开关开启状态下始终处于激活状态。
  • update-interval（整数，单位：秒，默认值 86400，仅远程） 远程 HTTP/HTTPS 插件的后台自动更新周期；本地文件插件不生效。

网络环境匹配条件 ​

通过 subnet 参数，可将插件的生效范围限定在特定网络环境下。语法格式为 前缀:匹配模式：

  • ssid:（文本字符串，支持通配符 * 与 ?） 匹配当前接入的 Wi-Fi 名称（SSID），例如 ssid:Company-WiFi 或 ssid:Office-*。
  • bssid:（MAC 地址格式，支持通配符 * 与 ?） 匹配当前连接的无线接入点硬件地址（BSSID）。
  • type:（枚举值，大小写不敏感） 匹配主网络接口连接类型，可选 CELLULAR、WIFI、WIRED、LOOPBACK、OTHER，例如 type:CELLULAR 匹配蜂窝数据。
  • gateway:（IP 地址字符串） 匹配默认网关 IP（预留配置项，当前版本作为占位保留）。
  • (无前缀)（文本字符串，支持通配符） 缺少显式前缀时，系统默认按 Wi-Fi SSID 模式处理。

合并机制与覆盖行为 ​

优先级 ​

多个激活插件按声明顺序生效，声明靠前优先级高于靠后；主配置优先级最低（作为基底）。插件内不支持嵌套声明 [Plugin]（忽略）。

章节与值类型合并行为 ​

不同配置类型与章节在合并时遵循如下行为规则：

  1. 单值标量（如 [General] 中的 log-level 等）
    • 默认直接覆盖底层对应配置。
  2. 多值/列表数组（如 skip-proxy、dns-server 等列表型键值）
    • 默认行为：整体替换（Replace）；
    • %APPEND% <值>：追加到现有列表末尾；
    • %INSERT% <值>：插入到现有列表头部。
  3. 字典项章节（[Proxy]、[Proxy Group]、[Host]、[Script]、[Proxy Resource]）
    • 按项名称（键）匹配：同名项覆盖现有定义；新名称项追加到该章节；
    • 支持在章节首行使用 %INSERT% 或 %APPEND% 控制新项的插入或追加位置。
  4. 有序规则列表（[Rule]、[Response]、[URL Rewrite]、[Header Rewrite]）
    • 默认行为为插入（%INSERT%），即插件规则默认优先插入到现有规则列表顶部；
    • 可在章节首行显式声明 %APPEND% 将规则追加到现有规则末尾；对于 [Rule] 规则列表，声明 %APPEND% 时规则永远追加在 FINAL 规则之前，确保追加规则始终能够参与匹配，FINAL 规则始终保持在规则列表末尾作为最终兜底；
    • 支持声明 %INSERT% 显式标明头部插入。

配置示例 ​

基础配置 ​

主配置文件 (main.conf)：

ini
[General]
log-level = info
dns-server = system

[Plugin]
# 1. Wi-Fi 网络插件
Office = ./plugins/office.conf, subnet=ssid:Corp-Office-*

# 2. 蜂窝网络插件
Cellular = ./plugins/cellular.conf, subnet=type:CELLULAR

# 3. 远程配置插件
AdBlock = "https://rules.example.com/adblock.conf", update-interval=43200

[Proxy]
DefaultProxy = socks, 198.51.100.1, 1080

[Rule]
FINAL,DefaultProxy

局部网络插件 (plugins/office.conf)：

ini
[Proxy]
# 局域网代理服务器，同名覆盖主配置
CorpProxy = socks, 10.0.0.1, 1080

[Rule]
# 规则插入到主配置规则前方（默认前插）
DOMAIN-SUFFIX,corp.internal,DIRECT
IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
DOMAIN-SUFFIX,oa.example.com,CorpProxy

蜂窝网络插件 (plugins/cellular.conf)：

ini
[General]
# 处于蜂窝移动网络时，将日志等级调整为 warn
log-level = warn