Fabric-alkalmazások hibaelhárítása

Gyakori problémák diagnosztizálása Fabric Apps-projekt fejlesztésekor vagy üzembe helyezésekor. Ez a cikk a bejelentkezéssel, a helyi szolgáltatásokkal, a sémamódosításokkal, a statikus üzemeltetéssel és a parancssori felülettel kapcsolatos problémákat ismerteti.

Üzembe helyezési problémák

Az üzembe helyezés 401- vagy 403-os hibával meghiúsul

Tünet: A futtatás npx rayfin up hitelesítési hibát ad vissza.

Okoz: A hitelesítési munkamenet lejárt, vagy nincs bejelentkezve.

Solution:

Az üzembe helyezés újrahitelesítése és újrapróbálkozása:

npx rayfin login
npx rayfin up

A statikus üzembe helyezés meghaladja a méretkorlátot

Tünet: A statikus tartalom üzembe helyezése méretkorláthiba miatt meghiúsul.

Okoz: A tömörített archívum mérete meghaladja a 100 MB-ot.

Solution:

A buildkimenet méretének csökkentése a következővel:

Forrástérképek kizárása éles buildekből
Nagyméretű képek és videók optimalizálása vagy eltávolítása
Bináris fájlok áthelyezése tárolóba ahelyett, hogy összekapcsolja őket
Annak ellenőrzése, hogy a csomagkonfiguráció kizárja-e a fejlesztési összetevőket

A statikus telepítésnek nincs távoli végpontja

Tünet: A futtatás npx rayfin up staticapp deploy jelentése szerint nincs konfigurálva távoli végpont.

Ok: Csak statikus telepítés frissíti a meglévő telepítést. Nem tudja beállítani az eredeti távoli alkalmazást.

Solution:

Egyszer végezz teljes telepítést:

npx rayfin up

A provisionálás befejezése után használd npx rayfin up staticapp deploy a következő, csak statikus frissítésekhez.

Hitelesítési problémák

Hitelesítési token megszerzése megbukik

Tünet:npx rayfin login vagy egy másik hitelesített CLI-parancs Failed to acquire authentication token vagy hitelesítőadat-tárolási hibát jelez.

Ok: A CLI nincs bejelentkezve, vagy a környezet nem biztosít operációs rendszer által támogatott hitelesítő adatok tárolását.

Solution:

Jelentkezz be újra:

npx rayfin login

Korlátozott helyi fejlesztői környezetben, ahol nincs hitelesítési adatbázis, engedélyezheti a titkosítási tartalékot:

npx rayfin login --encryption-fallback-enabled

Warning

A titkosítási tartalékmegoldás a token-gyorsítótárat titkosítatlanul tárolja. Csak megbízható fejlesztői környezetben használd. Ne használd gyártásban vagy megosztott környezetekben.

Tünet: A rendszer a hitelesítés után azonnal kijelentkezteti a felhasználókat.

Okoz: Az ügyfél nincs a megfelelő alap URL-címmel vagy közzétételi kulccsal konfigurálva.

Solution:

Ellenőrizze, hogy a konfiguráció megfelel-e RayfinClient a háttérrendszernek:

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

Symptom: A böngésző letiltja a Fabric portálablakot a bejelentkezés során.

Okoz:ensureSignedInWithFabric() nem egy felhasználói kézmozdulat-kezelőtől lett meghívva.

Solution:

A függvény meghívása szinkron eseménykezelőből:

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

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

Fabric hitelesítés időlejárja

Tünet: A Fabric hitelesítés öt perc után meghibásodik.

Ok: A Fabric portál nem adta vissza az átadási kódot, mielőtt a folyamat lejárt.

Solution:

Győződj meg róla, hogy returnOrigin egyezik az alkalmazásod eredetével, zárd be a felugró ablakot, és indítsd el újra a bejelentkezési folyamatot.

A Fabric SSO eredetütközést jelez

Tünet: A Fabric SSO-átadás elutasítja a választ, mert annak forrása nem egyezik.

Ok:returnOrigin, allowedRedirectUris, vagy fabricPortalUrl nem egyezik azzal a környezettel, ahol az alkalmazás és a Fabric portál fut.

Solution:

Állítsd returnOrigin be az alkalmazásod teljes eredeti forrását.
Győződj meg róla, hogy a forrás a services.auth.allowedRedirectUris helyen jelenik meg.
Használd a Fabric portál URL-jét a megfelelő gyártási, előnézeti vagy fejlesztési környezethez.
A(z) rayfin.yml módosítása után futtassa a(z) npx rayfin up elemet.

