Fejlfinding af Fabric-apps

Diagnosticer almindelige problemer, når du udvikler eller deployerer et Fabric Apps-projekt. Denne artikel omhandler problemer med login, lokale tjenester, skemaændringer, statisk hosting og CLI.

Udrulningsproblemer

Udrulning fejler med 401- eller 403-fejl

Symptom: Kørsel npx rayfin up giver en autentificeringsfejl.

Årsag: Din autentificeringssession udløb, eller du er ikke logget ind.

Løsning:

Genautentificér og prøv udrulningen igen:

npx rayfin login
npx rayfin up

Statisk udrulning overstiger størrelsesgrænsen

Symptom: Statisk indholdsudrulning fejler med en størrelsesbegrænsningsfejl.

Årsag: Det komprimerede arkiv overstiger 100 MB.

Løsning:

Reducer build-outputstørrelsen med:

  • Udelukkelse af kildekort fra produktionsbuilds
  • Optimering eller fjernelse af store billeder og videoer
  • At flytte binære filer til lagring i stedet for at samle dem
  • At verificere din bundler-konfiguration udelukker udviklingsartefakter

Godkendelsesproblemer

Sessionen består ikke efter login.

Symptom: Brugere logges ud straks efter autentificering.

Årsag: Klienten er ikke konfigureret med den korrekte basis-URL eller publicerbar nøgle.

Løsning:

Verd at konfigurationen matcher RayfinClient din backend:

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 blokeret

Symptom: Browseren blokerer Fabric portalvinduet under login.

Årsag:ensureSignedInWithFabric() blev ikke kaldt fra en bruger-gestus-håndterer.

Løsning:

Kald funktionen fra en synkron hændelseshåndterer:

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

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

Datamodelproblemer

Relationer, der ikke vises i API'et

Symptom: Relaterede entitetsfelter er ikke tilgængelige ved forespørgsler.

Årsag: Navigationsdekoratoren mangler, eller skemaet blev ikke anvendt.

Løsning:

  1. Sørg for, at relationsdekoratorerne er til stede:

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

  2. Påfør skemaet igen.

Autorisationspolitik virker ikke

Symptom: Brugere kan få adgang til optegnelser, de ikke burde se.

Årsag: Policeformuleringen er forkert, eller også stemmer kravnavnene ikke overens.

Løsning:

  1. Verificér, at policen bruger korrekte kravnavne (sub, email, role):

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

  2. Log den afkodede JWT for at verificere kravværdierne matcher din kode.

Forældede API-svar

Symptom: Frontend returnerer forældede dataformer efter skemaændringer.

Årsag: Den genererede konfiguration caches.

Løsning:

  1. Stop backend.

  2. Slet .temp/ mappen i rayfin/:

    rm -rf rayfin/.temp/

  3. Genstart tjenesterne og genanvend skemaet.

CLI-problemer

Kommando ikke fundet

Symptom: Kørende npx rayfin returnerer "kommando ikke fundet."

Årsag: CLI'en er ikke installeret, eller npm er ikke i din PATH.

Løsning:

  1. Tjek Node.js og npm er installeret:

    node --version
npm --version

  2. Geninstaller afhængigheder:

    npm install

CLI-versionsmismatch

Symptom: CLI-kommandoer fejler med uventede fejl efter opdatering.

Årsag: Den cachede CLI-version er forældet.

Løsning:

Opdater og geninstaller:

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

CLI global og lokal versionsmismatch

Symptom: CLI-kommandoer fejler med uventede fejl på tværs af projekter.

Årsag: Global og lokal installation af CLI-versionerne, og de matcher ikke.

Løsning: Valider lokal version npm list @microsoft/rayfin-cli. Dette viser versionen i dit nuværende projekts node_modules. Tjek global version npm list -g @microsoft/rayfin-cli. Dette viser den installerede version i hele systemet. Brug npm uninstall -g med Rayfin CLI-pakken til at fjerne den globale version og bruge dine lokale versioner.

Bygge- og emballageproblemer

Byg-kommandoen fejler

Symptom: Udrulning af statisk hosting fejler, fordi build-kommandoen ikke producerede noget output.

Årsag: Byggefejl eller forkert konfigureret byggekommando.

Løsning:

  1. Kør build-kommandoen manuelt:

    npm run build

  2. Ret eventuelle rapporterede fejl.

  3. Tjek at outputmappen indeholder filer.

Tom statisk mappe

Symptom: Statisk udrulning fejler med fejlen "empty folder".

Årsag: Den konfigurerede folder sti er forkert.

Løsning:

Bekræfte, at stien folder i rayfin.yml matcher dit build-output:

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

Databaseproblemer

Databaseskema apply fejler

Symptom: Løber npx rayfin up db apply eller npx rayfin up db apply --force fejler.

Årsag: Skemaet i den eksterne database og skemaet defineret i app-koden er ude af sync. App-koden er sandhedskilden for en Fabric-app.

Ændr ikke det fjernbaserede databaseskema via Fabric-portalen, SQL Server Management Studio (SSMS), SQL Server-udvidelsen til Visual Studio Code eller andre SQL-værktøjer. Følgende ændringer i kolonner i en dataenhed understøttes ikke:

  • Omdøbning af en klumme.
  • Ændring af en kolonnes datatype.
  • Fjerner en søjle.

Tilføjelse af en kolonne understøttes. Fjernelse eller ændring af en eksisterende kolonne kan ødelægge appen og dens udrulning til Fabric.

Løsning:

  1. Tilbagefør alle manuelle ændringer i det fjerntliggende databaseskema, så det matcher skemaet i app-koden.

  2. Hvis en kodningsagent har foretaget en ikke-understøttet skemaændring i app-koden, skal du instruere agenten i at tilbagerulle den ændring.

  3. Kør schema apply-kommandoen igen:

    npx rayfin up db apply

    For en kolonneomdøbning --force kan skemaopdateringen fuldføres:

    npx rayfin up db apply --force

    Advarsel!

    --force Brug kan forårsage permanent datatab. Gennemgå de foreslåede operationer og bekræft, at du accepterer risikoen for datatab, før du går videre.

Forbindelse nægtet

Symptom: Dataoperationer fejler med forbindelsesfejl.

Årsag: Databasecontaineren kører ikke, eller sundhedstjek fejlede.

Løsning:

  1. Gennemgå containerlogfiler:

    docker compose logs -f

  2. Genstart tjenesterne.

Datatab efter genstart

Symptom: Data forsvinder efter at have stoppet og startet tjenester.

Årsag: Bind blev slettet med --purge.

Løsning:

Brug --down i stedet for --purge at bevare data.

Kendte begrænsninger

For aktuelle begrænsninger og anbefalede løsninger, se:

  • count() er ikke tilgængelig på den flydende GraphQL-klient—brug results.length.
  • Mange-til-mange-relationer understøttes ikke – brug en eksplicit join-entitet.
  • Sessionsobjekter er uigennemsigtige—tjek isAuthenticated eller user egenskaber.
  • Efter at have aktiveret eller deaktiveret auth, rayfin.ymlgenstart backend.

Få hjælp

Hvis problemet fortsætter:

  1. Gennemgå dokumentationen Fabric Apps.
  2. Tjek GitHub-arkivet for kendte problemer.
  3. Indsend en fejlrapport med detaljerede logfiler og reproduktionstrin.

Relateret indhold

  • Last updated on