Koppeln Sie den iOS-Begleiter

Überprüfen Sie die beiden Enden der Verbindung

Der Begleiter ist ein Client eines laufenden Desktop-Sidecars. Es hostet nicht die Projektdatenbank, den Geometriekern, den Modellanbieter oder den Workflow-Runner. Vergewissern Sie sich vor dem Koppeln, dass der Desktop seine Projekte öffnet und dass das Telefon über WLAN, einen persönlichen Hotspot oder ein bereits konfiguriertes Overlay-/VPN-Netzwerk eine Verbindung zum Desktop herstellen kann.

Verwenden Sie einen nativen iOS-Build, der enthält modules/companion-net. Expo Go fehlt dieses Modul und kann die angeheftete Verbindung nicht herstellen. Das Paket verfügt auch über einen Browser-Entwicklungs-Fallback, der Browser-Abruf implementiert jedoch nicht die native Pinning-Richtlinie. Die Android-Konfiguration im Manifest stellt kein Android-Äquivalent des Swift-Moduls bereit.

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

Der iOS-Ausführungsbefehl erfordert macOS, Xcode und CocoaPods. Für den Aufbau eines physischen Geräts ist ein vertrauenswürdiges Geräte- und Signaturteam erforderlich. bun run --cwd apps/mobile build exportiert JavaScript; Es wird kein installierbares IPA erstellt. Siehe die mobile Referenz für Layout und Transportumsetzung.

Aktivieren Sie das Desktop-Gateway

Öffnen Sie Desktop-Einstellungen → Geräte und das zugehörige Mobile-Begleitfenster oder verwenden Sie /settings/companion. Schalten Sie das Gateway ein, erstellen Sie dann eine benannte Kopplung und zeigen Sie den QR-Code an. Dies ist ein separater Listener von der gewöhnlichen Loopback-API: HTTPS auf IPv4 0.0.0.0, standardmäßig Port 8443.

Der Dienst akzeptiert Ganzzahl-Ports 1024–65535. Wenn eine andere Anwendung den ausgewählten Port belegt, schlägt die Aktivierung fehl. Wählen Sie einen freien Port und erstellen Sie einen Link mit der resultierenden Adresse. Erlauben Sie die Verbindung über die Desktop-Firewall für das Netzwerk, das Sie verwenden möchten. Die Anwendung erstellt kein öffentliches Relay, keine Portweiterleitung oder ein VPN.

Der aktivierte Status und der Port bleiben erhalten. Nach einem Sidecar-Neustart versucht das Gateway fortzufahren, sobald die lokale API bereit ist. Zertifikats- und private Schlüsseldateien befinden sich im Sidecar-Datenverzeichnis companion/ unterverzeichnis; Der private Schlüssel wird nur mit Eigentümerberechtigungen geschrieben. Die native App vertraut dem Zertifikat beim Pairing und gibt kein allgemeines Versprechen ab, dass jedes lokale Zertifikat sicher ist.

Überprüfen und aktivieren Sie über die Desktop-API

Für ein reproduzierbares Entwicklungssetup verwenden Sie das Starttoken eines isolierten Sidecars, das Sie kontrollieren. Ersetzen Sie Port 43111 durch seinen Ready-Event-Port. Hierbei handelt es sich um Desktop-Verwaltungsaufrufe. Der Telefon-Token darf kein eigenes Gateway verwalten.

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}'

Der Status enthält den aktivierten Status, nullfähige Ports/Fingerabdrücke, vorgeschlagene Host- und Geräteeinträge. Der Fingerabdruck kann null sein, bevor ein Zertifikat vorhanden ist. Eine Öffentlichkeit gesundheitssonde stellt den Zustand des Loopback-Prozesses fest; Es beweist nicht, dass das HTTPS-Gateway aktiviert und erreichbar ist oder ein Geräte-Token akzeptiert. Benutzen Sie die Companion-API für genaue Managementschemata.

