# 聚浪Auto iOS 签名与安装说明

聚浪Auto iOS 版不通过 App Store 分发。官网下载的 IPA 必须完成有效签名后，才能安装到 iPhone。

## 推荐方式：使用 Xcode 和自己的开发者账号安装

适合开发、测试和少量自有设备，兼容主应用、网络扩展和自动化所需权限。

### 准备条件

- 一台安装最新版 Xcode 的 Mac。
- 一个有效的 Apple Developer 开发者账号。
- iPhone 已开启“开发者模式”，并通过数据线或局域网与 Mac 配对。
- 从官网取得对应版本的源码包或 IPA、版本号和 SHA-256 校验值。

### 必须配置的标识和权限

主应用与网络扩展必须属于同一个开发团队，并使用各自唯一的 App ID：

- 主应用 Bundle ID：例如 `com.yourcompany.JulangAuto`
- 网络扩展 Bundle ID：例如 `com.yourcompany.JulangAuto.TunnelProv`
- App Group：例如 `group.com.yourcompany.JulangAuto`

主应用需要：

- App Groups
- Personal VPN
- Network Extensions 中允许的 VPN 能力

网络扩展需要：

- App Groups
- Network Extensions：`packet-tunnel-provider`

主应用、网络扩展及双方 entitlements 中的 App Group 必须完全一致。

### Xcode 安装步骤

1. 打开 `JFileIOSHost.xcodeproj`。
2. 分别选择主应用 `JFileIOSHost` 和扩展 `TunnelProv`。
3. 在 Signing & Capabilities 中选择自己的 Team。
4. 将两个 Bundle ID 改成自己账号下的唯一标识。
5. 创建或选择同一个 App Group，并同步修改两个 entitlements 文件。
6. 确认主应用包含 Personal VPN，扩展包含 Packet Tunnel Provider。
7. 连接并信任 iPhone，选择该设备作为运行目标。
8. 点击 Run。首次安装后，在 iPhone 的“设置 → 隐私与安全性 → 开发者模式”确认已开启。
9. 如系统提示开发者不受信任，在“设置 → 通用 → VPN 与设备管理”中信任对应开发者。
10. 首次启动聚浪Auto，根据页面提示完成 VPN/自动化能力初始化。

## 使用 IPA 重签

IPA 内同时包含主应用和 `TunnelProv.appex` 网络扩展，不能只重签主应用。重签工具或签名服务必须完成以下操作：

1. 为网络扩展写入匹配的扩展描述文件并签名。
2. 为主应用写入匹配的主应用描述文件并签名。
3. 两个描述文件使用同一 Team 和同一 App Group。
4. 先签名内层扩展，再签名外层主应用。
5. 保留主应用对网络扩展的 Embed 配置。

只支持普通单 App 重签、无法处理 `.appex` 和 Network Extension 权限的工具，不适合本应用。

## 签名有效期

- 免费 Apple ID：通常有效期较短，并受设备与 App 数量限制。
- 个人或公司开发者账号：开发/Ad Hoc 描述文件通常最长一年，且只能安装到已登记 UDID 的设备。
- 企业签名：仅限符合 Apple 企业计划规则的组织内部设备，不得用于公开售卖或面向社会分发。

签名到期后，需要用新的证书和描述文件重新签名安装。相同 Bundle ID 和兼容签名条件下更新安装，通常可以保留应用数据；更换 Team 或 Bundle ID 时不能保证保留。

## 为什么官网不能直接安装到任意 iPhone

iOS 会验证证书、描述文件、设备 UDID、Bundle ID 和权限。普通开发或 Ad Hoc 签名只允许描述文件中登记的设备安装。因此，官网提供的是安装包和签名方法，不表示该 IPA 可在任意 iPhone 上直接安装。

## 安装前校验

下载后应核对官网 `release-manifest.json` 中的版本、构建号、文件大小和 SHA-256。校验不一致时不要安装。