Αντιμετώπιση προβλημάτων εφαρμογών Fabric

Διαγνώστε συνηθισμένα προβλήματα κατά την ανάπτυξη ή την ανάπτυξη ενός έργου Fabric Apps. Αυτό το άρθρο καλύπτει προβλήματα με την είσοδο, τις τοπικές υπηρεσίες, τις αλλαγές σχήματος, τη στατική φιλοξενία και το CLI.

Ζητήματα ανάπτυξης

Η ανάπτυξη αποτυγχάνει με σφάλμα 401 ή 403

σύμπτωμα: Η εκτέλεση npx rayfin up επιστρέφει ένα σφάλμα ελέγχου ταυτότητας.

Αίτιο: Η περίοδος λειτουργίας ελέγχου ταυτότητας έληξε ή δεν έχετε εισέλθει.

Λύση:

Επαναλάβετε τον έλεγχο ταυτότητας και δοκιμάστε ξανά την ανάπτυξη:

npx rayfin login
npx rayfin up

Η στατική ανάπτυξη υπερβαίνει το όριο μεγέθους

σύμπτωμα: Η ανάπτυξη στατικού περιεχομένου αποτυγχάνει με σφάλμα ορίου μεγέθους.

Αίτιο: Το συμπιεσμένο αρχείο υπερβαίνει τα 100 MB.

Λύση:

Μειώστε το μέγεθος εξόδου κατασκευής με:

Εξαίρεση χαρτών προέλευσης από δομές παραγωγής
Βελτιστοποίηση ή αφαίρεση μεγάλων εικόνων και βίντεο
Μετακίνηση δυαδικών αρχείων στο χώρο αποθήκευσης αντί για ομαδοποίηση
Η επαλήθευση της διαμόρφωσης του bundler εξαιρεί τα τεχνουργήματα ανάπτυξης

Η στατική ανάπτυξη δεν έχει απομακρυσμένο τελικό σημείο

σύμπτωμα: Η εκτέλεση npx rayfin up staticapp deploy αναφέρει ότι δεν έχει ρυθμιστεί κανένα απομακρυσμένο τελικό σημείο.

Αιτία: Η στατική ανάπτυξη ενημερώνει μια υπάρχουσα ανάπτυξη. Δεν μπορεί να παρέχει την αρχική απομακρυσμένη εφαρμογή.

Λύση:

Εκτελέστε μια πλήρη ανάπτυξη μία φορά:

npx rayfin up

Μετά την ολοκλήρωση της παροχής, χρησιμοποιήστε το npx rayfin up staticapp deploy για επόμενες ενημερώσεις μόνο στατικών.

Ζητήματα ελέγχου ταυτότητας

Η απόκτηση διακριτικού ελέγχου ταυτότητας αποτυγχάνει

Σύμπτωμα:npx rayfin login ή άλλες αναφορές Failed to acquire authentication token εντολών CLI με έλεγχο ταυτότητας ή σφάλμα αποθήκευσης διαπιστευτηρίων.

Αιτία: Το CLI δεν είναι συνδεδεμένο ή το περιβάλλον δεν παρέχει χώρο αποθήκευσης διαπιστευτηρίων που υποστηρίζεται από λειτουργικό σύστημα.

Λύση:

Συνδεθείτε ξανά:

npx rayfin login

Για ένα περιορισμένο περιβάλλον τοπικής ανάπτυξης χωρίς χώρο αποθήκευσης διαπιστευτηρίων, μπορείτε να ενεργοποιήσετε την εναλλακτική κρυπτογράφηση:

npx rayfin login --encryption-fallback-enabled

Προειδοποίηση

Η εναλλακτική κρυπτογράφηση αποθηκεύει την κρυφή μνήμη διακριτικού σε απλό κείμενο. Χρησιμοποιήστε το μόνο σε ένα αξιόπιστο περιβάλλον ανάπτυξης. Μην το χρησιμοποιείτε σε περιβάλλοντα παραγωγής ή κοινόχρηστα περιβάλλοντα.

σύμπτωμα: Οι χρήστες αποσυνδέονται αμέσως μετά τον έλεγχο ταυτότητας.

