跳到主要内容

域名 provider

这些 provider 管理静态、动态、V2Ray geosite 或 AdGuard 形式的域名规则资产。

domain_set​

作用​

提供高性能域名规则集合，可被 qname、cname 等插件引用。

配置示例​

- tag: core_domains
  type: domain_set
  args:
    exps:
      # 精确匹配
      - "full:login.example.com"
      # 后缀域名匹配
      - "domain:example.com"
      # 关键字匹配
      - "keyword:cdn"
      # 正则匹配
      - "regexp:^api[0-9]+\\.example\\.net$"
      # 不带前缀时按域名规则解析
      - "static.example.org"
    files:
      # 从文件合并更多规则
      - "/etc/oxidns/domains.txt"
    sets:
      # 复用其它具备域名匹配能力的 provider
      - "shared_domains"
      - "shared_geosite"

配置项​

exps​

  • 类型：array；必填：否；默认值：空数组
  • 作用：定义内联域名表达式列表。
  • 示例：
    • - "full:example.com"
    • - "domain:example.com"
    • - "keyword:cdn"
    • - "regexp:^api[0-9]+\\.example\\.net$"
  • 支持内容：
    • full:
    • domain:
    • keyword:
    • regexp:
    • 无前缀域名
  • 运行影响：
    • 在初始化阶段编译为可直接匹配的规则集合。

files​

  • 类型：array；必填：否；默认值：空数组
  • 作用：指定外部规则文件路径列表。
  • 示例：- "/etc/oxidns/domains.txt"
  • 文件要求：
    • 每行一条规则。
    • 空行与注释行会被忽略。
  • 运行影响：
    • 文件内容会在初始化或 reload_provider 时重新读取，并编译进当前 provider 的本地 matcher。

sets​

  • 类型：array；必填：否；默认值：空数组
  • 作用：引用其它具备域名匹配能力的 provider。
  • 示例：- "shared_domain_set"
  • 约束：
    • 允许引用任意具备域名匹配能力的 provider，例如 domain_set、geosite、adguard_rule。
  • 运行影响：
    • 当前 provider 只保存被引用 provider 的稳定句柄，不复制其规则。
    • 下游 provider 单独 reload 后，当前 domain_set 无需 reload 即可看到新结果。

行为说明​

  • 初始化或 reload 时只编译本地 exps / files。
  • 运行时按“本地 matcher -> sets 中声明顺序的 provider”依次判断。
  • 不再把被引用 provider 的规则文本或编译结果复制进当前 provider。

支持的规则格式​

  • full:example.com
  • domain:example.com
  • keyword:cdn
  • regexp:^api\\.example\\.com$
  • example.com

典型用途​

  • 共享核心域名列表。
  • 把本地手写规则和共享 provider 组合成一个统一入口。
注意事项
  • sets 只能引用具备域名匹配能力的 provider。
  • 若修改了 sets 拓扑、tag 或 provider 配置结构，仍需要应用级 reload；reload_provider 只刷新当前 provider 的既有配置和外部数据文件。

dynamic_domain_set​

实验性插件（v1.2.0 引入）

dynamic_domain_set 在 v1.2.0 首次发布，目前处于实验阶段：相关配置可能在后续版本调整。生产部署前请评估学习速率与磁盘写入对持久化层的影响。

作用​

提供可写的本地域名规则集合。它把规则持久化到一个文本文件，并通过热快照提供和 domain_set 相同的域名匹配能力，适合配合 learn_domain 自动学习放行或拦截列表。

dynamic_domain_set 不使用 SQLite，也不会改造 domain_set 的只读聚合职责。

配置示例​

- tag: learned_allow
  type: dynamic_domain_set
  args:
    path: "/etc/oxidns/learned-allow.txt"
    bootstrap_rules:
      - "domain:example.org"
    queue_size: 1024
    batch_size: 256
    flush_interval_ms: 200

配置项​

path​

  • 类型：string；必填：是
  • 作用：指定该 provider 管理的本地规则文件路径。
  • 运行影响：
    • 文件不存在时会自动创建。
    • 文件存在时会在启动和 reload_provider 时读取。

bootstrap_rules​

  • 类型：array；必填：否；默认值：空数组
  • 作用：当 path 文件不存在时写入初始规则。
  • 支持 full:、domain:、keyword:、regexp: 和无前缀域名；无前缀规则按 domain: 解析。

queue_size​

  • 类型：integer；必填：否；默认值：1024
  • 作用：定义自动学习写入队列大小。

batch_size​

  • 类型：integer；必填：否；默认值：256
  • 作用：定义后台 append 的批量 flush 阈值。

flush_interval_ms​

  • 类型：integer；必填：否；默认值：200
  • 作用：定义后台 append 的定时 flush 间隔。

文件格式​

  • 一行一条规则。
  • 支持 full:example.com、domain:example.com、keyword:cdn、regexp:^api\\.example\\.com$、example.com。
  • 空行和以 # 开头的注释行会在加载时忽略。
  • 域名会规范化为小写并移除尾部 .。

管理 API​

这些接口在默认管理前缀下暴露为 /api/plugins/<tag>/...：

方法路径作用
GET/rules?limit=500&cursor=0分页列出当前规则，返回 total、next_cursor、rules。
POST/rules添加规则，body 示例：{ "rules": ["example.com"], "rule_kind": "full" }。
DELETE/rules删除规则，body 示例：{ "rules": ["full:example.com"] }。
POST/rules/clear清空该动态规则文件并替换为空快照。
POST/reload通过 provider 通用 reload 重新读取文件。

