Řešení potíží s aplikacemi Fabric

Diagnostika běžných problémů při vývoji nebo nasazení projektu Fabric Apps Tento článek se zabývá problémy s přihlášením, místními službami, změnami schématu, statickým hostováním a rozhraním příkazového řádku.

Problémy při nasazení

Nasazení selže s chybou 401 nebo 403

Příznak: Spuštění npx rayfin up vrátí chybu při ověřování.

Příčina: Platnost vaší ověřovací relace vypršela nebo nejste přihlášeni.

Solution:

Znovu se ověřte a zkuste nasazení zopakovat:

npx rayfin login
npx rayfin up

Statické nasazení překračuje limit velikosti

Příznakem: Nasazení statického obsahu selže s chybou limitu velikosti.

Příčina: Komprimovaný archiv přesahuje 100 MB.

Solution:

Snižte velikost výstupu sestavení takto:

Vyloučení zdrojových map z produkčních buildů
Optimalizace nebo odebrání velkých obrázků a videí
Přesouvání binárních souborů do úložiště místo jejich sdružování
Ověření konfigurace bundleru vylučuje vývojové artefakty.

Statické nasazení nemá vzdálený koncový bod

Příznak: Při spuštění npx rayfin up staticapp deploy se zobrazí hlášení, že není nakonfigurován žádný vzdálený koncový bod.

Příčina: Pouze statické nasazení aktualizuje existující nasazení. Nemůže nastavit původní vzdálenou aplikaci.

Solution:

Proveďte plné nasazení jednou:

npx rayfin up

Po dokončení nastavení použijte npx rayfin up staticapp deploy pro další statické aktualizace.

Problémy s ověřováním

Získání autentizačního tokenu selže

Příznak:npx rayfin login nebo jiný autentizovaný příkaz CLI hlásí Failed to acquire authentication token nebo chybu při ukládání přihlašovacích údajů.

Příčina: CLI není přihlášen, nebo prostředí neposkytuje úložiště přihlašovacích údajů podporované operačním systémem.

Solution:

Přihlaste se znovu:

npx rayfin login

Pro omezené lokální vývojové prostředí bez úložiště přihlašovacích údajů můžete povolit šifrovací záložní řešení:

npx rayfin login --encryption-fallback-enabled

Warning

Záložní mechanismus šifrování ukládá mezipaměť tokenů v prostém textu. Používejte ho pouze v důvěryhodném vývojovém prostředí. Nepoužívej ho v produkci ani sdílených prostředích.

Příznakem: Uživatelé se odhlásí okamžitě po ověření.

Příčina: Klient není správně nakonfigurován se správnou základní adresou URL nebo veřejným klíčem.

Solution:

Ověřte, že konfigurace odpovídá vašemu back-endu RayfinClient :

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

Symptom: Browser během přihlašování blokuje okno portálu Fabric.

Příčina:ensureSignedInWithFabric() nebyla volána z obslužné rutiny gesta uživatele.

Solution:

Zavolejte funkci ze synchronní obslužné rutiny události:

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

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

Fabric autentizace vypršela

Příznak: Ověřování Fabric selže po pěti minutách.

Příčina: Portál Fabric nevrátil předávací kód dříve, než platnost toku vypršela.

Solution:

Ověřte, že to returnOrigin odpovídá původu vaší aplikace, zavřete vyskakovací okno a znovu spusťte přihlašovací proces.

Fabric SSO hlásí nesoulad původu

Příznak: Předání Fabric SSO odmítne odpověď, protože její původ neodpovídá.

Příčina:returnOrigin, allowedRedirectUris, nebo fabricPortalUrl neodpovídá prostředí, kde aplikace a Fabric portál běží.

Solution:

Nastavte returnOrigin na holý původ vaší aplikace.
Potvrďte, že původ se vyskytuje v services.auth.allowedRedirectUris.
Použijte URL portálu Fabric pro správné produkční, preview nebo vývojové prostředí.
Spusťte npx rayfin up po změně rayfin.yml.

Pro více informací viz Konfigurovat autentizační přesměrovací URI.

`initEmbeddedAuth()` vrací `null`

Příznak: Vložená autentizace nevytváří relaci.

Příčina: SDK nezaznamenalo, že aplikace běží uvnitř Fabric.

Solution:

Přidejte ?fabricEmbedded=true do adresy URL aplikace nebo nastavte fabricEmbedded: true v FabricAuthOptions.

Fabric autentizace hlásí nesoulad stavů

Příznak: Přihlášení selže, protože stav odpovědi neodpovídá stavu požadavku.

Příčina: Odpověď patří vypršenému toku nebo předchozímu pokusu o přihlášení.

Solution:

Zavřete vyskakovací okno Fabric a restartujte proces přihlašování. Nepoužívejte zpětné URL nebo hodnoty stavů z předchozích pokusů.

Problémy s datovým modelem

Data API po nasazení vrací interní chybu serveru

Příznak:npx rayfin up nebo npx rayfin up db apply uspěje, ale GraphQL nebo REST datové API vrátí interní chybu serveru.

