Подключите компаньона iOS

Проверьте два конца соединения

Компаньон является клиентом работающей настольной сайдкара. В нем не размещается база данных проекта, ядро геометрии, поставщик моделей или средство выполнения рабочих процессов. Перед сопряжением убедитесь, что на рабочем столе открываются проекты и что телефон может подключаться к рабочему столу через Wi-Fi, персональную точку доступа или уже настроенную оверлейную сеть/сеть VPN.

Используйте собственную сборку iOS, содержащую modules/companion-net. В Expo Go отсутствует этот модуль, и он не может установить закрепленное соединение. В пакете также есть запасной вариант для разработки браузера, но выборка браузера не реализует собственную политику закрепления. Конфигурация Android в манифесте не предоставляет эквивалент модуля Swift для Android.

bun install
bun run --cwd apps/mobile typecheck
bun run --cwd apps/mobile test
bun run --cwd apps/mobile ios

Для команды запуска iOS требуются macOS, Xcode и CocoaPods. Для сборки на физическом устройстве требуется доверенное устройство и команда подписывающих сторон. bun run --cwd apps/mobile build экспортирует JavaScript; он не создает устанавливаемый IPA. См. мобильная ссылка для планировки и транспортной реализации.

Включить шлюз рабочего стола

Откройте «Настройки рабочего стола» → «Устройства» и сопутствующую панель «Мобильный» или воспользуйтесь /settings/companion. Включите шлюз, затем создайте именованное соединение и покажите его QR-код. Это отдельный прослушиватель от обычного API обратной связи: HTTPS на IPv4 0.0.0.0, порт 8443 по умолчанию.

Служба принимает целочисленные порты 1024–65535. Если другое приложение занимает выбранный порт, включение не удастся; выберите свободный порт и создайте ссылку с полученным адресом. Разрешите подключение через брандмауэр настольного компьютера для сети, которую вы собираетесь использовать. Приложение не создает публичную ретрансляцию, переадресацию портов или VPN.

Включенное состояние и порт сохраняются. После перезапуска вспомогательной машины шлюз пытается возобновить работу, как только локальный API будет готов. Файлы сертификатов и закрытых ключей находятся в каталоге дополнительных данных. companion/ подкаталог; закрытый ключ записывается с разрешениями только владельца. Нативное приложение доверяет сертификату, полученному при сопряжении, а не общему обещанию, что каждый локальный сертификат безопасен.

Проверьте и включите через API рабочего стола.

Для воспроизводимой настройки разработки используйте токен запуска изолированной сайдкара, которой вы управляете. Замените порт 43111 портом готового события. Это вызовы управления рабочим столом; телефонному токену не разрешено администрировать собственный шлюз.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token
CADCAM_PAIR_DIR=$(mktemp -d /tmp/cadcamfun-pair-guide.XXXXXX)

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/enable"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"port":18443}'

Статус содержит включенное состояние, нулевой порт/отпечаток пальца, предлагаемый хост и записи устройств. Отпечаток пальца может быть нулевым до существования сертификата. Публика зонд здоровья устанавливает работоспособность процесса обратной связи; это не доказывает, что шлюз HTTPS включен, доступен или принимает токен устройства. Используйте Сопутствующий API для точных схем управления.

Создайте одну именованную пару

curl --fail-with-body -X POST "$CADCAM_URL/api/companion/pair"   -H "Authorization: Bearer $CADCAM_TOKEN"   -H 'Content-Type: application/json'   -d '{"name":"Workshop iPhone","host":"192.168.1.20"}'   -o "$CADCAM_PAIR_DIR/pairing.json"

CADCAM_DEVICE_ID=$(bun --no-env-file -e   'console.write((await Bun.file(process.argv[1]).json()).id)'   "$CADCAM_PAIR_DIR/pairing.json")

Замените пример хоста адресом, к которому может обратиться телефон, или опустите дополнительный хост, чтобы использовать обнаружение. Имя обрезано и должно содержать символы 1–60. Успех — HTTP 201 с id и link. Создание токена не включает прослушиватель; включите его отдельно.

Ссылка содержит токен устройства, отпечаток сертификата, основной источник HTTPS, имя и дополнительные альтернативные хосты. Отобразить или передать его приватно на телефон; это удостоверение. На рабочем столе хранится хеш токена, а не его открытый текст. В этой реализации запись не имеет поля срока действия, поэтому отзовите устаревшее устройство явно, а не предполагайте, что срок его действия истечет.