Αίτιο: Ο υπολογιστής-πελάτης δεν έχει ρυθμιστεί με τη σωστή βασική διεύθυνση URL ή το σωστό κλειδί με δυνατότητα δημοσίευσης.

Λύση:

Βεβαιωθείτε ότι η διαμόρφωση ταιριάζει με το RayfinClient backend σας:

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

Σύμπτωμα: Το πρόγραμμα περιήγησης αποκλείει το παράθυρο της πύλης Fabric κατά την είσοδο.

Αίτιο:ensureSignedInWithFabric() δεν κλήθηκε από χειριστή χειρονομιών χρήστη.

Λύση:

Καλέστε τη συνάρτηση από ένα σύγχρονο πρόγραμμα χειρισμού συμβάντων:

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

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

Το χρονικό όριο ελέγχου ταυτότητας Fabric λήγει

Σύμπτωμα: Ο έλεγχος ταυτότητας Fabric αποτυγχάνει μετά από πέντε λεπτά.

Αιτία: Η πύλη Fabric δεν επέστρεψε τον κωδικό παράδοσης πριν από τη λήξη της ροής.

Λύση:

Επιβεβαιώστε ότι returnOrigin ταιριάζει με την προέλευση της εφαρμογής σας, κλείστε το αναδυόμενο παράθυρο και ξεκινήστε ξανά τη ροή εισόδου.

Fabric SSO αναφέρει αναντιστοιχία προέλευσης

σύμπτωμα: Η μεταβίβαση Fabric SSO απορρίπτει την απόκριση επειδή η προέλευσή της δεν ταιριάζει.

Cause:returnOrigin, allowedRedirectUrisή fabricPortalUrl δεν συμφωνεί με το περιβάλλον όπου εκτελούνται η εφαρμογή και η πύλη Fabric.

Λύση:

Ορίστε returnOrigin την απλή προέλευση της εφαρμογής σας.
Επιβεβαιώστε ότι η προέλευση εμφανίζεται στο services.auth.allowedRedirectUris.
Χρησιμοποιήστε τη διεύθυνση URL της πύλης Fabric για το σωστό περιβάλλον παραγωγής, προεπισκόπησης ή ανάπτυξης.
Τρέξτε npx rayfin up μετά την αλλαγή rayfin.yml.

Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Διαμόρφωση URI ανακατεύθυνσης ελέγχου ταυτότητας.

`initEmbeddedAuth()` Επιστροφές `null`

Σύμπτωμα: Ο ενσωματωμένος έλεγχος ταυτότητας δεν δημιουργεί περίοδο λειτουργίας.

Αιτία: Το SDK δεν εντόπισε ότι η εφαρμογή εκτελείται μέσα στο Fabric.

Λύση:

Συμπεριλάβετε ?fabricEmbedded=true στη διεύθυνση URL της εφαρμογής ή ορίστε fabricEmbedded: true το FabricAuthOptions.

Ο έλεγχος ταυτότητας Fabric αναφέρει μια ασυμφωνία κατάστασης

Σύμπτωμα: Η είσοδος αποτυγχάνει, επειδή η κατάσταση απόκρισης δεν συμφωνεί με την κατάσταση αίτησης.

Αιτία: Η απόκριση ανήκει σε μια ροή που έχει λήξει ή σε μια προηγούμενη προσπάθεια εισόδου.

Λύση:

Κλείστε το αναδυόμενο παράθυρο Fabric και επανεκκινήστε τη ροή εισόδου. Μην επαναχρησιμοποιείτε διευθύνσεις URL επιστροφής κλήσης ή τιμές κατάστασης από προηγούμενη προσπάθεια.

Ζητήματα μοντέλου δεδομένων

Το Data API επιστρέφει ένα εσωτερικό σφάλμα διακομιστή μετά την ανάπτυξη

σύμπτωμα:npx rayfin up ή npx rayfin up db apply επιτυχεί, αλλά το API δεδομένων GraphQL ή REST επιστρέφει ένα εσωτερικό σφάλμα διακομιστή.

