P2P 与分布式存储 / 系统课时
用 Pin 命令保留一份 CID
用 Pin 命令保留一份 CID
读取过远端内容,并不意味着节点承诺长期保留。本节先把文件以不自动 Pin 的方式导入,再显式递归 Pin,观察成功信号和保留清单,形成安全的“获取后登记”流程。
学习目标
- 对真实根 CID 建立显式递归保留关系。
- 将获取完成与 Pin 完成作为两个独立验收条件。
命令完成之前不要登记成功
ipfs pin add 默认递归遍历根及后代,缺块时在线节点可能从网络获取。大目录的操作可能持续较久;启动命令或出现进度条不是成功结果。任务应在命令成功返回、清单可查且完整性检查通过后进入已保留状态。
本例用本地完整文件消除网络变量。环境为 Bash 与 Kubo 0.43.1,全新临时仓库,命令离线执行;真实 Kubo 操作本节未执行。原文件仍然保留在另一个临时目录,便于发现任何导入或恢复错误。
显式建立并核对 Pin
set -euo pipefail
export IPFS_PATH="$(mktemp -d)"
work="$(mktemp -d)"
ipfs init > /dev/null
printf 'explicit-pin\n' > "$work/input.txt"
cid="$(ipfs --offline add --pin=false -Q "$work/input.txt")"
# 不启用自动GC;只在这个独立仓库里建立保留关系。
ipfs --offline pin add --recursive=true "$cid"
ipfs --offline pin ls --type=recursive "$cid"
ipfs --offline pin verify --verbose
ipfs --offline cat "$cid" > "$work/output.txt"
cmp "$work/input.txt" "$work/output.txt"
printf 'pin and restore verified\n'预期结果:
pinned <CID> recursively
<CID> recursive
<CID> ok
pin and restore verifiedCID 和完整性检查的其他条目随实际仓库而变化。必须确认检查项为 ok,遇到 broken 或 error 阻断成功登记,即使命令退出码为零。pin add 重复对同一内容递归 Pin 不会制造第二份独立磁盘副本,程序也不能用重试次数作为副本数。若发生失败,应保存错误并再次查询实际状态,避免客户端记录与节点事实不一致。
递归与直接怎样选
常规 UnixFS 文件或目录使用递归 Pin。--recursive=false 只保护单块,适合确知对象没有需要保留的后代,或另有明确块管理策略的场景。给目录根做直接 Pin,然后成功读取根的信息,并不能验收目录中每个文件。
不建议在业务脚本中统一把所有 Pin 改成直接类型以“省空间”。这会改变保护语义,而且共享块原本已经由块存储去重。要减少长期占用,应从业务生命周期和多版本保留规则入手,盘点后再取消不需要的根。
业务侧成功登记还应包含节点身份与操作时间。两个节点分别完成 Pin 可以形成两个候选副本;同一节点的两个任务回执只证明两次调用。若希望达到多点保留,必须核对存储位置与故障域。
超时后的安全重试
在线 Pin 超时时,应区分网络获取不完整、磁盘写入失败和调用方等候时间不足。先核对节点、CID 和剩余磁盘,查询清单,然后对同一个目标重试。不要为了让命令快点完成改成直接 Pin,那只是把完整性要求删掉了。
练习对上述根再次运行递归 Pin,核对清单并说明为什么内容保护成立但副本数量没有增加。真实在线获取、服务超时和磁盘故障仍需读者另外验收。默认值和成功输出见Kubo Pin 实现,成功记录应随节点事实更新。