docs+test: macOS 隧道踩坑复盘/规则 + VPN 测试调研 + 黑盒测试工具
- docs/macos-sysext-realize-troubleshooting.html:补"运行时"章节(libbox 空指针、 接口时序、队列死锁、DNS 劫持)+ 运行时 checklist。 - docs/vpn-testing-research.md:VPN 测试调研(行业方法论 + GFW 专项 + Pangolin 分层测试项 + 三层测试工具设计)。 - CLAUDE.md:新增「client/ macOS 原生隧道」铁律章节(构建发版/系统扩展 realize 要求/ libbox+NE 集成/配置由服务端渲染/已知坑)。 - scripts/vpn_test.sh:客户端侧黑盒测试工具(出口 IP/DNS/可达性/延迟/吞吐/IPv6 泄漏, PASS/WARN/FAIL,可远程跑)。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JEHzjEcFzvGwgbxT6Wbt6c
This commit is contained in:
wangjia
@@ -82,3 +82,35 @@ cd web/website && npm run gen:tokens
|
||||
- `client/lib/pangolin_theme.dart` — 只含实现层（`PangolinScheme`/`PangolinText`/`PangolinTheme`），不含 token 数值。
|
||||
- `design/flutter/` 已删除；Flutter 组件 canonical 实现在 `client/lib/widgets/`，规格在 `design/preview/`。
|
||||
- **禁止**再向 `design/` 提交 Dart/TS 组件代码副本（会漂移）。
|
||||
|
||||
## client/ macOS 原生隧道(PacketTunnel 系统扩展 + 内嵌 libbox)
|
||||
|
||||
内嵌 sing-box(`Libbox.xcframework`)的 `NEPacketTunnelProvider` **系统扩展**(站外 Developer ID
|
||||
分发)。让它能被 `sysextd` 加载并真正连通踩了一长串坑,**改这块前必读**
|
||||
`docs/macos-sysext-realize-troubleshooting.html`。以下是铁律:
|
||||
|
||||
**构建 / 发版**
|
||||
- 一律走 `scripts/local_test.sh`(`build`/`notarize`/`copy`/`run`):Developer ID 签名 + 公证 + staple。
|
||||
- **每次构建必递增 `CFBundleVersion`**(`CURRENT_PROJECT_VERSION`)——否则 `sysextd` 视为同版本**不更新**,装上去跑的还是旧扩展。
|
||||
- SIP 开启的机器只接受**已公证**的 sysext;`client/macos/sign_libbox.sh` 在构建期以 Developer ID 重签内嵌 Libbox。
|
||||
|
||||
**系统扩展能被 realize 的硬性要求**(缺一即 `code=4` / 静默拒)
|
||||
- **自包含**:`PacketTunnel` target 设 `OTHER_LDFLAGS = ""`(切断继承项目级 CocoaPods 链接标志,否则会把 `flutter_secure_storage` 链进扩展);`Libbox.xcframework` **只 Link 不 Embed**(它是静态库)。验证:`otool -L` 扩展二进制应**零 `@rpath` 外部依赖**。
|
||||
- **bundle 名 = 标识符**:`PRODUCT_NAME = com.pangolin.pangolin.PacketTunnel`。
|
||||
- 扩展 `Info.plist` 必须有 **`NSSystemExtensionUsageDescription`**(网络扩展类别强制,主 app 的不顶用)。
|
||||
- **App Group 用 macOS 原生格式 `<TeamID>.<name>`**(`BYL4KQHMTN.com.pangolin.pangolin`,非 iOS 的 `group.` 前缀);`NEMachServiceName` 以其为前缀。
|
||||
- 沙箱扩展补 `network.client` / `network.server`;`get-task-allow=false` + 签名加 `--timestamp`。
|
||||
|
||||
**libbox / NetworkExtension 集成铁律**(改 `PacketTunnelProvider.swift` 注意)
|
||||
- `startTunnel` **必须在后台队列**执行 libbox 启动(`DispatchQueue.global().async`)——否则 `startOrReloadService` 在 provider 队列同步阻塞,与 `openTun → setTunnelNetworkSettings` 回调**三方死锁**(隧道卡 connecting 永不完成)。
|
||||
- `startOrReloadService(options:)` **传非空** `LibboxOverrideOptions()`(传 `nil` → libbox 解引用空指针 SIGSEGV,扩展进程崩溃)。
|
||||
- `startDefaultInterfaceMonitor` 要**阻塞到首个 path 更新再返回**(否则 sing-box 启动期拿不到默认接口,报 `no available network interface`)。
|
||||
|
||||
**配置由服务端渲染,客户端不拼**
|
||||
- sing-box 客户端配置由 `server/internal/httpapi/clientconfig.go::BuildClientConfig` 渲染、原样下发。
|
||||
- **TUN 模式必须有 DNS 劫持**:`route.rules` 首条 `{"action":"hijack-dns","port":[53]}`(排在 LAN 直连规则前)——否则发往隧道 DNS(172.19.0.2:53)的查询被 `172.16.0.0/12` 吞去直连,域名解析失败,**隧道连上也打不开网站**。
|
||||
- REALITY 数据口走 **节点 `endpoint` 的端口**(当前 443;受限网络常封高位端口如 11443,优先 443)。
|
||||
|
||||
**已知坑**
|
||||
- 开发机若是 **macOS 26 (Tahoe)**:`sysextd` 报 `no policy, cannot allow apps outside /Applications`(app 在 /Applications 也报)是 **Apple 回归**,本机调试需关 SIP 后 `systemextensionsctl developer on`;真实用户(macOS 14/15)不受影响。
|
||||
- #5 国内分流:客户端 `smartRoute` → `?split_cn=1` 下发远程 rule-set;**TODO 改本地 `.srs` 预取**,避免启动期下载。
|
||||
|
||||
Reference in New Issue
Block a user