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

Il database genera report sulle modifiche distruttive

Sintomo: Esecuzione di npx rayfin up db apply blocchi con un avviso relativo alla perdita di dati.

Causa: L'interfaccia della riga di comando ha rilevato modifiche dello schema che potrebbero eliminare i dati (eliminazione di colonne, ridenominazione delle tabelle).

Soluzione:

Esaminare attentamente le operazioni elencate. Se si accetta la perdita di dati, usare --force:

npx rayfin up db apply --force

Caution

L'uso --force di può causare una perdita permanente di dati. Verificare le operazioni prima di procedere.

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

Mancata corrispondenza tra la versione globale e quella 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

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