Příčina: Na Microsoft SQL Server @text() pole bez max vygeneruje NVARCHAR(MAX) sloupec, což může zabránit generování schématu GraphQL.

Solution:

Přidejte explicitní maximální délku ke každému ovlivněnému textovému poli:

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

Poté si změnu schématu zopakujte a aplikujte:

npx rayfin up db apply --force

Caution

Před použitím --forcesi zkontrolujte všechny nahlášené operace. Tato možnost může způsobit trvalou ztrátu dat.

Datová služba vyžaduje dialekt

Příznak: Nasazení selže s odpovědí HTTP 400 a hlásí Dialect is required when Data module is enabled.

Příčina:services.data.enabled je true, ale rayfin.yml nedefinuje dialekt.

Solution:

Konfigurujte Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Nová entita není po nasazení dostupná

Příznak: Nasazení uspěje, ale dotazy na novou nebo změněnou entitu selžou nebo se chovají jako by entita neexistovala.

Příčina: Schéma databáze může být stále v platnosti, nebo frontend používá zastaralé generované typy či cacheované konfigurace.

Solution:

Zkontrolujte nasazení:
```
npx rayfin up status
```
Počkejte, až bude nasazení v pořádku.
Obnovte nebo znovu postavte frontend.
Pokud entita stále selže, použijte schéma explicitně:
```
npx rayfin up db apply
```

Pro kompletní pracovní postup viz Aplikovat a ověřit změny schématu.

Relace se nezobrazují v rozhraní API

Příznakem: Související pole entit nejsou při dotazování k dispozici.

Příčina: Chybí dekorátor navigace nebo schéma nebylo použito.

Solution:

Ověřte, že jsou k dispozici dekorátory relací:
```
@one(() => Notebook) notebook?: Notebook;
```
Znovu použít schéma.

Zásady autorizace nefungují

Příznakem: Uživatelé mají přístup k záznamům, které by neměli vidět.

Příčina: Výraz zásady je nesprávný nebo názvy atributů neodpovídají.

Solution:

Ověřte, že zásada používá správné názvy deklarací identity (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Zakažte dekódovaný JWT a ověřte, že hodnoty deklarací identity odpovídají vašemu kódu.

Zastaralé odpovědi rozhraní API

Příznak: Front-end po změně schématu vrací zastaralé datové struktury.

Příčina: Vygenerovaná konfigurace je uložena v mezipaměti.

Solution:

Zastavte backend.
Odstraňte adresář .temp/ v rayfin/:
```
rm -rf rayfin/.temp/
```
Restartujte služby a znovu použijte schéma.

Problémy s rozhraním příkazového řádku

Příkaz nebyl nalezen.

Příznak: Při spuštění příkazu npx rayfin se zobrazí zpráva „příkaz nebyl nalezen.“

Příčina: Nástroj příkazového řádku není nainstalovaný nebo npm není ve vaší proměnné PATH.

Solution:

Ověřte, že jsou nainstalované Node.js a npm:
```
node --version
npm --version
```
Přeinstalovat závislosti:
```
npm install
```

Neshoda verzí rozhraní příkazového řádku

Příznak: Po aktualizaci příkazy CLI selhávají s neočekávanými chybami.

Příčina: Verze CLI uložená v mezipaměti je zastaralá.

Solution:

Aktualizace a přeinstalace:

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

Nesoulad mezi globální a lokální verzí CLI

Příznak: Příkazy CLI selhávají s neočekávanými chybami ve všech projektech.

Příčina: Globální a místní instalace verzí CLI se neshodují.

Řešení: Ověřte místní verzi npm list @microsoft/rayfin-cli. Zobrazí se verze v node_modules aktuálního projektu. Zkontrolujte globální verzi npm list -g @microsoft/rayfin-cli. Zobrazí se verze nainstalovaná v celém systému. Použijte npm uninstall -g s balíčkem Rayfin CLI k odstranění globální verze a používání místních verzí.

Problémy s tajným řízením

Skrytý příkaz nevyvolává výzvu

Příznak:npx rayfin secret set <NAME> Ukončí se bez výzvy k zadání hodnoty.

Příčina: Standardní vstup není interaktivní terminál, nebo proměnná CI prostředí je nastavena na true. Příkaz používá maskovanou interaktivní výzvu.

Solution:

Použijte jednu z následujících podporovaných alternativ pro tvorbu neinteraktivních tajemství:

Nastavte jedno tajemství tak, že jeho hodnotu přidáte příkazu:
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```
Nastavte více tajných údajů ze souboru prostředí:
```
npx rayfin secret set --env-file .\secrets.env
```

Uchovávejte tajné hodnoty mimo historii shellu a necommitujte secret.txt ani .\secrets.env do správy zdrojového kódu.

Skrytý příkaz vrátí chybu „Přístup odepřen“

Příznak:npx rayfin secret set nebo npx rayfin secret list vrátí chybu oprávnění.

Příčina: Aplikace není nasazená, nebo přihlášený účet nemá přístup k cílovému pracovnímu prostoru Fabric.

Solution:

Spusťte npx rayfin up, aby se aplikace zprovoznila.
Spusť npx rayfin login a vyber účet s přístupem do pracovního prostoru.
Zkus znovu tajný příkaz.

Další informace najdete v článku Správa tajných klíčů funkcí.

Problémy s sestavením a balením

Příkaz sestavení selže.

Příznak: Nasazení statického hostingu selže, protože příkaz pro sestavení nevygeneroval žádný výstup.

Příčina: Chyby sestavení nebo chybně nakonfigurovaný příkaz sestavení

Solution:

Spusťte příkaz sestavení ručně:
```
npm run build
```
Opravte všechny nahlášené chyby.
Ověřte, že výstupní složka obsahuje soubory.

Prázdná statická složka

Příznak: Statické nasazení selže s chybou „empty folder“.

Příčina: Nakonfigurovaná folder cesta je nesprávná.

Solution:

Ověřte, že cesta v folder odpovídá výstupu sestavení rayfin.yml:

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

Problémy s databází

Použití schématu databáze se nezdařilo

Příznak: Spuštění npx rayfin up db apply nebo npx rayfin up db apply --force selže.

Příčina: Schéma v vzdálené databázi a schéma definované v kódu aplikace nejsou synchronizované. Kód aplikace je zdrojem pravdy pro aplikaci Fabric.

Neměňte vzdálené databázové schéma přes portál Fabric, SQL Server Management Studio (SSMS), rozšíření SQL Server pro Visual Studio Code nebo jiné SQL nástroje. Následující změny sloupců v datové entitě nejsou podporovány:

Přejmenování sloupku.
Změna datového typu sloupce.
Odstranění sloupce.

Přidání sloupce je podporováno. Odstranění nebo úprava stávajícího sloupce může aplikaci a její nasazení do Fabric poškodit.

Solution:

Vraťte všechny ruční změny v vzdáleném databázovém schématu tak, aby odpovídalo schématu v kódu aplikace.
Pokud agent provedl nepodporovanou změnu schématu v kódu aplikace, instruujte agenta, aby tuto změnu vrátil.
Znovu spusťte příkaz schema apply:
```
npx rayfin up db apply
```
Při přejmenování sloupce může --force umožnit dokončení aktualizace schématu:
```
npx rayfin up db apply --force
```
Caution

Použití --force může způsobit trvalou ztrátu dat. Před pokračováním si prostudujte navrhované operace a potvrďte si, že přijímáte riziko ztráty dat.

Odmítnuté připojení

Příznak: Operace s daty selhávají kvůli chybám připojení.

Příčina: Kontejner databáze není spuštěn nebo selhaly kontroly stavu.

Solution:

Zkontrolujte protokoly kontejneru:
```
docker compose logs -f
```
Restartujte služby.

Ztráta dat po restartování

Příznakem: Po zastavení a spuštění služeb zmizí data.

Příčina: Svazky byly odstraněny pomocí --purge.

Solution:

--down Místo zachování dat použijte--purge.

Známá omezení

Aktuální omezení a doporučená alternativní řešení najdete tady:

count() není k dispozici v klientovi fluent GraphQL – použijte results.length.
Relace mnoho ku mnoha nejsou podporovány – použijte explicitní propojovací entitu.
Objekty relace jsou neprůhledné — zkontrolujte vlastnosti isAuthenticated nebo user.
Po povolení nebo zakázání autentizace v rayfin.yml restartujte backend.

Získání pomoci

Pokud se problém bude opakovat:

Projděte si dokumentaci k Fabric Apps.
Projděte si známé problémy v úložišti GitHub.
Vytvořte zprávu o chybě s podrobnými protokoly a kroky pro reprodukci.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-09-29

Řešení potíží s aplikacemi Fabric

Problémy při nasazení

Nasazení selže s chybou 401 nebo 403

Statické nasazení překračuje limit velikosti

Statické nasazení nemá vzdálený koncový bod

Problémy s ověřováním

Získání autentizačního tokenu selže

Relace se po přihlášení neuchovává

Automaticky otevírané okno Fabric SSO bylo zablokováno

Fabric autentizace vypršela

Fabric SSO hlásí nesoulad původu

initEmbeddedAuth() vrací null

Fabric autentizace hlásí nesoulad stavů

Problémy s datovým modelem

Data API po nasazení vrací interní chybu serveru

Datová služba vyžaduje dialekt

Nová entita není po nasazení dostupná

Relace se nezobrazují v rozhraní API

Zásady autorizace nefungují

Zastaralé odpovědi rozhraní API

Problémy s rozhraním příkazového řádku

Příkaz nebyl nalezen.

Neshoda verzí rozhraní příkazového řádku

Nesoulad mezi globální a lokální verzí CLI

Problémy s tajným řízením

Skrytý příkaz nevyvolává výzvu

Skrytý příkaz vrátí chybu „Přístup odepřen“

Problémy s sestavením a balením

Příkaz sestavení selže.

Prázdná statická složka

Problémy s databází

Použití schématu databáze se nezdařilo

Odmítnuté připojení

Ztráta dat po restartování

Známá omezení

Získání pomoci

Související obsah

Váš názor

Další materiály

`initEmbeddedAuth()` vrací `null`