P2P 与分布式存储 / 系统课时
追踪大文件切块和 DAG 组装
追踪大文件切块和 DAG 组装
把一个大文件导入 IPFS 后,得到的根 CID 通常并不直接对应整份文件的原始字节,而是指向组织多个数据块的根节点。本课使用 Kubo 生成可重复的测试文件,观察叶子块、内部节点与根 CID 的关系,并验证修改文件内容后 DAG 如何变化。
学习目标
- 使用 Kubo 导入大文件,并通过命令检查分块数量与根 CID。
- 区分原始数据叶子块、UnixFS 文件节点和 Merkle DAG 链接。
- 验证内容修改对块 CID、内部节点及根 CID 的影响。
准备可重复的大文件实验
实验使用 Kubo 命令行,适用于支持 ipfs add、ipfs refs、ipfs dag get 和 ipfs block stat 的现代 Kubo 版本。先确认已安装并初始化仓库;以下操作不需要连接公网,也不要求后台守护进程持续运行。
ipfs version
ipfs init预期结果:ipfs version 显示本机 Kubo 版本;首次执行 ipfs init 会创建仓库并输出初始化信息。如果仓库已经存在,不要重复初始化,直接继续实验。具体版本号和仓库路径因环境而异。
使用 Python 3 创建一个 2 MiB 文件。文件前半部分和后半部分采用不同字节,方便之后定位修改影响。固定块大小使用 262144 字节,即 256 KiB。
from pathlib import Path
# 使用固定内容保证多次实验可以复现相同的分块边界
half = 1024 * 1024
payload = b'A' * half + b'B' * half
Path('large.bin').write_bytes(payload)
print('size=', len(payload))预期输出:
size= 2097152这个文件大小为 2097152 字节。使用固定 256 KiB 分块时,原始文件数据恰好分成 8 块;但最终 DAG 的节点数量还受到 UnixFS 编码方式、布局策略及链接组织方式影响,不能把文件块数直接当作 DAG 总节点数。
导入文件并观察根 CID
使用固定大小分块器、CIDv1、原始叶子块和 balanced 布局,尽量排除默认参数变化造成的实验差异。--only-hash 只计算 CID,不写入仓库,因此这里不使用。
ipfs add --cid-version=1 --raw-leaves=true --chunker=size-262144 --trickle=false --pin=true -Q large.bin预期结果:终端输出一行以 bafy 开头的 CIDv1 字符串。把这行实际输出记为 ROOT_CID;不同版本或编码参数可能影响具体 CID,不应复制教材中的假定哈希值。
--trickle=false 选择 balanced DAG 布局;--raw-leaves=true 让文件数据叶子块采用 Raw 编码;--pin=true 固定导入内容,避免它在后续垃圾回收时被移除。这里的根节点仍然包含 UnixFS 文件元数据与指向子节点的链接。
下面的命令通过 UnixFS 文件接口读取数据并核对字节数。执行时将 <ROOT_CID> 替换成实际根 CID,不要连同尖括号一起输入。
ipfs cat <ROOT_CID> | wc -c预期输出(在提供 wc 的 Linux、macOS 或类 Unix Shell 中):
2097152Windows PowerShell 用户可以改用 ipfs get <ROOT_CID> -o recovered.bin 下载文件,再通过 Python 的 Path('recovered.bin').stat().st_size 检查文件大小。ipfs cat 输出的是重建后的原始文件字节,不会把内部 UnixFS 节点的编码字节混入结果。
从根节点追踪叶子块与链接
Merkle DAG 中,每个节点的 CID 由其编码后的内容决定。内部节点通过链接引用子节点的 CID,叶子节点则保存文件数据。父节点的链接发生变化时,父节点的编码内容和 CID 也随之变化。