行为说明​

  • contains_name / contains_question 只读取当前热快照，不做文件 I/O。
  • learn_domain 或 API 写入后会更新本 provider 快照，引用它的 qname 或父级 domain_set.sets 无需 reload 即可看到新结果。
  • 自动学习 append 默认异步批量落盘；API add/delete/clear 会等待文件写入和快照替换完成。
  • 外部手工编辑文件不会被自动 watcher 感知，需要调用 reload_provider 或 POST /api/plugins/<tag>/reload。
  • remove/clear 会重写该插件管理文件；API 重写不保证保留手写注释。
注意事项
  • path 应视为 dynamic_domain_set 的 machine-managed 文件。
  • 如果需要分别维护 allow 与 block，请配置两个独立的 dynamic_domain_set 实例。

geosite​

作用​

从 v2ray-rules-dat 的 geosite.dat 中提取一个或多个 code，并编译成可复用域名规则集合。

配置示例​

- tag: geosite_cn
  type: geosite
  args:
    file: "/etc/oxidns/geosite.dat"
    selectors:
      - "cn"
      - "geolocation-!cn"

配置项​

file​

  • 类型：string；必填：是
  • 作用：指定 geosite.dat 文件路径。

selectors​

  • 类型：array；必填：否；默认值：空数组
  • 作用：按 code 提取部分规则，也支持 code@attribute 语法按 attribute 进一步过滤。
  • 行为：
    • 大小写不敏感精确匹配。
    • 多个 selector 取并集。
    • 未设置或空数组时，加载整个 dat 文件的全部规则并集。
    • 例如 category-games@cn 表示只提取 category-games 中带 cn attribute 的规则。

组合示例​

按 code 划分域名策略，并直接供不同 matcher 使用：

plugins:
  - tag: geosite_cn
    type: geosite
    args:
      file: "/etc/oxidns/geosite.dat"
      selectors: ["cn"]

  # `geolocation-!cn` 是 geosite.dat 中的一个 code，不是通用的排除语法。
  - tag: geosite_non_cn
    type: geosite
    args:
      file: "/etc/oxidns/geosite.dat"
      selectors: ["geolocation-!cn"]

  - tag: match_cn_domain
    type: qname
    args: ["$geosite_cn"]

  - tag: match_non_cn_question
    type: question
    args: ["$geosite_non_cn"]

按 attribute 过滤某个 code；实际可用的 code 和 attribute 取决于所使用的 dat 版本：

- tag: geosite_games_cn
  type: geosite
  args:
    file: "/etc/oxidns/geosite.dat"
    selectors:
      - "category-games@cn"

- tag: match_games_cn
  type: qname
  args: ["$geosite_games_cn"]

把 geosite 与本地规则合并为一个可复用入口：

- tag: domestic_domains
  type: domain_set
  args:
    exps:
      - "full:internal.example"
    sets:
      - "geosite_cn"

- tag: match_domestic_domain
  type: qname
  args: ["$domestic_domains"]

行为说明​

  • Plain 会映射为 keyword: 规则。
  • Regex 会映射为 regexp: 规则。
  • RootDomain 会映射为 domain: 规则。
  • Full 会映射为 full: 规则。
  • 可被 qname、cname、question 直接引用，也可被 domain_set.sets 继续聚合。
  • 可通过 reload_provider 或 POST /plugins/<tag>/reload 独立刷新 dat 文件内容。
  • 如需在运行前把部分 selector 预导出成文本规则文件，可使用 oxidns export-dat --kind geosite。
Selector 注意事项
  • selector 只做 code 的精确匹配；geolocation-!cn 中的 ! 属于 code 文本，不表示“排除 cn”。
  • code@attribute 仅保留带有该 attribute 的规则；若同一 provider 同时写入 code 和 code@attribute，无 attribute 的 code 会加载该 code 的全部规则。
  • 指定的 selector 未命中 entry 或未产生规则时，启动或 provider reload 会失败。可先用 oxidns export-dat --kind geosite --selector <selector> 验证数据文件中是否存在它。

adguard_rule​

作用​

提供 AdGuard Home DNS 规则子集的可复用 provider。

这个 provider 提供两种语义：

  • contains_question：完整请求 question 求值，支持 dnstype
  • contains_name：name-only 投影求值，会忽略所有 dnstype 规则

配置示例​

- tag: ad_rules
  type: adguard_rule
  args:
    rules:
      # 基础拦截规则
      - "||ads.example.com^"
      # 例外规则
      - "@@||safe.ads.example.com^"
      # 带 dnstype / important / denyallow 的复杂规则也可以直接内联
      - "||cdn.example.com^$dnstype=A|AAAA,important,denyallow=cdn-safe.example.com"
    files:
      # 也可以从外部规则文件加载
      - "/etc/oxidns/adguard.txt"

行为说明​

  • 支持：基础域名规则、@@、important、badfilter、denyallow、请求侧 dnstype
  • 不支持但会汇总 warning 并跳过：URL/路径过滤规则、/etc/hosts 风格规则、页面元素过滤规则、dnsrewrite、$client、$ctag、未知 modifier
  • 初始化与 reload 会流式读取规则文件；跳过日志按原因汇总，并且每类最多记录 5 个规则样例
  • 完整优先级顺序为：
    • important 例外
    • important 拦截
    • 普通例外
    • 普通拦截

典型用途​

  • 配合 qname matcher 做 name-only 域名投影匹配。
  • 配合 question matcher 复用 AdGuard 规则文件。
  • 在 provider 层统一管理复杂的 AdGuard 域名拦截语义。
注意事项
  • qname / cname 这类 name-only matcher 会走 contains_name 语义，因此会忽略带 dnstype 的规则。
  • adguard_rule 可以被 domain_set.sets 继续组合；由于命中逻辑保留在运行时求值，@@、important、denyallow 和 dnstype 的优先级不会在组合后丢失。