P2P 与分布式存储 / 系统课时
为通信实验选定 libp2p 组件
为通信实验选定 libp2p 组件
本地 P2P 通信实验不必一开始就接入 DHT、NAT 穿透和中继服务。先用 Go 版 libp2p 组合 Host、TCP Transport、Noise 安全连接和 Stream,再通过已知地址连接两个节点。完成后,你将得到一个可运行、可验证的双节点通信项目,并知道后续应该在哪里接入节点发现能力。
学习目标
- 区分 Host、Transport、Security、Stream 和 Discovery 的职责,理解它们之间的协作关系。
- 创建 Go Module,安装指定版本的 go-libp2p,确定本地实验所需的最小组件配置。
- 运行两个本地节点,验证安全连接、协议协商和双向 Stream 通信。
选择最小通信组件
libp2p 是用于构建 P2P 网络应用的模块化协议栈。Go 实现通过 github.com/libp2p/go-libp2p 提供节点创建、连接管理、协议协商和数据流接口。应用不必自行实现 TCP 连接复用、加密握手和节点身份管理。
本地实验选择以下组件:
| 组件 | 负责什么 | 本地实验的选择 |
|---|---|---|
| Host | 维护 Peer ID、监听地址、连接和协议处理器 | libp2p.New 创建两个 Host |
| Transport | 建立底层网络连接 | TCP,监听 127.0.0.1 |
| Security | 在连接上协商加密通道并验证对端身份 | Noise,协议 ID 为 /noise |
| Stream Multiplexer | 在一条连接中复用多个独立数据流 | yamux |
| Stream | 承载某个应用协议的双向字节数据 | 自定义 Echo 协议 |
| Discovery | 获取其他节点的 Peer ID 和可拨号地址 | 暂不启用自动发现,手动提供 peer.AddrInfo |
这里的 Host 不是传统客户端服务器架构中的专用服务端。两个 Host 都可以主动连接其他节点,也可以注册 Stream 处理器接收请求。节点身份由密钥对确定的 Peer ID 表示,地址负责告诉其他节点从哪里建立连接。

需要特别区分 Security 与 Stream:Noise 负责保护节点之间的连接,Stream 负责在已建立的连接上交换应用数据。应用可以在同一连接中打开多个 Stream,每个 Stream 根据协议 ID 交给相应的处理器。
创建 Go 项目并安装依赖
以下示例基于 go-libp2p v0.50.0,该版本要求 Go 1.26.0 或更高版本。先通过 go version 检查本地工具链,确保 Go 命令可用。示例适用于 Windows PowerShell、macOS Terminal 和 Linux Shell 中常见的 Go 开发环境。
新建一个独立目录,并固定依赖版本:
mkdir p2p-lab
cd p2p-lab
go mod init example.com/p2p-lab
go get github.com/libp2p/go-libp2p@v0.50.0
go list -m github.com/libp2p/go-libp2p预期输出中,最后一条命令应显示:
github.com/libp2p/go-libp2p v0.50.0同时应生成 go.mod 和 go.sum。前者记录模块声明、Go 版本要求和依赖关系,后者记录依赖模块的校验信息。首次下载依赖可能出现额外日志,不应把下载日志当作程序运行结果。
如果 go get 提示工具链版本不满足要求,先升级 Go,或者确认环境是否允许 Go 自动下载对应工具链。不要通过手动修改 go.mod 的 go 指令来绕过依赖版本要求。
本实验只需要直接依赖 go-libp2p。TCP、Noise 和 yamux 的实现已经包含在该模块中,不需要分别安装独立的第三方通信框架。可在官方 v0.50.0 默认配置源码中核对这些组件的构造入口。
编写最小双节点通信程序
在项目目录创建 main.go。程序在同一进程内启动节点 A 和节点 B,使用真实的本地 TCP 连接完成通信。为了让组件选择明确,代码显式配置 TCP、Noise 和 yamux,而不是完全依赖默认选项。
package main
import (
"bufio"
"context"
"fmt"
"log"
"time"
"github.com/libp2p/go-libp2p"
"github.com/libp2p/go-libp2p/core/host"
"github.com/libp2p/go-libp2p/core/network"
"github.com/libp2p/go-libp2p/core/peer"
"github.com/libp2p/go-libp2p/core/protocol"
"github.com/libp2p/go-libp2p/p2p/muxer/yamux"
"github.com/libp2p/go-libp2p/p2p/security/noise"
"github.com/libp2p/go-libp2p/p2p/transport/tcp"
)
const echoProtocol = protocol.ID("/anystack/echo/1.0.0")
func newNode() (host.Host, error) {
return libp2p.New(
libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"),
libp2p.Transport(tcp.NewTCPTransport),
libp2p.Security(noise.ID, noise.New),
libp2p.Muxer(yamux.ID, yamux.DefaultTransport),
libp2p.DisableRelay(),
)
}
func run() error {
a, err := newNode()
if err != nil {
return err
}
defer a.Close()
b, err := newNode()
if err != nil {
return err
}
defer b.Close()
// 节点A注册应用协议,接收并原样回应一行文本。
a.SetStreamHandler(echoProtocol, func(s network.Stream) {
defer s.Close()
msg, err := bufio.NewReader(s).ReadString('\n')
if err != nil {
_ = s.Reset()
return
}
if _, err := fmt.Fprintf(s, "echo: %s", msg); err != nil {
_ = s.Reset()
}
})
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
// 直接提供节点A的身份和地址,不依赖自动发现服务。
info := peer.AddrInfo{ID: a.ID(), Addrs: a.Addrs()}
if err := b.Connect(ctx, info); err != nil {
return err
}
// 在已建立的安全连接上协商Echo协议并打开Stream。
s, err := b.NewStream(ctx, a.ID(), echoProtocol)
if err != nil {
return err
}
defer s.Close()
if _, err := fmt.Fprintln(s, "hello p2p"); err != nil {
return err
}
reply, err := bufio.NewReader(s).ReadString('\n')
if err != nil {
return err
}
fmt.Print("收到:", reply)
return nil
}
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}这个程序有三个关键设置。
第一,/ip4/127.0.0.1/tcp/0 是 libp2p Multiaddr。127.0.0.1 将监听范围限制在本机,末尾端口 0 让操作系统分配可用端口,因此两个节点不会因为固定端口相同而冲突。
第二,libp2p.Security(noise.ID, noise.New) 指定使用 Noise 安全传输。节点会利用各自的身份密钥参与安全握手,双方完成加密和对端身份验证后才能交换应用 Stream 数据。不要使用 libp2p.NoSecurity 代替这项配置。
第三,/anystack/echo/1.0.0 是实验自定义的应用协议 ID。接收方的 SetStreamHandler 和发送方的 NewStream 使用相同 ID,才能协商到正确的处理器。这个字符串不是 TCP 端口,也不是 Peer ID。
运行并验证通信结果
保存 main.go 后,在项目目录执行依赖整理与程序运行:
go mod tidy
go run .预期输出:
收到:echo: hello p2p这个结果证明了四件事:两个 Host 已创建;节点 B 通过节点 A 的 Peer ID 和地址建立连接;两端协商了兼容的安全连接及 Stream 协议;节点 A 收到消息后通过同一 Stream 返回了数据。
这里没有启动专用中心服务器。节点 A 虽然承担了本次 Echo 请求的接收方角色,但它本身仍是普通 P2P 节点,之后也可以主动调用 NewStream 向其他节点发起请求。
还要确认实验边界:这次连接使用的是程序直接传递的 peer.AddrInfo,不是通过 mDNS 或 DHT 自动发现。成功执行 Echo 也不能证明节点已经具备跨公网、穿透 NAT 或通过中继通信的能力。
排查配置错误并确定扩展边界
如果未得到预期输出,按失败阶段排查,不要同时改动所有组件。
| 现象 | 优先检查 | 修复方式 |
|---|---|---|
| Go 拒绝构建依赖 | Go 工具链版本是否满足模块要求 | 安装 Go 1.26.0 或更新版本 |
Connect 返回错误 |
目标 Peer ID、监听地址及节点是否仍在运行 | 确认 info.ID、info.Addrs 来自当前存活的 Host |
NewStream 协商失败 |
双方应用协议 ID 是否一致 | 统一使用 /anystack/echo/1.0.0 |
| 接收方一直等待消息 | 是否发送换行符、Stream 是否被提前关闭 | 保留 fmt.Fprintln 和按行读取逻辑 |
| 换成另一台机器后无法连接 | 是否仍使用回环地址 127.0.0.1 |
使用对端实际可达地址,并检查防火墙规则 |
本地配置还有两项需要明确的限制。
- 节点身份:未通过
libp2p.Identity指定持久化私钥时,程序每次启动都会生成新的节点身份,因此 Peer ID 可能改变。正式应用应安全保存身份私钥,并对可信对端建立授权策略;Noise 的身份验证不等于业务授权。 - 节点发现:当前使用静态
peer.AddrInfo,只适合已知节点的小型实验。同一局域网内可以考虑 mDNS;需要较大范围的节点发现时,可以评估 Kademlia DHT 与引导节点,但它们都不是完成本次 Echo 通信的必要条件。
最终保留的最小配置是两个 Host、一种 TCP Transport、一种 Noise Security、一种 yamux 多路复用器和一个自定义 Stream 协议。先确认这一组合能够稳定通信,再分别增加自动发现、地址管理或跨网连接能力,才容易判断新增组件引入了什么问题。