Riešenie problémov s Fabric Apps

Diagnostikujte bežné problémy pri vývoji alebo nasadení projektu Fabric Apps. Tento článok sa zaoberá otázkami prihlasovania, lokálnych služieb, zmien schémy, statického hostovania a CLI.

Problémy s nasadením

Nasadenie zlyháva s chybou 401 alebo 403

Príznak: Spustenie npx rayfin up vráti chybu autentifikácie.

Príčina: Vaša autentifikačná relácia vypršala alebo nie ste prihlásený.

Riešenie:

Znovu overte a vyskúšajte nasadenie:

npx rayfin login
npx rayfin up

Statické nasadenie prekračuje limit veľkosti

Príznak: Nasadenie statického obsahu zlyháva s chybou limitu veľkosti.

Príčina: Komprimovaný archív presahuje 100 MB.

Riešenie:

Zmenšite veľkosť výstupu zostavy takto:

Vylúčenie zdrojových máp z produkčných verzií
Optimalizácia alebo odstránenie veľkých obrázkov a videí
Presúvanie binárnych súborov do úložiska namiesto ich balenia
Overovanie konfigurácie bundlera vylučuje vývojové artefakty

Statické nasadenie nemá vzdialený koncový bod

Príznak: Spúšťam npx rayfin up staticapp deploy hlásenia, že žiadny vzdialený endpoint nie je nakonfigurovaný.

Príčina: Len statické nasadenie aktualizuje existujúce nasadenie. Nedokáže nastaviť pôvodnú vzdialenú aplikáciu.

Riešenie:

Uskutočniť celé nasadenie raz:

npx rayfin up

Po dokončení nastavenia použite npx rayfin up staticapp deploy na ďalšie statické aktualizácie.

Problémy s autentifikáciou

Získanie autentifikačného tokenu zlyháva

Príznak:npx rayfin login alebo iné autentifikované hlásenia Failed to acquire authentication token príkazov CLI alebo chyba pri ukladaní prihlasovacích údajov.

Príčina: CLI nie je prihlásený alebo prostredie neposkytuje úložisko prihlasovacích údajov podporované operačným systémom.

Riešenie:

Prihláste sa znova:

npx rayfin login

Pre obmedzené lokálne vývojové prostredie bez úložiska prihlasovacích údajov môžete povoliť šifrovaciu záložnú funkciu:

npx rayfin login --encryption-fallback-enabled

Upozornenie

Šifrovací záložný systém ukladá cache tokenov v čistom texte. Používajte ho iba v dôveryhodnom vývojovom prostredí. Nepoužívajte ho v produkcii ani v zdieľaných prostrediach.

Príznak: Používatelia sú okamžite po autentifikácii odhlásení.

Príčina: Klient nie je nakonfigurovaný so správnou základnou URL alebo publikovateľným kľúčom.

Riešenie:

Overte, či konfigurácia RayfinClient zodpovedá vášmu backendu:

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

Symptom: Prehliadač blokuje okno Fabric portálu počas prihlásenia.

Príčina:ensureSignedInWithFabric() nebolo volané od správcu používateľských gest.

Riešenie:

Funkciu voláme zo synchronného obslužovateľa udalostí:

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

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

Fabric autentifikácia vypršala

Príznak: Fabric autentifikácia zlyhá po piatich minútach.

Príčina: Fabric portál nevrátil kód na odovzdanie pred vypršaním flow.

Riešenie:

Skontrolujte, či to returnOrigin zodpovedá pôvodu vašej aplikácie, zatvorte vyskakovacie okno a začnite proces prihlasovania znova.

Fabric SSO hlási nesúlad pôvodu

Príznak: Fabric SSO handoff odmieta odpoveď, pretože jej pôvod sa nezhoduje.

Príčina:returnOrigin, allowedRedirectUris, alebo fabricPortalUrl nezodpovedá prostrediu, kde bežia aplikácia a Fabric portál.

Riešenie:

