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从源节点导出内容图并在目标节点恢复的结构

CAR 不默认执行 ZIP、GZIP 一类的压缩,也不以普通文件路径作为基本存储单元。导入 CAR 后,数据进入目标节点的块存储;如需在操作系统中恢复原始目录,应再执行 ipfs get。直接把同一内容图导入另一个仓库,不需要重新选择分块参数,因此能够保留原根 CID。

在两个独立仓库之间导出和导入

下面使用 macOS 或 Linux 的 Bash 环境演示,要求已经安装 Kubo CLI,并能正常执行 ipfs version。示例不启动 daemon,而是通过 IPFS_PATH 创建两个完全隔离的本地仓库,分别模拟节点 A 和节点 B。使用 --offline 避免读取时从网络补取缺失数据。

完整示例:

bash
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"

预期输出(忽略可能出现的初始化诊断信息):

text
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 变量。

bash
ipfs --offline get --output="$LAB/restored-directory" "$ROOT"
cmp "$LAB/data/docs/readme.txt" "$LAB/restored-directory/docs/readme.txt"
printf '普通目录恢复成功\n'

预期输出:

text
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 成功作为验收条件。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 CAR 打包和恢复内容图

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

登录哪都通