sing-box TUN 模式无法启动怎么排查?
简答:先看现象,不要直接重置网络:核心进程未启动,优先执行带配置路径的 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 二进制所在目录,或使用绝对路径执行。以下示例中的路径需要替换为你的真实路径。
| 平台 | 确认核心 | 检查配置 | 正常结果应关注什么 |
|---|---|---|---|
| Windows | where sing-boxsing-box version | sing-box check -c "C:\path\config.json" | 命令能找到核心;check 不再出现 JSON、unknown field 或标签引用错误 |
| macOS | command -v sing-boxsing-box version | sing-box check -c "$HOME/path/config.json" | 输出的核心版本与客户端实际使用的版本一致 |
| Linux | command -v sing-boxsing-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"}]}
- 备份原配置,不要直接覆盖订阅或客户端生成的文件。
- 将示例保存为单独文件,例如 Windows 的
C:\temp\sing-box-min.json、macOS 的~/tmp/sing-box-min.json,Linux 的/tmp/sing-box-min.json。 - 执行对应平台的
sing-box check -c 文件路径。 - 先以当前客户端支持的方式启动最小配置,观察日志是否出现 TUN 创建错误。
- 如果最小配置可以创建 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、默认接口和路由表设置。
| 命令 | 重点看什么 | 异常时下一步 |
|---|---|---|
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 denied | Windows 以管理员运行;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 文档和官方图形客户端列表为准。
安全回滚:先轻后重,再验证原网络
- 关闭 TUN、DNS 劫持、auto_route、auto_redirect 和系统代理开关。
- 完全退出 sing-box 及其他 VPN 客户端,等待虚拟接口和监听端口释放。
- 检查系统代理、VPN 项和虚拟适配器;Windows 额外检查 WinHTTP,Linux 记录路由和规则。
- 只有在确认设备原本支持直连、且不依赖企业代理的前提下,验证浏览器或命令行是否恢复原网络。不要把“关闭 TUN 后必须直连成功”当作所有设备都适用的结论。
- 若 Windows 仍异常,确认已保存 WinHTTP 原输出后再考虑
netsh winhttp reset proxy;若 macOS 仍异常,重新检查 VPN 和网络扩展;若 Linux 仍异常,恢复启动前保存的路由和 DNS 配置。 - 最后才考虑系统级网络重置,并先确认不会影响企业策略、虚拟机、容器或远程办公配置。
验证时先使用低风险检查: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 图形客户端的通用判断依据。