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

Statyczne wdrożenie nie ma zdalnego punktu końcowego

Objaw: Uruchomienie npx rayfin up staticapp deploy zgłasza, że nie skonfigurowano żadnego zdalnego punktu końcowego.

Przyczyna: Wdrożenie tylko statyczne aktualizuje istniejące wdrożenie. Nie może udostępnić początkowej aplikacji zdalnej.

Rozwiązanie:

Przeprowadz pełne wdrożenie raz:

npx rayfin up

Po zakończeniu aprowizowania używaj npx rayfin up staticapp deploy do kolejnych aktualizacji obejmujących wyłącznie elementy statyczne.

Problemy z uwierzytelnianiem

Pozyskanie tokena uwierzytelniającego nie powiodło się

Objaw:npx rayfin login lub inne uwierzytelnione polecenie CLI zgłasza Failed to acquire authentication token lub błąd przechowywania poświadczeń.

Przyczyna: CLI nie jest zalogowany lub środowisko nie zapewnia przechowywania danych uwierzytelniających wspieranych przez system operacyjny.

Rozwiązanie:

Zaloguj się ponownie:

npx rayfin login

W przypadku ograniczonego lokalnego środowiska programistycznego bez przechowywania danych uwierzytelniających można włączyć zabezpieczenie szyfrowania:

npx rayfin login --encryption-fallback-enabled

Warning

Awaryjny mechanizm szyfrowania przechowuje pamięć podręczną tokenów w postaci zwykłego tekstu. Używaj go tylko w zaufanym środowisku deweloperskim. Nie używaj go w środowiskach produkcyjnych ani współtworzonych.

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,
});

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>

Limit czasu uwierzytelniania usługi Fabric został przekroczony

Objaw: Uwierzytelnianie Fabric nie działa po pięciu minutach.

Przyczyna: Portal Fabric nie zwrócił kodu przekazania, zanim przepływ wygasł.

Rozwiązanie:

Upewnij się, że returnOrigin jest zgodne ze źródłem Twojej aplikacji, zamknij wyskakujące okno i ponownie rozpocznij proces logowania.

Fabric SSO zgłasza niezgodność pochodzenia

Objaw: Przekazanie SSO w usłudze Fabric odrzuca odpowiedź, ponieważ jej źródło nie jest zgodne.

Przyczyna:returnOrigin, allowedRedirectUris lub fabricPortalUrl nie odpowiada środowisku, w którym działa aplikacja i portal Fabric.

Rozwiązanie:

Ustaw returnOrigin na czyste źródło aplikacji.
Potwierdź, że źródło pojawia się w services.auth.allowedRedirectUris.
Użyj adresu URL portalu Fabric, aby uzyskać odpowiedni środowisko produkcyjne, podglądowe lub programistyczne.
Uruchom npx rayfin up po zmianie rayfin.yml.

Więcej informacji można znaleźć w artykule Konfiguruj URI przekierowania uwierzytelniania.

`initEmbeddedAuth()` zwraca `null`

Objaw: Wbudowane uwierzytelnianie nie tworzy sesji.

Przyczyna: SDK nie wykryło, że aplikacja działa wewnątrz Fabric.

Rozwiązanie:

Dołącz ?fabricEmbedded=true do adresu URL aplikacji lub ustaw fabricEmbedded: true w FabricAuthOptions.

Fabric authentication zgłasza niezgodność stanu

Objaw: Logowanie kończy się niepowodzeniem, ponieważ stan odpowiedzi nie odpowiada statusowi żądania.

Przyczyna: Odpowiedź dotyczy wygasłego przepływu lub wcześniejszej próby logowania.

Rozwiązanie:

Zamknij wyskakujące okienko Fabric i ponownie rozpocznij proces logowania. Nie używaj ponownie URL-ów callback ani wartości stanów z wcześniejszych prób.

Problemy z modelem danych

Data API zwraca wewnętrzny błąd serwera po wdrożeniu

Objaw:npx rayfin up lub npx rayfin up db apply się udaje, ale GraphQL lub REST data API zwraca wewnętrzny błąd serwera.

Przyczyna: W Microsoft SQL Server pole @text() bez max generuje kolumnęNVARCHAR(MAX), co może uniemożliwić generowanie schematu GraphQL.

Rozwiązanie:

Dodaj wyraźną maksymalną długość do każdego dotkniętego pola tekstowego:

@text({ max: 200 })
title!: string;

Następnie przejrzyj i zastosuj zmianę schematu:

npx rayfin up db apply --force

Caution

Przejrzyj wszystkie zgłoszone operacje przed użyciem --force. Ta opcja może spowodować trwałą utratę danych.

Usługa danych wymaga dialektu

Objaw: Wdrożenie kończy się niepowodzeniem po odpowiedzi HTTP 400 i raportuje Dialect is required when Data module is enabled.

Przyczyna:services.data.enabled to true, ale rayfin.yml nie definiuje dialektu.

Rozwiązanie:

Konfiguruj Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Nowy podmiot nie jest dostępny po wdrożeniu

