ENGINEERING-SUPPORT

Erst Beweise sichern, dann den Fehlerbereich des Cloud-Macs eingrenzen

Dieser Engineering-Leitfaden folgt einer klaren Reihenfolge. Prüfen Sie zuerst Gerät und Netzwerk, danach Xcode, Signierung und CI-Umgebung und zuletzt Speicher, Updates und Wiederherstellung.

Cloud-Mac jetzt mieten Zum Dashboard
6 Kategorien Einstiege für Engineering-Probleme
5 Verfügbare Knoten
365 Tage Knotenverfügbarkeit
Diagnoseauftrag RUN / SUPPORT
In Abhängigkeitsreihenfolge prüfen

Verbindung → Umgebung → Build → Daten

BEREIT
01 / Gerät
Geräte-ID, Knoten, Hostschlüssel
02 / Netzwerk
Lokaler Zugang, Routing, Port und Latenz
03 / Toolchain
macOS, Xcode, Zertifikate und Abhängigkeiten
04 / Auftrag
Reproduktionsbefehl, Logs, Exit-Code und Zeit
Vor dem Support-Ticket Logs anonymisieren und abgeschlossene Schritte dokumentieren
GUIDE-INDEX

Starten Sie am aktuellen Engpass – Sie müssen nicht alles von vorn lesen

Sechs Einstiege behandeln Identitätsprüfung, Systemänderungen, Entwicklungstools, Automatisierungsaufgaben, Netzwerkpfade und Bestellinformationen. Jeder zeigt, was zuerst zu prüfen und zu sichern ist und wann ein Ticket sinnvoll ist.

01 / CONNECT

Erstverbindung

Verbindungsdaten abrufen, Hostschlüssel prüfen, eine SSH-Sitzung herstellen und grundlegende Netzwerkprobleme vor der Aktivierung der grafischen Oberfläche ausschließen.

Verbindungsablauf starten 02 / SYSTEM

macOS verwalten

Sichern Sie vor Systemänderungen Daten, Versionen und Wiederherstellungsmaterial. Prüfen Sie die Toolchain, bevor Sie das Gerät für langfristige Aufgaben einsetzen.

Updates und Wiederherstellung ansehen 03 / TOOLCHAIN

Entwicklungsumgebung

Grenzen Sie Xcode-Fehler der Reihe nach über Zertifikate, Profile, Keychain-Berechtigungen, DerivedData und Build-Logs ein.

Xcode-Fehlerbehebung öffnen 04 / RUNNER

CI/CD anbinden

Prüfen Sie Runner-Identität, Arbeitsverzeichnis, Cache-Grenzen, Schlüsselinjektion und einen nach Fehlern reproduzierbaren Rollback-Pfad.

Runner-Checkliste ansehen 05 / NETWORK

Netzwerkdiagnose

Vergleichen Sie fünf Knoten über eine kabelgebundene Verbindung, eine feste Stichprobengröße und denselben Zeitraum. Trennen Sie zuerst lokalen Zugang von Auswirkungen des internationalen Routings.

Latenzmessung ansehen 06 / ORDER

Konto und Bestellung

Verknüpfen Sie Probleme über Bestellnummer und Geräte-ID. Übermitteln Sie niemals vollständige Kartennummern, private Schlüssel oder Kontokennwörter in Logs oder Tickets.

Ticketunterlagen vorbereiten
VERBINDUNGSABLAUF

Bei Verbindungsfehlern zuerst den Zielrechner, dann das Verbindungstool prüfen