Nastavte returnOrigin holý pôvod vašej aplikácie.
Potvrďte, že pôvod sa vyskytuje v services.auth.allowedRedirectUris.
Použite URL portálu Fabric pre správne produkčné, preview alebo vývojové prostredie.
Bež npx rayfin up po zmene rayfin.yml.

Pre viac informácií pozri Configure authentication redirect URIs.

`initEmbeddedAuth()` Návraty `null`

Príznak: Vložená autentifikácia nevytvára reláciu.

Príčina: SDK nezaznamenalo, že aplikácia beží vo Fabric.

Riešenie:

Zahrňte ?fabricEmbedded=true do URL aplikácie alebo nastavte fabricEmbedded: true v FabricAuthOptions.

Fabric autentifikácia hlási nesúlad stavov

Príznak: Prihlásenie zlyháva, pretože stav odpovede nezodpovedá stavu požiadavky.

Príčina: Odpoveď patrí vypršanému toku alebo predchádzajúcemu pokusu o prihlásenie.

Riešenie:

Zatvorte vyskakovacie okno Fabric a reštartujte proces prihlasovania. Nepoužívajte spätné URL alebo hodnoty stavov z predchádzajúceho pokusu.

Problémy s dátovým modelom

Data API po nasadení vracia internú chybu servera

Príznak:npx rayfin up alebo npx rayfin up db apply uspeje, ale GraphQL alebo REST dátové API vrátia internú chybu servera.

Príčina: Na Microsoft SQL Server pole @text() bez max generuje NVARCHAR(MAX) stĺpec, čo môže zabrániť generovaniu schémy GraphQL.

Riešenie:

Pridajte explicitnú maximálnu dĺžku ku každému ovplyvnenému textovému poliu:

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

Potom prejdite a aplikujte zmenu schémy:

npx rayfin up db apply --force

Výstraha

Pred použitím --forceskontrolujte všetky nahlásené operácie. Táto možnosť môže spôsobiť trvalú stratu dát.

Dátová služba vyžaduje dialekt

Príznak: Nasadenie zlyháva s odpoveďou HTTP 400 a hlási Dialect is required when Data module is enabled.

Príčina:services.data.enabled je , trueale rayfin.yml nedefinuje dialekt.

Riešenie:

Configure Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Nová entita nie je dostupná po nasadení

Príznak: Nasadenie je úspešné, ale dotazy na novú alebo zmenenú entitu zlyhajú alebo sa správajú, akoby entita neexistovala.

Príčina: Databázová schéma môže byť stále v platnosti, alebo frontend používa zastarané generované typy či uloženú konfiguráciu.

Riešenie:

Skontrolujte nasadenie:
```
npx rayfin up status
```
Počkaj, kým bude nasadenie zdravé.
Obnovte alebo znovu vybudujte frontend.
Ak entita stále zlyháva, použite schému explicitne:
```
npx rayfin up db apply
```

Pre kompletný pracovný postup pozri Použiť a overiť zmeny schémy.

Vzťahy, ktoré sa nezobrazujú v API

Príznak: Súvisiace pole entít nie sú pri dotazovaní dostupné.

Príčina: Navigačný dekorátor chýba alebo schéma nebola aplikovaná.

Riešenie:

Overte si, či sú prítomní dekoratéri na vzťahy:
```
@one(() => Notebook) notebook?: Notebook;
```
Znovu aplikuj schému.

Politika autorizácie nefunguje

Príznak: Používatelia môžu pristupovať k záznamom, ktoré by nemali vidieť.

Príčina: Výraz poistky je nesprávny alebo názvy nárokov nesedia.

Riešenie:

Overte, či poistka používa správne názvy nárokov (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Zaznamenajte dekódovaný JWT, aby ste overili, či hodnoty nárokov zodpovedajú vášmu kódu.

Zastarané odpovede API

Príznak: Frontend vracia zastarané dátové tvary po zmene schémy.

Príčina: Generovaná konfigurácia je uložená do vyrovnávacej pamäte.

Riešenie:

Zastavte backend.
Vymažte .temp/ adresár v rayfin/:
```
rm -rf rayfin/.temp/
```
Reštartujte služby a znovu aplikujte schému.

Problémy s CLI

Príkaz nenájdený

Príznak: Spustenie npx rayfin vráti "príkaz nenájdený."

Príčina: CLI nie je nainštalované alebo npm nie je vo vašej PATH.

Riešenie:

Overte, či sú nainštalované Node.js a npm:
```
node --version
npm --version
```
Závislosti na opätovnej inštalácii:
```
npm install
```

Nesúlad verzií CLI

Príznak: Príkazy CLI zlyhávajú s nečakanými chybami po aktualizácii.

Príčina: Cacheovaná verzia CLI je zastaraná.

Riešenie:

Aktualizácia a opätovná inštalácia:

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

Nesúlad globálnych a lokálnych verzií CLI

Príznak: CLI príkazy zlyhávajú s nečakanými chybami naprieč projektmi.

Príčina: Globálna a lokálna inštalácia CLI verzií a nezhodujú sa.

Riešenie: Overiť lokálnu verziu npm list @microsoft/rayfin-cli. Toto ukazuje verziu v node_modules vášho aktuálneho projektu. Skontrolujte globálnu verziu npm list -g @microsoft/rayfin-cli. Zobrazuje verziu nainštalovanú v celom systéme. Použite npm uninstall -g s balíkom Rayfin CLI na odstránenie globálnej verzie a použite lokálne verzie.

Problémy s riadením tajného tajomstva

Tajný príkaz nevyvoláva výzvu

Príznak:npx rayfin secret set <NAME> Opúšťa bez vyzvania hodnoty.

Príčina: Štandardný vstup nie je interaktívny terminál, alebo je premenná CI prostredia nastavená na true. Príkaz používa maskovanú interaktívnu výzvu.

Riešenie:

Použite jednu z nasledujúcich podporovaných alternatív pre neinteraktívne vytváranie tajomstiev:

Nastavte jedno tajomstvo tak, že jeho hodnotu pošlete príkazu:

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

Nastavte viacero tajomstiev zo súboru prostredia:
```
npx rayfin secret set --env-file .\secrets.env
```

Držte tajné hodnoty mimo svojej histórie a nezaväzujte sa secret.txt.\secrets.env ani neprepájajte do správy zdrojových kódov.

Tajné velenie vracia povolenie zamietnuté

Príznak:npx rayfin secret set alebo npx rayfin secret list vráti chybu povolenia.

Príčina: Aplikácia nie je nasadená alebo prihlásený účet nemá prístup k cieľovému pracovnému priestoru Fabric.

Riešenie:

Bež a nastav npx rayfin up aplikáciu.
Spusti npx rayfin login a vyber účet s prístupom do pracovného priestoru.
Skús znova tajný príkaz.

Pre viac informácií pozri Spravovať tajomstvá funkcií.

Problémy so stavbou a balením

Build príkaz zlyháva

Príznak: Nasadenie statického hostovania zlyháva, pretože príkaz na zostavenie nevytvoril žiadny výstup.

Príčina: Chyby pri zostavovaní alebo nesprávne nastavené build príkazy.

Riešenie:

Spusti build príkaz manuálne:
```
npm run build
```
Opravte všetky nahlásené chyby.
Overte, či výstupný priečinok obsahuje súbory.

Prázdny statický priečinok

Príznak: Statické nasadenie zlyháva s chybou "empty folder".

Príčina: Nastavená folder cesta je nesprávna.

Riešenie:

Overte, či cesta folder dovnútra rayfin.yml zodpovedá výstupu vašej zostavy:

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

Problémy s databázami

Aplikácia schémy databázy zlyháva

Príznak: Beží npx rayfin up db apply alebo npx rayfin up db apply --force zlyhá.

Príčina: Schéma v vzdialenej databáze a schéma definovaná v kóde aplikácie nie sú synchronizované. Kód aplikácie je zdrojom pravdy pre Fabric aplikáciu.

Neupravujte vzdialenú databázovú schému cez portál Fabric, SQL Server Management Studio (SSMS), rozšírenie SQL Server pre Visual Studio Code alebo iné SQL nástroje. Nasledujúce zmeny stĺpcov v dátovej entite nie sú podporované:

Premenovanie stĺpca.
Zmena dátového typu stĺpca.
Odstránenie stĺpca.

Pridanie stĺpca je podporované. Odstránenie alebo zmena existujúceho stĺpca môže aplikáciu a jej nasadenie do Fabric pokaziť.

Riešenie:

Vráťte akékoľvek manuálne zmeny v vzdialenej databázovej schéme tak, aby zodpovedala schéme v aplikačnom kóde.
Ak kód agent urobil nepodporovanú zmenu schémy v kóde aplikácie, inštruujte agenta, aby túto zmenu vrátil späť.
Spusti príkaz schema apply znova:
```
npx rayfin up db apply
```
Pri premenovaní --force stĺpcov môže byť aktualizácia schémy dokončená:
```
npx rayfin up db apply --force
```
Výstraha

Používanie --force môže spôsobiť trvalú stratu dát. Pred pokračovaním si prejdite navrhované operácie a potvrďte sa, že akceptujete riziko straty dát.

Spojenie zamietnuté

Príznak: Dátové operácie zlyhávajú s chybami spojenia.

Príčina: Databázový kontajner nebeží alebo kontrola zdravia zlyhala.

Riešenie:

Skontrolujte záznamy kontajnerov:
```
docker compose logs -f
```
Reštartujte služby.

Strata dát po reštarte

Príznak: Dáta zmiznú po zastavení a spustení služieb.

Príčina: Zväzky boli vymazané s --purge.

Riešenie:

Používajte --down namiesto --purge na uchovávanie dát.

Známe obmedzenia

Pre aktuálne obmedzenia a odporúčané obchádzky pozri:

count() nie je dostupný na plynulom GraphQL klientovi—použi results.length.
Vzťahy mnoho-na-mnohých nie sú podporované – použite explicitnú entitu spojenia.
Objekty relácie sú nepriehľadné – zaškrtnuté isAuthenticated alebo user vlastnosti.
Po zapnutí alebo vypnutí autentifikácie v , rayfin.ymlreštartujte backend.

Získať pomoc

Ak problém pretrváva:

Pozrite si dokumentáciu Fabric Apps.
Skontrolujte repozitár GitHub na známe problémy.
Podajte hlásenie chyby s podrobnými logmi a krokmi reprodukcie.

Pripomienky

Bola táto stránka užitočná?

Naposledy aktualizované: 2026-09-29

Riešenie problémov s Fabric Apps

Problémy s nasadením

Nasadenie zlyháva s chybou 401 alebo 403

Statické nasadenie prekračuje limit veľkosti

Statické nasadenie nemá vzdialený koncový bod

Problémy s autentifikáciou

Získanie autentifikačného tokenu zlyháva

Relácia nepretrváva po prihlásení

Fabric SSO vyskakovacie okno zablokované

Fabric autentifikácia vypršala

Fabric SSO hlási nesúlad pôvodu

initEmbeddedAuth() Návraty null

Fabric autentifikácia hlási nesúlad stavov

Problémy s dátovým modelom

Data API po nasadení vracia internú chybu servera

Dátová služba vyžaduje dialekt

Nová entita nie je dostupná po nasadení

Vzťahy, ktoré sa nezobrazujú v API

Politika autorizácie nefunguje

Zastarané odpovede API

Problémy s CLI

Príkaz nenájdený

Nesúlad verzií CLI

Nesúlad globálnych a lokálnych verzií CLI

Problémy s riadením tajného tajomstva

Tajný príkaz nevyvoláva výzvu

Tajné velenie vracia povolenie zamietnuté

Problémy so stavbou a balením

Build príkaz zlyháva

Prázdny statický priečinok

Problémy s databázami

Aplikácia schémy databázy zlyháva

Spojenie zamietnuté

Strata dát po reštarte

Známe obmedzenia

Získať pomoc

Súvisiaci obsah

Pripomienky

Ďalšie zdroje informácií

`initEmbeddedAuth()` Návraty `null`