P2P 与分布式存储 / 系统课时
用 CAR 打包和恢复内容图
用 CAR 打包和恢复内容图
把根 CID 对应的整个内容图导出为 CAR 文件,再导入另一个独立的 Kubo 仓库,就能迁移原始数据块并保留内容寻址关系。本篇使用两个离线仓库完成导出、导入和恢复,通过图统计、文件字节比较及 Pin 状态判断迁移是否完整。
学习目标
- 使用
ipfs dag export将指定根 CID 的完整内容图保存为 CAR 文件。 - 使用
ipfs dag import恢复数据块,并验证文件内容和递归 Pin 状态。 - 区分 CAR 与普通压缩包,识别不完整内容图带来的导入风险。
CAR 保存了哪些数据
CAR 是 Content Addressable aRchive 的缩写,用于保存按内容寻址的 IPLD 数据块及其根 CID 信息。它不是简单地把原始文件放进一个容器,而是保留内容图中的块及其 CID,使另一个节点能够按原来的链接关系重建数据。
CARv1 的主要内容包括:
- 归档头部:包含版本号和根 CID 列表。
- 数据块记录:每条记录包含 CID 和对应的原始块字节。
- 块间关系:由块内部的 IPLD 链接表达,而不是依赖压缩包中的目录索引。
假设一个 UnixFS 根目录包含 docs/readme.txt 和 config.json。根目录节点保存文件名及对应的 CID 链接;文件节点可能继续指向多个数据块。Kubo 的 ipfs dag export 会从指定根 CID 出发,递归导出可达的数据块,而不是导出整个本地仓库。

