P2P 与分布式存储 / 系统课时
直连失败时怎样回退中继通道
直连失败时怎样回退中继通道
两个 P2P 节点已经通过中继连通,但尝试 NAT 打洞升级直连时,可能因为防火墙、NAT 映射或网络超时而失败。本课实现一套可验证的回退策略:为连接升级设置等待预算,失败后保留原有中继通道,记录实际传输路径,并测量直连和中继的性能差异。
学习目标
- 理解 DCUtR 直连升级与中继保底的关系,区分升级失败和连接彻底断开。
- 使用 go-libp2p 配置连接超时,验证升级失败后仍能通过中继收发数据。
- 根据实际连接类型、请求延迟和中继资源限制判断是否需要重新拨号。
升级失败后为什么能够继续使用中继
libp2p 的 DCUtR(Direct Connection Upgrade through Relay)允许两个节点先通过 Circuit Relay v2 建立安全通信,再利用中继通道交换地址、协调同时拨号,尝试建立更高效的直接连接。
这里的升级是建立一条新的直接连接,而不是立即关闭原有中继连接。因此,在打洞失败时,只要中继连接仍然有效,应用就可以继续通过原有通道通信。
一个实际场景如下:节点 A 与节点 B 都位于限制入站连接的网络中,双方已经通过公网中继 R 连通。A 和 B 交换候选地址并尝试打洞,但因为 NAT 映射不兼容而无法直连。此时不应立即断开 R,而应保持中继业务流可用。

