L3 隧道

状态：Current

最后核对：2026-05-30

路由：/gateway/l3-networks

L3 隧道是在两个 Agent 之间创建的点对点网络。目前只接受 QUIC L3 和 userspace WireGuard。QUIC L3 当前使用 REALITY security 和 CONNECT-IP payload framing。后端只接受这两类当前 L3 family。

当前 L3 支持：

协议	传输	说明
QUIC	默认 QUIC DATAGRAM	当前 security profile：REALITY。Payload framing：RFC 9484 风格 CONNECT-IP，带 HTTP Datagram quarter stream ID。
WireGuard	userspace UDP	BoringTun runtime，不依赖内核模块。

前置条件

• 两个不同的已注册节点。
• 一个 Security Credentials 中的 REALITY profile。
• 部署前 Agent 已连接控制面。

创建隧道

需要 admin 或 operator。

1. 打开 L3 Tunnels。
2. 点击 Create L3 Tunnel。
3. 输入名称并选择启用状态。
4. 选择 Endpoint A 和 Endpoint B 节点。
5. 设置接口名，默认类似 nn-l3-left 和 nn-l3-right。
6. 配置 IPv4/IPv6 地址、allowed source CIDR、连接模式和监听端口。
7. 选择地址族、MTU 和 REALITY profile。
8. 选择能力开关并保存。

端点角色

端点	角色	说明
Endpoint A	listener	监听 QUIC REALITY，可配置连接信息。
Endpoint B	connector	主动连接 listener。

地址和 MTU

字段	规则
Address family	dual_stack、ipv4 或 ipv6。
IPv4 prefix length	1 到 32，默认 30。
IPv6 prefix length	1 到 128，默认 64。
MTU	576 到 9000，默认 1280。
IPv6 link-local	地址族为 dual_stack 或 ipv6 时，如果未填写显式 IPv6 host，Agent 会自动派生 IPv6 link-local 地址。

MTU 损耗

下面按当前后端和 Agent 接受的隧道协议计算 MTU 损耗。把两端 underlay 路径中最小的 IP 层 PMTU 记为 PMTU。

范围和假设：

• 这里计算的是 IP 层大小，不包含 Ethernet header、FCS、preamble、 VLAN tag、PPPoE 等 L2 开销。如果链路存在这些额外开销，要先从可用 underlay PMTU 中扣除。
• IPv4 underlay 和 IPv6 underlay 指两台节点之间的外层包。内层隧道 地址族可以是 IPv4、IPv6 或 dual-stack。
• IPv4 header 按 20 字节，IPv6 header 按 40 字节，UDP header 按 8 字节。
• QUIC transport 的线上开销不是固定常数。L3 over QUIC 只使用 QUIC DATAGRAM。
• WireGuard data packet 可能把加密 payload pad 到 16 字节边界。做 MTU 规划时，使用 WireGuard 标准损耗即可：IPv4 underlay 60 字节，IPv6 underlay 80 字节。

公式：

tunnel_mtu <= PMTU - overhead

QUIC L3

QUIC L3 在线上不是固定 header 隧道。QUIC packet number 长度、 connection ID 长度、DATAGRAM frame 编码、ACK 合并以及 TLS AEAD 扩展都会变化。

L3 over QUIC 只使用 QUIC DATAGRAM。每个 L3 datagram 是：

QUIC DATAGRAM payload = 8-byte NexusNet session id + 1-byte HTTP/3 Quarter Stream ID + 1-byte CONNECT-IP Context ID + inner IP packet

也就是在 QUIC 自身 DATAGRAM frame 和 packet protection 之前先有 10 字节。 Agent 配置 Quinn 时还额外预留 96 字节：

outer_udp_payload_budget = tunnel_mtu + 1 + 1 + 8 + 96
                         = tunnel_mtu + 106

underlay PMTU 为 1500 时：

Underlay	不分片时最大 UDP payload	当前预算下安全 tunnel MTU
IPv4	1500 - 20 - 8 = 1472	1472 - 106 = 1366
IPv6	1500 - 40 - 8 = 1452	1452 - 106 = 1346

重要运维说明：

• Agent 默认 NEXUS_QUIC_OUTER_UDP_PAYLOAD_SIZE 是 1472，这是 IPv4 尺寸。如果 underlay 是严格 PMTU 1500 的 IPv6 路径，并且不能分片，应把它 设置为 1452 或更低。
• 默认 tunnel MTU 1280 在 IPv4 和 IPv6 underlay 下都落在 CONNECT-IP QUIC DATAGRAM 预算内，也是公网路径推荐起点。

PMTU 1500 快速建议

协议模式	IPv4 underlay MTU 设置	IPv6 underlay MTU 设置	保守 dual-stack 设置
QUIC L3	1366，按单包 DATAGRAM 预算	1346，按单包 DATAGRAM 预算	1280
Userspace WireGuard	1440	1420	1280

未知公网路径建议先用保守 dual-stack 值或默认 1280，再用两端 underlay 地址 做 PMTU 测试后上调。

REALITY 端口复用

同一 listener 节点、协议、端口和 SNI 必须使用相同 X25519 key；同一 SNI + short ID 不能重复。多个隧道可以通过不同 short ID 复用同一端口。

部署

点击 deploy 后，后端刷新所有启用的 L3 隧道配置，并向连接中的 Agent 推送每节点配置。