配置总览

写在最前

ForgeDNS 的配置文件是 YAML。当前顶层结构由四部分组成：

runtime:
  worker_threads: 4

api:
  http: "127.0.0.1:9088"

log:
  level: info
  file: ./forgedns.log

plugins:
  - tag: seq_main
    type: sequence
    args:
      - exec: "forward 1.1.1.1"

其中：

runtime
- 运行时参数。
api
- 管理 API。
log
- 日志输出。
plugins
- 所有插件实例定义。ForgeDNS 通过插件组合完成完整 DNS 流程。

顶层字段

`runtime`

runtime:
  worker_threads: 4

字段说明：

worker_threads
- 含义：Tokio 多线程运行时的 worker 数。
- 默认：未配置时自动取系统可用并行度。
- 限制：不能为 0。

`log`

log:
  level: info
  file: ./forgedns.log
  rotation:
    type: daily
    max_files: 7

字段说明：

level
- 可选值：off trace debug info warn error
- 默认：info
file
- 含义：可选日志文件路径。
- 不配置时仅输出到标准输出。
- 配置后，ForgeDNS 会同时输出到标准输出和日志文件。
- 日志文件内容为 UTF-8 纯文本格式，不写入终端 ANSI 颜色控制码。
rotation
- 含义：日志文件轮转策略。
- 默认：never

rotation 支持以下配置：

type: never
- 不轮转，始终写入同一个文件。
type: minutely
- 按分钟轮转。
type: hourly
- 按小时轮转。
type: daily
- 按天轮转。
type: weekly
- 按周轮转。
- 可选配置 max_files，表示最多保留多少个历史文件；0 表示不自动删除。

`api`

api.http 支持两种写法。

简写：

api:
  http: "127.0.0.1:9088"

详写：

api:
  http:
    listen: "127.0.0.1:9443"
    ssl:
      cert: "/etc/forgedns/api.crt"
      key: "/etc/forgedns/api.key"
      client_ca: "/etc/forgedns/client-ca.crt"
      require_client_cert: true
    auth:
      type: basic
      username: "admin"
      password: "secret"

字段说明：

http.listen
- API 监听地址。
http.ssl.cert
- API 证书文件。
http.ssl.key
- API 私钥文件。
http.ssl.client_ca
- 可选客户端证书 CA。
http.ssl.require_client_cert
- 是否要求双向 TLS。
http.auth
- 当前支持 basic。
- Basic Auth 的请求头编码方式见《管理 API》章节。

校验规则：

listen 不能为空。
cert 和 key 必须成对出现。
require_client_cert: true 时必须提供 client_ca。
basic.username 和 basic.password 都不能为空。

`plugins`

每个插件定义都采用统一结构：

- tag: cache_main
  type: cache
  args:
    size: 4096

通用规则：

tag
- 插件实例唯一标识。
- 不能为空。
- 在整个配置中必须唯一。
type
- 插件类型名。
- 必须与已注册插件工厂一致。
args
- 插件参数。
- 不同插件的参数形态不同，可能是对象、字符串、数组或空值。

四类插件的职责

`server`

作用：接收 DNS 请求并把请求送入某个执行器入口。

特点：

不负责复杂策略判断。
核心配置通常是监听地址、TLS 参数、入口执行器。

`executor`

作用：执行动作。

典型动作包括：

查询上游
生成本地响应
缓存读写
TTL 调整
ECS 处理
回退和并发竞争
观测与系统联动

`matcher`

作用：做条件判断，供 sequence 规则使用。

典型判断维度包括：

查询域名
查询类型
客户端 IP
应答 IP
应答码
环境变量
采样命中
限流状态

`provider`

作用：提供可复用规则集，供 matcher 或其它插件引用。

当前主要有：

domain_set
ip_set
geoip
geosite
adguard_rule

sequence 编排模型

sequence 是 ForgeDNS 的策略中枢。绝大多数非平凡配置都会以它作为总入口。

示例：

