P2P 与分布式存储 / 系统课时
Circuit Relay 如何转发节点流量
Circuit Relay 如何转发节点流量
当节点位于严格 NAT 或防火墙之后,外部节点可能无法直接拨入。Circuit Relay 允许私有节点先连接公共中继并预约接入位置,让其他节点通过中继地址建立通信。本课将使用 go-libp2p 搭建三节点实验,完成预约、转发、数据验证与性能测量。
学习目标
- 解释 Circuit Relay v2 的预约、连接建立和双向转发过程。
- 部署公共中继节点,让无法接受直接入站连接的节点通过中继地址接收请求。
- 验证中继连接的实际路径,测量往返延迟与有效吞吐,并识别资源限制。
中继连接怎样建立
假设私有节点 A 位于家庭 NAT 后面,公共中继 R 部署在云服务器,节点 B 希望访问 A。A 可以主动连接 R,但 B 无法通过 A 的私有地址直接建立入站连接。
Circuit Relay v2 将通信分为两个阶段:先预约,再建立中继连接。它使用两个不同的协议:
- Hop 协议
/libp2p/circuit/relay/0.2.0/hop:由客户端向中继发起RESERVE或CONNECT请求。 - Stop 协议
/libp2p/circuit/relay/0.2.0/stop:由中继向目标节点发起连接交付请求。
具体执行顺序如下:
- A 主动连接 R,并发送
RESERVE请求。 - R 检查预约容量、访问权限与资源限制;成功时返回
STATUS:OK、预约过期时间以及预约凭证等信息。 - A 保持到 R 的连接,并将包含 R 与 A 身份的中继地址提供给 B。
- B 连接 R,使用 Hop
CONNECT请求访问 A。 - R 检查 A 的有效预约,通过 Stop
CONNECT通知 A。A 接受后,R 将两侧数据流连接起来。 - A 与 B 在建立的中继传输上完成端到端安全连接协商,随后通过 R 双向传输应用数据。

