P2P 与分布式存储 / 系统课时
排查节点不可达和下载超时
排查节点不可达和下载超时
当 ipfs routing findprovs 已返回提供者 Peer ID,ipfs get 却一直等待,故障可能出在地址、连接或数据传输。本课用两个 Kubo 节点复现发现成功却下载失败的情况,再逐项定位并验证修复。
学习目标
- 复现“找到提供者但无法下载”,区分提供者记录与实际可用性。
- 按多地址、连接、NAT 和区块交换的顺序定位超时原因。
- 恢复节点后,通过独立接收端验证内容确实可取回。
在两台节点复现故障
准备两台独立主机 A(内容提供者)与 B(下载者),均安装 Kubo 并已运行 ipfs daemon,使用不同的仓库;以下命令在 Bash 中执行,按 Kubo 0.43.1 检查。先确保 B 没有缓存测试内容,且没有其他节点复制它。
在 A 上创建小文件、导入并主动发布提供者记录:
printf 'ipfs-net-probe-20261017\n' > probe.txt
CID_A="$(ipfs add -q probe.txt)"
printf 'CID_A=%s\n' "$CID_A"
ipfs provide once "$CID_A"预期结果:获得 CID_A=<CID_A>;<CID_A> 是本机实际生成的 CID。provide once 在该版本标为实验性,其终端事件可能随版本变化,不以打印内容判断是否发布成功。
在 B 上粘贴真实 CID,查询提供者:
CID='<CID_A>'
ipfs routing findprovs "$CID"预期输出示例(将占位符替换为实际值):
<PEER_ID_A>如果暂时没有结果,检查两端是否在线并重新查询。确认能查到 A 后,在 A 的终端执行:
ipfs shutdown预期结果:A 的守护进程退出。随即在 B 上执行:
ipfs routing findprovs "$CID"
ipfs --timeout=15s get "$CID" -o ./probe-downloaded.txt预期结果:提供者记录在过期前仍可能返回 A,但下载无法从已停机的 A 获取内容,并在限定时间内失败。具体错误文本不固定;如果记录已消失,或 B 已缓存内容,本次就不构成目标故障,需重新准备新文件。能发现提供者不等于提供者仍在线。
先确认提供者记录和节点地址
一次成功下载至少跨过五个关口:发现提供者、获得其可拨号地址、建立 libp2p 连接、请求区块、收到并验证内容。每跨过一关才检查下一关;不要一看到超时就清空仓库。

在 B 上用 A 的真实 Peer ID 检查地址与连接:
PEER_ID_A='<PEER_ID_A>'
ipfs routing findpeer "$PEER_ID_A"
ipfs --timeout=15s id "$PEER_ID_A"
ipfs swarm peers -v预期结果:findpeer 若有返回,展示的是候选多地址而非可达性证明;ipfs id 需实际联通对端才能完成 Identify。A 停机时,后两项通常无法证明已连接 A。若只有 /ip4/192.168.*、/ip4/10.* 或回环地址,公网 B 无法直接拨号;若地址存在但 Identify 失败,继续检查对端在线状态、拨号传输与防火墙。
检查 NAT 和真实入站路径
先在 A 的独立终端恢复 Kubo,保持进程运行:
ipfs daemon预期输出末尾通常包含:
Daemon is ready再从 A 的另一终端检查监听地址、公告地址及自动可达性判断:
ipfs swarm addrs listen
ipfs swarm addrs local
ipfs swarm addrs autonat
ipfs config Addresses.Swarm预期结果:listen 显示本地监听位置,local 显示对外通告的候选地址;在 Kubo 0.43.1 中,autonat 可显示 Public、Private 或 Unknown。0.0.0.0 表示监听所有 IPv4 接口,不表示互联网能连入;Private 也不是每条传输路径都失败的绝对证明。
| 检查现象 | 优先确认的原因与动作 |
|---|---|
| 只有内网或旧公网地址 | 核对 A 的实际公网出口、地址公告和 NAT 映射 |
| 有公网地址但直连超时 | 检查 A 的入站防火墙、路由器转发和运营商 CGNAT |
| TCP 连接失败、QUIC 可用或相反 | 分别检查实际监听的 TCP 与 UDP 端口,不混用协议 |
autonat 为 Private 或 Unknown |
从 B 等外网节点实测拨号,排查打洞、中继和探测条件 |
常见 Swarm 端口为 TCP/4001 与 UDP/4001(QUIC),但以当前 Addresses.Swarm 为准。需要公网入站时,将实际使用的 P2P 端口映射到 A 的内网地址,并按真实映射配置可达的公告地址;运营商 CGNAT 下单改本地路由器往往无效,可考虑公网 IPv6、可靠中继或具备公网入口的节点。不要把 Kubo RPC 的默认 5001 端口当成 P2P 端口公开。
区分连接故障与区块交换停滞
如果 B 的 ipfs id "$PEER_ID_A" 成功,且 ipfs swarm peers -v 能看到 A,再次下载时仍卡住,就在 B 的另一终端观察:
ipfs bitswap stat
ipfs bitswap wantlist预期结果:命令展示区块交换统计以及当前等待的 CID;若请求长时间停在 wantlist,说明当前仍在等待区块,但不能单凭这一项断言 NAT 故障。此时应在 A 执行 ipfs cat "$CID_A" 验证源数据确实可读,并核对 A 是否保留了完整 DAG、两端是否存在区块交换协议或资源限制。连接建立只是传输前提,不代表提供者手上仍有全部需要的块。
恢复服务并完成验收
保持 A 的守护进程运行,在另一终端验证原文件并重新发布:
ipfs cat "$CID_A"
ipfs provide once "$CID_A"预期结果:cat 打印 ipfs-net-probe-20261017,重新发布完成;如果这一步失败,应先修复 A 的本地仓库或 CID,而不是排查 B 的网络。
在 B 上重新下载,并读取文件:
ipfs --timeout=30s get "$CID" -o ./probe-downloaded.txt
cat ./probe-downloaded.txt预期输出(cat 的内容):
ipfs-net-probe-20261017最后确认 B 下载前确实没有该 CID 的本地副本,且 A 的 Peer ID 在 B 的连接信息中可见。这样才能把“路由发现正常”与“经跨节点传输取回正确数据”分别验收。命令详情可查 Kubo CLI 参考,NAT 处理可查 Kubo NAT 配置说明。