P2P 与分布式存储 / 系统课时
Pin 到底保留了什么数据
Pin 到底保留了什么数据
一个文件可以刚读完还能打开,却在垃圾回收后消失。本节用根块与后代块的关系解释 Pin 的保留范围,帮助你选择递归保留,避免只保留一个目录根块却丢掉目录中的文件。
学习目标
- 区分递归 Pin、直接 Pin 和间接 Pin。
- 根据内容结构判断保留范围,而不是只看根 CID。
保留集合对应本地块
Pin 是节点对本地数据保留的要求。递归 Pin 保护指定根及其可遍历后代,适用于 UnixFS 文件和目录的整个 DAG。直接 Pin 只保护指定单块,不自动保留其链接对象。间接 Pin 表示一个块受某个递归根保护,并不是第三种独立副本。
读取内容产生的本地缓存不等于 Pin。缓存块可以被 GC 清理;Pin 不使磁盘免于损坏,也不保证进程在线。远端服务的 Pin 还必须在该服务上检查,不能用本地 pin ls 代替远端承诺。

计算保留范围
下面在 Node.js 中演示图遍历。R、A 等是教学标签,不是 CID,集合计算不替代 Kubo 的块存储与 Pin 验证。保存为 scope.cjs 并执行 node scope.cjs。
const graph = {R: ['A', 'B'], A: ['C'], B: [], C: []};
function reachable(root) {
const seen = new Set(), todo = [root];
// 去重使共享后代只计算一次,也避免重复遍历。
while (todo.length) {
const key = todo.pop();
if (seen.has(key)) continue;
if (!(key in graph)) throw new Error(`missing node ${key}`);
seen.add(key); todo.push(...graph[key]);
}
return [...seen].sort().join(',');
}
console.log('recursive: ' + reachable('R'));
console.log('direct: R');预期输出:
recursive: A,B,C,R
direct: R如果另一个递归根也指向 C,取消 R 的 Pin 后,C 仍可能受到保护。因此“取消一个 Pin”并不等于“它的所有后代马上释放”。容量统计应该针对实际唯一块,而不是把每个根的逻辑大小简单相加。
数据存在与保留声明分别核对
对重要目录,应检查递归根在清单中,再检查后代是否完整,最后恢复文件。只成功读取根块,能证明的只是一个块存在。递归 Pin 操作需要缺块时可能访问网络;命令未完成时不应把任务登记为已保护。
MFS 中可达的数据也受 GC 保护,虽然它们不一定作为显式 Pin 出现在清单里。遇到取消 Pin 后空间没有减少,先盘点其他根和 MFS 引用,再考虑共享块、存储后端和文件系统,而不是强制删除块文件。
保留范围还受编解码可遍历性约束。根必须能正确解析,其链接对象才能纳入递归保护。不能将任意二进制数据里看似 CID 的字符串当成真正的 DAG 链接;应用自己保存的引用清单,必须由应用显式登记对应根。
当业务文件使用加密包装时,Pin 保留的是密文块,而解密密钥仍需独立备份。恢复到所有块不等于恢复到可使用明文;密钥丢失是另一个故障域,节点的保护关系无法弥补它。
验收边界
练习把示例改成 R 与另一根 S 共享 C,分别写出取消 R 前后的保护集合。真正的节点验证需要在独立练习仓库执行 ipfs pin ls 和 ipfs pin verify --verbose;本节只实跑图遍历,未执行 Kubo 验收。
命令与类型依据见官方 Pin 说明和Kubo Pin 命令源码。对于分块文件,默认选择递归 Pin;选择直接 Pin 应当有明确的单块用途。