Add optimistic DNS cache

2026-04-11 17:47:20 +10:00 · 2026-04-11 12:10:52 +08:00
parent 6ba7a6f001
commit ebd31ca363
30 changed files with 1233 additions and 383 deletions
--- a/docs/configuration/dns/index.md
+++ b/docs/configuration/dns/index.md
@@ -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.
--- a/docs/configuration/dns/index.zh.md
+++ b/docs/configuration/dns/index.zh.md
@@ -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 地址的反向映射以为路由目的提供域名。
--- a/docs/configuration/dns/rule_action.md
+++ b/docs/configuration/dns/rule_action.md
@@ -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
 }
--- a/docs/configuration/dns/rule_action.zh.md
+++ b/docs/configuration/dns/rule_action.zh.md
@@ -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
 }
--- a/docs/configuration/experimental/cache-file.md
+++ b/docs/configuration/experimental/cache-file.md
@@ -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.
--- a/docs/configuration/experimental/cache-file.zh.md
+++ b/docs/configuration/experimental/cache-file.zh.md
@@ -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 缓存存储在缓存文件中。
--- a/docs/configuration/route/rule_action.md
+++ b/docs/configuration/route/rule_action.md
@@ -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"
--- a/docs/configuration/route/rule_action.zh.md
+++ b/docs/configuration/route/rule_action.zh.md
@@ -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 起"
--- a/docs/deprecated.md
+++ b/docs/deprecated.md
@@ -27,6 +27,21 @@ check [Migration](../migration/#migrate-address-filter-fields-to-response-matchi

 Old fields will be removed in sing-box 1.16.0.

+#### `independent_cache` DNS option
+
+`independent_cache` DNS option is deprecated.
+The DNS cache now always keys by transport, making this option unnecessary,
+check [Migration](../migration/#migrate-independent-dns-cache).
+
+Old fields will be removed in sing-box 1.16.0.
+
+#### `store_rdrc` cache file option
+
+`store_rdrc` cache file option is deprecated,
+check [Migration](../migration/#migrate-store-rdrc).
+
+Old fields will be removed in sing-box 1.16.0.
+
 #### Legacy Address Filter Fields in DNS rules

 Legacy Address Filter Fields (`ip_cidr`, `ip_is_private` without `match_response`)
--- a/docs/deprecated.zh.md
+++ b/docs/deprecated.zh.md
@@ -27,6 +27,21 @@ TLS 中的内联 ACME 选项（`tls.acme`）已废弃，

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

+#### `independent_cache` DNS 选项
+
+`independent_cache` DNS 选项已废弃。
+DNS 缓存现在始终按传输分离，使此选项不再需要，
+参阅[迁移指南](/zh/migration/#迁移-independent-dns-cache)。
+
+旧字段将在 sing-box 1.16.0 中被移除。
+
+#### `store_rdrc` 缓存文件选项
+
+`store_rdrc` 缓存文件选项已废弃，
+参阅[迁移指南](/zh/migration/#迁移-store_rdrc)。
+
+旧字段将在 sing-box 1.16.0 中被移除。
+
 #### 旧版地址筛选字段 (DNS 规则)

 旧版地址筛选字段（不使用 `match_response` 的 `ip_cidr`、`ip_is_private`）已废弃，
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -137,6 +137,68 @@ to fetch a DNS response, then match against it explicitly with `match_response`.
    }
    ```

+### Migrate independent DNS cache
+
+The DNS cache now always keys by transport name, making `independent_cache` unnecessary.
+Simply remove the field.
+
+!!! info "References"
+
+    [DNS](/configuration/dns/)
+
+=== ":material-card-remove: Deprecated"
+
+    ```json
+    {
+      "dns": {
+        "independent_cache": true
+      }
+    }
+    ```
+
+=== ":material-card-multiple: New"
+
+    ```json
+    {
+      "dns": {}
+    }
+    ```
+
+### Migrate store_rdrc
+
+`store_rdrc` is deprecated and can be replaced by `store_dns`,
+which persists the full DNS cache to the cache file.
+
+!!! info "References"
+
+    [Cache File](/configuration/experimental/cache-file/)
+
+=== ":material-card-remove: Deprecated"
+
+    ```json
+    {
+      "experimental": {
+        "cache_file": {
+          "enabled": true,
+          "store_rdrc": true
+        }
+      }
+    }
+    ```
+
+=== ":material-card-multiple: New"
+
+    ```json
+    {
+      "experimental": {
+        "cache_file": {
+          "enabled": true,
+          "store_dns": true
+        }
+      }
+    }
+    ```
+
 ### ip_version and query_type behavior changes in DNS rules

 In sing-box 1.14.0, the behavior of
--- a/docs/migration.zh.md
+++ b/docs/migration.zh.md
@@ -137,6 +137,68 @@ sing-box 1.14.0 新增字段参阅 [ACME](/zh/configuration/shared/certificate-p
    }
    ```

+### 迁移 independent DNS cache
+
+DNS 缓存现在始终按传输名称分离，使 `independent_cache` 不再需要。
+直接移除该字段即可。
+
+!!! info "参考"
+
+    [DNS](/zh/configuration/dns/)
+
+=== ":material-card-remove: 弃用的"
+
+    ```json
+    {
+      "dns": {
+        "independent_cache": true
+      }
+    }
+    ```
+
+=== ":material-card-multiple: 新的"
+
+    ```json
+    {
+      "dns": {}
+    }
+    ```
+
+### 迁移 store_rdrc
+
+`store_rdrc` 已废弃，且可以被 `store_dns` 替代，
+后者将完整的 DNS 缓存持久化到缓存文件中。
+
+!!! info "参考"
+
+    [缓存文件](/zh/configuration/experimental/cache-file/)
+
+=== ":material-card-remove: 弃用的"
+
+    ```json
+    {
+      "experimental": {
+        "cache_file": {
+          "enabled": true,
+          "store_rdrc": true
+        }
+      }
+    }
+    ```
+
+=== ":material-card-multiple: 新的"
+
+    ```json
+    {
+      "experimental": {
+        "cache_file": {
+          "enabled": true,
+          "store_dns": true
+        }
+      }
+    }
+    ```
+
 ### DNS 规则中的 ip_version 和 query_type 行为更改

 在 sing-box 1.14.0 中，DNS 规则中的