Files
shenleiandClaude Opus 5.5 dc1bfc99d2 Move mesh networking logic into the SDK and fix lifecycle bugs
SDK:
- Add build_config/migrate_config, mesh_cidrs, route_generation, health
  and start_bridged; expose abi_info (capability revision 2).
- Add wait_routes long-poll; stop wakes waiters, and context_free now
  stops the network immediately instead of waiting for waiters to time out.

Hosts:
- Dart: waitRoutes(), MeshProxySession route watcher, ABI capability check.
- Android: fix a deadlock where every VPN request waited on its own
  single-thread worker; requests are now async, status is served from a
  snapshot, and combined mode reports Partial when the mesh stops.
- macOS helper: mesh-only unified mode stops when the mesh is lost;
  installed_subnet_routes excludes the overlay.
- Lab: restore Partial sessions, write migrated profiles back, remove the
  unreachable TOML import dialog; native test now connects via the form.

Docs updated accordingly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 18:17:42 +09:00

48 lines
5.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# macOS 系统组网开发版
MeshPort 保留两种独立模式:默认 `application` 只服务通过 SDK 发起的连接;`system_vpn` 创建 macOS utun,使其他应用的普通系统 TCP/UDP socket 可以访问虚拟网段。Flutter Lab 的设置页可选择模式。
## 配置与路由边界
```toml
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 秒更新,系统路由定期重新同步;安装失败重试,公告撤回删除路由。helper 是串行的请求/响应进程,由 GUI 状态轮询驱动,因此仍用轮询读取 `mesh_cidrs`,不使用 `wait_routes`;统一模式 status 的 `installed_subnet_routes` 不含虚拟网段,与 Android 一致;仅组网的统一模式在 `health.mesh_routable` 失效时整体停止(与 Android 一致),联合模式则保持代理并报告 `Partial`。
原生调用超过 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](android.md)。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 `migrate_config` 删除该字段并改用自动学习。直接使用 SDK 的旧配置也可调用该操作或手动移除此字段。
虚拟网段与本机现有接口重叠时,系统模式启动由 SDK 拒绝(“overlay overlaps an existing interface”),macOS helper 与 Android 服务不再各自预检。Android 上另一应用仍活动的 VPN 接口若与虚拟网段重叠,同样会被拒绝。自动子网是 IPv4;移动端、Windows 的打包与实际互通尚待验证。