P2P 与分布式存储 / 系统课时
观察 libp2p 对等连接的建立
观察 libp2p 对等连接的建立
运行中的 Kubo 节点可能同时连接多个 IPFS Peer,但发现节点、建立传输连接和交换文件区块并不是同一件事。本课通过两个本地 Kubo 节点建立连接,读取 Peer ID、Multiaddr 和连接信息,观察 libp2p 的传输与连接复用,并判断连接成功究竟证明了什么。
学习目标
- 使用 Kubo 命令建立并检查两个节点之间的 libp2p 连接。
- 识别 Peer ID、Multiaddr、传输协议和连接方向的含义。
- 区分传输连接、协议流与 Bitswap 区块交换,避免误判节点状态。
准备两个独立的 Kubo 节点
实验使用两个独立仓库模拟 Peer A 和 Peer B。适用于支持 ipfs swarm 命令的 Kubo 版本,例如 Kubo 0.30.x。不同版本的默认传输协议、输出字段和监听地址可能不同,实验以实际命令输出为准。
先确认已安装 Kubo,并在两个终端分别使用独立的仓库路径。以下命令适用于 Linux 或 macOS 的 Bash;不要对已有生产仓库重新执行初始化。
终端 A:
# 使用独立仓库,避免覆盖默认节点配置
export IPFS_PATH="$HOME/ipfs-lab-a"
mkdir -p "$IPFS_PATH"
ipfs init
ipfs config Addresses.Swarm --json '["/ip4/127.0.0.1/tcp/4101"]'
ipfs config Addresses.API --json '"/ip4/127.0.0.1/tcp/5101"'
ipfs config Addresses.Gateway --json '"/ip4/127.0.0.1/tcp/8181"'
ipfs daemon --offline终端 B:
# B 必须使用另一套仓库和监听端口
export IPFS_PATH="$HOME/ipfs-lab-b"
mkdir -p "$IPFS_PATH"
ipfs init
ipfs config Addresses.Swarm --json '["/ip4/127.0.0.1/tcp/4102"]'
ipfs config Addresses.API --json '"/ip4/127.0.0.1/tcp/5102"'
ipfs config Addresses.Gateway --json '"/ip4/127.0.0.1/tcp/8182"'
ipfs daemon --offline预期结果:两个终端均保持运行,最终显示节点已准备就绪的提示,例如 Daemon is ready。初始化生成的 Peer ID、仓库路径和启动耗时因环境而异。
这里使用 --offline 避免节点连接公共 IPFS 网络,方便只观察指定的本地连接。该模式仍允许本机显式拨号。两个节点的 Swarm、API 和 Gateway 端口必须分别避开冲突;其中 API 端口只供本地命令行管理,不是 Peer 之间交换数据的端口。
从 Peer ID 和 Multiaddr 建立连接
保留两个守护进程运行,再打开两个新的终端执行查询。命令必须指向对应仓库,否则可能误连默认节点。
终端 A:
export IPFS_PATH="$HOME/ipfs-lab-a"
# 读取 A 的节点身份
ipfs id -f='<id>\n'终端 B:
export IPFS_PATH="$HOME/ipfs-lab-b"
# 读取 B 的节点身份
ipfs id -f='<id>\n'预期输出:每个终端各返回一行 Peer ID,两个值应当不同,例如以 12D3KooW 开头的标识。实际 ID 由初始化时生成的密钥决定,不能直接复制示例标识作为连接目标。
记下 B 的真实 Peer ID,返回终端 A,执行以下命令。将 <PEER_B_ID> 替换为 B 的完整标识。
export IPFS_PATH="$HOME/ipfs-lab-a"
# 显式拨号到 B 的 TCP 监听地址
ipfs swarm connect /ip4/127.0.0.1/tcp/4102/p2p/<PEER_B_ID>
ipfs swarm peers -v预期结果:连接命令报告成功连接到 B;ipfs swarm peers -v 列出 B 的地址、Peer ID 和连接方向等信息。具体行格式随 Kubo 版本变化。
Multiaddr 是分层描述网络地址的格式。上述地址可以拆成以下部分:
| 地址片段 | 含义 |
|---|---|
/ip4/127.0.0.1 |
使用 IPv4 回环地址 |
/tcp/4102 |
通过 TCP 连接 B 的监听端口 |
/p2p/<PEER_B_ID> |
目标节点的 Peer ID,用于识别远端身份 |
Peer ID 表示节点身份,而 IP 地址和端口表示本次可用的网络位置。同一个 Peer ID 可以对应多个可达 Multiaddr;节点地址改变不必然意味着节点身份改变。libp2p 会在建立安全连接时验证远端身份,不能仅凭目标 IP 地址认定连接对象正确。

