Vom Symptom zur Ursache

Verbindungs- und Build-Probleme in überprüfbare Schritte aufteilen

Du musst nicht zuerst das gesamte Handbuch lesen. Wähle zunächst Verbindung, Umgebung, Automatisierung, Netzwerk oder Speicher und prüfe anschließend Adresse, Berechtigungen, Tool-Versionen und Logs. Jeder Schritt nennt das erwartete Ergebnis, damit du weißt, ob du selbst weitersuchen oder ein Ticket einreichen solltest.

Einstieg in die Fehlerbehebung Ticket im Kontrollzentrum einreichen
6 Kategorien Dokumentationsbereiche
2 Optionen Remote-Verbindungsarten
5 Pfade Symptom-Entscheidungspfade
Dokumentationsindex

Wähle zuerst die Aufgabe, die du gerade erledigst

Jeder Einstieg führt zu konkreten Prüfpunkten auf dieser Seite. Ändere möglichst immer nur eine Variable und dokumentiere Befehle, Versionen und Ergebnisse davor und danach.

Erste Verbindung Zugangsdaten vorbereiten, Host-Fingerabdruck prüfen, Schlüssel ersetzen und die Sitzung korrekt beenden. CONNECT Entwicklungsumgebung Xcode-Pfad, Build-Ziele, Abhängigkeitsauflösung und Speicherort der Log-Archive prüfen. TOOLCHAIN Automatisierte Builds self-hosted runner registrieren sowie Labels, Parallelität und Arbeitsverzeichnisse planen. RUNNER Netzwerkzugriff Mit ausführlichen Logs Adressfehler, nicht erreichbare Ports, Zeitüberschreitungen und Authentifizierungsfehler unterscheiden. NETWORK Speicherverwaltung Speicherverbrauch von DerivedData, Caches, Archiven und Arbeitsverzeichnissen ermitteln. STORAGE Fehlerbehebung Anhand von fünf Symptomkategorien in den Entscheidungsbaum einsteigen und die nächste überprüfbare Aktion bestimmen. RESOLVE
Grundregel: Nicht gleichzeitig Xcode aktualisieren, Abhängigkeiten ersetzen, das Netzwerk wechseln und die Signaturkonfiguration ändern. Immer nur eine Sache ändern, damit die Ursache aus dem Ergebnis erkennbar bleibt.
Remote-Verbindung

SSH und VNC folgen unterschiedlichen Prüfpfaden

SSH eignet sich für Kommandozeile, Automatisierung und Dateiübertragung; VNC für Aufgaben mit grafischer macOS-Oberfläche. Bei beiden zuerst die Knotenadresse prüfen und anschließend die Zugangsdaten verifizieren.

Kommandozeilenpfad

SSH-Verbindung prüfen

  1. 01
    Verbindungsdaten vorbereiten

    Hostadresse, Port, Benutzername und temporären Zugang anhand der Bestellübergabe prüfen. Adressen nicht aus alten Terminalverläufen kopieren, da sie sich geändert haben können.

  2. 02
    Erste Prüfung durchführen

    Zuerst aus einem vertrauenswürdigen Netzwerk eine Verbindung im ausführlichen Modus herstellen und den Host-Fingerabdruck prüfen. Bei einer Abweichung von den Übergabedaten sofort abbrechen.

  3. 03
    Temporäre Zugangsdaten ersetzen

    Den eigenen SSH-Public-Key in die Autorisierungsdatei eintragen. Nach erfolgreicher Anmeldung mit der neuen Sitzung nicht mehr benötigte temporäre Zugänge entfernen.

  4. 04
    Sitzung korrekt beenden

    Zuerst Vordergrundaufgaben stoppen und prüfen, dass die Logs geschrieben wurden, dann exit zum Beenden verwenden. Ein Terminal nicht direkt schließen, solange darin noch ein Release läuft.

  5. 05
    Zugriffsfehler prüfen

    Bei einer Zeitüberschreitung zuerst Netzwerk und Port prüfen; bei einer abgelehnten Verbindung Adresse und Dienststatus; bei Authentifizierungsfehlern Benutzername, Schlüsselberechtigungen und Autorisierungsdatei.

Pfad zur grafischen Oberfläche

