Files
MeshPort/docs/development-validation.md
T
shenandshen c7cc2aa865 Fix VPN internet connectivity and simplify client setup
Initialize Android physical interfaces and preserve macOS scoped routes. Add redacted diagnostics, default DNS, ordered auto-save, simplified controls, scanner rotation settings, and native regression coverage. Restore vendored build sources and document validation and stability checks.
2026-10-12 06:51:25 -07:00

15 KiB
Raw Blame History

2026-10-11 开发验证记录

2026-10-12:互联网统一 VPN 断网排查

实际用户节点的独立 HTTPS 检测返回 HTTP 204;关闭统一 VPN 后普通 HTTPS 同样成功。启用统一 VPN 后,自动采样确认普通域名解析超时、本机 SOCKS 返回网络不可达、固定 IP HTTPS 被重置。退出测试 APP 后物理默认路由和原有 DNS 恢复。

新增按引擎隔离、最多 32 条的运行时警告/错误记录,在内存中脱敏节点认证及 URL 凭据后投影至客户端日志;不将原始上游错误写入 stderr 或日志文件。实际错误明确为启动 DNS 的 dial udp 1.1.1.1:53: connect: network is unreachable,随后导致 cloudflare-dns.com 与网页解析失败。

修复为在接管全局路由前安装物理接口的 IPv4 scoped default route,供绑定物理接口的启动 DNS 和代理外层 socket 使用。复用既有 scoped route,停止时只删除本次创建且网关/接口仍匹配的路由。APP 已构建、签名验证通过;Rust 路由所有权测试、Go 并发测试及日志脱敏回归通过;Flutter 全量测试 42 项通过、6 项环境测试跳过。产物为 outputs/macos/MeshPort-0.1.0-unified-vpn-fix.app 及同目录 ZIP。

实际运行验收通过:2026-10-12 04:17(America/Los_Angeles),使用用户原有的 VLESS/Reality 节点、绕过中国大陆及代理加密 DNS 配置,统一 VPN 启用时,物理接口绑定 UDP connect 成功;普通 HTTPS、SOCKS5h HTTPS 和固定 IP HTTPS 均返回 HTTP 204;TUN DNS 返回有效 A 记录。采样后退出测试 APP,原有默认路由和 DNS 恢复,新增 scoped default 已移除,普通 HTTPS 再次返回 HTTP 204。短时验证覆盖本次 IPv4 互联网断网问题;IPv6 端到端、网络切换和长期运行仍需验证。

失败证据保留于本机 outputs/validation/macos-internet-tun-runtime-failure-20261012.log 和 macos-internet-tun-runtime-errors-20261012.log,原始运行采样不随源码上传。

修复成功证据保留于本机 outputs/validation/macos-internet-tun-fixed-20261012.log。

2026-10-11:代理连接诊断版

  • 修复代理 DNS 缺失时具体错误被替换成通用“操作失败”的问题;代理模式新增出口选择校验,重试清除旧错误。
  • 代理页新增“查看连接日志”。记录入口、功能、模式、节点数量、DNS 是否配置,以及配置校验、动态库加载、helper 授权、引擎启动的阶段与耗时。认证值在写入前脱敏,已替换草稿的凭据仍保持隐藏;不输出完整配置。
  • Go 引擎初始化/启动失败返回固定的阶段与错误分类,如 listen_port_in_use、permission_denied、dns_resolution_failed;不暴露上游错误中的认证或 URL 内容。
  • macOS 通过 OSLog 同步记录脱敏事件,subsystem 为 com.example.meshportLab,category 为 Runtime。真实启动和缺少 DNS 的失败均已在 APP 日志页及系统日志中验证。
  • 从固定 EasyTier 提交恢复被 **/build/ 忽略而遗漏的三个构建源码文件,并修正忽略规则。适配本机 Xcode,macOS 最低版本为 12.0。
  • Flutter 全量测试 42 项通过、6 项原生/环境依赖测试跳过;另启用 Rust/Go 动态库的配置往返与联合生命周期测试 11 项通过。Flutter analyze、Go test -race ./...、Go vet、APP 深度签名验证均通过。
  • 产物:outputs/macos/MeshPort-0.1.0-proxy-diagnostics.app,开发调试签名,构建号 20261012143711;ZIP 位于同目录。已启动该产物,用户将自行导入真实节点;尚未验证用户代理的互联网通信。

