P2WLAN:异地设备进同一张网,顺手把「连接到底通没通」写成了 53KB 规格

3,312 Star 的开源虚拟局域网工具:Rust 数据面 + Go 控制面 + Flutter 客户端,NAT 条件矩阵、五级代际围栏、22 条 CI 门禁。附实测数据、架构拆解与三个真实代价。

图:P2WLAN 官方封面

P2WLAN 是一款免费开源的虚拟局域网工具:给异地设备分配私有虚拟 IP,让它们像插在同一台路由器上一样互相访问。朋友异地联机、在外连家里的 NAS、连远端开发机,都不用逐个开公网端口。

项目:https://github.com/yhan-sun/p2wlan(3,312 Star · 154 Fork · MIT · Rust 主语言)

公众号上关于它的介绍已经不少。这篇补三件别处没说的:规模到底有多大、技术含量具体在哪、以及为什么它现在还不能「装完就用」。

本文所有数字均为 2026-11-04 通过 GitHub REST API 实测,非引用二手报道。


01 · 先看硬数据

维度实测值备注
Star / Fork3,312 / 154关注者远多于深度使用者
Watchers5极低,社区尚未形成
建库 / 最近 push2026-07-16 / 2026-11-02存续 111 天
Commit 总数1,835平均每天 16.5 次
贡献者10前两位占 93.6%
Release 总数165v0.1.68 → v0.1.171
PR / Issue236 / 33开着的 issue 仅 2 个
许可证MIT客户端 + Control + Relay 全覆盖

把贡献者名单摊开:

anYuJia              1041
yhan-sun              677
J-cloud-J              66
github-actions[bot]    15
dependabot[bot]        12
jwc1love               10
Libestor                8
P2WLAN maintenance      3
RoamerFly               2
YZoiu                   1

两个人写了 93.6% 的代码。 这不是缺点,但它决定了项目的真实形态:一个高密度小团队的产物,不是社区共建项目。Bus factor 事实上是 1.5。

代码规模(git/trees/main?recursive=1,2,451 项,未截断):

语言文件数体积其中测试
Rust92214.0 MB234 个 / 4.1 MB
Python(验收脚本)2513.5 MB—
Dart(Flutter GUI)2442.8 MB77 个 / 0.8 MB
Go(Control + Relay)1741.3 MB94 个 / 0.65 MB
文档(docs/)19190 KB—

测试代码占 Rust 总量 29%、Go 总量 50%。 这个比例在个人主导的网络项目里不常见。

版本节奏也值得记一笔:96 天 165 个 release,平均 1.7 天发一次。0.1.68 → 0.1.171,三个月涨了 103 个 patch 号。这既是活跃度也是不稳定性——含义是协议和行为还在高频变动,不是「稳定版在打补丁」。


02 · 它解决的是 NAT 那道墙

场景很朴素:家里开 Minecraft 服务器,朋友在学校连不上。

因为家庭路由器做 NAT,外部主动来的包进不来;而多数家庭宽带、校园网、移动网络根本没有可用公网 IPv4,还叠着 CGNAT 和企业防火墙。

P2WLAN 的做法是虚拟三层网络:给设备分配 10.x.x.x 虚拟 IP,应用照常用「IP + 端口」访问,不暴露任何公网端口。

但这里有个容易误读的地方,官方文档写得很明确:

P2WLAN 提供的是三层 IP 网络,不提供以太网二层广播桥接。

所以「依赖局域网广播自动发现」的游戏,装上也搜不到对方,必须手动填 IP。这条限制挡住了相当一部分「局域网联机」的想象空间,也是它和 ZeroTier(提供虚拟以太网 / 二层桥接)最本质的功能差异。


03 · 路径策略:三段式,5 秒直连窗口

默认先保留 5 秒直连窗口,同时并行准备 Relay;窗口结束后才允许启用已确认的加密中继。已建立的直连失活时允许 Relay 兜底,并继续尝试恢复直连。

