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

Statisk udrulning har intet fjernendepunkt

Symptom: Kørende npx rayfin up staticapp deploy rapporterer, at der ikke er konfigureret noget fjernendepunkt.

Årsag: Statisk-only udrulning opdaterer en eksisterende udrulning. Den kan ikke provisionere den oprindelige fjernapplikation.

Løsning:

Kør en fuld udrulning én gang:

npx rayfin up

Når provisionen er fuldført, bruges npx rayfin up staticapp deploy til efterfølgende statisk-only opdateringer.

Godkendelsesproblemer

Indsamling af autentificeringstoken fejler

Symptom:npx rayfin login eller en anden autentificeret CLI-kommandorapport Failed to acquire authentication token eller en fejl i legitimationslagring.

Årsag: CLI'en er ikke logget ind, eller miljøet tilbyder ikke operativsystem-understøttet legitimationslagring.

Løsning:

Log ind igen:

npx rayfin login

For et begrænset lokalt udviklingsmiljø uden legitimationslagring kan du aktivere krypterings-fallback:

npx rayfin login --encryption-fallback-enabled

Advarsel!

Krypterings-fallback gemmer token-cachen i klartekst. Brug det kun i et pålideligt udviklingsmiljø. Brug det ikke i produktion eller delte miljøer.

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

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>

Fabric-autentificering går ud på tidsudløb

Symptom: Fabric-autentificering fejler efter fem minutter.

Årsag: Fabric-portalen returnerede ikke handoff-koden, før flowet udløb.

Løsning:

Bekræft at det returnOrigin matcher din apps oprindelse, luk popup'en, og start login-flowet igen.

Fabric SSO rapporterer en oprindelsesmismatch

Symptom: Fabric SSO-handoff'en afviser svaret, fordi oprindelsen ikke matcher.

ÅrsagreturnOrigin: , allowedRedirectUris, eller fabricPortalUrl matcher ikke det miljø, hvor appen og Fabric-portalen kører.

Løsning:

Sæt returnOrigin til din apps bare oprindelse.
Bekræft, at oprindelsen optræder i services.auth.allowedRedirectUris.
Brug Fabric-portalens URL for det korrekte produktions-, forhåndsvisnings- eller udviklingsmiljø.
Løb npx rayfin up efter skiftet rayfin.yml.

For mere information, se Konfigurer autentificeringsomdirigerings-URI'er.

`initEmbeddedAuth()` Tilbagevenden `null`

Symptom: Indlejret autentificering opretter ikke en session.

Årsag: SDK'en registrerede ikke, at appen kører inde i Fabric.

Løsning:

Inkluder ?fabricEmbedded=true URL'en i appen, eller sæt fabricEmbedded: true i FabricAuthOptions.

Fabric-autentificering rapporterer en tilstandsmismatch

Symptom: Login-in fejler, fordi svartilstanden ikke matcher anmodningstilstanden.

Årsag: Svaret tilhører et udløbet flow eller et tidligere login-forsøg.

Løsning:

Luk Fabric-popupen og genstart login-flowet. Genbrug ikke callback-URL'er eller tilstandsværdier fra et tidligere forsøg.

Datamodelproblemer

Data API returnerer en intern serverfejl efter udrulning

Symptom:npx rayfin up eller npx rayfin up db apply lykkes, men GraphQL- eller REST-data-API'en returnerer en intern serverfejl.

Årsag: På Microsoft SQL Server genererer et @text() felt uden max en NVARCHAR(MAX) kolonne, som kan forhindre generering af GraphQL-skemaet.

Løsning:

Tilføj en eksplicit maksimal længde til hvert berørt tekstfelt:

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

Gennemgå og anvend derefter skemaændringen:

npx rayfin up db apply --force

Advarsel!

Gennemgå alle rapporterede operationer, før du bruger --force. Muligheden kan forårsage permanent datatab.

Dataservice kræver en dialekt

Symptom: Udrulningen fejler med et HTTP 400-svar og rapporterer Dialect is required when Data module is enabled.

Årsag:services.data.enabled er true, men rayfin.yml definerer ikke en dialekt.

Løsning:

Konfigurér Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Ny enhed er ikke tilgængelig efter udrulning

Symptom: Implementeringen lykkes, men forespørgsler mod en ny eller ændret enhed fejler eller opfører sig, som om enheden ikke eksisterer.

