Fehlerbehebung für den Desktop

Identifizieren Sie die Laufzeit, bevor Sie sie ändern

Eine Desktop-Sitzung hat separate Fehlergrenzen: Vite stellt während der Entwicklung Frontend-Assets bereit; Der Tauri-Rust-Prozess verfügt über eine native Integration. Der Bun-Sidecar bedient Anwendungsanfragen und Persistenz. Die SolidJS-Webansicht stellt eine Verbindung zu dieser API her. Ein leeres Fenster, ein Boot-Timeout, eine 401-Antwort und eine leere Projektliste können unterschiedliche Ursachen haben.

Notieren Sie den Startbefehl und ob der Endpunkt von Tauri- oder Vite-Variablen stammt. Löschen Sie keine Datenbank und installieren Sie keine Abhängigkeiten neu, nur weil eine andere Laufzeit andere Daten anzeigt.

Verstehen Sie den Startzeitpunkt

Die Rust-Shell generiert ein Starttoken, löst Anwendungsdaten und Migrationsverzeichnisse auf und erzeugt den Ziel-Sidecar. Das Kind bindet 127.0.0.1 auf einem vergänglichen Hafen. Es wartet, bis es öffentlich ist /api/health antwortet und schreibt dann ein JSON-fähiges Ereignis mit diesem Port. Die Webansicht wird aufgerufen get_sidecar_endpoint und erstellt seine verwaltete API-Laufzeit.

„Retry“ startet die Verbindungsversuche mit der Webansicht neu. es füllt das erschöpfte Rust-Aufsichtsbudget nicht wieder auf. Beheben Sie die Startursache und starten Sie die App neu, wenn der Supervisor den Status „Terminalfehler“ erreicht hat. Ein Port vor einem untergeordneten Neustart kann veraltet sein.

Überprüfen Sie Ports und Zustand separat

Vite verwendet localhost:1420 mit strikter Portauswahl, passend zur konfigurierten Entwicklungs-URL von Tauri. Es schlägt fehl, anstatt stillschweigend zu einem anderen Port zu wechseln. Der Sidecar-Port hat nichts damit zu tun und ändert sich zwischen den Starts. Der begleitende HTTPS-Port ist ein dritter Listener, Standard 8443, und Studio verwendet Loopback 4396.

CADCAM_URL=http://127.0.0.1:43111
CADCAM_TOKEN=local-development-token

curl --max-time 5 --fail-with-body "$CADCAM_URL/api/health"
curl --max-time 5 --fail-with-body "$CADCAM_URL/health"   -H "Authorization: Bearer $CADCAM_TOKEN"
curl --max-time 5 --fail-with-body "$CADCAM_URL/version"   -H "Authorization: Bearer $CADCAM_TOKEN"

Die öffentliche Gesundheitsroute gibt Status und Zeitstempel zurück. Authentifizierte Systemrouten legen die Bereitschaft und die Anwendungsversion offen. Ein fehlerfreier Prozess beweist nicht, dass alle Anbieter, Datenbankabfragen oder nativen Dialoge funktionieren. Vergleichen Sie die Gesundheits-API und System-API bei der Sondenauswahl.

Wenn Port 1420 belegt ist, identifizieren und stoppen Sie absichtlich den vorhandenen Entwicklungsserver. Wenn ein gespeicherter API-Port Verbindungen ablehnt, lesen Sie das aktuelle Bereitschaftsereignis oder lösen Sie den Tauri-Endpunkt erneut auf, anstatt benachbarte Ports zu erraten.

Reproduzieren Sie mit einem isolierten Sidecar

Ein Quellprozess ist nützlich, um native Bundle-Probleme vom Serververhalten zu trennen. Führen Sie dies vom Repository-Stammverzeichnis in einem interaktiven Terminal aus. Es erstellt ein neues Datenverzeichnis und verwendet explizit den generierten Migrationsordner.

CADCAM_DIAGNOSTIC_DIR=$(mktemp -d /tmp/cadcamfun-desktop-guide.XXXXXX)
CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR="$CADCAM_DIAGNOSTIC_DIR/data" CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" CADCAMFUN_AI_OFFLINE=true bun --no-env-file apps/sidecar/src/main.ts

Kopieren Sie den angekündigten Port in die Probe-Variablen in einem zweiten Terminal. Der Offline-KI-Modus vermeidet die Abhängigkeit von einem konfigurierten Remote-Modell für grundlegende Startdiagnosen. Es wird kein alternatives lokales Modell ausgeführt. Der Server beobachtet stdin EOF, ein explizites Shutdown-Ereignis und normale Laufzeitinterrupts.