先列出根节点直接引用的子 CID,再递归列出所有可达节点。ipfs refs 默认列出直接引用;-r 会沿 DAG 递归遍历。
ipfs refs <ROOT_CID>
ipfs refs -r <ROOT_CID>预期结果:两条命令分别输出根节点直接引用的 CID,以及递归遍历得到的子节点 CID,每行一个。当前示例的 8 个逻辑分块只有两种不同内容:前四块完全相同,后四块完全相同,因此重复出现的 CID 是正常现象。不能通过输出行数直接判断仓库中有多少个唯一物理块。
进一步查看根节点的结构:
ipfs dag get <ROOT_CID>预期结果:输出根节点的结构化 JSON 表示。对于这里的 UnixFS DAG-PB 根节点,通常可以看到 Data 与 Links 字段。Links 中包含指向子节点的 CID 及相关链接信息,Data 承载编码后的 UnixFS 元数据。二进制字段的 JSON 表示取决于 DAG 编解码器,不要把显示出的编码字符串误认为文件原文。
检查任意一个从 ipfs refs 得到的叶子 CID:
ipfs block stat <LEAF_CID>预期结果:输出该块的 Key 和 Size 信息。对于本实验完整的 Raw 数据叶子块,Size 应为 262144 字节;根节点大小则包含元数据和链接编码,不等于 2 MiB。实际 CID 与输出格式以本机 Kubo 为准。
修改一个字节并比较 DAG
为了验证哈希依赖关系,复制原文件,只修改第一个 256 KiB 分块中的一个字节。其余 7 个分块保持不变,分块大小和布局参数也不改变。
from pathlib import Path
source = bytearray(Path('large.bin').read_bytes())
source[100] = ord('Z') # 只改变第一个分块内部的一个字节
Path('large-modified.bin').write_bytes(source)
print('changed_offset=', 100)
print('size=', len(source))预期输出:
changed_offset= 100
size= 2097152使用与第一次完全相同的导入参数:
ipfs add --cid-version=1 --raw-leaves=true --chunker=size-262144 --trickle=false --pin=true -Q large-modified.bin预期结果:得到一个新的根 CID,记为 NEW_ROOT_CID,它应与原来的 ROOT_CID 不同。接着比较两个根节点的直接链接:
ipfs refs <ROOT_CID>
ipfs refs <NEW_ROOT_CID>预期结果:修改后的第一个 Raw 数据块 CID 发生变化;原来未修改的 A 块及 B 块对应的 CID 保持不变。由于根节点包含子节点链接信息,根 CID 也发生变化。文件名本身不是这里判定 Raw 数据块 CID 的依据。

这个实验采用固定分块边界,所以只改动一个字节不会改变后续块的切分位置。如果在文件开头插入一个字节,固定大小分块的边界可能整体偏移,导致大量后续块 CID 一起变化。换成 Rabin 等内容定义分块策略时,变化传播范围又可能不同。
理解内部节点与 DAG 深度
本实验的 2 MiB 文件只有 8 个逻辑叶子块。在常见的 Kubo balanced UnixFS 布局下,这些叶子可以由一个根文件节点直接引用,因此不一定出现额外的中间文件节点。只有当子节点数量超过布局允许的单层链接容量时,才需要增加内部层级。
为了观察更深的结构,可以使用同一套导入参数测试一个更大的文件,例如 64 MiB。若仍按 256 KiB 切分,会产生 256 个逻辑分块;是否出现中间节点及其具体分组方式,取决于 Kubo 的 balanced 布局实现与分支因子,不应仅凭文件大小猜测。
实际排查时按以下顺序确认:
- 使用
ipfs add记录根 CID 和完整导入参数。 - 使用
ipfs refs检查根节点的直接子链接。 - 使用
ipfs refs -r检查递归可达的节点。 - 使用
ipfs dag get观察文件节点的 UnixFS 元数据和链接。 - 使用
ipfs block stat区分 Raw 叶子块大小与内部节点编码大小。
最终可以用三个事实检查自己的理解:同样的原始数据块在相同编码条件下拥有相同 CID;文件根节点通过链接组织数据块;修改某个数据块会改变该块 CID,并沿着引用路径影响祖先节点,最终得到新的根 CID。