sing-box DNS 迁移需要在替换 server 格式时保留解析与路由行为。本文在 Ubuntu 24.04 LTS amd64 上，将 sing-box 1.13.21 历史配置中的一个 UDP 引导上游、一个 HTTPS 上游映射到 1.14.3。legacy DNS server 已在 1.14.0 移除；旧版本用于解释输入，不建议长期运行。作者未进行完整端到端实测。［1］［2］［6］［7］

关键要点

不只检查 JSON，还要保留标签、引导依赖和路由意图。

HTTPS 上游使用域名时，需要独立的域名解析器。

typed DNS 默认直连，显式 detour 会影响其他拨号字段是否生效。

配置、二进制与服务设置应作为匹配的一套恢复。

谁负责这次 sing-box DNS 迁移？

先按自建环境的维护分工确认有效文件的生成者。若 GUI、面板、订阅或生成器负责配置，应使用其支持的迁移流程，并确认配置更新怎样传到客户端。会被覆盖的本地修改不算持久迁移。

客户端与核心职责说明帮助区分格式所有权与界面设置。更换 DNS 上游不能证明 TUN 或系统代理承载了预期流量；无关启动故障可按设备和应用排障顺序检查。

准备私密工作目录、空闲回环端口 1053、Ubuntu dnsutils 中的 dig，以及单独准备在 /opt/sing-box-1.14.3/sing-box 的官方 1.14.3 可执行文件。使用前核对发行文件的平台和官方完整性资料，不覆盖运行中的二进制，不下载后直接执行远程安装脚本。需要解释历史文件时，私下保留现有匹配可执行文件。

记录实际二进制路径和版本、有效配置与 include 目录、服务单元及 drop-in、运行身份、属主、权限和启用状态。备份放在有效 include 树外，避免服务意外加载。操作运行服务前，确认独立恢复连接可用。

步骤 1：盘点 sing-box 旧 DNS 配置及依赖

以下输入没有额外规则、缓存调优、FakeIP、查询过滤或 strategy 覆盖。将其保存为私密练习目录内的 dns-old.json。这是解释用样例，不是替换现有服务的命令。

{
  "dns": {
    "servers": [
      {
        "tag": "bootstrap",
        "address": "1.1.1.1",
        "detour": "direct"
      },
      {
        "tag": "secure-dns",
        "address": "https://dns.google/dns-query",
        "address_resolver": "bootstrap",
        "detour": "direct"
      }
    ],
    "final": "secure-dns"
  },
  "inbounds": [
    {
      "type": "direct",
      "tag": "dns-test",
      "listen": "127.0.0.1",
      "listen_port": 1053
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "inbound": [
          "dns-test"
        ],
        "action": "hijack-dns"
      }
    ],
    "final": "direct"
  }
}

bootstrap 解析 secure-dns 的主机名，后者处理 dns.final 选择的查询。direct 入站省略 network 时，在回环同时接收 TCP 和 UDP；指定入站的路由动作将这些请求交给 DNS 处理。它不提供公网解析，也不捕获系统全部 DNS。［5］［9］

迁移真实文件前，列出所有 server tag，以及 DNS 规则、final、路由选项和出站拨号器中的引用。记录哪些上游用数字地址、哪些用域名、哪些经过代理。名称存在不代表用途正确。有额外 strategy 或过滤时，先停止套用最小例子，按官方指南独立迁移策略语义。［1］

步骤 2：映射字段并保留 sing-box 域名解析器意图

逐项解释变化，不做全局文本替换。同一个词可能处于不同对象，也可能控制完全不同的决策。

历史输入	typed 目标	必须保留的含义
`address: 1.1.1.1`	`type: udp`、数字 `server`、端口 53	引导连接不依赖另一次域名解析
`address` 中的 HTTPS URL	`type: https`、`server`、443 和 `path`	主机名、路径及验证的 TLS 身份符合上游服务
`address_resolver: bootstrap`	`domain_resolver: bootstrap`	上游域名不通过自身才能建立的连接解析
server `tag` 和 `dns.final`	保留字符串	所有引用仍选择正确上游
本输入的 `detour: direct`	本目标省略	使用 typed server 文档规定的默认直连
其他位置的 strategy 或查询策略	按情况映射	答案选择和过滤语义须单独核验

typed UDP 和 HTTPS 默认直接拨号，legacy 则可能继承默认出站。本例旧上游显式 direct，省略 detour 保留该意图。如果原配置经过代理，不要为了像示例而删除 detour，应追踪出站及引导路径。启用 detour 后，拨号交给其出站，其他拨号字段会被忽略；把 domain_resolver 放在旁边，并不自动设置所选出站自己的解析器。［3］［4］［8］

