P2P 与分布式存储 / 系统课时
通过 DNSLink 绑定内容域名
通过 DNSLink 绑定内容域名
IPFS 的 CID 能精确标识内容,但文件更新后 CID 通常会改变,不适合作为长期对外公布的固定入口。本课使用 DNSLink 将可控域名映射到 IPFS 或 IPNS 路径,完成 DNS 记录配置、命令行验证和更新测试,并明确 DNSLink 对传统 DNS 服务的依赖。
学习目标
- 理解
_dnslinkTXT 记录的格式,以及域名解析到 IPFS 或 IPNS 内容的过程。 - 使用真实域名或本地 DNS 模拟环境配置并验证 DNSLink。
- 区分 DNSLink、CID 和 IPNS 的更新方式,识别缓存与 DNS 安全边界。
DNSLink 记录如何指向内容
DNSLink 使用 DNS TXT 记录发布内容路径。假设拥有域名 example.com,可以在 _dnslink.example.com 下添加 TXT 记录,将域名指向指定 CID。
记录名称和记录值分别为:
| 字段 | 示例 | 作用 |
|---|---|---|
| 记录类型 | TXT | 存放 DNSLink 文本 |
| 主机名 | _dnslink.example.com |
DNSLink 查询入口 |
| 记录值 | dnslink=/ipfs/<CID> |
指向不可变 IPFS 内容 |
| 另一种记录值 | dnslink=/ipns/<NAME> |
指向可解析的 IPNS 名称 |
| TTL | 300 秒 | 建议的 DNS 缓存时间 |
其中 <CID> 需要替换为实际导入内容后得到的 CID,<NAME> 则需要替换为真实 IPNS 名称。尖括号只是教学占位符,不能直接作为生产记录值使用。
当客户端访问 /ipns/example.com 时,支持 DNSLink 的 IPFS 名称解析器可以查询 _dnslink.example.com 的 TXT 记录,取得目标路径,再继续读取 IPFS 内容或解析 IPNS 名称。

