ipfs pin update怎样安全换CID？ 图 1
ipfs pin update怎样安全换CID？ · 图 1

网站快照或数据集只改了少数文件时，先rm旧Pin再add新CID会重复遍历大量相同DAG，还会制造一个旧版本不受保护的窗口。ipfs pin update为共同分支较多的新旧对象提供增量路径，但它的默认行为会移除旧Pin，因此安全流程应先把默认值改成显式决定。

命令的两个位置参数不能写反

ipfs pin update的参数依次是旧对象路径和待固定的新对象路径，用于更新递归Pin。

该命令利用新旧DAG的共同分支减少遍历，适合新对象与旧对象高度相似的场景。

from-path是现有旧对象，to-path是准备固定的新对象。Kubo根据差异跳过已经由旧递归Pin覆盖的共同分支。新旧数据越相似，越可能减少重复遍历；两个完全无关的DAG仍能更新，但不要期待同样的效率。

阶段必须成立失败时动作
预检旧CID是recursive Pin停止并查Pin类型
获取新CID及其完整DAG可达补齐providers或本地块
更新新Pin成功写入保留旧Pin和日志
验收新根与深层路径可读不执行旧Pin清理

旧对象必须是递归Pin

旧对象必须已经是递归Pin，默认—unpin=true会在更新后移除旧Pin。

direct Pin只保护根块，indirect表示对象被另一个递归Pin覆盖，二者都不满足pin update要求。运行前用精确CID查询pin ls，并保存输出。若旧CID已不存在或仅为indirect，应先重新评估数据关系，不要为了让命令通过盲目添加或删除Pin。

还要确认新CID解析到预期codec和内容，而不是只检查字符串格式。对网站发布包，可先读取manifest、首页和几个深层资源；对CAR导入包，记录导入结果与根CID。

默认unpin=true意味着旧保护会被撤下

官方说明—unpin默认true。对关键数据，第一轮更稳妥的选择是显式使用—unpin=false，形成新旧两个递归Pin并存的验收窗口。确认新CID完整、应用已切换且回滚窗口结束后，再精确移除旧Pin。

双Pin会暂时占用额外元数据和不共享分支的存储，这是可控的安全成本。不要在磁盘已接近上限时直接运行更新；先结合repo/stat评估容量，并暂停自动GC，避免把验证过程与空间回收混在一起。

退出码成功之后还要做三联验证

Pin用于保护解析后的CID不被垃圾回收；更新后应通过pin ls与pin verify验收，而不是只看命令退出。

第一用pin ls确认新根是recursive，并确认旧根是否符合预期保留；第二运行pin verify检查递归Pin的DAG完整性；第三从应用真实访问路径抽查根文件、深层文件和较大对象。若内容有manifest或哈希清单，再做逐项比对。

验证日志应保存Kubo版本、旧CID、新CID、unpin参数、开始结束时间、pin verify结果和抽查样本。只写“command succeeded”不足以证明新版本可服务。

回滚的前提是旧Pin仍在

应用切换后出现404、内容哈希不符或深层块缺失时，立即把流量指回旧CID，保留新CID现场并排查providers、导入和本地仓库。若首次更新使用默认unpin=true，旧根可能已失去直接保护，回滚还要重新拉取数据，恢复时间会明显增加。

清理旧Pin前再次确认没有其它IPNS记录、网关配置、离线任务或备份清单仍引用它。删除只移除Pin保护，真正的数据块何时被GC取决于仓库操作。

完整性检查可参考Pin完整性核验，垃圾回收边界见repo/gc删除边界，远端固定状态见远端Pin状态。本文适用于合法内容运维，不承诺公共网关永久可用，也不建议将敏感明文存入公开IPFS。

命令资料与回滚条件

  1. Kubo pin update：参数、默认unpin、效率与旧Pin前提。
  2. Kubo pin add：Pin防止垃圾回收的作用。
  3. Kubo pin ls：Pin类型和精确查询。
  4. Kubo pin verify：递归Pin完整性验证。

资料访问时间为2026-08-13。仍需保留的边界：命令耗时和磁盘峰值取决于DAG规模、共享分支和数据可达性；文章不给统一时长。