Αιτία: Στον Microsoft SQL Server, ένα @text() πεδίο χωρίς max δημιουργεί μια NVARCHAR(MAX) στήλη, η οποία μπορεί να αποτρέψει τη δημιουργία σχήματος GraphQL.

Λύση:

Προσθέστε ένα ρητό μέγιστο μήκος σε κάθε πεδίο κειμένου που επηρεάζεται:

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

Στη συνέχεια, ελέγξτε και εφαρμόστε την αλλαγή σχήματος:

npx rayfin up db apply --force

Προσοχή

Ελέγξτε όλες τις αναφερόμενες λειτουργίες πριν χρησιμοποιήσετε το --force. Η επιλογή μπορεί να προκαλέσει μόνιμη απώλεια δεδομένων.

Η υπηρεσία δεδομένων απαιτεί μια διάλεκτο

σύμπτωμα: Η ανάπτυξη αποτυγχάνει με απόκριση HTTP 400 και αναφέρει Dialect is required when Data module is enabled.

Αιτία:services.data.enabled είναι true, αλλά rayfin.yml δεν ορίζει διάλεκτο.

Λύση:

Ρύθμιση παραμέτρων του Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Η νέα οντότητα δεν είναι διαθέσιμη μετά την ανάπτυξη

Σύμπτωμα: Η ανάπτυξη είναι επιτυχής, αλλά τα ερωτήματα σε μια νέα ή τροποποιημένη οντότητα αποτυγχάνουν ή συμπεριφέρονται σαν να μην υπάρχει η οντότητα.

Αιτία: Το σχήμα της βάσης δεδομένων μπορεί να εξακολουθεί να εφαρμόζεται ή το προσκήνιο μπορεί να χρησιμοποιεί τύπους που δημιουργούνται χωρίς ενημέρωση ή ρύθμιση παραμέτρων στο cache.

Λύση:

Ελέγξτε την ανάπτυξη:
```
npx rayfin up status
```
Περιμένετε έως ότου η ανάπτυξη είναι υγιής.
Ανανεώστε ή δημιουργήστε ξανά το frontend.
Εάν η οντότητα εξακολουθεί να αποτυγχάνει, εφαρμόστε το σχήμα ρητά:
```
npx rayfin up db apply
```

Για την πλήρη ροή εργασιών, ανατρέξτε στο θέμα Εφαρμογή και επαλήθευση αλλαγών σχήματος.

Σχέσεις που δεν εμφανίζονται στο API

σύμπτωμα: Τα πεδία σχετικής οντότητας δεν είναι διαθέσιμα κατά την υποβολή ερωτημάτων.

Αίτιο: Ο διακοσμητής πλοήγησης λείπει ή το σχήμα δεν εφαρμόστηκε.

Λύση:

Βεβαιωθείτε ότι οι διακοσμητές σχέσεων είναι παρόντες:
```
@one(() => Notebook) notebook?: Notebook;
```
Εφαρμόστε ξανά το σχήμα.

Η πολιτική εξουσιοδότησης δεν λειτουργεί

σύμπτωμα: Οι χρήστες μπορούν να έχουν πρόσβαση σε καρτέλες που δεν πρέπει να βλέπουν.

Αίτιο: Η παράσταση πολιτικής είναι εσφαλμένη ή τα ονόματα των αξιώσεων δεν ταιριάζουν.

Λύση:

Βεβαιωθείτε ότι η πολιτική χρησιμοποιεί σωστά ονόματα αξιώσεων (sub, email, role):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Καταγράψτε το αποκωδικοποιημένο JWT για να επαληθεύσετε ότι οι τιμές αξίωσης ταιριάζουν με τον κώδικά σας.

Μπαγιάτικες απαντήσεις API

σύμπτωμα: Το Frontend επιστρέφει παλιά σχήματα δεδομένων μετά τις αλλαγές σχήματος.

Αίτιο: Η διαμόρφωση που δημιουργείται αποθηκεύεται στο cache.

Λύση:

Σταματήστε το backend.
Διαγράψτε τον .temp/ κατάλογο στο rayfin/:
```
rm -rf rayfin/.temp/
```
Επανεκκινήστε τις υπηρεσίες και εφαρμόστε ξανά το σχήμα.