Wechseln Sie nicht wiederholt den Client, solange Hostadresse, Port und Zugangsdaten nicht geprüft sind. Die folgenden vier Schritte müssen der Reihe nach erfolgen; jeder liefert überprüfbare Eingaben für den nächsten.

  1. 01

    Gerätedaten abrufen

    Melden Sie sich am Dashboard an und prüfen Sie in der passenden Bestellung Geräte-ID, gewählten Knoten, Hostadresse, SSH-Port und aktuelle Zugangsdaten. Bei mehreren parallel genutzten Geräten ordnen Sie zuerst jede Bestellnummer eindeutig einer Geräte-ID zu.

    Sichern Bestellnummer, Geräte-ID, Knoten, Port
  2. 02

    Hostschlüssel prüfen

    Vergleichen Sie bei der Erstverbindung den vom Client angezeigten Fingerabdruck mit dem Eintrag im Dashboard. Ändert er sich nach einer Neuinstallation, prüfen Sie zuerst den Änderungsverlauf und entfernen Sie erst danach den alten lokalen Eintrag. Warnungen dürfen nicht einfach ignoriert werden.

    ssh-keygen -R example-host
ssh -p 22 user@example-host
  3. 03

    Zuerst eine SSH-Baseline herstellen

    Testen Sie DNS, Port und SSH zunächst über eine kabelgebundene Verbindung. Nach Erfolg protokollieren Sie Anmeldezeit, Ausgangsnetzwerk und die Antwort der Shell; bei Fehlern sichern Sie die vollständige Fehlermeldung und nicht nur die Zeile „Verbindung fehlgeschlagen“.

    Einordnung Zeitüberschreitung deutet eher auf Routing oder Port hin; Verbindungsablehnung eher auf den Zieldienst; bei Authentifizierungsfehlern zuerst Zugangsdaten und Berechtigungen prüfen.
  4. 04

    Danach die grafische Verbindung konfigurieren

    Erst wenn die SSH-Baseline stabil ist, prüfen Sie Adresse, Port, Client-Version und lokale Firewall für die grafische Oberfläche. Bei Rucklern dokumentieren Sie zusätzlich Auflösung, Kodierungseinstellungen und Netzwerklatenz.

    Grenze Eine funktionierende grafische Oberfläche bedeutet nicht, dass hochbitratige Medienvorschauen wie auf einem lokalen Bildschirm laufen. Prüfen Sie dies anhand der tatsächlichen Verbindung.
NETZWERKMESSUNG

Ping-Median von fünf Knoten unter gleichen Bedingungen vergleichen

Die Tabelle zeigt Routingunterschiede von wichtigen Städten nach Singapur, Japan (Tokio), Südkorea (Seoul), Hongkong und in den Westen der USA. Die Werte dienen als Orientierung für die Standortwahl und sind keine Zusage für Durchsatz, Bildrate der grafischen Oberfläche oder Auftragsdauer.

Messzeitraum Werktage 14:00–16:00 UTC+8
Stichprobengröße 50 Messungen je Knoten
Zugang Gigabit-Ethernet
Kennzahl Median der Round-Trip-Latenz
Referenzwerte des Ping-Medians von drei wichtigen Städten zu fünf VMDebug-Knoten, in Millisekunden
Testquelle Provider Singapur Japan (Tokio) Südkorea (Seoul) Hongkong Westen der USA
Shanghai China Telecom 71 ms 42 ms 46 ms 34 ms 141 ms
Shenzhen China Unicom 44 ms 55 ms 59 ms 18 ms 157 ms
Peking China Mobile 91 ms 48 ms 39 ms 63 ms 138 ms
Lokal messen

WLAN und Schwankungen des lokalen Ausgangs ausschließen

Verbinden Sie das Gerät direkt per Ethernet und pausieren Sie große Synchronisierungen, Videokonferenzen und Systemupdates. Testen Sie fortlaufend lokales Gateway und Knotenadresse. Schwanken beide, beheben Sie zuerst den lokalen Zugang.

Dann das Routing prüfen

Der Median erklärt nicht das gesamte Nutzungserlebnis

Die Remote-Interaktion wird außerdem von Paketverlust, Jitter, Upload-Bandbreite und Client-Kodierung beeinflusst. Bei Netzwerkproblemen nennen Sie Provider, Stadt, Messzeitraum, Stichprobengröße und Traceroute-Ergebnis.

XCODE-DIAGNOSE

Bei Signierungsfehlern nicht zuerst die Umgebung löschen, sondern fünf Abhängigkeitsebenen prüfen

