蜂窝加速器-真专线线路

sing-box TUN 模式无法启动怎么排查?

更新于 2026-11-05 · fengwo88.site

简答:先看现象,不要直接重置网络:核心进程未启动,优先执行带配置路径的 check;TUN 网卡未创建,优先检查权限、VPN 冲突和系统扩展;TUN 已创建但断网,再检查 DNS、默认路由、系统代理和回滚状态。Windows、macOS、Linux 的命令和路径不同,Android 不要套用桌面端命令。

定义:sing-box TUN 模式是通过虚拟网络接口接管系统流量的运行方式,启动故障通常发生在配置解析、权限、虚拟网卡、路由或 DNS 初始化环节。

先分三类:看到什么现象就跳到对应分支

本文是第三方使用指南,不代表任何 sing-box 客户端或服务的官方支持。排查前先记录:操作系统及版本、客户端名称、sing-box 版本、完整的第一条错误,以及脱敏后的 TUN 配置片段。不要只复制最后一行“启动失败”,因为它往往只是前面错误的结果。

首屏速查:先判断故障阶段
现象首看内容先执行什么暂时不要做什么
客户端启动即闪退、核心没有进程unknown field、JSON 错误、deprecated、outbound 标签错误确认二进制路径,再执行 sing-box check -c 配置文件不要先改 DNS、路由或删除网卡
核心运行但 TUN 网卡没有出现permission denied、access denied、device already exists检查管理员/root 权限、旧 VPN、虚拟适配器和系统扩展不要直接执行网络重置或清空路由
TUN 出现但网页打不开route failed、timeout、DNS 错误、系统代理错误分别验证 DNS、默认路由、代理和普通入站不要把节点问题和 TUN 创建问题混在一起

配置检查通过,只能说明配置文件能够被当前核心解析,不能证明系统允许创建 TUN,也不能证明 DNS、路由和其他 VPN 没有冲突。sing-box 官方配置文档提供了 check、format 和 merge 等命令,具体参数以sing-box 官方配置文档为准。

反馈或继续求助时使用这个模板

  • 系统:Windows、macOS、Linux 或 Android,以及系统版本。
  • 客户端:客户端名称和界面版本;如果是命令行,注明二进制来源。
  • 核心:执行 sing-box version 后的完整输出。
  • 配置:执行 sing-box check -c 配置文件 的结果。
  • 日志:从启动开始的第一条错误,隐藏服务器地址、UUID、密码和密钥。
  • 现象:核心未启动、TUN 未出现,还是 TUN 出现后断网。

第一步:确认核心、配置文件和工作目录

命令行排查最常见的误判是:命令执行成功,但实际检查的不是客户端正在使用的配置文件。先进入 sing-box 二进制所在目录,或使用绝对路径执行。以下示例中的路径需要替换为你的真实路径。

分平台命令与正常判断
平台确认核心检查配置正常结果应关注什么
Windowswhere sing-box
sing-box version
sing-box check -c "C:\path\config.json"命令能找到核心;check 不再出现 JSON、unknown field 或标签引用错误
macOScommand -v sing-box
sing-box version
sing-box check -c "$HOME/path/config.json"输出的核心版本与客户端实际使用的版本一致
Linuxcommand -v sing-box
sing-box version
sudo sing-box check -c /etc/sing-box/config.json检查的是服务实际加载的配置,而不是下载目录中的旧文件

如果系统提示找不到命令,先不要据此判断配置损坏。Windows 可使用客户端目录中的 sing-box.exe 绝对路径;macOS、Linux 可使用 /完整路径/sing-box。如果通过 systemd 运行,官方安装文档给出的日志查看方式是 sudo journalctl -u sing-box --output cat -e,持续查看可使用 sudo journalctl -u sing-box --output cat -f,参见sing-box 官方安装与服务管理文档。

版本迁移不要凭记忆改字段

如果日志出现 unknown field 或 deprecated,先记录版本,再对照对应版本的迁移说明。官方迁移页明确列出:1.10.0 将 TUN 的 inet4_address、inet6_address 等字段合并到 address;1.15.0 起 TUN 使用自有 TCP/IP 栈,旧的 stack 选项已标记为废弃,并计划在 1.17.0 移除。不要把这些迁移规则套到所有版本,修改前应查看sing-box 官方 Migration 文档。

第二步:用最小 TUN 配置隔离配置、权限和路由

“最小配置”不是把字段随意删到无法启动,而是先保留一个 TUN 入站、一个 direct 出站和日志,暂时移除复杂 DNS、规则集、自动路由、系统代理联动以及多个监听端口。它的目的只是判断核心能否创建 TUN,不代表可直接作为日常上网配置。