Θέματα CLI

Η εντολή δεν βρέθηκε

σύμπτωμα: Η εκτέλεση npx rayfin επιστρέφει "η εντολή δεν βρέθηκε".

Αίτιο: Το CLI δεν είναι εγκατεστημένο ή το npm δεν βρίσκεται στο PATH σας.

Λύση:

Βεβαιωθείτε ότι τα Node.js και npm είναι εγκατεστημένα:
```
node --version
npm --version
```
Επανεγκατάσταση εξαρτήσεων:
```
npm install
```

Αναντιστοιχία έκδοσης CLI

σύμπτωμα: Οι εντολές CLI αποτυγχάνουν με μη αναμενόμενα σφάλματα μετά την ενημέρωση.

Αίτιο: Η αποθηκευμένη έκδοση CLI είναι παλιά.

Λύση:

Ενημέρωση και επανεγκατάσταση:

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

Αναντιστοιχία καθολικής και τοπικής έκδοσης CLI

σύμπτωμα: Οι εντολές CLI αποτυγχάνουν με μη αναμενόμενα σφάλματα σε όλα τα έργα.

Αίτιο: Παγκόσμια και τοπική εγκατάσταση των εκδόσεων CLI και δεν ταιριάζουν.

Λύση: Επικύρωση τοπικής έκδοσης npm list @microsoft/rayfin-cli. Αυτό εμφανίζει την έκδοση στην node_modules του τρέχοντος έργου σας. Ελέγξτε την καθολική έκδοση npm list -g @microsoft/rayfin-cli. Αυτό δείχνει την έκδοση που είναι εγκατεστημένη σε όλο το σύστημα. Χρησιμοποιήστε το npm uninstall -g με το πακέτο Rayfin CLI για να καταργήσετε την καθολική έκδοση και να χρησιμοποιήσετε τις τοπικές σας εκδόσεις.

Θέματα διαχείρισης μυστικών

Η μυστική εντολή δεν ζητά

σύμπτωμα:npx rayfin secret set <NAME> χωρίς να ζητηθεί τιμή.

Αιτία: Η τυπική είσοδος δεν είναι αλληλεπιδραστικό τερματικό ή η μεταβλητή CI περιβάλλοντος έχει οριστεί σε true. Η εντολή χρησιμοποιεί μια καλυμμένη αλληλεπιδραστική προτροπή.

Λύση:

Χρησιμοποιήστε μία από τις ακόλουθες υποστηριζόμενες εναλλακτικές λύσεις για μη αλληλεπιδραστική δημιουργία μυστικών:

Ορίστε ένα μυστικό διοχετεύοντας την τιμή του στην εντολή:
```
Get-Content .\secret.txt | npx rayfin secret set <NAME> --stdin
```
Ορίστε πολλά μυστικά από ένα αρχείο περιβάλλοντος:
```
npx rayfin secret set --env-file .\secrets.env
```

Κρατήστε μυστικές τιμές έξω από το ιστορικό του κελύφους σας και μην δεσμεύεστε secret.txt ή .\secrets.env ελέγχετε την πηγή.

Η μυστική εντολή επιστρέφει την άδεια που απορρίφθηκε

σύμπτωμα:npx rayfin secret set ή npx rayfin secret list επιστρέφει ένα σφάλμα άδειας.

Αιτία: Η εφαρμογή δεν έχει αναπτυχθεί ή ο συνδεδεμένος λογαριασμός δεν έχει πρόσβαση στον χώρο εργασίας Fabric προορισμού.

Λύση:

Εκτελέστε npx rayfin up για να παρέχετε την εφαρμογή.
Εκτελέστε npx rayfin login και επιλέξτε έναν λογαριασμό με πρόσβαση στον χώρο εργασίας.
Δοκιμάστε ξανά τη μυστική εντολή.

Για περισσότερες πληροφορίες, ανατρέξτε στο θέμα Διαχείριση μυστικών συναρτήσεων.

Ζητήματα κατασκευής και συσκευασίας

