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:
ipfs id -f='<id>\n'预期输出:
<ID><ID> 表示当前节点的 Peer ID,实际值因节点而异。若提示无法连接 API,应先在另一个终端执行 ipfs daemon,保持进程运行后再重试。
创建两个文件版本,并分别导入 IPFS。这里采用文件根 CID,不使用目录包装,以便后续直接读取文件内容。
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预期输出:
两个版本 CID 是否不同:yes两个文件的字节不同,因此在相同导入参数下得到不同 CID。CID_V1 和 CID_V2 是当前 Shell 中的变量,后续命令需要在同一终端执行。实际 CID 字符串由文件内容及导入配置决定。
生成名称并发布第一个 CID
IPNS 使用密钥对应的身份标识作为可变名称。发布者用私钥签署 IPNS 记录,记录中包含指向内容的路径、序列号和有效期等信息;解析者依据公钥身份验证记录,而不是信任某个任意字符串。
创建专用密钥 course-ipns,避免修改节点默认身份所使用的 IPNS 名称:
ipfs key gen --type=ed25519 course-ipns预期输出为新密钥对应的 IPNS 名称,例如:
k51...上面的 k51... 仅表示名称格式,实际输出是完整的编码字符串。密钥名称必须在本地唯一;如果已存在同名密钥,命令会报错,不应直接删除正在使用的私钥。
使用新密钥发布第一个版本:
ipfs name publish --key=course-ipns --allow-offline /ipfs/$CID_V1预期输出形态如下,实际名称和 CID 不同:
Published to k51...: /ipfs/bafy...--key 选择签名密钥;--allow-offline 允许在没有足够网络连接时生成和保存本地记录,但不保证其他节点能够立即发现它。正常联网发布仍需要网络路由服务协助传播记录。

更新名称并验证解析结果
先读取密钥的完整 IPNS 名称,随后分别验证本地名称解析和内容读取。ipfs name resolve 返回的是 /ipfs/<CID> 路径,而不是文件正文。
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,第二条读取命令输出:
version=1现在保持密钥和名称不变,只把记录指向第二个 CID,再重新解析:
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;内容读取输出:
version=2这说明名称身份保持不变,而记录指向的不可变内容发生了变化。旧 CID 并不会因为 IPNS 更新而被改写或自动删除,仍可在对应数据块可用时通过原 CID 读取。

控制记录有效期与解析缓存
IPNS 更新不是对所有客户端的即时推送。发布者需要将新签名记录传播到路由系统,解析端还可能持有旧记录的缓存。因此本地解析成功不等于所有远端节点已经看到新版本。
常用发布参数如下:
| 参数 | 示例 | 作用 |
|---|---|---|
--key |
course-ipns |
指定签名密钥 |
--lifetime |
24h |
设置记录有效期 |
--ttl |
5m |
提供建议缓存时间 |
--allow-offline |
true |
允许离线发布,不保证网络传播 |
例如,将当前名称重新发布到第二个版本,并指定记录有效期和建议缓存时间:
ipfs name publish --key=course-ipns --lifetime=24h --ttl=5m /ipfs/$CID_V2预期结果为发布成功消息,其中名称仍是原 IPNS 名称,目标仍为第二个 CID。--lifetime=24h 表示记录在签名时设定的有效期,不是文件保存期限;--ttl=5m 是缓存建议,不代表五分钟内所有节点必然更新。发布者需要在记录到期前重新发布有效记录,尤其是在长期无人维护的部署中。
排查远端解析旧版本时,建议按以下顺序检查:
- 在发布节点执行
ipfs name resolve --nocache /ipns/$IPNS_NAME,确认当前记录的目标路径。 - 检查发布节点是否在线,以及是否成功将记录发布到所用路由系统。
- 在另一台独立 Kubo 节点上解析相同名称,比较目标 CID;不要把同一节点的缓存命中当作跨节点验证。
- 如果远端仍返回旧记录,检查缓存、路由可达性和记录有效期,再等待传播或重新发布。
区分名称更新和内容可用性
IPNS 只负责把一个可验证的名称解析到目标路径,不负责永久存储目标内容。即使远端已经解析出新 CID,如果没有节点继续提供对应的数据块,ipfs cat 仍可能无法成功取回文件。
对需要长期访问的第二版内容,可以在持有文件的节点执行:
ipfs pin add $CID_V2
ipfs pin ls --type=recursive $CID_V2预期结果:第一条命令确认递归 Pin,第二条列出第二版 CID,并标明其为 recursive 类型。具体 CID 因文件内容而异。Pin 保护的是当前节点本地的数据块,不能替代跨节点复制或远端可用性测试。
最终验收应分别检查三件事:同一个 IPNS 名称能解析到新 CID;通过新 CID 能读取 version=2;在独立节点上也能发现记录并获取文件。只有这三项分别通过,才能确认名称更新、内容寻址和网络分发链路都符合预期。