Ein Quellprozess verwendet aktuelle Dateien. Ein nativer Prozess verwendet die kompilierte ausführbare Datei, die bereits bereitgestellt wurde src-tauri/binaries. Wenn nur der kompilierte Lauf fehlschlägt, führen Sie einen Neuaufbau durch bun run build:sidecar und prüfen Sie Bündelungs-/Migrationsressourcen. Durch das Bearbeiten von TypeScript wird eine bereits laufende ausführbare Datei nicht ersetzt.

Lösen Sie den tatsächlichen Datenbankpfad auf

Diese Dateien sind keine Aliase. Passen Sie den ausgewählten Prozesspfad an, bevor Sie fehlende Zeichnungen untersuchen. Browser-Fixtures öffnen diese SQLite-Dateien niemals. Der Sidecar wendet Migrationen nur an, wenn seine Konfiguration einen Migrationsordner bereitstellt; Wenn Sie es weglassen, wird der Quellbaumordner nicht automatisch erkannt.

Die Datenbankschicht ermöglicht WAL und Fremdschlüssel. Vor einem bestehenden Datenbank-Upgrade wird ein automatisches Backup vor der Migration erstellt und fünf passende Backups aufbewahrt. Ein solches Backup wird nicht bei jedem Speichern, unveränderten Start, ersten Erstellen oder In-Memory-Test erstellt. Bewahren Sie eine konsistente Sicherung durch das Datenbank-/Wiederherstellungsverfahren; Durch das Kopieren nur der Hauptdatei einer laufenden WAL-Datenbank können festgeschriebene WAL-Inhalte weggelassen werden.

Protokollausgabe und Protokolle lesen

In einem Quell-Sidecar-Terminal ist stdout für Bereitschafts-/Fehlerprotokollereignisse reserviert und JSON-Anwendungsprotokolle gehen an stderr. In der nativen App erfasst das Rust-Protokollierungs-Plugin Shell-seitige Ereignisse, einschließlich überwachter untergeordneter Ausgaben. Die Shell schwärzt Zeilen, die möglicherweise ihre Startanmeldeinformationen enthalten.

Der Eingeborene get_logs_dir der Befehl löst das Anwendungsprotokollverzeichnis des Betriebssystems auf. Dies ist zuverlässiger als die Annahme eines universellen Pfads über alle Systeme hinweg. Eine Entwicklerdiagnose innerhalb der Webansicht kann sie über die vorhandene Tauri-Befehlsschnittstelle aufrufen; Das Öffnen nativer Pfade ist auf zulässige Ordner beschränkt und ausführbare Dateitypen werden abgelehnt.

Die wiederverwendbare Boot-Screen-Komponente unterstützt einen optionalen View-Logs-Rückruf, aber der aktuelle App.tsx leitet diesen Rückruf nicht weiter. Gehen Sie nicht davon aus, dass während eines Startfehlers die Schaltfläche „Protokolle anzeigen“ angezeigt wird. Halten Sie das Entwicklungsstartterminal verfügbar oder verwenden Sie das native Protokollverzeichnis über eine geeignete Diagnoseoberfläche.

Geben Sie für einen Bericht den Startmodus, nicht geheime Daten/Migrationspfade, die verstrichene Wartezeit, die aktuelle API-Version, das genaue Fehlertag/die genaue Fehlernachricht und die letzten relevanten Startereignisse an. Schwärzen Sie Start-/Sitzungs-/Gerätetokens, Kopplungslinks, Modellschlüssel und Signaturmaterial.

Unterscheiden Sie die Authentifizierung von leeren Daten

Der Real-Client-Modus des Browsers erfordert beides VITE_SIDECAR_URL und VITE_SIDECAR_TOKEN. Eine URL ohne Token aktiviert den Fake-Fallback nicht; Die Endpunktauflösung schlägt fehl. Variablen müssen bereitgestellt werden, bevor Vite startet. Durch das Aktualisieren einer übergeordneten Shell wird ein bereits laufender Server nicht neu konfiguriert.

VITE_SIDECAR_URL=http://127.0.0.1:43111 VITE_SIDECAR_TOKEN=local-development-token bun run --filter @cadcamfun/desktop dev

Geschützte Aufrufe können zusätzlich zum Anwendungstoken den Kontositzungskontext verwenden. Companion- und Standalone-Bridge-Token haben einen engeren Geltungsbereich und sind kein Ersatz für ein Start-Token. Ein 401 benötigt eine Diagnose der Anmeldeinformationen; a 403 benötigt Betriebs-/Zugriffsdiagnose; Ein fehlendes oder unzugängliches Projekt kann als 404 gemeldet werden.