对应用完全透明:虚拟 IP 不变,不用重配地址。

Relay 只在直连不可用时参与,转发的是密文——但节点标识、时间、包大小这些元数据仍对中继可见。这一点官方在隐私说明里没藏着。


04 · 真正硬的地方:打洞不是「支持/不支持」

多数同类软件在这件事上的表述是二元的:支持打洞 / 对称 NAT 用中继。P2WLAN 的 README 给的是一张 4×4 矩阵,按 RFC 3489 的经典 NAT 命名交叉:

本端 ↓ / 对端 →全锥形受限锥形端口受限锥形对称 NAT
全锥形🟢🟢🟢🟢
受限锥形🟢🟢🟢🟢
端口受限锥形🟢🟢🟢🟡 条件
对称 NAT🟢🟢🟡 条件🟡 双端条件

🟢 常规支持(常规 UDP 探测 + 经认证的源地址学习可建立直连)|🟡 条件支持(需结合实测端口规律、过滤规则与协调探测)

关键是最后一行:它不因为「对称 NAT」这个标签就放弃。 双端对称 NAT 时走的是三套策略的组合:

  • 端口预测 —— 学端口分配的步长与范围,按规律推出候选
  • 固定锚 —— 双方测量都支持时,用 2/4/8 个 socket 做首波覆盖
  • 有界生日探测 —— 端口域内按与域宽互素的步长扫描

文档里的实现约束细到这种程度:

单 socket 预测窗口最多 32 个候选。完整同方向尾段可生成有界的连续后继假设……观察到跳号时使用完整生日窗口,最多发布 96 个候选。

目标 IP 聚合上限为每秒 448、每 60 秒 4500;原有进程上限每秒 512、每 60 秒 6000 不变。

这是把「探测预算」当一等公民在管。原因不难理解:打洞本质是向陌生 IP 发包,在别人的网络里就是攻击特征。没有预算控制,这套东西在校园网和企业网会被当成扫描器处理。

hh2(Hard↔Hard 打洞协商)的启用条件是双方注册都声明 hh2_pair_nomination 和 hh2_plan_v2 两项能力,不满足就退回旧流程——用能力协商替代版本号判断,是这里最正确的工程决策。


05 · 架构:控制面与数据面彻底分开

模块技术职责
GUIFlutter登录、设备/房间管理、连接状态与诊断
Data PlaneRustTUN、路由、Peer、NAT traversal、加密会话、Relay fallback
虚拟网卡macOS utun / Windows Wintun / Linux TUN为应用提供普通的三层虚拟接口
Control PlaneGo + SQLite认证、设备注册、虚拟 IP、凭据、信令、Relay catalog
RelayGo票据校验、密文转发

数据面是自包含的 WireGuard-like Noise,用 X25519 + ChaCha20-Poly1305 + BLAKE2s。官方明确声明:

P2WLAN 不是官方 WireGuard 实现,也不声明 WireGuard 互操作兼容。

后果是双向的:不受 WireGuard 生态的协议约束,可以做自己的路径管理与中继票据;反过来,你无法用标准 WireGuard 客户端接入这张网。

一处值得单独提的架构原则,写在 docs/explanation/architecture.md 里:

daemon 是活动路径事实的唯一所有者,Control 不推断或猜测数据面路径。

Control 只持久化 daemon 主动上报的路径快照,不会根据 RTT、候选或在线标记自己推算「这条应该是直连」。这一条约束住了整类「界面显示 Direct、实际走中继」的经典故障。


06 · 最有价值的一份文档:路径可观测性

docs/reference/path-observability.md,53,119 字节,比 README 还长一倍。

它回答的问题只有一个:你怎么证明当前这条连接是 Direct,而不是你以为的 Direct?

答案是五级围栏(fencing):

含义:旧会话过期后上报的路径状态,无论 revision 编号多大,都不能覆盖新会话的记录。 设计目标直接写在文档里——

