如何在WaterWall链内使用WireGuard?链内VPN与裸IP包I/O完整指南

原创2026-11-18 04:55:5424 阅读

如何在WaterWall链内使用WireGuard?链内VPN与裸IP包I/O完整指南

WaterWall 是一个用 C 语言编写的隧道与代理运行时,通过 JSON 把一个个小节点串成网络链路。本文聚焦它的链内 WireGuard 实现——WireGuardDevice 节点:把 WaterWall 节点链直接变成一个真正的 WireGuard VPN 端点,支持裸 IP 包 I/O,无需创建内核 WireGuard 接口即可与标准 WireGuard 客户端互通。

🧩 什么是"链内 WireGuard"?

WaterWall 的核心思路是:每个节点只做一件事,通过 next 字段按名字串成链,回复数据沿链返回(见项目主文档 readme.md)。WireGuardDevice 正是遵循这一思想的 WireGuard 实现,它是一个纯包隧道(packet tunnel):

  • 内层一侧:IPv4 / IPv6 裸 IP 包
  • 外层一侧:裸 WireGuard 握手 / Cookie / 传输数据消息

两个关键设计点(详见 tunnels/WireGuardDevice/description.md):

  • WireGuardDevice 不自己打开 UDP _socket,也不创建操作系统的 WireGuard 接口
  • 它是链上的"一个普通节点",加密、对端状态、路由、握手、keepalive、rekey 全部由它承担

这就是"链内 VPN"的含义:WireGuard 协议栈被封装成链中的一个节点,可以像积木一样和 TUN 设备、UDP 套接字、包转换节点自由组合。

🎯 角色分工:三类节点各司其职

在 WaterWall 里,WireGuard VPN 由三类节点协作完成:

节点 职责
UdpStatelessSocket 拥有外层 UDP 套接字,绑定监听地址/端口,收发 UDP 数据报(只能放在链首)
WireGuardDevice WireGuard 加密与认证、对端状态、AllowedIPs 路由、握手、keepalive、rekey
TunDevice / RawSocket / PacketsToConnection / PacketsToStream 等 拥有内层裸 IP 包一侧(TUN 设备、裸套接字或包/流转换)

典型拓扑如下(客户端与服务器各一条链):

客户端机器:
UdpStatelessSocket -> WireGuardDevice -> TunDevice

服务器机器:
UdpStatelessSocket -> WireGuardDevice -> TunDevice / PacketsToConnection

📐 正确布局:节点顺序与方向自动解析

受支持的链形只有一个:

UdpStatelessSocket -> WireGuardDevice -> 包侧节点

三个必须知道的方向规则:

  1. UdpListener 不能替代 UdpStatelessSocket。它同样只能放链首,且会拒绝下游的 Init,无法作为 WireGuard 的传输适配器。
  2. 方向是自动解析的。链装配完成后,层解析器(layer solver)会判定两侧邻接边的域:解析出的 L3 边是内层包侧,L4 边是外层传输侧。两侧必须恰好解析为一个 L3 和一个 L4,否则启动直接失败,诊断信息为 chain layers must resolve exactly one L3 packet side and one L4 transport side(对应测试 tests/cases/wireguard_ambiguous_layers/README.md)。
  3. 旧的 transport-direction 配置项已移除,配置后会报错 transport-direction is no longer supported(对应测试 tests/cases/wireguard_transport_direction_removed/README.md)。

💡 如果复杂拓扑让解析器无法判定两侧角色,请添加显式的包/流桥节点(如 PacketsToStream 或 StreamToPackets)帮助分层解析。

⚙️ WireGuardDevice 配置速查表

字段 层级 必填 说明
privatekey settings ✅ Base64 编码的 32 字节 WireGuard 私钥
peers settings ✅ 对端数组,非空,最多 32 个
peers[].publickey peer ✅ Base64 编码的 32 字节对端公钥
peers[].allowedips peer ✅ 逗号分隔的 CIDR(IPv4/IPv6 均可),每对端最多 16 条
peers[].endpoint peer ✅ host:port / ipv4:port / [ipv6]:port;主机名仅在启动时解析一次
peers[].presharedkey peer ❌ 可选的 Base64 32 字节预共享密钥
peers[].persistentkeepalive peer ❌ 保活间隔(秒),0–65535,默认 0(关闭)
auth-client-node-name settings ❌ 在传输侧内部创建 UserController(见下文注意事项)

最小配置骨架:

{
  "name": "wg-device",
  "type": "WireGuardDevice",
  "settings": {
    "privatekey": "<base64-32-byte-private-key>",
    "peers": [
      {
        "publickey": "<base64-32-byte-peer-public-key>",
        "allowedips": "10.44.0.2/32,10.55.0.0/16",
        "endpoint": "vpn.example.com:51820",
        "persistentkeepalive": 25
      }
    ]
  },
  "next": "packet-side"
}

📝 可运行的客户端配置示例

下面是一段来自官方回环测试的真实配置节选(测试用例:tests/cases/wireguard_udpstateless_packet_roundtrip/config.json),客户端一侧由三个节点组成:

{
  "name": "wg-client",
  "type": "WireGuardDevice",
  "settings": {
    "privatekey": "0MHoX6RogAEFxKF7c5E84tA1Qy3l9u8IzJfgcVt4B2Y=",
    "peers": [
      {
        "publickey": "GnRcOavdc180YrXak138cZxWlMoEUZL0Mg/ZyWhLBgo=",
        "allowedips": "0.0.0.0/0",
        "endpoint": "127.0.0.1:26751",
        "persistentkeepalive": 1
      }
    ]
  },
  "next": "wg-packet-bridge"
}
{
  "name": "udp-client",
  "type": "UdpStatelessSocket",
  "settings": {
    "listen-address": "127.0.0.1",
    "listen-port": 26750
  },
  "next": "wg-client"
}

