229 lines
7.2 KiB
Markdown
229 lines
7.2 KiB
Markdown
# iOS VPN Setup Checklist (Personal Use)
|
||
|
||
Этот чеклист закрывает именно 3 пункта:
|
||
|
||
1. Добавить и настроить `PacketTunnel` target в Xcode.
|
||
2. Настроить `Bundle ID`, `App Group`, `Signing`, `Network Extension`.
|
||
3. Подключить `Libbox.xcframework` и установить pod-зависимости.
|
||
|
||
---
|
||
|
||
## 0) Перед началом
|
||
|
||
- Работай на macOS с установленным Xcode.
|
||
- Открой проект: `ios/Runner.xcworkspace` (не `Runner.xcodeproj`).
|
||
- Убедись, что у тебя есть Apple Developer Team (желательно paid account).
|
||
|
||
---
|
||
|
||
## 1) Добавить PacketTunnel target в Xcode
|
||
|
||
### 1.1 Создание target
|
||
|
||
1. В Xcode открой `Runner.xcworkspace`.
|
||
2. В левом навигаторе выбери синий проект `Runner`.
|
||
3. В разделе `TARGETS` нажми `+`.
|
||
4. Выбери шаблон: `Network Extension` -> `Packet Tunnel Provider`.
|
||
5. Name: `PacketTunnel`.
|
||
6. Language: `Swift`.
|
||
7. Нажми `Finish`.
|
||
8. Если Xcode спросит `Activate scheme?` -> `Activate`.
|
||
|
||
### 1.2 Привязка существующих файлов из репозитория
|
||
|
||
В проекте уже подготовлены файлы:
|
||
|
||
- `ios/PacketTunnel/PacketTunnelProvider.swift`
|
||
- `ios/PacketTunnel/Info.plist`
|
||
- `ios/PacketTunnel/PacketTunnel.entitlements`
|
||
|
||
Сделай так:
|
||
|
||
1. Если Xcode создал свои дефолтные файлы в PacketTunnel target, удали их из target (можно `Remove Reference`).
|
||
2. Перетащи в Xcode папку `ios/PacketTunnel/` из Finder.
|
||
3. В диалоге добавления включи:
|
||
- `Copy items if needed`: **off** (файлы уже в репо),
|
||
- `Add to targets`: **PacketTunnel**.
|
||
4. Проверь `Target Membership` у `PacketTunnelProvider.swift` -> только `PacketTunnel`.
|
||
|
||
### 1.3 Embed extension в Runner
|
||
|
||
1. Выбери target `Runner` -> `General`.
|
||
2. Найди секцию `Frameworks, Libraries, and Embedded Content`.
|
||
3. Убедись, что `PacketTunnel.appex` добавлен как `Embed & Sign`.
|
||
|
||
Если не добавлен:
|
||
|
||
1. `Runner` -> `Build Phases`.
|
||
2. В `Embed App Extensions` нажми `+`.
|
||
3. Добавь `PacketTunnel.appex`.
|
||
|
||
---
|
||
|
||
## 2) Настроить IDs, Signing, App Group, Capabilities
|
||
|
||
> Важно: `Runner` и `PacketTunnel` должны быть на одной Team и с совместимыми entitlement.
|
||
|
||
### 2.1 Bundle Identifier
|
||
|
||
Рекомендуемый формат:
|
||
|
||
- Runner: `com.yourname.vpn`
|
||
- PacketTunnel: `com.yourname.vpn.PacketTunnel`
|
||
|
||
Шаги:
|
||
|
||
1. `Runner` target -> `Signing & Capabilities` -> выставь `Bundle Identifier`.
|
||
2. `PacketTunnel` target -> `Signing & Capabilities` -> выставь `Bundle Identifier`.
|
||
|
||
### 2.2 Team и подпись
|
||
|
||
Для обоих target (`Runner`, `PacketTunnel`):
|
||
|
||
1. `Automatically manage signing` -> ON.
|
||
2. `Team` -> одна и та же команда.
|
||
3. `Signing Certificate`/`Provisioning Profile` должны подтянуться автоматически.
|
||
|
||
### 2.3 App Group
|
||
|
||
Для обоих target добавь capability `App Groups` и **одинаковую** группу:
|
||
|
||
- `group.com.yourname.vpn`
|
||
|
||
Шаги:
|
||
|
||
1. `Signing & Capabilities` -> `+ Capability` -> `App Groups`.
|
||
2. Создай/выбери группу `group.com.yourname.vpn`.
|
||
3. Повтори для второго target.
|
||
|
||
### 2.4 Network Extension capability
|
||
|
||
Для обоих target:
|
||
|
||
1. `+ Capability` -> `Network Extensions`.
|
||
2. Тип: `Packet Tunnel`.
|
||
|
||
### 2.5 Синхронизация build settings (если Xcode не подставил)
|
||
|
||
Проверь:
|
||
|
||
- `Runner` использует `ios/Runner/Runner.entitlements`
|
||
- `PacketTunnel` использует `ios/PacketTunnel/PacketTunnel.entitlements`
|
||
- `PacketTunnel` использует `ios/PacketTunnel/Info.plist`
|
||
|
||
Где смотреть:
|
||
|
||
1. Target -> `Build Settings`.
|
||
2. Найти `Code Signing Entitlements`.
|
||
3. Найти `Info.plist File`.
|
||
|
||
### 2.6 Значение App Group в plist/entitlements
|
||
|
||
В проекте уже задано через `AppGroupIdentifier` и переменные.
|
||
Если будут ошибки по group id, можно временно зафиксировать вручную:
|
||
|
||
- в `Runner.entitlements` и `PacketTunnel.entitlements` поставить literal `group.com.yourname.vpn`.
|
||
|
||
---
|
||
|
||
## 3) Подключить Libbox.xcframework + pods
|
||
|
||
### 3.1 Положить framework
|
||
|
||
Нужный путь:
|
||
|
||
- `ios/Frameworks/Libbox.xcframework`
|
||
|
||
Проверь, что папка действительно называется **ровно** `Libbox.xcframework`.
|
||
|
||
### 3.2 Установить pods
|
||
|
||
Из корня проекта:
|
||
|
||
```bash
|
||
flutter pub get
|
||
cd ios
|
||
pod install
|
||
```
|
||
|
||
Если `pod install` ругается на framework:
|
||
|
||
- проверь путь `ios/Frameworks/Libbox.xcframework`;
|
||
- удали кэши и повтори:
|
||
|
||
```bash
|
||
cd ios
|
||
pod deintegrate
|
||
pod install
|
||
```
|
||
|
||
### 3.3 Открывать только workspace
|
||
|
||
После pod install всегда открывай:
|
||
|
||
- `ios/Runner.xcworkspace`
|
||
|
||
---
|
||
|
||
## 4) Первый запуск на iPhone
|
||
|
||
1. Подключи iPhone кабелем.
|
||
2. В Xcode выбери устройство как run destination.
|
||
3. Собери `Runner` scheme (`Cmd + R`).
|
||
4. На iPhone подтверди доверие developer certificate (если нужно).
|
||
5. Дай разрешение на VPN при первом подключении.
|
||
|
||
---
|
||
|
||
## 5) Быстрый preflight перед каждым запуском
|
||
|
||
- `Runner` и `PacketTunnel` в одной Team.
|
||
- `Bundle ID` уникальны и корректны.
|
||
- Оба target имеют `App Groups` и `Network Extensions`.
|
||
- В `Embed App Extensions` присутствует `PacketTunnel.appex`.
|
||
- На месте `ios/Frameworks/Libbox.xcframework`.
|
||
- Проект открыт как `Runner.xcworkspace`.
|
||
|
||
---
|
||
|
||
## 6) Частые ошибки и фиксы
|
||
|
||
### `Missing entitlement` / `permission denied`
|
||
|
||
- Не совпали capabilities между target.
|
||
- Неверный provisioning profile.
|
||
- App Group не добавлен в оба target.
|
||
|
||
### `PacketTunnel.appex missing` или не стартует extension
|
||
|
||
- Не встроен extension в `Runner` (`Embed App Extensions`).
|
||
- Неверный bundle id extension.
|
||
|
||
### `No such module Libbox`
|
||
|
||
- Нет `Libbox.xcframework` в `ios/Frameworks/`.
|
||
- Не выполнен `pod install`.
|
||
- Открыт `xcodeproj`, а не `xcworkspace`.
|
||
|
||
### VPN включается, но трафик не идет
|
||
|
||
- Неверный конфиг/ссылка.
|
||
- Проблемы DNS/route в extension.
|
||
- Смотри логи Xcode для `PacketTunnelProvider`.
|
||
|
||
---
|
||
|
||
## 7) Что уже подготовлено в этом репозитории
|
||
|
||
Уже добавлено:
|
||
|
||
- `ios/Podfile`
|
||
- `ios/Runner/Runner.entitlements`
|
||
- `ios/PacketTunnel/Info.plist`
|
||
- `ios/PacketTunnel/PacketTunnel.entitlements`
|
||
- `ios/PacketTunnel/PacketTunnelProvider.swift`
|
||
- `ios/Frameworks/README.md`
|
||
- iOS deployment target поднят до 15.0 в `ios/Runner.xcodeproj/project.pbxproj`
|
||
|
||
Тебе осталось довести Xcode-конфиг и положить `Libbox.xcframework`.
|