Erstellen Sie eine benannte Paarung

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")

Ersetzen Sie den Beispielhost durch eine Adresse, die das Telefon erreichen kann, oder lassen Sie den optionalen Host weg, um die Erkennung zu verwenden. Der Name ist gekürzt und muss 1–60 Zeichen enthalten. Erfolgreich ist HTTP 201 mit id und link. Durch das Erstellen eines Tokens wird der Listener nicht aktiviert. Aktivieren Sie es separat.

Der Link enthält das Gerätetoken, den Zertifikatsfingerabdruck, den primären HTTPS-Ursprung, den Namen und optional alternative Hosts. Zeigen Sie es privat an oder übertragen Sie es auf das Telefon. es ist ein Ausweis. Der Desktop speichert den Token-Hash und nicht seinen Klartext. Der Datensatz verfügt in dieser Implementierung über kein Ablauffeld. Sperren Sie daher ein veraltetes Gerät explizit, anstatt davon auszugehen, dass es abläuft.

Laden Sie die Kopplung auf iOS

1. Öffnen Sie den Verbindungsbildschirm der installierten CADCAMFUN-App.
2. Wählen Sie „Kopplungs-QR-Code scannen und Kamerazugriff gewähren“ oder verwenden Sie „Kopplungslink einfügen“.
3. Geben Sie für die manuelle Eingabe die Desktop-Adresse, das Token und den vollständigen Zertifikatsfingerabdruck über das Verbindungsformular an.
4. Erlauben Sie den Zugriff auf das lokale Netzwerk, wenn iOS Sie dazu auffordert. Kamerazugriff und Netzwerkzugriff sind separate Berechtigungen.
5. Warten Sie, bis die Integritäts-/Bootstrap-Prüfung erfolgreich ist und die App Projekte öffnet.

Der Parser erfordert einen HTTPS-Ursprung ohne Benutzerinformationen, Pfadinhalt, Abfrage oder Fragment. Token müssen aus 16–4096 Zeichen ohne Leerzeichen/Steuerzeichen bestehen. Fingerabdrücke bestehen aus genau 64 hexadezimalen Zeichen. Ungültige Links werden abgelehnt, bevor Anfragen gestartet werden.

Erkannte alternative Ursprünge werden dedupliziert. Der Client führt ein Rennen der Kandidaten durch, verwendet die erste erfolgreiche Verbindung, bricht die anderen ab und speichert den erfolgreichen Ursprung. Discovery bewirbt bis zu sechs geeignete private IPv4-Adressen, einschließlich WLAN, Hotspot und IPv4-Bereiche im Tailscale-Stil; Der aktuelle IPv4-Listener kündigt keine erkannten IPv6-Hosts an.

Welche Zertifikat-Pinning-Prüfungen werden durchgeführt?

Der Swift-Transport verwendet Ephemeral URLSession instanzen und einen benutzerdefinierten Vertrauensdelegierten. Es ruft die DER-Bytes des Blattzertifikats ab, berechnet SHA-256 und akzeptiert die Verbindung nur, wenn dieser Hash dem gepaarten Fingerabdruck entspricht. HTTPS ist erforderlich und Weiterleitungen werden abgelehnt. Native Aufrufer greifen nicht stillschweigend auf den nicht angehefteten Abruf zurück, wenn das Modul fehlt.

Dies unterstützt das selbstsignierte Zertifikat des Desktops, ohne beliebige selbstsignierte Server zu akzeptieren. Die Vertrauensentscheidung ergibt sich aus dem Pairing-QR/Link. Das Ersetzen des Desktop-Zertifikats ändert diese Entscheidung; Erstellen Sie eine neue vertrauenswürdige Paarung, anstatt die Nichtübereinstimmung zu unterdrücken.

