ConnProof 快速开始：安装、运行和阅读诊断结果

ConnProof 是一个在你自己电脑上运行的连接诊断工具。它不需要注册账号、不连接任何云端服务、不上传任何数据——安装完成后，你与它的全部交互都发生在本地终端里。这篇指南带你走完从安装到读懂第一份报告的完整流程，全程大约十分钟。

运行环境要求

• Node.js 20 或更新的 LTS 版本。在终端运行 node --version 确认；没有安装的话，从 Node.js 官网下载对应平台的 LTS 安装包；
• pnpm 9 或更新版本（从源码安装时需要）。可用 corepack enable 激活 Node 自带的包管理器支持；
• Windows 10/11、macOS 12+、主流 Linux 发行版均可运行。

安装

当前版本从源码安装。克隆或下载本项目仓库后，在项目根目录执行：

pnpm install

pnpm build:packages

pnpm build:cli

构建完成后验证安装：

node apps/cli/dist/index.js --version

看到 connproof 0.1.0 即安装成功。想在任意目录直接使用 connproof 命令，可在 apps/cli 目录下执行 npm link（或把上面的完整路径做成 shell 别名）。下文示例统一使用 connproof 简写。

第一次诊断

挑一个你想检查的域名——比如某个连不上的服务的主机名——运行：

connproof diagnose example.com

ConnProof 会按 DNS → TCP → TLS 的顺序逐层检测，每层都基于真实的网络操作：真的去解析记录、真的建立 TCP 连接、真的完成 TLS 握手。大约几秒后你会得到一份报告，它包含五个部分：

1. 目标：本次检测的对象与端口；
2. 结论：一句话说明检测发现了什么（或没发现问题）；
3. 诊断代码：当检测命中某条已知故障模式时给出，例如 TLS-002。这是整份报告最有用的一行——它是稳定的、可搜索的、与文档一一对应的；
4. 检测证据：每一层的具体观察记录，带耗时。✓ 表示通过，✗ 表示失败，! 表示需要关注，○ 表示跳过或无法执行；
5. 可能原因与建议操作：按概率排序的原因列表和可执行的下一步。

理解六种检测状态

ConnProof 的每项检测都会以六种状态之一结束，理解它们是读懂报告的关键：

状态	含义
pass	检测执行了，结果正常
fail	检测执行了，确认存在问题
warning	执行了，发现需要关注但不必然致命的情况
skipped	因前置层失败或用户参数而未执行
unsupported	当前平台/环境不支持这项检测
inconclusive	执行了，但证据不足以下结论

后三种状态是 ConnProof 的诚实边界：工具不会把"没测"或"测不了"包装成"正常"。前一层失败时，后面的层会明确标为 skipped 而不是凭空显示结果——报告里的每一个结论都对应真实发生过的检测。

常用命令速览

按需使用单项检测，比完整诊断更快、证据更聚焦：

connproof dns example.com

connproof tcp example.com --port 443

connproof tls example.com --port 443

connproof websocket wss://example.com/path

connproof subscription "https://example.com/subscription"

connproof doctor

doctor 值得单独一提：它不检测远程目标，而是体检你的本机环境——Node 版本、系统时间信息、DNS 配置、常见本地代理端口的监听状态、系统代理指向、写入权限、网络接口与默认路由摘要。遇到"什么都连不上"的情况时，先跑 doctor 往往能直接定位到本地原因。

每个命令都支持 --help 查看专属参数：

connproof tls --help

按症状选命令

不确定从哪条命令开始时，按你遇到的症状对号入座：

症状	第一条命令	理由
某个网站/服务连不上	connproof diagnose 该域名	逐层定位，覆盖面最全
什么都连不上	connproof doctor	全局故障多在本机环境
客户端提示订阅更新失败	connproof subscription "订阅地址"	直击订阅链路
报错里有 TLS / 证书字样	connproof tls 域名 --port 443	聚焦握手与证书证据
报错里有 WebSocket / ws 字样	connproof websocket wss://地址	真实升级握手取证
想确认某端口是否可达	connproof tcp 域名 --port 端口	最轻量的单点检测

诊断的一个通用心法：从范围最大的怀疑开始收缩。先用 doctor 排除本机，再用 diagnose 定位层级，最后用单项命令聚焦取证——三步下来，问题通常已经缩小到一篇具体的错误文档能覆盖的范围。

安装常见问题

• pnpm: command not found：先运行 corepack enable（需要 Node 16.13+），或按 pnpm 官网指引独立安装；
• pnpm install 在公司网络下卡住：pnpm 需要访问 npm 仓库，受限网络下配置公司镜像源（pnpm config set registry <镜像地址>）；
• 构建报 Node 版本错误：项目要求 Node 20+，用 node --version 核实，多版本共存时注意终端实际使用的是哪一个；
• Windows 上执行报安全策略错误：PowerShell 的执行策略可能拦截 npm 链接的脚本，改用 node apps/cli/dist/index.js 直接调用可以绕开这一层。

通用选项

选项	作用
--timeout <毫秒>	调整检测超时（默认 10 秒）
--ipv4 / --ipv6	强制使用某个地址族
--format text|json|markdown	输出格式
--output <文件>	把报告写入文件
--verbose	显示检测步骤
--no-color	关闭彩色输出

--format json 输出结构稳定的机器可读报告，适合接入客服系统或自动化脚本；--format markdown 适合贴进工单和 Issue。最近一次诊断的报告会保存在本机（~/.connproof/last-report.json，已脱敏），随时可以用 connproof report --format markdown 重新导出，不必重跑检测。

隐私默认值

所有报告在生成时自动经过脱敏：订阅地址的查询参数、Token、Cookie、用户目录、邮箱会被移除或替换，公网与私网 IP 部分遮盖（回环地址保留，便于排查本地代理）。这意味着默认导出的报告可以比较放心地发给客服——当然，发送前自己再过目一遍永远是好习惯。详细规则见报告脱敏说明。

工具不会做的事

最后明确几条边界，避免带着错误预期使用：ConnProof 不会修改任何系统设置——它只读取和检测，修复动作永远由你自己执行，工具的职责是让你知道该改什么、改完怎么验证；不会扫描网络——它只检测你明确输入的那一个目标，加上一个固定的常见本地代理端口清单（仅限本机回环地址），没有任何网段或端口范围扫描能力；不会上传数据——检测流量之外，它不与任何服务器通信，报告只存在于你的本机；不会转换订阅——对订阅地址只做可达性与响应类型判断，内容不解析、不存储。如果你需要的是这些功能，ConnProof 不是合适的工具；如果你需要的是"搞清楚连接为什么失败"，它正是为此而生。

下一步

• 拿到错误码后，在本站错误库找到对应文档，按步骤排查；
• 想了解检测背后的原理，读ConnProof 如何从网络检测生成证据链；
• 需要向客服反馈问题，先看应该提供哪些脱敏信息；
• 修复之后，重新运行同一条命令——看到全部 pass 才算真正闭环。

最后一个建议：在网络一切正常的时候，也花一分钟对你最依赖的一两个服务跑一次 diagnose 并保存报告。这份"健康基线"在未来某天出问题时会成为最有价值的对照材料——正常时的耗时是多少、证书是谁签的、走的是 IPv4 还是 IPv6，全都有据可查。诊断工具最好的使用时机，其实是在你还不需要它的时候。