docs: add evaluate action, response matching fields, and deprecation notices

2026-04-11 17:47:20 +10:00 · 2026-03-29 14:15:47 +08:00
parent b05f58b469
commit 1913376113
6 changed files with 297 additions and 17 deletions
--- a/docs/configuration/dns/rule.md
+++ b/docs/configuration/dns/rule.md
@@ -4,8 +4,15 @@ icon: material/alert-decagram

 !!! quote "Changes in sing-box 1.14.0"

+    :material-plus: [match_response](#match_response)  
+    :material-plus: [response_rcode](#response_rcode)  
+    :material-plus: [response_answer](#response_answer)  
+    :material-plus: [response_ns](#response_ns)  
+    :material-plus: [response_extra](#response_extra)  
    :material-plus: [source_mac_address](#source_mac_address)  
-    :material-plus: [source_hostname](#source_hostname)
+    :material-plus: [source_hostname](#source_hostname)  
+    :material-delete-clock: [ip_accept_any](#ip_accept_any)  
+    :material-delete-clock: [rule_set_ip_cidr_accept_empty](#rule_set_ip_cidr_accept_empty)

 !!! quote "Changes in sing-box 1.13.0"

@@ -94,12 +101,6 @@ icon: material/alert-decagram
          "192.168.0.1"
        ],
        "source_ip_is_private": false,
-        "ip_cidr": [
-          "10.0.0.0/24",
-          "192.168.0.1"
-        ],
-        "ip_is_private": false,
-        "ip_accept_any": false,
        "source_port": [
          12345
        ],
@@ -171,7 +172,16 @@ icon: material/alert-decagram
          "geosite-cn"
        ],
        "rule_set_ip_cidr_match_source": false,
-        "rule_set_ip_cidr_accept_empty": false,
+        "match_response": false,
+        "ip_cidr": [
+          "10.0.0.0/24",
+          "192.168.0.1"
+        ],
+        "ip_is_private": false,
+        "response_rcode": "",
+        "response_answer": [],
+        "response_ns": [],
+        "response_extra": [],
        "invert": false,
        "outbound": [
          "direct"
@@ -180,7 +190,9 @@ icon: material/alert-decagram
        "server": "local",

        // Deprecated
-        
+
+        "ip_accept_any": false,
+        "rule_set_ip_cidr_accept_empty": false,
        "rule_set_ipcidr_match_source": false,
        "geosite": [
          "cn"
@@ -477,6 +489,17 @@ Make `ip_cidr` rule items in rule-sets match the source IP.

 Make `ip_cidr` rule items in rule-sets match the source IP.

+#### match_response
+
+!!! question "Since sing-box 1.14.0"
+
+Enable response-based matching. When enabled, this rule matches against DNS response data
+(set by a preceding [`evaluate`](/configuration/dns/rule_action/#evaluate) action)
+instead of only matching the original query.
+
+Required for `response_rcode`, `response_answer`, `response_ns`, `response_extra` fields.
+Also required for `ip_cidr` and `ip_is_private` when `legacyDNSMode` is disabled.
+
 #### invert

 Invert match result.
@@ -547,24 +570,69 @@ Match GeoIP with query response.

 Match IP CIDR with query response.

+When `legacyDNSMode` is disabled, `match_response` must be set to `true`.
+
 #### ip_is_private

 !!! question "Since sing-box 1.9.0"

 Match private IP with query response.

+When `legacyDNSMode` is disabled, `match_response` must be set to `true`.
+
 #### rule_set_ip_cidr_accept_empty

 !!! question "Since sing-box 1.10.0"

+!!! failure "Deprecated in sing-box 1.14.0"
+
+    `rule_set_ip_cidr_accept_empty` is deprecated and will be removed in sing-box 1.16.0.
+    Only supported in `legacyDNSMode`.
+
 Make `ip_cidr` rules in rule-sets accept empty query response.

 #### ip_accept_any

 !!! question "Since sing-box 1.12.0"

+!!! failure "Deprecated in sing-box 1.14.0"
+
+    `ip_accept_any` is deprecated and will be removed in sing-box 1.16.0.
+    Only supported in `legacyDNSMode`. Use `match_response` with response items instead.
+
 Match any IP with query response.

+### Response Fields
+
+!!! question "Since sing-box 1.14.0"
+
+Match fields for DNS response data. Require `match_response` to be set to `true`
+and a preceding rule with [`evaluate`](/configuration/dns/rule_action/#evaluate) action to populate the response.
+
+#### response_rcode
+
+Match DNS response code.
+
+Accepted values are the same as in the [predefined action rcode](/configuration/dns/rule_action/#rcode).
+
+#### response_answer
+
+Match DNS answer records.
+
+Record format is the same as in [predefined action answer](/configuration/dns/rule_action/#answer).
+
+#### response_ns
+
+Match DNS name server records.
+
+Record format is the same as in [predefined action ns](/configuration/dns/rule_action/#ns).
+
+#### response_extra
+
+Match DNS extra records.
+
+Record format is the same as in [predefined action extra](/configuration/dns/rule_action/#extra).
+
 ### Logical Fields

 #### type
--- a/docs/configuration/dns/rule.zh.md
+++ b/docs/configuration/dns/rule.zh.md
@@ -4,8 +4,15 @@ icon: material/alert-decagram

 !!! quote "sing-box 1.14.0 中的更改"

+    :material-plus: [match_response](#match_response)  
+    :material-plus: [response_rcode](#response_rcode)  
+    :material-plus: [response_answer](#response_answer)  
+    :material-plus: [response_ns](#response_ns)  
+    :material-plus: [response_extra](#response_extra)  
    :material-plus: [source_mac_address](#source_mac_address)  
-    :material-plus: [source_hostname](#source_hostname)
+    :material-plus: [source_hostname](#source_hostname)  
+    :material-delete-clock: [ip_accept_any](#ip_accept_any)  
+    :material-delete-clock: [rule_set_ip_cidr_accept_empty](#rule_set_ip_cidr_accept_empty)

 !!! quote "sing-box 1.13.0 中的更改"

@@ -94,12 +101,6 @@ icon: material/alert-decagram
          "192.168.0.1"
        ],
        "source_ip_is_private": false,
-        "ip_cidr": [
-          "10.0.0.0/24",
-          "192.168.0.1"
-        ],
-        "ip_is_private": false,
-        "ip_accept_any": false,
        "source_port": [
          12345
        ],
@@ -171,7 +172,16 @@ icon: material/alert-decagram
          "geosite-cn"
        ],
        "rule_set_ip_cidr_match_source": false,
-        "rule_set_ip_cidr_accept_empty": false,
+        "match_response": false,
+        "ip_cidr": [
+          "10.0.0.0/24",
+          "192.168.0.1"
+        ],
+        "ip_is_private": false,
+        "response_rcode": "",
+        "response_answer": [],
+        "response_ns": [],
+        "response_extra": [],
        "invert": false,
        "outbound": [
          "direct"
@@ -180,6 +190,9 @@ icon: material/alert-decagram
        "server": "local",

        // 已弃用
+
+        "ip_accept_any": false,
+        "rule_set_ip_cidr_accept_empty": false,
        "rule_set_ipcidr_match_source": false,
        "geosite": [
          "cn"
@@ -476,6 +489,15 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.

 使规则集中的 `ip_cidr` 规则匹配源 IP。

+#### match_response
+
+!!! question "自 sing-box 1.14.0 起"
+
+启用响应匹配。启用后，此规则将匹配 DNS 响应数据（由前序 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作设置），而不仅是匹配原始查询。
+
+`response_rcode`、`response_answer`、`response_ns`、`response_extra` 字段需要此选项。
+当 `legacyDNSMode` 未启用时，`ip_cidr` 和 `ip_is_private` 也需要此选项。
+
 #### invert

 反选匹配结果。
@@ -547,24 +569,69 @@ Available values: `wifi`, `cellular`, `ethernet` and `other`.

 与查询响应匹配 IP CIDR。

+当 `legacyDNSMode` 未启用时，`match_response` 必须设为 `true`。
+
 #### ip_is_private

 !!! question "自 sing-box 1.9.0 起"

 与查询响应匹配非公开 IP。

+当 `legacyDNSMode` 未启用时，`match_response` 必须设为 `true`。
+
 #### ip_accept_any

 !!! question "自 sing-box 1.12.0 起"

+!!! failure "已在 sing-box 1.14.0 废弃"
+
+    `ip_accept_any` 已废弃且将在 sing-box 1.16.0 中被移除。
+    仅在 `legacyDNSMode` 中可用。请使用 `match_response` 和响应项替代。
+
 匹配任意 IP。

 #### rule_set_ip_cidr_accept_empty

 !!! question "自 sing-box 1.10.0 起"

+!!! failure "已在 sing-box 1.14.0 废弃"
+
+    `rule_set_ip_cidr_accept_empty` 已废弃且将在 sing-box 1.16.0 中被移除。
+    仅在 `legacyDNSMode` 中可用。
+
 使规则集中的 `ip_cidr` 规则接受空查询响应。

+### 响应字段
+
+!!! question "自 sing-box 1.14.0 起"
+
+DNS 响应数据的匹配字段。需要将 `match_response` 设为 `true`，
+且需要前序规则使用 [`evaluate`](/zh/configuration/dns/rule_action/#evaluate) 动作来填充响应。
+
+#### response_rcode
+
+匹配 DNS 响应码。
+
+接受的值与 [predefined 动作 rcode](/zh/configuration/dns/rule_action/#rcode) 中相同。
+
+#### response_answer
+
+匹配 DNS 应答记录。
+
+记录格式与 [predefined 动作 answer](/zh/configuration/dns/rule_action/#answer) 中相同。
+
+#### response_ns
+
+匹配 DNS 名称服务器记录。
+
+记录格式与 [predefined 动作 ns](/zh/configuration/dns/rule_action/#ns) 中相同。
+
+#### response_extra
+
+匹配 DNS 额外记录。
+
+记录格式与 [predefined 动作 extra](/zh/configuration/dns/rule_action/#extra) 中相同。
+
 ### 逻辑字段

 #### type
--- a/docs/configuration/dns/rule_action.md
+++ b/docs/configuration/dns/rule_action.md
@@ -2,6 +2,11 @@
 icon: material/new-box
 ---

+!!! quote "Changes in sing-box 1.14.0"
+
+    :material-plus: [evaluate](#evaluate)  
+    :material-delete-clock: [strategy](#strategy)
+
 !!! quote "Changes in sing-box 1.12.0"

    :material-plus: [strategy](#strategy)  
@@ -58,6 +63,48 @@ If value is an IP address instead of prefix, `/32` or `/128` will be appended au

 Will overrides `dns.client_subnet`.

+### evaluate
+
+!!! question "Since sing-box 1.14.0"
+
+```json
+{
+  "action": "evaluate",
+  "server": "",
+  "disable_cache": false,
+  "rewrite_ttl": null,
+  "client_subnet": null
+}
+```
+
+`evaluate` sends a DNS query to the specified server and saves the response for subsequent rules
+to match against using [`match_response`](/configuration/dns/rule/#match_response) and response fields.
+Unlike `route`, it does **not** terminate rule evaluation.
+
+Only allowed on top-level DNS rules (not inside logical sub-rules).
+
+#### server
+
+==Required==
+
+Tag of target server.
+
+#### disable_cache
+
+Disable cache and save cache in this query.
+
+#### rewrite_ttl
+
+Rewrite TTL in DNS responses.
+
+#### client_subnet
+
+Append a `edns0-subnet` OPT extra record with the specified IP prefix to every query by default.
+
+If value is an IP address instead of prefix, `/32` or `/128` will be appended automatically.
+
+Will overrides `dns.client_subnet`.
+
 ### route-options

 ```json
--- a/docs/configuration/dns/rule_action.zh.md
+++ b/docs/configuration/dns/rule_action.zh.md
@@ -2,6 +2,11 @@
 icon: material/new-box
 ---

+!!! quote "sing-box 1.14.0 中的更改"
+
+    :material-plus: [evaluate](#evaluate)  
+    :material-delete-clock: [strategy](#strategy)
+
 !!! quote "sing-box 1.12.0 中的更改"

    :material-plus: [strategy](#strategy)  
@@ -58,6 +63,46 @@ icon: material/new-box

 将覆盖 `dns.client_subnet`.

+### evaluate
+
+!!! question "自 sing-box 1.14.0 起"
+
+```json
+{
+  "action": "evaluate",
+  "server": "",
+  "disable_cache": false,
+  "rewrite_ttl": null,
+  "client_subnet": null
+}
+```
+
+`evaluate` 向指定服务器发送 DNS 查询并保存响应，供后续规则通过 [`match_response`](/zh/configuration/dns/rule/#match_response) 和响应字段进行匹配。与 `route` 不同，它**不会**终止规则评估。
+
+仅允许在顶层 DNS 规则中使用（不可在逻辑子规则内部使用）。
+
+#### server
+
+==必填==
+
+目标 DNS 服务器的标签。
+
+#### disable_cache
+
+在此查询中禁用缓存。
+
+#### rewrite_ttl
+
+重写 DNS 回应中的 TTL。
+
+#### client_subnet
+
+默认情况下，将带有指定 IP 前缀的 `edns0-subnet` OPT 附加记录附加到每个查询。
+
+如果值是 IP 地址而不是前缀，则会自动附加 `/32` 或 `/128`。
+
+将覆盖 `dns.client_subnet`.
+
 ### route-options

 ```json
--- a/docs/deprecated.md
+++ b/docs/deprecated.md
@@ -21,6 +21,29 @@ and only supported in `legacyDNSMode`.

 Old fields will be removed in sing-box 1.16.0.

+#### `ip_accept_any` in DNS rules
+
+`ip_accept_any` in DNS rules is deprecated
+and only supported in `legacyDNSMode`.
+Use `match_response` with response items instead.
+
+Old fields will be removed in sing-box 1.16.0.
+
+#### `rule_set_ip_cidr_accept_empty` in DNS rules
+
+`rule_set_ip_cidr_accept_empty` in DNS rules is deprecated
+and only supported in `legacyDNSMode`.
+
+Old fields will be removed in sing-box 1.16.0.
+
+#### Legacy address filter DNS rule items
+
+Legacy address filter DNS rule items (`ip_cidr`, `ip_is_private` without `match_response`)
+are deprecated and only supported in `legacyDNSMode`.
+Use `match_response` with the `evaluate` action instead.
+
+Old behavior will be removed in sing-box 1.16.0.
+
 ## 1.12.0

 #### Legacy DNS server formats
--- a/docs/deprecated.zh.md
+++ b/docs/deprecated.zh.md
@@ -14,6 +14,36 @@ TLS 中的内联 ACME 选项（`tls.acme`）已废弃，

 旧字段将在 sing-box 1.16.0 中被移除。

+#### DNS 规则动作中的 `strategy`
+
+DNS 规则动作中的 `strategy` 已废弃，
+且仅在 `legacyDNSMode` 中可用。
+
+旧字段将在 sing-box 1.16.0 中被移除。
+
+#### DNS 规则中的 `ip_accept_any`
+
+DNS 规则中的 `ip_accept_any` 已废弃，
+且仅在 `legacyDNSMode` 中可用。
+请使用 `match_response` 和响应项替代。
+
+旧字段将在 sing-box 1.16.0 中被移除。
+
+#### DNS 规则中的 `rule_set_ip_cidr_accept_empty`
+
+DNS 规则中的 `rule_set_ip_cidr_accept_empty` 已废弃，
+且仅在 `legacyDNSMode` 中可用。
+
+旧字段将在 sing-box 1.16.0 中被移除。
+
+#### 旧的地址筛选 DNS 规则项
+
+旧的地址筛选 DNS 规则项（不使用 `match_response` 的 `ip_cidr`、`ip_is_private`）已废弃，
+且仅在 `legacyDNSMode` 中可用。
+请使用 `match_response` 和 `evaluate` 动作替代。
+
+旧行为将在 sing-box 1.16.0 中被移除。
+
 ## 1.12.0

 #### 旧的 DNS 服务器格式