P2P 与分布式存储 / 系统课时

沿 DAG 链接验证数据完整性

沿 DAG 链接验证数据完整性

拿到 IPFS 文件的根 CID,并不代表所有文件内容已经保存在本地。本课使用 Kubo 创建一个跨越多个数据块的文件,从根节点追踪子块引用,验证每个块的内容完整性,并通过缺失块实验区分内容损坏、数据不可用与引用不完整三种情况。

学习目标

  • 理解根 CID、DAG-PB 节点、UnixFS 文件数据与子块 CID 之间的关系。
  • 使用 Kubo 命令检查 DAG 链接并验证原始块的内容哈希。
  • 通过离线缺块实验判断文件无法恢复的原因及处理方法。

根 CID 如何约束整张数据图

IPFS 的 Merkle DAG 是一种以内容标识符连接节点的有向无环图。每个块的 CID 包含内容编解码类型与多哈希信息,父节点保存子节点的 CID,因此子块内容改变后,父节点中记录的引用也必须相应改变。

以 Kubo 常见的 UnixFS 文件布局为例,大文件可以由一个 DAG-PB 根节点和多个叶子数据块组成。根节点包含文件布局信息及子块链接,叶子块保存文件内容。具体结构取决于导入参数、分块策略与 UnixFS 编码方式,不能假定每个文件都有相同的树高。

Merkle DAG 父子链接与内容完整性验证关系

这里需要区分两层校验:第一层是获取某个块后,按照 CID 指定的哈希算法计算其内容摘要并比较;第二层是按照已验证的父节点链接继续获取子块,直到收集到恢复文件所需的全部数据。

例如根节点 R 引用 A、B、C,验证 R 成功只说明 R 的原始块字节符合 R 的 CID,并不能证明 A、B、C 已经下载。只有这些子块都可获取且校验通过,文件内容才具备完整恢复的条件。

创建可追踪的多块文件

以下实验适用于安装并初始化了 Kubo 的环境,使用支持 ipfs add、ipfs dag、ipfs block 和 ipfs refs 的常见 Kubo 版本。先启动本地守护进程,并确保命令行能够连接本地 API。实验使用 CIDv1、固定大小分块与默认的平衡布局,以便观察 DAG 链接。

在 Linux、macOS 或具有 Python 3 的 Bash 环境中执行:

bash
# 在另一个终端保持 ipfs daemon 运行
ipfs daemon

预期结果:终端最终出现类似以下就绪提示,其他启动日志及地址因环境而异。

text
Daemon is ready

另开终端执行:

bash
# 创建约1 MiB的确定性测试内容,避免依赖外部下载
python3 -c 'from pathlib import Path; Path("dag-test.bin").write_bytes(bytes(range(256)) * 4096)'

# 固定分块大小与布局,关闭进度输出便于记录CID
ipfs add --cid-version=1 --chunker=size-262144 --trickle=false --progress=false dag-test.bin

预期输出的格式如下,CID 由实际导入结果决定,不应复制示意值作为真实 CID:

text
added <CID> dag-test.bin

文件大小为 1,048,576 字节,即 1 MiB;按 262,144 字节分块,文件数据可划分为四个完整数据块。默认 UnixFS 导入器可能在叶子块之外创建用于链接的 DAG-PB 节点,因此 DAG 块总数不一定等于四。

将输出中的实际 CID 记录为根 CID。以下命令中的 <CID> 均表示替换为该真实值,尖括号不是命令参数的一部分。

从根节点逐层检查链接

首先读取根节点的 DAG 表示,确认其编解码类型及子块引用。ipfs dag get 输出解码后的结构,而 ipfs block get 取得用于哈希验证的原始块字节,两者用途不同。

bash
# 用实际根CID替换占位符
ipfs dag get <CID>
ipfs refs -r <CID>

