P2P 与分布式存储 / 系统课时
追踪 Bitswap 请求与区块返回
追踪 Bitswap 请求与区块返回
当 IPFS 节点已经找到内容提供者,却仍然无法读取文件时,需要继续检查实际的数据交换过程。本课使用两个 Kubo 节点构建远端读取实验,观察 Bitswap 的 Wantlist、请求计数和区块接收结果,并区分内容发现、区块传输与文件重建三个阶段。
学习目标
- 解释 Bitswap 如何通过 Wantlist 请求内容块,以及区块返回后如何完成验证与存储。
- 使用两个 Kubo 节点复现远端文件读取,检查请求前后的 Bitswap 状态。
- 根据连接、Wantlist、计数器和读取结果定位常见区块交换故障。
Bitswap 在内容获取链路中的位置
IPFS 使用 CID 标识内容块。对于通过 UnixFS 导入的文件,一个文件 CID 可能对应单个数据块,也可能指向由多个块组成的 DAG(有向无环图)。客户端必须取得足够的相关块,才能重建完整文件。
Bitswap 是 IPFS 使用的区块交换协议之一。它通过 libp2p 连接在节点之间交换请求与数据,主要涉及以下概念:
- Wantlist:节点希望获取的 CID 集合,协议请求还包含优先级和请求类型等信息。
- Block:实际传输的内容块,其内容必须与预期 CID 对应。
- Have / DontHave:支持相应协议扩展的节点可以报告是否持有某个块,而不立即发送块内容。
- Blockstore:本地内容块存储。成功接收并验证的块可被写入其中,供后续读取使用。
一个典型的远端读取过程是:节点 B 获得文件 CID,确定候选提供者,向节点 A 请求根块,读取块中的链接后继续请求缺失的子块,最后由 UnixFS 层重建文件。