下面示例用于隔离 TUN 创建问题。它不包含节点、DNS 劫持和复杂路由;如果你的客户端要求额外字段,仍应以客户端生成的配置和当前官方文档为准。

{"log":{"level":"debug","timestamp":true},"inbounds":[{"type":"tun","tag":"tun-in","address":["172.19.0.1/30"],"auto_route":false}],"outbounds":[{"type":"direct","tag":"direct"}]}

  1. 备份原配置,不要直接覆盖订阅或客户端生成的文件。
  2. 将示例保存为单独文件,例如 Windows 的 C:\temp\sing-box-min.json、macOS 的 ~/tmp/sing-box-min.json,Linux 的 /tmp/sing-box-min.json。
  3. 执行对应平台的 sing-box check -c 文件路径。
  4. 先以当前客户端支持的方式启动最小配置,观察日志是否出现 TUN 创建错误。
  5. 如果最小配置可以创建 TUN,再按“普通入站或节点 → TUN → auto_route → DNS → 规则 → strict_route”的顺序一次恢复一项,每次重启并记录结果。

auto_route 会把默认路由设置到 TUN;官方文档同时提醒,为避免流量回环,需要配合自动检测接口、默认接口或出站绑定接口等设置。排障时先关闭它,有助于区分“网卡创建失败”和“路由接管失败”,参见sing-box 官方 TUN 文档。

在 Linux 上,auto_redirect 只在启用 auto_route 时生效,并依赖 nftables 相关能力;官方文档将其描述为 Linux 场景下改善 TUN 路由、性能并减少 Docker bridge 冲突的选项。它不是 Windows 或 macOS 的通用修复开关,也不是所有 Linux 环境都能无条件启用。

Windows:管理员权限、Wintun、虚拟适配器和代理残留

1. 先用管理员权限复现。退出客户端后,右键客户端选择“以管理员身份运行”。如果是命令行,在管理员 PowerShell 或命令提示符中运行核心。若管理员运行后仍出现 access denied,再检查其他 VPN、虚拟机网络工具和旧客户端。

2. 查看虚拟网络适配器。打开“设置 → 网络和 Internet → 高级网络设置”,查看是否存在旧的 VPN、Wintun 或 sing-box 虚拟适配器。只处理明确属于旧客户端且当前未使用的虚拟适配器,不要禁用正在使用的 Wi-Fi、以太网或企业安全软件适配器。

3. 检查系统代理。打开“设置 → 网络和 Internet → 代理”,关闭不再使用的手动代理和自动配置脚本。关闭客户端窗口不一定等于系统代理已经恢复,因此要直接查看该页面。

4. 检查 WinHTTP,但先保存原输出。在管理员命令提示符中执行:

  • netsh winhttp show proxy:记录当前 WinHTTP 代理配置。
  • netsh winhttp dump > "%USERPROFILE%\Desktop\winhttp-before.txt":尝试保存当前配置,便于后续核对。

只有确认这台设备不依赖企业代理、自动发现或办公软件的 WinHTTP 设置后,才考虑执行 netsh winhttp reset proxy。该命令会将 WinHTTP 代理恢复为 DIRECT;Microsoft 文档说明了 show proxy、dump 和 reset proxy 的作用,参见Microsoft netsh winhttp 文档。执行后若企业软件失去联网能力,应联系设备管理员按原策略恢复,不要继续修改 sing-box 配置。

5. 端口被占用时查 PID。如果日志出现 address already in use,在管理员命令提示符执行 netstat -ano | findstr :7890,把示例端口替换为日志中的端口。记录 PID 后,在任务管理器“详细信息”中确认进程,只有确定是旧客户端或测试进程时才结束它;也可以改用未占用端口。

6. strict_route 只用于最后的对照测试。官方 TUN 文档说明,Windows 的 strict_route 可防止 DNS 泄漏,但在某些情况下可能导致 VirtualBox 等应用无法正常工作。排障时先关闭它,确认基础 TUN 和路由正常后再按需求启用。

macOS:网络扩展、VPN 项、系统代理和授权

1. 检查 VPN 冲突。打开“系统设置 → VPN”,确认其他 VPN 没有处于连接状态。若多个客户端同时尝试接管系统流量,TUN 创建或路由写入可能互相影响。

2. 检查扩展和授权。打开“系统设置 → 通用 → 登录项与扩展”,查看客户端使用的网络扩展是否被关闭或等待授权。Apple 的 Mac 设置文档说明,登录项与扩展入口用于管理系统扩展;相关路径可参考Apple 登录项与扩展设置说明。

3. 检查代理残留。打开“系统设置 → 网络 → Wi-Fi 或以太网 → 详细信息 → 代理”,检查 HTTP、HTTPS、SOCKS 和自动代理配置是否仍指向已退出的客户端。Apple 的网络设置文档包含 VPN、DNS 和代理项目,参见Apple Mac VPN 与网络设置说明。

