ConnProof

如何阅读 ConnProof 报告中的状态、证据和错误码 ​

一份诊断报告拿在手里，价值取决于你能从中读出多少。这篇指南把报告逐段拆开，说明每个部分回答什么问题、哪些字段值得优先看、以及新手最常见的几个误读。读完之后，你应该能在三十秒内从任何一份 ConnProof 报告里提取出"问题在哪一层、下一步做什么"。

报告的骨架 ​

文本格式的报告从上到下依次是：目标 → 结论 → 诊断代码 → 严重程度 → 检测证据 → 可能原因 → 建议操作 → 详细文档链接 → 隐私声明。阅读的高效顺序其实是三步：

  1. 看诊断代码（如 TLS-002）：它是整份报告的索引键，直接决定你该打开哪篇文档；
  2. 看证据区的 ✗ 行：失败发生在哪一层、耗时多少、具体观察是什么；
  3. 看 ✗ 之前最后一个 ✓：最后一个成功的层告诉你"路通到了哪里"——这正是分层诊断的价值所在。

结论和原因列表是对以上信息的人话翻译，先看证据再看翻译，你对报告的理解会深一层。

六种状态的准确含义 ​

符号状态你应该读作
✓pass这一步真实执行过，且没有发现问题
✗fail这一步真实执行过，确认存在问题
!warning执行过，有值得注意的情况，但不一定是故障主因
○skipped没有执行——通常因为前一层已失败
○unsupported想执行但当前环境不支持这项检测
?inconclusive执行了，但拿到的证据不足以下结论

三个常见误读值得纠正：

  • skipped 不是 fail。TLS 显示 skipped 只是因为 TCP 没通，不代表 TLS 有问题——修好 TCP 后它可能完全正常；
  • warning 不一定要处理。证书还有 12 天到期是 warning，它提醒你关注，但与你今天的连接故障未必相关；
  • inconclusive 不是工具坏了。它是工具在说"我测了，但这个证据回答不了你的问题"——通常意味着需要换一个检测角度（比如从浏览器检测转到 CLI）。

证据条目的解剖 ​

每条证据五个字段：标签说明观察项（如"TCP 443 建连"），值是观察结果（如"成功，耗时 118 ms"），来源标注产生它的检测器（dns/tcp/tls/websocket/subscription/http），时间戳精确到毫秒，redacted 标记该条是否被脱敏改写过。

值里的耗时数字不只是装饰：

  • DNS 解析超过几百毫秒 → 解析链路偏慢，即使成功也值得留意；
  • TCP 建连的耗时大致对应网络往返时间，同城目标几毫秒、跨洋上百毫秒是正常量级，与预期严重不符时可能绕了路；
  • TLS 握手耗时约为 TCP 建连的一到两倍（多一到两个往返）属正常，显著超出则握手过程有蹊跷；
  • 失败证据里的耗时同样有信息——"失败于 3 ms"和"失败于 10000 ms"是两种完全不同的失败（前者是本地或近端的果断拒绝，后者是等到超时的杳无音信）。

错误码怎么用 ​

错误码的格式是"分类-三位数字"：DNS、TCP、TLS、HTTP、WS（WebSocket）、SUB（订阅）、PROXY（代理环境）、LONG（长连接）、CLIENT（客户端行为）、ROUTE（出口线路）。三个使用姿势：

  1. 搜索：在本站搜索框直接输入错误码，或把它连同原始报错一起交给搜索引擎；
  2. 沟通：向客服或社区求助时报上错误码，比描述症状高效得多——"TLS-002，证据显示 TCP 通、握手超时"一句话就把问题说清了；
  3. 追踪：错误码永不变更，你可以放心把它记进自己的运维笔记，明年它还是这个意思。

报告尾部的文档链接由错误码自动生成，指向本站对应的排查文档——那里有按平台展开的具体步骤。

JSON 与 Markdown 格式的用法 ​

同一份报告可以渲染成三种格式（--format text|json|markdown），数据完全一致：

  • text 给人看，终端里带颜色；
  • json 给程序看：字段集稳定（reportVersion 标记结构版本），包含完整的结构化 findings、每条证据、环境快照与隐私元数据。客服系统可以直接解析它自动分类工单；自动化脚本可以取 summary.fail 判断是否有故障；
  • markdown 给工单和 Issue：状态表格 + 证据列表 + 可点击的文档链接，粘贴即用。

实用技巧：诊断跑完后想换格式不必重跑——connproof report --format markdown 会把本地保存的最近一次报告（已脱敏）重新渲染。

一次完整的读报演练 ​

把方法串起来走一遍。假设你拿到这样一份报告（示例结构，非真实检测）：

text
诊断代码：TLS-002
检测证据：
✓ DNS A 记录解析：返回 2 个 IPv4 地址，耗时 42 ms
✓ DNS AAAA 记录解析：返回 2 个 IPv6 地址，耗时 45 ms
✓ TCP 443 建连：成功，耗时 118 ms
✓ SNI：目标域名
✗ TLS 握手：超时（10000 ms）

三步读法的应用：第一步，错误码 TLS-002 → 打开 TLS 握手超时 文档；第二步，✗ 行显示失败在 TLS 层、等满了 10 秒超时（不是快速失败）；第三步，最后的 ✓ 是 TCP 建连 118 ms——路一直通到了目标端口，问题精确地卡在握手环节。三条信息合起来还能推出更多：DNS 双栈都正常排除了解析问题；118 ms 的建连耗时说明目标不在近处（可能是跨境链路，这类链路上握手被干扰的概率也更高）；"等满超时"而非"立即断开"把嫌疑从"主动拒绝"移向"数据包被丢弃"。带着这些推论去读文档的排查步骤，你已经能跳过一半不适用的分支。

汇总区（summary）的判读 ​

JSON 报告里的 summary 段做了预统计：各状态的计数、失败中的最高严重程度、以及一句综合结论。两个字段的组合值得注意：fail: 0 且 inconclusive > 0 意味着"没发现问题，但也没能证明没问题"——这时结论会明说证据有限，别把它当成健康证明转发；highestSeverity: critical 目前只出现在证书校验类失败上，看到它优先处理安全维度而不是连通维度。

多份报告的对比阅读 ​

单份报告回答"现在怎么了"，多份报告才能回答"什么变了"。三种最有用的对比：跨网络对比（家宽 vs 热点）——同一目标两份报告并排，差异行直接指认干扰发生的一侧；跨时间对比（故障时 vs 正常时）——保留一份正常时期的基线报告，故障时的耗时膨胀、状态翻转一目了然；修复前后对比——这是闭环的最后一步，"修复后报告全部通过"才是问题解决的证明，而不是"感觉好了"。JSON 格式最适合做这类对比（字段稳定、可用工具 diff），日常习惯是在网络一切正常的日子里对常用目标跑一次检测存档，未来的你会感谢这份基线。对比时优先盯三处：状态翻转的行（✓ 变 ✗）、耗时数量级变化的行、以及证书颁发者是否变化——它们几乎覆盖了所有有意义的差异。

相关阅读 ​