Résoudre les problèmes liés aux applications Fabric

Diagnostiquez les problèmes courants lorsque vous développez ou déployez un projet Fabric Apps. Cet article traite des problèmes liés à la connexion, aux services locaux, aux modifications de schéma, à l’hébergement statique et à l’interface CLI.

Problèmes de déploiement

Échec du déploiement avec l’erreur 401 ou 403

Symptôme: L’exécution npx rayfin up retourne une erreur d’authentification.

Cause : Votre session d’authentification a expiré ou vous n’êtes pas connecté.

Solution:

Réauthentifier et réessayer le déploiement :

npx rayfin login
npx rayfin up

La base de données applique des rapports de modifications destructrices

Symptôme: L'exécution de blocs npx rayfin up db apply affiche un avertissement de perte de données.

Cause : L’interface CLI a détecté des modifications de schéma susceptibles de supprimer des données (suppression de colonnes, renommage de tables).

Solution:

Passez en revue attentivement les opérations répertoriées. Si vous acceptez la perte de données, utilisez --force:

npx rayfin up db apply --force

Avertissement

L’utilisation --force peut entraîner une perte de données permanente. Vérifiez les opérations avant de continuer.

Le déploiement statique dépasse la limite de taille

Symptôme: Le déploiement de contenu statique échoue avec une erreur de limite de taille.

Cause : L’archive compressée dépasse 100 Mo.

Solution:

Réduisez la taille de sortie de build par :

  • Exclusion des fichiers de mappage source des compilations de production
  • Optimisation ou suppression d’images et de vidéos volumineuses
  • Déplacement de fichiers binaires vers le stockage au lieu de les regrouper
  • La vérification de la configuration de votre bundler exclut les artefacts de développement

Problèmes d’authentification

Session non persistante après la connexion

Symptôme: Les utilisateurs sont déconnectés immédiatement après l’authentification.

Cause : Le client n’est pas configuré avec l’URL de base correcte ou la clé modifiable.

Solution:

Vérifiez que la RayfinClient configuration correspond à votre 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,
});

fenêtre contextuelle d’authentification unique Fabric bloquée

Symptom : Browser bloque la fenêtre du portail Fabric pendant la connexion.

Cause :ensureSignedInWithFabric() n’a pas été appelé à partir d’un gestionnaire de mouvements utilisateur.

Solution:

Appelez la fonction à partir d’un gestionnaire d’événements synchrone :

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

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

Problèmes liés au modèle de données

Relations non affichées dans l’API

Symptôme: Les champs d’entité associés ne sont pas disponibles lors de l’interrogation.

Cause : Le décorateur de navigation est manquant ou le schéma n’a pas été appliqué.

Solution:

  1. Vérifiez que les décorateurs de relation sont présents :

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

  2. Réappliquez le schéma.

Stratégie d’autorisation ne fonctionne pas

Symptôme: Les utilisateurs peuvent accéder aux enregistrements qu’ils ne doivent pas voir.

Cause : L’expression de stratégie est incorrecte ou les noms de revendication ne correspondent pas.

Solution:

  1. Vérifiez que la stratégie utilise les noms de revendication corrects (sub, email, role) :

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

  2. Consignez le JWT décodé pour vérifier que les valeurs des revendications correspondent à votre code.

Réponses d’API obsolètes

Symptôme: Le serveur frontal retourne des formes de données obsolètes après les modifications du schéma.

Cause : La configuration générée est mise en cache.

Solution:

  1. Arrêtez le backend.

  2. Supprimez le .temp/ répertoire dans rayfin/:

    rm -rf rayfin/.temp/

  3. Redémarrez les services et réappliquez le schéma.

Problèmes liés à l’interface de ligne de commande

Commande introuvable

Symptôme: L’exécution npx rayfin retourne « commande introuvable ».

Cause : L’interface CLI n’est pas installée ou npm n’est pas dans votre chemin d’accès.

Solution:

  1. Vérifiez que Node.js et npm sont installés :

    node --version
npm --version

  2. Réinstallez les dépendances :

    npm install

Incompatibilité de version CLI

Symptôme: Les commandes CLI échouent avec des erreurs inattendues après la mise à jour.

Cause : La version de l’interface CLI mise en cache est obsolète.

Solution:

Mettre à jour et réinstaller :

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

Incompatibilité de version globale et locale de l’interface CLI

Symptôme: Les commandes CLI échouent avec des erreurs inattendues entre les projets.

Cause : Installation globale et locale des versions de l’interface CLI et elles ne correspondent pas.

Solution : Valider la version npm list @microsoft/rayfin-clilocale . Cela montre la version du node_modules de votre projet actuel. Vérifiez la version npm list -g @microsoft/rayfin-cliglobale. Cela montre la version installée à l’échelle du système. Utilisez npm uninstall -g le package Rayfin CLI pour supprimer la version globale et utiliser vos versions locales.

Problèmes de compilation et de mise en package

Échec de la commande Build

Symptôme: Échec du déploiement d’hébergement statique, car la commande de build n’a produit aucune sortie.

Cause : Erreurs de génération ou commande de build mal configurée.

Solution:

  1. Exécutez la commande de build manuellement :

    npm run build

  2. Corrigez les erreurs signalées.

  3. Vérifiez que le dossier de sortie contient des fichiers.

Dossier statique vide

Symptôme: Le déploiement statique échoue avec l’erreur « dossier vide ».

Cause : Le chemin d’accès configuré folder est incorrect.

Solution:

Vérifiez que le chemin d’accès folder correspond rayfin.yml à votre sortie de build :

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

Problèmes de base de données

Connexion refusée

Symptôme: Les opérations de données échouent avec les erreurs de connexion.

Cause : Le conteneur de base de données n’est pas en cours d’exécution ou les vérifications d’intégrité ont échoué.

Solution:

  1. Passez en revue les journaux de conteneur :

    docker compose logs -f

  2. Redémarrez les services.

Perte de données après le redémarrage

Symptôme: Les données disparaissent après l’arrêt et le démarrage des services.

Cause : Les volumes ont été supprimés avec --purge.

Solution:

Utilisez --down au lieu de --purge pour préserver les données.

Limitations connues

Pour connaître les limitations actuelles et les solutions de contournement recommandées, consultez :

  • count() n’est pas disponible sur le client Fluent GraphQL : utilisez results.length.
  • Les relations plusieurs-à-plusieurs ne sont pas prises en charge : utilisez une entité de jointure explicite.
  • Les objets de session sont opaques : vérifiez les propriétés isAuthenticated ou user.
  • Après avoir activé ou désactivé l’authentification dans rayfin.yml, redémarrez le serveur principal.

Obtenir de l’aide

Si le problème persiste :

  1. Consultez la documentation Fabric Apps.
  2. Vérifiez le dépôt GitHub pour connaître les problèmes connus.
  3. Soumettez un rapport de bug avec des journaux détaillés et les étapes de reproduction.

Contenu connexe

  • Last updated on