feat(client/macos): P1 方案B 骨架 — System Extension + NETunnelProviderManager 接线
ci-pangolin / Lint — shellcheck (push) Has been cancelled
ci-pangolin / OpenAPI Sync Check (push) Has been cancelled
ci-pangolin / Redline Scan — 脱敏 (UI 文案) (push) Has been cancelled
ci-pangolin / Flutter — analyze + test (push) Has been cancelled

把 PoC 的 sudo sing-box 外部二进制换成自包含、免 root 的 NEPacketTunnelProvider
(System Extension)+ 嵌入 libbox 的生产架构铺好骨架(不破坏现有 PoC 构建)。

- PacketTunnel/:扩展 target 源 — PacketTunnelProvider(LibboxSetup→NewService→start,
  openTun 建 NEPacketTunnelNetworkSettings)、Info.plist(NEProviderClasses)、
  entitlements(packet-tunnel-provider-systemextension + App Group)
- Runner/VpnChannel.swift:主 app 经 NETunnelProviderManager 启停 + 状态/速率回传,
  对齐 Dart 侧 VpnNativeBridge 的 pangolin/vpn channel 契约
- vpn_bridge_provider.dart:kUseNativeVpnMacOS 开关(默认 false,联调通过后置 true)
- docs/p1-macos-system-extension.md:文件清单 + Xcode/签名步骤 + 待办
  (Team BYL4KQHMTN;Network Extensions 已确认自助开通、无需 Apple 审批)

非破坏:新源文件未入 build target、注册行/app-group entitlements 均注释、gate 默认 false。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
wangjia
2026-06-19 11:07:36 +08:00
parent 64a1a64c3f
commit b25c8bbc2c
10 changed files with 480 additions and 6 deletions
+10 -3
View File
@@ -94,8 +94,10 @@
## 6. 签名 / 权限 / 分发(上线硬门槛)
- **Apple Network Extensions entitlement**:需向 Apple **申请**(Developer 账号 →
Network Extensions capability,packet-tunnel-provider)。**审批是前置阻断项**,先提交。
- **Apple Network Extensions entitlement**:**已确认自助开通,无需 Apple 审批**——在
Identifiers → App ID 的 Capabilities 里直接勾 **Network Extensions** 即得
Packet Tunnel Provider(含 `-systemextension` 形态)。早年需申请的是 NEHotspotHelper(热点),
与我们无关。**故此项不再是阻断项。**
- **付费 Apple Developer 账号**(个人/公司)+ Developer ID 证书。
- macOS:sysex 必须 **Developer ID 签名 + Hardened Runtime + 公证**;首次启用 sysex 用户需在
「系统设置 → 隐私与安全性」允许。
@@ -126,6 +128,11 @@ libbox CommandServer ──(gRPC/IPC)──▶ 原生订阅速率/状态 ──(
2. **P1 · macOS System Extension(主力)**:新增 sysex target + NEPacketTunnelProvider +
App Group + 签名公证;`NativeVpnBridge` 经 method channel 启停;连接页接 libbox 状态/速率。
**达标即 macOS 不再需要外部 sing-box / sudo。**
🚧 **骨架已落**:App/扩展 entitlements(App Group)、`VpnChannel`(NETunnelProviderManager
启停+状态/速率回传)、`PacketTunnel/`(Provider+Info.plist+entitlements)、Dart 分派开关
`kUseNativeVpnMacOS`(默认 false)。**接线指南**:[p1-macos-system-extension.md](./p1-macos-system-extension.md)。
Network Extensions 权限**已确认自助开通、无需 Apple 审批**;Team ID `BYL4KQHMTN`
待人工:Xcode 建 target + 加 `Libbox.xcframework` + 移植 libbox 平台接口 + 签名公证。
3. **P2 · Android**:VpnService + libbox.aar + PlatformInterfaceWrapper(参考官方)。
4. **P3 · iOS**:复用 macOS PacketTunnel 代码 + iOS appex。
5. **P4 · Windows/Linux**:libbox 服务/helper + wintun / setcap。
@@ -134,7 +141,7 @@ libbox CommandServer ──(gRPC/IPC)──▶ 原生订阅速率/状态 ──(
## 9. 风险 / 阻断项
- **Apple Network Extensions entitlement 审批**(周期不定)——**最先提交**
- ~~Apple Network Extensions entitlement 审批~~ → **已排除**:自助开通,无审批(见 §6)
- 付费开发者账号 + 证书/公证流水线(CI 自动签名公证)。
- libbox 与节点 sing-box **版本/配置兼容**:`clientconfig.go` 下发的 JSON 必须被嵌入 libbox 接受
(已踩过 1.12+ DNS/urltest 坑,需对齐版本)。