#NSGW · WireGuard Peer Relay 协议层

本页是 architecture.md §2.2 的协议层附录,详细描述 NSGW 如何在不解密的前提下中继 WireGuard 流量,以及与原生 WireGuard 客户端的兼容矩阵。设计参照 Tailscale Peer Relay。

适合的读者:NSGW 实现者、要把站点节点接入 NSIO 但只能跑原生 WG 客户端的运维。

#1. WireGuard 报文头里 NSGW 能直接看到的字段

WireGuard 只有四种报文,布局固定,前几个字节为明文:

NSGW 只读 index(4 字节)和 mac1(16 字节),报文按字节原样转发,不修改、不重组、不解密。

#2. 三个关键路由动作

#2.1 用 mac1 把 HandshakeInit 路由到正确的 NSN

WireGuard 协议定义(白皮书):

mac1 = MAC( key = HASH("mac1----" ‖ responder_static_pubkey),
            data = msg[0..116] )

• MAC = keyed BLAKE2s,output 16 bytes
• HASH = BLAKE2s
• responder_static_pubkey = 接收方(NSN)的静态公钥

NSGW 持有 NSD 通过 SSE gateway_wg_relay 下发的所有候选 NSN 公钥。启动 / 配对表变更时预计算并缓存:

mac1_keys[i] = HASH("mac1----" ‖ NSN_i.pubkey)

收到一个 Init 时,对每个 mac1_keys[i] 做一次 MAC,匹配的就是目标 NSN。

on init_packet(p, src_4tuple):
    for (i, key) in mac1_keys:
        if MAC(key, p[0..116]) == p[116..132]:
            dst = NSN_i.endpoint
            sender_idx = u32_le(p[4..8])
            sessions[(sender_idx, src_4tuple)] = {
                src_4tuple,
                dst,
                state = "init_forwarded",
            }
            forward(p, dst)
            return
    drop_with_log("init_no_mac1_match", src_4tuple)

复杂度:O(N) BLAKE2s-MAC per Init,N = 已注册 NSN 数。握手频率每 2 分钟一次,N=1k 时单包 ≈ 几十 µs,完全可负担;若需要更大规模,可做 mac1 前缀哈希分桶。

#2.2 用 receiver_index 把 Response / Transport 反向路由

NSN 回的 HandshakeResponse 里:

• receiver_index = NSC 在 Init 里写的 sender_index(NSN 把对端的 idx 原样回写)
• sender_index = NSN 自己分配的新 idx

on response_packet(p, src_4tuple):  # src_4tuple 是 NSN 这一段的来源
    rcv_idx = u32_le(p[8..12])
    snd_idx = u32_le(p[4..8])
    sess = sessions.find_by_init(rcv_idx)   # 上一步登记的 NSC 会话
    if not sess:
        drop_with_log("response_orphan", src_4tuple)
        return
    sessions[(snd_idx, src_4tuple)] = {
        src_4tuple,
        dst = sess.src_4tuple,           # NSN 这一头反向指 NSC
        state = "response_forwarded",
    }
    forward(p, sess.src_4tuple)

之后所有 type-3(CookieReply)与 type-4(TransportData)包,receiver_index 就足以单步查表转发:

on cookie_or_transport(p, src_4tuple):
    rcv_idx = u32_le(p[4..8])
    sess = sessions[(rcv_idx, src_4tuple)]
    if not sess:
        drop_with_log("transport_orphan", rcv_idx)
        return
    forward(p, sess.dst)

整体即一个加了 mac1 索引的 UDP NAT。

#2.3 数据流图

NSC                       NSGW                       NSN
 │ Init {sndr=A, mac1=X}    │                          │
 ├─────────────────────────►│ mac1 命中 NSN.pubkey      │
 │                          │ sessions[A,NSC]={dst=NSN} │
 │                          ├─────────────────────────►│
 │                          │ Response {sndr=B,rcv=A}   │
 │                          │◄─────────────────────────┤
 │                          │ A→NSC (反查)              │
 │                          │ sessions[B,NSN]={dst=NSC} │
 │ Response {...}           │                          │
 │◄─────────────────────────┤                          │
 │ Transport {rcv=B, ...}   │                          │
 ├─────────────────────────►│ B→NSN (单跳查表)          │
 │                          ├─────────────────────────►│
 │                          │ Transport {rcv=A, ...}   │
 │                          │◄─────────────────────────┤
 │ Transport {...}          │                          │
 │◄─────────────────────────┤                          │

#3. 为什么客户端完全无感

WG 协议本身有两项原生特性,让中继对端"自然"工作:

1. Endpoint 与 PublicKey 解耦:peer 配置里的 Endpoint = NSGW:port 决定初始往哪发;PublicKey 仍是对端的真实静态公钥(不是 NSGW 的)。NSGW 不持任何相关密钥,物理上无法解密。
2. Roaming Endpoint:当 WG 收到一条 mac1 校验通过且解密成功的握手报文,会自动把对应 peer 的 endpoint 更新为该报文的来源 IP:port(自 WG 内核模块定型起就有,2017+)。所以即便初始配置写得不一样,握手一旦从 NSGW 来,两端各自把"对端"锁定在 NSGW,后续所有出包自然走 NSGW。