Einige Bildschirme, einschließlich der Registerkarten für untergeordnete Projektressourcen, wandeln derzeit einzelne Listenfehler in leere Arrays um. Eine leere Registerkarte ist kein ausreichender Beweis dafür, dass Datensätze gelöscht wurden. Lesen Sie das entsprechende projekt, zeichnung, oder werkzeugweg endpunkt, bevor Sie die Arbeit neu erstellen.

Ein gültiges Starttoken besteht aus 64 Hexadezimalzeichen (32 zufälligen Bytes) und ändert sich bei jedem Start. Ein Token anderer Form wurde von der Desktop-Shell nicht ausgegeben.

Erkennen Sie Vorschau- und native Einschränkungen

Die gefälschte API verwaltet ausgewählte Projekte, Zeichnungen, Materialien, Werkzeuge, Maschinen, Werkzeugpfade, KV und Generatorpfade. Nicht unterstützte Sammlungen geben HTTP 501 mit einer vorschauspezifischen Meldung zurück. Die Gerätedaten gehören zur laufenden Seite. Eine erfolgreiche Vorschauaktion kann kein anhaltendes Organisations-, Plugin-, Abrechnungs- oder Live-Anbieterverhalten nachweisen.

Native Dialoge, Schlüsselbundvorgänge, Taskleiste, Updater und macOS-Materialien erfordern den Tauri-Host und die richtigen Funktionen. Ein registrierter Befehl kann für die Webansicht im Rahmen seiner Funktionskonfiguration immer noch nicht verfügbar sein. Beim Öffnen von Dateien registriert die Shell unterstützte Verknüpfungen und leitet Pfade weiter; Das allein beweist nicht, dass ein bestimmter Herausgeber die Inhalte importiert hat.

Grafikfehler sind eine weitere Grenze. Eine Containergröße ungleich Null, sichtbare Elemente/Ebenen, entsperrte Auswahl und unterstütztes WebGL sind Voraussetzungen für die relevanten Ansichtsfensterinteraktionen. Ein gerendertes Netz ist ein Beweis für das Rendern, nicht für eine erfolgreiche Speicherung oder CAM-Überprüfung. Benutzen Sie die ansichtsfenster-Diagnose für Worker-Kapazität, Timeout und Vier-Ansicht-Verhalten.

Beheben Sie Präferenz- und Anzeigeprobleme

Der freigegebene Webview-Einstellungsdatensatz ist cadcamfun.settings. Zu den Standardwerten gehören Millimeter, Systemdesign, drei Dezimalstellen, GRBL-Einstellung, aktivierter Schnappverschluss, Toleranz 0,01 mm und aktiviertes Glas. Gespeicherte Felder werden unabhängig validiert; Ungültige Werte werden zurückgesetzt, ohne dass die Shell ausfällt. Voller/blockierter lokaler Speicher kann Persistenz verhindern.

Beim Ändern der Anzeigeeinheiten wird die gespeicherte CAD-Geometrie nicht neu skaliert. Die Dokumenttoleranz wird über den gemeinsamen CAD-/Generator-/Überprüfungseinstellungs-Helper weitergegeben. Einige Feature-/Rotationswerte verwenden explizit Grad; Beim Zeichnen von Winkeln wird das Bogenmaß verwendet. Überprüfen Sie den Feldvertrag, bevor Sie eine numerische Nichtübereinstimmung als beschädigte Geometrie diagnostizieren.

Das Verhalten von Glass hängt von der Tauri/macOS-Unterstützung ab. Die Implementierung verwendet Liquid Glass, sofern unterstützt, Lebendigkeit auf älteren macOS-Geräten durch das Plugin und einen undurchsichtigen Fallback, wenn es nicht verfügbar oder deaktiviert ist. Themen-/Materialänderungen haben keine Auswirkungen auf die Geometrie, den Projekteigentümer oder die Bearbeitungsnachweise.

Bevorzugen Sie die entsprechenden Einstellungen oder Funktionskontrollen gegenüber dem Löschen des gesamten Webview-Speichers. Dieser Speicher kann auch Sitzungs-/Editor-Übergaben enthalten. Bei einem visuellen Zurücksetzen der Einstellungen handelt es sich nicht um eine Datenbankreparatur.

Trennen Sie die UI-Wiederherstellung vom Bearbeitungsnachweis

Ein geladenes Projekt, eine erfolgreiche HTTP-Speicherung, ein animierter Werkzeugweg und eine generierte NC sind unterschiedliche Beobachtungen. Bevor Sie sich auf ein gespeichertes Bearbeitungsergebnis verlassen, überprüfen Sie die genaue NC, die Quellzeichnung/das Quellmaterial, die Werkzeugbaugruppen, den Maschinenraum, den ausgewählten Beitrag und die Verifizierungsfreigabe/Probleme für dieses Ergebnis.

