网络诊断（未发布源码）

发布状态

本页描述主项目 2026-10-14 完成的源码能力。JS SDK 0.4.0 与 Flutter 0.2.1 尚未完成 registry 发布，Collector/Dashboard 和业务 App 也未因此自动升级。先使用审核过的源码版本测试，再按实际发布状态接入。

JS SDK 接入

Web 使用 createHealthGuardClient，小程序使用 createMiniProgramClient，uni-app 使用 createUniAppClient，统一新增可选 networkDiagnostics：

import { createHealthGuardClient } from '@health-guard/sdk-web';
const client = createHealthGuardClient({
  appKey: 'your-app-key',
  endpoint: 'https://collector.example.com/api/events/batch',
  release: 'your-app-version',
  environment: 'production',
  autoCapture: true,
  networkDiagnostics: true
});

使用包含本次实现的源码 SDK 或在正式发布后安装对应版本。无需把分类、补传和平台诊断逻辑复制到业务项目。高级配置为 networkDiagnostics: { cooldownMs: 30000, maxPendingEvents: 100, storage }；storage 是同步 getItem/setItem 适配器。默认使用平台存储，不可用时退回内存。初始化只执行一次，生命周期结束调用 dispose()。

诊断证据

• category：offline / dns / connect / tls / timeout / cancelled / http / unknown，来自本次请求和设备线索，不等于确认根因。
• network：允许的在线状态、网络类型、effectiveType、系统 validated/metered/VPN 信息；各端能力不同，缺失字段不伪造。
• targetOrigin：只保留协议、域名和端口，不包含路径、凭据、查询或片段。
• timing：可读取的 DNS、连接、TTFB 毫秒值；不可读时为 unavailable，不能用 0 表示缺失。H5 跨域阶段依赖响应的 Timing-Allow-Origin，也不能复用前一次同 URL 请求的耗时。
• recentChanges：近两分钟最多五条平台网络状态通知，不包含网络标识。

JS 端为被动采集；Flutter 0.2.0 可显式启用受域名白名单约束的 DNS/TCP/TLS/健康探测，默认关闭，不允许任意地址探测。普通浏览器 Failed to fetch 不能区分 DNS、TLS、CORS 和服务端不可达。设备在线也不能证明业务服务可达。

隐私与补传

默认每目标域 30 秒附加一次详细诊断，最多缓存 20 个域；限频不会丢掉 HTTP 失败事件。JS 和 Flutter 队列最多 100 条，超限移除最旧项，失败沿用原事件 ID、发生时间和版本补传。Collector 对同一事件 ID 幂等接收。

新增诊断和 HTTP 补传不采集请求头/请求体、SSID/BSSID、IP 或运营商身份；落盘请求 URL 去掉用户信息、全部查询和片段。原有手动上下文/请求数据仍需遵守业务隐私边界。默认上传在诊断开启时要求 accepted 等于本批事件数，200 HTML 不能算接收确认；自定义 transport 必须在真正确认后才 resolve。

迁移与验收

先更新并验收 Collector/Dashboard，再发布 SDK，再升级并重新发布业务客户端。旧 App 和历史事件不会自动补齐网络字段。移除重复业务上报时逐项核对原有已处理异常和业务配置。实际断网、重启补传、切网、VPN 和真实邮件告警需要独立验收。

完整说明与检查命令见 主仓库网络诊断指南；Flutter 见 接入说明。

Flutter SDK 的详细诊断与迁移配置见 Flutter 接入。

单次事件与历史摘要

新 HTTP 指纹使用 origin、方法、路径、环境、平台、状态和原始故障阶段。历史 Issue/事件保持原 ID、指纹和修复记录，不自动拆分历史混合问题；新分组可能与旧分组并存。邮件中的「本次异常」对应触发事件，「历史聚合摘要」仅供参考。延迟补报及启动回填按事件时间维护最近摘要和版本。

Flutter 0.2.1 可选择 IO adapter 记录原请求连接取得与响应头等待；参见 Flutter SDK。原请求子阶段未测量时保留不可用。日志没有该 HTTP 请求与客户端建立连接超时可以同时成立，应按 X-Request-ID 关联；要进一步区分 DNS/TCP/TLS 或设备故障，仍需原连接跟踪或现场抓包。