如何在WaterWall链内使用WireGuard?链内VPN与裸IP包I/O完整指南
如何在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
- 外层 UDP 绑定地址、端口属于
UdpStatelessSocket(见 tunnels/UdpStatelessSocket/description.md) - 内层接口 IP(如
10.44.0.1/24)通常属于TunDevice或另一个包侧组件
📐 正确布局:节点顺序与方向自动解析
受支持的链形只有一个:
UdpStatelessSocket -> WireGuardDevice -> 包侧节点
三个必须知道的方向规则:
UdpListener不能替代UdpStatelessSocket。它同样只能放链首,且会拒绝下游的Init,无法作为 WireGuard 的传输适配器。- 方向是自动解析的。链装配完成后,层解析器(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)。 - 旧的
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 消息)
- 缓冲区必须是一个 IPv4 或 IPv6 包,提取其目的 IP
- 按最长前缀匹配
AllowedIPs选择对端 - 加密为 WireGuard 传输消息,写入对端当前 endpoint,发往
UdpStatelessSocket - 没有任何对端匹配时,数据包被直接丢弃
入方向(UDP 数据报 → 内层 IP 包)
- 数据报被解释为裸 WireGuard 消息体,识别消息类型(握手 / Cookie 应答 / 传输数据)
- 解密并认证后,验证解密结果确实是 IP 包
- 内层源 IP 必须通过该对端
AllowedIPs校验 - 通过后才转发到内层包侧
与缓冲区相关的细节:节点声明 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 集成测试,可以直接用来验证本地构建:
- UDP 无状态套接字包回环:两个
WireGuardDevice跨真实 UDP 回环套接字,用包模式的TesterClient/TesterServer打通,同时覆盖AllowedIPs路由与传输加密(tests/cases/wireguard_udpstateless_packet_roundtrip/README.md) - 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用例做端到端回归验证