P2WLAN

P2WLAN 是一个开源、P2P 优先、可自托管的虚拟局域网工具。它为设备分配私有虚拟 IP，让分布在家庭宽带、移动网络、校园网、云服务器等不同网络中的设备，能够像在同一个局域网里一样通信。

连接建立时，P2WLAN 会优先尝试 LAN Direct / 公网 UDP P2P；如果当前 NAT、防火墙或网络环境不允许直连，则自动回退到 Encrypted Relay。业务侧仍然使用同一个虚拟 IP，不需要为每台设备单独维护公网端口、动态域名或复杂路由。

首页 · 网络状态与在线设备	设备 · 节点、速率与在线状态
互联 · 房间管理与连接延迟	房间详情 · 虚拟 IP、连接路径与延迟

从全局网络状态、设备在线情况，到多房间管理、连接方式和端到端延迟，常用信息可以直接在客户端里看到。设备名称和截图数据均为演示数据。

P2WLAN 的目标不是替你定义业务，而是提供一张跨地域的虚拟三层网络。只要应用本身能通过 IP 通信，就可以把它放到这张网络上。

房间适合需要独立边界的临时或固定网络：例如一个 Minecraft 生存服、一次朋友联机、一组 NAS 维护设备，或者一个开发测试环境。客户端可以集中查看房间成员、在线状态、虚拟 IP、当前连接路径和延迟，不需要把所有设备混在同一个列表里。

前往 GitHub Releases 下载对应平台的最新版本。

打开客户端并登录；服务器或无桌面环境可使用 CLI：

p2wlan config set control https://control.example.com

打开客户端并登录；服务器或无桌面环境可使用 CLI：

p2wlan login -u your-name
p2wlan account show

在客户端启动网络，或在 CLI 中执行：

p2wlan up
p2wlan status

连接建立后，直接像访问普通局域网地址一样使用对端的 P2WLAN 虚拟 IP：

ping 10.20.0.5
ssh user@10.20.0.5

游戏服务器、NAS、Web 面板或数据库同理：应用只需要连接对端虚拟 IP 和对应业务端口。

客户端会显示 Peer 当前使用的路径。遇到问题时，可先运行：

p2wlan doctor
p2wlan logs -f

Linux CLI 也提供安装脚本：

VERSION=vX.Y.Z
curl -fsSL https://raw.githubusercontent.com/yhan-sun/p2wlan/$VERSION/scripts/install-linux-cli.sh -o /tmp/p2wlan-install.sh
sudo sh /tmp/p2wlan-install.sh --version "$VERSION"

Linux CLI 的房间管理、Direct/Relay 路径策略、路由修复、支持包和 systemd 部署说明见客户端指南与CLI 参考。常用命令还包括：

p2wlan room list
p2wlan room connect <房间号或房间 ID>
p2wlan route verify
p2wlan support-bundle --upload

自托管 Control/Relay 的安装、校验、systemd 启停、备份和升级见自托管指南与升级与恢复。服务端使用 server-vX.Y.Z 标签，客户端使用 vX.Y.Z 标签。

sudo ./scripts/install-server.sh --version server-vX.Y.Z --role all
sudo p2wlan-server status
sudo p2wlan-server doctor --service all
sudo p2wlan-server update --version server-vX.Y.Z
sudo p2wlan-server backup
sudo p2wlan-server rollback

发布后的服务端可以由本机上传，或让已安装 manager 的服务器自行拉取：

./scripts/deploy-server.sh --host <服务器地址> --user <SSH用户> \
  --version server-vX.Y.Z --start
./scripts/deploy-server.sh --mode fetch --host <服务器地址> \
  --user <SSH用户> --version server-vX.Y.Z --start

省略 --identity 时 SSH 会在终端提示服务器密码，远端 sudo 会提示管理员密码；密码不会出现在命令行。部署入口和 staging 变量由自托管指南与发布 workflow 共同定义，不把具体主机或私钥写入仓库。

P2WLAN 将连接控制和数据传输分开：

• Control Plane：身份、设备、虚拟 IP、凭据和信令。
• Rust daemon：虚拟网卡、路由、Peer、NAT traversal、加密数据面和路径选择。
• Relay：只在 Direct 不可用时参与，负责转发密文。

flowchart LR
    A[设备 A] <-->|"LAN Direct / UDP P2P"| B[设备 B]
    A -->|"认证 / 信令"| C[Control Plane]
    B -->|"认证 / 信令"| C
    A -.->|"Direct 不可用"| R[Encrypted Relay]
    R -.-> B

连接策略可以概括为：

LAN Direct → Public UDP Direct → Encrypted Relay

Direct 能否建立取决于两端真实网络环境。NAT、CGNAT、防火墙、云安全组等都可能阻止直连；此时 Relay 是后备路径，而不是对任意网络环境 P2P 成功率的承诺。

P2WLAN 使用自包含的 WireGuard-like Noise 数据面，并使用 X25519、ChaCha20-Poly1305、BLAKE2s 等密码学组件。P2WLAN 不是官方 WireGuard 实现，也不声明 WireGuard 互操作兼容。

新机器的完整配置、Windows 原生与 Docker Compose 示例见自托管指南。

Control Plane 和 Relay 位于 server/；Linux CLI / daemon 位于 Rust workspace。最小构建可以从仓库根目录执行：

cd server
go build -o p2wlan-control .
go build -o p2wlan-relay ./relay

CLI 和 daemon 可在仓库根目录构建：

cargo build --release -p p2wlan-cli -p p2wlan-daemon

生产部署还需要根据当前代码配置 HTTPS/WSS、数据库、认证密钥和 Relay 地址。README 首页只保留入口信息，具体配置请以 server/ 中的实现为准。

• 设备业务流量通过端点间的加密数据面传输。
• Relay 转发密文，不负责解密业务载荷。
• Relay 仍可能观察连接相关元数据，例如节点标识、时间和数据包大小。
• 项目处于 Preview，尚未完成独立安全审计。
• 不保证任意 NAT 环境都能建立 P2P 直连；Relay 可用性同样依赖 Control Plane 和 Relay 可达。
• 高敏感生产环境请在部署前自行完成安全评估。

凭据边界和安全限制见 SECURITY.md、隐私说明 与安全模型；发布资产对应关系见发布契约。

Flutter 开发和发布统一使用 Flutter 3.47.2 / Dart 3.13.2，仓库根目录 .fvmrc 是本地 FVM、CI 和发布流水线的版本来源。

仓库按职责拆分：

• apps/flutter_client/ — Flutter 客户端
• client/daemon/ — Rust daemon
• client/cli/ — Rust CLI
• client/tun/ — TUN / 虚拟网卡抽象
• client/crypto/ — 加密组件
• server/ — Go Control Plane
• server/relay/ — Go Relay

实现细节请优先以源码、测试和 CI 为准。

MIT