Files
MeshPort/docs/development-validation.md
shenandshen c94143dfae Keep macOS client running in the menu bar when its window closes
Retain the main Flutter window, add reopen and explicit quit actions, and preserve its controller while hidden. Fix native test host paths and cover the window and menu lifecycle with XCTest.
2026-10-12 18:46:53 -07:00

129 lines
16 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.
# 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 日志](../outputs/validation/macos-unified-tun-20261011.log),日志仅含本机测试网络,不包含用户网络配置。
## 构建产物
- 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 结果。
页面和限制见 [界面实现清单](ui-implementation.md);使用方法与模块边界见 [客户端运行控制](client-runtime.md)。
## 2026-10-11:高级客户端功能
已追加自动订阅更新、source/binary 与内联规则集、DoH/DoT、macOS/Android 原生文件和二维码导入、应用启动自动连接与 macOS 13+ 登录项设置;自动选出口按要求不实现。使用入口、缓存范围和平台差异见 [高级客户端功能](advanced-client-features.md)。
- Flutter 全量测试:34 项通过,3 项专门环境/UI 开关测试跳过;Rust/Go 动态库生命周期测试实际执行。
- Go 全量 `test -race ./...` 和 `vet ./...` 通过;新增真实 DoH / DoT 解析、规则集组网优先、HTTPS source 自动刷新、下载失败保留有效规则和直连模式暂停代理 DNS / 规则集测试。
- 并发测试暴露 sing-box 1.14.3 远程规则集读取与更新的竞争,已用 [固定版本补丁](../engines/singbox/patches/README.md) 修复,复现测试继续保留。
- 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 验证记录](../outputs/validation/android-client-20261012.md)。测试使用 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` 已覆盖安装并打开,保留现有配置。此次只修改方向配置,未自动开启手机相机或扫描用户二维码。
### macOS 关闭窗口与菜单栏驻留
MainFlutterWindow.close 改为隐藏窗口,保留 Flutter 控制器和网络会话;取消最后窗口关闭时退出。AppDelegate 强持有主窗口与状态栏项,顶部图标提供“打开 MeshPort”和“退出 MeshPort”;Dock 重新打开同样恢复原窗口,不创建第二个引擎。关闭主窗口时取消正在进行的相机扫码。
原生 XCTest 两项通过:performClose 隐藏窗口但保留同一控制器,菜单打开动作恢复保留的窗口,退出项明确指向 NSApplication.terminate。修复了原有 RunnerTests 仍引用 meshport_lab.app 的 TEST_HOST 和 scheme 名称。使用隔离预览验证关闭后进程保留、明确退出后进程消失;界面工具无法直接读取状态栏项,其打开动作由原生检查覆盖。未在本轮切换真实 VPN 连接。
普通入口产物 `outputs/macos/MeshPort-0.1.0-menubar.app` 及 ZIP;未开启 MESHPORT_UI_PREVIEW。构建和深度严格签名验证通过,本机开发签名。测试预览已退出,原有配置未改动。