预期结果:第一条命令返回根节点的 JSON 表示;对于本实验的 DAG-PB 根节点,可观察到 Data 和 Links 等字段。第二条命令逐行输出递归遍历得到的子块 CID,具体数量和顺序取决于实际 DAG 布局。

ipfs refs -r 用于列出可遍历的后代引用,不代表所有内容都已通过独立的端到端文件校验。若只希望查看直接子节点,可使用 ipfs refs <CID>,并将其输出与根节点中的链接对应起来。

从根CID递归读取并验证子块的执行流程

需要注意,DAG-PB 节点中的 Data 是经过编码的 UnixFS 数据,不应直接将其当成整个文件的原始字节。UnixFS 读取器会依据文件布局、链接及块内容完成重组。

独立验证块哈希与文件恢复

Kubo 的 ipfs block stat 可以检查块是否可获取以及原始块大小,但不能单独作为内容完整性测试的全部证据。为了独立验证 CID,应该获取原始块字节并使用与 CID 一致的哈希算法。

下面使用 Python 3 标准库和 Kubo CLI,对实验根 CID 执行独立 SHA-256 检查。由于实验生成的是 CIDv1,且使用默认 SHA2-256 多哈希,脚本会解析 CIDv1 的二进制表示并验证多哈希字段;不适用于任意其他哈希算法的 CID。

python
import base64
import hashlib
import subprocess
import sys


def read_varint(data, pos):
    value = 0
    shift = 0
    while True:
        if pos >= len(data):
            raise ValueError("不完整的varint")
        byte = data[pos]
        pos += 1
        value |= (byte & 0x7F) << shift
        if byte < 128:
            return value, pos
        shift += 7
        if shift > 63:
            raise ValueError("varint过长")


def verify(cid):
    # 本实验使用CIDv1的base32文本形式
    if not cid.startswith("b"):
        raise ValueError("需要base32编码的CIDv1")
    encoded = cid[1:].upper()
    raw = base64.b32decode(encoded + "=" * (-len(encoded) % 8))
    version, pos = read_varint(raw, 0)
    codec, pos = read_varint(raw, pos)
    hash_code, pos = read_varint(raw, pos)
    digest_size, pos = read_varint(raw, pos)
    expected = raw[pos:]
    if version != 1 or hash_code != 0x12 or digest_size != 32 or len(expected) != 32:
        raise ValueError("仅支持本实验的CIDv1 SHA2-256")

    # 必须读取原始块,不能哈希dag get的JSON表示
    block = subprocess.check_output(["ipfs", "block", "get", cid])
    actual = hashlib.sha256(block).digest()
    if actual != expected:
        raise ValueError("块内容与CID不匹配")
    print(f"验证通过 codec={codec} bytes={len(block)}")


if __name__ == "__main__":
    verify(sys.argv[1])

保存为 verify_block.py,将 <CID> 替换为实际根 CID 后运行:

bash
python3 verify_block.py <CID>

预期输出格式如下,codec 与 bytes 来自真实根块,不能预先固定其值:

text
验证通过 codec=<CODEC> bytes=<SIZE>

脚本只验证指定 CID 对应的单个块。要验证整个 DAG,必须对所有可达的子块分别执行相同校验,并确认不存在遗漏的必需引用。生产实现还应限制遍历节点数、深度和累计数据量,防止恶意 DAG 消耗过多资源。

随后使用 UnixFS 文件读取命令验证能否恢复完整文件:

bash
ipfs cat <CID> > restored.bin
sha256sum dag-test.bin restored.bin

预期结果:sha256sum 输出两行记录,哈希摘要相同,文件名分别为 dag-test.bin 和 restored.bin。如果运行环境没有 sha256sum,可以改用 Python 的 hashlib 比较两个文件。

根 CID 验证、递归块验证和文件哈希比较分别覆盖不同层面:单块内容身份、整张引用图的完整获取,以及重建结果是否与原始文件相同。

缺失块与错误块如何影响恢复

