Rozwiązywanie problemów z aplikacjami Fabric

Diagnozowanie typowych problemów podczas opracowywania lub wdrażania projektu Fabric Apps. W tym artykule opisano problemy z logowaniem, usługami lokalnymi, zmianami schematu, hostem statycznym i interfejsem wiersza polecenia.

Problemy z wdrażaniem

Wdrożenie kończy się niepowodzeniem z powodu błędu 401 lub 403

Objawem: Uruchomienie npx rayfin up zwraca błąd uwierzytelniania.

Przyczyna: Twoja sesja uwierzytelniania wygasła lub nie zalogowano się.

Rozwiązanie:

Ponowne uwierzytelnianie i ponów próbę wdrożenia:

npx rayfin login
npx rayfin up

Wdrożenie statyczne przekracza limit rozmiaru

Objawem: Wdrażanie zawartości statycznej kończy się niepowodzeniem z powodu błędu limitu rozmiaru.

Przyczyna: Skompresowane archiwum przekracza 100 MB.

Rozwiązanie:

Zmniejsz rozmiar danych wyjściowych kompilacji, wykonując następujące zadania:

  • Wykluczanie map źródłowych z kompilacji produkcyjnych
  • Optymalizowanie lub usuwanie dużych obrazów i wideo
  • Przenoszenie plików binarnych do pamięci masowej zamiast dołączania ich do pakietu
  • Weryfikowanie konfiguracji pakietu wyklucza artefakty programistyczne

Problemy z uwierzytelnianiem

Sesja nie utrzymuje się po zalogowaniu

Objawem: Użytkownicy są wylogowani natychmiast po uwierzytelnieniu.

Przyczyna: Klient nie jest skonfigurowany z poprawnym bazowym adresem URL ani kluczem publicznym.

Rozwiązanie:

Sprawdź, czy konfiguracja RayfinClient odpowiada Twojemu backendowi:

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

Zablokowano wyskakujące okno logowania SSO w usłudze Fabric

Symptom: Przeglądarka blokuje okno portalu Fabric podczas logowania.

Przyczyna:ensureSignedInWithFabric() nie zostało wywołane z procedury obsługi gestu użytkownika.

Rozwiązanie:

Wywołaj funkcję z synchronicznej procedury obsługi zdarzeń:

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

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

Problemy z modelem danych

Relacje nie pojawiają się w API

Objawem: Pola powiązanej jednostki nie są dostępne podczas wykonywania zapytań.

Przyczyna: Brakuje dekoratora nawigacji lub schemat nie został zastosowany.

Rozwiązanie:

  1. Sprawdź, czy dekoratory relacji są obecne:

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

  2. Ponownie zastosuj schemat.

Zasady autoryzacji nie działają

Objawem: Użytkownicy mogą uzyskiwać dostęp do rekordów, których nie powinni widzieć.

Przyczyna: Wyrażenie zasad jest nieprawidłowe lub nazwy oświadczeń nie są zgodne.

Rozwiązanie:

  1. Sprawdź, czy zasady używają poprawnych nazw oświadczeń (sub, email, role):

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

  2. Zapisz w logach zdekodowany token JWT, aby sprawdzić, czy wartości deklaracji odpowiadają wartościom w kodzie.

Nieaktualne odpowiedzi API

Objawem: Fronton zwraca nieaktualne kształty danych po zmianie schematu.

Przyczyna: Wygenerowana konfiguracja jest przechowywana w pamięci podręcznej.

Rozwiązanie:

  1. Zatrzymaj backend.

  2. Usuń katalog .temp/ w rayfin/:

    rm -rf rayfin/.temp/

  3. Uruchom ponownie usługi i ponownie zastosuj schemat.

Problemy z interfejsem wiersza polecenia

Nie znaleziono polecenia

Objaw: Po uruchomieniu npx rayfin wyświetla się komunikat „nie znaleziono polecenia”.

Przyczyna: Narzędzie CLI nie jest zainstalowane lub npm nie znajduje się w zmiennej PATH.

Rozwiązanie:

  1. Sprawdź, czy Node.js i narzędzie npm są zainstalowane:

    node --version
npm --version

  2. Zainstaluj ponownie zależności:

    npm install

Niezgodność wersji CLI

Objaw: Polecenia CLI zwracają nieoczekiwane błędy po aktualizacji.

Przyczyna: Buforowana wersja CLI jest nieaktualna.

Rozwiązanie:

Zaktualizuj i zainstaluj ponownie:

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

Globalne i lokalne niedopasowanie wersji CLI

Objaw: Polecenia CLI kończą się nieoczekiwanymi błędami we wszystkich projektach.

Przyczyna: Globalna i lokalna instalacja CLI oraz niezgodność ich wersji.