Gewöhnliche Browser-/Curl-Vertrauensfehler sind nicht gleichbedeutend mit dem Testen des nativen Delegaten der App. Ein Browser lehnt möglicherweise einen korrekt angehefteten selbstsignierten Server ab, weil er einen anderen Vertrauensspeicher verwendet. Überprüfen Sie dies über die installierte App und untersuchen Sie den tatsächlichen Fehler, anstatt die Zertifikatsvalidierung global zu deaktivieren.

Nach erfolgreicher Geräteauthentifizierung zeichnet das Gateway einen zuletzt gesehenen Zeitstempel für seinen aktuellen Dienststatus auf. Aktualisieren Sie den Status des Desktop-Geräts, um den authentifizierten Datenverkehr zu bestätigen. Dies weist auf die Verwendung von Token hin. Es ist kein Beweis dafür, dass jede Projektaktion erfolgreich war, oder ein dauerhafter Sicherheitsprüfpfad.

Verstehen Sie den Geräte-Token-Bereich

Das Gerätetoken ist durch die Zulassungsliste für Methode/Pfad begrenzt. Es ist grundsätzlich nicht schreibgeschützt und wählt kein Projekt aus. Akzeptierte Anfragen werden unter der Anwendungsidentität des Desktops weitergeleitet und unterliegen weiterhin der Endpunktautorisierung. Beschreiben Sie das Pairing niemals als bloßes Gewähren einer passiven Überwachung.

Assistentenberechtigungen und ausstehende Fragen sind separate Sitzungsinteraktionen. Beantworten Sie sie auf Anfrage in der mobilen Benutzeroberfläche. Ein Token, das den Antwortendpunkt erreichen kann, bedeutet nicht, dass jede Tool-Aktion bereits genehmigt wurde.

Nutzen Sie Sitzungen und stellen Sie die Konnektivität wieder her

Wählen Sie ein Projekt aus, um dessen Übersicht, Verlauf, Pulls und Workflow-Ausführungen zu überprüfen. Assistentensitzungen werden auf dem Desktop mit seinen Anbietereinstellungen ausgeführt. Konfigurieren Sie dort zunächst den Provider. Das Telefon merkt sich ein ausgewähltes Projekt und die letzte Sitzung pro Projekt für den gekoppelten Desktop; Durch Ändern der Desktop-Identität wird diese Zuordnung gelöscht.

Vordergrundprüfungen prüfen mit einem Budget von 15 Sekunden. Fehlgeschlagene Prüfungen werden bis zu 30 Sekunden lang unterbrochen, und das Vorziehen der App löst eine weitere Prüfung aus. Der Hintergrundstatus wird getrennt vom Offlinestatus verfolgt. Tippen Sie in den Telefoneinstellungen auf die Desktop-Zeile, um die manuelle Überprüfung erneut durchzuführen.

In der Warteschlange befindliche Assistentennachrichten werden mit maximal 50 Einträgen gespeichert, wobei die ältesten über diese Grenze hinaus gelöscht werden. Sie versuchen es später erneut und behalten möglicherweise ihre Sitzungskennung. Hierbei handelt es sich um eine begrenzte Unterstützung für die Nachrichtenübermittlung, nicht um eine Offline-CAD-Berechnung oder eine genau-einmalige Ausführung. Überprüfen Sie nach einem unterbrochenen Schreib-/Wechselvorgang die Desktop-Sitzung und das Projekt, bevor Sie dieselbe Änderung wiederholen.

Absichtlich widerrufen oder entkoppeln

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"

Token werden bei jeder neuen Anfrage überprüft, sodass nachfolgende Anfragen mit dem widerrufenen Token fehlschlagen. Durch den Widerruf wird ein bereits weitergeleiteter Stream nicht explizit beendet. Das Deaktivieren des Gateways stoppt den Listener; POST /api/companion/disable ist der administrative Endpunkt.

