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 指向目录节点,目录节点通过链接指向文件节点;较大的文件还可能继续指向多个数据块。

对于递归固定的根 CID R,Kubo 需要保留 R 及沿其链接可达的后代块。递归遍历还要求相关链接能够被解析、必要的数据块能够获取;缺少后代时,递归固定可能失败。
直接固定 R 则只要求保留 R 本身,不代表 A、B、C、D 自动受到保护。若这些后代没有其他 Pin 或保留机制,垃圾回收后就可能出现无法完整读取目录的情况。
创建测试内容并查询 Pin
以下操作适用于支持 ipfs pin 子命令的 Kubo CLI。开始前确认 Kubo 已安装、仓库已初始化,并且本地守护进程正在运行。可以在单独终端使用 ipfs daemon 启动节点。
为避免修改生产仓库,建议使用独立测试节点。以下示例在 Bash 环境执行,使用临时目录创建两个文件,并将目录导入 Kubo。
# 创建包含两个文件的测试目录
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 导入参数和编码方式决定:
added <CID_README> pin-demo/readme.txt
added <CID_CONFIG> pin-demo/config.json
added <CID_ROOT> pin-demo记录最后一行的目录根 CID。下文使用 <CID_ROOT> 表示这个实际值;它只是说明性占位符,执行命令时必须替换,不能连同尖括号原样输入。
首先查询根节点是否已经存在固定记录:
ipfs pin ls --type=recursive预期结果:列表中不应出现本次导入的 <CID_ROOT>,但仓库原有的其他递归 Pin 可能仍会显示。
随后添加递归固定并查询:
# 为目录根及可达后代建立递归保护
ipfs pin add <CID_ROOT>
ipfs pin ls --type=recursive
ipfs pin ls --type=all预期输出中,添加操作应出现类似记录:
pinned <CID_ROOT> recursively查询结果中,根 CID 应显示为 recursive;部分子块在 --type=all 查询中会显示为 indirect。具体 CID 数量取决于 UnixFS 节点布局和是否存在其他固定记录。
ipfs add 默认会对导入的根内容建立递归 Pin,因此本实验特意使用 --pin=false。如果省略该参数,再执行 ipfs pin add,就不能清楚观察从未固定到已固定的状态变化。
移除 Pin 并验证垃圾回收
移除 Pin 只是撤销保留声明,不等于立即删除数据。为了安全验证,先查询目标 CID 的状态,再撤销固定记录。
# 先确认根节点存在递归Pin
ipfs pin ls --type=recursive
# 撤销本次实验建立的递归Pin
ipfs pin rm <CID_ROOT>
ipfs pin ls --type=recursive预期输出中,移除操作应出现:
unpinned <CID_ROOT>再次查询递归 Pin 列表时,不应再出现该根 CID,除非它随后被重新固定。此时块数据可能仍保存在本地仓库,直接执行 ipfs cat 或 ipfs get 仍可能成功。
垃圾回收命令为:
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,前提是全部相关块仍可获取:
ipfs pin add <CID_ROOT>
ipfs pin ls --type=recursive预期结果:固定成功后,查询列表重新包含 <CID_ROOT>,类型为 recursive。如果之前的垃圾回收已经删除相关块,且网络上无法重新获取,固定操作可能失败,此时需要从原始文件重新导入。
实际运维中,建议同时记录根 CID、固定节点、固定状态、最后一次完整读取验证时间和副本数量。这样才能分别回答内容是否仍被保留、是否能够从网络发现,以及用户能否真正取回完整文件。