控制面可达或探测 ACK 不能单独证明业务互通。

也就是说,ping 通、登录成功、界面显示 Direct 标签,这三件事都不构成证据。判定必须来自当前 generation 下、完成加密确认、且经过实际业务验证的路径。

遥测还做了严格的数据最小化:只传路径类型(direct / relay / connecting / probing / fallback_relay / failed / none)、RTT、代际标识和迁移原因码。不传任何 IP、端口、候选 endpoint、密钥或报文载荷。

为什么这套东西重要?因为虚拟组网软件最典型的故障是「看起来通、实际走中继」——用户为此多付了延迟,却以为自己在直连。把「路径事实由 daemon 唯一拥有」写成架构原则,是这类工具里少见的严谨。


07 · 仓库里有一份写给 AI 的工程禁令

根目录有一份 3.6 KB 的 AGENTS.md,开头一句:

本文件是仓库级工作契约。任何 AI 或自动化代理在修改本仓库前都必须遵守它。

内容是负面清单,且几乎每条都对应一种真实翻车模式:

约束对应的翻车模式
单一状态所有者:影响连接正确性的事实只能有一个权威所有者两份状态各自演进,最后谁也不知道哪份是真的
有界资源:队列/缓存/重试必须回答容量、生命周期、取消条件、失败如何观测无限 channel、无限重试、无 deadline 等待、静默丢包
锁不跨不受控等待:禁止持锁做网络 I/O、sleep 或无上界 await死锁、优先级反转
错误是 API 的一部分:日志文本不是状态机接口用字符串匹配恢复控制流
生产路径不得用 panic 处理可被网络/输入/远端状态触发的失败一个畸形包打崩整个 daemon

配套的 scripts/quality/check_code_health.py 是个复杂度棘轮:历史热点相对 PR 基线只能缩小,不能扩大。

CI 有 22 条 workflow,命名直接暴露了验收口径:

nat-topology-gate · dplpmtud-required · path-state-machine-required
business-mtu-budget-required · mobile-lifecycle · windows-lifecycle
parallel-rooms · room-connectivity · rekey-reliability
security-audit-required · release-post-publish-audit

大多数开源网络工具只有一条 ci.yml。这里把「NAT 拓扑」「MTU 预算」「路径状态机」「重密钥可靠性」各自拆成必须通过的独立门禁——因为这些恰恰是最容易静默退化的地方。


08 · 界面:房间把「谁和谁互联」单独拎出来

图:P2WLAN 首页,网络状态与在线设备

图:设备列表,节点、速率与在线状态

客户端不只是一串 IP 列表。房间是它相对同类工具有辨识度的设计:

图:互联页面,多房间管理与连接延迟

一个 Minecraft 生存服一个房间,NAS 运维一个房间,开发测试一个房间——各自独立网络与虚拟 IP,不混在同一个设备列表里。加入方式支持房间号或邀请,成员能看在线状态、虚拟 IP、连接路径和延迟。

图:房间详情,虚拟 IP、连接路径与延迟

界面上 LAN Direct / Direct / Relay 三种标签是分开的,用户能直接判断当前到底直连还是绕中继。

没有图形环境的 Linux 服务器用 CLI + daemon,排障命令:

p2wlan status --json
p2wlan doctor
p2wlan route verify
p2wlan logs -f

09 · 三个必须说清的代价

① 没有默认服务器,冷启动就是一道墙

新安装不预填项目运营的 Control 或 Relay,也不自动注册账号。官方快速开始第一步就是「先准备 Control 地址」。

自托管路径是 Linux + systemd,发布 server-vX.Y.Z 独立包,普通部署不需要在服务器上装 Go 或 Node。

这是设计选择,不是缺陷(避免把所有用户绑到同一个中心)。但它意味着:「免费开源」和「零成本可用」是两件事。 服务器、域名、TLS 证书、中继带宽都由部署者承担。想临时和朋友联机又没有服务器,前期准备工作量不小。

