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

通过 Pin 保留必要的数据块

通过 Pin 保留必要的数据块

本课使用 Kubo 命令行完成 Pin 的查询、添加和移除,并通过一个包含多个文件的目录验证递归固定的保护范围。完成后,你将能够区分直接固定与递归固定,判断哪些数据块可以被垃圾回收,以及为什么本地 Pin 不等于全网永久可用。

学习目标

  • 使用 ipfs pin ls、ipfs pin add 和 ipfs pin rm 管理固定记录。
  • 理解递归 Pin 如何保护 UnixFS Merkle DAG 中的根节点与子块。
  • 验证 Pin 与垃圾回收的关系,识别本地留存和网络可用性的边界。

Pin 解决什么问题

Kubo 将内容存储为由 CID 标识的数据块。文件导入后,相关块进入本地仓库,但并非所有块都会被永久保留。仓库垃圾回收(Garbage Collection,GC)会清理不再受到固定记录等保留机制保护的数据块。

Pin 是 Kubo 对本地内容的保留声明。对于需要长期保存的文件、目录或应用资源,应明确建立 Pin,而不是依赖近期访问过或曾经下载过这一事实。

Kubo 的传统 Pin 类型主要包括:

类型 含义 保护范围
recursive 递归固定 根块以及沿 DAG 链接可达的全部后代块
direct 直接固定 指定块本身,不自动保护后代
indirect 间接固定 因属于其他递归 Pin 的后代而受到保护

indirect 是查询时显示的派生状态,不是需要单独创建的固定类型。一个块也可能同时受到多个固定根的保护。

例如,一个目录包含 readme.txt 和 config.json。如果只保留目录根块,却丢失某个文件的数据块,目录结构仍可能被解析,但文件内容无法完整读取。因此,对完整目录的长期留存通常使用递归 Pin。

递归 Pin 如何保护 DAG

UnixFS 将目录、文件元数据和文件数据组织为 Merkle DAG。根 CID 指向目录节点,目录节点通过链接指向文件节点;较大的文件还可能继续指向多个数据块。

递归Pin与直接Pin保护范围对比

对于递归固定的根 CID R,Kubo 需要保留 R 及沿其链接可达的后代块。递归遍历还要求相关链接能够被解析、必要的数据块能够获取;缺少后代时,递归固定可能失败。

直接固定 R 则只要求保留 R 本身,不代表 A、B、C、D 自动受到保护。若这些后代没有其他 Pin 或保留机制,垃圾回收后就可能出现无法完整读取目录的情况。

创建测试内容并查询 Pin

以下操作适用于支持 ipfs pin 子命令的 Kubo CLI。开始前确认 Kubo 已安装、仓库已初始化,并且本地守护进程正在运行。可以在单独终端使用 ipfs daemon 启动节点。

为避免修改生产仓库,建议使用独立测试节点。以下示例在 Bash 环境执行,使用临时目录创建两个文件,并将目录导入 Kubo。

bash
# 创建包含两个文件的测试目录
mkdir -p pin-demo
printf 'Pin keeps important blocks.\n' > pin-demo/readme.txt
printf '{"version":1}\n' > pin-demo/config.json

# --pin=false 避免导入时自动递归固定
ipfs add -r --cid-version=1 --pin=false pin-demo

预期输出结构如下,实际 CID 由文件字节、UnixFS 导入参数和编码方式决定:

text
added <CID_README> pin-demo/readme.txt
added <CID_CONFIG> pin-demo/config.json
added <CID_ROOT> pin-demo

记录最后一行的目录根 CID。下文使用 <CID_ROOT> 表示这个实际值;它只是说明性占位符,执行命令时必须替换,不能连同尖括号原样输入。

首先查询根节点是否已经存在固定记录:

bash
ipfs pin ls --type=recursive

预期结果:列表中不应出现本次导入的 <CID_ROOT>,但仓库原有的其他递归 Pin 可能仍会显示。

随后添加递归固定并查询:

bash
# 为目录根及可达后代建立递归保护
ipfs pin add <CID_ROOT>
ipfs pin ls --type=recursive
ipfs pin ls --type=all

预期输出中,添加操作应出现类似记录:

text
pinned <CID_ROOT> recursively