Ein Fehler kann durch ein nicht verfügbares Zertifikat, ein unpassendes Profil, fehlende Keychain-Berechtigungen, einen verschmutzten Cache oder abweichende Build-Parameter entstehen. Sichern Sie zuerst die Roh-Logs und prüfen Sie dann in der folgenden Reihenfolge.

  1. 01

    Zertifikat

    Prüfen Sie, ob das Zielzertifikat vorhanden und gültig ist, Zertifikat und privater Schlüssel zusammenpassen und der aktuelle Build-Benutzer es lesen kann. Listen Sie zuerst die Signierungsidentitäten auf, statt alle Materialien direkt neu zu importieren.

    security find-identity -v -p codesigning
  2. 02

    Provisioning Profile

    Prüfen Sie Bundle Identifier, Team-ID, Zertifikatstyp, Geräteumfang und Berechtigungen. Bei manueller Signierung muss die Konfiguration tatsächlich auf die Zieldatei verweisen und nicht auf einen alten Cache.

    CODE_SIGN_STYLE / PROVISIONING_PROFILE_SPECIFIER
  3. 03

    Keychain-Berechtigungen

    CI-Benutzer und interaktiv angemeldete Benutzer können unterschiedliche Keychain-Suchlisten verwenden. Prüfen Sie, ob die Ziel-Keychain entsperrt und im Suchpfad enthalten ist und der Build-Prozess den privaten Schlüssel lesen darf.

    security list-keychains
  4. 04

    DerivedData

    Dokumentieren Sie zuerst den aktuellen Pfad und den fehlgeschlagenen Auftrag und löschen Sie dann nur die abgeleiteten Daten des betroffenen Projekts. Löschen aller Caches darf nicht der erste Schritt sein, da vergleichbare Build-Belege verloren gehen.

    xcodebuild -showBuildSettings
  5. 05

    Build-Logs

    Sichern Sie vollständigen Befehl, Scheme, Configuration, SDK, Xcode-Version, Exit-Code und Position des ersten Fehlers. Prüfen Sie zuerst den ersten Fehler als Ursache, nicht die zusammenfassende letzte Zeile.

    xcodebuild -version
CI/CD-RUNNER

Behandeln Sie den Runner als reproduzierbaren Auftrag, nicht als dauerhaft anwachsenden Arbeitsordner

Ein exklusiver physischer Mac kann Build-Aufträge dauerhaft ausführen. Die Stabilität hängt jedoch weiterhin von Identität, Verzeichnissen, Caches, Schlüsseln und Rollback-Grenzen ab. Für jede Änderung muss klar sein: Was wurde geändert, wie wird es geprüft und wie wird es zurückgenommen?

Checkliste für die Runner-Anbindung 5 PRÜFUNGEN
  1. 01

    Runner-Identität registrieren

    Verwenden Sie für jedes Gerät einen eindeutig erkennbaren Runner-Namen und Tags und dokumentieren Sie Registrierungsumfang, Dienstbenutzer und Startart. Vermeiden Sie nicht unterscheidbare Namen für mehrere Runner.

  2. 02

    Arbeitsverzeichnisse isolieren

    Legen Sie je Repository, Branch oder Auftrag ein eigenes Verzeichnis an. Parallele Aufträge dürfen nicht in dieselben DerivedData-, Archiv- oder Abhängigkeitsausgabeverzeichnisse schreiben.

  3. 03

    Cache-Grenzen festlegen

    Trennen Sie wiederaufbaubare Caches von dauerhaft zu sichernden Artefakten. Dokumentieren Sie vor dem Löschen Verzeichnisgröße, letzte Nutzung und Auftragszuordnung, damit kein Kaltstart durch eine Komplettlöschung entsteht.

  4. 04

    Schlüssel zur Laufzeit injizieren

    Schlüssel dürfen nur bei Bedarf in die Prozessumgebung oder eine temporäre Keychain gelangen. Deaktivieren Sie die Ausgabe in Logs, löschen Sie temporäre Materialien nach dem Auftrag und sperren Sie den Zugriff.

  5. 05

    Rollback für Fehler definieren

    Sichern Sie vor Updates von Runner, Xcode oder Abhängigkeiten die Versionsstände. Bei fehlgeschlagener Prüfung stellen Sie Konfigurationsdateien, Toolchain-Auswahl und Cache-Indizes wieder her, statt weitere Änderungen aufzuschichten.