实际日志证据保留于本机 outputs/validation/proxy-diagnostics-macos-20261011.log。

本轮继续实现统一 TUN、主要 24 页 UI 和 FakeIP。Android 真机验证按用户要求暂缓,没有安装 APK,也没有替换正在使用的 macOS APP。

检查 结果和范围
Go test -race ./... 12 项顶层测试通过;模式、组网优先、真实 DNS/FakeIP TCP 通信、撤销 DNS、缓存重建、隔离草稿 HTTP 检测、诊断范围隔离及 ABI 生命周期
Go vet ./... 通过
Flutter analyze 无问题
Flutter 客户端测试 22 项通过,含原生 Rust/Go 联合启停、Partial、撤销保护、导入、认证隐藏、DNS/规则/组网表单
macOS APP 构建通过,包含统一 TUN helper;最终开发签名 codesign --verify --deep --strict 通过
Android ARM64 APK 构建通过;APK v2 签名、zipalign 16 KiB 校验通过,JNI/Rust/Go ELF LOAD 对齐均 ≥ 16 KiB
macOS 系统 TUN 普通 OS TCP/UDP 回显、公告子网自动接入、停止删除测试路由及保持默认路由均通过;范围仅为 10.253.88.0/24 测试网
Rust/FFI 映射子网 UDP 同一 /24 内相邻 /25 的纯 SDK 和 FFI 回归均通过;测试网关必须编译 proxy-packet,此前 FFI 超时来自测试构建缺少此组件
Android 联合 VPN 真机 未执行;入口明确标注待验证

Go/Rust 上游仍存在既有链接或弃用警告,不影响上述成功结果。第一次 Go 回归在沙盒中不能监听本机端口,放开本机测试端口后全部通过;不是功能回归。macOS TUN 首轮发现测试构造需要进入 Tokio runtime,随后修正 smoltcp TCP 回显服务提前关闭,以及错误地把出站 SDK UDP socket 当作入站服务的问题;UDP 自检使用远端映射子网和普通 OS 服务;正式流量通路已明确区分物理出口与 lo0 桥接出口;另修复有效前缀与保护前缀重复生成 TUN 路由,避免公告重建时重复删除导致清理失败,并新增回归测试。helper 自检网关已显式启用 proxy-packet,此前 UDP 包到达网关后没有进入子网转发,并非已证实的正式远端网关故障。新增不使用 TUN 的 SDK/FFI 回归覆盖这一场景。TUN 关闭后等待内部地址释放再重建;系统自检已验证重建后路由保留及普通 TCP/UDP 回显,尚不代表长时间稳定性验收。仅组网模式还移除了无对应公告的 IPv6 TUN 地址,避免上游根据空 IPv6 route_address 安装隐式 IPv6 默认路由。

系统自检记录见 macOS 统一 TUN 日志,日志仅含本机测试网络,不包含用户网络配置。

构建产物

  • macOS:apps/meshport_lab/build/macos/Build/Products/Debug/MeshPort.app,构建号 20261011095231。
  • Android:outputs/android/MeshPort-0.1.0-1791641256-debug.apk,ARM64 调试签名。

macOS 是本机开发签名,未公证;Android 是调试 APK,均不是正式发布版本。

验证边界

保留用户现有 v2rayN 与已连接 MeshPort,不做全局路由切换。因此 macOS 互联网统一 TUN 的全局 DNS、IPv6、网络切换与长时间运行未实测;不把仅组网的受限路由测试称作全局代理测试。Android 新增联合 VPN 的实际通信、后台和网络切换仍需真机。

公告变化重建 Go 引擎,会中断已有连接,尚无无损热更新。新版概览、代理与 DNS/FakeIP 页面已在 macOS 实际窗口检查,四个导航和编辑入口可达;全部页面的不同尺寸视觉验收仍需继续。