在 go-libp2p 中,libp2p.EnableHolePunching() 用于启用打洞能力,libp2p.EnableRelay() 用于启用中继传输。应用可以设置以下超时预算,避免业务无限等待直连升级。
| 控制项 | 实验取值 | 处理原则 |
|---|---|---|
| 初始连接超时 | 5 秒 | 连接失败则返回错误 |
| 升级观察窗口 | 4 秒 | 未发现直连则继续使用中继 |
| 单条业务流截止时间 | 3 秒 | 超时终止本次请求,不立即销毁所有连接 |
| 直连重试退避 | 1、2、4 秒 | 应用层限频,避免持续打洞 |
需要区分三个结果:直连建立成功,可以优先使用直连;直连失败但中继有效,继续通过中继通信;直连和中继均失效,则必须重新发现地址或中继节点,不能宣称已完成回退。
搭建可运行的中继保底实验
使用 Go 1.25.7 和 go-libp2p v0.49.0。下面的程序在本机建立节点 A、节点 B 和中继 R,分别运行直连和中继实验。中继模式通过禁止 A、B 监听网络地址,模拟无法建立直接入站连接的情况。
这样能够稳定验证中继保底行为,但不等同于真实 NAT 打洞实验,因为禁用监听地址也会使节点缺少可用于打洞的候选监听地址。
首先创建项目并安装依赖:
mkdir relay-fallback
cd relay-fallback
go mod init example.com/relay-fallback
go get github.com/libp2p/go-libp2p@v0.49.0
go get github.com/multiformats/go-multiaddr@v0.16.1预期结果:命令成功完成,生成 go.mod 和 go.sum,其中 go.mod 包含指定的 go-libp2p 依赖版本。依赖下载日志与本机缓存有关,不要求逐行一致。
在项目目录创建 main.go,写入以下完整程序:
package main
import (
"context"
"flag"
"fmt"
"io"
"log"
"time"
libp2p "github.com/libp2p/go-libp2p"
"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/protocol/circuitv2/client"
"github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/relay"
ma "github.com/multiformats/go-multiaddr"
)
func must(err error) {
if err != nil {
log.Fatal(err)
}
}
func main() {
mode := flag.String("mode", "relay", "direct or relay")
flag.Parse()
if *mode != "direct" && *mode != "relay" {
log.Fatal("mode must be direct or relay")
}
ctx := context.Background()
opts := []libp2p.Option{
libp2p.EnableRelay(),
libp2p.EnableHolePunching(),
}
if *mode == "relay" {
// 禁止监听地址,稳定模拟无法直接入站的节点。
opts = append([]libp2p.Option{libp2p.NoListenAddrs}, opts...)
}
a, err := libp2p.New(opts...)
must(err)
defer a.Close()
b, err := libp2p.New(opts...)
must(err)
defer b.Close()
const echoProtocol = protocol.ID("/course/echo/1.0.0")
b.SetStreamHandler(echoProtocol, func(s network.Stream) {
defer s.Close()
var buf [4]byte
for {
if _, err := io.ReadFull(s, buf[:]); err != nil {
return
}
if _, err := s.Write(buf[:]); err != nil {
return
}
}
})
dialCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
if *mode == "direct" {
// 本机可直连:直接拨号 B 的监听地址。
must(a.Connect(dialCtx, peer.AddrInfo{
ID: b.ID(), Addrs: b.Addrs(),
}))
} else {
r, err := libp2p.New(
libp2p.ListenAddrStrings("/ip4/127.0.0.1/tcp/0"),
)
must(err)
defer r.Close()
_, err = relay.New(r)
must(err)
rInfo := peer.AddrInfo{ID: r.ID(), Addrs: r.Addrs()}
must(a.Connect(ctx, rInfo))
must(b.Connect(ctx, rInfo))
// 目标 B 必须先在 R 上申请中继预留。
_, err = client.Reserve(ctx, b, rInfo)
must(err)
addr, err := ma.NewMultiaddr(
"/p2p/" + r.ID().String() +
"/p2p-circuit/p2p/" + b.ID().String(),
)
must(err)
must(a.Connect(dialCtx, peer.AddrInfo{
ID: b.ID(), Addrs: []ma.Multiaddr{addr},
}))
// 只限制应用等待升级的时间,不销毁已有中继连接。
deadline := time.Now().Add(4 * time.Second)
upgraded := false
for time.Now().Before(deadline) {
for _, conn := range a.Network().ConnsToPeer(b.ID()) {
if !conn.Stat().Limited {
upgraded = true
break
}
}
if upgraded {
break
}
time.Sleep(100 * time.Millisecond)
}
if upgraded {
fmt.Println("upgrade=direct")
} else {
fmt.Println("upgrade=timeout fallback=relay")
}
}
// 明确允许在受限中继连接上建立业务流。
streamCtx := network.WithAllowLimitedConn(ctx, "fallback-check")
s, err := a.NewStream(streamCtx, b.ID(), echoProtocol)
must(err)
defer s.Close()
must(s.SetDeadline(time.Now().Add(3 * time.Second)))
path := "direct"
if s.Conn().Stat().Limited {
path = "relay"
}
// 在同一业务流上执行20次请求响应,计算平均往返时间。
var total time.Duration
var reply [4]byte
for i := 0; i < 20; i++ {
start := time.Now()
_, err = s.Write([]byte("ping"))
must(err)
_, err = io.ReadFull(s, reply[:])
must(err)
if string(reply[:]) != "ping" {
log.Fatal("unexpected response")
}
total += time.Since(start)
}
fmt.Printf("mode=%s path=%s ping=20 avg_rtt_ms=%.2f\n",
*mode, path, float64(total.Microseconds())/20000)
}程序的关键操作是先建立实际可用的数据连接,再观察是否存在非受限直连。等待升级期间并不关闭中继,所以观察超时后仍能打开业务流。
network.WithAllowLimitedConn() 很重要。Circuit Relay v2 连接带有资源限制,go-libp2p 不允许普通业务流在未明确授权的情况下随意使用这种连接。如果缺少该上下文选项,在仅有中继连接时可能遇到 network.ErrLimitedConn。
验证回退结果与实际传输路径
先运行中继模式,再运行直连模式。两次程序使用相同的 Echo 协议,均发送 20 次四字节请求,并计算平均往返时间。
go run . -mode=relay
go run . -mode=direct预期输出结构如下,两次运行的实际延迟会根据设备负载和网络环境变化:
upgrade=timeout fallback=relay
mode=relay path=relay ping=20 avg_rtt_ms=<TIME>
mode=direct path=direct ping=20 avg_rtt_ms=<TIME>这里 <TIME> 代表实际测得的毫秒数,不是固定数值。最重要的验收结果是第一种模式在升级观察超时后仍能完成 20 次请求响应,且 path=relay;第二种模式应显示 path=direct。
程序使用 s.Conn().Stat().Limited 检查承载当前业务流的连接,而不仅仅检查节点之间是否存在某条直接连接。这个区别很重要:一个节点可能同时具有直接连接和中继连接,不能根据对等节点列表简单推断每条业务流的实际传输路径。
生产环境建议按以下字段记录每次业务请求的路径信息:
| 字段 | 示例值 | 用途 |
|---|---|---|
peer_id |
实际远端 Peer ID | 定位目标节点 |
transport_path |
direct 或 relay |
识别实际业务路径 |
connection_limited |
true 或 false |
检查连接资源限制 |
upgrade_result |
success、timeout、failed |
记录升级结果 |
rtt_ms |
实际测量值 | 比较交互延迟 |
relay_peer_id |
实际中继 Peer ID | 关联中继节点与故障 |
其中 upgrade_result 是应用自行定义的日志字段,并非 go-libp2p 自动提供的同名状态。需要更准确地记录每次 DCUtR 打洞尝试的成功与失败原因时,应接入版本对应的打洞追踪或指标机制,而不是仅根据等待超时推断协议失败。
比较性能时还要避免一个误区:上述两种模式都运行在本机,测得的数值只能证明路径选择和测量代码有效,不能代表跨公网传输的真实性能。
真实测试应将节点 A、节点 B 部署到不同网络,并让 R 位于独立公网服务器。保持消息大小、请求数量和测试时段基本一致,分别记录直连与中继路径的 RTT 分布,以及实际完成传输的数据量和耗时。
例如,某次独立实验测得直连传输 64 KiB 用时 40 毫秒,中继传输相同数据用时 160 毫秒,则按照数据量除以耗时计算,前者约为 13.11 Mbit/s,后者约为 3.28 Mbit/s。这只是计算示例,不是 libp2p 的固定性能指标。
处理升级超时和中继自身失效
业务恢复需要分别处理直连升级失败、中继连接断开以及中继预留过期,不能用同一个超时结果覆盖所有情况。
| 发现的现象 | 判断依据 | 应采取的动作 |
|---|---|---|
| 升级等待超过 4 秒 | 仍未出现非受限连接 | 继续使用有效中继,不中断业务 |
| 直连建立成功 | 存在 Limited=false 的连接 |
新业务流优先走直连,并验证实际路径 |
| 业务流返回超时 | 读写超过请求截止时间 | 终止本次请求,检查连接状态后决定重试 |
| 中继连接被关闭 | 原有中继连接不可用 | 检查预留和资源限制,必要时重建中继连接 |
| 中继预留过期 | 无有效 reservation | 重新申请预留并更新可公告的中继地址 |
| 多次打洞失败 | 失败计数达到策略阈值 | 按退避间隔重试,继续保留有效中继 |
还需要处理连接切换期间的业务流生命周期。根据 go-libp2p 的连接升级行为,新建业务流可以优先使用成功建立的直接连接,但已经存在的长连接业务流不会自动把内部传输无缝迁移到另一条连接上。
因此,长期运行的聊天流、同步流或文件传输流应具备重新建流能力。连接切换时使用业务序列号、确认位置或分块偏移恢复数据,避免直接重发已经处理过的消息。
例如文件同步已确认偏移为 65536 字节,切换连接后应从该偏移继续读取,而不是默认从文件开头重新传输。涉及写操作的消息还应通过请求 ID 做幂等处理。
中继本身也不能视为永久在线。需要监控 reservation 的有效期,在过期前续约;当中继因时间或数据配额关闭连接时,应重新选择有效中继。默认预留有效期约为 1 小时,但应用必须以实际返回的到期时间为准。
最后可以按三个条件验收回退方案:升级超时后原有中继业务仍可用;新业务流能够识别并记录实际使用的连接类型;中继失效时能明确报错并触发重新连接,而不是无限重试一条已经关闭的通道。只要这三项通过,直连升级失败就不会被错误地放大为整个 P2P 会话不可用。