VNC-Verbindung prüfen

  1. 01
    Client und Adresse vorbereiten

    Einen vertrauenswürdigen VNC-Client verwenden und Knotenadresse sowie Port gemäß Übergabedaten eintragen. Vor der Verbindung unnötiges Speichern von Zugangsdaten im Client deaktivieren.

  2. 02
    Erste Bildschirmprüfung durchführen

    Prüfen, ob die erwartete grafische macOS-Oberfläche angezeigt wird, und Region sowie Gerätekonfiguration abgleichen. Bei einer fehlerhaften Anzeige nicht sofort Code oder Zertifikate importieren.

  3. 03
    Zugangsdaten aktualisieren

    Nach dem Ersetzen des temporären Passworts die Verbindung neu herstellen und die neuen Zugangsdaten prüfen. Vollständige Zugangsdaten weder in Team-Chats noch in Build-Skripten speichern.

  4. 04
    Leere Sitzung beenden

    Arbeit speichern, sensible Fenster schließen und die Sitzung beenden. Bei Zusammenarbeit den aktuellen Benutzer und laufende grafische Aufgaben dokumentieren.

  5. 05
    Bildschirmfehler eingrenzen

    Bei schwarzem Bildschirm zunächst erneut verbinden und den Sitzungsstatus prüfen; bei Verzögerungen die Anzeigequalität reduzieren; bei fehlender Verbindung Adresse, Port und lokales Netzwerk erneut prüfen.

Verbindungsdiagnose

SSH-Verbose-Logs verstehen statt wiederholt zu versuchen

Der ausführliche Modus zeigt, ob die Verbindung beim Netzwerk, beim Fingerabdruck oder bei der Authentifizierung hängen bleibt. Die folgende Adresse dient nur als Beispiel; für reale Verbindungen gelten die Bestellübergabedaten.

support-check · ssh diagnostic 
$ ssh -v -p 22 build@203.0.113.24
OpenSSH: reading configuration data
debug1: Connecting to 203.0.113.24 port 22
debug1: Connection established
debug1: identity file ~/.ssh/id_ed25519 type 3

The authenticity of host cannot be established.
ED25519 key fingerprint is SHA256:verify-with-delivery-record
Continue connecting only after fingerprint verification.

debug1: Server host key accepted
debug1: Offering public key: ~/.ssh/id_ed25519
debug1: Authentication succeeded (publickey)
Connected to the dedicated physical Mac node

$ sw_vers
ProductName: macOS

$ exit
Connection closed.
TIMEOUT

Verbindung bleibt lange bei Connecting hängen

Zuerst in ein nachweislich funktionierendes Netzwerk wechseln und anschließend Adresse sowie Port prüfen. Bei Zeitüberschreitungen in mehreren Netzwerken Zeitpunkt, lokale Ausgangsumgebung und vollständige Logs dokumentieren.

FINGERPRINT

Host-Fingerabdruck stimmt nicht mit den Aufzeichnungen überein

Verbindung stoppen und nicht einfach den lokalen Known-Hosts-Eintrag löschen und erneut versuchen. Zuerst Bestellknoten und Übergabedaten abgleichen, dann die Ursache der Änderung per Ticket bestätigen lassen.

AUTH

Netzwerk erreichbar, aber Authentifizierung fehlgeschlagen

Benutzername, Pfad zum privaten Schlüssel, Dateiberechtigungen und vollständigen Public-Key-Eintrag in der Autorisierungsdatei prüfen. Beim Einreichen von Logs Schlüsselmaterial ausblenden und nur Informationen zur Authentifizierungsphase beibehalten.

Entwicklungs-Toolchain

Zuerst die Xcode-Auswahl fixieren, dann Projektfehler bearbeiten

Die häufigsten Abweichungen auf Build-Maschinen entstehen durch uneinheitliche Pfade der Kommandozeilen-Tools, Zielnamen, Abhängigkeitsstände und Signaturvariablen. Zuerst die Maschinenebene prüfen, dann die Projektebene.

XCODE

Auswahl der Kommandozeilen-Tools bestätigen

Ausführen xcode-select -p zeigt den aktuellen Pfad; anschließend mit xcodebuild -version die Version prüfen. Nach einem Wechsel das Terminal neu öffnen, damit nachfolgende Aufgaben dieselbe Umgebung verwenden.