将映射结果保存为 dns-new.json：

{
  "dns": {
    "servers": [
      {
        "type": "udp",
        "tag": "bootstrap",
        "server": "1.1.1.1",
        "server_port": 53
      },
      {
        "type": "https",
        "tag": "secure-dns",
        "server": "dns.google",
        "server_port": 443,
        "path": "/dns-query",
        "domain_resolver": "bootstrap",
        "tls": {
          "enabled": true,
          "server_name": "dns.google",
          "insecure": false
        }
      }
    ],
    "final": "secure-dns"
  },
  "inbounds": [
    {
      "type": "direct",
      "tag": "dns-test",
      "listen": "127.0.0.1",
      "listen_port": 1053
    }
  ],
  "outbounds": [
    {
      "type": "direct",
      "tag": "direct"
    }
  ],
  "route": {
    "rules": [
      {
        "inbound": [
          "dns-test"
        ],
        "action": "hijack-dns"
      }
    ],
    "final": "direct"
  }
}

HTTPS 上游使用域名，明确选择独立 UDP 引导。保持 TLS 验证。TLS 保护 HTTPS 一段，UDP 引导本身并未加密。公共上游只是依赖分离的示例，不代表隐私、可用性、延迟或地区可达性承诺。［4］

步骤 3：在隔离进程检查目标配置

旧样例只在现有匹配二进制可用时检查。旧版因弃用机制拒绝时，不绕过安全门禁，也不为此向生产主机安装旧版本。目标检查使用单独准备的 1.14.3：

/PRIVATE/BACKUP/sing-box-1.13.21 check -c dns-old.json
/opt/sing-box-1.14.3/sing-box version
/opt/sing-box-1.14.3/sing-box check -c dns-new.json
/opt/sing-box-1.14.3/sing-box run -c dns-new.json

以前台普通用户运行；1053 不需要低端口权限。练习文件权限保持 600。若回环 1053 已占用，停止并统一换一个空闲高端口，不终止其所有者。check 成功仅证明格式接受，运行进程和真实查询属于不同证据。

在另一终端明确查询地址与端口：

dig @127.0.0.1 -p 1053 example.com A
dig @127.0.0.1 -p 1053 example.com AAAA
dig @127.0.0.1 -p 1053 example.com A +tcp

检查 DNS 状态、记录类型、答案和显示的服务器。某域没有 IPv6 记录时，成功响应也可能没有 AAAA 答案。浏览器或不指定上游的 dig 可能使用别的解析器，不能验证此进程。私下记录实际观察；命令没有虚构输出。

步骤 4：替换服务前检查失败条件

用私密副本每次改一个条件，只 Ctrl-C 停止自己的前台进程，再运行所选副本。检查之间恢复已知安全文件，不更改共享防火墙或系统 DNS。

读者检查	预期现象	失败处理
有效配置，分别 UDP 与 TCP 查询	经所选 DNS 路径取得响应	分开检查绑定、上游访问、TLS 和日志
副本中让 HTTPS 指向未使用本地端口	即使格式接受，真实查询仍失败	恢复端点，不弱化 TLS，不加隐藏回退
`domain_resolver` 换成不存在的标签	配置检查或启动拒绝引用	修正标签后才查询
让 `secure-dns` 通过自身解析自己的主机名	被拒绝或解析失败，不能构成有效引导	恢复数字地址的独立引导，不依赖固定错误字符串
用目标二进制运行旧格式样例	legacy 格式被拒绝	使用映射后的目标，不绕过弃用限制
重启未修改的有效目标	新查询恢复	对照私密基线核对文件、二进制和权限

上游故障可能看似迁移故障。区分格式拒绝、套接字绑定、域名引导、TLS 和答案策略；表中是预期条件，不是作者测试结果。一次超时不能证明具体根因。

步骤 5：启用目标并成套恢复

隔离检查完成后，沿用所有者支持的部署流程，让服务指向目标二进制与验证过的文件。重查运行身份、必要证书读取、单元命令和 include 路径；以实际身份检查有效配置，在维护窗口只重启获授权单元，查看有限日志，再从真实服务入口重复查询。

恢复时停止改后的服务，恢复保存的可执行文件或准确软件包、配置及 includes、属主、单元与 drop-in、原启用状态。单元文件变化后运行 sudo systemctl daemon-reload。用恢复后的匹配二进制检查，按原状态启动，查看状态和日志，重复原基线查询。只恢复 JSON 却留下不兼容核心不算恢复。

