P2P 与分布式存储 / 系统课时
区分可信网关与可验证检索
区分可信网关与可验证检索
通过 IPFS HTTP 网关读取文件时,客户端可能直接相信网关返回的内容,也可以自行验证返回数据是否与目标 CID 匹配。本课通过普通网关请求和 CAR 数据验证实验,区分传输成功与内容可信,并明确网关、CID 和本地验证器各自承担的职责。
学习目标
- 区分普通网关检索与无信任网关检索的信任边界。
- 使用 Kubo 和 CAR 格式完成一次可复现的内容校验。
- 判断 HTTP 成功响应、CID 校验和文件完整性分别能证明什么。
普通网关为什么存在信任边界
假设浏览器访问 https://<GATEWAY>/ipfs/<CID>,其中 <GATEWAY> 是网关域名,<CID> 是目标内容标识。普通网关通常解析 UnixFS 数据并返回文件字节,浏览器负责展示结果。
如果客户端只检查 HTTP 200 状态码,实际验证的是请求得到成功响应,而不是响应体必然符合 CID。网关可能配置错误、返回缓存中的错误内容,或者在传输过程中出现数据替换。
普通 HTTPS 网关提供的是客户端与网关之间的加密传输和服务器身份认证;HTTPS 本身不会验证响应内容是否符合 IPFS 的内容寻址规则。
| 检查项目 | 普通 HTTP 检索 | 客户端可验证检索 |
|---|---|---|
| HTTP 状态 | 可以检查 | 可以检查 |
| 返回内容 | 通常是已解析的文件字节 | 可以是 CAR 中的原始 IPLD 块 |
| CID 校验 | 依赖网关或额外客户端逻辑 | 客户端自行计算并核对 |
| DAG 链接 | 通常由网关遍历 | 客户端可验证块间引用 |
| 信任边界 | 信任网关正确解析并返回内容 | 信任本地验证实现及预先取得的目标 CID |
CAR 如何支持无信任检索
CAR(Content Addressable aRchives)是一种承载内容寻址数据块的归档格式。CAR 文件包含根 CID 信息和一组带 CID 的块记录,客户端能够在不要求网关提前还原文件的情况下读取这些块。
验证器需要根据每个块的 CID 中声明的多哈希算法重新计算块内容的摘要,确认实际字节与 CID 一致,再根据 DAG 编码解码链接并检查引用关系。对于 UnixFS 文件,还需要正确解释文件节点、子块顺序及文件长度等语义。

