Files

T

wangjia e129f094c2 feat(ios): M3 PoC — PacketTunnelProvider + entitlement + 内存监控 [tsk_nsobbj_rJdy0]

### 新增文件
- client/ios/PacketTunnel/MemoryMonitor.swift
  周期打点 NE 进程内存（os_proc_available_memory iOS13+ / mach_task_basic_info 兼容
  iOS12）；每 10s 采样一次；availableMemory < 5MB 时输出 ⚠️ 警告；提供
  summaryString() 供 handleAppMessage/getMemory IPC 返回。

- client/ios/PacketTunnel/PacketTunnel.entitlements
  Extension 的 NE + App Group entitlement 文件；申请说明写入注释。

- client/ios/Runner/Runner.entitlements
  主 App 的 NE + App Group entitlement 文件；申请说明写入注释。

- doc/ne-entitlement-申请指引.md
  完整申请操作手册：Bundle ID 清单、Apple Developer Portal 步骤、
  专项审批英文申请文案（已脱敏，无红线词）、审批 lead time 说明。

### 修改文件
- client/ios/PacketTunnel/PacketTunnelProvider.swift
  完整 M3 实现（替换原骨架 TODO）：
  · startTunnel：解析 configJson（options/App Group 两路回退）→
    buildNetworkSettings → setTunnelNetworkSettings → setupTunBridge
    → startLibbox → startPacketBridging → memoryMonitor.start()
  · stopTunnel：memoryMonitor.stop() → stopLibbox → closeTunBridge
  · handleAppMessage：JSON IPC 协议（getStatus/getMemory/selectOutbound）
  · LibboxPlatformInterface 扩展（#if canImport(Libbox)）：
    openTun 返回 socketpair libbox 侧 fd，autoDetectInterfaceControl no-op，
    writeLog 转 os.log，useProcFS 返回 false
  · packetFlow 双向桥接（readFromPacketFlow/writeToPacketFlow 循环）
  · parseTunAddress/parseDNSServers 从 JSON 提取网络参数

- client/ios/Runner/VpnManager.swift
  · localizedDescription "穿山甲 Pangolin VPN" → "Pangolin 加速"（红线词修复）
  · 新增 appGroup 常量（group.com.pangolin.pangolinVpn）
  · start() 写入 App Group UserDefaults 缓存 configJson

- client/ios/Runner/Info.plist
  NSVPNUsageDescription "穿山甲使用 VPN…" → "Pangolin 使用网络加速通道…"（红线词修复）

- client/ios/PacketTunnel/Info.plist
  CFBundleDisplayName "穿山甲 Tunnel" → "Pangolin 加速通道"（红线词修复）

- client/ios/Runner.xcodeproj/project.pbxproj
  · Runner + PacketTunnel 所有 build config 添加 CODE_SIGN_ENTITLEMENTS
  · 新增 MemoryMonitor.swift 到 PacketTunnel Sources 构建阶段
  · 新增 Runner.entitlements / PacketTunnel.entitlements / MemoryMonitor.swift
    文件引用及分组

- app/kernel/build-ios.sh
  添加 M3 内存裁剪决策记录：gVisor→grpc→QUIC 优先裁减顺序及内存估算，
  等待真机 10min 压测结果后更新最终结论

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-13 17:44:11 +08:00

5.7 KiB

Raw Blame History

Network Extension Entitlement 申请指引

任务 tsk_nsobbj_rJdy0（M3 iOS PoC）
状态：申请文案已备妥，等待开发者账号侧操作

1. 需要申请的 Entitlement

Entitlement	值	申请对象
`com.apple.developer.networking.networkextension`	`packet-tunnel-provider`	主 App + Extension 各自的 Bundle ID
`com.apple.security.application-groups`	`group.com.pangolin.pangolinVpn`	同上（App Group 在两个 Bundle ID 间共享）

2. Bundle ID 清单

角色	Bundle ID
主 App	`com.pangolin.pangolinVpn`
PacketTunnel Extension	`com.pangolin.pangolinVpn.PacketTunnel`
App Group	`group.com.pangolin.pangolinVpn`

3. 申请步骤（Apple Developer Portal）

3.1 注册 App Group

登录 developer.apple.com → Certificates, Identifiers & Profiles
左侧 Identifiers → 点击 +
选择 App Groups → Continue
Description: Pangolin App Group
Identifier: group.com.pangolin.pangolinVpn
Continue → Register