Η εντολή "Δημιουργία" αποτυγχάνει

σύμπτωμα: Η ανάπτυξη στατικής φιλοξενίας αποτυγχάνει επειδή η εντολή build δεν παρήγαγε έξοδο.

Αίτιο: Σφάλματα κατασκευής ή εσφαλμένη διαμόρφωση εντολής build.

Λύση:

Εκτελέστε την εντολή build χειροκίνητα:
```
npm run build
```
Διορθώστε τυχόν σφάλματα που αναφέρθηκαν.
Βεβαιωθείτε ότι ο φάκελος εξόδου περιέχει αρχεία.

Κενός στατικός φάκελος

σύμπτωμα: Η στατική ανάπτυξη αποτυγχάνει με το σφάλμα "empty folder".

Αίτιο: Η διαμορφωμένη folder διαδρομή είναι λανθασμένη.

Λύση:

Επαληθεύστε ότι η διαδρομή ταιριάζει με folder το αποτέλεσμα της rayfin.yml κατασκευής σας:

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

Θέματα βάσης δεδομένων

Η εφαρμογή σχήματος βάσης δεδομένων αποτυγχάνει

σύμπτωμα: Τρέχει npx rayfin up db apply ή npx rayfin up db apply --force αποτυγχάνει.

Αίτιο: Το σχήμα στην απομακρυσμένη βάση δεδομένων και το σχήμα που ορίζεται στον κώδικα της εφαρμογής δεν είναι συγχρονισμένα. Ο κώδικας της εφαρμογής είναι η πηγή αλήθειας για μια εφαρμογή Fabric.

Μην τροποποιείτε το σχήμα της απομακρυσμένης βάσης δεδομένων μέσω της πύλης Fabric, του SQL Server Management Studio (SSMS), της επέκτασης SQL Server για τον κώδικα του Visual Studio Code ή άλλων εργαλείων SQL. Οι ακόλουθες αλλαγές σε στήλες σε μια οντότητα δεδομένων δεν υποστηρίζονται:

Μετονομασία στήλης.
Αλλαγή του τύπου δεδομένων μιας στήλης.
Αφαίρεση στήλης.

Υποστηρίζεται η προσθήκη στήλης. Η κατάργηση ή η τροποποίηση μιας υπάρχουσας στήλης μπορεί να διακόψει τη λειτουργία της εφαρμογής και την ανάπτυξή της στο Fabric.

Λύση:

Επαναφέρετε τυχόν μη αυτόματες αλλαγές στο σχήμα της απομακρυσμένης βάσης δεδομένων, ώστε να ταιριάζει με το σχήμα στον κώδικα της εφαρμογής.
Εάν ένας παράγοντας κωδικοποίησης έκανε μια μη υποστηριζόμενη αλλαγή σχήματος στον κώδικα της εφαρμογής, δώστε εντολή στον παράγοντα να επαναφέρει αυτήν την αλλαγή.
Εκτελέστε ξανά την εντολή εφαρμογής σχήματος:
```
npx rayfin up db apply
```
Για μια μετονομασία στήλης, --force μπορεί να επιτρέψει την ολοκλήρωση της ενημέρωσης σχήματος:
```
npx rayfin up db apply --force
```
Προσοχή

Η χρήση --force μπορεί να προκαλέσει μόνιμη απώλεια δεδομένων. Ελέγξτε τις προτεινόμενες λειτουργίες και επιβεβαιώστε ότι αποδέχεστε τον κίνδυνο απώλειας δεδομένων πριν συνεχίσετε.

Η σύνδεση απορρίφθηκε

σύμπτωμα: Οι λειτουργίες δεδομένων αποτυγχάνουν λόγω σφαλμάτων σύνδεσης.

Αίτιο: Το κοντέινερ της βάσης δεδομένων δεν εκτελείται ή οι έλεγχοι εύρυθμης λειτουργίας απέτυχαν.

Λύση:

Ελέγξτε τα αρχεία καταγραφής κοντέινερ:
```
docker compose logs -f
```
Επανεκκινήστε τις υπηρεσίες.

Απώλεια δεδομένων μετά την επανεκκίνηση

