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

Problemi di autenticazione

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>

Problemi del modello di dati

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.

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

  • Last updated on