Der CAM-Snapshot-Code bewahrt Kernel-Beweise nur dann, wenn der aktuelle NC-Text und sein Hash übereinstimmen. Portable Programme schreiben, um die Konsistenz des Dokuments zu überprüfen und möglicherweise erfasste Kernel-Anfragen neu zu bewerten. Das Bearbeiten von NC oder das Ändern des Bestands kann frühere Beweise ungültig machen. Durch erneutes Öffnen der einfachen NC kann ein Programm analysiert werden, ohne dass derselbe Fertigungsnachweis wiederhergestellt werden muss.

Überprüfen Sie nach einem Absturz oder einer unterbrochenen Speicherung zunächst die gespeicherte Zeile und ihre Versionen. Beim CAM-Speichermodus wird das vorherige Programm vor einer Aktualisierung aufgezeichnet, während beim manuellen Speichern der Werkzeugwegdetails die aktualisierte Revision aufgezeichnet wird. Die Projekthistorie ist wieder getrennt. Verwenden der Geschichtsvergleich einen Wiederherstellungspfad wählen.

Wandeln Sie eine ungelöste Prüfung nicht in einen akzeptierten Vorgang um, da die Benutzeroberfläche wiederhergestellt wurde. Führen Sie die entsprechende Überprüfung anhand der tatsächlichen Ressourcen und NC erneut durch. Eine Anwendungszustandsprüfung hat keine Autorität über die Maschinensicherheit.

Triage jeweils einen Fehler

1. Notieren Sie den Startmodus, die Prozessversionen, die Ports und das tatsächliche Datenverzeichnis.
2. Prüfen Sie den Zustand, dann ein geschützter Lesevorgang. Trennen Sie Konnektivität von Autorisierung.
3. Überprüfen Sie strukturierte Start-/Migrationsfehler, bevor Sie etwas zurücksetzen oder löschen.
4. Reproduzieren Sie anhand eines isolierten Quellprozesses, wenn ein kompiliertes/natives Problem vermutet wird.
5. Beheben Sie die identifizierte Ursache, starten Sie den entsprechenden Prozess neu und aktualisieren Sie veraltete Endpunktvariablen.
6. Öffnen Sie das gespeicherte Dokument/Programm erneut und überprüfen Sie den beibehaltenen Status, die Versionen, die Exporte und die aktuelle Überprüfung.

Implementierungsanker sind app/App.tsx, app/sidecar.ts, src-tauri/src/{sidecar,commands,lib}.rs, Sidecar main.ts/config.ts/shutdown.ts, und der Datenbanklebenszyklus. Lokale Entwicklung liefert Konfigurationsdetails; begleiterpaarung verwaltet seine separate Netzwerkgrenze.

Checkliste für den Start

1. Ist die Sidecar-Binärdatei für diese Plattform vorhanden (src-tauri/binaries/sidecar-<target triple>)? desktop:dev baut es; tauri:dev kann einen Stub verwenden.
2. Werden Migrationen inszeniert? src-tauri/resources/migrations? bun run build:sidecar oder bun scripts/build.ts --only=resources inszeniert sie neu.
3. Habe den Sidecar gedruckt ready innerhalb von 60 Sekunden? Suchen Sie nach einem error zeile auf stdout und JSON-Protokolle auf stderr im Protokollverzeichnis (get_logs_dir).
4. Wurde es neu gestartet? Es ist nur ein automatischer Neustart zulässig; ein zweiter Fehler belässt den Status bei failed.
5. Tut GET /api/health antwort auf den gemeldeten Port? Wenn dies der Fall ist, aber geschützte Routen 401 zurückgeben, gehört das Token zu einem anderen Start.
6. Ist das Datenverzeichnis beschreibbar und wird die Datenbankdatei nicht von einem anderen Prozess mit inkompatiblen Migrationen geöffnet gehalten?

Lesen der Protokolle

Sidecar-Protokolle sind JSON-Zeilen auf stderr, die vom stdout-Handshake getrennt gehalten werden. Zeilen, die Anmeldeinformationen enthalten könnten, werden durch ersetzt [redacted: line may contain credentials] bevor sie geschrieben werden, daher wird eine geschwärzte Zeile in einem Protokoll erwartet, keine Beschädigung. Wenn der Handshake selbst eine solche Zeile trug, ist der gemeldete Startfehler die Schwärzungsmarkierung; Lesen Sie die umgebenden stderr-Zeilen für den Kontext.

Das Protokollverzeichnis ist plattformspezifisch. Holen Sie es sich von der get_logs_dir befehl, anstatt einen Pfad zu erraten, und öffnen Sie ihn mit open_path, das das Anwendungsprotokollverzeichnis akzeptiert.

Fehlermeldungen und was sie bedeuten

In 3D