要使用中继,客户端只需把 Endpoint 指向 NSGW;不需要客户端版本支持任何新协议、新字段、新握手扩展。

#4. 与原生 WireGuard 的兼容矩阵

#4.1 标准接入示例(NSC 与 NSN 都用原生 WG 客户端)

NSC 端(任意 wg-quick / 内核 WG / 商用 WG 客户端):

[Interface]
PrivateKey = <NSC_priv>
Address    = 10.0.0.1/32
ListenPort = 0

[Peer]
PublicKey  = <NSN_pub>                  # ← 仍是 NSN 的真实公钥
Endpoint   = nsgw.example.com:51820     # ← 改这一行就够了
AllowedIPs = 10.0.0.2/32
PersistentKeepalive = 25

NSN 端镜像配置即可。NSC 与 NSN 之间会话密钥端到端协商,NSGW 物理上无法解密。

#4.2 客户端实现支持

#4.3 协议特性兼容

#4.4 终结模式与中继模式同端口共存

NSGW 在同一个 51820/udp 上同时承担两种角色,凭 mac1 自动分派:

mac1 == MAC(HASH("mac1----" ‖ NSGW_self.pub),  init[:116])  → 终结模式 (§2.1)
mac1 == MAC(HASH("mac1----" ‖ NSN_i.pub),      init[:116])  → 中继到 NSN_i (§2.2)
全部不匹配                                                   → 丢弃 + 计数

带来的好处:客户端配置里只有一个 Endpoint = NSGW:51820,把某对 (NSC, NSN) 登记进"中继配对表"后,流量自动从终结切到中继,客户端无感、不需要重启、不需要换 endpoint。

#5. 边界情形与失败模式

#6. 不能从中继模式实现的能力

中继模式按设计放弃以下能力,需要的话切到 §2.1 终结模式:

这是两种模式互补的本质——终结模式换"网关侧能做事",中继模式换"端到端加密 + 兼容存量 WG"。

#7. 与 NSD 的契约

#7.1 决策时机:注册时声明,不是运行时申请

中继模式是否启用,在 NSN / NSC 注册阶段就已经决定:

1. NSN / NSC 通过 POST /api/v1/machine/register 在 body 中声明 supported_link_modes: ["direct", "relay", "terminate", "wss"] 子集(物理可达性 / 合规决定)。
2. NSD 在策略授权层为每条 (NSC, NSN) 边取 NSC.supported ∩ NSN.supported 选最优先项,材料化为 wg_config 与 gateway_wg_relay。
3. 模式生效后,NSC / NSN 端按下发的 wg_config 把 peer Endpoint 指向 NSGW(模式 = relay)或对端真实 endpoint(模式 = direct);没有"直连失败 → 申请中继"的运行期反馈环。
4. 模式变更属于策略变更:admin 调权限,或节点重新登记 supported_link_modes。

跨组件总览见 总体架构 §5.4。

#7.2 SSE 事件结构

NSGW 侧的中继配对表,由 NSD 通过 SSE gateway_wg_relay(规划中)推送:

// 示意结构,字段以 NSD 实现为准
{
  "type": "gateway_wg_relay",
  "version": 1,
  "relay_pairs": [
    {
      "nsc_pubkey": "<base64>",   // 仅作展示;NSGW 路由不用 NSC 公钥(中继模式无 NSC 侧 mac1 demux 路径)
      "nsn_pubkey": "<base64>",   // ← mac1 demux 用这个
      "nsn_endpoint": "100.64.0.2:51820",
      "addressing": "receiver_index",   // 或 "port"
      "listen_port": null               // addressing=port 时为分配的端口
    }
  ]
}

NSGW 对该事件做 diff apply:新增条目 → 加入 mac1 候选 key 表;删除 → 同步移除并清理 sessions。NSGW 完全被动,不接收 NSC/NSN 的运行期申请、也不主动决策。

#8. 最小实现规模估计

NSGW 一侧的代码:

合计约 500–800 行 Go,纯 user-space UDP socket,不依赖任何内核 WG / netlink——这一点是与终结模式实现路径的关键差异,也意味着 peer-relay 子系统可独立部署、独立扩展。

#9. 不在 Peer Relay 范围内

• NSGW 自己作为 WG 端点参与握手 —— 那是 §2.1 终结模式的事。
• WSS 中继(WsFrame) —— 那是 §2.3,用于 UDP 完全被阻断的环境。两者并行存在、不互替。
• STUN / ICE / hole-punch 自身 —— 中继是 hole-punch 失败后的兜底;前者放在客户端 / NSD 协调侧。
• 应用层策略 / 计费 / 审计 —— 由 NSN 与 NSGW 终结模式承担。