- tag: seq_main
  type: sequence
  args:
    - matches:
        - "$lan_clients"
        - "qtype 1"
      exec: "$cache_main"
    - matches: "!$has_resp"
      exec: "$forward_main"
    - exec: "accept"

每条规则支持两个核心字段：

matches
- 一个 matcher 表达式或表达式数组。
- 数组中的所有条件都成立时，本条规则才命中。
exec
- 命中后执行的动作。

引用插件与 quick setup

引用已有插件

使用 $tag 引用已定义插件：

- exec: "$forward_main"
- matches:
    - "$is_internal"
    - "!$has_resp"
  exec: "$cache_main"

quick setup

如果 sequence 中写的不是 $tag，而是 type + 参数 形式，ForgeDNS 会即时构造临时插件。

示例：

- exec: "forward 1.1.1.1 8.8.8.8"
- matches: "qname domain:example.com"
  exec: "ttl 300"

当前常见 quick setup：

matcher
- _true
- _false
- qname ...
- qtype ...
- qclass ...
- client_ip ...
- resp_ip ...
- ptr_ip ...
- cname ...
- mark ...
- env ...
- random ...
- rate_limiter ...
- rcode ...
- has_resp
- has_wanted_ans
- string_exp ...
executor
- forward ...
- ttl ...
- sleep ...
- debug_print ...
- query_summary ...
- metrics_collector ...
- black_hole ...
- drop_resp
- ecs_handler ...
- forward_edns0opt ...
- ipset ...
- nftset ...

sequence 内建控制流

除了调用插件，sequence.args[].exec 还可以直接写内建控制流：

`accept`

立即结束当前 sequence。
这是一次明确的提前停止，因此调用方不会继续执行后续规则。
不会自动生成响应。
典型用法：
- cache、hosts、arbitrary 等前置 executor 已经写入 response 后，直接收口。
- 命中某个分支后明确不希望再进入后续 forward / 副作用逻辑。

`return`

立即结束当前 sequence，把控制权交回调用方。
不会自动生成响应。
如果当前 sequence 是被 jump 调用的，调用方会从 jump 后一条规则继续执行。
如果当前 sequence 是顶层入口，它等价于“提前结束当前规则链”。

`reject [rcode]`

立即基于当前 request 构造一个 DNS 响应，并结束当前 sequence。
默认 rcode 为 REFUSED，所以 reject 等价于拒绝请求。
可以显式写十进制数值，例如：
- reject 2 => SERVFAIL
- reject 3 => NXDOMAIN
当前参数只支持十进制数字，不支持 SERVFAIL、NXDOMAIN 这类名字。
调用方不会继续执行后续规则。

`mark ...`

向 DnsContext.marks 写入一个或多个无符号整数 mark。
支持写法：
- mark 1
- mark 1 2 3
- mark 1,2,3
写入后会继续执行当前 sequence 的下一条规则。
它本身不会生成响应，也不会终止当前 sequence。

`jump seq_tag`

调用另一个 sequence，语义上类似“子过程调用”。
参数必须是目标 sequence 的 tag，且不能写 $ 前缀。
被调用的 sequence 如果：
- 正常执行到尾部，当前 sequence 会从 jump 的下一条规则继续。
- 中途执行了 return，当前 sequence 也会从 jump 的下一条规则继续。
- 中途执行了 accept、reject 或其它返回 Stop 的操作，当前 sequence 也会一起停止，不再继续后续规则。

`goto seq_tag`

直接把控制权转交给另一个 sequence，语义上类似“单向跳转”。
参数必须是目标 sequence 的 tag，且不能写 $ 前缀。
当前 sequence 在执行 goto 后不会恢复：
- 目标 sequence 正常跑到尾部，不回到 goto 后面的规则。
- 目标 sequence 执行 return，该 return 会继续向外层传播，但同样不回到 goto 后面的规则。
- 目标 sequence 执行 accept / reject / 其它 Stop，结果也直接向外层传播。
适合把请求永久移交给另一个策略分支。

示例：

- matches: "$rate_ok"
  exec: "mark 100"
- matches: "!$rate_ok"
  exec: "reject 2"