Загрузите сопряжение на iOS

1. Откройте экран подключения установленного приложения CADCAMFUN.
2. Выберите «Сканировать QR-код сопряжения и предоставить доступ к камере» или воспользуйтесь «Вставить ссылку для сопряжения».
3. Для ввода вручную укажите адрес рабочего стола, токен и полный отпечаток сертификата через форму подключения.
4. Разрешите доступ к локальной сети по запросу iOS. Доступ к камере и доступ к сети — это отдельные разрешения.
5. Подождите, пока проверка работоспособности/загрузки завершится успешно и приложение откроет проекты.

Синтаксическому анализатору требуется источник HTTPS без информации о пользователе, содержимого пути, запроса или фрагмента. Токены должны состоять из символов 16–4096 без пробелов и управляющих символов; отпечатки пальцев представляют собой ровно 64 шестнадцатеричных символов. Недействительные ссылки отклоняются до начала запросов.

Обнаруженные альтернативные источники дедуплицируются. Клиент проверяет кандидатов, использует первое успешное соединение, прерывает остальные и сохраняет успешный источник. Discovery объявляет до шести подходящих частных IPv-адресов4, включая диапазоны Wi-Fi, точки доступа и IPv-адреса в стиле Tailscale4; текущий прослушиватель IPv4 не объявляет обнаруженные хосты IPv6.

Какие проверки закрепления сертификата

Транспорт Swift использует эфемерные URLSession экземпляры и пользовательский делегат доверия. Он получает байты DER конечного сертификата, вычисляет SHA-256 и принимает соединение только тогда, когда этот хэш равен парному отпечатку пальца. Требуется HTTPS, перенаправления запрещены. Собственные вызывающие программы не возвращаются к открепленной выборке автоматически, если модуль отсутствует.

Это поддерживает самозаверяющий сертификат настольного компьютера без принятия произвольных самозаверяющих серверов. Решение о доверии принимается на основе сопряжения QR/ссылка. Замена сертификата рабочего стола меняет это решение; создайте новую доверенную пару вместо того, чтобы подавлять несоответствие.

Обычные ошибки доверия браузера/curl не эквивалентны тестированию собственного делегата приложения. Браузер может отклонить правильно закрепленный самозаверяющий сервер, поскольку он использует другое хранилище доверенных сертификатов. Проверьте через установленное приложение и проверьте фактическую ошибку, а не отключайте глобальную проверку сертификата.

После успешной аутентификации устройства шлюз записывает временную метку последнего посещения для текущего состояния службы. Обновите статус настольного устройства, чтобы подтвердить аутентифицированный трафик. Это указывает на использование токена; это не является доказательством того, что каждое действие проекта было успешным, или надежным следом аудита безопасности.

Понимание области действия токена устройства

Токен устройства ограничен списком разрешенных методов/путей. Он по своей сути не доступен только для чтения и не выбирает один проект. Принятые запросы пересылаются под идентификатором приложения рабочего стола и подлежат авторизации на конечной точке. Никогда не описывайте создание пар как просто предоставление пассивного наблюдения.

Разрешения Ассистента и ожидающие вопросы — это отдельные взаимодействия сеанса. Ответьте на них в мобильном интерфейсе по запросу. Токен, который может достичь конечной точки ответа, не означает, что каждое действие инструмента уже одобрено.

Используйте сеансы и восстанавливайте подключение

Выберите проект, чтобы просмотреть его обзор, историю, выборки и рабочие процессы. Сеансы помощника выполняются на рабочем столе с настройками его провайдера. Сначала настройте там провайдера. Телефон запоминает выбранный проект и последний сеанс каждого проекта для сопряженного рабочего стола; изменение идентификатора рабочего стола очищает это сопоставление.

Проверка на переднем плане проверяется с бюджетом в 15 секунды. Неудачные проверки отменяются через 30 секунды, а перезапуск приложения запускает еще одну проверку. Фоновое состояние отслеживается отдельно от автономного состояния. Коснитесь строки рабочего стола в настройках телефона, чтобы повторить проверку вручную.

