Files
MeshPort/docs/advanced-client-features.md
T
shenleiandClaude Haiku 5.5 2f185f914d Snapshot uncommitted work: proxy UI, sing-box integration, socks bridge
- Lab app: proxy panel, node editor, configuration and detail pages,
  responsive layout, and related tests
- Add meshport-socks crate and sing-box bridge scripts/docs
- Add singbox_flutter binding and meshport_client_core package
- FFI, VPN helper (unified mac path), and Android/macOS runner updates
- Docs for architecture, client runtime, UI design, and validation
- UI design output artifacts under outputs/ui

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
2026-10-12 10:06:15 +09:00

8.0 KiB
Raw Blame History

客户端自动更新、规则集与导入

更新:2026-10-11。出口仍由用户手动选择;本轮按要求不实现自动测速选出口。

功能 macOS Android
订阅定时更新 应用运行期间 应用运行期间
内联 / HTTPS source、binary 规则集 已接入引擎 已接入引擎
普通 DNS、DoH、DoT 已接入引擎 已接入引擎
代理节点 / TOML 文件导入 NSOpenPanel 系统文档选择器
相机扫码 / 二维码图片 AVFoundation + Vision 内置 ZXing 扫描与图片解码
应用启动后自动连接 已接入 已接入
登录时启动 macOS 13+ 系统登录项 不支持,未实现 Android 开机广播连接

Android 本轮已编译,按用户安排暂不安装真机。macOS 图片二维码入口已实际验证;相机权限、真实登录启动和自动连接恢复仍需要用户环境验证,未为测试开启用户的登录项或自动连接开关。

使用入口

  • 代理 → 订阅管理 → 编辑订阅:启用自动更新,选择 15 分钟至 7 天的间隔,返回代理页点击“安全保存配置”。定时器每分钟检查到期项;应用重开也检查逾期项。
  • 代理 → 编辑普通规则:添加、排序、启停规则集。普通规则先匹配,随后规则集,再使用默认出口;组网有效子网和已撤销子网保护始终在前。全局 / 直连模式暂停普通规则和规则集。
  • 代理 → 编辑 DNS:启动解析器仍为 IP;直连和代理解析器可填写 IP、https://主机/dns-query 或 tls://主机:853。DoH 默认 443、DoT 默认 853;TLS 校验保持开启。代理 DNS 经手动所选节点;解析器主机名由独立启动 DNS 解析,避免循环依赖。仅组网模式不接管互联网 DNS。
  • 代理 → 导入与预览:选择文件、相机扫码或二维码图片。只填入草稿,点击“解析并预览”后确认导入。HTTPS 订阅链接可以选择“作为订阅地址添加”。导入普通 sing-box JSON 只提取节点,不能覆盖受管理 TUN、DNS 和组网路由。
  • 组网配置导入:TOML 导入对话框同样支持文件、相机和二维码图片,校验后由用户点击连接。
  • 设置 → 启动与后台:分别选择自动连接与 macOS 登录启动。登录项需要系统批准时会显示实际状态和系统设置入口;Android 自动连接指打开 APP 后连接,不代表开机后台建立 VPN。

更新与缓存行为

订阅只替换自己的来源节点,保留手动节点、其他订阅及相同节点的 ID。选中节点被删除时清空选择,用户需重新选择,不自动换出口。空响应、仅含不支持节点的响应、网络失败或超出 64 KiB 保存限额,都保留旧配置;失败后 15 分钟重试。编辑期间不自动覆盖草稿。更新成功保存到平台安全存储,当前会话的实际出口保持到显式重连。

远程规则集支持 sing-box source JSON 和 .srs binary,初次连接下载、连接期间每 1–168 小时更新。它们可选择直连或所选代理下载。首次下载失败且没有缓存会阻止引擎启动;后续下载或解析失败保留最后一份有效规则。缓存与 FakeIP 一样属于当前引擎私有会话,公告引起的重建可复用,释放会话会清理,不保证 APP 重启后离线使用。

内联 source JSON 可直接编辑或从文件导入,最多 256 条 / 24 KiB。全配置仍受 64 KiB 存储与引擎输入限制。二维码必须有唯一内容;文本文件最多 1 MiB、图片最多 20 MiB / 2000 万像素。文件路径不交给特权 helper,客户端只读取用户选择的内容。