FakeIP 缓存在同一上下文重建时保留,最终释放清理,跨会话重新连接可能影响系统保留的旧 DNS 结果。

页面和限制见 界面实现清单;使用方法与模块边界见 客户端运行控制。

2026-10-11:高级客户端功能

已追加自动订阅更新、source/binary 与内联规则集、DoH/DoT、macOS/Android 原生文件和二维码导入、应用启动自动连接与 macOS 13+ 登录项设置;自动选出口按要求不实现。使用入口、缓存范围和平台差异见 高级客户端功能。

  • Flutter 全量测试:34 项通过,3 项专门环境/UI 开关测试跳过;Rust/Go 动态库生命周期测试实际执行。
  • Go 全量 test -race ./... 和 vet ./... 通过;新增真实 DoH / DoT 解析、规则集组网优先、HTTPS source 自动刷新、下载失败保留有效规则和直连模式暂停代理 DNS / 规则集测试。
  • 并发测试暴露 sing-box 1.14.3 远程规则集读取与更新的竞争,已用 固定版本补丁 修复,复现测试继续保留。
  • macOS:构建、深度签名验证通过;真实图片选择器读取测试 QR,并显示 1 个节点的预览,未保存或连接测试节点。
  • Android:ARM64 APK 已编译;相机、文档选择与新自动连接尚未真机验证。本轮未连接手机或安装 APK。
  • 未开启用户的登录项、自动连接或相机权限,未替换 /Applications/MeshPort.app,保留现有 v2rayN 与 MeshPort 连接。真实登录恢复、相机与公共加密 DNS 在当前网络的可达性需后续验证。

最终高级功能 APP 与 APK 的路径记录在 outputs/validation/advanced-client-20261011.md;APP 位于独立输出目录,避免覆盖用户正在查看的开发构建。

2026-10-11:macOS 连接配置修复

实际客户端连接失败来自 foreign_relay_bps_limit:上游默认 u64::MAX 投影为 JSON 数值后,被 Dart 舍入为浮点数,重新生成 TOML 导致 EasyTier 配置校验失败。FFI 投影和编辑器改为精确十进制字符串,客户端迁移旧的默认无限制值并拒绝其他不精确输入。

  • 原生 Rust FFI 投影测试通过;Flutter 原生配置往返与配置页面共 6 项测试通过;Flutter analyze 无问题。
  • Rust SDK/helper 与 macOS APP 构建通过,开发签名深度验证通过。
  • 修复版:outputs/macos/MeshPort-0.1.0-config-fix.app。
  • 经用户授权,将旧窗口中的代理配置保存到本机钥匙串;修复版重新启动后实际读到现有节点。当前代理 DNS 尚未填写,实际互联网 SOCKS5 验证等待用户选择 DNS。v2rayN 保持运行,未切换系统路由。

2026-10-12:互联网连接修复与配置简化

macOS 互联网统一 VPN 的实际故障是物理出口绑定后的 UDP DNS 请求返回 network is unreachable。helper 在安装 TUN 路由前补充并验证物理接口的 scoped default route;复用已有路由,只清理自己创建且仍匹配原网关/接口的路由。此前实测用户节点通过普通 HTTPS、SOCKS5 HTTPS、固定 IP HTTPS 和 TUN DNS 检查,停止后原 DNS、默认路由和互联网访问恢复。本机证据为 outputs/validation/macos-internet-tun-fixed-20261012.log。该修复的 IPv6、网络切换和长时间运行仍未验收。

本次简化配置与界面:

  • 首次启动默认“仅代理 / 全局代理”,macOS 和 Android 默认统一 VPN。恢复已有功能、节点和自定义 DNS;旧仅组网入口归一为组网功能。
  • 代理 DNS 默认 https://cloudflare-dns.com/dns-query;缺失或留空均使用此默认值,自定义值保留。直连模式仍使用直连 DNS。
  • 首次仅导入一个节点时自动选中;多个节点由用户选择。订阅更新删除原出口时不自动换到另一节点。
  • 配置修改自动按顺序保存,失败显示“重试保存”;运行中修改提示“重连应用修改”,由用户执行后才改变运行配置。概览与代理页共用连接动作。
  • 仅代理概览只展示连接信息、节点管理、日志和最近事件;网络入口、DNS/FakeIP、分流规则折叠到“高级设置”,组网高级配置同样折叠。分享链接的中文名称正确解码。