Telefoneinstellungen → Dieses Telefon entkoppeln löscht die lokal gespeicherte Kopplung und kehrt zu „Verbinden“ zurück. Der Desktop-Revoke-Endpunkt wird nicht aufgerufen. Verwenden Sie beide Aktionen, wenn Sie ein Gerät außer Betrieb nehmen. Um nur die Geräteanmeldeinformationen zu rotieren, widerrufen Sie sie und führen Sie eine neue Kopplung durch. Durch das Ersetzen des gesamten Zertifikats ändert sich auch die PIN jedes Telefons.

Diagnostizieren Sie Fehler nach Schicht

Native CI erstellt eine nicht signierte Simulator-App und überprüft die echte Gateway-Kopplung/Projektliste. Separate CI-Prüfungen, Typprüfung, Logiktests und JavaScript-Export. Diese beweisen nicht das Signieren physischer Geräte, die TestFlight-Verteilung, das Routing in Remote-Netzwerken oder einen echten Modellanbieter.

Wiederholt fehlerhafte Token werden gedrosselt: Zehn fehlgeschlagene Versuche von einer IP-Adresse innerhalb von 60 Sekunden führen dazu, dass weitere Anfragen von dieser IP-Adresse 429 zurückgeben, bis das Fenster abläuft. Ein 429 nach der erneuten Kopplung bedeutet normalerweise, dass ein altes Geräte-Token immer noch erneut versucht wird.

Implementierungskarte

Der Verwaltungsvertrag ist packages/api/src/groups/companion.ts. Sidecar-Lebenszyklus- und Routenrichtlinien sind in Kraft services/companion.ts und companion-gateway.ts. Telefonanalyse, Verbindungswiederherstellung, Speicher und Benutzeroberfläche sind vorhanden lib/pairing.ts, server.tsx, storage.ts, und app/connect.tsx. Der native Vertrauensdelegierte ist modules/companion-net/ios/CompanionNetModule.swift.

Behalten Sie für einen Supportbericht die App-Version, die Verbindungsmethode, den nicht geheimen Gateway-Host/-Port, den genauen Fehler/Status und ob das native Modul vorhanden ist. Schwärzen Sie Token, Pairing-Links, Modellanmeldeinformationen und private Schlüssel. Fügen Sie die hinzu System-API versionsergebnis beim Vergleich zweier Entwicklungsverfahren.

Was ein gekoppeltes Telefon anrufen kann

Jede Anfrage über das Gateway muss ein Geräte-Token enthalten und dieser Zulassungsliste entsprechen. Alles andere, einschließlich Anmeldeinformationen, Plugins, Dateien, Abrechnung usw /api/companion selbst, wird abgelehnt. Zugelassene Anfragen werden mit dem Anwendungstoken, den das Telefon nie sieht, an die Loopback-API weitergeleitet.

Anatomie der Paarungsglieder

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

Das Zertifikat ist ein selbstsigniertes P-256-Zertifikat, dessen alternative Antragstellernamen Folgendes enthalten: localhost, 127.0.0.1und die erreichbaren privaten Adressen der Maschine. Es bleibt drin <dataDir>/companion, sodass Paarungen Neustarts überleben. Durch den Austausch ändert sich der Fingerabdruck und es ist eine erneute Kopplung erforderlich.

Gateway-Verwaltungs-API

Fehlgeschlagene Bearer-Versuche werden pro IP-Adresse gedrosselt: Nach 10 Fehlern innerhalb von 60 Sekunden antwortet das Gateway HTTP 429 („Zu viele fehlgeschlagene Versuche“), bis das Fenster verstrichen ist. Ein falsches oder widerrufenes Token erhält andernfalls HTTP 401.

Gateway-Status, erfasst

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

Wenn host nicht die Adresse ist, die Ihr Telefon erreichen kann (z. B. ein Container oder eine VPN-Schnittstelle), schlägt die Kopplung auf der Netzwerkebene fehl, obwohl alles andere korrekt ist.

In 3D