További információért lásd: Hitelesítési átirányítási URI-k konfigurálása.

`initEmbeddedAuth()` visszaad `null`

Tünet: Az ágyazott hitelesítés nem hoz létre munkamenetet.

Ok: Az SDK nem érzékelte, hogy az alkalmazás a Fabric-en belül fut.

Solution:

Foglalja bele a(z) ?fabricEmbedded=true elemet az alkalmazás URL-címébe, vagy állítsa be a(z) fabricEmbedded: true elemet a(z) FabricAuthOptions helyen.

A Fabric hitelesítése állapotbeli eltérést jelez

Tünet: Bejelentkezés meghibás, mert a válaszállapot nem egyezik a kérés állapotával.

Ok: A válasz egy lejárt folyamathoz vagy egy korábbi bejelentkezési kísérlethez tartozik.

Solution:

Zárd be a Fabric felugró ablakot, és indítsd újra a bejelentkezési folyamatot. Ne használd újra a korábbi próbálkozás visszahívási URL-jeit vagy állapotértékeit.

Adatmodellekkel kapcsolatos problémák

Az adat API telepítés után belső szerverhibát ad vissza

Tünet:npx rayfin up vagy npx rayfin up db apply sikerrel jár, de a GraphQL vagy REST adat API belső szerver hibát ad.

Ok: A Microsoft SQL Serverben a max nélküli @text() mező NVARCHAR(MAX) oszlopot hoz létre, ami megakadályozhatja a GraphQL-séma létrehozását.

Solution:

Adj hozzá egy explicit maximális hosszt minden érintett szövegmezőhöz:

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

Ezután nézd át és alkalmazd a sémaváltozást:

npx rayfin up db apply --force

Caution

Vizsgálja át az összes jelentett műveletet, mielőtt használná --force. Ez az opció tartós adatvesztést okozhat.

Az adatszolgáltatáshoz dialektusra van szükség

Tünet: A telepítés HTTP 400-as válasszal meghiúsul, és a(z) Dialect is required when Data module is enabled hibát jelzi.

Ok:services.data.enabled az true, de rayfin.yml nem definiálja a dialektust.

Solution:

A Microsoft SQL Server konfigurálása:

services:
  data:
    enabled: true
    dialect: mssql

Új entitás nem elérhető a telepítés után

Tünet: A telepítés sikeres, de egy új vagy megváltoztatott entitás elleni lekérdezések megbuknak, vagy úgy viselkednek, mintha az entitás nem létezne.

Ok: Az adatbázis séma még mindig érvényes, vagy a frontend elavult generált típusokat vagy gyorsítótáros konfigurációt használ.

Solution:

Nézd meg a telepítést:
```
npx rayfin up status
```
Várd meg, amíg a telepítés megfelelő állapotba kerül.
Frissítsd vagy építsd újra a frontendet.
Ha az entitás továbbra is meghibásodik, alkalmazzuk a sémát explicit:
```
npx rayfin up db apply
```

A teljes munkafolyamathoz lásd: A sémamódosítások alkalmazása és ellenőrzése.

Az API-ban nem megjelenő kapcsolatok

Tünet: A kapcsolódó entitásmezők nem érhetők el lekérdezéskor.

Okoz: Hiányzik a navigációs dekorátor, vagy a séma nem lett alkalmazva.

Solution:

Ellenőrizze, hogy a kapcsolatot jelölő dekorátorok jelen vannak-e:
```
@one(() => Notebook) notebook?: Notebook;
```
Alkalmazza újra a sémát.

Az engedélyezési szabályzat nem működik

Tünet: A felhasználók hozzáférhetnek a nem látható rekordokhoz.

Okoz: A szabályzatkifejezés helytelen, vagy a jogcímnevek nem egyeznek.

Solution:

Ellenőrizze, hogy a szabályzat helyes jogcímneveket használ-e (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Naplózza a dekódolt JWT-t, és ellenőrizze, hogy a jogcímértékek megfelelnek-e a kódnak.

Elavult API-válaszok

Tünet: Az előtér elavult adatalakzatokat ad vissza a sémamódosítások után.

Ok: A létrehozott konfiguráció gyorsítótárban van.

Solution:

Állítsa le a háttérfolyamatot.
Törölje a(z) .temp/ könyvtárat itt: rayfin/:
```
rm -rf rayfin/.temp/
```
Indítsa újra a szolgáltatásokat, és alkalmazza újra a sémát.

CLI-problémák

A parancs nem található

Tünet: A futtatás npx rayfin a "parancs nem található" értéket adja vissza.

Okoz: A parancssori felület nincs telepítve, vagy az npm nincs a PATH-ban.

Solution:

Ellenőrizze, hogy a Node.js és az npm telepítve van-e:
```
node --version
npm --version
```
Függőségek újratelepítése:
```
npm install
```

A parancssori felület verziójának eltérése

Tünet: A parancssori felület parancsai a frissítés után váratlan hibákkal meghiúsulnak.

Okoz: A gyorsítótárazott parancssori felület verziója elavult.

Solution:

Frissítés és újratelepítés:

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

CLI globális és helyi verziók eltérése

Tünet: A parancssori felület parancsai nem várt hibákkal meghiúsulnak a projektekben.

Okoz: A CLI-verziók globális és helyi telepítése nem egyezik meg.

Megoldás: Helyi verzió npm list @microsoft/rayfin-cliellenőrzése. Ez az aktuális projekt node_modules verziószámát jeleníti meg. Ellenőrizze a globális verziót npm list -g @microsoft/rayfin-cli. Ez a rendszerszintű telepített verziót jeleníti meg. A npm uninstall -g Rayfin CLI-csomaggal eltávolíthatja a globális verziót, és használhatja a helyi verziókat.

Titkos kezelési problémák

A titkos parancs nem hív

Tünet:npx rayfin secret set <NAME> Érték felkérés nélkül távoz.

Ok: A szabványos bemenet nem interaktív terminál, vagy a CI környezeti változó be van állítva erre: true. A parancs egy maszkos, interaktív promptot használ.

Solution:

Használj az alábbi támogatott alternatívák egyikét a nem interaktív titkos létrehozáshoz:

Állítson be egy titkos értéket úgy, hogy az értékét a parancsnak továbbítja:
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```
Állíts be több titkot egy környezeti fájlból:
```
npx rayfin secret set --env-file .\secrets.env
```

Ne tárolj bizalmas értékeket a shell-előzményekben, és ne commitáld a secret.txt vagy .\secrets.env elemeket a verziókezelőbe.

A titkos parancs „Hozzáférés megtagadva” hibaüzenetet ad vissza

Tünet:npx rayfin secret set vagy npx rayfin secret list engedélyhibát ad vissza.

Ok: Az alkalmazás nincs telepítve, vagy a bejelentkezett fiók nem fér hozzá a célként megadott Fabric-munkaterülethez.

Solution:

Futtassa a(z) npx rayfin up parancsot az alkalmazás üzembe helyezéséhez.
Futtass npx rayfin login és válassz egy fiókot, amely hozzáfér a munkaterülethez.
Próbáld meg újra a titkos parancsot.

További információért lásd: Funkciótitkok kezelése.

Összeállítással és csomagolással kapcsolatos problémák

A Build parancs sikertelen

Tünet: A statikus üzemeltetés üzembe helyezése meghiúsul, mert a buildelési parancs nem hozott létre kimenetet.

Okoz: Buildelési hibák vagy helytelenül konfigurált buildelési parancs.

Solution:

Futtassa manuálisan a buildelési parancsot:
```
npm run build
```
Javítsa ki a jelentett hibákat.
Ellenőrizze, hogy a kimeneti mappa fájlokat tartalmaz-e.

Üres statikus mappa

Tünet: A statikus üzembe helyezés "üres mappa" hibával meghiúsul.

Okoz: A konfigurált folder elérési út helytelen.

Solution:

Ellenőrizze, hogy az folder elérési út rayfin.yml megegyezik-e a build kimenetével:

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

Adatbázissal kapcsolatos problémák

Adatbázis séma alkalmazása hibás

Tünet: A(z) npx rayfin up db apply vagy npx rayfin up db apply --force futtatása sikertelen.

Ok: A távoli adatbázisban lévő séma és az alkalmazás kódjában definiált séma nincs szinkronban. Az alkalmazás kódja a hiteles forrás egy Fabric-alkalmazás esetében.

Ne módosítsd a távoli adatbázis sémát a Fabric portálon keresztül, SQL Server Management Studio (SSMS), az Visual Studio Code SQL Server kiterjesztésén vagy más SQL eszközökön. Az alábbi oszlopok módosításai nem támogatottak egy adatentitásban:

Egy oszlop átnevezése.
Egy oszlop adattípusának megváltoztatása.
Egy oszlop eltávolítása.

Egy oszlop hozzáadása támogatott. Egy meglévő oszlop eltávolítása vagy módosítása megszakíthatja az alkalmazást és annak telepítését a Fabric-re.

Solution:

Visszaállítsd a távoli adatbázis sémájának manuális változtatásait, hogy az egyezzen az alkalmazás kódjában lévő sémával.
Ha egy kódoló ügynök nem támogatott sémát változtatott az alkalmazás kódjában, utasítsa az ügynököt, hogy állítsa vissza ezt a változást.
Futtasd be újra a séma alkalmazási parancsot:
```
npx rayfin up db apply
```
Egy oszlopátnevezés --force esetén lehetővé teheti a séma frissítésének befejezését:
```
npx rayfin up db apply --force
```
Caution

A használat --force tartós adatvesztést okozhat. Tekintse át a javasolt műveleteket, és győződjön meg róla, hogy elfogadja az adatvesztés kockázatát, mielőtt folytatná.

Kapcsolat elutasítva

Tünet: Az adatműveletek csatlakozási hibákkal meghiúsulnak.

Okoz: Az adatbázistároló nem fut, vagy az állapot-ellenőrzések sikertelenek.

Solution:

Konténernaplók áttekintése:
```
docker compose logs -f
```
Indítsa újra a szolgáltatásokat.

Adatvesztés újraindítás után

Tünet: Az adatok eltűnnek a szolgáltatások leállítása és elindítása után.

Ok: A kötetek törlése a(z) --purge használatával történt.

Solution:

Az adatok megőrzése érdekében használja a(z) --down elemet a(z) --purge helyett.

Ismert korlátozások

Az aktuális korlátozásokról és az ajánlott kerülő megoldásokról lásd:

count() nem érhető el a fluent GraphQL-ügyfélben – használja a(z) results.length elemet.
A sok-sokhoz kapcsolatok nem támogatottak – használjon külön kapcsoló entitást.
A munkamenet-objektumok átlátszatlanok – ellenőrzés isAuthenticated vagy user tulajdonságok.
Miután engedélyezte vagy letiltotta a hitelesítést rayfin.yml, indítsa újra a háttérrendszert.

Segítség kérése

Ha a probléma továbbra is fennáll:

Tekintse át a Fabric Apps dokumentációját.
Az ismert problémákat az GitHub adattárban ellenőrizheti.
Küldjön be hibajelentést részletes naplókkal és a hiba reprodukálásának lépéseivel.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Utolsó frissítés időpontja: 2026-09-29

Fabric-alkalmazások hibaelhárítása

Üzembe helyezési problémák

Az üzembe helyezés 401- vagy 403-os hibával meghiúsul

A statikus üzembe helyezés meghaladja a méretkorlátot

A statikus telepítésnek nincs távoli végpontja

Hitelesítési problémák

Hitelesítési token megszerzése megbukik

A munkamenet nem marad fenn a bejelentkezés után

Fabric SSO előugró ablaka le van tiltva

Fabric hitelesítés időlejárja

A Fabric SSO eredetütközést jelez

initEmbeddedAuth() visszaad null

A Fabric hitelesítése állapotbeli eltérést jelez

Adatmodellekkel kapcsolatos problémák

Az adat API telepítés után belső szerverhibát ad vissza

Az adatszolgáltatáshoz dialektusra van szükség

Új entitás nem elérhető a telepítés után

Az API-ban nem megjelenő kapcsolatok

Az engedélyezési szabályzat nem működik

Elavult API-válaszok

CLI-problémák

A parancs nem található

A parancssori felület verziójának eltérése

CLI globális és helyi verziók eltérése

Titkos kezelési problémák

A titkos parancs nem hív

A titkos parancs „Hozzáférés megtagadva” hibaüzenetet ad vissza

Összeállítással és csomagolással kapcsolatos problémák

A Build parancs sikertelen

Üres statikus mappa

Adatbázissal kapcsolatos problémák

Adatbázis séma alkalmazása hibás

Kapcsolat elutasítva

Adatvesztés újraindítás után

Ismert korlátozások

Segítség kérése

Kapcsolódó tartalom

Visszajelzés

További források

`initEmbeddedAuth()` visszaad `null`