Erwartet: Pfad und Version stimmen überein
TARGET

Tatsächlich verfügbare Ziele auflisten

Zuerst xcodebuild -listausführen, workspace-, project-, scheme- und configuration-Namen bestätigen und die exakten Namen in den Automatisierungsbefehl übernehmen.

Erwartet: Ziele sind auflistbar
SIGNING

Signaturvariablen und Projektkonfiguration trennen

Prüfen, ob die für den Build benötigten Variablen in der aktuellen Sitzung vorhanden sind, ohne vertrauliche Werte im Repository zu speichern. Nur die Existenz der Variablen ausgeben, niemals ihren vollständigen Inhalt in Logs anzeigen.

Erwartet: Variablen vorhanden und nicht offengelegt
LOGS

Vollständige Build-Aufzeichnungen archivieren

Für jede Aufgabe Befehle, Startzeit, Exit-Code, Build-Logs und Artefaktpfade aufbewahren. Bei Fehlern auch den Kontext rund um den ersten Fehler sichern, nicht nur die Zusammenfassung am Ende.

Erwartet: Fehler reproduzierbar
Automatisierte Builds

self-hosted runner auffindbar, isoliert und abmeldbar machen

Bei der Runner-Integration geht es nicht nur darum, dass der erste Job erfolgreich läuft. Nachfolgende Jobs müssen wissen, auf welchem Knoten und in welchem Verzeichnis sie ausgeführt werden; bei der Deaktivierung muss die Registrierung bereinigt werden.

  1. 01

    Ausführungsidentität vor der Registrierung prüfen

    Eine eigene Ausführungsidentität und ein Arbeitsverzeichnis erstellen. Sicherstellen, dass die Identität das Repository lesen und in das Build-Verzeichnis schreiben darf, aber nicht automatisch administrative Rechte ohne Bezug zum Build besitzt.

    Prüfung: Manuelle Aufgabe kann mit derselben Identität abgeschlossen werden
  2. 02

    Tatsächliche Fähigkeiten mit Labels beschreiben

    Labels sollten Region, Chipfamilie, Xcode-Hauptversion und Zweck beschreiben. Bezeichnungen wie „neueste“ oder „schnellste“, die mit der Zeit unzutreffend werden, vermeiden.

    Prüfung: Planungskriterien treffen eindeutig auf den Zielknoten zu
  3. 03

    Arbeitsverzeichnisse isolieren

    Für unterschiedliche Repositories oder Pipelines eigene Unterverzeichnisse verwenden und Cache-Verzeichnisse separat verwalten. Temporäre Dateien nach Abschluss löschen, aber weiterhin benötigte Caches mit eindeutiger Herkunft behalten.

    Prüfung: Zwei Aufgaben überschreiben keine Artefakte der jeweils anderen
  4. 04

    Parallelität und Ressourcenkonflikte begrenzen

    Mit einer einzelnen Aufgabe beginnen, CPU, Arbeitsspeicher, Datenträger und Build-Dauer beobachten und erst danach über mehr Parallelität entscheiden. Grafische Aufgaben und umfangreiche Builds nicht ohne Dokumentation gleichzeitig ausführen.

    Prüfung: Auslagerungsspeicher wächst während Spitzenlast nicht dauerhaft
  5. 05

    Bei Deaktivierung vollständig abmelden

    Zuerst keine neuen Aufgaben mehr annehmen, die aktuelle Aufgabe abschließen lassen, dann den runner auf der Automatisierungsplattform abmelden und Registrierungstoken sowie nicht mehr benötigte Arbeitsverzeichnisse entfernen.

    Prüfung: Alte Labels nehmen keine Aufgaben mehr an
Dasselbe Arbeitsverzeichnis niemals mehreren parallelen Aufgaben überlassen. Abhängigkeits-Caches, DerivedData, Archive und temporäre Signaturdateien können sich gegenseitig überschreiben und scheinbar zufällige Build-Fehler verursachen.
Begriffsklärung

Acht Begriffe mit einheitlicher Bedeutung

Einheitliche Begriffe in Tickets und Teamdokumentation verhindern, dass Netzwerk, Gerät, Sitzung und Build-Tools vermischt beschrieben werden.

