外观

故障排查 ​

“开启服务”不可用 ​

先检查“概览 → 系统自测”：

  1. “设置 → 内核”是否已经配置有效的内核组件；
  2. “配置”是否存在一份当前生效配置；
  3. 配置是否包含可用的本地入站和出站；
  4. 本地监听端口是否被其他程序占用。

订阅配置没有本地入站时，客户端通常会补建受管 Mixed 入口。仍提示缺少入口时，检查配置是否包含格式错误的 inbounds 数组，或当前代理端口是否超出 1–65535。

内核启动后仍无法连接 ​

客户端会等待内核健康检查和本地代理端口。如果这里失败：

  • 查看应用日志和内核日志中的第一条启动错误；
  • 检查配置字段和引用的 tag；
  • 在“能力信息”中确认当前内核支持配置所需的协议和传输；
  • 根据日志中的首个错误检查配置路径、字段和监听端口。

不要只根据进程存在判断服务可用；健康检查、本地监听和系统代理三者都需要成功。

TUN 无法开启或开启后断网 ​

TUN 运行需要兼容的 Zero 内核，并需要操作系统允许创建虚拟网卡和修改路由。先检查 TUN 状态中显示的配置来源，再判断应该修改当前配置还是客户端缺省值。

常见情况：

  • 权限不足：Windows 使用管理员权限运行；Linux/macOS 确保当前启动方式具备 TUN 与路由操作权限。客户端会尽量把权限错误直接显示出来；
  • Windows 提示 Wintun 问题：官方 Zero Core 0.0.1 Windows 发布包已经包含 Wintun。只有自行打包或文件不完整时才应优先检查组件缺失；
  • 地址或 MTU 无效：主地址和第二地址使用 CIDR，MTU 必须在 576–65535；
  • 网络切换后断流：新版 Zero 会重新协调物理出口和 TUN 捕获路由。仍失败时保存 underlay/route 相关日志，不要先手工给每个代理服务器添加永久 host route；
  • 切换配置后状态不一致：确认 TUN 的 configSource 已切换到新配置或客户端缺省值，并检查切换失败后的恢复日志；
  • 内核重启后 TUN 没恢复：确认客户端保存的期望状态仍为开启，并查看重启后的 TUN replay/reconcile 日志。

客户端管理的 TUN 可在运行中“保存并应用”，但会重建网卡；旧内核不能核实参数时采用关闭、保存、开启的流程。状态未知时先刷新确认，不要反复重试。内核启动成功但 TUN 恢复失败时，按独立的恢复错误处理，详见 TUN 指南。

TUN 已开启但 DNS 路径不符合预期 ​

在“设置 → DNS”确认模式、上游和保存应用结果，再检查 DNS 劫持及实际 TUN 运行状态。配置本身拥有 TUN 时，还要检查当前配置的 DNS/TUN 参数。

普通 53 端口劫持不能解密应用自己的 DoH/DoT/DoQ，也不能保证恢复 ECH 隐藏的主机名。系统代理不会自动接管全部 UDP、DNS 或 WebRTC。按 DNS 指南区分上游分流、Fake-IP 排除域名和 TUN 排除网段。

已连接但应用没有走代理 ​

  • 确认概览中的系统代理状态为“已开启”；
  • 检查目标应用是否自行覆盖系统代理；
  • 检查“设置 → 常规”的代理端口与内核实际 Mixed 监听是否一致；
  • 如果使用 TUN，确认 TUN 状态和系统权限，不要把 TUN 与系统代理状态混为一谈；
  • Windows 上检查是否有其他程序同时修改 ProxyServer、绕过列表或 PAC。

Lite 模式允许系统代理和 TUN 同时启用，因此看到两者都处于开启状态本身不是异常。

可以从托盘打开代理终端，用 curl 或包管理器验证注入的 HTTP/SOCKS5 环境变量。该终端可用而其他应用不可用时，问题通常在应用自身的代理设置。

订阅同步失败 ​

  • 检查 URL 是否仍然有效；
  • 检查网络是否允许访问订阅服务；
  • 自动检测只应根据本次订阅响应判断格式，不应由已有本地配置强行决定；
  • Zero 订阅使用规范的 zero 格式，即 Base64 编码的 Zero JSON；客户端不接受远程明文 Zero JSON；
  • Clash 等其他来源按当前支持的规范格式选择；
  • 查看错误是否来自下载、重定向、Base64 解码、YAML/JSON 解析还是格式转换；
  • 如果响应最终跳转到普通网页，检查服务端令牌和订阅模板，不要把网页强制按 Base64 解析。

一次同步失败不会覆盖原有可用配置。

节点或测速状态没有更新 ​

节点选择和测速结果通过运行时事件和策略快照更新。先确认事件连接正常，再检查 policy.probe.completed 是否到达。

还应确认：

  • 当前页面显示的配置与内核活动配置一致；
  • 切换配置后没有继续等待旧配置的测速；
  • URLTest 当前选中项已经按最新运行时策略快照同步；
  • 父 selector 中的 URLTest 没有同时被展开为全部成员重复测速；
  • 成员较多时已经等待自适应超时窗口；
  • 超时后到达的新鲜结果是否更新了卡片和悬浮历史。

客户端手动刷新 URLTest 时按当前策略的实际生效出站执行探测。如果 UI 仍显示旧选中项，优先检查策略事件/快照链路，而不是仅重复测速。

不要用连续点击或高频轮询代替事件链路排查。完整语义见本地代理、系统代理与节点测速。

实时连接切换配置后异常 ​

切换配置会清空旧配置的页面投影，但新的 flow 事件仍应持续进入。客户端会在事件流持续运行时同步活动连接快照，并按实际 flow 变化统计暂停期间的更新。

如果切换后只有重启应用才能看到新连接：

  1. 检查 GUI 事件连接是否仍然订阅；
  2. 检查新配置是否已经成为内核活动配置；
  3. 查看活动 flow reconciliation 是否持续执行；
  4. 保存配置切换前后第一批 flow.snapshot / lifecycle 事件用于排查。

打开终端没有反应 ​

Windows 托盘终端依赖 pwsh.exe 或 powershell.exe。检查应用日志中的 tray: open terminal、内核启动、本地代理监听和进程创建记录。终端只有在本地代理端口可用后才会打开。

仍无法定位 ​

按照数据与诊断导出诊断包，并附上：

  • ZNet Sink 版本；
  • 内核版本；
  • 操作系统与架构；
  • 当前配置名称以及是否刚发生过配置切换；
  • TUN 是否开启、由当前配置还是客户端缺省值管理；
  • 可以稳定复现的步骤；
  • 首次出现的错误，而不是只截取最后一条连带错误。

ZeroDeNet