Fehlerbehebung für Fabric-Apps

Diagnostizieren Sie häufige Probleme, wenn Sie ein Fabric Apps-Projekt entwickeln oder bereitstellen. In diesem Artikel werden Probleme mit der Anmeldung, lokalen Diensten, Schemaänderungen, statischem Hosting und der CLI behandelt.

Bereitstellungsprobleme

Die Bereitstellung schlägt mit dem Fehler 401 oder 403 fehl

Symptom: Beim Ausführen wird npx rayfin up ein Authentifizierungsfehler zurückgegeben.

Ursache: Ihre Authentifizierungssitzung ist abgelaufen oder Sie sind nicht angemeldet.

Solution:

Erneutes Authentifizieren und Wiederholen der Bereitstellung:

npx rayfin login
npx rayfin up

Datenbank-Apply-Berichte melden destruktive Änderungen

Symptom: Die Ausführung von npx rayfin up db apply wird mit einer Warnung vor Datenverlust blockiert.

Ursache: Die CLI hat Schemaänderungen erkannt, die Daten löschen können (Spalten ablegen, Tabellen umbenennen).

Solution:

Überprüfen Sie die aufgeführten Vorgänge sorgfältig. Wenn Sie den Datenverlust in Kauf nehmen, verwenden Sie --force:

npx rayfin up db apply --force

Statisches Deployment überschreitet das Größenlimit.

Symptom: Die Bereitstellung statischer Inhalte schlägt mit einem Größengrenzwertfehler fehl.

Ursache: Das komprimierte Archiv überschreitet 100 MB.

Solution:

Reduzieren Sie die Größe der Build-Ausgabe um:

• Source-Maps aus Produktions-Builds ausschließen
• Optimieren oder Entfernen großer Bilder und Videos
• Verschieben von Binärdateien in den Speicher, anstatt sie zu bündeln
• Überprüfen, ob die Bundler-Konfiguration Entwicklungsartefakte ausschließt

Authentifizierungsprobleme

Sitzung nach der Anmeldung nicht beibehalten

Symptom: Benutzer werden unmittelbar nach der Authentifizierung abgemeldet.

Ursache: Der Client ist nicht mit der richtigen Basis-URL oder dem Veröffentlichungsschlüssel konfiguriert.

Solution:

Überprüfen Sie, ob die RayfinClient Konfiguration Ihrem Back-End entspricht:

const client = new RayfinClient({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL ?? 'http://localhost:5168',
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

Fabric SSO-Popup blockiert

Symptom: Browser blockiert das Fabric Portalfenster während der Anmeldung.

Ursache:ensureSignedInWithFabric() wurde nicht von einem Benutzergestenhandler aufgerufen.

Solution:

Aufrufen der Funktion aus einem synchronen Ereignishandler:

async function handleClick() {
  await ensureSignedInWithFabric(client.auth, options);
}

// Attach to button click
<button onClick={handleClick}>Sign in</button>

Datenmodellprobleme

Beziehungen, die nicht in der API angezeigt werden

Symptom: Verwandte Entitätsfelder sind beim Abfragen nicht verfügbar.

Ursache: Der Navigationsdekoror fehlt, oder das Schema wurde nicht angewendet.

Solution:

1. Überprüfen Sie, ob die Beziehungsdekoratoren vorhanden sind:

   @one(() => Notebook) notebook?: Notebook;
   

2. Erneutes Anwenden des Schemas.

Autorisierungsrichtlinie funktioniert nicht

Symptom: Benutzer können auf Datensätze zugreifen, die sie nicht sehen sollten.

Ursache: Der Richtlinienausdruck ist falsch, oder die Anspruchsnamen stimmen nicht überein.

Solution:

1. Überprüfen Sie, ob die Richtlinie die richtigen Anspruchsnamen verwendet (sub, email, role):

   policy: (claims, item) => claims.sub.eq(item.user_id)
   

2. Protokollieren Sie die dekodierte JWT, um zu überprüfen, ob die Claim-Werte mit Ihrem Code übereinstimmen.

Veraltete API-Antworten

Symptom: Frontend gibt veraltete Daten-Shapes nach Schemaänderungen zurück.

Ursache: Die generierte Konfiguration wird zwischengespeichert.

Solution:

1. Stoppen Sie das Backend.

2. Löschen Sie das .temp/ Verzeichnis in rayfin/:

   rm -rf rayfin/.temp/
   

3. Starten Sie die Dienste neu und wenden Sie das Schema erneut an.

CLI-Probleme

Befehl nicht gefunden

Symptom: Wird ausgeführt npx rayfin , wird "Befehl nicht gefunden" zurückgegeben.

Ursache: Die CLI ist nicht installiert, oder npm befindet sich nicht in Ihrem PATH.

Solution:

1. Überprüfen Sie, Node.js und npm installiert sind:

   node --version
   npm --version
   

2. Installieren Sie Abhängigkeiten neu:

   npm install
   

CLI-Versionskonflikt

Symptom: CLI-Befehle schlagen nach dem Aktualisieren mit unerwarteten Fehlern fehl.

Ursache: Die zwischengespeicherte CLI-Version ist veraltet.

Solution:

Aktualisieren und erneutes Installieren:

npm update --save
npm install
npx rayfin --version

Abweichung zwischen globaler und lokaler CLI-Version

Symptom: CLI-Befehle schlagen bei unerwarteten Fehlern in Projekten fehl.

Ursache: Globale und lokale Installation der CLI-Versionen und stimmen nicht überein.

Lösung: Überprüfen der lokalen Version npm list @microsoft/rayfin-cli. Dies zeigt die Version im node_modules Ihres aktuellen Projekts an. Überprüfen Sie die globale Version npm list -g @microsoft/rayfin-cli. Dies zeigt die systemweit installierte Version an. Verwenden Sie npm uninstall -g das Rayfin CLI-Paket, um die globale Version zu entfernen und Ihre lokalen Versionen zu verwenden.

Build- und Paketierungsprobleme

Buildbefehl schlägt fehl

Symptom: Fehler bei der statischen Hostingbereitstellung, da der Buildbefehl keine Ausgabe erzeugt hat.

Ursache: Buildfehler oder falsch konfigurierter Buildbefehl.

Solution:

1. Führen Sie den Buildbefehl manuell aus:

   npm run build
   

2. Beheben Sie alle gemeldeten Fehler.

3. Überprüfen Sie, ob der Ausgabeordner Dateien enthält.

Leerer statischer Ordner

Symptom: Die statische Bereitstellung schlägt mit dem Fehler "Leerer Ordner" fehl.

Ursache: Der konfigurierte folder Pfad ist falsch.

Solution:

Überprüfen Sie, ob der Pfad folder in rayfin.yml mit Ihrer Build-Ausgabe übereinstimmt:

services:
  staticHosting:
    folder: dist  # Verify this matches your build output
    buildCommand: npm run build

Datenbankprobleme

Verbindung verweigert

Symptom: Datenvorgänge schlagen mit Verbindungsfehlern fehl.

Ursache: Der Datenbankcontainer läuft nicht, oder die Zustandsprüfungen sind fehlgeschlagen.

Solution:

1. Überprüfen von Containerprotokollen:

   docker compose logs -f
   

2. Starten Sie Dienste neu.

Datenverlust nach dem Neustart

Symptom: Daten verschwinden nach dem Beenden und Neustarten von Diensten.

Ursache: Volumes wurden mit --purge gelöscht.

Solution:

Verwenden Sie --down anstelle von --purge, um Daten zu erhalten.

Bekannte Einschränkungen

Aktuelle Einschränkungen und empfohlene Problemumgehungen finden Sie unter:

• count() ist im Fluent GraphQL-Client nicht verfügbar – verwenden Sie results.length.
• Viele-zu-viele-Beziehungen werden nicht unterstützt – verwenden Sie eine explizite Join-Entität.
• Sitzungsobjekte sind opak – prüfen Sie die Eigenschaften isAuthenticated oder user.
• Nachdem Sie die Authentifizierung in rayfin.yml aktiviert oder deaktiviert haben, starten Sie das Backend neu.

Hilfe erhalten

Falls das Problem weiterhin besteht:

1. Lesen Sie die Dokumentation Fabric Apps.
2. Überprüfen Sie das Repository GitHub auf bekannte Probleme.
3. Erstellen Sie einen Fehlerbericht mit detaillierten Protokollen und Reproduktionsschritten.

Verwandte Inhalte

• CLI-Referenz
• Deploy to Fabric
• Authentifizierung konfigurieren