Files
MeshPort/docs/system-vpn.md
T

5.2 KiB
Raw Blame History

macOS 系统组网开发版

MeshPort 保留两种独立模式:默认 application 只服务通过 SDK 发起的连接;system_vpn 创建 macOS utun,使其他应用的普通系统 TCP/UDP socket 可以访问虚拟网段。Flutter Lab 的设置页可选择模式。

配置与路由边界

ipv4 = "192.168.20.5/24"
listeners = []
[[peer]]
uri = "tcp://your-server:52015"
[network_identity]
network_name = "your-network"
network_secret = "your-secret"
[runtime]
mode = "system_vpn"

本阶段仅支持 macOS、静态私有 IPv4,前缀 /16 到 /30。虚拟地址必须唯一。helper 在启动前检查已有接口的 IPv4 网段,重叠时拒绝启动;同时使用 EasyTier GUI 时应先断开冲突网络。当前不支持系统模式 DHCP、本机子网发布、出口节点或默认路由。两种模式均自动学习符合规则的节点公告子网。系统模式安装相应 OS 路由;应用内模式仅供 SDK TCP/UDP 连接访问,不配置系统 DNS。

Rust 的 system-vpn feature 是显式编译开关;默认 SDK 构建保持应用内模式。系统模式使用操作系统 socket,不能调用应用内模式的 connect_tcp/listen_tcp/bind_udp;Lab 的单次 TCP/UDP 探测自动改用系统 socket。批量 UDP 线路采样仍属于应用内模式。

启动和生命周期

运行 scripts/run-lab-macos.sh,它构建并启动包含动态库与 helper 的开发应用。系统模式启动时 macOS 请求管理员授权;Flutter UI 不提权,独立 helper 创建网络接口。控制通道是当前用户私有临时目录中的 Unix socket,helper 校验对端 UID,限制请求大小与允许的操作。断开连接停止引擎,但应用存活期间保留已授权 helper 和控制通道,使用每 30 秒一次的空闲心跳支持下次连接复用授权。退出应用关闭控制通道并清理 helper;控制通道异常关闭或空闲超时也会停止引擎,临时目录由 Dart 清理。虚拟网段在启动前检查冲突。自动公告子网只允许私有 IPv4 /16 至 /32,最多 32 项(CIDR 排序后截取);过滤默认路由、公网、过宽网段、虚拟网段及本机接口重叠。接口缓存每 2 秒更新,系统路由定期重新同步;安装失败重试,公告撤回删除路由。

原生调用超过 60 秒时 helper 退出,以关闭 utun 文件描述符;Dart 控制请求超时为 30 秒。

设置页支持自动保存和独立的自动连接开关。配置保存在 ~/Library/Application Support/MeshPort/,代理文件为 proxy-profile.json,组网文件为 network-profile.toml;目录权限 0700、文件权限 0600,内容为明文,使用原子写入。启动时尝试无弹窗迁移旧 Keychain 配置;需要授权时在设置页点击“迁移旧配置”,保留旧备份且不覆盖已有本地配置。未编辑的导入配置保留高级参数;修改表单后使用表单生成的配置。

发布边界

这是开发版 helper 方案,使用管理员授权。Release 打包优先使用可用的 Apple Development 身份保持签名稳定,没有身份时使用 ad-hoc;尚未完成 Developer ID 签名、公证或 Network Extension 发布流程;macOS App Sandbox 已为此开发方案关闭。Android VpnService 已接入,并通过隔离真机 TCP/UDP 和自动公告路由验证,详见 Android。iOS Packet Tunnel、移动端长期后台恢复仍待验证。

显式特权自检:sudo target/debug/meshport-vpn-helper --self-test。自检通过 loopback 建立两个隔离的 EasyTier 节点,使用 10.253.77.0/24 作为客户端虚拟网段,自动学习另一节点发布的 10.253.78.0/24,验证额外子网路由以及普通系统 TCP/UDP 经 utun 回显、默认路由保持不变、公告撤回后的路由删除和停止后的接口删除。最多运行 45 秒;阶段日志写入 /tmp/meshport-vpn-self-test-<pid>.log,不写网络密钥。

与其他 TUN 共存

macOS 的节点连接使用物理网卡候选,IPv4/IPv6 都排除其他 VPN 的 utun;不会将默认出口探测到的代理 TUN 地址重新加入候选。硬件检测在阻塞线程池等待子进程,避免嵌入宿主的异步信号处理影响冷启动。诊断中的 connectivity.bind_device 和 interface_ipv4s/interface_ipv6s 可确认实际候选。此调整由应用内和系统模式共用,不修改其他 VPN 的默认路由或配置。

例如 Redmi_AX6 已发布 192.168.21.0/24,Lab 虚拟 IP 为 192.168.20.4/24:无需填写远端子网。节点列表显示发布子网,两种模式的概览显示自动接入网段。该列表是通过规则的目标路由投影,不代表每一条 OS 路由安装均成功;实际系统路由可用 route 命令确认。

保留 v2rayN TUN,先用 route -n get 192.168.21.201 检查更具体的 /24 路由是否指向 MeshPort 的 utun。只设置 v2rayN “直连”规则不能建立 EasyTier 子网路由。如路由仍被代理接管,再检查 TUN 路由排除配置;不要依赖变化的 utun 编号设置永久路由。

旧版 runtime.subnet_routes 已移除;Lab 恢复旧版已保存单行配置时会删除该字段并改用自动学习。直接使用 SDK 的旧配置应移除此字段。自动子网是 IPv4;移动端、Windows 的打包与实际互通尚待验证。