go-libp2p 实战:用 mDNS 实现局域网自动发现与 P2P 聊天应用
go-libp2p 实战:用 mDNS 实现局域网自动发现与 P2P 聊天应用
导读
本文围绕 go-libp2p 官方示例 chat-with-mdns 展开,完整讲解如何构建一个在同一局域网(LAN)内零配置自动发现对端、并建立 P2P 聊天流的应用。你将掌握 libp2p Host 的构建与监听、SetStreamHandler 协议流处理、NewMdnsService 发现服务的使用,以及 peer 连接与 NewStream 的完整调用链,并深入理解 mDNS 发现服务的源码实现细节(TXT 记录广播、.local 域名过滤、地址适用性判定等),具备直接复制改造到自有项目的实战能力。
示例背景:与 rendezvous 方案的差异
示例 README 开篇即说明,本项目是 chat-with-rendezvous 的姊妹篇("heavily influenced by (and shamelessly copied from)")。两者的目标一致——让两个 libp2p 节点互相发现并建立聊天流,但发现机制截然不同:
chat-with-rendezvous借助 Kademlia DHT 与 rendezvous 字符串(类似"在埃菲尔铁塔碰头"),需要 bootstrap 节点、跨网络可达性,适用于公网或广域网场景;chat-with-mdns借助 mDNS(组播 DNS,RFC 6762),只在本机局域网内组播广播自身地址,适用于"多台设备在同一 WiFi / 有线局域网内自动互相发现"的场景(见 main.go 的帮助文本:"mDNS is great when you have multiple peers in local LAN")。
也就是说:局域网内不需要任何中心节点,两台设备只要在同一网段,启动程序后即可自动发现对方并开始聊天。
一、构建示例
在 examples/chat-with-mdns 目录下执行:
go get -v -d ./...
go build
第一条命令下载并解析示例依赖(输出到模块缓存),第二条在当前目录编译出可执行文件 chat-with-mdns。构建成功后,需要开两个不同的终端窗口,分别运行:
./chat-with-mdns -port 6666
./chat-with-mdns -port 6668
两个节点会在同一局域网内通过 mDNS 互相发现。示例程序默认监听 0.0.0.0(即所有网络接口,flags.go),因此端口分开即可避免冲突。启动后控制台会打印各自的 Multiaddress(形如 /ip4/192.168.x.x/tcp/6666/p2p/<PeerID>),随后任意一端输入文本并回车,另一端就会以绿色字体显示收到的消息。
二、命令行参数说明
示例将全部可调参数集中在 flags.go 中通过标准库 flag 包解析,完整参数如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
-rendezvous |
meetme |
用于标识节点组的唯一字符串,同组节点共享该值;好友之间约定同一个字符串即可互相发现 |
-host |
0.0.0.0 |
节点监听地址,0.0.0.0 表示监听所有网络接口 |
-pid |
/chat/1.1.0 |
流协议 ID,作为流头部标识,两端必须一致 |
-port |
0 |
监听端口,0 表示让系统随机分配一个空闲端口 |
可以用更完整的形式启动,例如:
./chat-with-mdns -host 0.0.0.0 -port 6666 -rendezvous mygroup -pid /chat/1.1.0
程序还内置了 -help 开关(main.go),打印上述用法说明。
值得注意的细节:-rendezvous 在 mDNS 场景下作为服务名(Service Name)传入 NewMdnsService。从源码 p2p/discovery/mdns/mdns.go 可见,若传入空字符串则回退到默认服务名 _p2p._udp;示例默认值 meetme 与 chat-with-rendezvous 保持一致,两个示例共用同一套"碰头暗号"语义,只是广播介质从 DHT 换成了局域网组播。
三、工作原理:四个核心步骤
结合 main.go 的完整代码,整个程序可拆解为以下四步。
步骤 1:配置并创建 libp2p Host
ctx := context.Background()
r := rand.Reader
// Creates a new RSA key pair for this host.
prvKey, _, err := crypto.GenerateKeyPairWithReader(crypto.RSA, 2048, r)
if err != nil {
panic(err)
}
// 0.0.0.0 will listen on any interface device.
sourceMultiAddr, _ := multiaddr.NewMultiaddr(fmt.Sprintf("/ip4/%s/tcp/%d", cfg.listenHost, cfg.listenPort))
// libp2p.New constructs a new libp2p Host.
// Other options can be added here.
host, err := libp2p.New(
libp2p.ListenAddrs(sourceMultiAddr),
libp2p.Identity(prvKey),
)
if err != nil {
panic(err)
}
libp2p.New 是 go-libp2p 的节点构造函数(libp2p.go)。它内部等价于 NewWithoutDefaults(append(opts, FallbackDefaults)...),即在不显式指定的情况下自动套用合理默认值:默认使用 TCP、WebSocket、QUIC 传输协议;默认 yamux 多路复用;默认 noise/TLS 加密;未指定身份时自动生成随机 Ed25519 密钥对并派生 PeerID。
示例额外传入了两个选项:
libp2p.ListenAddrs(sourceMultiAddr):显式指定监听地址(options.go),将/ip4/<host>/tcp/<port>加入cfg.ListenAddrs;libp2p.Identity(prvKey):显式指定节点身份(options.go),这里手动生成了 2048 位 RSA 密钥对(crypto.GenerateKeyPairWithReader),使节点拥有稳定、可复现的 PeerID,方便日志与调试。
步骤 2:注册流处理器 SetStreamHandler
// Set a function as stream handler.
// This function is called when a peer initiates a connection and starts a stream with this peer.
host.SetStreamHandler(protocol.ID(cfg.ProtocolID), handleStream)
SetStreamHandler 在 Host 的协议多路复用器(Mux)上注册指定协议 ID 的处理函数(接口定义见 core/host/host.go),等价于 host.Mux().SetHandler(proto, handler)。当远端节点向本地发起连接并打开流时,该处理器会被调用。
处理器 handleStream 的核心逻辑(main.go):
func handleStream(stream network.Stream) {
fmt.Println("Got a new stream!")
// Create a buffer stream for non-blocking read and write.
rw := bufio.NewReadWriter(bufio.NewReader(stream), bufio.NewWriter(stream))
go readData(rw)
go writeData(rw)
// 'stream' will stay open until you close it (or the other side closes it).
}
关键点:
- 用
bufio.NewReadWriter为network.Stream包一层带缓冲的读写器; readData/writeData以 goroutine 并发运行,实现"边读边写"的非阻塞式交互;- 流会一直保持打开,直到某一端主动关闭或连接断开——这是 libp2p stream 的生命周期模型。
读写两个 goroutine 的实现(main.go):
func readData(rw *bufio.ReadWriter) {
for {
str, err := rw.ReadString('\n')
if err != nil {
fmt.Println("Error reading from buffer")
panic(err)
}
if str == "" {
return
}
if str != "\n" {
// Green console colour: \x1b[32m
// Reset console colour: \x1b[0m
fmt.Printf("\x1b[32m%s\x1b[0m> ", str)
}
}
}
func writeData(rw *bufio.ReadWriter) {
stdReader := bufio.NewReader(os.Stdin)
for {
fmt.Print("> ")
sendData, err := stdReader.ReadString('\n')
if err != nil {
fmt.Println("Error reading from stdin")
panic(err)
}
_, err = rw.WriteString(fmt.Sprintf("%s\n", sendData))
if err != nil {
fmt.Println("Error writing to buffer")
panic(err)
}
err = rw.Flush()
if err != nil {
fmt.Println("Error flushing buffer")
panic(err)
}
}
}
消息以 换行符 \n 作为帧边界:writeData 从 stdin 读一行、追加 \n 写入流并 Flush;readData 按行读取并带绿色 ANSI 颜色输出。这套"按行定界 + 缓冲读写"的极简协议设计是理解 libp2p stream 双工通信的良好起点。
步骤 3:用 mDNS 发现附近的节点
发现逻辑封装在 mdns.go 中:
type discoveryNotifee struct {
PeerChan chan peer.AddrInfo
}
// interface to be called when new peer is found
func (n *discoveryNotifee) HandlePeerFound(pi peer.AddrInfo) {
n.PeerChan <- pi
}
// Initialize the MDNS service
func initMDNS(peerhost host.Host, rendezvous string) chan peer.AddrInfo {
// register with service so that we get notified about peer discovery
n := &discoveryNotifee{}
n.PeerChan = make(chan peer.AddrInfo)
// An hour might be a long long period in practical applications. But this is fine for us
ser := mdns.NewMdnsService(peerhost, rendezvous, n)
if err := ser.Start(); err != nil {
panic(err)
}
return n.PeerChan
}
调用链非常清晰:
discoveryNotifee实现Notifee接口(HandlePeerFound(peer.AddrInfo));mdns.NewMdnsService(peerhost, rendezvous, n)创建发现服务,把本地 Host、服务名、通知回调一并注册进去;ser.Start()启动服务——此时节点开始组播广播自己的地址,同时监听局域网内的 mDNS 应答;- 每当发现新节点,回调
HandlePeerFound会把peer.AddrInfo塞入 channel,供主循环消费。
步骤 4:连接到发现的节点并打开流
发现到对端之后,主循环(main.go)负责建立连接与流:
peerChan := initMDNS(host, cfg.RendezvousString)
for { // allows multiple peers to join
peer := <-peerChan // will block until we discover a peer
if peer.ID > host.ID() {
// if other end peer id greater than us, don't connect to it, just wait for it to connect us
fmt.Println("Found peer:", peer, " id is greater than us, wait for it to connect to us")
continue
}
fmt.Println("Found peer:", peer, ", connecting")
if err := host.Connect(ctx, peer); err != nil {
fmt.Println("Connection failed:", err)
continue
}
// open a stream, this stream will be handled by handleStream other end
stream, err := host.NewStream(ctx, peer.ID, protocol.ID(cfg.ProtocolID))
if err != nil {
fmt.Println("Stream open failed", err)
} else {
rw := bufio.NewReadWriter(bufio.NewReader(stream), bufio.NewWriter(stream))
go writeData(rw)
go readData(rw)
fmt.Println("Connected to:", peer)
}
}
这里有几个必须理解的设计:
- 按 PeerID 大小"分工":
if peer.ID > host.ID()用于避免两端同时发起NewStream。PeerID 较大的一端只等待、不主动拨号,由较小的一端负责Connect+NewStream。这一技巧保证了流只有一个发起方,避免协议栈层面出现"双向同时开流"的重复连接; host.Connect(ctx, peer):将peer.AddrInfo中的地址吸收进本地 peerstore,必要时发起拨号(接口契约见 core/host/host.go:"Connect will absorb the addresses in pi into its internal peerstore. If there is not an active connection, Connect will issue a h.Network.Dial");host.NewStream(ctx, peer.ID, protocol.ID(cfg.ProtocolID)):以指定协议 ID 打开一条新的双工流,远端会触发步骤 2 注册的handleStream;- 外层
for {}循环:peerChan是阻塞式 channel,<-peerChan会一直等待新节点;这允许多个节点陆续加入聊天,而不仅仅支持两两互通。
四、源码深挖:mDNS 服务内部是怎么工作的?
示例只是 NewMdnsService 的使用方,真正实现位于 p2p/discovery/mdns/mdns.go,底层依赖 github.com/libp2p/zeroconf/v2(mDNS 的 Go 实现,go.mod 中声明)。了解内部机制有助于你判断在什么网络环境下该方案可用。
4.1 服务注册:只广播适合 LAN 的地址
Start() 首先调用 startServer()(mdns.go)。它通过 host.Network().InterfaceListenAddresses() 拿到所有监听地址,然后做两层筛选后注册 mDNS 服务:
getIPs:从 multiaddr 中抽取 IPv4 / IPv6 地址,填充 DNS 的 A / AAAA 记录(作者注释说明:其实 libp2p 并不关心这些 IP 记录,但路由器与防火墙要求必须携带它们,见 mdns.go);isSuitableForMDNS:判定地址是否适合通过 mDNS 广播(mdns.go),判定规则为:- 必须是以
/ip4、/ip6开头的直连地址,或.local结尾的 DNS 名(.local是 RFC 6762 保留给 mDNS 的顶级域,只能组播解析,不能走单播 DNS); - 排除中继地址(
P_CIRCUIT,即 p2p-circuit 中继)与浏览器专用传输(WebTransport、WebRTC、WebSocket/WSS)——这些地址对直连的局域网发现没有意义,广播只会撑大 mDNS 报文; - 过滤的另一个目的是控制 mDNS 报文大小,尽量保持在 RFC 6762 建议的 1500 字节以内(对应 issue 见源码注释,mdns.go)。
- 必须是以
每个符合条件地址的 multiaddr 字符串以 dnsaddr= 前缀写入 TXT 记录(常量 dnsaddrPrefix,mdns.go),最终通过 zeroconf.RegisterProxy 注册名为 _p2p._udp.local 的服务。
4.2 服务解析:只消费 TXT 记录
startResolver(mdns.go)启动两个 goroutine:
- 一个用
zeroconf.Browse监听组播组内的 mDNS 应答,把ServiceEntry送入容量 1000 的 channel; - 另一个消费 entry,只关心
dnsaddr=前缀的 TXT 记录(源码注释明确 "We only care about the TXT records. Ignore A, AAAA and PTR"),解析出 multiaddr 后经peer.AddrInfosFromP2pAddrs还原成peer.AddrInfo,过滤掉自己(info.ID == s.host.ID()跳过)后,以 goroutine 方式回调HandlePeerFound。
4.3 生命周期与测试佐证
- 服务实现
Service接口(Start() error+io.Closer),Close()会取消内部 context、关闭 zeroconf server 并等待解析 goroutine 退出(mdns.go); - 每次创建服务时节点会生成 32~63 位的随机 peerName(
randomString(32 + rand.Intn(32)),mdns.go),保证同一局域网内服务实例名互不冲突。
上述地址过滤规则均有测试用例验证,见 p2p/discovery/mdns/mdns_test.go 的 TestIsSuitableForMDNS:例如 /ip4/192.168.1.1/tcp/4001、/ip4/192.168.1.2/udp/4001/quic-v1 判定为适合;/ip4/.../udp/4001/webrtc、/ip4/.../tcp/443/wss、/dns4/example.com/tcp/4001、带 p2p-circuit 的中继地址均判定为不适合。另有 TestOtherDiscovery(mdns_test.go)在 Linux 上启动 4 个 Host,断言各自都能在 5 秒内发现其余全部节点——这正是示例"两个终端开箱即聊"背后的测试保证。
五、实战建议与边界
基于源码实现,几点可以沉淀为工程经验的结论:
- 适用场景:mDNS 发现只适用于同一局域网 / 同一组播域。若对端在公网或跨 NAT,应改用 chat-with-rendezvous 的 DHT + rendezvous 方案,或引入 relay 中继;
- 协议 ID 一致性:
-pid(默认/chat/1.1.0)在两端必须一致,否则NewStream无法命中对方的SetStreamHandler,流会被协议协商阶段拒绝; - 双向握手技巧:按 PeerID 大小决定由谁发起
NewStream,是避免双向同时建流的实用模式,可迁移到任何多节点自动组网代码中; - 消息定界:以
\n作为应用层帧边界适合演示与简单工具;生产级应用应使用显式长度前缀或 protobuf 等带定界协议(可参考仓库内 multipro 示例 的 protobuf 用法); - 替换成本:示例把
NewMdnsService封装成initMDNS并返回 channel,抽象出了"发现结果 = channel 流"的通用形态,替换成 DHT 发现时只需保持<-chan peer.AddrInfo的消费方不变。
延伸阅读
- 示例完整源码:main.go、mdns.go、flags.go
- mDNS 服务实现与测试:p2p/discovery/mdns/mdns.go、p2p/discovery/mdns/mdns_test.go
- Host 接口定义:core/host/host.go
- 节点构造器
libp2p.New与选项:libp2p.go、options.go - 对照组(DHT 发现方案):chat-with-rendezvous
- 更多官方示例索引:examples/README.md