bitswap/stat如何排查取块异常？

用户说“IPFS打不开”时，问题可能在网关HTTP、DNS、节点连接、内容路由、Bitswap供应、本地磁盘或原始内容根本不存在。bitswap/stat适合观察交换层，但必须先把累计计数器转成可比较的时间窗口。

九组字段先按用途归档

Kubo /api/v0/bitswap/stat返回BlocksReceived、BlocksSent、DataReceived、DataSent、DupBlksReceived、DupDataReceived、MessagesReceived、Peers和Wantlist等字段。

BlocksReceived与DataReceived描述接收块数和字节，BlocksSent与DataSent描述对外发送；DupBlksReceived与DupDataReceived记录重复接收；MessagesReceived反映协议消息；Peers与Wantlist展示当前交换关系和待请求对象。字段名称相近，单位却不同，图表必须明确块、字节、消息和列表项。

单看DataReceived很大，可能只是节点运行很久；单看DupDataReceived高，也无法判断问题发生在当前时段。监控首次采集时只建立基线，不应立即触发速率告警。

双快照把累计值变成速率

这些数字主要是累计计数器，要通过两次采样做差才能估算时间窗口内速率。

在T0和T1分别记录同一节点的stats，以时间差计算接收字节每秒、发送字节每秒、消息速率和重复数据比例。若节点在窗口内重启，累计值可能回落，应丢弃该差值并重新建立基线。

现象	增量特征	下一步
完全无交换	收发与消息差值接近零	查peer、网络与是否有请求
请求堆积	wantlist增长、接收不动	查供应者和内容路由
重复偏高	DupData增量占比上升	查多路径、重试与连接质量
能收不能发	接收增长、发送停滞	查是否有外部请求和服务策略

重复比例只在有足够流量的窗口才有意义。分母很小时，一个重复块就会产生夸张百分比，应设置最小样本量。

wantlist不下降要问三个问题

Bitswap用wantlist表达节点想要的块；wantlist持续不降需再查peer连接、供应者与具体CID。

第一，节点是否拥有可工作的Bitswap peer；第二，网络中是否能找到该CID的提供者；第三，提供者是否真的持有并愿意发送所需块。wantlist存在只证明本地还想要数据，不证明远端一定可用，也不说明完整DAG的每个子块都有来源。

选择一个本节点已缓存的CID验证本地读取，再选择一个已知公开且当前可达的CID验证网络获取，最后重试问题CID。三组结果可帮助区分本地存储、整体网络和特定内容供应。测试时记录CID、开始时间、超时、节点版本和peer变化。

重复数据不是天然攻击信号

多peer并行请求、超时重试、网络抖动和块到达竞态都可能产生重复。只有重复比例持续升高并伴随有效吞吐下降、wantlist堆积或资源消耗异常，才值得深入调查。不要因为一次重复尖峰就封禁大量peer，否则可能进一步降低可用性。

若怀疑特定连接，比较其协议、方向和数据贡献，逐步隔离而非批量断开。节点自身CPU或磁盘拥塞也会让已到达数据处理变慢，必须联看系统指标。

管理RPC不能暴露给公网

Kubo RPC是管理级接口，官方要求默认仅绑定localhost，绝不能直接暴露在公开互联网。

Kubo RPC可以执行远超只读统计的管理操作。诊断脚本应在localhost、SSH隧道或严格受控管理网运行，使用独立权限与日志脱敏。反向代理加一个猜得到的路径，不构成充分保护。

抓取统计时设置超时和频率限制，不让监控反过来压垮节点。任何面向用户的公共状态页只展示聚合指标，不返回peer地址、管理端点或内部路径。

一张取块故障记录应包含什么

保存T0/T1原始stats、差值、节点启动时间、Kubo版本、peer数、wantlist摘要、测试CID结果、系统CPU与磁盘、网关HTTP状态和采取的动作。恢复后再观察一个完整窗口，确认有效接收恢复且wantlist下降，而不是仅看到一次请求成功就结案。

指标只负责缩小范围，CID实测才闭环

bitswap/stat能告诉你节点正在交换什么样的流量，却不能保证某个CID一定有供应者。把增量指标、peer连接、wantlist和具体取块结果放在同一时间轴，诊断才完整。