jump / goto 的区别示例：

- tag: child_seq
  type: sequence
  args:
    - exec: "mark 2"
    - exec: "return"

- tag: parent_jump
  type: sequence
  args:
    - exec: "mark 1"
    - exec: "jump child_seq"
    - exec: "mark 3"

- tag: parent_goto
  type: sequence
  args:
    - exec: "mark 1"
    - exec: "goto child_seq"
    - exec: "mark 3"

parent_jump 最终会留下 1,2,3，因为 jump 调用结束后会继续执行下一条。
parent_goto 最终只会留下 1,2，因为控制权不会回到 goto 之后。

通用规则语法

域名规则

以下规则会出现在 qname、cname、domain_set、hosts、redirect 等插件中：

full:example.com
- 完整匹配。
domain:example.com
- 后缀匹配。
keyword:cdn
- 子串匹配。
regexp:^api[0-9]+\\.example\\.com$
- 正则匹配。
example.com
- 未写前缀时，通常等价于 domain:example.com。

IP 规则

以下规则会出现在 client_ip、resp_ip、ptr_ip、ip_set 等插件中：

单个 IP：1.1.1.1
网段：192.168.0.0/16
IPv6 网段：2400:3200::/32

provider 引用

支持在 matcher 或 provider 参数中引用 provider：

$tag
- 引用已定义且具备对应匹配能力的 provider。
- 例如域名场景可引用 domain_set、geosite。
- 例如 IP 场景可引用 ip_set、geoip。
&/path/to/file
- 直接从文件加载规则。

示例：

args:
  - "domain:example.com"
  - "$core_domains"
  - "&/etc/forgedns/domains.txt"

上游统一结构

forward 的 upstreams 使用统一的 UpstreamConfig。

示例：

upstreams:
  - addr: "udp://1.1.1.1:53"
  - addr: "https://resolver.example/dns-query"
    bootstrap: "8.8.8.8:53"
    timeout: 5s
    enable_http3: true

常用字段：

addr
- 上游地址。
- 未写协议时按 UDP 处理。
- 支持 udp://、tcp://、tcp+pipeline://、tls://、tls+pipeline://、quic://、doq://、https://、doh://、h3://。
- DoH 应写完整路径，例如 https://resolver.example/dns-query。
dial_addr
- 指定实际连接 IP，但仍保留 addr 中的主机名用于 SNI/校验。
port
- 覆盖端口。
bootstrap
- 当上游地址是域名时，用于解析上游域名的引导 DNS。
bootstrap_version
- 4 或 6。
socks5
- SOCKS5 代理。
- 支持 host:port 与 user:pass@host:port。
- IPv6 需写成 [addr]:port。
idle_timeout
- 空闲连接超时，单位秒。
max_conns
- 连接池最大连接数。
insecure_skip_verify
- 跳过 TLS 证书校验，仅建议测试环境使用。
timeout
- 单次查询超时，默认 5s。
enable_pipeline
- TCP/DoT 请求流水线。
enable_http3
- DoH 使用 HTTP/3。
so_mark
- Linux SO_MARK。
bind_to_device
- Linux SO_BINDTODEVICE。

写在最前​

顶层字段​

runtime​

log​

api​

plugins​

四类插件的职责​

server​

executor​

matcher​

provider​

sequence 编排模型​

引用插件与 quick setup​

引用已有插件​

quick setup​

sequence 内建控制流​

accept​

return​

reject [rcode]​

mark ...​

jump seq_tag​

goto seq_tag​

通用规则语法​

域名规则​

IP 规则​

provider 引用​

上游统一结构​

写在最前

顶层字段

`runtime`

`log`

`api`

`plugins`

四类插件的职责

`server`

`executor`

`matcher`

`provider`

sequence 编排模型

引用插件与 quick setup

引用已有插件

quick setup

sequence 内建控制流

`accept`

`return`

`reject [rcode]`

`mark ...`

`jump seq_tag`

`goto seq_tag`

通用规则语法

域名规则

IP 规则

provider 引用

上游统一结构