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

发布 IPNS 名称并更新内容指向

发布 IPNS 名称并更新内容指向

本课使用 Kubo 命令行创建 IPNS 名称,先将名称发布到一个文件 CID,再更新为新版本 CID,并通过名称解析和内容读取验证更新结果。完成后,你将掌握不改变访问名称就能切换内容版本的方法,以及 IPNS 发布、缓存和解析的关键边界。

学习目标

  • 使用 Kubo 生成 IPNS 密钥,并发布指向指定 CID 的名称记录。
  • 更新同一个 IPNS 名称的目标 CID,验证新旧内容的解析结果。
  • 区分 IPNS 可变名称与 IPFS 不可变 CID,理解记录有效期和缓存造成的延迟。

准备节点和两个内容版本

以下操作适用于支持 ipfs key、ipfs name publish 和 ipfs name resolve 的 Kubo 0.3x 系列命令行。准备一个已初始化并正在运行的本地 Kubo 节点,终端能够调用 ipfs。本例使用 Bash,在 Linux、macOS 或安装 Bash 的环境中执行。

先确认节点可以访问本地 API:

bash
ipfs id -f='<id>\n'

预期输出:

text
<ID>

<ID> 表示当前节点的 Peer ID,实际值因节点而异。若提示无法连接 API,应先在另一个终端执行 ipfs daemon,保持进程运行后再重试。

创建两个文件版本,并分别导入 IPFS。这里采用文件根 CID,不使用目录包装,以便后续直接读取文件内容。

bash
printf 'version=1\n' > ipns-v1.txt
printf 'version=2\n' > ipns-v2.txt
CID_V1=$(ipfs add -Q --cid-version=1 ipns-v1.txt)
CID_V2=$(ipfs add -Q --cid-version=1 ipns-v2.txt)
printf '两个版本 CID 是否不同:'
if [ "$CID_V1" != "$CID_V2" ]; then echo yes; else echo no; fi

预期输出:

text
两个版本 CID 是否不同:yes

两个文件的字节不同,因此在相同导入参数下得到不同 CID。CID_V1 和 CID_V2 是当前 Shell 中的变量,后续命令需要在同一终端执行。实际 CID 字符串由文件内容及导入配置决定。

生成名称并发布第一个 CID

IPNS 使用密钥对应的身份标识作为可变名称。发布者用私钥签署 IPNS 记录,记录中包含指向内容的路径、序列号和有效期等信息;解析者依据公钥身份验证记录,而不是信任某个任意字符串。

创建专用密钥 course-ipns,避免修改节点默认身份所使用的 IPNS 名称:

bash
ipfs key gen --type=ed25519 course-ipns

预期输出为新密钥对应的 IPNS 名称,例如:

text
k51...

上面的 k51... 仅表示名称格式,实际输出是完整的编码字符串。密钥名称必须在本地唯一;如果已存在同名密钥,命令会报错,不应直接删除正在使用的私钥。

使用新密钥发布第一个版本:

bash
ipfs name publish --key=course-ipns --allow-offline /ipfs/$CID_V1

预期输出形态如下,实际名称和 CID 不同:

text
Published to k51...: /ipfs/bafy...

--key 选择签名密钥;--allow-offline 允许在没有足够网络连接时生成和保存本地记录,但不保证其他节点能够立即发现它。正常联网发布仍需要网络路由服务协助传播记录。

IPNS名称、签名记录与不可变CID之间的关系

更新名称并验证解析结果

先读取密钥的完整 IPNS 名称,随后分别验证本地名称解析和内容读取。ipfs name resolve 返回的是 /ipfs/<CID> 路径,而不是文件正文。

bash
IPNS_NAME=$(ipfs key list -l | awk '$2 == "course-ipns" {print $1}')
ipfs name resolve --nocache /ipns/$IPNS_NAME
ipfs cat /ipfs/$CID_V1

预期结果:第一条解析命令返回 /ipfs/ 加第一个版本的完整 CID,第二条读取命令输出:

text
version=1

现在保持密钥和名称不变,只把记录指向第二个 CID,再重新解析:

bash
ipfs name publish --key=course-ipns --allow-offline /ipfs/$CID_V2
ipfs name resolve --nocache /ipns/$IPNS_NAME
ipfs cat /ipfs/$CID_V2

预期结果:发布命令仍显示相同的 k51... 名称,但目标路径变为 /ipfs/ 加第二个版本的 CID;解析命令返回第二个 CID;内容读取输出:

text
version=2

这说明名称身份保持不变,而记录指向的不可变内容发生了变化。旧 CID 并不会因为 IPNS 更新而被改写或自动删除,仍可在对应数据块可用时通过原 CID 读取。

IPNS更新前后名称保持不变而目标CID变化

控制记录有效期与解析缓存

IPNS 更新不是对所有客户端的即时推送。发布者需要将新签名记录传播到路由系统,解析端还可能持有旧记录的缓存。因此本地解析成功不等于所有远端节点已经看到新版本。

常用发布参数如下:

参数 示例 作用
--key course-ipns 指定签名密钥
--lifetime 24h 设置记录有效期
--ttl 5m 提供建议缓存时间
--allow-offline true 允许离线发布,不保证网络传播

例如,将当前名称重新发布到第二个版本,并指定记录有效期和建议缓存时间:

bash
ipfs name publish --key=course-ipns --lifetime=24h --ttl=5m /ipfs/$CID_V2

预期结果为发布成功消息,其中名称仍是原 IPNS 名称,目标仍为第二个 CID。--lifetime=24h 表示记录在签名时设定的有效期,不是文件保存期限;--ttl=5m 是缓存建议,不代表五分钟内所有节点必然更新。发布者需要在记录到期前重新发布有效记录,尤其是在长期无人维护的部署中。

排查远端解析旧版本时,建议按以下顺序检查:

  1. 在发布节点执行 ipfs name resolve --nocache /ipns/$IPNS_NAME,确认当前记录的目标路径。
  2. 检查发布节点是否在线,以及是否成功将记录发布到所用路由系统。
  3. 在另一台独立 Kubo 节点上解析相同名称,比较目标 CID;不要把同一节点的缓存命中当作跨节点验证。
  4. 如果远端仍返回旧记录,检查缓存、路由可达性和记录有效期,再等待传播或重新发布。

区分名称更新和内容可用性

IPNS 只负责把一个可验证的名称解析到目标路径,不负责永久存储目标内容。即使远端已经解析出新 CID,如果没有节点继续提供对应的数据块,ipfs cat 仍可能无法成功取回文件。

对需要长期访问的第二版内容,可以在持有文件的节点执行:

bash
ipfs pin add $CID_V2
ipfs pin ls --type=recursive $CID_V2

预期结果:第一条命令确认递归 Pin,第二条列出第二版 CID,并标明其为 recursive 类型。具体 CID 因文件内容而异。Pin 保护的是当前节点本地的数据块,不能替代跨节点复制或远端可用性测试。

最终验收应分别检查三件事:同一个 IPNS 名称能解析到新 CID;通过新 CID 能读取 version=2;在独立节点上也能发现记录并获取文件。只有这三项分别通过,才能确认名称更新、内容寻址和网络分发链路都符合预期。

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

目录与阅读设置

阅读设置

17

记录一个想法

发布 IPNS 名称并更新内容指向

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

登录哪都通