中继地址使用 Multiaddr 表示,其完整形式为 /ip4/<PUBLIC_IP>/tcp/4001/p2p/<RELAY_ID>/p2p-circuit/p2p/<TARGET_ID>。
其中,<PUBLIC_IP> 是中继的公网 IPv4 地址,<RELAY_ID> 是 R 的 Peer ID,<TARGET_ID> 是 A 的 Peer ID。/p2p-circuit 表示需要通过前面的中继节点访问后面的目标节点,而不是直接拨号到 A。
预约与实际转发也不是同一种资源。预约表示 R 暂时接受为 A 提供接入服务,只有 B 成功发起连接并且 A 接受后,才会产生实际的中继数据流。
部署公共中继并建立预约
下面使用 Go 和 go-libp2p 完成一个真实的三进程实验。代码适用于 github.com/libp2p/go-libp2p v0.50.0,该版本要求 Go 1.26.0 或更新版本。三个进程可以部署在不同机器上,也可以先在同一台机器上使用可达地址测试协议流程。
准备三个运行位置:
| 角色 | 部署位置 | 网络要求 |
|---|---|---|
| R:公共中继 | 有公网入口的 Linux 云服务器 | TCP 4001 可从 A、B 到达 |
| A:接收节点 | NAT 后的电脑或云主机 | 可以主动访问 R,不需要开放入站端口 |
| B:拨号节点 | 另一台客户端 | 可以主动访问 R |
在各机器的项目目录中执行初始化命令:
go mod init relaylab
go get github.com/libp2p/go-libp2p@v0.50.0预期结果:当前目录生成 go.mod,并记录 go-libp2p v0.50.0 及所需依赖。依赖下载信息可能因已有缓存而不同;三个运行位置应使用相同版本。
将下面的完整程序保存为 main.go。它通过 -mode 参数分别承担公共中继、私有接收端和拨号端三个角色。
package main
import (
"bytes"
"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"
)
func check(err error) {
if err != nil {
log.Fatal(err)
}
}
// 在同一条应用流上执行多轮请求与回显,统计完整往返耗时。
func exchange(s network.Stream, size, rounds int) time.Duration {
request := bytes.Repeat([]byte{'A'}, size)
response := make([]byte, size)
start := time.Now()
for i := 0; i < rounds; i++ {
_, err := s.Write(request)
check(err)
_, err = io.ReadFull(s, response)
check(err)
if !bytes.Equal(request, response) {
log.Fatal("echo payload mismatch")
}
}
return time.Since(start)
}
func main() {
mode := flag.String("mode", "", "relay, receive or dial")
publicIP := flag.String("public-ip", "", "relay public IPv4")
relayAddr := flag.String("relay", "", "full relay multiaddr")
target := flag.String("target", "", "receiver Peer ID")
flag.Parse()
ctx := context.Background()
switch *mode {
case "relay":
if *publicIP == "" {
log.Fatal("-public-ip is required")
}
h, err := libp2p.New(
libp2p.ListenAddrStrings("/ip4/0.0.0.0/tcp/4001"),
)
check(err)
defer h.Close()
// 显式提供 Circuit Relay v2 服务,并限制单条中继连接的资源。
_, err = relay.New(h, relay.WithLimit(&relay.RelayLimit{
Duration: 5 * time.Minute,
Data: 4 << 20,
}))
check(err)
fmt.Printf("relay=/ip4/%s/tcp/4001/p2p/%s\n", *publicIP, h.ID())
select {}
case "receive", "dial":
if *relayAddr == "" {
log.Fatal("-relay is required")
}
// 禁用普通监听地址,模拟无法被直接拨入的节点。
h, err := libp2p.New(libp2p.NoListenAddrs, libp2p.EnableRelay())
check(err)
defer h.Close()
relayInfo, err := peer.AddrInfoFromString(*relayAddr)
check(err)
check(h.Connect(ctx, *relayInfo))
if *mode == "receive" {
h.SetStreamHandler(protocol.ID("/relay-lab/1.0.0"), func(s network.Stream) {
defer s.Close()
// 将收到的应用字节原样返回,便于验证端到端数据传输。
_, _ = io.Copy(s, s)
})
reservation, err := client.Reserve(ctx, h, *relayInfo)
check(err)
fmt.Printf("receiver=%s expires=%s\n",
h.ID(), reservation.Expiration.Format(time.RFC3339))
fmt.Printf("circuit=%s/p2p-circuit/p2p/%s\n",
*relayAddr, h.ID())
select {}
}
if *target == "" {
log.Fatal("-target is required")
}
// 使用中继路径而不是目标节点的直接监听地址。
circuit := *relayAddr + "/p2p-circuit/p2p/" + *target
targetInfo, err := peer.AddrInfoFromString(circuit)
check(err)
check(h.Connect(ctx, *targetInfo))
streamCtx := network.WithAllowLimitedConn(ctx, "relay-lab")
s, err := h.NewStream(streamCtx, targetInfo.ID,
protocol.ID("/relay-lab/1.0.0"))
check(err)
defer s.Close()
check(s.SetDeadline(time.Now().Add(30 * time.Second)))
// 小消息用于测量往返延迟,较大消息用于测量有效吞吐。
pingTime := exchange(s, 1, 20)
bulkTime := exchange(s, 32*1024, 8)
goodput := float64(2*32*1024*8) / bulkTime.Seconds() / 1024
fmt.Printf("via=%s\n", s.Conn().RemoteMultiaddr())
fmt.Printf("avgRTT=%s goodput=%.1f KiB/s\n",
pingTime/20, goodput)
default:
log.Fatal("choose -mode=relay, receive or dial")
}
}预期结果:程序根据指定角色分别启动中继服务、创建并维持预约,或通过中继连接完成数据回显测试。receive 模式不开放直接监听地址;dial 模式必须使用包含 /p2p-circuit 的目标地址。程序将输出真实 Peer ID、预约到期时间以及测得的性能数据。
中继服务使用了两个明确的资源限制:
| 参数 | 实验取值 | 含义 |
|---|---|---|
RelayLimit.Duration |
5 分钟 | 单条中继连接最长保持时间 |
RelayLimit.Data |
4 MiB | 每个方向允许转发的数据上限 |
| TCP 监听端口 | 4001 | 公共中继接受直接连接的端口 |
这里使用 relay.New 显式启动服务,而不是依赖自动公网可达性检测。生产环境可以改用 libp2p.EnableRelayService 配合公网可达性检测,但需要分别核对公网检测、监听地址和服务启用状态。
运行三节点并验证转发
先在公共云服务器启动 R。服务器必须拥有实际可达的公网入口;如果采用云平台公网 IP 映射,还需要放行安全组与主机防火墙中的 TCP 4001。
go run . -mode=relay -public-ip=<PUBLIC_IP>预期输出形态:
relay=/ip4/<PUBLIC_IP>/tcp/4001/p2p/<ID>将实际输出的完整中继地址复制下来。<PUBLIC_IP> 为服务器真实公网 IPv4,<ID> 为本次启动生成的中继 Peer ID,必须使用程序输出值替换后续命令中的占位符。
接下来在 NAT 后的 A 上运行接收端:
go run . -mode=receive -relay="/ip4/<PUBLIC_IP>/tcp/4001/p2p/<RELAY_ID>"预期输出形态:
receiver=<ID> expires=<TIME>
circuit=/ip4/<PUBLIC_IP>/tcp/4001/p2p/<RELAY_ID>/p2p-circuit/p2p/<ID>其中 expires 是实际预约到期时间,格式为 RFC3339。第二行是 B 应使用的完整中继地址。复制接收端真实的 Peer ID 作为 <TARGET_ID>。
最后,在 B 上执行拨号与回显验证:
go run . -mode=dial -relay="/ip4/<PUBLIC_IP>/tcp/4001/p2p/<RELAY_ID>" -target=<TARGET_ID>预期输出形态:
via=<PATH>
avgRTT=<TIME> goodput=<RATE> KiB/s<PATH> 是实际连接的远端 Multiaddr,应包含 /p2p-circuit;<TIME> 和 <RATE> 分别是实测平均往返耗时与有效吞吐数值。具体数值取决于网络条件,不能预先固定。
这个实验有四个明确的验收条件:
- A 的
client.Reserve成功,获得预约到期时间。 - B 能通过完整中继地址连接 A,而 A 没有开放普通入站监听端口。
- B 的连接路径包含
/p2p-circuit,证明连接经过中继传输。 - 每一轮回显字节与请求一致,没有出现
echo payload mismatch。
如果三个进程部署在同一台主机上,可以使用该实验验证协议流程,但不能据此证明公网 NAT 穿透能力。要验证真实跨网可达性,应将 A 放在不允许公网入站的网络,R 放在公网可达服务器,并从独立网络运行 B。
测量延迟与带宽开销
中继路径包含 B 到 R、R 到 A 两段网络连接。即使每一段都正常工作,中继的转发、排队、资源争用和路径绕行仍可能增加应用延迟。
假设测得 B 到 R 的 RTT 为 45 ms,A 到 R 的 RTT 为 35 ms。在链路稳定、忽略额外排队与处理延迟的理想情况下,B 与 A 经 R 通信的端到端 RTT 约为 80 ms。
这只是根据两段 RTT 推算的参考值。实际结果应以应用协议回显测量为准,不应将两段链路的 RTT 当成独立固定延迟。
本例采用两种测量方式:
| 测量项 | 实验负载 | 指标解释 |
|---|---|---|
| 小消息延迟 | 1 字节,重复 20 次 | 20 次完整请求回显的平均耗时 |
| 有效吞吐 | 32 KiB,重复 8 次 | 双向回显有效载荷总字节数除以耗时 |
| 路径验证 | RemoteMultiaddr() |
检查连接是否经过 /p2p-circuit |
吞吐测试总计发送 256 KiB、回显 256 KiB,有效载荷合计 512 KiB。程序打印的 goodput 是这一轮回显的双向合计应用有效吞吐,不等于底层 TCP 链路的单向带宽上限。
例如,如果这 512 KiB 的往返回显测试耗时 0.8 秒,那么按本课定义计算的有效吞吐为 640 KiB/s。这是计算示例,不代表任何实际部署的固定性能。
为了公平比较直连与中继,应保持发送端、接收端、测试载荷与运行次数相同,分别采集直连和中继数据。不能拿本地回环地址的直连结果去和跨地域公网中继结果直接比较。
中继还会消耗服务器出口流量。B 向 A 发送 10 MiB、A 向 B 返回 10 MiB 时,R 大约需要接收 20 MiB、发送 20 MiB 的应用数据,实际网络计费流量还会包含传输协议与加密开销。因此,中继服务器应重点监控出口带宽、活跃连接数和流量峰值。
预约失败、资源限制与生产边界
Circuit Relay v2 引入了明确的预约容量和转发资源控制,不能假设任何中继都允许无限连接、无限流量或永久预约。
Go 实现的默认中继限制通常包含约 1 小时的预约有效期、单条连接 2 分钟持续时间与每方向 128 KiB 数据上限。本课显式将后两项调整为 5 分钟和 4 MiB;具体服务限制仍应以所部署版本与服务器返回的 Limit 信息为准。
排查时先区分以下现象:
| 现象或协议状态 | 主要原因 | 处理方式 |
|---|---|---|
| 无法连接公共 R | 公网地址错误、TCP 4001 被防火墙拦截 | 检查监听地址、安全组与真实公网可达性 |
RESERVATION_REFUSED |
预约容量不足或服务拒绝预约 | 检查中继预约数量、资源配置和服务器状态 |
NO_RESERVATION |
A 没有有效预约,或预约已经失效 | 重新预约,确认 A 与 R 的连接仍然存在 |
RESOURCE_LIMIT_EXCEEDED |
中继连接资源超过服务限制 | 减少并发、调整资源策略或增加中继节点 |
PERMISSION_DENIED |
中继访问控制策略拒绝该 Peer | 检查 ACL 和允许访问的节点身份 |
| 数据流被重置 | 连接持续时间、数据量或其他连接条件达到上限 | 缩小中继承载的数据量,重新连接或切换直连 |
预约需要在到期前更新,并且依赖接收端与中继之间持续存在的连接。本课示例执行一次显式 client.Reserve,适用于短时间验证,不包含生产环境所需的续约调度、断线重连与中继切换逻辑。
生产部署还需要处理三个实际问题:
- 身份持久化:示例每次启动都会生成新的 Peer ID。生产节点必须保存并复用身份私钥,否则重启后原有中继地址中的 Peer ID 将失效。
- 资源与权限管理:使用
relay.WithResources、relay.WithLimit和必要的 ACL 管理预约数、并发连接及可用流量,避免公共中继被滥用。 - 直连升级与故障转移:当双方网络条件允许时,可结合 DCUtR 打洞尝试升级为直接连接;同时准备多个可用中继,避免单个中继故障导致所有私有节点失联。
尤其需要注意,Circuit Relay v2 的限额由中继控制。即使应用希望建立长时间连接,中继仍然可以在时间或流量上限到达时重置数据流。长连接业务必须能够重新连接、重新认证并恢复必要的应用状态。
正式设计中,应将中继定位为受资源限制的可达性保障通道,而不是无限制的大流量转发服务。协议细节可参阅 libp2p Circuit Relay v2 规范。