Arbeitsverzeichnis

Für jeden Auftrag einen eindeutigen Pfad erzeugen

Der Pfad muss mindestens Projekt-ID, Auftrags-ID und Versuchszahl enthalten. Aufräumaktionen dürfen nur das Verzeichnis dieses Auftrags treffen, damit parallele Builds nicht versehentlich gelöscht werden.

WORK_ROOT="$HOME/ci-work"
JOB_DIR="$WORK_ROOT/$PROJECT/$RUN_ID"
mkdir -p "$JOB_DIR"
Fehlerbelege

Vor dem Beenden vier Informationsarten archivieren

Sichern Sie Runner-Version, Toolchain-Version, vollständigen Exit-Code und das erste Ursachen-Log. Auch Cache-Trefferrate und freier Speicher gehören in die Auftragszusammenfassung, um Unterschiede vorher und nachher vergleichen zu können.

  • Runner- und macOS-Version
  • Xcode-Pfad und -Version
  • Befehl, Exit-Code und Logs
  • Freier Speicher und Cache-Status
SPEICHER & TB5

Vor dem Einbinden zusätzlichen Speichers eine wiederherstellbare Kopie erstellen und vor dem Verbinden die Topologie klären

Zusätzlicher Speicher und Thunderbolt 5 verändern Datenpfade und Berechtigungsgrenzen. Vor jedem Formatieren, Ändern des Einhängepunkts oder Trennen eines Geräts müssen Datenkopie und angehaltener Auftragsstatus bestätigt sein.

Zusätzlicher Speicher

Vor dem Einhängen prüfen

  1. Datenkopie bestätigen

    Für wichtigen Code, Medien, Build-Artefakte und Konfigurationen muss mindestens eine unabhängige Kopie vorhanden sein. Ein noch nicht geprüftes Volume darf nicht als einziger Speicherort dienen.

  2. Datenträgeridentität dokumentieren

    Notieren Sie Volume-Name, Dateisystem, Kapazität, Geräte-ID und vorgesehenen Einhängepunkt. Verlassen Sie sich nicht allein auf die angezeigte Reihenfolge, um den Zieldatenträger zu bestimmen.

  3. Zugriffsrechte prüfen

    Stellen Sie sicher, dass der Benutzer, der Builds oder Medienaufträge ausführt, die nötigen Verzeichnisrechte besitzt. Umgehen Sie Besitzprobleme nicht durch eine globale Lockerung der Rechte.

  4. Lese-/Schreibzugriff testen

    Prüfen Sie mit einer löschbaren Testdatei zuerst Erstellen, Lesen, Umbenennen und Löschen, bevor Sie das echte Arbeitsverzeichnis verschieben.

Thunderbolt 5

Reihenfolge beim Verbinden mehrerer Geräte

  1. Physische Topologie zeichnen

    Kennzeichnen Sie jeden Mac, die Kabelrichtung, den gemeinsamen Speicher und die Aufgabenrolle. Ändern Sie keine Verbindung, solange die Upstream- und Downstream-Geräte nicht eindeutig identifizierbar sind.

  2. Berechtigungsgrenzen vereinheitlichen

    Legen Sie fest, welches Gerät schreibt und welche nur lesen, und verwenden Sie für Automatisierungsaufträge eigene Verzeichnisse, um paralleles Überschreiben zu verhindern.

  3. Verbindung schrittweise prüfen

    Führen Sie nach jedem weiteren Gerät einen Verbindungs-, Berechtigungs- sowie Lese-/Schreibtest durch. Warten Sie nicht, bis alle Kabel angeschlossen sind, bevor Sie die Fehlersuche beginnen.

  4. In umgekehrter Auftragsreihenfolge trennen

    Stoppen Sie zuerst Schreib- und Build-Aufträge, bestätigen Sie das Speichern der Caches, hängen Sie anschließend das Volume aus und trennen Sie die Geräte vom Ende der Verbindung her.