需要注意,Bitswap 不负责把文件名解析成 CID,也不保证所有远端读取都必须经过它。Kubo 还可能使用其他受支持的块获取方式。下面的实验通过 Bitswap 统计和本地块状态判断是否实际发生了相应交换,而不是仅凭 ipfs cat 成功就断言使用了 Bitswap。
准备两个隔离的 Kubo 节点
实验环境为支持 ipfs bitswap、ipfs block 和 ipfs swarm 命令的 Kubo 版本,建议使用 Kubo 0.30.x 或具备相同命令的较新版本。以下以 Linux 或 macOS 的 Bash 为例,要求已安装 ipfs 命令,并使用两个终端分别运行节点 A、B。
为了避免两个节点共用仓库和端口,分别设置 IPFS_PATH,并使用 --profile=server 初始化测试仓库。该 Profile 会调整默认配置,但不会自动关闭所有网络发现机制。
mkdir -p /tmp/ipfs-bitswap-lab/a /tmp/ipfs-bitswap-lab/b
export IPFS_PATH=/tmp/ipfs-bitswap-lab/a
ipfs init --profile=server
ipfs config Addresses.API /ip4/127.0.0.1/tcp/5001
ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8080
ipfs config --json Addresses.Swarm '["/ip4/127.0.0.1/tcp/4101"]'
ipfs daemon --offline预期结果:终端 A 完成初始化并显示类似以下状态;启动输出可能包含其他提示。
Daemon is ready终端 B 使用独立仓库和端口:
export IPFS_PATH=/tmp/ipfs-bitswap-lab/b
ipfs init --profile=server
ipfs config Addresses.API /ip4/127.0.0.1/tcp/5002
ipfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8081
ipfs config --json Addresses.Swarm '["/ip4/127.0.0.1/tcp/4102"]'
ipfs daemon --offline预期结果:终端 B 同样进入守护进程就绪状态。
Daemon is ready这里使用 --offline 是为了排除公共 DHT、引导节点及其他外部网络连接的干扰。两个节点仍可通过显式的本地地址建立连接。后续操作需要另外打开终端执行 CLI 命令,不能关闭正在运行的两个 daemon。
发布文件并建立节点连接
在新的终端中,先准备一个大于单块大小的测试文件,以便观察根块和数据块的多次请求。下面生成约 1 MiB 的确定性测试内容,随后在节点 A 导入并获取 CID。
export IPFS_PATH=/tmp/ipfs-bitswap-lab/a
python3 -c 'from pathlib import Path; Path("/tmp/ipfs-bitswap-lab/sample.bin").write_bytes(bytes(range(256)) * 4096)'
ipfs add --cid-version=1 --chunker=size-262144 --raw-leaves=true /tmp/ipfs-bitswap-lab/sample.bin
ipfs id -f='<id>\n'预期结果:第一条 IPFS 命令返回文件 CID,第二条返回节点 A 的 Peer ID,具体值随环境变化。
added <CID> sample.bin
<ID>这里的 <CID> 和 <ID> 分别表示实际返回的内容标识与 Peer ID,不是要原样输入的字符串。文件内容、分块器、UnixFS 布局和 CID 版本共同决定最终 CID。
在节点 B 的 CLI 终端中连接节点 A。将命令中的 <ID> 替换为节点 A 实际的 Peer ID。
export IPFS_PATH=/tmp/ipfs-bitswap-lab/b
ipfs swarm connect /ip4/127.0.0.1/tcp/4101/p2p/<ID>
ipfs swarm peers预期结果:连接命令报告成功,Peer 列表包含节点 A 的地址及 Peer ID。
connect <ID> success
/ip4/127.0.0.1/tcp/4101/p2p/<ID>swarm peers 的实际输出还可能包含连接方向等信息。连接成功只证明 libp2p 传输路径可用,并不能证明目标块存在,也不能证明 Bitswap 已经发出请求。
观察 Wantlist 与区块接收
在节点 B 上,先记录请求前的 Bitswap 状态,并检查目标根块是否已在本地。以下命令中的 <CID> 必须替换为节点 A 导入时得到的真实 CID。
export IPFS_PATH=/tmp/ipfs-bitswap-lab/b
ipfs bitswap wantlist
ipfs bitswap stat
ipfs block stat <CID>预期结果:在全新仓库中,Wantlist 通常为空;统计信息包含区块接收、发送等计数。由于 B 尚未获取目标根块,block stat 应返回找不到对应块的错误,而不是块大小。
接着启动远端读取。为了更容易捕捉短暂的 Wantlist,使用 Bash 后台任务执行读取,同时连续采样状态。
export IPFS_PATH=/tmp/ipfs-bitswap-lab/b
ipfs cat <CID> > /tmp/ipfs-bitswap-lab/received.bin &
CAT_PID=$!
for i in 1 2 3 4 5; do
ipfs bitswap wantlist
sleep 0.2
done
wait "$CAT_PID"
ipfs bitswap stat
ipfs block stat <CID>预期结果:如果远端块成功获取,ipfs cat 正常退出,received.bin 包含完整文件内容;block stat 返回根块 CID 和大小。若使用 Bitswap 完成传输,相关接收计数应相对于基线增加。
Key: <CID>
Size: <SIZE><SIZE> 是根块的实际字节数,不等于整个 UnixFS 文件的长度。ipfs bitswap stat 的字段及显示格式可能随 Kubo 版本不同,应该对比同一版本请求前后的数值,而不是依赖固定示例值。
Wantlist 是瞬时状态:如果块在两次采样之间已返回,请求条目就可能已经消失。因此,Wantlist 为空不代表没有发生过请求。对于本地双节点和约 1 MiB 的小文件,传输通常很快,采样不到条目属于正常现象。
还可以在节点 A 的 CLI 终端执行 ipfs bitswap stat,检查发送相关计数是否变化。若两端统计均没有预期变化,应结合版本支持的实际块获取协议判断,不能把所有读取都归因于 Bitswap。
验证文件重建和块完整性
Bitswap 交换的是内容块,而 ipfs cat 输出的是 UnixFS 重建后的文件字节。两者不能混为一谈:一个约 1 MiB 的文件可以由多个叶子块和一个根节点组成,根块的 block stat 大小可能只有数百字节。
在节点 B 上对比原文件和接收文件的 SHA-256 摘要:
sha256sum /tmp/ipfs-bitswap-lab/sample.bin /tmp/ipfs-bitswap-lab/received.bin
cmp /tmp/ipfs-bitswap-lab/sample.bin /tmp/ipfs-bitswap-lab/received.bin预期结果:两行 SHA-256 摘要相同,cmp 不输出内容且退出状态为 0。
<HASH> /tmp/ipfs-bitswap-lab/sample.bin
<HASH> /tmp/ipfs-bitswap-lab/received.bin<HASH> 是实际计算得到的 64 位十六进制摘要,两行必须一致。此处原文件位于共享文件系统,仅用于结果对比;节点 B 的 IPFS 仓库仍与节点 A 独立。
成功接收的块会按 CID 进行内容验证。如果网络传来的字节与预期 CID 不匹配,节点不能把它当成有效的目标块。需要区分两层检查:CID 验证针对内容块,cmp 则检查最终重建文件是否与实验源文件逐字节一致。
按证据定位区块交换失败
当 ipfs cat 长时间等待或最终失败时,按照下面的顺序检查,比反复重试更容易找到原因。
| 观察现象 | 可能原因 | 检查与修正 |
|---|---|---|
swarm peers 没有 A |
连接失败或地址错误 | 重新检查 Peer ID、4101 监听端口和 swarm connect 结果 |
| 已连接但读取超时 | 没有可用提供者或目标 CID 错误 | 在 A 执行 ipfs block stat <CID>,确认根块存在 |
| Wantlist 一直存在 | 请求未满足或对端未返回数据 | 对比 B 的接收计数与 A 的发送计数,检查对端是否持有块 |
| Wantlist 为空但读取成功 | 请求已完成或使用了其他块获取路径 | 检查本地块状态和统计增量,不直接判定为故障 |
| 根块已获取但文件读取失败 | 某个子块缺失或无法获取 | 检查 DAG 链接及后续缺失块,不能只验证根 CID |
对于根块存在但文件仍无法完整读取的情况,可以在节点 A 执行:
export IPFS_PATH=/tmp/ipfs-bitswap-lab/a
ipfs dag stat <CID>
ipfs refs <CID>预期结果:在支持这些命令的 Kubo 版本中,dag stat 返回 DAG 统计信息,refs 列出从根节点可遍历到的链接 CID;如果对应数据不存在或 DAG 不完整,命令可能报错。
实验完成后,可在两个 daemon 终端按 Ctrl+C 正常停止节点。只有确认测试数据不再需要时,才删除 /tmp/ipfs-bitswap-lab。
最终应同时取得三类证据:节点间连接存在、目标内容块由远端进入本地、重建文件与原文件一致。这样才能把网络发现成功、Bitswap 区块交换成功和 UnixFS 文件读取成功区分开来。