4. 分离普通连接和 TUN。先关闭 TUN 和系统代理,只测试普通入站或基础连接;普通连接能工作后,再启用 TUN。若普通入站也无法连接,优先检查配置、出站标签和节点,不要把问题归因于 macOS 网络扩展。

5. 恢复顺序。关闭 TUN → 退出客户端 → 检查 VPN 项和网络扩展 → 恢复代理页面 → 重新启动客户端。不要为了启动 TUN 而降低 macOS 的整体安全设置;如果系统扩展明确被阻止,应使用客户端维护者提供的兼容版本或授权说明。

Linux:TUN 设备、路由、规则和 DNS 逐项核对

1. 检查 TUN 设备。执行 ls -l /dev/net/tun。如果文件不存在,可先执行 sudo modprobe tun 后再次检查。若设备存在但日志仍显示 permission denied,使用 root 启动进行对照;长期运行所需的 capability 应按发行版和服务管理方式配置,不要直接给二进制添加不必要权限。

2. 记录启动前后的网络状态。启动前执行以下命令并保存输出:

  • ip link:记录已有网卡和是否存在旧 TUN 接口。
  • ip route:记录默认路由和默认出口。
  • ip rule:记录策略路由规则。
  • resolvectl status:记录当前 DNS 链路;若系统没有该命令,查看发行版实际使用的 DNS 服务。

启动最小配置后重复这些命令。正常判断不是“输出必须完全一样”,而是确认新 TUN 接口是否出现、默认路由是否按配置变化、策略路由是否新增,以及 DNS 是否仍指向可用的上游。若启动后默认路由消失或指向错误接口,先关闭 TUN 恢复原网络,再检查 auto_route、默认接口和路由表设置。

Linux 命令、正常观察点与下一步
命令重点看什么异常时下一步
ip link是否出现 TUN 接口,接口是否为 UP没有接口:查权限、模块和其他 VPN;接口存在但 DOWN:查客户端日志
ip route默认路由、TUN 路由和出口接口默认路由异常:关闭 TUN,检查 auto_route 和默认接口
ip rule是否出现 sing-box 相关策略规则规则缺失或冲突:检查 auto_route、auto_redirect 和现有 nftables 策略
resolvectl status当前 DNS 服务器、接口和域名解析状态DNS 不可达:暂时关闭 DNS 劫持,先验证普通解析

3. 谨慎启用 auto_redirect。官方 TUN 文档说明,Linux 上它需要配合 auto_route,并使用 nftables 改善路由;如果机器运行 Docker、Podman 或自定义防火墙规则,先保存现有规则,再单独启用并观察变化。它的适用条件是 Linux,不应作为 Windows 或 macOS 的排障步骤。

报错对照:核心日志与浏览器提示分开处理

按错误来源分组的处理优先级
错误来源提示或日志优先处理
核心日志unknown field、deprecated记录版本,对照官方 migration 文档,修正字段后重新执行 check
核心日志permission denied、access deniedWindows 以管理员运行;Linux 检查 TUN 设备和权限;macOS 检查网络扩展授权
核心日志device already exists、interface exists退出其他 VPN,检查旧虚拟网卡和残留进程,再重启
核心日志address already in use使用 Windows 的 netstat -ano 或 Linux/macOS 的 lsof -i :端口 查占用
核心日志route failed、cannot add route先关闭 auto_route 或 strict_route 做对照,再检查默认接口和现有路由
浏览器或系统提示ERR_CONNECTION_REFUSED检查浏览器指向的本地端口是否有 sing-box 入站监听
浏览器或系统提示ERR_PROXY_CONNECTION_FAILED检查 Windows“设置 → 网络和 Internet → 代理”或 macOS“网络 → 详细信息 → 代理”中的残留设置
浏览器或系统提示DNS_PROBE_FINISHED_NXDOMAIN先区分域名确实不存在,还是 DNS 上游、劫持规则或本地解析失败
浏览器或系统提示timeout、连接超时先测本地入站,再测 DNS 和路由,最后检查节点与 MTU;不要先改多个变量

浏览器错误不一定会出现在 sing-box 日志中。判断顺序应是:核心是否运行 → TUN 是否创建 → 本地监听是否可达 → DNS 是否能解析 → 默认路由是否正确 → 节点或出站是否可用。

Android 不能直接套用桌面端排查方法

Android 的 TUN 通常依赖系统 VPN 接口和客户端的 VPN 权限,不能直接使用 Windows 的管理员命令、macOS 的网络扩展路径或 Linux 的 /dev/net/tun 检查。sing-box 官方 TUN 文档列出了 Android 专用的用户、应用包和 VPN 相关选项;如果 Android 客户端提示 TUN 无法启动,应先检查系统弹出的 VPN 授权、是否已有其他 VPN 连接、客户端是否被系统限制后台运行,以及客户端自己的日志。