Rozwiązanie: Zweryfikuj wersję lokalną npm list @microsoft/rayfin-cli. To pokazuje wersję w katalogu node_modules bieżącego projektu. Sprawdź wersję npm list -g @microsoft/rayfin-cliglobalną . Spowoduje to wyświetlenie zainstalowanej wersji dla całego systemu. Użyj npm uninstall -g z pakietem CLI Rayfin, aby usunąć globalną wersję i korzystać z wersji lokalnych.

Problemy z kompilacją i pakowaniem

Polecenie kompilacji kończy się niepowodzeniem

Objawem: Wdrażanie hostingu statycznego kończy się niepowodzeniem, ponieważ polecenie kompilacji nie wygenerowało żadnych danych wyjściowych.

Spowodować: Błędy kompilacji lub nieprawidłowo skonfigurowane polecenie kompilacji.

Rozwiązanie:

  1. Uruchom polecenie kompilacji ręcznie:

    npm run build

  2. Napraw wszelkie zgłoszone błędy.

  3. Sprawdź, czy folder wyjściowy zawiera pliki.

Pusty folder statyczny

Objawem: Wdrażanie statyczne kończy się niepowodzeniem z powodu błędu "pusty folder".

Spowodować: Skonfigurowana folder ścieżka jest niepoprawna.

Rozwiązanie:

Sprawdź, czy ścieżka folder w rayfin.yml odpowiada danym wyjściowym kompilacji:

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

Problemy z bazą danych

Zastosowanie schematu bazy danych nie powiodło się

Objaw: Uruchomienie npx rayfin up db apply lub npx rayfin up db apply --force kończy się niepowodzeniem.

Przyczyna: Schemat w zdalnej bazie danych oraz schemat zdefiniowany w kodzie aplikacji są niezsynchronizowane. Kod aplikacji jest źródłem prawdy dla aplikacji Fabric.

Nie modyfikuj zdalnego schematu bazy danych przez portal Fabric, SQL Server Management Studio (SSMS), rozszerzenie SQL Server do Visual Studio Code ani inne narzędzia SQL. Następujące zmiany kolumn w jednostce danych nie są obsługiwane:

  • Zmiana nazwy kolumny.
  • Zmiana typu danych kolumny.
  • Usuwanie kolumny.

Dodanie kolumny jest obsługiwane. Usunięcie lub zmiana istniejącej kolumny może zepsuć działanie aplikacji i jej wdrożenie do Fabric.

Rozwiązanie:

  1. Cofnij wszelkie ręczne zmiany w schemacie zdalnej bazy danych, aby pasowały do schematu w kodzie aplikacji.

  2. Jeśli agent kodujący dokonał niewspieranej zmiany schematu w kodzie aplikacji, polec agentowi przywrócenie tej zmiany.

  3. Ponownie uruchom polecenie schema apply:

    npx rayfin up db apply

    W przypadku zmiany nazwy kolumny --force może umożliwić ukończenie aktualizacji schematu:

    npx rayfin up db apply --force

    Caution

    Użycie --force może spowodować trwałą utratę danych. Przejrzyj proponowane operacje i popewnij, że akceptujesz ryzyko utraty danych, zanim przystąpisz do dalszych działań.

Odmowa połączenia

Objaw: Operacje na danych nie powiodą się z powodu błędów połączenia.

Przyczyna: Kontener bazy danych nie jest uruchomiony lub kontrole kondycji zakończyły się niepowodzeniem.

Rozwiązanie:

  1. Przejrzyj dzienniki kontenerów:

    docker compose logs -f

  2. Uruchom ponownie usługi.

Utrata danych po ponownym uruchomieniu

Objawem: Dane znikają po zatrzymaniu i uruchomieniu usług.

Przyczyna: Woluminy zostały usunięte przy użyciu polecenia --purge.

Rozwiązanie:

Użyj --down zamiast --purge , aby zachować dane.

Znane ograniczenia

Aby zapoznać się z bieżącymi ograniczeniami i zalecanymi obejściami, zobacz:

  • count() nie jest dostępne w kliencie Fluent GraphQL — użyj results.length.
  • Relacje wiele-do-wielu nie są obsługiwane — użyj jawnej jednostki sprzężenia.
  • Obiekty sesji są nieprzejrzyste — sprawdź właściwości isAuthenticated lub user.
  • Po włączeniu lub wyłączeniu uwierzytelniania w programie rayfin.ymluruchom ponownie zaplecze.

Uzyskaj pomoc

Jeśli problem nadal występuje:

  1. Zapoznaj się z dokumentacją Fabric Apps.
  2. Sprawdź repozytorium GitHub pod kątem znanych problemów.
  3. Prześlij zgłoszenie błędu wraz ze szczegółowymi logami i krokami odtworzenia problemu.

Treści powiązane

  • Last updated on