Vianetsintä Fabric-sovelluksissa

Diagnosoi yleisiä ongelmia, kun kehität tai otat käyttöön Fabric Apps -projektin. Tässä artikkelissa käsitellään kirjautumisen, paikallisten palveluiden, skeemamuutosten, staattisen hostingin ja komentorivijärjestelmän ongelmia.

Käyttöönotto-ongelmat

Käyttöönotto epäonnistuu 401- tai 403-virheellä

Oire: Käynnistys npx rayfin up palauttaa todennusvirheen.

Syy: Tunnistautumisistuntosi päättyi tai et ole kirjautunut sisään.

Ratkaisu:

Uudelleentodennus ja käyttöönotto uudelleen:

npx rayfin login
npx rayfin up

Staattinen käyttöönotto ylittää kokorajan

Oire: Staattisen sisällön käyttöönotto epäonnistuu kokorajoitusvirheen vuoksi.

Syy: Pakattu arkisto ylittää 100 MB.

Ratkaisu:

Pienennä buildin tuotoskokoa seuraavasti:

Lähdekarttojen poissulkeminen tuotantoversioista
Suurten kuvien ja videoiden optimointi tai poistaminen
Binääritiedostojen siirtäminen tallennustilaan niiden niputtamisen sijaan
Bundler-konfiguraation varmistaminen sulkee kehityshäiriöt pois

Staattisella käyttöönotolla ei ole etäpäätepisteitä

Oire: Käynnissä npx rayfin up staticapp deploy oleva raportti kertoo, ettei etäpäätepisteitä ole konfiguroitu.

Syy: Pelkkä staattinen käyttöönotto päivittää olemassa olevan käyttöönoton. Se ei pysty tarjoamaan alkuperäistä etäsovellusta.

Ratkaisu:

Suorita täysi käyttöönotto kerran:

npx rayfin up

Kun proquestointi on valmis, käytä npx rayfin up staticapp deploy sitä seuraaviin vain staattisiin päivityksiin.

Autentikointiongelmat

Tunnistautumistokenin hankinta epäonnistuu

Oire:npx rayfin login tai muut todennetut CLI-komentoraportit Failed to acquire authentication token tai tunnistetietojen tallennusvirhe.

Syy: Komentojärjestelmä ei ole kirjautuneena sisään, tai ympäristö ei tarjoa käyttöjärjestelmän tukemaa tunnistetietojen tallennusta.

Ratkaisu:

Kirjaudu uudelleen sisään:

npx rayfin login

Rajoitetussa paikallisessa kehitysympäristössä ilman tunnistetietojen tallennusta voit ottaa käyttöön salauksen varasuunnitelman:

npx rayfin login --encryption-fallback-enabled

Varoitus

Salauksen varajärjestelmä tallentaa token-välimuistin selväkielisenä tekstinä. Käytä sitä vain luotettavassa kehitysympäristössä. Älä käytä sitä tuotannossa tai jaetuissa ympäristöissä.

Oire: Käyttäjät kirjautuvat ulos heti tunnistautumisen jälkeen.

Syy: Asiakasohjelmaa ei ole määritetty oikealla perus-URL:llä tai julkaistavalla avaimella.

Ratkaisu:

Varmista, että kokoonpano RayfinClient vastaa taustajärjestelmääsi:

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

Oire: Selain estää Fabric-portaalin ikkunan kirjautumisen aikana.

Syy:ensureSignedInWithFabric() Ei kutsuttu käyttäjäeleiden käsittelijältä.

Ratkaisu:

Kutsu funktio synkronisen tapahtumakäsittelijän kautta:

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

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

Fabric-todennus aikakatkaisee

Oire: Fabric-tunnistautuminen epäonnistuu viiden minuutin kuluttua.

Syy: Fabric-portaali ei palauttanut siirtokoodia ennen virran vanhentumista.

Ratkaisu:

Varmista, että se returnOrigin vastaa sovelluksesi alkuperää, sulje ponnahdusikkuna ja aloita kirjautumisprosessi uudelleen.

Fabric SSO raportoi alkuperävirheestä

Oire: Fabric SSO:n siirto hylkää vastauksen, koska sen alkuperä ei täsmää.

Syy:returnOrigin, allowedRedirectUris, tai fabricPortalUrl ei vastaa ympäristöä, jossa sovellus ja Fabric-portaali pyörivät.

Ratkaisu:

