Files
MeshPort/docs/advanced-client-features.md
T

67 lines
9.2 KiB
Markdown
Raw 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。出口仍由用户手动选择;本轮按要求不实现自动测速选出口。
| 功能 | macOS | Android |
| --- | --- | --- |
| 订阅定时更新 | 应用运行期间 | 应用运行期间 |
| 内联 / HTTPS source、binary 规则集 | 已接入引擎 | 已接入引擎 |
| 普通 DNS、DoH、DoT | 已接入引擎 | 已接入引擎 |
| 代理节点 / TOML 文件导入 | NSOpenPanel | 系统文档选择器 |
| 相机扫码 / 二维码图片 | AVFoundation + Vision | 内置 ZXing 扫描与图片解码 |
| 应用启动后自动连接 | 已接入 | 已接入 |
| 登录时启动 | macOS 13+ 系统登录项 | 不支持,未实现 Android 开机广播连接 |
Android 本轮已编译,按用户安排暂不安装真机。macOS 图片二维码入口已实际验证;相机权限、真实登录启动和自动连接恢复仍需要用户环境验证,未为测试开启用户的登录项或自动连接开关。
## 使用入口
- **代理 → 订阅管理 → 编辑订阅**:启用自动更新,选择 15 分钟至 7 天的间隔,返回代理页点击“安全保存配置”。定时器每分钟检查到期项;应用重开也检查逾期项。
- **代理 → 编辑普通规则**:添加、排序、启停规则集。普通规则先匹配,随后规则集,再使用默认出口;组网有效子网和已撤销子网保护始终在前。绕过中国大陆模式同样执行自定义规则及规则集,并优先于私网和大陆 IP 预设。全局 / 直连模式暂停普通规则和规则集。
- **代理 → 编辑 DNS**:启动解析器仍为 IP;直连和代理解析器可填写 IP、`https://主机/dns-query` 或 `tls://主机:853`。DoH 默认 443、DoT 默认 853;TLS 校验保持开启。代理 DNS 经手动所选节点;解析器主机名由独立启动 DNS 解析,避免循环依赖。仅组网模式不接管互联网 DNS。
- **代理 → 导入与预览**:选择文件、相机扫码或二维码图片。只填入草稿,点击“解析并预览”后确认导入。HTTPS 订阅链接可以选择“作为订阅地址添加”。导入普通 sing-box JSON 只提取节点,不能覆盖受管理 TUN、DNS 和组网路由。
- **组网配置**:通过组网页表单填写;原 TOML 导入对话框已移除。保存过的完整 TOML 在未修改表单时原样保留。
- **设置 → 启动与后台**:分别选择自动连接与 macOS 登录启动。登录项需要系统批准时会显示实际状态和系统设置入口;Android 自动连接指打开 APP 后连接,不代表开机后台建立 VPN。
## 更新与缓存行为
普通规则、规则集的匹配策略以及自定义规则模式的默认策略提供四项:**代理、直连、组网、拒绝**。代理使用当前所选节点,直连使用本机网络,拒绝终止匹配连接。组网仅允许已接入的 IPv4 组网目标;需要先启用“代理 + 组网”,并由对端发布对应网段。未接入、已撤销或组网出口不可用时拒绝连接,不回退到代理或直连。
例如让 `192.168.50.0/24` 走组网:在对端发布此子网并确认本机已收到有效路由,再添加普通规则,类型选择 IP 网段、内容填写 `192.168.50.0/24`、策略选择“组网”,保存并重连。本地分流规则不会创建或发布远端路由。受管理的有效组网路由和撤销保护始终优先于普通规则;绕过中国大陆模式也可追加此规则。当前不支持 IPv6 组网网段。
订阅只替换自己的来源节点,保留手动节点、其他订阅及相同节点的 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 规则列表读写未完整同步。项目保留固定版本的最小源码修补,详情见 [补丁说明](../engines/singbox/patches/README.md)。`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](https://developer.apple.com/documentation/servicemanagement/smappservice)、[Android 文档选择器](https://developer.android.com/guide/components/intents-common#Storage) 与 [ZXing Android Embedded](https://github.com/journeyapps/zxing-android-embedded) 接入;后者固定 4.3.0,采用 Apache-2.0 许可证。DNS 采用 sing-box [HTTPS](https://sing-box.sagernet.org/configuration/dns/server/https/) 和 [TLS](https://sing-box.sagernet.org/configuration/dns/server/tls/) 传输。
## 绕过中国大陆预设
代理页的“普通互联网流量模式”新增“绕过中国大陆”。无需配置规则集:引擎使用 SagerNet 的 [geoip-cn 二进制规则集](https://github.com/SagerNet/sing-geoip/tree/rule-set),通过所选代理首次下载并每 24 小时更新。目标大陆 IP 与普通私网直连,其余目标走代理;组网有效前缀与已撤销前缀保护先于普通私网和大陆规则执行。
域名经真实 IP 解析后匹配,包括 FakeIP 恢复域名后的解析;当前引擎仍以 IPv4 为主。判断按目标 IP,不能保证“中国网站”全部直连。远程列表首次下载失败时连接失败,后续更新失败保留会话内有效列表;跨 APP 重启离线缓存尚未接入。
预设先执行自定义规则、规则集,再执行普通私网及大陆 IP 直连,最后使用所选代理;组网路由和失效保护始终在最前。自定义默认动作仅在自定义规则模式生效,绕过中国大陆的兜底始终为所选代理,不覆盖保存内容。`meshport-geoip-cn` 为预设保留的规则集标识,用户规则集不能占用。全局模式不加载大陆 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 客户端核心默认启用,旧保存配置重载时同样启用。未使用该字段的旧原始引擎调用保持兼容。