服务器一侧结构相同:UdpStatelessSocket -> WireGuardDevice -> 包侧终端节点(测试中是包模式的 TesterServer,真实场景换成 TunDevice、RawSocket 或 PacketsToConnection 等)。

⚠️ 注意:当前实现要求每个 peer 都必须配置 endpoint——即使该对端看起来更像"响应方"。会话状态过期重置后会回退到这个配置的 endpoint。

📦 裸 IP 包 I/O:AllowedIPs 双向路由

WireGuardDevice 把 AllowedIPs 用在了两个方向,这正是 WireGuard 的"加密密钥路由"(cryptokey-routing)模型:

出方向(内层 IP 包 → WireGuard 消息)

  1. 缓冲区必须是一个 IPv4 或 IPv6 包,提取其目的 IP
  2. 按最长前缀匹配 AllowedIPs 选择对端
  3. 加密为 WireGuard 传输消息,写入对端当前 endpoint,发往 UdpStatelessSocket
  4. 没有任何对端匹配时,数据包被直接丢弃

入方向(UDP 数据报 → 内层 IP 包)

  1. 数据报被解释为裸 WireGuard 消息体,识别消息类型(握手 / Cookie 应答 / 传输数据)
  2. 解密并认证后,验证解密结果确实是 IP 包
  3. 内层源 IP 必须通过该对端 AllowedIPs 校验
  4. 通过后才转发到内层包侧

与缓冲区相关的细节:节点声明 required_padding_left = 16,对应 16 字节 WireGuard 传输数据头的头部预留;认证标签(auth tag)追加在尾部。协议默认 MTU 为 1420(见 tunnels/WireGuardDevice/common/wireguard_constants.h)。

🔁 你应该了解的动态行为

这些参数都定义在 tunnels/WireGuardDevice/common/wireguard_constants.h 中,源码实现见 tunnels/WireGuardDevice/common/wireguard.c:

  • 400 ms 设备循环:启动后周期性运行,负责初始握手尝试、keepalive 发送、rekey 调度、会话过期清理
  • rekey 策略:约 120 秒(REKEY_AFTER_TIME)触发 rekey,180 秒(REJECT_AFTER_TIME)后拒绝;消息计数达到 2^60 也会触发 rekey
  • 漫游支持:每个对端有"配置的 endpoint"和"当前 endpoint"两个值;收到经认证的入站流量时,当前 endpoint 会更新为实际发送方地址端口
  • 抗 DoS:完整的 Cookie 机制(MAC1/MAC2 校验 + 加密 Cookie),每对端握手发起限速约 2 次/秒(见 wireguard.c#L873-L880),Cookie 密钥每 2 分钟刷新
  • 防重放:32 位滑动窗口位图(wireguard.c#L482-L543)
  • 当设置了 auth-client-node-name 时,WireGuardDevice 会在传输侧内部自建 UserController,布局变为 UdpStatelessSocket -> UserController -> WireGuardDevice -> 包侧节点;此时不要手动再放一个 UserController

⚠️ 常见错误与修复方法

错误信息 原因 修复
chain layers must resolve exactly one L3 packet side and one L4 transport side 两侧邻接节点无法同时解析出 L3 包侧与 L4 传输侧 添加显式桥节点(PacketsToStream / StreamToPackets)明确分层
transport-direction is no longer supported 使用了已移除的方向配置项 删除该配置,方向现在由层解析器自动判定
启动失败,提示缺少 next 或位置非法 UdpStatelessSocket 只能放链首,或误用 UdpListener 外层 UDP 一律用 UdpStatelessSocket 并放在链首
流量被静默丢弃 内层目的 IP 不匹配任何对端的 AllowedIPs 检查 allowedips 覆盖范围(最长前缀匹配)

✅ 验证你的 WireGuard 链:官方测试用例

仓库自带了完整的 WireGuard 集成测试,可以直接用来验证本地构建:

  1. UDP 无状态套接字包回环:两个 WireGuardDevice 跨真实 UDP 回环套接字,用包模式的 TesterClient / TesterServer 打通,同时覆盖 AllowedIPs 路由与传输加密(tests/cases/wireguard_udpstateless_packet_roundtrip/README.md)
  2. Cookie 过载回环:在回环基础上用中继 trace 验证 Cookie / 质询行为(tests/cases/wireguard_cookie_overload_roundtrip/README.md),配套脚本为 tests/run_wireguard_cookie_case.sh 与 tests/wireguard_cookie_relay.py

获取源码后,先发现用例属性,再通过 lane 包装器执行:

git clone https://gitcode.com/gh_mirrors/wa/WaterWall
ctest --preset linux -N -V -R '^waterwall\.wireguard_udpstateless_packet_roundtrip$'

📌 关键点总结

  • WireGuardDevice 是纯包隧道:内层裸 IP 包 ↔ 外层 WireGuard 消息,不开 UDP socket、不建内核接口
  • 唯一支持的链形:UdpStatelessSocket -> WireGuardDevice -> 包侧节点;UdpListener 不能当传输适配器
  • 方向自动解析,transport-direction 已移除;分层不明就加 PacketsToStream 类桥节点
  • AllowedIPs 双向生效:出方向选对端,入方向验源地址;不匹配即丢弃
  • 每个 peer 的 endpoint 目前必填;对端上限 32、CIDR 上限 16
  • 设备循环 400 ms 驱动握手/keepalive/rekey;内置 Cookie 抗 DoS 与 32 位窗口防重放
  • 用仓库自带的 wireguard_udpstateless_packet_roundtrip 用例做端到端回归验证
登录后查看全文
WaterWall