Physischer Knoten
Das Hardwaregerät, auf dem macOS tatsächlich ausgeführt wird. Eine BookaMac-Bestellung entspricht einem physischen Mac mini, keiner abstrakten gemeinsam genutzten Recheninstanz.
Dediziert
Das Gerät wird während der Mietdauer gemäß Bestellung von einem Kunden genutzt; Workloads anderer Kunden teilen nicht dieselbe physische Maschine.
Cloud Mac
Ein Mac an einem entfernten Knoten, der über das Netzwerk erreichbar ist. Der Begriff beschreibt Standort und Zugriffsart, nicht eine virtuelle Maschine.
VNC
Verbindungsart zum Anzeigen und Bedienen der grafischen macOS-Oberfläche, geeignet für Aufgaben mit Fenstern, Anzeige und Interaktion.
SSH
Verschlüsselte Kommandozeilenverbindung für Skripte, Dateiübertragung, Build-Verwaltung und das Erfassen diagnostischer Logs.
self-hosted runner
Vom Team selbst registrierter und verwalteter Automatisierungs-Executor, der Aufgaben auf einem bestimmten dedizierten physischen Mac-Knoten ausführt.
Build-Cache
Zwischendaten, die wiederholte Downloads und Kompilierungen reduzieren. Caches beschleunigen Aufgaben, können aber bei Versionswechseln zu Umgebungsabweichungen führen.
Bereitstellungsprofil
Ein Bestandteil des Signaturkonfigurationsmaterials für Release- und Testabläufe. Nach Projektberechtigungen verwalten und bei Übergabe oder Außerbetriebnahme bereinigen.
Symptom-Entscheidungsbaum

Von der beobachteten Erscheinung zur nächsten Prüfung

Den passendsten Symptomabschnitt öffnen. Nach jedem Prüfschritt erst mit dem nächsten fortfahren und keine Zwischenschritte ohne dokumentiertes Ergebnis überspringen.

Knoten nicht erreichbar: Was sollte zuerst geprüft werden?
  1. Adresse bestätigen:Hostadresse, Port und Benutzernamen aus den aktuellen Bestellübergabedaten erneut kopieren.
  2. Zeitüberschreitung und Ablehnung unterscheiden:Bei einer Zeitüberschreitung zuerst lokales Netzwerk oder Übertragungsweg prüfen; bei sofortiger Ablehnung Adresse, Port und Verbindungsart.
  3. Ausführliche Logs öffnen:Mit ssh -v prüfen, ob die Netzwerkverbindung hergestellt wurde, die Fingerabdruckprüfung erfolgreich war und an welchem Authentifizierungsschritt es stoppt.
  4. In einem anderen vertrauenswürdigen Netzwerk erneut testen:Bei abweichenden Ergebnissen beide Netzwerkumgebungen dokumentieren und nicht nur „manchmal funktioniert es“ melden.
  5. Support eskalieren:Wenn mehrere Netzwerke fehlschlagen, Bestellkennung, Region, Zeitpunkt und bereinigte ausführliche Logs dem Ticket beifügen.
Build fehlgeschlagen: Xcode-, Projekt- oder Abhängigkeitsproblem?
  1. Version festhalten:Die Ausgaben von xcode-select -p und xcodebuild -version dokumentieren.
  2. Ziele auflisten:Bestätigen, dass scheme-, configuration-, workspace- oder project-Name tatsächlich vorhanden ist.
  3. Ersten Fehler finden:Den ersten eindeutigen Fehler im Log lokalisieren, statt aus der abschließenden Fehlerschlagzeile rückwärts zu raten.
  4. Abhängigkeiten prüfen:Abhängigkeiten anhand der Sperrdatei erneut auflösen, ohne Projektdateien zu ändern, und die Ergebnisse vergleichen.
  5. Bereich eingrenzen:Mit dem kleinsten Ziel separat bauen, um zwischen Umgebungs-, Projektkonfigurations- und modulspezifischem Fehler zu unterscheiden.