CAR 不默认执行 ZIP、GZIP 一类的压缩,也不以普通文件路径作为基本存储单元。导入 CAR 后,数据进入目标节点的块存储;如需在操作系统中恢复原始目录,应再执行 ipfs get。直接把同一内容图导入另一个仓库,不需要重新选择分块参数,因此能够保留原根 CID。
在两个独立仓库之间导出和导入
下面使用 macOS 或 Linux 的 Bash 环境演示,要求已经安装 Kubo CLI,并能正常执行 ipfs version。示例不启动 daemon,而是通过 IPFS_PATH 创建两个完全隔离的本地仓库,分别模拟节点 A 和节点 B。使用 --offline 避免读取时从网络补取缺失数据。
完整示例:
set -euo pipefail
# 创建两个独立仓库和一份包含两个文件的测试目录
LAB="$(mktemp -d)"
mkdir -p "$LAB/source" "$LAB/target" "$LAB/data/docs"
printf 'CAR demo v1\n' > "$LAB/data/docs/readme.txt"
printf '{"mode":"test"}\n' > "$LAB/data/config.json"
# 在源仓库添加目录,记录根CID及完整内容图统计
export IPFS_PATH="$LAB/source"
ipfs init >/dev/null
ROOT="$(ipfs --offline add --recursive --quieter --cid-version=1 "$LAB/data")"
SOURCE_STAT="$(ipfs --offline dag stat "$ROOT")"
ipfs --offline dag export --progress=false "$ROOT" > "$LAB/site.car"
test -s "$LAB/site.car"
printf 'CAR 已生成\n'
# 切换到全新的目标仓库,离线导入并递归Pin根节点
export IPFS_PATH="$LAB/target"
ipfs init >/dev/null
ipfs --offline dag import --pin-roots=true "$LAB/site.car" >/dev/null
TARGET_STAT="$(ipfs --offline dag stat "$ROOT")"
test "$SOURCE_STAT" = "$TARGET_STAT"
printf '图统计一致\n'
# 从导入后的CID路径读取两个文件并比较原始字节
ipfs --offline cat "/ipfs/$ROOT/docs/readme.txt" > "$LAB/restored-readme.txt"
ipfs --offline cat "/ipfs/$ROOT/config.json" > "$LAB/restored-config.json"
cmp "$LAB/data/docs/readme.txt" "$LAB/restored-readme.txt"
cmp "$LAB/data/config.json" "$LAB/restored-config.json"
printf '两个文件字节一致\n'
# 确认归档根节点已受到递归Pin保护
ipfs --offline pin ls --type=recursive --quiet "$ROOT" | grep -Fx "$ROOT" >/dev/null
printf '根 CID 已递归 Pin\n'
printf 'CAR 路径:%s\n' "$LAB/site.car"预期输出(忽略可能出现的初始化诊断信息):
CAR 已生成
图统计一致
两个文件字节一致
根 CID 已递归 Pin
CAR 路径:<PATH>/site.car<PATH> 是 mktemp -d 创建的临时工作目录,实际路径每次可能不同;ROOT 保存的真实 CID 也由内容和导入参数决定。
这里有三个关键点。第一,ipfs dag export 把 CAR 二进制流写到标准输出,必须重定向到 .car 文件,不能直接当作文本查看。第二,ipfs dag import --pin-roots=true 导入归档中的块,并尝试递归 Pin 归档头部声明的根 CID。第三,导入后读取的是原来的根 CID,而不是重新执行 ipfs add 生成一个新根。
检查归档覆盖范围和恢复结果
导入命令执行成功不应成为唯一验收依据。完整迁移至少需要检查内容图是否可遍历、目标文件能否恢复,以及数据是否得到本地保留。
| 检查项目 | 检查方式 | 通过条件 |
|---|---|---|
| CAR 文件有效性 | 检查文件非空且 dag import 无错误 |
可以读取归档并处理根 CID |
| 内容图覆盖 | 源、目标分别执行 ipfs dag stat |
同一根 CID 的块数量及图大小一致 |
| 文件恢复 | 通过 /ipfs/<CID>/... 读取并执行 cmp |
原始字节完全一致 |
| 根节点保护 | ipfs pin ls --type=recursive |
能找到导入的根 CID |
| 网络独立性 | 在全新仓库中使用 --offline 读取 |
不依赖远端节点补取数据 |
其中,ipfs dag stat 会遍历指定根的内容图,给出块数量和图大小。它适合检查可遍历范围,但不能单独代替字节级内容校验。示例进一步使用 cmp 比较两个恢复文件;只要任一文件不同,命令就会以非零状态结束。
如果需要把导入的数据还原成普通目录,可以保持目标仓库的 IPFS_PATH 设置不变,再执行以下命令。该命令依赖前一个示例已经创建的 ROOT 和 LAB 变量。
ipfs --offline get --output="$LAB/restored-directory" "$ROOT"
cmp "$LAB/data/docs/readme.txt" "$LAB/restored-directory/docs/readme.txt"
printf '普通目录恢复成功\n'预期输出:
Saving file(s) to <PATH>/restored-directory
普通目录恢复成功其中第一行是 Kubo 的保存路径提示,具体目录路径可能不同;部分版本或终端环境也可能显示进度信息。重点是目标目录中出现 docs/readme.txt 和 config.json,且文件内容与源目录一致。
处理不完整归档和常见误区
默认的 ipfs dag export 需要取得从根 CID 可达的完整数据图。如果某些子块缺失,并且无法获取,导出会失败。排查时应先确认源仓库能完整读取数据,再重新导出,而不是仅检查根 CID 是否存在。
Kubo 0.42 及之后的版本还提供 dag export --local-only,允许跳过本地缺失的块,生成部分 CAR。这适用于缓存迁移等场景,却不能将这样的 CAR 当作完整备份。对应的 dag import --local-only 不会递归 Pin 根节点,因为部分内容图无法满足完整递归 Pin 的要求。
另外,dag import 会导入 CAR 文件中包含的数据块,即使部分块不在归档根的可达范围内。这些额外块不会自动受到根节点的递归 Pin 保护,后续可能被垃圾回收。对于需要长期保留的归档,应明确根 CID、检查完整可达性,并确认 Pin 结果。
实际项目可以把 CAR 用于跨环境迁移、离线数据交付和内容图备份。建议同时保存根 CID、CAR 文件、生成时使用的 Kubo 版本以及恢复验证结果。命令选项可参照 Kubo CLI 官方参考。对于必须完整恢复的交付物,应以离线可遍历全部内容图、根 CID 保持一致、文件字节校验通过及递归 Pin 成功作为验收条件。