Add optimistic DNS cache

2026-04-11 12:10:52 +08:00
parent 1735022e91
commit 9eae48e208
30 changed files with 1233 additions and 383 deletions
@@ -2,6 +2,11 @@
 icon: material/alert-decagram
 ---

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

    :material-decagram: [servers](#servers)
@@ -25,6 +30,7 @@ icon: material/alert-decagram
    "disable_expire": false,
    "independent_cache": false,
    "cache_capacity": 0,
+    "optimistic": false, // or {}
    "reverse_mapping": false,
    "client_subnet": "",
    "fakeip": {}
@@ -57,12 +63,20 @@ One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.

 Disable dns cache.

+Conflict with `optimistic`.
+
 #### disable_expire

 Disable dns cache expire.

+Conflict with `optimistic`.
+
 #### independent_cache

+!!! failure "Deprecated in sing-box 1.14.0"
+
+    `independent_cache` is deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-independent-dns-cache).
+
 Make each DNS server's cache independent for special purposes. If enabled, will slightly degrade performance.

 #### cache_capacity
@@ -73,6 +87,34 @@ LRU cache capacity.

 Value less than 1024 will be ignored.

+#### optimistic
+
+!!! question "Since sing-box 1.14.0"
+
+Enable optimistic DNS caching. When a cached DNS entry has expired but is still within the timeout window,
+the stale response is returned immediately while a background refresh is triggered.
+
+Conflict with `disable_cache` and `disable_expire`.
+
+Accepts a boolean or an object. When set to `true`, the default timeout of `3d` is used.
+
+```json
+{
+  "enabled": true,
+  "timeout": "3d"
+}
+```
+
+##### enabled
+
+Enable optimistic DNS caching.
+
+##### timeout
+
+The maximum time an expired cache entry can be served optimistically.
+
+`3d` is used by default.
+
 #### reverse_mapping

 Stores a reverse mapping of IP addresses after responding to a DNS query in order to provide domain names when routing.