Speicherplatz knapp: Welche Verzeichnisse zuerst prüfen?
  1. Gesamtauslastung prüfen:Mit df -h den Speicher auf Volume-Ebene anzeigen, nicht nur ein einzelnes Projektverzeichnis prüfen.
  2. Große Verzeichnisse lokalisieren:DerivedData, Archive, Simulatordaten, Abhängigkeits-Caches und Runner-Arbeitsverzeichnisse prüfen.
  3. Caches und Artefakte unterscheiden:Caches können neu erstellt werden; Lieferartefakte und Diagnose-Logs zuerst archivieren und erst danach löschen.
  4. Aktive Aufgaben stoppen:Vor dem Bereinigen sicherstellen, dass kein Build in das Zielverzeichnis schreibt, damit kein beschädigter Zwischenstand entsteht.
  5. Ursprung des Wachstums erneut prüfen:Nach der Bereinigung den zusätzlichen Speicherverbrauch des nächsten Jobs beobachten und das tatsächlich dauerhaft wachsende Verzeichnis ermitteln.
Zertifikat oder Bereitstellungsprofil fehlerhaft: Wie vermeidet man eine blinde Neuinstallation?
  1. Originalfehler dokumentieren:Zwischen nicht gefunden, abgelaufen, fehlenden Berechtigungen und nicht passender Konfiguration unterscheiden.
  2. Build-Ziel abgleichen:Bestätigen, dass aktuelles scheme, configuration und Signatureinstellungen zum erwarteten Projekt gehören.
  3. Schlüsselbundberechtigungen prüfen:Sicherstellen, dass die ausführende Build-Identität auf benötigtes Material zugreifen kann, ohne unnötige Berechtigungen auszuweiten.
  4. Bereitstellungsprofil abgleichen:Bestätigen, dass die Datei den Anforderungen der aktuellen Aufgabe entspricht, und nicht mehrere schwer unterscheidbare alte Versionen parallel behalten.
  5. Vertrauliches Material schützen:Im Ticket nur Fehler, Namen und erforderliche Metadaten übermitteln, niemals private Schlüssel oder vollständige Zugangsdaten.
Verbindungs- oder Build-Geschwindigkeit schwankt: Wie lässt sich der Fehlerbereich bestimmen?
  1. Zeitbereich angeben:Start, Ende und Dauer dokumentieren; „in letzter Zeit langsam“ nicht als einzige Beschreibung verwenden.
  2. Getrennt messen:Remote-Anzeige, Dateiübertragung, Abhängigkeitsdownload und lokalen Build separat beobachten und nicht zu einem einzigen Geschwindigkeitsurteil zusammenfassen.
  3. Parallele Aufgaben prüfen:Prüfen, ob andere Builds, Indexierungen, Transkodierungen oder Modellaufgaben gleichzeitig Ressourcen beanspruchen.
  4. Netzwerke vergleichen:Dieselbe Aktion in verschiedenen vertrauenswürdigen Netzwerken erneut testen, um lokalen Übertragungsweg und Auslastung entfernter Aufgaben zu unterscheiden.
  5. Beispielwerte aufbewahren:Region, Zeitpunkt, Befehlsdauer und bereinigte Logs einreichen, damit unter denselben Bedingungen erneut geprüft werden kann.
Supportweg

Was sollte ein direkt bearbeitbares Support-Ticket enthalten?

Zuerst die Fakten ordnen, dann über das Kontrollzentrum einreichen. Vollständiger Kontext führt meist schneller zur Ursache als mehrere nachgereichte, verstreute Screenshots.

01

Bestellkennung

Nur die erforderliche Bestellkennung angeben, keine Zahlungsdaten oder andere irrelevante Informationen senden.

02

Knotenregion

Singapur, Japan (Tokio), Südkorea (Seoul) oder Hongkong sowie die tatsächlich verwendete Verbindungsart angeben.

03

Zeitpunkt des Auftretens

Zeitzone, Zeitpunkt des ersten Auftretens, Dauer und Reproduzierbarkeit angeben.

04

Bereinigte Logs

Befehle, Exit-Code und Fehlerkontext aufbewahren; Token, Passwörter, private Schlüssel und vollständige Zugangsdaten ausblenden.

Zuerst nach der Dokumentation reproduzieren, dann die Belege ins Ticket übernehmen

Im Kontrollzentrum kannst du bestehende Bestellungen ansehen und technische Tickets einreichen. Wenn du noch eine Konfiguration auswählst, vergleiche zunächst Spezifikationen und geeignete Workflows der zwei dedizierten physischen Mac mini.

Zum Kontrollzentrum Konfigurationen vergleichen