查询结果中,根 CID 应显示为 recursive;部分子块在 --type=all 查询中会显示为 indirect。具体 CID 数量取决于 UnixFS 节点布局和是否存在其他固定记录。

ipfs add 默认会对导入的根内容建立递归 Pin,因此本实验特意使用 --pin=false。如果省略该参数,再执行 ipfs pin add,就不能清楚观察从未固定到已固定的状态变化。

移除 Pin 并验证垃圾回收

移除 Pin 只是撤销保留声明,不等于立即删除数据。为了安全验证,先查询目标 CID 的状态,再撤销固定记录。

bash
# 先确认根节点存在递归Pin
ipfs pin ls --type=recursive

# 撤销本次实验建立的递归Pin
ipfs pin rm <CID_ROOT>
ipfs pin ls --type=recursive

预期输出中,移除操作应出现:

text
unpinned <CID_ROOT>

再次查询递归 Pin 列表时,不应再出现该根 CID,除非它随后被重新固定。此时块数据可能仍保存在本地仓库,直接执行 ipfs cat 或 ipfs get 仍可能成功。

垃圾回收命令为:

bash
ipfs repo gc

预期结果:命令会报告被回收的块,但具体数量和 CID 不固定。没有其他保护的测试块可能被清理;仍受到其他递归或直接 Pin 保护的块不会仅因本次撤销操作而被回收。

如果垃圾回收后仍能通过 CID 读取内容,不能据此认定撤销 Pin 失败。内容可能受到其他 Pin 保护、仍被仓库保留,或者被节点从网络重新获取。验证本地保留状态时应以 Pin 查询和仓库实际状态为依据,而不是只看一次网络读取是否成功。

判断哪些内容应该固定

在实际项目中,应根据内容的保留责任选择固定范围。

内容场景 建议做法 原因
网站静态资源目录 递归固定发布版本的根 CID 保留页面、脚本、样式与图片等可达块
单个完整文件 递归固定文件根 CID 大文件可能由多个块组成
独立原始块 按需求直接固定 只需要保护指定块本身
临时下载缓存 不长期固定 允许仓库按策略回收
已淘汰的发布版本 确认无其他依赖后移除 Pin 释放不再需要的保留责任

假设项目每周发布一个新版本,每个版本占用约 200 MiB。如果连续保留 10 个完全不共享数据块的版本,受 Pin 保护的数据量约为 2000 MiB。实际占用还会受到跨版本块复用、仓库元数据和其他内容的影响,不能简单将文件逻辑大小视为磁盘精确占用。

一种可执行的发布策略是:先递归固定新版本根 CID,验证文件读取成功,再更新应用引用;待旧版本不再需要时,移除旧根的 Pin,最后在维护窗口执行垃圾回收。多个版本共享的数据块,只要仍被其他递归 Pin 保护,就不应因删除某个旧版本 Pin 而失去保护。

Pin 不等于全网永久可用

需要明确区分三个条件:本地保留、网络可发现、远端可读取。

本地 Pin 主要解决第一个条件。其他节点想要读取内容,还需要发现能够提供数据的节点、建立连接并成功传输相关块。即使节点 A 已递归固定目录,若节点 A 长期离线、网络不可达或未能被其他节点发现,节点 B 也未必能获取内容。

对于需要持续公开访问的内容,可以在多个独立节点上保留副本,并定期验证读取结果。第三方 Pinning 服务也可以承担远端副本保留,但需要确认服务是否成功固定、是否覆盖完整 DAG,以及是否满足实际可用性要求。

最后可在当前节点重新建立实验目录的递归 Pin,前提是全部相关块仍可获取:

bash
ipfs pin add <CID_ROOT>
ipfs pin ls --type=recursive

预期结果:固定成功后,查询列表重新包含 <CID_ROOT>,类型为 recursive。如果之前的垃圾回收已经删除相关块,且网络上无法重新获取,固定操作可能失败,此时需要从原始文件重新导入。

实际运维中,建议同时记录根 CID、固定节点、固定状态、最后一次完整读取验证时间和副本数量。这样才能分别回答内容是否仍被保留、是否能够从网络发现,以及用户能否真正取回完整文件。

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

目录与阅读设置

阅读设置

17

记录一个想法

通过 Pin 保留必要的数据块

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

登录哪都通