Risolvere i problemi delle app Fabric

Diagnosticare i problemi comuni quando si sviluppa o si distribuisce un progetto app di Fabric. Questo articolo illustra i problemi relativi all'accesso, ai servizi locali, alle modifiche dello schema, all'hosting statico e all'interfaccia della riga di comando.

Problemi di distribuzione

La distribuzione non riesce con errore 401 o 403

Sintomo: L'esecuzione npx rayfin up restituisce un errore di autenticazione.

Causa: La sessione di autenticazione è scaduta o non si è connessi.

Soluzione:

Ripetere l'autenticazione e ripetere la distribuzione:

npx rayfin login
npx rayfin up

La distribuzione statica supera il limite di dimensione

Sintomo: La distribuzione del contenuto statico ha esito negativo con un errore di limite di dimensioni.

Causa: L'archivio compresso supera i 100 MB.

Soluzione:

Ridurre le dimensioni dell'output di compilazione tramite:

  • Esclusione delle mappe di origine dalle build di produzione
  • Ottimizzazione o rimozione di immagini e video di grandi dimensioni
  • Spostamento di file binari nella risorsa di archiviazione invece di raggrupparli
  • La verifica della configurazione del bundler esclude gli artefatti di sviluppo

La distribuzione statica non ha un endpoint remoto

Sintomo: L’esecuzione di npx rayfin up staticapp deploy segnala che non è configurato alcun endpoint remoto.

Causa: La distribuzione solo statica aggiorna una distribuzione esistente. Non può eseguire il provisioning dell'app remota iniziale.

Soluzione:

Esegui una distribuzione completa una sola volta:

npx rayfin up

Dopo il completamento del provisioning, utilizzare npx rayfin up staticapp deploy per aggiornamenti successivi solo statici.

Problemi di autenticazione

Fallimento dell'acquisizione del token di autenticazione

Sintomo:npx rayfin login oppure un altro comando CLI autenticato segnala Failed to acquire authentication token o un errore di archiviazione delle credenziali.

Causa: La CLI non è connessa, oppure l'ambiente non fornisce archiviazione delle credenziali supportata dal sistema operativo.

Soluzione:

Accedi di nuovo:

npx rayfin login

Per un ambiente di sviluppo locale limitato senza archiviazione delle credenziali, puoi abilitare il fallback della crittografia:

npx rayfin login --encryption-fallback-enabled

Avvertimento

Il fallback della crittografia memorizza la cache del token in testo chiaro. Usalo solo in un ambiente di sviluppo affidabile. Non usarlo in produzione o in ambienti condivisi.

Sessione non persistente dopo l'accesso

Sintomo: Gli utenti vengono disconnessi immediatamente dopo l'autenticazione.

Causa: Il client non è configurato con l'URL di base corretto o la chiave pubblicabile.

Soluzione:

Verifica che la RayfinClient configurazione corrisponda al tuo back-end:

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

Fabric popup SSO bloccato

Symptom: Browser blocca la finestra del portale di Fabric durante l'accesso.

Causa:ensureSignedInWithFabric() non è stato chiamato da un gestore dei gesti dell'utente.

Soluzione:

Chiamare la funzione da un gestore eventi sincrono:

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

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

Scadenza dell'autenticazione Fabric

Sintomo: l'autenticazione Fabric fallisce dopo cinque minuti.

Causa: Il portale Fabric non ha restituito il codice di passaggio prima che il flusso scadesse.

Soluzione:

Conferma che returnOrigin corrisponda all'origine della tua app, chiudi il pop-up e riavvia il flusso di accesso.

Fabric SSO segnala una discrepanza di origine

Sintomo: Il passaggio di consegne SSO Fabric rifiuta la risposta perché la sua origine non corrisponde.

Causa:returnOrigin, allowedRedirectUris, o fabricPortalUrl non corrisponde all'ambiente in cui sono in esecuzione l'app e il portale Fabric.

Soluzione:

  1. Imposta returnOrigin su l'origine di base della tua app.
  2. Conferma che l'origine appare in services.auth.allowedRedirectUris.
  3. Usa l'URL del portale Fabric per l'ambiente di produzione, anteprima o sviluppo corretto.
  4. Esegui npx rayfin up dopo aver modificato rayfin.yml.

Per ulteriori informazioni, vedi Configura gli URI di reindirizzamento dell'autenticazione.

initEmbeddedAuth() restituisce null

Sintomo: L'autenticazione incorporata non crea una sessione.

Causa: L'SDK non ha rilevato che l'app è in esecuzione all'interno di Fabric.

Soluzione:

Includi ?fabricEmbedded=true nell'URL dell'app, oppure imposta fabricEmbedded: true in FabricAuthOptions.

L'autenticazione Fabric segnala una discrepanza di stato