Objaw: Wdrożenie się powiodło, ale zapytania wobec nowej lub zmienionej jednostki zawodzą lub zachowują się, jakby ta jednostka nie istniała.

Przyczyna: Schemat bazy danych może nadal działać, albo frontend może używać przestarzałych generowanych typów lub konfiguracji w pamięci podręcznej.

Rozwiązanie:

Sprawdź miejsce rozmieszczenia:
```
npx rayfin up status
```
Poczekaj, aż wdrożenie będzie działać prawidłowo.
Odśwież lub odbuduj frontend.
Jeśli podmiot nadal zawodzi, zastosuj schemat wprost:
```
npx rayfin up db apply
```

Pełny przepływ pracy można znaleźć w artykule Zastosowanie i weryfikacja zmian schematu.

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:

Sprawdź, czy dekoratory relacji są obecne:
```
@one(() => Notebook) notebook?: Notebook;
```
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:

Sprawdź, czy zasady używają poprawnych nazw oświadczeń (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
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:

Zatrzymaj backend.
Usuń katalog .temp/ w rayfin/:
```
rm -rf rayfin/.temp/
```
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:

Sprawdź, czy Node.js i narzędzie npm są zainstalowane:
```
node --version
npm --version
```
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 zarządzaniem tajemnicą

Tajne polecenie nie wywołuje wywołania

Objaw:npx rayfin secret set <NAME> Kończy działanie bez monitu o podanie wartości.

Przyczyna: Standardowe wejście nie jest interaktywnym terminalem lub zmienna środowiskowa CI jest ustawiona na true. Polecenie używa interaktywnego monitu z maskowaniem.

Rozwiązanie:

Skorzystaj z jednej z następujących wspieranych alternatyw do tworzenia tajemnic nieinteraktywnych:

Ustaw jeden sekret, przesyłając jego wartość do polecenia:

Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin

Ustaw wiele sekretów z pliku środowiskowego:

npx rayfin secret set --env-file .\secrets.env

Nie przechowuj tajnych wartości w historii powłoki i nie zapisuj secret.txt ani .\secrets.env w kontroli wersji.

Tajne dowództwo zwraca zgodę odrzuconą

Objaw:npx rayfin secret set lub npx rayfin secret list zwraca błąd uprawnień.

Przyczyna: Aplikacja nie jest wdrożona lub konto zalogowane nie ma dostępu do docelowego workspace Fabric.

Rozwiązanie:

Uruchom npx rayfin up, aby przygotować aplikację.
Uruchom npx rayfin login i wybierz konto z dostępem do przestrzeni roboczej.
Spróbuj ponownie z tajnym poleceniem.

Więcej informacji można znaleźć w sekcji Zarządzaj sekretami funkcji.

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:

Uruchom polecenie kompilacji ręcznie:
```
npm run build
```
Napraw wszelkie zgłoszone błędy.
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:

Cofnij wszelkie ręczne zmiany w schemacie zdalnej bazy danych, aby pasowały do schematu w kodzie aplikacji.
Jeśli agent kodujący dokonał niewspieranej zmiany schematu w kodzie aplikacji, polec agentowi przywrócenie tej zmiany.
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:

Przejrzyj dzienniki kontenerów:
```
docker compose logs -f
```
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:

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

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-09-29

Rozwiązywanie problemów z aplikacjami Fabric

Problemy z wdrażaniem

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

Wdrożenie statyczne przekracza limit rozmiaru

Statyczne wdrożenie nie ma zdalnego punktu końcowego

Problemy z uwierzytelnianiem

Pozyskanie tokena uwierzytelniającego nie powiodło się

Sesja nie utrzymuje się po zalogowaniu

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

Limit czasu uwierzytelniania usługi Fabric został przekroczony

Fabric SSO zgłasza niezgodność pochodzenia

initEmbeddedAuth() zwraca null

Fabric authentication zgłasza niezgodność stanu

Problemy z modelem danych

Data API zwraca wewnętrzny błąd serwera po wdrożeniu

Usługa danych wymaga dialektu

Nowy podmiot nie jest dostępny po wdrożeniu

Relacje nie pojawiają się w API

Zasady autoryzacji nie działają

Nieaktualne odpowiedzi API

Problemy z interfejsem wiersza polecenia

Nie znaleziono polecenia

Niezgodność wersji CLI

Globalne i lokalne niedopasowanie wersji CLI

Problemy z zarządzaniem tajemnicą

Tajne polecenie nie wywołuje wywołania

Tajne dowództwo zwraca zgodę odrzuconą

Problemy z kompilacją i pakowaniem

Polecenie kompilacji kończy się niepowodzeniem

Pusty folder statyczny

Problemy z bazą danych

Zastosowanie schematu bazy danych nie powiodło się

Odmowa połączenia

Utrata danych po ponownym uruchomieniu

Znane ograniczenia

Uzyskaj pomoc

Treści powiązane

Opinia

Dodatkowe zasoby

`initEmbeddedAuth()` zwraca `null`