Årsag: Databaseskemaet kan stadig være i brug, eller også kan frontenden bruge forældede genererede typer eller cache-konfiguration.

Løsning:

Tjek udrulningen:
```
npx rayfin up status
```
Vent til udsendelsen er sund.
Opdater eller genopbyg frontend.
Hvis entiteten stadig fejler, anvend skemaet eksplicit:
```
npx rayfin up db apply
```

For hele arbejdsgangen, se Anvendelse og verificér skemaændringer.

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:

Sørg for, at relationsdekoratorerne er til stede:
```
@one(() => Notebook) notebook?: Notebook;
```
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:

Verificér, at policen bruger korrekte kravnavne (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
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:

Stop backend.
Slet .temp/ mappen i rayfin/:
```
rm -rf rayfin/.temp/
```
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:

Tjek Node.js og npm er installeret:
```
node --version
npm --version
```
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.

Problemer med hemmelig administration

Hemmelig kommando giver ikke besked

Symptom:npx rayfin secret set <NAME> forlader uden at spørge om en værdi.

Årsag: Standardinput er ikke en interaktiv terminal, eller miljøvariablen CI er sat til true. Kommandoen bruger en maskeret interaktiv prompt.

Løsning:

Brug et af følgende understøttede alternativer til oprettelse af ikke-interaktive hemmeligheder:

Sæt én hemmelighed ved at pippe dens værdi til kommandoen:

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

Sæt flere hemmeligheder fra en miljøfil:

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

Hold hemmelige værdier ude af din shell-historik og forpligt secret.txt dig ikke til .\secrets.env eller til versionskontrol.

Hemmelig kommando returnerer tilladelse nægtet

Symptom:npx rayfin secret set eller npx rayfin secret list returnerer en tilladelsesfejl.

Årsag: Appen er ikke deployed, eller den indloggede konto har ikke adgang til det målrettede Fabric-arbejdsområde.

Løsning:

Kør npx rayfin up for at provisionere appen.
Kør npx rayfin login og vælg en konto med adgang til arbejdsområdet.
Prøv den hemmelige kommando igen.

For mere information, se Administrer funktionshemmeligheder.

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:

Kør build-kommandoen manuelt:
```
npm run build
```
Ret eventuelle rapporterede fejl.
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:

Tilbagefør alle manuelle ændringer i det fjerntliggende databaseskema, så det matcher skemaet i app-koden.
Hvis en kodningsagent har foretaget en ikke-understøttet skemaændring i app-koden, skal du instruere agenten i at tilbagerulle den ændring.
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:

Gennemgå containerlogfiler:
```
docker compose logs -f
```
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:

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

Feedback

Var denne side nyttig?

Sidst opdateret den 2026-09-29

Fejlfinding af Fabric-apps

Udrulningsproblemer

Udrulning fejler med 401- eller 403-fejl

Statisk udrulning overstiger størrelsesgrænsen

Statisk udrulning har intet fjernendepunkt

Godkendelsesproblemer

Indsamling af autentificeringstoken fejler

Sessionen består ikke efter login.

Fabric SSO popup blokeret

Fabric-autentificering går ud på tidsudløb

Fabric SSO rapporterer en oprindelsesmismatch

initEmbeddedAuth() Tilbagevenden null

Fabric-autentificering rapporterer en tilstandsmismatch

Datamodelproblemer

Data API returnerer en intern serverfejl efter udrulning

Dataservice kræver en dialekt

Ny enhed er ikke tilgængelig efter udrulning

Relationer, der ikke vises i API'et

Autorisationspolitik virker ikke

Forældede API-svar

CLI-problemer

Kommando ikke fundet

CLI-versionsmismatch

CLI global og lokal versionsmismatch

Problemer med hemmelig administration

Hemmelig kommando giver ikke besked

Hemmelig kommando returnerer tilladelse nægtet

Bygge- og emballageproblemer

Byg-kommandoen fejler

Tom statisk mappe

Databaseproblemer

Databaseskema apply fejler

Forbindelse nægtet

Datatab efter genstart

Kendte begrænsninger

Få hjælp

Relateret indhold

Feedback

Yderligere ressourcer

`initEmbeddedAuth()` Tilbagevenden `null`