如果 Android 上只是部分应用无法联网,先关闭其他 VPN 和分应用规则,再用最小配置或全局允许的方式做一次对照。官方文档还说明,某些大量路由的功能受 Android VpnService 能力限制,因此不要把桌面端的 route address set 配置原样复制到 Android 图形客户端。相关适用范围以官方 TUN 文档和官方图形客户端列表为准。

安全回滚:先轻后重,再验证原网络

  1. 关闭 TUN、DNS 劫持、auto_route、auto_redirect 和系统代理开关。
  2. 完全退出 sing-box 及其他 VPN 客户端,等待虚拟接口和监听端口释放。
  3. 检查系统代理、VPN 项和虚拟适配器;Windows 额外检查 WinHTTP,Linux 记录路由和规则。
  4. 只有在确认设备原本支持直连、且不依赖企业代理的前提下,验证浏览器或命令行是否恢复原网络。不要把“关闭 TUN 后必须直连成功”当作所有设备都适用的结论。
  5. 若 Windows 仍异常,确认已保存 WinHTTP 原输出后再考虑 netsh winhttp reset proxy;若 macOS 仍异常,重新检查 VPN 和网络扩展;若 Linux 仍异常,恢复启动前保存的路由和 DNS 配置。
  6. 最后才考虑系统级网络重置,并先确认不会影响企业策略、虚拟机、容器或远程办公配置。

验证时先使用低风险检查:Windows 可用 ipconfig、netsh winhttp show proxy,macOS 可查看网络代理页面,Linux 可重复执行 ip route 和 resolvectl status。如果原网络恢复,再按最小配置逐项加回 TUN、auto_route、DNS、规则和 strict_route。

了解边界云加速的线路方案与网络诊断服务,具体配置和可用性以官网说明为准。

常见问题

sing-box check 通过,为什么 TUN 还是无法启动?

check 主要验证配置是否能被当前核心解析,不能替代管理员或 root 权限、虚拟网卡、系统扩展、路由和 DNS 检查。通过 check 后仍要根据日志确认 TUN 是否真的创建成功。

最小 TUN 配置应该保留哪些字段?

排障时可保留 log、一个 tun 入站、address、一个 direct 出站和必要的 tag;暂时移除复杂 DNS、规则集、多个监听端口、auto_route、auto_redirect 和 strict_route。它只用于隔离启动问题,不代表日常可用配置。

Windows 关闭 sing-box 后仍然无法上网怎么办?

先确认这台设备原本支持直连,再打开“设置 → 网络和 Internet → 代理”检查手动代理和自动配置脚本。随后在管理员命令提示符中执行 netsh winhttp show proxy,保存输出;只有确认不依赖企业 WinHTTP 代理时,才考虑 netsh winhttp reset proxy。

macOS 上 TUN 启动失败应该先看哪里?

先打开“系统设置 → VPN”确认没有其他 VPN,再到“系统设置 → 通用 → 登录项与扩展”检查网络扩展授权,最后打开“系统设置 → 网络 → Wi-Fi 或以太网 → 详细信息 → 代理”清理旧代理。

Linux 没有 /dev/net/tun 会导致启动失败吗?

可能会。先执行 ls -l /dev/net/tun;文件不存在时,可用 sudo modprobe tun 做一次对照。设备存在但仍提示权限不足,则检查运行用户、服务权限和 capability,不要直接清空整套路由。

strict_route 和 auto_route 应该先开哪个?

排障时建议先验证 TUN 能否创建,再单独启用 auto_route,最后根据需求测试 strict_route。auto_route 负责把默认路由设置到 TUN;strict_route 会强化路由约束,Windows 某些应用可能因此受到影响,具体以当前版本官方 TUN 文档为准。

Android 可以照搬 Linux 的 TUN 排查命令吗?

不建议。Android 图形客户端通常通过系统 VPN 接口工作,应优先检查 VPN 授权、其他 VPN、后台限制和客户端日志;/dev/net/tun、ip route 等桌面或 Linux 命令不能作为 Android 图形客户端的通用判断依据。

相关阅读

参考资料

  1. Tun - sing-box 官方文档
  2. Configuration - sing-box 官方文档
  3. Migration - sing-box 官方文档
  4. Package Manager - sing-box 官方文档
  5. Graphical Clients - sing-box 官方文档
  6. netsh winhttp - Microsoft Learn
  7. Change Login Items & Extensions settings on Mac - Apple Support
  8. Change VPN settings on Mac - Apple Support