自动连接默认关闭,仅使用已保存的配置和入口,每次 APP 启动尝试一次。没有已保存网络时不靠私用默认文件自动连接;仅代理功能允许使用已保存代理配置独立启动。授权取消、代理节点缺失、现有 VPN 冲突等失败会显示实际错误,不反复抢占 VPN。

上游规则集修补与验证

本轮真实并发刷新测试发现 sing-box 1.14.3 规则列表读写未完整同步。项目保留固定版本的最小源码修补,详情见 补丁说明。scripts/go-local.sh 在忽略目录准备私有模块副本,通过备用 modfile 编译,不修改上游下载缓存;版本或原始文件哈希改变会要求重新审查修补。所有项目 Go 构建脚本均通过该入口执行。

修补同时将远程规则集下载限制为 30 秒、32 MiB、最多五次 HTTPS 重定向,拒绝 HTTP 降级和 URL 用户名密码。配置由 sing-box 原生规则集解析器校验,无法从规则集声明任意 TUN 或出口。

新增测试位于 advanced_profile_test.dart、advanced_pages_test.dart 与 advanced_config_test.go:订阅来源与选择保留、更新到期、配置往返、导入需预览、启动页只读状态、DoT 默认端口、真实 DoH / DoT 请求、规则集组网优先、HTTPS 规则自动刷新及失败保留。TLS 测试仅在隔离测试引擎信任临时测试证书,不修改系统证书。

原生接口依照 Apple SMAppService、Android 文档选择器 与 ZXing Android Embedded 接入;后者固定 4.3.0,采用 Apache-2.0 许可证。DNS 采用 sing-box HTTPS 和 TLS 传输。

绕过中国大陆预设

代理页的“普通互联网流量模式”新增“绕过中国大陆”。无需配置规则集:引擎使用 SagerNet 的 geoip-cn 二进制规则集,通过所选代理首次下载并每 24 小时更新。目标大陆 IP 与普通私网直连,其余目标走代理;组网有效前缀与已撤销前缀保护先于普通私网和大陆规则执行。

域名经真实 IP 解析后匹配,包括 FakeIP 恢复域名后的解析;当前引擎仍以 IPv4 为主。判断按目标 IP,不能保证“中国网站”全部直连。远程列表首次下载失败时连接失败,后续更新失败保留会话内有效列表;跨 APP 重启离线缓存尚未接入。

预设暂停自定义规则、规则集与自定义默认动作,但不覆盖保存内容。全局模式不加载大陆 IP 列表,普通流量全部走代理。原有自定义规则和直连模式仍保留;旧配置不自动切换。修改模式后保存,连接或重连生效,已有连接可能中断。

代理 DNS 防泄露

客户端默认启用受管理的 DNS 保护,适用于自定义规则、绕过中国大陆与全局代理。用户必须在 DNS 页明确填写代理解析器(IP / DoH / DoT),没有内置代理 DNS 服务商;缺少配置时连接前报错,不停止已有会话。普通域名查询和目标解析经所选代理发送,解析失败不尝试直连或启动解析器。

代理节点、解析器主机名仍可能通过直连启动 DNS 解析;使用 IP 地址能减少必要的启动查询,但 TLS 主机验证保持开启。配置的组网后缀 DNS 和撤销保护继续优先执行。直连模式不保证经代理的 DNS 隐私,仅组网不接管普通 DNS;应用内 SOCKS5 仅处理应用交给它的请求。统一 VPN 捕获的普通 53 端口 DNS 进入内部 DNS 模块,应用自带 DoH/DoT 仍按普通连接策略处理,不声称全设备所有解析都经过指定解析器。

本次没有加入退出 VPN 后的系统防火墙锁定,也未完成平台 IPv6、网络切换和全局 DNS 真机验收。单纯 DoH/DoT 或 FakeIP 不是这些边界的替代。

SDK 的原始 Go JSON 新增可选 dns_protection,启用后代理模式要求显式 proxy_dns_server;Flutter 客户端核心默认启用,旧保存配置重载时同样启用。未使用该字段的旧原始引擎调用保持兼容。