σύμπτωμα: Τα δεδομένα εξαφανίζονται μετά τη διακοπή και την εκκίνηση των υπηρεσιών.

Αίτιο: Οι τόμοι διαγράφηκαν με --purge.

Λύση:

Χρησιμοποιήστε το --down--purge αντί για τη διατήρηση δεδομένων.

Γνωστοί περιορισμοί

Για τους τρέχοντες περιορισμούς και τις προτεινόμενες λύσεις, ανατρέξτε στο θέμα:

count() δεν είναι διαθέσιμο στον άπταιστα πελάτη GraphQL—χρησιμοποιήστε results.lengthτο .
Οι σχέσεις πολλά-προς-πολλά δεν υποστηρίζονται—χρησιμοποιήστε μια ρητή οντότητα συμμετοχής.
Τα αντικείμενα της συνεδρίας είναι αδιαφανή—έλεγχος ή isAuthenticateduser ιδιότητες.
Αφού ενεργοποιήσετε ή απενεργοποιήσετε τον έλεγχο ταυτότητας στο rayfin.yml, επανεκκινήστε το backend.

Λάβετε βοήθεια

Εάν το πρόβλημα παραμένει:

Ανατρέξτε στην τεκμηρίωση εφαρμογών Fabric.
Ελέγξτε το αποθετήριο GitHub για γνωστά προβλήματα.
Υποβάλετε μια αναφορά σφάλματος με λεπτομερή αρχεία καταγραφής και βήματα αναπαραγωγής.

Σχόλια

Ήταν χρήσιμη αυτή η σελίδα;

Τελευταία ενημέρωση στις 2026-09-29

Αντιμετώπιση προβλημάτων εφαρμογών Fabric

Ζητήματα ανάπτυξης

Η ανάπτυξη αποτυγχάνει με σφάλμα 401 ή 403

Η στατική ανάπτυξη υπερβαίνει το όριο μεγέθους

Η στατική ανάπτυξη δεν έχει απομακρυσμένο τελικό σημείο

Ζητήματα ελέγχου ταυτότητας

Η απόκτηση διακριτικού ελέγχου ταυτότητας αποτυγχάνει

Η περίοδος λειτουργίας δεν διατηρείται μετά την είσοδο

Fabric SSO μπλοκαρίστηκε

Το χρονικό όριο ελέγχου ταυτότητας Fabric λήγει

Fabric SSO αναφέρει αναντιστοιχία προέλευσης

initEmbeddedAuth() Επιστροφές null

Ο έλεγχος ταυτότητας Fabric αναφέρει μια ασυμφωνία κατάστασης

Ζητήματα μοντέλου δεδομένων

Το Data API επιστρέφει ένα εσωτερικό σφάλμα διακομιστή μετά την ανάπτυξη

Η υπηρεσία δεδομένων απαιτεί μια διάλεκτο

Η νέα οντότητα δεν είναι διαθέσιμη μετά την ανάπτυξη

Σχέσεις που δεν εμφανίζονται στο API

Η πολιτική εξουσιοδότησης δεν λειτουργεί

Μπαγιάτικες απαντήσεις API

Θέματα CLI

Η εντολή δεν βρέθηκε

Αναντιστοιχία έκδοσης CLI

Αναντιστοιχία καθολικής και τοπικής έκδοσης CLI

Θέματα διαχείρισης μυστικών

Η μυστική εντολή δεν ζητά

Η μυστική εντολή επιστρέφει την άδεια που απορρίφθηκε

Ζητήματα κατασκευής και συσκευασίας

Η εντολή "Δημιουργία" αποτυγχάνει

Κενός στατικός φάκελος

Θέματα βάσης δεδομένων

Η εφαρμογή σχήματος βάσης δεδομένων αποτυγχάνει

Η σύνδεση απορρίφθηκε

Απώλεια δεδομένων μετά την επανεκκίνηση

Γνωστοί περιορισμοί

Λάβετε βοήθεια

Σχετικό περιεχόμενο

Σχόλια

Πρόσθετοι πόροι

`initEmbeddedAuth()` Επιστροφές `null`