② 0.1.x,且没有独立安全审计

项目自己在 SECURITY.md 里写得直白:

项目尚未完成独立安全审计,不声明安全认证;加密实现、CI 检查与发布清单不能替代独立审计。

对家庭测试和开发验证,了解边界后可以用;对企业核心系统,这条「未审计」就是硬拒理由。

③ 版本双命名空间,说明协议还在动

客户端 vX.Y.Z、服务端 server-vX.Y.Z,官方特意声明:

即使两个标签具有相同的数字后缀,也不表示它们指向同一个源码提交、同一次构建或同一组发布产物。

配合 hh2 的能力协商机制可以判断:协议还在快速演进,别指望版本号一致就能互通。


10 · 和 Tailscale / ZeroTier / EasyTier 怎么选

强项代价
P2WLAN房间式组织、图形客户端、直连优先 + 加密中继一体、三端 MIT 可自托管需自备 Control;三层网络不桥接广播;0.1.x 未审计
Tailscale托管控制面、WireGuard 数据面、成熟 ACL 与设备管理官方服务为主;双端 hard NAT 走 DERP 中继
ZeroTier虚拟以太网、二层桥接、可自建控制器配置重;对称 NAT 下易走中继
EasyTier去中心化 mesh、多协议传输、子网代理拓扑与协议配置由部署者负责

一句话分工:要省事选 Tailscale,要二层语义选 ZeroTier,要 mesh 拓扑选 EasyTier;要「朋友进一个房间就能联机」且想把服务器攥在自己手里,才是 P2WLAN 的位置。


11 · 给不同人的判断

  • 普通用户:想要开箱即用,现在不合适——没有公共 Control,你得先有台服务器。想玩,找一个愿意跑服务端的朋友。
  • HomeLab / 自建服务玩家:这是它的主场。三层网络足够 SSH、RDP、NAS Web 面板、数据库;房间把「游戏组」和「运维组」分开这点,比 Tailscale 的 ACL 更直观。
  • 企业 / 生产环境:不行。未审计 + 0.1.x + bus factor 1.5。
  • 做网络方向的人:这个仓库值得读源码,不是读 README。 三份文档按信息密度排序是 path-observability.md(53KB) > engineering-quality.md(27KB) > networking.md(24KB)。它们不是产品介绍,是设计规格——包括失败模式、预算上限、围栏规则。同类开源项目里,把「我如何证明我的直连是真的」写到这个程度的不多。

写在最后

这类工具最有意思的地方,不只是「能连上」,而是**「能证明自己是怎么连上的」**。

3,312 star 里,大概多数人只是觉得「异地联机」这个场景爽。但它真正的工程量花在了别处——NAT 探测预算、代际围栏、路径可观测性、复杂度棘轮。这些不进 demo,不影响 star 曲线,但它们决定了这东西在真实网络里会不会悄悄退化。

代价也清楚:三个半月 165 个版本、0.1.171、没有审计、没有公共服务器。

它现在是一份很好的工程样本,不是一个可以交给非技术朋友的成品。


数据来源:GitHub REST API 实测(2026-11-04 12:30 UTC),含 /repos、/commits?per_page=1(Link last page 1835)、/contributors?anon=1、/releases(165 页)、/search/issues、/git/trees/main?recursive=1(2,451 项未截断)。文档引文出自 README.md、docs/reference/networking.md、docs/reference/path-observability.md、docs/explanation/architecture.md、docs/explanation/engineering-quality.md、AGENTS.md、SECURITY.md、docs/reference/compatibility.md。截图取自项目官方仓库 assets/readme/。

未验证项:NAT 打洞实际成功率、与 Tailscale / ZeroTier / EasyTier 的功能对等度。本文只比较各项目文档中声明的策略,未做横向实测。