观察传输连接与连接方向
建立连接后,可以从 A 和 B 两侧查看同一条连接。下面使用 Kubo 的 Swarm 查询接口。
终端 A:
export IPFS_PATH="$HOME/ipfs-lab-a"
# 查看详细连接信息与传输地址
ipfs swarm peers -v
ipfs swarm addrs预期结果:swarm peers -v 显示 B 的连接记录,通常包含远端地址、Peer ID、连接方向和连接延迟等信息;swarm addrs 展示已知 Peer 的地址信息。不同版本的输出格式可能有所不同。
终端 B 执行:
export IPFS_PATH="$HOME/ipfs-lab-b"
ipfs swarm peers -v预期结果:B 能看到 A 的连接记录。在单条由 A 主动发起的 TCP 连接上,A 通常显示出站方向,B 显示入站方向;如果存在额外连接或连接迁移,应以实际记录为准。
观察时需要区分三个概念:
- 监听地址:节点允许其他 Peer 尝试连接的位置,可使用
ipfs swarm addrs listen查看。 - 已知地址:节点地址簿中记录的候选地址,不保证当前可达,也不代表已经连接。
- 活动连接:当前已经建立的 Swarm 连接,可通过
ipfs swarm peers检查。
现代 libp2p 可以支持 TCP、QUIC 等不同传输方式,具体取决于 Kubo 版本与配置。TCP 连接的 Multiaddr 常出现 /tcp/;QUIC v1 通常使用 /udp/<PORT>/quic-v1。本实验明确使用 TCP,不能因为系统支持 QUIC 就推断当前连接走的是 QUIC。
理解连接复用与协议流
libp2p 在传输连接之上提供安全通信和流复用能力。以 TCP 为例,一条底层连接可以承载多个逻辑协议流,而不必让每种应用协议都单独建立 TCP 连接。
Kubo 使用的具体安全协议、流复用器和应用协议取决于版本与双方协商结果。常见的安全协议包括 Noise,流复用机制包括 yamux;Bitswap、Identify 等应用协议可以通过各自的逻辑流工作。

可以使用 ipfs swarm stats 查看节点连接的统计信息,并通过 ipfs stats bitswap 观察 Bitswap 层的状态:
export IPFS_PATH="$HOME/ipfs-lab-a"
# 分别观察Swarm连接统计和Bitswap状态
ipfs swarm stats
ipfs stats bitswap预期结果:第一条命令输出 Swarm 连接统计信息;第二条命令输出 Bitswap 统计信息,例如区块接收和发送计数。字段名称及统计范围以当前版本为准。仅建立连接而未请求内容时,不应预期区块接收计数必然增加。
这些统计命令不能完整列出所有实时逻辑流,也不能单独证明 Noise 或 yamux 已经被选用。需要确认具体协商协议时,应结合当前 Kubo 版本文档及 libp2p 调试日志,必要时在受控实验环境中抓包分析。
验证连接断开与恢复
为了确认观察到的是活动连接,而不是仅保存在地址簿中的 Peer 信息,可以主动断开 B,再检查 A 的连接列表。
先在终端 A 执行断开命令,将占位符替换为 B 的真实 Peer ID:
export IPFS_PATH="$HOME/ipfs-lab-a"
# 断开指定Peer的活动连接
ipfs swarm disconnect /p2p/<PEER_B_ID>
ipfs swarm peers预期结果:断开命令报告成功;随后活动连接列表中不再包含 B。在其他自动拨号机制存在时,连接可能重新建立,因此需要立即检查并结合实验模式判断。
重新连接:
export IPFS_PATH="$HOME/ipfs-lab-a"
ipfs swarm connect /ip4/127.0.0.1/tcp/4102/p2p/<PEER_B_ID>
ipfs swarm peers预期结果:重新连接成功,活动 Peer 列表再次包含 B。
如果连接失败,按以下顺序排查:
- 在 B 的终端确认守护进程仍在运行,并用
ipfs swarm addrs listen检查 TCP 监听端口是否为 4102。 - 确认连接命令中的 Peer ID 与 B 的
ipfs id输出一致,避免把节点 A 的身份误写为 B。 - 确认两个终端使用不同的
IPFS_PATH,且没有其他进程占用 4101、4102、5101、5102 等实验端口。 - 跨主机测试时,将回环地址替换为对端真实可达地址,并检查传输协议、主机防火墙和 NAT 映射。
实验完成后,使用 Ctrl+C 停止两个守护进程。不要直接删除尚在运行的仓库目录。
最终应能独立核实三个事实:两个 Peer ID 不同;A 能通过 B 的 Multiaddr 建立活动连接;断开后活动连接记录消失,重新拨号后恢复。libp2p 连接是后续内容发现与区块交换的通信基础,但内容提供者发现、Bitswap 请求和 CID 数据校验仍需分别验证。