P2P 与分布式存储 / 系统课时
Multiaddr 如何描述拨号地址
Multiaddr 如何描述拨号地址
排查 libp2p 拨号失败时,需要把目标地址拆成主机位置、传输协议和节点身份,再分清本机监听地址、对外公告地址与实际可拨号地址。掌握 Multiaddr 的组成规则后,你可以读懂 TCP、QUIC 和 DNS 地址,并用解析器检查配置,缩小连接失败的排查范围。
学习目标
- 识别
ip4、ip6、dns4、tcp、udp、quic-v1和p2p等地址组件。 - 区分监听地址、公告地址与实际可拨号地址,解释 NAT 对地址的影响。
- 使用 Multiaddr 解析器检查地址结构,并定位常见配置错误。
读懂 Multiaddr 的协议组件
Multiaddr 是一种可组合的网络地址表达方式。普通 TCP 地址 192.168.1.20:4001 只体现 IP 和端口,而 Multiaddr 将协议类型也写入字符串:/ip4/192.168.1.20/tcp/4001。
从左向右读取时,先确定网络位置,再确定使用什么传输协议,最后可附加目标节点身份。各组件有自己的参数规则:
| 组件 | 含义 | 典型写法 |
|---|---|---|
ip4 |
IPv4 地址 | /ip4/192.168.1.20 |
ip6 |
IPv6 地址 | /ip6/::1 |
dns4 |
解析为 IPv4 的 DNS 名称 | /dns4/node.example.org |
dns6 |
解析为 IPv6 的 DNS 名称 | /dns6/node.example.org |
tcp |
TCP 传输端口 | /tcp/4001 |
udp |
UDP 传输端口 | /udp/4001 |
quic-v1 |
基于 UDP 的 QUIC v1 传输 | /udp/4001/quic-v1 |
p2p |
libp2p 节点身份 | /p2p/<PeerID> |
其中 <PeerID> 是说明用占位符,实际配置时必须替换为完整有效的 Peer ID。ip4、tcp、udp 等组件后面需要具体值,而 quic-v1 自身不再接端口号。
下面三种地址代表不同的连接方式:
- TCP:
/ip4/192.168.1.20/tcp/4001,通过 IPv4 地址和 TCP 端口访问。 - DNS + TCP:
/dns4/node.example.org/tcp/4001,先解析域名,再建立 TCP 连接。 - QUIC v1:
/ip4/192.168.1.20/udp/4001/quic-v1,通过 UDP 端口建立 QUIC 连接。
node.example.org 是示例域名,不代表已经部署服务。普通的 /udp/4001 也不等于 QUIC:只有正确声明 /quic-v1 并配置支持该传输的 libp2p 实现,才能按 QUIC 方式拨号。
Peer ID 如何与网络位置组合
IP 地址、端口和 DNS 名称解决的是到哪里连接,Peer ID 解决的是希望连接哪个节点。一个 libp2p 节点可以拥有多个网络地址,但其 Peer ID 由节点公钥身份决定,不应随着普通的 IP 地址变化而改变。
完整拨号地址可采用以下结构:
/ip4/192.0.2.10/tcp/4001/p2p/<PeerID>
这里的 192.0.2.10 属于文档示例地址段,<PeerID> 需要替换为目标节点提供的真实身份标识。这是一条地址模板,不是可直接连接的生产地址。
节点拨号时通常依次完成这些工作:
- 从 Multiaddr 提取 IP 或 DNS 目标、传输类型和端口。
- 选择本地已安装且支持该地址的传输实现,尝试建立连接。
- 使用 libp2p 配置的安全传输协议完成身份认证与加密协商;QUIC v1 使用其自身的 TLS 1.3 安全机制。
- 将认证得到的远端身份与期望的 Peer ID 对比;身份不符时不能把连接当作目标节点的有效连接。
区分监听地址、公告地址与可拨号地址
同一个节点可能同时拥有多个地址,它们分别用于绑定本地网络接口、向其他节点公布连接入口,以及供远端实际建立连接。
假设节点 B 位于家庭网络,内网 IP 为 192.168.1.20,在 TCP 4001 端口监听;路由器对外使用公网端口 45001,并转发到这台主机。
| 地址类别 | 示例 | 实际用途 |
|---|---|---|
| 监听地址 | /ip4/0.0.0.0/tcp/4001 |
绑定本机所有 IPv4 网络接口 |
| 内网地址 | /ip4/192.168.1.20/tcp/4001 |
同一可达内网内的节点使用 |
| 公告地址 | /ip4/203.0.113.9/tcp/45001 |
告知外部节点应尝试的公网入口 |
| 实际拨号地址 | 公告地址加目标 /p2p/<PeerID> |
远端按照位置和身份连接目标节点 |
这里的 203.0.113.9 是文档保留地址,仅用于演示公网入口;真实部署必须换成实际公网地址或有效域名。表中的最终拨号地址还需要替换为真实 Peer ID。

