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

Databaseanvendelse rapporterer destruktive ændringer

Symptom: Kørende npx rayfin up db apply blokke med advarsel om datatab.

Årsag: CLI'en opdagede skemaændringer, der kunne slette data (fjernelse af kolonner, omdøbning af tabeller).

Løsning:

Gennemgå de listede operationer grundigt. Hvis du accepterer datatabet, brug --force:

npx rayfin up db apply --force

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 vs lokal version mismatch

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

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

• CLI-reference
• Udrul til Fabric
• Konfigurer godkendelse