缺失块、错误块与引用不完整的表现并不相同,排查时应先确认根节点能否读取,再逐层定位失败的子 CID。

故障类型 典型现象 判断与处理
缺失块 根节点可读取,某个子 CID 无法获取 检查本地块存储、在线提供者与网络连接,从其他持有正确块的节点恢复
错误块 收到的字节与请求 CID 的哈希不匹配 拒绝该块,重新从其他来源获取;不能用错误字节继续组装
引用不完整 父节点未包含预期数据的链接 如果父节点本身哈希正确,说明其内容就是这样定义的;需要找到正确的根 CID 或重新导入完整文件

可以通过两个相互隔离的 Kubo 仓库模拟缺块。第一个仓库已经拥有完整文件,第二个仓库只导入根节点原始块,且不连接第一个仓库或其他可能持有子块的节点。此时第二个仓库可能成功读取根节点结构,却无法恢复完整文件。

下面的 Bash 实验使用独立的临时仓库,并在离线模式下读取,避免网络自动补齐缺失块。执行前需确保根 CID 来自前述多块文件。

bash
# 从原仓库导出根节点原始块
ipfs block get <CID> > root.block

# 新建隔离仓库并初始化
export IPFS_PATH="$(mktemp -d)"
ipfs init

# 离线导入根块;根CID应与原值相同
ipfs block put --format=protobuf --mhtype=sha2-256 --mhlen=32 root.block

# 只具备根块时尝试离线读取整个文件
ipfs --offline cat <CID> > incomplete.bin

预期结果:ipfs block put 返回与原根 CID 对应的标识;最后的 ipfs cat 在缺少必需子块时失败,并输出块不可获取一类的错误。具体错误文字取决于 Kubo 版本,不应将 incomplete.bin 当成成功恢复的文件。实验结束后退出当前终端或恢复原来的 IPFS_PATH,避免后续命令误操作隔离仓库。

若收到内容被篡改的块,正确实现应依据请求 CID 拒绝不匹配的字节,而不是把它保存为原 CID 对应的有效内容。若发布者原本就生成了包含错误数据的 DAG,哈希仍然可能完全匹配,这属于内容来源与正确性问题,不属于传输完整性失败。

按层定位失败并恢复内容

实际排查时,建议遵循以下顺序:

  1. 用 ipfs block stat <CID> 确认根块能否获取;失败时先检查根 CID 是否正确、仓库是否包含该块,以及是否有可连接的提供者。
  2. 用 ipfs refs -r <CID> 递归检查引用;若遍历中断,记录最后能够访问的节点及失败的子 CID。
  3. 对已获取的关键块运行独立哈希校验,排除本地缓存、传输或非标准存储实现造成的内容错误。
  4. 使用 ipfs cat <CID> 恢复文件,并与已知可信的原始文件哈希比较;没有可信原件时,只能证明与该 DAG 所定义内容的一致性。
  5. 对缺失的块,从仍然持有正确 CID 内容的节点重新获取;恢复后重新执行递归读取与文件比较。

例如,一个根节点引用四个数据块,其中三个可获取、一个不可获取,即使当前已有 75% 的文件数据,也不能认为整个文件恢复成功。普通 UnixFS 文件没有默认的跨块纠删码冗余,缺少必需块时无法凭其他块自动推导出缺失字节。

对于需要长期分发的内容,应在导入后使用 ipfs pin add <CID> 保留本地所需块,并在其他独立节点保存完整副本。Pin 主要约束本地垃圾回收行为,不等于自动创建远端备份,也不保证节点始终在线。

沿 DAG 验证完整性的最终判据是:从可信的根 CID 出发,所有恢复文件所需的引用都能解析,所有获取的块都与各自 CID 匹配,并且 UnixFS 能够成功重建文件。根块存在只是验证的起点,不是完整文件可用的证明。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

沿 DAG 链接验证数据完整性

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通