退回历史版本仅属临时故障遏制，仍受其安全支持与公告限制；不能无限期保留旧格式生产服务，应安排受支持迁移。隔离练习结束时 Ctrl-C 停止自己的进程并确认 1053 释放。没有修改客户端系统 DNS，也就没有路由器全网切换要撤回。

总结

映射每个上游的类型、端点、标签、解析器与拨号路径。
明确指向回环入口，检查真实答案及受控失败。
二进制、配置和服务设置共同部署、共同恢复。

常见问题（FAQ）

1.14.3 还能保留 legacy server 吗？

不能。移除边界是 1.14.0，应采用 typed server，而不是绕过旧格式限制。［2］

`address_resolver` 总能直接替换吗？

应在具体 server 和拨号上下文映射。全局改名不会自动保留代理所有权或查询策略。

为什么保留标签？

规则和最终选择引用标签。改名必须更新全部相关引用；保留名称也仍需确认实际角色正确。

HTTPS 为什么需要引导解析器？

建立 HTTPS 前必须解析上游域名，若依赖同一尚未建立的连接，就形成循环依赖。

typed server 都应保留 `detour: direct` 吗？

不应。默认已经直连；启用 detour 改变其他拨号字段的适用性，还要单独检查所选出站解析器。［3］［4］

`sing-box check` 能证明 DNS 可用吗？

不能。它检查配置，真实查询、答案策略、上游连接和重启行为需要各自观察。

生成器覆盖了新文件怎么办？

与维护者迁移源配置或受支持模板。手改生成输出无法建立持久的配置所有权。

免责声明：只操作获授权主机和网络，遵守适用法律及政策。本文是文档支持的步骤与读者检查标准，不代表部署记录或性能保证。

来源:

sing-box DNS migration guide — https://sing-box.sagernet.org/migration/
sing-box legacy DNS server — https://sing-box.sagernet.org/configuration/dns/server/legacy/
sing-box UDP DNS server — https://sing-box.sagernet.org/configuration/dns/server/udp/
sing-box HTTPS DNS server — https://sing-box.sagernet.org/configuration/dns/server/https/
sing-box route rule actions — https://sing-box.sagernet.org/configuration/route/rule_action/
sing-box 1.14.3 release — https://github.com/SagerNet/sing-box/releases/tag/v1.14.3
sing-box 1.13.21 historical release — https://github.com/SagerNet/sing-box/releases/tag/v1.13.21
sing-box shared dial fields — https://sing-box.sagernet.org/configuration/shared/dial/
sing-box direct inbound — https://sing-box.sagernet.org/configuration/inbound/direct/

Sources checked 2026 年 10 月 11 日。

延伸阅读:

sing-box DNS 迁移：替换旧字段并核对解析引导与回退

谁负责这次 sing-box DNS 迁移？

步骤 1：盘点 sing-box 旧 DNS 配置及依赖

步骤 2：映射字段并保留 sing-box 域名解析器意图

步骤 3：在隔离进程检查目标配置

步骤 4：替换服务前检查失败条件

步骤 5：启用目标并成套恢复

总结

常见问题（FAQ）

1.14.3 还能保留 legacy server 吗？

`address_resolver` 总能直接替换吗？

为什么保留标签？

HTTPS 为什么需要引导解析器？

typed server 都应保留 `detour: direct` 吗？

`sing-box check` 能证明 DNS 可用吗？

生成器覆盖了新文件怎么办？

开启 3 天免费试用

相关文章

TUN 模式与系统代理有何不同？直接连接、路由排除与应用范围

VPN 配置更新后仍使用旧设置？来源版本、活动配置与运行状态核对

什么是 Xray 与 V2Ray？理解代理核心、协议与客户端职责

谁负责这次 sing-box DNS 迁移？

步骤 1：盘点 sing-box 旧 DNS 配置及依赖

步骤 2：映射字段并保留 sing-box 域名解析器意图

步骤 3：在隔离进程检查目标配置

步骤 4：替换服务前检查失败条件

步骤 5：启用目标并成套恢复

总结

常见问题（FAQ）

1.14.3 还能保留 legacy server 吗？

address_resolver 总能直接替换吗？

为什么保留标签？

HTTPS 为什么需要引导解析器？

typed server 都应保留 detour: direct 吗？

sing-box check 能证明 DNS 可用吗？

生成器覆盖了新文件怎么办？

开启 3 天免费试用

相关文章

TUN 模式与系统代理有何不同？直接连接、路由排除与应用范围

VPN 配置更新后仍使用旧设置？来源版本、活动配置与运行状态核对

什么是 Xray 与 V2Ray？理解代理核心、协议与客户端职责

`address_resolver` 总能直接替换吗？

typed server 都应保留 `detour: direct` 吗？

`sing-box check` 能证明 DNS 可用吗？