Сообщения помощника в очереди сохраняются максимум с 50 записями, при этом самые старые сообщения, превышающие этот предел, удаляются. Они повторяют попытку позже и могут сохранить свой идентификатор сеанса. Это поддержка ограниченной доставки сообщений, а не автономных вычислений САПР или однократного выполнения. После прерванной записи/поворота проверьте сеанс рабочего стола и проект, прежде чем повторять то же изменение.

Намеренно отозвать или разорвать пару

curl --fail-with-body -X DELETE   "$CADCAM_URL/api/companion/devices/$CADCAM_DEVICE_ID"   -H "Authorization: Bearer $CADCAM_TOKEN"

curl --fail-with-body "$CADCAM_URL/api/companion"   -H "Authorization: Bearer $CADCAM_TOKEN"

Токены проверяются при каждом новом запросе, поэтому последующие запросы с использованием отозванного токена завершаются неудачей. Отзыв не завершает явно уже перенаправленный поток. Отключение шлюза останавливает прослушиватель; POST /api/companion/disable является административной конечной точкой.

Настройки телефона → Отключить этот телефон удаляет локальное сохраненное сопряжение и возвращает соединение. Он не вызывает конечную точку отзыва рабочего стола. Используйте оба действия при выводе устройства из эксплуатации. Чтобы сменить только учетные данные устройства, отзовите их и выполните новое сопряжение; замена всего сертификата также меняет PIN-код каждого телефона.

Диагностика сбоев по слоям

Native CI создает неподписанное приложение-симулятор и проверяет реальное соединение шлюзов/список проектов. Отдельные CI-проверки типа, логические тесты и экспорт JavaScript. Они не доказывают подписание физических устройств, распространение TestFlight, маршрутизацию удаленной сети или реального поставщика модели.

Повторные плохие токены ограничиваются: десять неудачных попыток с одного IP-адреса в течение 60 секунд заставляют последующие запросы с него возвращать HTTP 429 до истечения срока действия окна. 429 после повторного сопряжения обычно означает, что старый токен устройства все еще пытается повторить попытку.

Карта реализации

Договор управления – это packages/api/src/groups/companion.ts. Жизненный цикл сайдкара и политика маршрутов находятся в стадии разработки. services/companion.ts и companion-gateway.ts. Разбор телефона, восстановление соединения, хранилище и пользовательский интерфейс находятся в стадии разработки. lib/pairing.ts, server.tsx, storage.ts, и app/connect.tsx. Собственный делегат доверия modules/companion-net/ios/CompanionNetModule.swift.

Для отчета о поддержке сохраните версию приложения, метод подключения, хост/порт несекретного шлюза, точную ошибку/статус, а также наличие собственного модуля. Редактируйте токены, ссылки сопряжения, учетные данные модели и закрытые ключи. Добавьте Системный API результат версии при сравнении двух процессов разработки.

На что может звонить сопряженный телефон

Каждый запрос через шлюз должен содержать токен устройства и соответствовать этому списку разрешений. Все остальное, включая учетные данные, плагины, файлы, выставление счетов и /api/companion себе отказывают. Принятые запросы пересылаются в API обратной связи с токеном приложения, который телефон никогда не видит.

Анатомия парной связи

cadcamfun://pair?host=https%3A%2F%2F192.168.1.20%3A8443&token=<43-char base64url>&fp=<sha256 hex>&name=Ada%27s+iPhone&hosts=https%3A%2F%2F100.64.0.7%3A8443

Сертификат представляет собой самозаверяющий сертификат P-256, альтернативные имена субъектов которого включают localhost, 127.0.0.1и доступные частные адреса машины. Он хранится в <dataDir>/companion, поэтому пары выдерживают перезапуск. При его замене меняется отпечаток пальца и требуется повторное сопряжение.

API администрирования шлюза

Неудачные попытки канала-носителя регулируются для каждого IP-адреса: после сбоев 10 в течение 60 секунд шлюз отвечает HTTP 429 («Слишком много неудачных попыток») до тех пор, пока не пройдет окно. В противном случае неправильный или отозванный токен получает HTTP 401.

Статус шлюза зафиксирован

{ "enabled": false, "port": null, "fingerprint": null, "host": "172.30.0.2", "devices": [] }

Если host не является адресом, к которому может обратиться ваш телефон (например, контейнер или интерфейс VPN), сопряжение не удастся на сетевом уровне, даже если все остальное правильно.

Через 3Д