3.2 配置主 App Identifier

Identifiers → 找到 com.pangolin.pangolinVpn
Capabilities → 勾选：
- ☑ App Groups → 选择 group.com.pangolin.pangolinVpn
- ☑ Network Extensions → 勾选 Packet Tunnel Provider
Save → Confirm

3.3 注册 PacketTunnel Extension Identifier

Identifiers → 点击 +
选择 App IDs → Continue → 选择 App Extension → Continue
Bundle ID: com.pangolin.pangolinVpn.PacketTunnel
Description: Pangolin Packet Tunnel Extension
Capabilities → 勾选：
- ☑ App Groups → 选择 group.com.pangolin.pangolinVpn
- ☑ Network Extensions → 勾选 Packet Tunnel Provider
Continue → Register

3.4 更新 Provisioning Profiles

分别为以下三个 Bundle ID 创建/更新 Development Provisioning Profile：

com.pangolin.pangolinVpn
com.pangolin.pangolinVpn.PacketTunnel

Profile 类型选 iOS App Development，关联真机 UDID。

4. Network Extension 专项审批说明

⚠️ Network Extension Entitlement（特别是 packet-tunnel-provider）在 Apple 侧需要额外审批，
不能直接在 Developer Portal 自助开启，需通过苹果的额外功能申请流程。

4.1 申请入口

https://developer.apple.com/contact/request/network-extension-entitlement/

4.2 申请表填写指引（⚠️ 脱敏口径，禁止出现红线词）

红线词：VPN / 翻墙 / 科学上网 / 突破封锁 / 自由穿越 / Go anywhere / 绕过
注意：Apple 技术表单中「Network Extension」本身是技术名词，可正常使用。
产品描述使用「网络加速」「隐私保护」「企业隧道」等口径。

表单参考内容

App Name（应用名称）
Pangolin

App Description（应用描述）

Pangolin is a privacy-focused network acceleration app that provides encrypted
connectivity for users who require secure and reliable network performance.
The app uses a Packet Tunnel Provider Network Extension to establish an
encrypted tunnel between the user's device and our proxy servers, improving
connection stability and protecting user privacy on untrusted networks (public
Wi-Fi, etc.).

What does your app do that requires this entitlement?（为何需要该 entitlement）

Our app implements a Packet Tunnel Provider Network Extension to create an
encrypted overlay network for privacy protection. The extension intercepts
outbound IP traffic via NEPacketTunnelNetworkSettings, routes it through our
secure proxy infrastructure using the sing-box open-source networking library
(github.com/SagerNet/sing-box), and returns decrypted responses to the device.
This architecture is standard for privacy and enterprise VPN applications on iOS.
The extension runs as a separate process per Apple's Network Extension
framework requirements and communicates with the main app only via
NETunnelProviderSession.sendProviderMessage for status and statistics queries.

Primary use case（主要使用场景）
Privacy protection and encrypted network access on untrusted networks

Does the app use this entitlement to circumvent network controls?（是否用于绕过网络控制）
No. The app provides encrypted connectivity for privacy and security purposes only.

5. 审批 Lead Time

App Group + Network Extension 自助配置：即时生效
Packet Tunnel Provider 额外审批：通常 2–5 个工作日（实测范围 1–14 天）
建议：提交申请后同步进行代码开发，不等审批完成再写代码

6. 本地文件对应关系

文件	说明
`client/ios/Runner/Runner.entitlements`	主 App entitlement 文件（`CODE_SIGN_ENTITLEMENTS` 已配置）
`client/ios/PacketTunnel/PacketTunnel.entitlements`	Extension entitlement 文件
`client/ios/Runner.xcodeproj/project.pbxproj`	Xcode 项目（已添加 `CODE_SIGN_ENTITLEMENTS` 到所有 build configurations）

审批通过后，在 Developer Portal 下载新 Provisioning Profile，在 Xcode → Signing & Capabilities 中选择正确的 Profile 即可。

7. 验证 Entitlement 是否生效

真机安装后，在 Mac 上执行：

# 提取已安装 IPA 的 embedded.mobileprovision 并验证
xcrun security cms -D -i /path/to/Runner.app/embedded.mobileprovision | \
  plutil -p - | grep -A5 "NetworkExtension\|application-groups"

若输出包含 packet-tunnel-provider 且值不为 entitlement-not-found，则 entitlement 生效。

5.7 KiB Raw Blame History Unescape Escape