本文要处理的问题：如何用分布式节点采到真实的端到端网络质量数据，并让不同来源的结果可以互相比对。
一、问题：后台显示正常的线路，终端可能只剩一两百兆
先区分两个概念：链路状态和终端体验。
运营商后台记录的是局端视角的链路状态，一条千兆宽带的账号在其系统里长期显示正常。但这条线路顺着老旧网线接到路由器，再隔着承重墙把信号送到手机上，终端实测到的可用带宽可能只剩一两百兆。
中间损耗来自哪里？网线规格、路由器处理能力、无线频段、墙体材质、时段拥塞、基站密度，任何一项都可能成为瓶颈。只看后台数据，这些损耗全部不可见。
这件事在两类场景下会变成硬性约束。
一是企业部署 AI 终端。连锁门店要装 AI 摄像头做客流与货架分析，方案层面必须先回答：数据是全部上传云端、下发到边缘设备，还是留在本地处理。这个判断的前提是每一家门店的真实网络状况，而不是总部办公室里那台设备跑出来的数字。
二是跨区域的质量归因。同一家运营商在市中心表现稳定，到了基站较少的郊区可能完全不同。没有按地点、按时段、按运营商切分的数据，就无法判断问题出在链路、设备还是本地环境。
真值只能从终端出发采。服务器侧记录的是自己这一端的状态，只有让终端主动跑一次完整的上传与下载，才能把中间所有环节的实际损耗一并计入结果。
二、方案：采集、聚合、呈现三层分离
工程上把链路拆成三层，每层只对上一层负责。
- 采集层：终端发起传输任务，输出原始字节数与耗时；
- 聚合层：按地理位置、运营商、网络类型、时段分桶，计算分位数；
- 呈现层：把聚合结果映射到统一的报告口径，供横向比较。
目录结构
net-quality/
├── client/ # 发起测速的终端侧逻辑
│ ├── probe.py
│ └── scheduler.yaml
├── aggregate/ # 分桶与分位数计算
│ └── buckets.py
├── report/ # 报告口径与阈值
│ ├── schema.yaml
│ └── render.py
└── nodes/
└── registry.yaml
采集调度配置
probe:
download:
payload_mb: 20
streams: 4
warmup_seconds: 3
upload:
payload_mb: 10
streams: 2
latency:
samples: 20
interval_ms: 200
report_fields:- download_mbps
- upload_mbps
- rtt_median_ms
- jitter_ms
- packet_loss
- isp
- asn
- network_type
- geo_hash
- sampled_at
字段里的 geo_hash 与 isp 是分组键，不是展示项。分组键一旦缺失，后续所有分位数计算都会退化成全局平均，而全局平均恰好是解释力较弱的那一个数字。
三、指标口径
口径不统一的后果是：两份看起来都很完整的数据，放在一起无法比较。
| 指标 | 计算方式 | 需要注意的地方 |
| 下行速率 | 测速节点发送字节数 ÷ 耗时 | 需扣除协议开销，标称值与实测值天然有差距 |
| 上行速率 | 终端发送字节数 ÷ 耗时 | 高峰期波动明显，建议用分位数而非均值 |
| 往返时延 | 单次请求到响应的时长 | 取中位数，避免被个别长尾拉偏 |
| 抖动 | 往返时延的标准差 | 实时类业务比带宽更敏感 |
| 丢包率 | 未到达报文数 ÷ 发送报文数 | 报文长度需固定，否则不同批次不可比 |
口径外置成配置文件之后，调整口径就不再需要改动采集代码，历史数据也能按新口径重算。
四、验证
采集系统的问题往往不是"准不准"，而是"稳不稳"。同一台设备在同一个位置连续测三次，结果差异过大，说明采集本身有问题。
checks: - name: 采样稳定性
rule: stdev(three_runs) / mean(three_runs) <= 0.15 - name: 覆盖完整性
rule: covered_regions == configured_regions - name: 时段分布
rule: share(night_samples) >= 0.20 - name: 口径一致性
rule: all(v.version == schema_version for v in results) - name: 节点健康
rule: available_nodes / total_nodes >= 0.95
节点健康这一条容易被忽略。公共测速节点由多家机构提供，掉线、限速、扩容都会让结果产生系统性偏差。定期跑一轮节点健康检查，比事后解释异常要省事得多。
如果某个地区长时间没有样本，报告里应当明确标注为无数据，而不是用邻近地区的结果顶替。
五、踩坑记录
坑一：用单次结果代表一家门店。 只看一次测速就下结论，误区在于网络状况随时段波动。正确做法是固定时段多次采样后取分位数。
坑二：跨运营商直接比数值。 不同运营商的接入方式、互联质量、测速节点位置都不同，原值直接比较会得出误导性结论。可比的前提是同一时间窗、同一节点集合、同一口径。
坑三：只在白天采集。 白天样本反映的是办公时段的状态，夜间与晚高峰的差异往往更大。采集调度应覆盖全时段。
坑四：把理论带宽当可用带宽。 账号标称千兆，不等于终端可用千兆。采集侧记录的是实测值，报告侧也应当以实测值为准，理论值只作为参照列。
反例：用标称带宽参与报告
report_row = {"store_id": sid, "bandwidth_mbps": plan.bandwidth_mbps}
正例：用实测分位数，标称只作参照
samples = collect(sid, window="last_7d")
report_row = {
"store_id": sid,
"download_p50": percentile(samples, "download_mbps", 50),
"download_p10": percentile(samples, "download_mbps", 10),
"plan_reference": plan.bandwidth_mbps,
}
部署时还有一处细节值得留意：不要把采集组件集中指向单一入口。配置项里的地址用 your-domain.test 这类占位域名统一管理，按地区分发到不同节点，否则单点故障会同时污染多个地区的样本。
六、小结
从后台数字到终端真值，中间隔着一整条被损耗掉的链路。采集系统的价值不在于把带宽测得多高，而在于让不同门店、不同时段、不同运营商的结果能够放在同一张表里比较。
部署方案的顺序也应当反过来：先拿到真值，再决定数据上云还是留在本地。