Sintomo: Il login fallisce perché lo stato della risposta non corrisponde allo stato della richiesta.

Causa: La risposta appartiene a un flusso scaduto o a un precedente tentativo di accesso.

Soluzione:

Chiudi il popup Fabric e riavvia il flusso di accesso. Non riutilizzare URL di callback o valori di stato di un tentativo precedente.

Problemi del modello di dati

L'API dati restituisce un errore interno del server dopo il deployment

Sintomo:npx rayfin up oppure npx rayfin up db apply riesce, ma l'API dati GraphQL o REST restituisce un errore interno del server.

Causa: Su Microsoft SQL Server, un @text() campo senza max genera una NVARCHAR(MAX) colonna che può impedire la generazione dello schema GraphQL.

Soluzione:

Aggiungi una lunghezza massima esplicita a ciascun campo di testo interessato:

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

Poi rivedi e applica il cambiamento dello schema:

npx rayfin up db apply --force

Caution

Rivedere tutte le operazioni segnalate prima di utilizzare --force. L'opzione può causare una perdita permanente di dati.

Il servizio dati richiede un dialetto

Sintomo: Il deployment fallisce con una risposta HTTP 400 e segnala Dialect is required when Data module is enabled.

Causa:services.data.enabled è true, ma rayfin.yml non definisce un dialetto.

Soluzione:

Configura Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

La nuova entità non è disponibile dopo il dispiegamento

Sintomo: Il deployment ha successo, ma le query su un'entità nuova o modificata falliscono o si comportano come se l'entità non esistesse.

Causa: Lo schema del database potrebbe essere ancora in applicazione, oppure il frontend potrebbe utilizzare tipi generati obsoleti o una configurazione cache.

Soluzione:

  1. Controlla il dispiegamento:

    npx rayfin up status

  2. Aspetta che il dispiegamento sia sano.

  3. Aggiorna o ricostruisci il frontend.

  4. Se l'entità continua a fallire, applica esplicitamente lo schema:

    npx rayfin up db apply

Per il flusso di lavoro completo, vedi Applica e verifica modifiche allo schema.

Relazioni non visualizzate nell'API

Sintomo: I campi di entità correlati non sono disponibili durante l'esecuzione di query.

Causa: L'elemento Decoratore di navigazione manca oppure lo schema non è stato applicato.

Soluzione:

  1. Verificare che i decoratori di relazione siano presenti:

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

  2. Riapplicare lo schema.

Criteri di autorizzazione non funzionanti

Sintomo: Gli utenti possono accedere ai record che non dovrebbero vedere.

Causa: L'espressione di criteri non è corretta o i nomi delle attestazioni non corrispondono.

Soluzione:

  1. Verifica che il criterio usi i nomi di attestazione corretti (sub, email, role):

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

  2. Registra il JWT decodificato per verificare che i valori dei claim corrispondano a quelli nel codice.

Risposte api non aggiornate

Sintomo: Il front-end restituisce forme di dati obsolete dopo le modifiche dello schema.

Causa: La configurazione generata viene memorizzata nella cache.

Soluzione:

  1. Arresta il backend.

  2. Eliminare la cartella .temp/ in rayfin/:

    rm -rf rayfin/.temp/

  3. Riavviare i servizi e riapplicare lo schema.

Problemi CLI

Comando non trovato

Sintomo: L'esecuzione npx rayfin restituisce "comando non trovato".

Causa: L'interfaccia della riga di comando non è installata o npm non è presente nel percorso.

Soluzione:

  1. Verificare che Node.js e npm siano installati:

    node --version
npm --version

  2. Reinstallare le dipendenze:

    npm install

Versione CLI non corrispondente

Sintomo: I comandi dell'interfaccia della riga di comando hanno esito negativo con errori imprevisti dopo l'aggiornamento.

Causa: La versione dell'interfaccia della riga di comando memorizzata nella cache non è aggiornata.

Soluzione:

Aggiornare e reinstallare:

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

Discorrispondenza tra la versione globale e locale della CLI

Sintomo: I comandi CLI non riescono ed emettono errori imprevisti in tutti i progetti.

Causa: Installazione globale e locale delle versioni dell'interfaccia della riga di comando e non corrispondono.

Soluzione: convalidare la versione npm list @microsoft/rayfin-clilocale. Viene visualizzata la versione nel node_modules del progetto corrente. Controlla la versione globale npm list -g @microsoft/rayfin-cli. Viene visualizzata la versione installata a livello di sistema. Usare npm uninstall -g con il pacchetto dell'interfaccia della riga di comando Rayfin per rimuovere la versione globale e usare le versioni locali.

Questioni di gestione segreta

Il comando segreto non visualizza alcun prompt

Sintomo:npx rayfin secret set <NAME> Esce senza chiedere un valore.