CAR 只是数据格式,不是安全保证。下载 CAR 后直接解包而不检查块哈希和链接,仍然没有完成无信任检索。客户端还应检查返回的根是否与请求目标一致,以及重建目标文件所需的块是否齐全。
使用 Kubo 构造可验证的 CAR 数据
以下实验适用于安装了 Kubo CLI、支持 ipfs dag export 与 ipfs dag import 的环境。使用两个独立仓库分别代表内容生产端与验证端,避免验证端预先持有待验证数据。
先在 Bash 环境执行以下命令,创建源仓库并生成一个单块 Raw CID。显式指定 CIDv1 和 Raw 叶节点,可以减少导入布局差异对实验的影响。
export IPFS_PATH="$(mktemp -d)"
ipfs init --profile=test
printf 'hello ipfs\n' > sample.txt
CID=$(ipfs add -Q --cid-version=1 --raw-leaves=true --chunker=size-262144 sample.txt)
printf 'Source CID: %s\n' "$CID"
ipfs dag export "$CID" > sample.car
ls -lh sample.car预期结果:终端显示以 bafk 开头的 CIDv1 字符串和非空 sample.car 文件。CID 的完整文本由实际内容决定;ls 显示的文件大小随 CAR 编码开销变化。
Source CID: bafk<实际CID剩余字符>
-rw-r--r-- ... sample.car这里的 <实际CID剩余字符> 是输出说明占位,并非合法 CID。实验中的 sample.txt 含有 hello ipfs 和末尾换行,合计 11 字节。ipfs dag export 根据目标 CID 导出可达 DAG 的块,生成的 CAR 可以交给其他客户端验证。
接下来建立全新的验证仓库,导入 CAR 并重新读取目标内容。
export IPFS_PATH="$(mktemp -d)"
ipfs init --profile=test
ipfs dag import --pin-roots=false sample.car
ipfs block get "$CID" > recovered.bin
cmp sample.txt recovered.bin
printf 'Verified content: '
cat recovered.bin预期结果:导入命令报告成功处理 CAR;cmp 没有差异输出,最后打印原始文件内容。
Verified content: hello ipfsipfs dag import 会按 Kubo 的块存储校验规则处理导入数据,ipfs block get 从新仓库读取目标块;对于本例的单块 Raw 文件,cmp 可以直接比较原始文件字节。对于多块 UnixFS 文件,不能将根块的原始字节直接当成完整文件,需要使用能够验证并解析整个 DAG 的客户端重建文件。
通过 HTTP 请求 CAR 并检查返回类型
支持 IPFS Trustless Gateway 规范的网关可以根据 HTTP Accept 请求头返回 CAR 数据。这里使用已知的目标 CID 发起请求,网关地址需要替换为实际支持 CAR 响应的服务。
curl --fail --show-error --location \
-H 'Accept: application/vnd.ipld.car' \
-D response.headers \
-o gateway.car \
"https://<GATEWAY>/ipfs/$CID"预期结果:如果网关支持该请求并成功返回,gateway.car 为非空 CAR 文件,响应头包含与 CAR 对应的媒体类型,例如:
HTTP/2 200
content-type: application/vnd.ipld.car实际 HTTP 版本、响应头大小写及附加参数可能不同。若返回 406、其他错误状态或 HTML 错误页,不能将响应体当作 CAR。curl --fail 会使 HTTP 400 及以上响应通常以非零状态退出,但不会验证内容哈希。
随后在独立仓库中导入并验证返回的 CAR。为了避免已有本地块掩盖缺失数据,建议每次测试都使用新仓库;还必须确认 CAR 的根与预期 CID 对应,并检查目标 DAG 是否完整。
对于当前单块 Raw 示例,可以使用以下命令完成字节级检查:
export IPFS_PATH="$(mktemp -d)"
ipfs init --profile=test
ipfs dag import --pin-roots=false gateway.car
ipfs block get "$CID" > from-gateway.bin
cmp sample.txt from-gateway.bin
printf 'Gateway content verified\n'预期结果:在网关返回正确且包含目标块的 CAR 时,最后显示:
Gateway content verified这段实验假设 CID 和 sample.txt 仍来自前面的可信源数据。生产环境不应依赖本地原文件做逐字节比较,而应由客户端以预先取得的 CID 为校验依据,验证每个返回块及其 DAG 链接。
判断校验失败的具体位置
当远程检索失败时,按照数据接收、块验证、DAG 遍历三个层次定位,可以避免把所有异常都归结为网关不可用。
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
| HTTP 200,但返回 HTML | Content-Type 与响应体 |
检查网关是否支持 CAR 协商 |
| CAR 可以读取,但块哈希不匹配 | 块字节与块 CID | 拒绝错误块,重新检索 |
| 块哈希正确,但缺少子块 | DAG 链接及缺失 CID | 补取缺失块,不宣布文件完整 |
| 块齐全,但文件重建错误 | UnixFS 解码与文件布局 | 检查解码器和路径解析 |
| 所有 CID 校验成功,但内容不是预期文件 | 初始目标 CID 的来源 | 核对可信清单或签名发布记录 |
在真实项目中,可以将检索结果分为 transport_ok、blocks_verified、dag_complete 和 content_decoded 四个内部检查阶段。它们是应用自定义的状态名,并非网关标准响应字段。只有目标 CID、所需块及文件解码全部验证通过,才能向业务层报告内容可用。
普通网关适合对网关服务有明确运营信任的网页展示场景;需要跨不可信服务商取回数据、校验镜像或验证归档时,应使用支持 CAR 的检索接口和真正执行本地校验的客户端。即使网关不可信,只要预期 CID 来源可靠、验证算法正确且所需数据完整,客户端仍能独立判断取回内容是否与目标匹配。