sing-box DoH3 WireGuard 失败怎么排查？从 MTU、UDP 到 DNS 回环逐层定位
简答：sing-box DoH3 WireGuard 失败时，优先对比 direct、DoH3 和其他 DNS 传输，再检查 WireGuard endpoint、AllowedIPs、UDP 443。
定义：sing-box DoH3 WireGuard 失败，是指 DNS over HTTP/3 经 WireGuard 出站时出现超时、无返回数据或 no recent network activity，而直连或其他 DNS 传输可能正常。
先看结论：DoH3 经 WireGuard 超时，先查路径和 MTU
更新于 2026 年 10 月 26 日。当前可核验的复现证据显示，sing-box 1.14.3 在用户态 WireGuard 经过 1290 字节下游路径时，DoH3 初始 QUIC UDP 负载为 1280 字节，加上 IPv4 和 UDP 头后达到 1308 字节；未修改版本在复现实验中 0/3 返回 DNS，改用 1200 字节初始负载后为 3/3。这个结果来自 sing-box Issue #4656 的本地复现，不能直接推断所有 DoH3 故障都由同一原因造成。
| 现象 | 优先检查 | 下一步 |
|---|---|---|
| direct 正常，DoH3 经 WireGuard 超时 | WireGuard UDP 通道、MTU、AllowedIPs、回程路径 | 先移除 detour 做 direct 对照，再逐项恢复 |
| DoH3 和普通 UDP DNS 都失败 | WireGuard endpoint、Peer 地址、端口或握手 | 先确认 WireGuard 本身能否访问目标 IP |
| DoH3 失败，DoH2 或 DoT 正常 | QUIC/UDP 443、路径 MTU、NAT 映射 | 降低 WireGuard 或路径 MTU，并查看 debug 日志 |
| 日志出现 lookup failed 或解析反复超时 | DoH3 服务器域名的 domain_resolver 是否回环 | 用 direct 的 bootstrap DNS 解析 DoH3 服务器域名 |
如果你只想先试一步：把 DoH3 的 detour 临时改为直连；直连恢复而 WireGuard 仍超时，问题范围就从“DoH3 地址或 TLS”缩小到 WireGuard、UDP、MTU 或路由。
第一步：确认版本、构建能力和当前配置形态
官方文档显示，DoH3 DNS 服务器自 sing-box 1.12.0 起提供；新版 WireGuard endpoint 文档标注自 sing-box 1.11.0 起使用，1.14.0 又增加了 udp_mapping、udp_filtering 和 udp_nat_max 等 UDP NAT 字段。请先执行 sing-box version，确认版本、平台以及构建标签，至少核对是否包含 with_quic 和 with_wireguard。这些字段和版本信息可在 sing-box HTTP3 官方配置文档 与 sing-box WireGuard endpoint 文档中核对。
- DoH3 配置：检查
type、server、server_port、path、tls和 Dial Fields。 - WireGuard 配置：检查
type: wireguard、mtu、address、Peer 的address、port、public_key与allowed_ips。 - 配置形态：新版应优先按照 endpoint 页面检查 WireGuard 写法，不要把旧版 WireGuard outbound 字段和新版 endpoint 配置混用。旧版 outbound 页面仍可用于识别历史配置，但不应据此推断当前配置一定有效。
Issue #4656 的复现环境为 sing-box 1.14.3，构建标签包含 with_quic、with_wireguard 和 with_gvisor；它证明的是一个带明确环境约束的复现，不是所有平台的普遍结论。
第二步：用三组对照测试拆开 DNS、WireGuard 和 QUIC
- DoH3 直连对照：保留服务器、端口、路径和 TLS，只临时移除
detour。如果直连可以返回而经 WireGuard 超时，优先检查 UDP/QUIC 路径，而不是先改服务器域名。 - 其他 DNS 传输对照：在相同 WireGuard 出站下，临时使用 HTTPS、TLS 或普通 UDP DNS 进行测试。若其他传输可用而 DoH3 失败，重点查看 UDP 443、QUIC 初始包和路径 MTU；若全部失败，回到 WireGuard endpoint 与路由检查。
- WireGuard 目标 IP 对照：临时把 Peer 的域名改为已核对的 IP 地址，避免 Peer 地址本身还要经过同一条待建立的 DNS 链路。如果改成 IP 后恢复，说明域名解析路径可能存在回环或超时。
- 记录每次变化：一次只改一个字段，记录 sing-box 版本、网络类型、MTU、DNS 类型、是否设置 detour、失败日志和恢复结果；不要同时改 MTU、AllowedIPs 和 DNS。
官方 DoH3 文档明确要求：当 server 使用域名时，需要设置 domain_resolver；新版 DoH3 使用 Dial Fields 中的解析字段，而不是把旧版 address_resolver 直接照搬过来。可先让 domain_resolver 指向一个直连的 bootstrap DNS，避免“解析 DoH3 服务器时又要先经过 DoH3”形成回环。
第三步：检查新版 WireGuard endpoint 与 DoH3 的最小配置关系
下面是用于排错的结构片段，不包含真实私钥、服务器地址或密钥。它的目的不是直接复制上线，而是让你看出 DNS 服务器、解析器和 WireGuard 出站之间的关系。
{ "dns": { "servers": [ { "type": "h3", "tag": "doh3-wg", "server": "dns.example", "server_port": 443, "path": "/dns-query", "tls": { "enabled": true, "server_name": "dns.example" }, "domain_resolver": "bootstrap", "detour": "wg-ep" }, { "type": "udp", "tag": "bootstrap", "server": "已核对的直连 DNS 地址" } ] }, "endpoints": [ { "type": "wireguard", "tag": "wg-ep", "system": false, "mtu": 1280, "address": ["10.0.0.2/32"], "private_key": "已替换为私钥", "peers": [ { "address": "已核对的 Peer IP 或域名", "port": 51820, "public_key": "已替换为 Peer 公钥", "allowed_ips": ["0.0.0.0/0"], "persistent_keepalive_interval": 25 } ] } ] }
- 先用已核对的 Peer IP：排除 Peer 域名解析失败；确认链路后再恢复域名。
- 先使用保守 MTU 做对照：示例使用 1280 只是诊断起点，不代表所有网络都应固定为这个值；稳定后再根据实际路径测试。
- 检查 AllowedIPs：如果不包含 DoH3 服务器的目标地址，流量可能没有进入 WireGuard；如果范围过大，也可能把 bootstrap DNS 或 Peer endpoint 自身错误地送回隧道。
- 检查持久保活：在存在 NAT 映射回收的网络中，可暂时设置
persistent_keepalive_interval，但它不能修复 MTU 或错误路由。
字段名称和版本起点请以 WireGuard endpoint 官方页面及 HTTP3 官方页面为准；不要把示例中的占位内容直接用于生产环境。
第四步：专门验证 1290 字节路径、MTU 和 UDP 443
Issue #4656 的复现把下游路径限制为 1290 字节，并观察到未修改客户端发送 1308 字节 IPv4/UDP 数据包；报告还指出，恢复到 1500 字节路径后未修改版本可以工作。这个证据强烈提示：当你的网络存在较小路径 MTU、禁止分片或 ICMP fragmentation-needed 消息没有正确处理时，DoH3 的 QUIC 初始握手可能比普通 TCP DNS 更容易暴露问题，但仍需在自己的路径上验证。
- 先看系统接口 MTU：Linux 执行
ip link和ip route get 目标地址；Windows PowerShell 执行Get-NetIPInterface和Get-NetRoute，记录实际出口接口与 MTU。 - 再看 WireGuard endpoint MTU：把 endpoint 的
mtu从当前值临时降到 1280 或更低的测试值，重启 sing-box 后只重复 DoH3 查询。若恢复，再逐步提高并记录临界点。 - 检查 UDP 443：DoH3 依赖 QUIC/UDP；如果同一目标的 HTTPS/TCP 正常而 UDP 443 不通，不能仅凭网页能打开就判断 DoH3 路径正常。
- 检查 IPv4 与 IPv6：先分别测试 IPv4 和 IPv6；如果只有 IPv6 失败，暂时使用已验证的 IPv4 路径做对照，避免把双栈差异误判为 DNS 配置错误。
- 不要把一次成功当作修复：至少重复冷启动、空闲后首次查询和连续查询，观察是否只在连接建立或 NAT 映射过期后失败。
如果降低 MTU 后恢复，只能说明 MTU 或分片路径是高可能因素；它不能单独证明 sing-box 在所有网络中都有同一个缺陷，也不能排除防火墙、NAT 或回程路径差异。
第五步：从日志判断是解析、握手还是回程失败
将日志级别临时设为 debug，然后只执行一次 DNS 查询。命令行运行 sing-box 时查看标准错误输出；作为 systemd 服务运行时，可在 Linux 中执行 sudo journalctl -u sing-box -b --no-pager。图形客户端则打开客户端的日志面板，按时间筛选本次查询，不要把完整配置、私钥或订阅令牌贴到公开工单。
| 日志线索 | 通常指向 | 核验动作 |
|---|---|---|
lookup failed | DoH3 服务器域名或 Peer 域名未能解析 | 检查 domain_resolver，临时改用已核对 IP |
handshake 没有后续数据 | WireGuard Peer、端口、AllowedIPs 或 UDP 路径 | 检查 Peer 地址、端口、密钥和握手时间 |
outbound packet connection 失败 | 出站选择或路由没有把流量送入预期 endpoint | 核对 detour、路由规则和目标地址 |
no recent network activity | QUIC 会话没有收到有效回包 | 优先做 MTU、UDP 443、IPv4/IPv6 和 direct 对照 |
| TLS 或证书错误 | 服务器名称、证书校验或 DoH3 地址不匹配 | 核对 tls.server_name、服务器域名和路径 |
Issue #4656 的报告明确说明，其失败定义是 8 秒内没有 DNS 回复，并观察到 exchange6/4: timeout: no recent network activity；同一报告也提醒，IPv6、其他平台、性能和当前 testing 运行时并未覆盖，因此日志相似不等于原因完全相同。
一个安全的排查顺序：恢复服务优先，再确认根因
- 备份当前配置和版本信息，不要直接覆盖原文件。
- 把 DoH3 的
detour改为 direct，确认 DoH3 本身、路径和 TLS 是否可用。 - 在 WireGuard 下先换成其他 DNS 传输，判断是 WireGuard 全部不可用，还是 QUIC/UDP 单独失败。
- 把 Peer 地址临时改为已核对 IP，检查
allowed_ips、端口、密钥和持久保活。 - 将 endpoint MTU 临时降到 1280 做对照；每次重启后重复冷启动、空闲后首次和连续查询。
- 如果低 MTU 可用，再逐步提高 MTU；如果只有 DoH3 仍失败，保留替代 DNS 传输，并等待上游版本或配置方案进一步确认。
不要直接把 Issue #4656 中的两行候选源码修改当作通用升级方案。该 issue 报告的是局部复现和候选修复，且正文明确指出这不是完整的 ICMP/PMTU 处理；更稳妥的做法是先用配置层对照测试定位，再根据官方版本说明决定是否升级。
最后核对：2026 年 10 月 26 日
本文结论基于截至 2026 年 10 月 26 日可查看的 sing-box 官方配置文档、WireGuard endpoint 文档，以及 GitHub Issue #4656 和 #4027。Issue #4027 曾报告 DoH3 经 WireGuard 失败，但维护者在 2026 年 4 月 19 日回复“无法重现”并关闭为 not planned；因此不能把它当作已确认的普遍 Bug。Issue #4656 提供了更具体的 1290 字节路径复现，但同样不覆盖所有平台和网络。
本文为 proxytips.cc 的技术整理，不代表 sing-box 官方，也没有把单次复现实验写成本站实测。若排查后仍存在跨境办公或长期 UDP 路径问题，建议先保留日志、版本、MTU 和对照结果，再评估网络线路本身是否适合当前业务。
常见问题
sing-box DoH3 WireGuard 失败，最可能是 MTU 吗？
在存在较小路径 MTU、禁止分片或回程 ICMP 处理异常时，MTU 是高优先级嫌疑。Issue #4656 在 1290 字节路径上复现了 DoH3 超时，但这只是特定环境证据。可先把 endpoint MTU 临时降到 1280，再重复冷启动和连续查询；如果恢复，再逐步提高确认临界点。
为什么 DoH3 直连正常，经过 WireGuard 就超时？
这通常说明 DoH3 服务器、TLS 或路径本身未必有问题，故障范围更集中在 WireGuard 的 UDP 通道、AllowedIPs、NAT、回程路径或 MTU。先移除 detour 做 direct 对照，再用其他 DNS 传输经过同一 WireGuard 出站测试。
domain_resolver 应该怎么设置，才能避免 DNS 回环？
当 DoH3 的 server 使用域名时，官方文档要求设置 domain_resolver。排错时应让它指向一个直连可用的 bootstrap DNS，并暂时避免让 Peer 地址和 DoH3 服务器域名依赖同一条尚未建立的 WireGuard-DNS 链路。
新版 sing-box 应该使用 WireGuard outbound 还是 endpoint？
应先按当前版本的官方 endpoint 文档检查配置。WireGuard endpoint 页面标注自 sing-box 1.11.0 起使用，1.14.0 又增加了 UDP NAT 字段；旧版 outbound 页面可帮助识别历史配置，但不能保证旧字段适用于当前版本。
日志里的 no recent network activity 代表什么？
它表示在等待窗口内没有收到有效网络活动或 DNS 回复，不等于已经证明是 sing-box 的固定 Bug。应结合是否有 handshake、lookup failed、TLS 错误，以及 direct、其他 DNS 传输和低 MTU对照结果一起判断。
相关阅读
参考资料
- sing-box Issue #4656：DoH3 over userspace WireGuard 在 1290 字节路径失败的本地复现
- sing-box 官方 HTTP3 DNS 配置文档
- sing-box 官方 WireGuard endpoint 配置文档（singbox.ai）
- sing-box Issue #4027：DoH3 通过 WireGuard 失败及无法重现结论