Aseta returnOrigin sovelluksesi pelkkä alkuperä.
Vahvista, että alkuperä esiintyy .services.auth.allowedRedirectUris
Käytä Fabric-portaalin URL-osoitetta oikean tuotanto-, esikatselu- tai kehitysympäristön löytämiseksi.
Juokse npx rayfin up vaihtamisen rayfin.ymljälkeen.

Lisätietoja löytyy kohdasta Määritä totuudenmukainen redirect URIs.

`initEmbeddedAuth()` Palautukset `null`

Oire: Upotettu tunnistautuminen ei luo istuntoa.

Syy: SDK ei havainnut, että sovellus pyörii Fabric:n sisällä.

Ratkaisu:

Sisällytä ?fabricEmbedded=true sovelluksen URL-osoitteeseen tai aseta fabricEmbedded: true .FabricAuthOptions

Fabric authentication raportoi tilan epäsuhdan.

Oire: Kirjautuminen epäonnistuu, koska vastaustila ei vastaa pyyntötilaa.

Syy: Vastaus kuuluu vanhennuneeseen virtaan tai aiempaan kirjautumisyritykseen.

Ratkaisu:

Sulje Fabric-ponnahdusikkuna ja käynnistä kirjautumisprosessi uudelleen. Älä käytä aiemman yrityksen callback-URL-osoitteita tai tilaarvoja.

Tietomallin ongelmat

Data API palauttaa sisäisen palvelinvirheen käyttöönoton jälkeen

Oire:npx rayfin up tai npx rayfin up db apply onnistuu, mutta GraphQL- tai REST-data-API palauttaa sisäisen palvelinvirheen.

Syy: Microsoft SQL Server:ssä kenttä @text() ilman max tuottaa sarakkeenNVARCHAR(MAX), joka voi estää GraphQL-skeeman generoinnin.

Ratkaisu:

Lisää jokaiselle kyseiselle tekstikentälle eksplisiittinen maksimipituus:

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

Sitten tarkista ja sovella skeemamuutos:

npx rayfin up db apply --force

Varoitus

Käy läpi kaikki raportoidut toiminnot ennen kuin käytät --force. Vaihtoehto voi aiheuttaa pysyvää tietojen menetystä.

Datapalvelu vaatii murteen

Oire: Käyttöönotto epäonnistuu HTTP 400 -vastauksessa ja raportoi Dialect is required when Data module is enabled.

Syy:services.data.enabled on true, mutta rayfin.yml ei määrittele murretta.

Ratkaisu:

Configure Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Uutta yksikköä ei ole saatavilla käyttöönoton jälkeen

Oire: Käyttöönotto onnistuu, mutta kyselyt uutta tai vaihdettua entiteettiä vastaan epäonnistuvat tai käyttäytyvät ikään kuin entiteettiä ei olisi olemassa.

Syy: Tietokantaskeema saattaa edelleen olla voimassa, tai frontend saattaa käyttää vanhentuneita generoituja tyyppejä tai välimuistissa olevia konfiguraatioita.

Ratkaisu:

Tarkista käyttöönotto:
```
npx rayfin up status
```
Odota, kunnes lähetys on kunnossa.
Päivitä tai rakenna käyttöliittymä uudelleen.
Jos entiteetti edelleen epäonnistuu, sovelletaan skeemaa eksplisiittisesti:
```
npx rayfin up db apply
```

Koko työnkulun löydät kohdasta Apply ja tarkista skeeman muutokset.

Suhteet, jotka eivät näy API:ssa

Oire: Liittyvät entiteettikentät eivät ole käytettävissä kyselyissä.

Syy: Navigointisisustus puuttuu tai skeemaa ei ole otettu käyttöön.

Ratkaisu:

Varmista, että suhteen sisustajat ovat paikalla:
```
@one(() => Notebook) notebook?: Notebook;
```
Sovella skeema uudelleen.

Valtuutuskäytäntö ei toimi

Oire: Käyttäjät voivat päästä käsiksi tietueisiin, joita heidän ei pitäisi nähdä.

Syy: Vakuutuslauseke on virheellinen tai korvausvaatimusten nimet eivät täsmää.

Ratkaisu:

Varmista, että vakuutus käyttää oikeita korvausnimiä (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Kirjaa purettu JWT varmistaaksesi, että vaatimusten arvot vastaavat koodiasi.

Vanhentuneet API-vastaukset

Oire: Frontend palauttaa vanhentuneita datamuotoja skeeman muuttuessa.

Syy: Generoitu konfiguraatio tallennetaan välimuistiin.

Ratkaisu:

Pysäytä taustajärjestelmä.
Poista hakemisto .temp/ :rayfin/
```
rm -rf rayfin/.temp/
```
Käynnistä palvelut uudelleen ja sovella skeema uudelleen.

CLI-ongelmat

Komentoa ei löytynyt

Oire: Käynnissä npx rayfin oleva palautus palauttaa "komentoa ei löydetty."

Syy: CLI:tä ei ole asennettu tai npm ei ole PATHILLASI.

Ratkaisu:

Varmista, että Node.js ja npm ovat asennettuna:
```
node --version
npm --version
```
Palauta riippuvuudet:
```
npm install
```

CLI-version epäsopivuus

Oire: CLI-komennot epäonnistuvat odottamattomien virheiden vuoksi päivityksen jälkeen.

Syy: Välimuistissa oleva CLI-versio on vanhentunut.

Ratkaisu:

Päivitä ja asenna uudelleen:

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

CLI:n globaali ja paikallinen versio ei ole yhteensopiva

Oire: CLI-komennot epäonnistuvat odottamattomien virheiden vuoksi eri projekteissa.

Syy: CLI-versioiden globaali ja paikallinen asennus, mutta ne eivät täsmään.

Ratkaisu: Validoi paikallinen versio npm list @microsoft/rayfin-cli. Tämä näyttää version nykyisen projektisi node_modules. Tarkista globaali versio npm list -g @microsoft/rayfin-cli. Tämä näyttää järjestelmän laajuisen asennetun version. Käytä npm uninstall -g Rayfin CLI -pakettia poistaaksesi globaalin version ja käyttääksesi paikallisia versioita.

Salaisen hallinnan ongelmat

Salainen komento ei kehitä

Oire:npx rayfin secret set <NAME> poistuu ilman arvon pyytämistä.

Syy: Vakiosyöte ei ole interaktiivinen terminaali, tai CI ympäristömuuttuja on asetettu .true Komento käyttää naamioitua interaktiivista kehotusta.

Ratkaisu:

Käytä jotakin seuraavista tuetuista vaihtoehdoista ei-interaktiiviseen salaisuuksien luomiseen:

Aseta yksi salaisuus ohjaamalla sen arvo komentoon:

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

Aseta useita salaisuuksia ympäristötiedostosta:
```
npx rayfin secret set --env-file .\secrets.env
```

Pidä salaiset arvot poissa shell-historiastasi äläkä sitoudu secret.txt tai .\secrets.env käytä lähdekoodin hallintaa.

Salainen komento palauttaa luvan evättyn

Oire:npx rayfin secret set tai npx rayfin secret list palauttaa käyttöoikeusvirheen.

Syy: Sovellusta ei ole otettu käyttöön, tai kirjautuneella tilillä ei ole pääsyä kohde-Fabric-työtilaan.

Ratkaisu:

Juokse npx rayfin up sovelluksen käyttöönottoon.
Suorita npx rayfin login ja valitse tili, jolla on pääsy työtilaan.
Yritä salainen komento uudelleen.

Lisätietoja löytyy kohdasta Hallinnoi funktion salaisuuksia.

Rakennus- ja pakkausongelmat

Build-komento epäonnistuu

Oire: Staattinen isännöinti epäonnistuu, koska build-komento ei tuottanut tulosta.

Syy: Rakennusvirheet tai väärin konfiguroitu build-komento.

Ratkaisu:

Suorita build-komento manuaalisesti:
```
npm run build
```
Korjaa kaikki raportoidut virheet.
Varmista, että ulostulokansio sisältää tiedostoja.

Tyhjä staattinen kansio

Oire: Staattinen käyttöönotto epäonnistuu "tyhjä kansio" -virheellä.

Syy: Konfiguroitu folder polku on virheellinen.

Ratkaisu:

Varmista, että reitti folder vastaa rayfin.yml rakennustulostasi:

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

Tietokantaongelmat

Tietokantaskeeman soveltaminen epäonnistuu

Oire: Juokseminen npx rayfin up db apply tai npx rayfin up db apply --force epäonnistuminen.

Syy: Etätietokannan skeema ja sovelluksen koodissa määritelty skeema ovat epäsynkassa. Sovelluksen koodi on totuuden lähde Fabric-sovellukselle.

Älä muokkaa etätietokantaskeemaa Fabric-portaalin, SQL Server Management Studio (SSMS), SQL Server -laajennuksen Visual Studio Code -laajennuksen tai muiden SQL-työkalujen kautta. Seuraavat muutokset sarakkeissa tietoyksikössä eivät ole tuettuja:

Sarakkeen nimeäminen uudelleen.
Sarakkeen tietotyypin muuttaminen.
Pylvään poistaminen.

Sarakkeen lisääminen on tuettua. Olemassa olevan sarakkeen poistaminen tai muuttaminen voi rikkoa sovelluksen ja sen käyttöönoton Fabric-järjestelmään.

Ratkaisu:

Peruuta kaikki manuaaliset muutokset etätietokantaskeemaan niin, että ne vastaavat sovelluksen koodin skeemaa.
Jos koodausagentti teki tuettoman skeeman muutoksen sovelluksen koodiin, käske agenttia palauttamaan muutos.
Suorita skeeman soveltamiskomento uudelleen:
```
npx rayfin up db apply
```
Sarakkeen uudelleennimeämisessä --force skeeman päivitys saattaa valmistua:
```
npx rayfin up db apply --force
```
Varoitus

Käyttäminen --force voi aiheuttaa pysyvää datan menetystä. Tarkista ehdotetut toimenpiteet ja varmista, että hyväksyt tietojen menetyksen riskin ennen etenemistä.

Yhteys hylätty

Oire: Datatoiminnot epäonnistuvat yhteysvirheiden vuoksi.

Syy: Tietokantakontti ei ole käynnissä tai terveystarkistukset epäonnistuivat.

Ratkaisu:

Tarkista säiliölokit:
```
docker compose logs -f
```
Käynnistä palvelut uudelleen.

Tietojen menetys uudelleenkäynnistyksen jälkeen

Oire: Data katoaa palveluiden pysähtymisen ja käynnistymisen jälkeen.

Syy: Niteet poistettiin .--purge

Ratkaisu:

Käytä --down tiedon säilyttämisen sijaan --purge .

Tunnetut rajoitukset

Nykyiset rajoitukset ja suositeltavat kiertotavat löytyvät täältä:

count() ei ole saatavilla sujuvassa GraphQL-asiakasohjelmassa—käytä results.length.
Moni-moni-suhteita ei tueta – käytä eksplisiittistä liittymisentiteettiä.
Istunto-objektit ovat läpinäkymättömiä—tarkistus isAuthenticated tai user ominaisuudet.
Kun autentikointi rayfin.ymlon aktivoitu tai poistettu käytöstä, käynnistä backend uudelleen.

Avun hakeminen

Jos ongelma jatkuu:

Tutustu Fabric Apps -dokumentaatioon.
Tarkista GitHub repository tunnettuja ongelmia varten.
Tee bugiraportti, jossa on yksityiskohtaiset lokit ja toistovaiheet.

Palaute

Onko tästä sivusta apua?

Viimeksi päivitetty 2026-09-29

Vianetsintä Fabric-sovelluksissa

Käyttöönotto-ongelmat

Käyttöönotto epäonnistuu 401- tai 403-virheellä

Staattinen käyttöönotto ylittää kokorajan

Staattisella käyttöönotolla ei ole etäpäätepisteitä

Autentikointiongelmat

Tunnistautumistokenin hankinta epäonnistuu

Istunto ei säily kirjautumisen jälkeen

Fabric SSO -ponnahdusikkuna estetty

Fabric-todennus aikakatkaisee

Fabric SSO raportoi alkuperävirheestä

initEmbeddedAuth() Palautukset null

Fabric authentication raportoi tilan epäsuhdan.

Tietomallin ongelmat

Data API palauttaa sisäisen palvelinvirheen käyttöönoton jälkeen

Datapalvelu vaatii murteen

Uutta yksikköä ei ole saatavilla käyttöönoton jälkeen

Suhteet, jotka eivät näy API:ssa

Valtuutuskäytäntö ei toimi

Vanhentuneet API-vastaukset

CLI-ongelmat

Komentoa ei löytynyt

CLI-version epäsopivuus

CLI:n globaali ja paikallinen versio ei ole yhteensopiva

Salaisen hallinnan ongelmat

Salainen komento ei kehitä

Salainen komento palauttaa luvan evättyn

Rakennus- ja pakkausongelmat

Build-komento epäonnistuu

Tyhjä staattinen kansio

Tietokantaongelmat

Tietokantaskeeman soveltaminen epäonnistuu

Yhteys hylätty

Tietojen menetys uudelleenkäynnistyksen jälkeen

Tunnetut rajoitukset

Avun hakeminen

Liittyvä sisältö

Palaute

Lisäresursseja

`initEmbeddedAuth()` Palautukset `null`