验证:Flutter analyze 无问题;启用 Rust/Go 动态库的 Flutter 全量测试 50 项通过,3 项需要专门开关的旧原生/UI 测试跳过。覆盖默认 DNS、首次节点选择、连续编辑保存顺序、保存失败重试、原生生命周期及不同窗口宽度。macOS 隔离预览窗口检查了概览、代理页和导入页布局;自动化输入受本机输入法影响,节点导入/选择通过 widget 测试验收。预览使用 MESHPORT_UI_PREVIEW=true,不读写用户配置、不初始化原生连接;交付 APP 未开启此标记。

产物:outputs/macos/MeshPort-0.1.0-simple.app 及同名 ZIP,包含 Rust/Go 动态库和 VPN helper;macOS 构建与深度严格签名验证通过。使用本机开发签名,未公证。本轮界面简化未再次切换实际系统 VPN;Android 共用配置逻辑已更新,未进行真机连接验证。

2026-10-12:Android 真机统一代理修复

MI 8 Lite(Android 15 / API 35、ARM64、4 KB 页面)完成新一轮真机验证。首次测试等待授权超时后,Flutter 自动卸载了临时 APP;已改用保留测试包并自动恢复普通 APP 的包装脚本,失败和成功均恢复安装,保留用户存储。

统一 VPN 实际复现“引擎 Running 但无法连接”,错误为 no available network interface。平台适配器的 Initialize 现在先发布物理接口列表给 sing-box NetworkManager。新增 Go 回归使用真实出站拨号:修复前复现同样错误,修复后 TCP 回显和 TCP/UDP socket 保护调用检查通过;Go 全量 race 与 vet 通过。

  • 系统组网 VPN:加密存储、应用内 TCP/UDP、Java/Dart 普通系统 TCP/UDP、公告子网安装与撤销全部通过。
  • 互联网统一 VPN:默认 Cloudflare DoH、普通 TCP/UDP、HTTPS 204、两次启动/停止和停止后 HTTPS 恢复全部通过。仅代理启动不依赖组网 TOML;首次单节点自动选择也在真机测试执行。
  • Android 增加脱敏 MeshPortRuntime 事件和 VPN 创建、引擎就绪、清理阶段日志;仅代理启动提示改为导入节点后连接。
  • 未保存测试节点;已退出测试 VPN、停止两套本机夹具并移除 adb reverse,手机恢复普通 APP。

详细结果和日志见 Android 验证记录。测试使用 Wi-Fi 与隔离 SOCKS5 出口;用户自己的代理节点、移动网络切换、长时间后台和 IPv6 上网仍需后续验证。

最终交付 outputs/android/MeshPort-0.1.0-1791811912-debug.apk,普通入口,开发签名,已安装并在 MI 8 Lite 前台打开;APK v2 签名、16 KB zipalign 校验通过。最终 Flutter analyze 无问题、50 项回归通过(3 项专门开关测试跳过)。

Android 扫码方向修复

用户反馈点击相机扫码后变成横屏。ZXing 4.3.0 的 CaptureActivity 库 manifest 默认 sensorLandscape;原有 setOrientationLocked(false) 只关闭额外锁定,不覆盖 manifest 的横屏要求。宿主 manifest 现在覆盖为 fullUser,跟随用户旋转设置,保留原有关闭方向锁定选项。合并 manifest 已确认 CaptureActivity 为 fullUser;构建、签名和 16 KB zipalign 检查通过。outputs/android/MeshPort-0.1.0-1791812247-debug.apk 已覆盖安装并打开,保留现有配置。此次只修改方向配置,未自动开启手机相机或扫描用户二维码。