UPDATE & WIEDERHERSTELLUNG

Systemupdates brauchen einen Prüf-Mac, eine Baseline und Rückfallmaterial

Alle Knoten laufen 365 Tage im Jahr durchgehend. macOS- und Toolchain-Updates planen Sie entsprechend Ihrem Auftragsrhythmus; prüfen Sie zuerst mit unkritischen Aufgaben und aktualisieren Sie erst danach langfristig laufende Runner.

Ablauf für Updates 6 PHASEN
  1. 01

    Snapshot-Checkliste erstellen

    Exportieren Sie Code-Status, Lockfiles, Homebrew-Liste, Xcode-Pfad, Zertifikatsnamen, Keychain-Liste, Runner-Konfiguration und freien Speicher.

  2. 02

    Nicht wiederherstellbare Daten sichern

    Verschieben Sie private Konfigurationen, Signierungsmaterial, Build-Artefakte und Projektdaten an einen unabhängigen Ort und prüfen Sie praktisch, ob mindestens eine Datei wiederhergestellt werden kann.

  3. 03

    Toolchain-Kompatibilität prüfen

    Prüfen Sie die Kompatibilität von Ziel-macOS, Xcode, Command-Line-Tools, Paketmanager, Runner und Projektabhängigkeiten und dokumentieren Sie erforderliche ältere Versionen.

  4. 04

    Schreibaufträge pausieren

    Stoppen Sie CI-Warteschlangen, Medienverarbeitung und Datensynchronisierung und bestätigen Sie, dass kein Prozess mehr in Arbeitsverzeichnisse, Caches oder zusätzlichen Speicher schreibt.

  5. 05

    Minimale Abnahme durchführen

    Prüfen Sie nach dem Update nacheinander SSH, Datenträger, Xcode-Version, Zertifikatzugriff, Wiederherstellung der Abhängigkeiten, Tests, Archivierung und Artefaktdownload.

  6. 06

    Neue Baseline dokumentieren

    Speichern Sie Dauer, Logs, Cache-Status und freien Speicher des ersten erfolgreichen Auftrags. Stellen Sie parallele Aufträge anschließend schrittweise wieder her, statt alle Warteschlangen auf einmal freizugeben.

Abbruchkriterien

In diesen Fällen zuerst zurückrollen

  • Auf ein benötigtes Zertifikat oder einen privaten Schlüssel kann nicht zugegriffen werden
  • Die vom Projekt benötigte Xcode-Version ist nicht verfügbar
  • Zusätzlicher Speicher ist schreibgeschützt oder lässt sich nicht einhängen
  • Der gleiche Baseline-Befehl schlägt nun zuverlässig fehl

Aktualisieren Sie nicht mehrere Komponenten nacheinander, solange die Ursache unklar ist. Sonst lassen sich Auswirkungen von System, Toolchain und Projektkonfiguration in den Logs nicht unterscheiden.

Ticketunterlagen

Damit der Support das Problem direkt reproduzieren kann

  • Bestellnummer und Geräte-ID
  • Zeitpunkt des Problems und gewählter Knoten
  • macOS-, Xcode- und Runner-Version
  • Minimale Reproduktionsschritte und erwartetes Ergebnis
  • Anonymisierte vollständige Logs und Exit-Code
  • Durchgeführte Prüfungen und deren Ergebnisse
Dashboard-Ticket einreichen
NÄCHSTER SCHRITT

Logs anonymisiert? Dann den Auftrag an den Support übergeben

Probleme bestehender Bestellungen reichen Sie bitte über ein Dashboard-Ticket ein, zusammen mit Geräte-ID, Reproduktionsschritten und vollständigem Fehlerkontext. Für Konfigurationsfragen vor einer Bestellung können Sie die eindeutige Support-E-Mail-Adresse nutzen.

support@vmdebug.com
Dashboard-Ticket einreichen Kontaktwege ansehen