图中的关键是端口映射:外部访问 45001,内部服务仍监听 4001。若路由器没有建立映射,或者防火墙拒绝入站 TCP 连接,即使公告地址的语法完全正确,远端仍可能拨号失败。
不能直接将 0.0.0.0 当作对外地址,也不能把 192.168.1.20 公告给普通公网节点并假设它们可以访问。公网可拨号性需要通过远端实际连接测试或 AutoNAT 等机制验证;位于无法开放入站端口的网络中时,可考虑 libp2p Relay 或打洞机制。
用 Multiaddr 解析器检查地址
手动按斜杠拆分字符串容易漏掉不带参数的组件,也无法完整检查协议值是否合法。可以直接使用官方 JavaScript Multiaddr 实现解析地址。
以下示例适用于 Node.js 22,并使用 @multiformats/multiaddr 13.0.3。先在终端创建实验目录并安装依赖:
mkdir multiaddr-check
cd multiaddr-check
npm init -y
npm install @multiformats/multiaddr@13.0.3预期结果:命令正常结束,当前目录出现 package.json、package-lock.json 和 node_modules。npm 安装日志中的包数量及审计信息会随环境变化。
创建 check.mjs 文件,输入下面的完整代码:
import { multiaddr } from '@multiformats/multiaddr'
const addresses = [
'/ip4/127.0.0.1/tcp/4001',
'/dns4/node.example.org/tcp/4001',
'/ip4/127.0.0.1/udp/4001/quic-v1'
]
// 使用协议库解析地址,避免手动切分时丢失无参数组件。
for (const address of addresses) {
const components = multiaddr(address).getComponents()
const labels = components.map(({ name, value }) =>
value === undefined ? name : `${name}=${value}`
)
// 只验证结构,不进行 DNS 查询或网络拨号。
console.log(labels.join(' | '))
}在同一个目录执行:
node check.mjs预期输出:
ip4=127.0.0.1 | tcp=4001
dns4=node.example.org | tcp=4001
ip4=127.0.0.1 | udp=4001 | quic-v1可以看到,getComponents() 会按顺序返回协议名及其参数值,quic-v1 则只有协议名。把第三条地址的 4001 改成 70000,解析器应拒绝这个超出有效端口范围的地址。
但解析成功只说明地址符合解析器支持的结构与值规则,不等于地址已经存在、端口处于监听状态、QUIC 传输已配置,或者目标节点身份验证能够通过。
按故障现象检查配置
实际排查时,先确认地址是否能解析,再检查传输实现和网络可达性,最后检查身份是否正确。这样能避免把 DNS、NAT 和 Peer ID 问题混在一起。
| 现象 | 常见错误 | 检查与修正 |
|---|---|---|
| 远端始终无法连接 | 公告了 0.0.0.0 或 127.0.0.1 |
改用远端可访问的真实 IP 或 DNS 名称 |
| 同一局域网能连,公网不能连 | 公告私网地址或缺少 NAT 映射 | 检查公网 IP、端口转发和防火墙入站规则 |
| TCP 可连接,QUIC 不可连接 | 只开放 TCP 端口或未启用 QUIC | 确认 /udp/<端口>/quic-v1、UDP 放行和 QUIC 传输支持 |
| 域名形式无法连接 | DNS 记录未解析到正确地址 | 核对 dns4 对应的 A 记录或 dns6 对应的 AAAA 记录 |
| 能建立底层连接但身份认证失败 | /p2p/ 后的 Peer ID 与远端身份不一致 |
从可信来源重新获取目标 Peer ID,核对节点身份 |
| 地址解析报错 | 协议名拼写、参数格式或端口值错误 | 使用解析器逐段检查,不把 quic-v1 误写为带参数协议 |
例如,一个节点监听 TCP 4001,但公告的地址写成 /ip4/203.0.113.9/udp/4001/quic-v1。即便真实公网地址可用,远端也会尝试 QUIC 而不是 TCP;如果节点没有提供对应的 QUIC 服务,拨号仍会失败。正确做法是让公告地址中的传输协议和外部端口与实际开放的服务保持一致。
还要注意,同一节点可以同时公布 TCP 和 QUIC 两类地址,不需要强制只保留一种。每条地址都应独立确认协议支持、端口可达以及身份匹配。
Multiaddr 的配置应同时满足三个条件:地址结构有效、网络入口实际可达、远端身份与预期一致。三项分别验证,比仅检查字符串是否能解析更能准确判断 libp2p 拨号失败的原因。