Causa: L'input standard non è un terminale interattivo, oppure la CI variabile ambiente è impostata su true. Il comando utilizza un prompt interattivo mascherato.

Soluzione:

Usa una delle seguenti alternative supportate per la creazione di segreti non interattiva:

  • Imposta un secret reindirizzando il relativo valore al comando tramite pipe:

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

  • Imposta più segreti da un file di ambiente:

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

Tieni i valori segreti fuori dalla cronologia della shell e non fare il commit di secret.txt o .\secrets.env nel sistema di controllo del codice sorgente.

Il comando segreto restituisce «autorizzazione negata»

Sintomo:npx rayfin secret set oppure npx rayfin secret list restituisce un errore di autorizzazione.

Causa: L'app non è distribuita, oppure l'account connesso non ha accesso allo spazio di lavoro Fabric di destinazione.

Soluzione:

  1. Esegui npx rayfin up per eseguire il provisioning dell'app.
  2. Esegui npx rayfin login e seleziona un account con accesso allo spazio di lavoro.
  3. Riprova il comando segreto.

Per ulteriori informazioni, vedi Gestisci i segreti delle funzioni.

Problemi di compilazione e pacchettizzazione

Il comando di compilazione non riesce

Sintomo: La distribuzione dell'hosting statico ha esito negativo perché il comando di compilazione non ha prodotto alcun output.

Causa: Errori di compilazione o comando di compilazione non configurato correttamente.

Soluzione:

  1. Eseguire manualmente il comando di compilazione:

    npm run build

  2. Correggere eventuali errori segnalati.

  3. Verificare che la cartella di output contenga file.

Cartella statica vuota

Sintomo: Il deployment statico non riesce con l'errore "cartella vuota".

Causa: Il percorso configurato folder non è corretto.

Soluzione:

Verifica che il percorso folder in rayfin.yml corrisponda all'output della compilazione:

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

Problemi relativi al database

Fallimento dell'applicazione dello schema del database

Sintomo: L'esecuzione di npx rayfin up db apply o npx rayfin up db apply --force non riesce.

Causa: Lo schema nel database remoto e quello definito nel codice dell'app sono fuori sincrono. Il codice dell'app è la fonte di verità per un'app Fabric.

Non modificare lo schema del database remoto tramite il portale Fabric, SQL Server Management Studio (SSMS), l'estensione SQL Server per Visual Studio Code o altri strumenti SQL. Le seguenti modifiche alle colonne in un'entità dati non sono supportate:

  • Rinominare una colonna.
  • Cambiare il tipo di dato di una colonna.
  • Rimuovere una colonna.

L'aggiunta di una colonna è supportata. Rimuovere o modificare una colonna esistente può compromettere l'app e il suo deployment su Fabric.

Soluzione:

  1. Annulla eventuali modifiche manuali allo schema del database remoto in modo che corrisponda allo schema nel codice dell'app.

  2. Se un agente di codifica ha effettuato una modifica dello schema non supportata nel codice dell'app, istruisci l'agente a ripristinare quella modifica.

  3. Esegui di nuovo il comando schema apply:

    npx rayfin up db apply

    Per una rinomina di colonna, --force potrebbe permettere che l'aggiornamento dello schema si completi:

    npx rayfin up db apply --force

    Caution

    L'uso --force di può causare una perdita permanente di dati. Esamina le operazioni proposte e conferma di accettare il rischio di perdita dati prima di procedere.

Connessione rifiutata

Sintomo: Le operazioni di dati hanno esito negativo con errori di connessione.

Causa: Il contenitore di database non è in esecuzione o i controlli di integrità non sono riusciti.

Soluzione:

  1. Esaminare i log dei contenitori:

    docker compose logs -f

  2. Riavviare i servizi.

Perdita di dati dopo il riavvio

Sintomo: I dati scompaiono dopo l'arresto e l'avvio dei servizi.

Causa: I volumi sono stati eliminati con --purge.

Soluzione:

Usare --down anziché --purge per conservare i dati.

Limitazioni note

Per le limitazioni correnti e le soluzioni alternative consigliate, vedere:

  • count() non è disponibile nel client Fluent GraphQL: usare results.length.
  • Le relazioni molti-a-molti non sono supportate: usare un'entità di join esplicita.
  • Gli oggetti di sessione sono opachi: controlla le proprietà isAuthenticated o user.
  • Dopo aver abilitato o disabilitato l'autenticazione in rayfin.yml, riavviare il back-end.

Come ottenere assistenza

Se il problema persiste:

  1. Esaminare la documentazione Fabric Apps.
  2. Controllare il repository GitHub per i problemi noti.
  3. Segnalare un bug con log dettagliati e passaggi di riproduzione.

Contenuti correlati

  • Ultimo aggiornamento: