Felsöka Fabric-appar

Diagnostisera vanliga problem när du utvecklar eller distribuerar ett Fabric Apps-projekt. Den här artikeln beskriver problem med inloggning, lokala tjänster, schemaändringar, statisk värd och CLI.

Distributionsproblem

Driftsättning misslyckas med felkod 401 eller 403

Symptom: Att köra npx rayfin up ger ett autentiseringsfel.

Orsaka: Autentiseringssessionen har upphört att gälla eller så är du inte inloggad.

Solution:

Autentisera om och försök distribuera igen:

npx rayfin login
npx rayfin up

Statisk distribution överskrider storleksgränsen

Symptom: Distribution av statiskt innehåll misslyckas med ett storleksgränsfel.

Orsaka: Det komprimerade arkivet överstiger 100 MB.

Solution:

Minska storleken på byggutdata genom att:

• Exkludera källkartor från produktionsbyggen
• Optimera eller ta bort stora bilder och videor
• Flytta binära filer till lagring i stället för att bunta ihop dem
• Om du verifierar paketeringskonfigurationen undantas utvecklingsartefakter

Statisk driftsättning har ingen fjärrslutpunkt

Symptom: När du kör npx rayfin up staticapp deploy visas att ingen fjärrslutpunkt är konfigurerad.

Orsak: Distribution enbart av statiskt innehåll uppdaterar en befintlig distribution. Den kan inte provisionera den initiala fjärrappen.

Solution:

Kör en fullständig distribution en gång:

npx rayfin up

Efter att provisionering är klar, använd npx rayfin up staticapp deploy för efterföljande statisk-endast uppdateringar.

Autentiseringsproblem

Insamling av autentiseringstoken misslyckas

Symptom:npx rayfin login eller rapporterar ett annat autentiserat CLI-kommando Failed to acquire authentication token eller ett fel i lagring av autentiseringsuppgifter.

Orsak: CLI:n är inte inloggad, eller så tillhandahåller miljön inte operativsystemsbackad legitimationslagring.

Solution:

Logga in igen:

npx rayfin login

För en begränsad lokal utvecklingsmiljö utan legitimationslagring kan du aktivera krypteringsfallbacken:

npx rayfin login --encryption-fallback-enabled

Varning

Krypteringsfallback lagrar tokencachen i klartext. Använd det endast i en betrodd utvecklingsmiljö. Använd det inte i produktion eller delade miljöer.

Sessionen bevaras inte efter inloggning

Symptom: Användarna loggas ut omedelbart efter autentiseringen.

Orsaka: Klienten har inte konfigurerats med rätt bas-URL eller publiceringsbar nyckel.

Solution:

Kontrollera att konfigurationen RayfinClient matchar serverdelen:

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

Popupfönstret för Fabric-enkelinloggning har blockerats

Symptom: Browser blockerar Fabric portalfönstret under inloggningen.

Orsak:ensureSignedInWithFabric() anropades inte från en hanterare för användargester.

Solution:

Anropa funktionen från en synkron händelsehanterare:

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

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

Fabric-autentiseringens tidsgräns överskrids

Symptom: Fabric-autentiseringen misslyckas efter fem minuter.

Orsak: Fabric-portalen returnerade inte handoff-koden innan flödet gick ut.

Solution:

Bekräfta att det returnOrigin stämmer överens med appens ursprung, stäng popupen och starta inloggningsflödet igen.

Fabric SSO rapporterar en ursprungsmismatch

Symptom: Fabric SSO-överlämningen avvisar svaret eftersom ursprunget inte matchar.

Orsak:returnOrigin, allowedRedirectUris, eller fabricPortalUrl stämmer inte överens med miljön där appen och Fabric-portalen körs.

Solution:

1. Ange returnOrigin som appens origin.
2. Kontrollera att ursprunget visas i services.auth.allowedRedirectUris.
3. Använd Fabric-portalens URL för rätt produktions-, förhandsgransknings- eller utvecklingsmiljö.
4. Kör npx rayfin up efter att du har ändrat rayfin.yml.

För mer information, se Konfigurera autentiseringsomdirigerings-URI:er.

initEmbeddedAuth() returnerar null

Symptom: Inbäddad autentisering skapar ingen session.

Orsak: SDK:n upptäckte inte att appen körs i Fabric.

Solution:

Inkludera ?fabricEmbedded=true i appens URL, eller sätt fabricEmbedded: true i FabricAuthOptions.

Fabric-autentiseringen rapporterar en tillståndskonflikt

Symptom: Inloggningen misslyckas eftersom svarstillståndet inte stämmer överens med förfrågan.

Orsak: Svaret tillhör ett utgånget flöde eller ett tidigare inloggningsförsök.

Solution:

Stäng Fabric-popupen och starta om inloggningsflödet. Återanvänd inte callback-URL:er eller tillståndsvärden från ett tidigare försök.

Problem med datamodell

Data API returnerar ett internt serverfel efter distribution

Symptom:npx rayfin up eller npx rayfin up db apply lyckas, men GraphQL- eller REST-data-API:et returnerar ett internt serverfel.

Orsak: På Microsoft SQL Server genererar ett @text() fält utan max en NVARCHAR(MAX) kolumn, vilket kan förhindra generering av GraphQL-schemat.

Solution:

Lägg till en explicit maxlängd på varje påverkat textfält:

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

Sedan granska och tillämpa schemaändringen:

npx rayfin up db apply --force

Caution

Gå igenom alla rapporterade operationer innan du använder --force. Alternativet kan orsaka permanent dataförlust.

Datatjänst kräver en dialekt

Symptom: Distributionen misslyckas med ett HTTP 400-svar och rapporterar Dialect is required when Data module is enabled.

Orsak:services.data.enabled är true, men rayfin.yml definierar inte en dialekt.

Solution:

Konfigurera Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Ny enhet är inte tillgänglig efter utrullning

Symptom: Utplaceringen lyckas, men frågor mot en ny eller ändrad entitet misslyckas eller beter sig som om entiteten inte existerar.

Orsak: Databasschemat kan fortfarande gälla, eller så kan frontend använda föråldrade genererade typer eller cachad konfiguration.

Solution:

1. Kontrollera utplaceringen:

   npx rayfin up status
   

2. Vänta tills distributionen fungerar som den ska.

3. Uppdatera eller bygg om frontend.

4. Om entiteten fortfarande misslyckas, tillämpa schemat uttryckligen:

   npx rayfin up db apply
   

För hela arbetsflödet, se Tillämpa och verifiera schemaändringar.

Relationer visas inte i API

Symptom: Relaterade entitetsfält är inte tillgängliga när du frågar.

Orsaka: Navigeringsdekoratören saknas eller så tillämpades inte schemat.

Solution:

1. Kontrollera att relationsdekoratörerna finns:

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

2. Använd schemat igen.

Auktoriseringsprincipen fungerar inte

Symptom: Användare kan komma åt poster som de inte bör se.

Orsaka: Principuttrycket är felaktigt eller så matchar inte anspråksnamnen.

Solution:

1. Kontrollera att policyn använder korrekta namn på anspråk (sub, email, role):

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

2. Logga den avkodade JWT:n för att verifiera att claim-värdena överensstämmer med värdena i koden.

Inaktuella API-svar

Symptom: Klientdelen returnerar inaktuella dataformer efter schemaändringar.

Orsak: Den genererade konfigurationen är cachelagrad.

Solution:

1. Stoppa serverdelen.

2. .temp/ Ta bort katalogen i rayfin/:

   rm -rf rayfin/.temp/
   

3. Starta om tjänster och använd schemat igen.

CLI-problem

Kommandot hittades inte

Symptom: Om du kör npx rayfin returneras "kommandot hittades inte".

Orsaka: CLI är inte installerat eller så finns inte npm i din SÖKVÄG.

Solution:

1. Kontrollera att Node.js och npm är installerade:

   node --version
   npm --version
   

2. Installera om beroenden:

   npm install
   

CLI-versionskonflikt

Symptom: CLI-kommandon misslyckas med oväntade fel efter uppdatering.

Orsak: Cachad CLI-version är föråldrad.

Solution:

Uppdatera och installera om:

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

Versionskonflikt mellan global och lokal version av CLI

Symptom: CLI-kommandon misslyckas och ger oväntade fel i flera projekt.

Orsaka: Global och lokal installation av CLI-versionerna och de matchar inte.

Lösning: Verifiera lokal version npm list @microsoft/rayfin-cli. Detta visar versionen i det aktuella projektets node_modules. Kontrollera den globala versionen npm list -g @microsoft/rayfin-cli. Detta visar den version som är installerad för hela systemet. Använd npm uninstall -g med Rayfin CLI-paketet för att ta bort den globala versionen och använda dina lokala versioner.

Hemliga hanteringsproblem

Hemligt kommando ger ingen uppmaning

Symptom:npx rayfin secret set <NAME> avslutas utan att be om ett värde.

Orsak: Standardindata är inte en interaktiv terminal, eller så är miljövariabeln CI inställd på true. Kommandot använder en maskerad interaktiv prompt.

Solution:

Använd ett av följande stödda alternativ för icke-interaktiv hemlighetsskapande:

• Sätt en hemlighet genom att skicka dess värde till kommandot:

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

• Sätt flera hemligheter från en miljöfil:

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

Håll hemliga värden borta från kommandohistoriken i skalet och checka inte in secret.txt eller .\secrets.env i versionshanteringen.

Hemligt kommando returnerar tillstånd nekat

Symptom:npx rayfin secret set eller npx rayfin secret list returnerar ett behörighetsfel.

Orsak: Appen är inte distribuerad, eller så har det inloggade kontot inte tillgång till mål-Fabric-arbetsområdet.

Solution:

1. Kör npx rayfin up för att provisionera appen.
2. Kör npx rayfin login och välj ett konto med tillgång till arbetsytan.
3. Försök igen med den hemliga ordern.

För mer information, se Hantera funktionshemligheter.

Problem med bygge och paketering

Build-kommandot misslyckas

Symptom: Distributionen av statisk värd misslyckas eftersom byggkommandot inte gav några utdata.

Orsak: Byggfel eller felaktigt konfigurerat byggkommando.

Solution:

1. Kör build-kommandot manuellt:

   npm run build
   

2. Åtgärda eventuella rapporterade fel.

3. Kontrollera att utdatamappen innehåller filer.

Tom statisk mapp

Symptom: Statisk distribution misslyckas med felet "tom mapp".

Orsaka: Den konfigurerade folder sökvägen är felaktig.

Solution:

Kontrollera att folder sökvägen i rayfin.yml matchar dina byggutdata:

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

Databasproblem

Det gick inte att tillämpa databasschemat

Symtom: Att köra npx rayfin up db apply eller npx rayfin up db apply --force misslyckas.

Orsak: Schemat i den fjärranslutna databasen och schemat som definieras i appkoden är ur synk. Appkoden är sanningskällan för en Fabric-app.

Ändra inte det fjärrstyrda databasschemat via Fabric-portalen, SQL Server Management Studio (SSMS), SQL Server-tillägget för Visual Studio Code eller andra SQL-verktyg. Följande ändringar i kolumner i en dataenhet stöds inte:

• Byter namn på en kolumn.
• Att ändra en kolumns datatyp.
• Att ta bort en kolumn.

Att lägga till en kolumn stöds. Att ta bort eller ändra en befintlig kolumn kan förstöra appen och dess distribution till Fabric.

Solution:

1. Återställ alla manuella ändringar i det fjärrstyrda databasschemat så att det matchar schemat i appkoden.

2. Om en kodningsagent gjorde en ostödd schemaändring i appkoden, instruera agenten att återställa den ändringen.

3. Kör schema apply-kommandot igen:

   npx rayfin up db apply
   

   Vid byte av kolumnnamn kan --force göra det möjligt för uppdateringen av schemat att slutföras:

   npx rayfin up db apply --force
   

   Caution

   Användning --force kan orsaka permanent dataförlust. Gå igenom de föreslagna operationerna och bekräfta att du accepterar risken för dataförlust innan du går vidare.

Anslutningen nekades

Symptom: Dataåtgärder misslyckas med anslutningsfel.

Orsaka: Databascontainern körs inte eller så misslyckades hälsokontrollerna.

Solution:

1. Granska containerloggar:

   docker compose logs -f
   

2. Starta om tjänster.

Dataförlust efter omstart

Symptom: Data försvinner efter att tjänster har stoppats och startats.

Orsaka: Volymer togs bort med --purge.

Solution:

Använd --down i stället --purge för att bevara data.

Kända begränsningar

Aktuella begränsningar och rekommenderade lösningar finns i:

• count() är inte tillgängligt på Fluent GraphQL-klienten – använd results.length.
• Många-till-många-relationer stöds inte – använd en explicit kopplingsentitet.
• Sessionsobjekt är ogenomskinliga – kontroll isAuthenticated eller user egenskaper.
• När du har aktiverat eller inaktiverat autentiseringen i rayfin.ymlstartar du om serverdelen.

Få hjälp

Om problemet kvarstår:

1. Läs dokumentationen Fabric Apps.
2. Kontrollera GitHub-lagringsplatsen för kända problem.
3. Skapa en felrapport med detaljerade loggar och reproduktionssteg.

Relaterat innehåll

• CLI-referens
• Tillämpa och verifiera schemaändringar
• Konfigurera autentiseringsomdirigerings-URI:er.
• Hantera funktionens hemliga nycklar.
• Distribuera till Fabric
• Konfigurera autentisering