@@ -2,6 +2,11 @@
 icon: material/alert-decagram
 ---

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

    :material-decagram: [servers](#servers)
@@ -25,6 +30,7 @@ icon: material/alert-decagram
    "disable_expire": false,
    "independent_cache": false,
    "cache_capacity": 0,
+    "optimistic": false, // or {}
    "reverse_mapping": false,
    "client_subnet": "",
    "fakeip": {}
@@ -56,12 +62,20 @@ icon: material/alert-decagram

 禁用 DNS 缓存。

+与 `optimistic` 冲突。
+
 #### disable_expire

 禁用 DNS 缓存过期。

+与 `optimistic` 冲突。
+
 #### independent_cache

+!!! failure "已在 sing-box 1.14.0 废弃"
+
+    `independent_cache` 已在 sing-box 1.14.0 废弃，且将在 sing-box 1.16.0 中被移除，参阅[迁移指南](/zh/migration/#迁移-independent-dns-cache)。
+
 使每个 DNS 服务器的缓存独立，以满足特殊目的。如果启用，将轻微降低性能。

 #### cache_capacity
@@ -72,6 +86,34 @@ LRU 缓存容量。

 小于 1024 的值将被忽略。

+#### optimistic
+
+!!! question "自 sing-box 1.14.0 起"
+
+启用乐观 DNS 缓存。当缓存的 DNS 条目已过期但仍在超时窗口内时，
+立即返回过期的响应，同时在后台触发刷新。
+
+与 `disable_cache` 和 `disable_expire` 冲突。
+
+接受布尔值或对象。当设置为 `true` 时，使用默认超时 `3d`。
+
+```json
+{
+  "enabled": true,
+  "timeout": "3d"
+}
+```
+
+##### enabled
+
+启用乐观 DNS 缓存。
+
+##### timeout
+
+过期缓存条目可被乐观提供的最长时间。
+
+默认使用 `3d`。
+
 #### reverse_mapping

 在响应 DNS 查询后存储 IP 地址的反向映射以为路由目的提供域名。
@@ -6,7 +6,8 @@ icon: material/new-box

    :material-delete-clock: [strategy](#strategy)  
    :material-plus: [evaluate](#evaluate)  
-    :material-plus: [respond](#respond)
+    :material-plus: [respond](#respond)  
+    :material-plus: [disable_optimistic_cache](#disable_optimistic_cache)

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

@@ -23,6 +24,7 @@ icon: material/new-box
  "server": "",
  "strategy": "",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -52,6 +54,12 @@ One of `prefer_ipv4` `prefer_ipv6` `ipv4_only` `ipv6_only`.

 Disable cache and save cache in this query.

+#### disable_optimistic_cache
+
+!!! question "Since sing-box 1.14.0"
+
+Disable optimistic DNS caching in this query.
+
 #### rewrite_ttl

 Rewrite TTL in DNS responses.
@@ -73,6 +81,7 @@ Will override `dns.client_subnet`.
  "action": "evaluate",
  "server": "",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -97,6 +106,12 @@ Tag of target server.

 Disable cache and save cache in this query.

+#### disable_optimistic_cache
+
+!!! question "Since sing-box 1.14.0"
+
+Disable optimistic DNS caching in this query.
+
 #### rewrite_ttl

 Rewrite TTL in DNS responses.
@@ -131,6 +146,7 @@ Only allowed after a preceding top-level `evaluate` rule. If the action is reach
 {
  "action": "route-options",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -6,7 +6,8 @@ icon: material/new-box

    :material-delete-clock: [strategy](#strategy)  
    :material-plus: [evaluate](#evaluate)  
-    :material-plus: [respond](#respond)
+    :material-plus: [respond](#respond)  
+    :material-plus: [disable_optimistic_cache](#disable_optimistic_cache)

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

@@ -23,6 +24,7 @@ icon: material/new-box
  "server": "",
  "strategy": "",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -52,6 +54,12 @@ icon: material/new-box

 在此查询中禁用缓存。

+#### disable_optimistic_cache
+
+!!! question "自 sing-box 1.14.0 起"
+
+在此查询中禁用乐观 DNS 缓存。
+
 #### rewrite_ttl

 重写 DNS 回应中的 TTL。
@@ -73,6 +81,7 @@ icon: material/new-box
  "action": "evaluate",
  "server": "",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -95,6 +104,12 @@ icon: material/new-box

 在此查询中禁用缓存。

+#### disable_optimistic_cache
+
+!!! question "自 sing-box 1.14.0 起"
+
+在此查询中禁用乐观 DNS 缓存。
+
 #### rewrite_ttl

 重写 DNS 回应中的 TTL。
@@ -129,6 +144,7 @@ icon: material/new-box
 {
  "action": "route-options",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -1,5 +1,10 @@
 !!! question "Since sing-box 1.8.0"

+!!! quote "Changes in sing-box 1.14.0"
+
+    :material-delete-clock: [store_rdrc](#store_rdrc)  
+    :material-plus: [store_dns](#store_dns)
+
 !!! quote "Changes in sing-box 1.9.0"

    :material-plus: [store_rdrc](#store_rdrc)  
@@ -14,7 +19,8 @@
  "cache_id": "",
  "store_fakeip": false,
  "store_rdrc": false,
-  "rdrc_timeout": ""
+  "rdrc_timeout": "",
+  "store_dns": false
 }
 ```

@@ -42,6 +48,10 @@ Store fakeip in the cache file

 #### store_rdrc

+!!! failure "Deprecated in sing-box 1.14.0"
+
+    `store_rdrc` is deprecated and will be removed in sing-box 1.16.0, check [Migration](/migration/#migrate-store-rdrc).
+
 Store rejected DNS response cache in the cache file

 The check results of [Legacy Address Filter Fields](/configuration/dns/rule/#legacy-address-filter-fields)
@@ -52,3 +62,9 @@ will be cached until expiration.
 Timeout of rejected DNS response cache.

 `7d` is used by default.
+
+#### store_dns
+
+!!! question "Since sing-box 1.14.0"
+
+Store DNS cache in the cache file.
@@ -1,5 +1,10 @@
 !!! question "自 sing-box 1.8.0 起"

+!!! quote "sing-box 1.14.0 中的更改"
+
+    :material-delete-clock: [store_rdrc](#store_rdrc)  
+    :material-plus: [store_dns](#store_dns)
+
 !!! quote "sing-box 1.9.0 中的更改"

    :material-plus: [store_rdrc](#store_rdrc)  
@@ -14,7 +19,8 @@
  "cache_id": "",
  "store_fakeip": false,
  "store_rdrc": false,
-  "rdrc_timeout": ""
+  "rdrc_timeout": "",
+  "store_dns": false
 }
 ```

@@ -40,6 +46,10 @@

 #### store_rdrc

+!!! failure "已在 sing-box 1.14.0 废弃"
+
+    `store_rdrc` 已在 sing-box 1.14.0 废弃，且将在 sing-box 1.16.0 中被移除，参阅[迁移指南](/zh/migration/#迁移-store_rdrc)。
+
 将拒绝的 DNS 响应缓存存储在缓存文件中。

 [旧版地址筛选字段](/zh/configuration/dns/rule/#旧版地址筛选字段) 的检查结果将被缓存至过期。
@@ -49,3 +59,9 @@
 拒绝的 DNS 响应缓存超时。

 默认使用 `7d`。
+
+#### store_dns
+
+!!! question "自 sing-box 1.14.0 起"
+
+将 DNS 缓存存储在缓存文件中。
@@ -7,6 +7,10 @@ icon: material/new-box
    :material-plus: [bypass](#bypass)  
    :material-alert: [reject](#reject)

+!!! quote "Changes in sing-box 1.14.0"
+
+    :material-plus: [resolve.disable_optimistic_cache](#disable_optimistic_cache)
+
 !!! quote "Changes in sing-box 1.12.0"

    :material-plus: [tls_fragment](#tls_fragment)  
@@ -279,6 +283,7 @@ Timeout for sniffing.
  "server": "",
  "strategy": "",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -302,6 +307,12 @@ DNS resolution strategy, available values are: `prefer_ipv4`, `prefer_ipv6`, `ip

 Disable cache and save cache in this query.

+#### disable_optimistic_cache
+
+!!! question "Since sing-box 1.14.0"
+
+Disable optimistic DNS caching in this query.
+
 #### rewrite_ttl

 !!! question "Since sing-box 1.12.0"
@@ -7,6 +7,10 @@ icon: material/new-box
    :material-plus: [bypass](#bypass)  
    :material-alert: [reject](#reject)

+!!! quote "sing-box 1.14.0 中的更改"
+
+    :material-plus: [resolve.disable_optimistic_cache](#disable_optimistic_cache)
+
 !!! quote "sing-box 1.12.0 中的更改"

    :material-plus: [tls_fragment](#tls_fragment)  
@@ -268,6 +272,7 @@ UDP 连接超时时间。
  "server": "",
  "strategy": "",
  "disable_cache": false,
+  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "client_subnet": null
 }
@@ -291,6 +296,12 @@ DNS 解析策略，可用值有：`prefer_ipv4`、`prefer_ipv6`、`ipv4_only`、

 在此查询中禁用缓存。

+#### disable_optimistic_cache
+
+!!! question "自 sing-box 1.14.0 起"
+
+在此查询中禁用乐观 DNS 缓存。
+
 #### rewrite_ttl

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