配置可控域名的 TXT 记录
以下操作适用于具有 DNS 记录管理权限的域名,以及已安装并运行 Kubo 的环境。示例使用 example.com 作为文档域名,实际操作必须替换为自己控制的域名。
先在运行中的 Kubo 节点创建测试文件并导入 IPFS:
printf 'DNSLink version 1\n' > dnslink-demo.txt
ipfs add -Q dnslink-demo.txt预期输出:
<CID><CID> 表示命令实际返回的内容标识,具体值由文件字节和导入参数决定。-Q 表示只输出最终 CID。
随后登录域名的权威 DNS 服务商控制台,添加一条 TXT 记录:
- 进入域名
example.com的 DNS 记录管理页面。 - 新建 TXT 记录,主机名填写
_dnslink;如果服务商要求完整域名,则填写_dnslink.example.com。 - 记录值填写
dnslink=/ipfs/<CID>,将<CID>替换为刚才得到的真实值。 - TTL 设置为 300 秒;如果服务商有最低 TTL 限制,采用允许的值。
- 保存记录并等待 DNS 服务生效。
部分控制台会自动补全域名后缀。若输入完整域名导致生成 _dnslink.example.com.example.com,应改用相对主机名 _dnslink。
可以使用 dig 查询记录。在 Linux 上通常可通过系统包管理器安装 dnsutils 或 bind-utils;macOS 常见环境也提供 dig。Windows 可使用支持 DNS TXT 查询的工具。
dig TXT _dnslink.example.com +short配置正确且 DNS 缓存已更新时,预期输出形式为:
"dnslink=/ipfs/<CID>"输出中的 <CID> 应为实际记录值。若没有输出,先检查记录是否提交到正确的 DNS 区域,再检查权威 DNS 与递归解析器是否已同步。TTL 不是保证全球解析器在指定秒数内全部更新的承诺。
验证域名解析与文件读取
DNS TXT 查询只能证明记录可见,不能证明 Kubo 能解析 DNSLink 或取回文件。应继续使用 IPFS 命令验证完整链路。
ipfs resolve /ipns/example.com
ipfs cat /ipns/example.com当 TXT 记录指向刚才导入的文件,且内容可取回时,预期输出依次为:
/ipfs/<CID>
DNSLink version 1这里的 <CID> 代表真实内容标识,ipfs cat 的第二行是文件原始内容。ipfs resolve 负责解析名称,ipfs cat 进一步读取数据,两者检查的层次不同。
如果不拥有公网域名,可以通过本地模拟 DNS 理解记录结构。例如使用支持 TXT 记录的本地权威 DNS 服务,将 _dnslink.test.example 映射到测试 CID,再使用 dig 指定本地 DNS 服务地址查询。
dig @127.0.0.1 -p 5353 TXT _dnslink.test.example +short此命令依赖事先在本机 UDP 5353 端口启动并配置好的 DNS 服务,不会自动创建模拟记录。预期结果是返回配置的 dnslink=/ipfs/<CID> TXT 值;若服务没有启动,则会出现查询超时或连接失败。
更新 DNSLink 指向的内容
DNSLink 可以通过修改 TXT 记录更新域名对应的内容,而无需更改用户使用的域名。
假设当前记录指向 CID A,文件内容为 DNSLink version 1。现在将文件改为第二版:
printf 'DNSLink version 2\n' > dnslink-demo.txt
ipfs add -Q dnslink-demo.txt预期输出:
<CID_B>由于文件内容改变,新 CID 通常不同于旧 CID。将 DNS TXT 记录从 dnslink=/ipfs/<CID_A> 更新为 dnslink=/ipfs/<CID_B>,再执行查询与读取验证。
dig TXT _dnslink.example.com +short
ipfs cat /ipns/example.com当 DNS 缓存已刷新、记录正确且新版内容可取回时,预期输出形式为:
"dnslink=/ipfs/<CID_B>"
DNSLink version 2更新期间,不同递归 DNS 解析器可能暂时返回不同版本。需要平滑切换时,应先确保新版内容在网络中可获取,再修改 TXT 记录,并在至少一个旧 TTL 周期内保留旧版内容。具体保留时间还需考虑解析器缓存行为。

如果希望 DNS 记录长期保持不变,也可以让 TXT 记录指向 /ipns/<NAME>,再通过发布新的 IPNS 记录更新其目标 CID。不过这会增加一次名称解析,并引入 IPNS 记录有效期、发布和缓存等管理要求。
识别 DNS 依赖与常见故障
DNSLink 的可变性依赖传统 DNS 基础设施。域名注册状态、权威 DNS 服务、递归缓存以及 TXT 记录的完整性,都可能影响解析结果。
| 现象 | 优先检查 | 处理方式 |
|---|---|---|
dig 没有返回 TXT |
主机名、DNS 区域、记录是否生效 | 核对 _dnslink 前缀和权威 DNS 记录 |
TXT 正确但 ipfs resolve 失败 |
Kubo 使用的 DNS 解析环境、记录语法 | 检查 dnslink= 前缀及 /ipfs/ 或 /ipns/ 路径 |
| 名称解析成功但读取失败 | 内容提供者和区块可用性 | 检查提供节点在线状态及内容是否保留 |
| 更新后仍读取旧版 | 递归 DNS 缓存、名称解析缓存 | 等待缓存刷新并检查不同解析器的结果 |
| 域名被错误指向其他 CID | DNS 管理权限、记录变更、DNS 安全配置 | 审计变更记录并恢复正确映射 |
CID 可以帮助客户端校验获取的数据是否匹配指定内容标识,但不能单独证明 DNS 返回的 CID 就是域名所有者期望发布的版本。DNSLink 的映射真实性依赖 DNS 信任链;DNSSEC 可以为正确配置并完成验证的 DNS 记录提供认证保护,但并非所有客户端解析路径都执行 DNSSEC 验证。
在生产环境中,应保护 DNS 管理账号、限制记录修改权限、监控 _dnslink TXT 记录变化,并保证目标内容有足够的副本。这样既能使用固定域名发布更新内容,也能分别定位名称解析故障和内容获取故障。