12. 观测与排障#
Link1 的排障原则：先确认流量是否进入 Link1，再确认域名/IP 是否正确，再确认规则命中，再确认策略组选择，再确认出站协议是否成功。
排障总流程#
1. 内核是否运行
2. 流量是否进入 Link1
3. Link1 是否知道正确目标
4. 规则是否命中预期 action
5. 策略组是否选择预期节点
6. 出站协议是否连通
7. DNS、TUN、HTTP Engine 等高级能力是否影响结果不要一开始就改协议参数。很多“节点不可用”其实是客户端没进代理、DNS 没进 Link1、规则顺序错、策略组当前选了 DIRECT。
App 中最常用的观测位置#
| 位置 | 用途 |
|---|---|
| 首页运行状态 | 确认内核是否运行、配置是否应用、实时速率是否变化 |
| 连接列表 | 查看真实连接、目标、命中规则、出站和错误 |
| 策略组页面 | 查看当前选择、节点延迟和健康状态 |
| Provider 页面 | 查看订阅刷新、过滤结果、节点数量 |
| DNS/Fake-IP 信息 | 判断域名是否由 Link1 解析 |
| 规则测试 | 构造虚拟连接，验证规则顺序和 action |
| 日志页面 | 定位配置、DNS、拨号、协议握手、HTTP Engine 错误 |
| HTTP 捕获 | 查看被 Capture 的 HTTP 请求/响应 |
1. 内核是否运行#
App 中应先确认：
- 当前配置档案已应用。
- 状态显示运行中。
- 没有端口占用、权限不足、TUN 创建失败等启动错误。
直接运行内核时可用：
spark -f config.yaml -t
spark -d . -f config.yaml如果 -t 通过但启动失败，多半是运行环境问题，例如端口被占用、没有创建 TUN 的权限、路由器缺少内核能力或证书文件路径错误。
2. 流量是否进入 Link1#
显式代理#
用最小请求验证：
curl -x http://127.0.0.1:7890 https://www.example.com/然后看 App 连接列表是否出现 www.example.com。
如果没有出现：
- 客户端代理地址可能填错。
- 系统代理没有生效。
- 浏览器用了自己的代理设置。
- 请求被
--noproxy或系统绕过规则跳过。
- 你看的不是当前运行的配置档案。
TUN#
看 App 或系统网络设置：
- TUN 是否已启用。
- 系统默认路由是否指向 TUN。
auto-route是否生效。
- 是否有
route-exclude-address把目标排除。
- DNS hijack 是否生效。
路由器透明代理#
先在路由器本机验证出站，再从局域网设备验证。重点看：
- 局域网设备默认网关是否是路由器。
- 防火墙规则是否把 TCP/UDP 导入 Link1。
- DNS 查询是否也进入路由器。
- 是否有私网、旁路由、IPv6 路由绕过。
3. Link1 是否知道正确目标#
连接详情里应看：
- 目标是域名还是 IP。
- 如果是 Fake-IP，是否能反查回域名。
- Sniffer 是否识别了 HTTP Host / TLS SNI / QUIC SNI。
- DNS 日志是否出现该域名。
如果规则写的是 DOMAIN-SUFFIX,example.com,PROXY，但连接详情只有 93.184.216.34:443，域名规则可能不会命中。处理：
- 显式代理场景：让客户端把域名交给 HTTP/SOCKS 代理。
- TUN/透明代理场景：开启 Link1 DNS、Fake-IP 和 DNS hijack。
- HTTPS/QUIC 场景：按需开启 Sniffer，但不要把 Sniffer 当成 DNS 替代品。
4. 规则是否命中预期#
用 App 的规则测试输入目标 host、IP、端口、网络类型、入站类型和源 IP，确认：
- 是否命中你预期的规则。
- 是否过早命中更靠前的规则。
- 是否落到了最后的
MATCH。
- action 是节点、策略组、
DIRECT还是REJECT。
真实连接和规则测试不一致时，优先比较元数据：真实连接是不是只有 IP？入站类型是不是不同？源 IP 是否不同？端口是否不同？
5. 策略组是否选了预期节点#
在策略组页面确认：
- 规则 action 指向哪个组。
- 该组当前选中哪个成员。
- 成员是否健康。
- 自动组是否因为延迟测试选择了另一个节点。
use引入的 provider 是否真的有节点。
常见误解：
| 现象 | 解释 |
|---|---|
规则指向 PROXY 但实际走 DIRECT | PROXY 组里当前选中了 DIRECT |
url-test 没选你想要的节点 | 它按测试 URL 的结果选择，不按目标网站选择 |
| 订阅刷新成功但组为空 | filter/exclude-filter 把节点过滤掉了 |
| 节点显示可用但某网站慢 | 健康检查 URL 与目标网站路径不同，只能代表部分网络质量 |
6. 出站协议是否连通#
出站失败通常有四类：
| 类别 | 典型现象 | 检查点 |
|---|---|---|
| DNS/网络不可达 | timeout、no route、connection refused | server 能否解析，端口是否可达 |
| 认证失败 | auth failed、bad password、invalid user | 密码、UUID、token、用户名是否正确 |
| TLS/指纹失败 | certificate、handshake、fingerprint 错误 | sni、servername、skip-cert-verify、client-fingerprint |
| 协议参数不匹配 | QUIC/TUIC/Hysteria2 握手失败 | 版本、ALPN、拥塞控制、上传下载带宽、UDP 开关 |
排查顺序：
- 用最小配置只保留一个节点和
MATCH。
- 在策略组中直接选择该节点。
- 发起一个简单请求。
- 看日志中第一个协议相关错误。
- 对照 出站协议配置 检查必填字段。
7. DNS 常见问题#
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 域名规则不命中 | DNS 没进入 Link1 | 开启 dns.enable、TUN dns-hijack 或显式代理域名转发 |
| 国内网站走代理 | 规则顺序错误或 GeoData 不可用 | 检查 RULE-SET、GEOIP、Geo 文件 |
| 部分域名解析慢 | nameserver 超时或 fallback 过多 | 缩短上游链路，按域名分流 DNS |
| Fake-IP 访问内网失败 | 内网域名被分配 Fake-IP | 加入 fake-ip-filter 或 hosts |
| IPv6 结果异常 | 全局 ipv6 与 dns.ipv6 不一致 | 明确决定是否启用 IPv6 |
8. TUN 常见问题#
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 开启后断网 | 默认路由冲突、DNS 未接管、出站也被 TUN 捕获 | 检查 auto-route、strict-route、排除地址 |
| 只有浏览器可用 | 浏览器仍走显式代理，系统流量未进 TUN | 确认 TUN 状态和系统路由 |
| UDP 不通 | 出站节点不支持 UDP 或透明代理链路不支持 | 检查节点 udp 和协议能力 |
| 局域网访问异常 | 私网地址被代理或 Fake-IP 影响 | 加私网规则、route exclude、fake-ip-filter |
| macOS 平台冲突 | 同时启用多个透明入口 | 保留一种接管方式 |
9. Provider 常见问题#
| 现象 | 常见原因 | 处理 |
|---|---|---|
| provider 没节点 | 下载失败、格式不对、过滤过严 | 看 Provider 页面错误和节点数量 |
| 订阅节点有但组里没有 | proxy-groups.use 没引用 provider | 检查组配置 |
| 节点名字变化导致选择丢失 | 订阅更新后节点名称改变 | 使用稳定 provider 或手动组 |
| 健康检查全失败 | 测试 URL 不可达或节点全不可用 | 换测试 URL，确认基础网络 |
| WARP 候选不可用 | 账号/密钥/endpoint/本机 UDP 问题 | 对照 WARP provider 示例逐项检查 |
10. HTTP Engine 常见问题#
| 现象 | 常见原因 | 处理 |
|---|---|---|
| 没有捕获 | Capture 未启用、host 未命中、流量未进入 HTTP Engine | 检查 http-engine.enabled、capture.enabled、match |
| HTTPS 看不到 body | 未开启 MITM 或客户端不信任 CA | 配置 mitm.hosts 并安装 CA |
| 开启后网站打不开 | 证书不被信任、规则 fail-closed、body 过大 | 缩小 MITM host，改 on-error: fail-open |
| 改写不生效 | match 条件不匹配或方向错误 | 看 flow 的 host/path/method 和规则方向 |
| Capture 占磁盘 | 保存完整 body 且限制过大 | 降低 max-flows 和 full-body-max-bytes |
11. 日志关键词速查#
| 关键词 | 层级 | 解释 |
|---|---|---|
compile config | 配置编译 | YAML 字段、引用或组合错误 |
listen / bind | 入站 | 端口占用或权限问题 |
tun / route | TUN | 虚拟网卡、路由或权限问题 |
dns、resolve、rcode、nameserver | DNS | DNS 上游、Fake-IP、分流问题 |
rule / match | 路由 | 规则命中或规则集加载问题 |
provider | Provider | 订阅下载、文件读取、过滤、健康检查 |
dial / connect | 出站 | 远端连接失败 |
handshake | 协议/TLS | 认证、证书、指纹或协议参数错误 |
mitm / capture / rewrite | HTTP Engine | 证书、捕获、改写规则问题 |
常见网络错误白话翻译#
不同平台的错误文本可能略有差异，但含义大致相同。排障时不要只看最后一个错误，要结合它出现在 DNS、拨号、TLS 握手还是 HTTP Engine 阶段。
| 错误/关键词 | 白话含义 | 常见原因 | 先检查什么 |
|---|---|---|---|
connection refused | 对方机器收到了连接，但端口没人接 | 端口写错、服务没启动、防火墙主动拒绝 | server/port，上游服务状态 |
timeout / i/o timeout | 发起连接或读写等待超时 | 网络不通、UDP 被挡、上游太慢、DNS 卡住 | DNS 解析结果、端口可达性、节点健康 |
no route to host | 本机不知道怎么到达目标 | 路由表错误、TUN/透明代理路由冲突、网关不可达 | TUN auto-route、排除路由、默认网关 |
network is unreachable | 目标网络不可达 | IPv6 开了但本机没 IPv6、路由缺失 | ipv6/dns.ipv6、ip-version |
EOF | 对端提前断开连接 | 协议不匹配、TLS/SNI 错误、上游主动关 | 协议 type、TLS、SNI、认证字段 |
unexpected EOF | 读到一半连接断了 | 中间链路断开、服务端关闭、证书/协议失败 | 第一条握手错误、上游日志 |
tls: certificate | 证书校验失败 | SNI 不匹配、自签证书、系统时间错误 | servername/sni、skip-cert-verify、时间 |
handshake failure | 协议握手失败 | 密码/UUID/ALPN/REALITY/obfs 不一致 | 协议章节中的必填字段和组合表 |
authentication failed / auth failed | 认证失败 | 用户名、密码、UUID、token 错 | 凭据是否复制完整，有无多余空格 |
context canceled | 请求被取消 | 用户关闭连接、超时保护触发、配置切换 | 是否手动停止、是否有超时/重载 |
body exceeds max size | body 超过规则允许读取大小 | HTTP Engine/JQ/QuickJS body 太大 | max-size、body-max-size、是否真的要读 body |
body is required but unavailable | 规则要求 body，但当前没有可读 body | 流式 body、无 body、方向写错 | require-body、direction、match 条件 |
ReferenceError | QuickJS 访问了不存在的变量/对象 | 拼写错误，或使用了 console/fetch/DOM 等不存在的环境 | QuickJS 调试方法 |
12. 典型问题处理#
浏览器设置了代理但没流量#
- 确认浏览器代理端口是
mixed-port。
- 用
curl -x做最小验证。
- 看 App 连接列表是否出现请求。
- 如果没有，检查系统代理绕过规则和浏览器代理插件。
规则写了域名但不命中#
- 看连接详情目标是域名还是 IP。
- 如果是 IP，检查 DNS 是否进入 Link1。
- TUN/透明代理下开启 Fake-IP 和 DNS hijack。
- 必要时开启 Sniffer 作为补充。
策略组明明选了节点但还直连#
- 看真实连接命中的规则 action。
- 确认 action 是否真的指向这个策略组。
- 检查前面是否有
DIRECT规则提前命中。
- 检查是否有
SUB-RULE、AND、OR改变流程。
某个节点所有网站都打不开#
- 用最小配置只保留该节点。
- 确认服务器地址和端口可达。
- 检查协议必填字段。
- 检查 TLS/SNI/指纹和证书验证设置。
- 如果依赖
dialer-proxy，先验证前置节点可用。
路由器上内网设备无法使用#
- 确认内网设备网关和 DNS 指向路由器。
- 确认 Link1 监听在路由器可访问地址。
- 确认防火墙/路由规则把流量导入 Link1。
- 检查私网地址是否被错误代理。
- 分别测试 TCP、UDP 和 DNS。
13. 给别人反馈问题时应提供什么#
建议提供：
- Link1 App 版本和内核版本。
- 当前平台：Windows/macOS/Linux/路由器/手机。
- 入口方式：显式代理、TUN、路由器透明代理或 listener。
- 最小可复现配置，删除密码、私钥、订阅地址等敏感信息。
- App 连接详情截图或复制文本。
- 相关日志片段，从第一次错误开始，不要只截最后一行。
- 你期望命中的规则和实际命中的规则。
- 你期望使用的出站和实际使用的出站。
不要直接公开订阅地址、节点密码、WireGuard 私钥、企业 VPN 凭据、HTTP Capture body 或完整证书私钥。