Memecahkan masalah aplikasi Fabric

Diagnosis masalah umum saat Anda mengembangkan atau menyebarkan proyek Fabric Apps. Artikel ini membahas masalah dengan masuk, layanan lokal, perubahan skema, hosting statis, dan CLI.

Masalah penerapan

Penerapan gagal dengan error 401 atau 403

Gejala: Menjalankan npx rayfin up mengembalikan kesalahan autentikasi.

Menyebabkan: Sesi autentikasi Anda kedaluwarsa atau Anda tidak masuk.

Solution:

Lakukan autentikasi ulang lalu coba lagi deployment:

npx rayfin login
npx rayfin up

Penyebaran statis melebihi batas ukuran

Gejala: Penyebaran konten statis gagal dengan kesalahan batas ukuran.

Menyebabkan: Arsip terkompresi melebihi 100 MB.

Solution:

Kurangi ukuran output build dengan:

Mengecualikan peta sumber dari versi produksi
Mengoptimalkan atau menghapus gambar dan video besar
Memindahkan file biner ke penyimpanan alih-alih menggabungkannya
Memastikan konfigurasi bundler Anda mengecualikan artefak pengembangan

Penerapan statis tidak memiliki endpoint jarak jauh

Gejala: Menjalankan npx rayfin up staticapp deploy menunjukkan bahwa tidak ada endpoint jarak jauh yang dikonfigurasi.

Penyebab: Penerapan hanya berbasis statis memperbarui penerapan yang sudah ada. Aplikasi jarak jauh awal tidak dapat disiapkan.

Solution:

Jalankan penerapan penuh satu kali:

npx rayfin up

Setelah provisioning selesai, gunakan npx rayfin up staticapp deploy untuk pembaruan statis saja.

Masalah autentikasi

Akuisisi token autentikasi gagal

Gejala:npx rayfin login atau perintah CLI terautentikasi lain melaporkan Failed to acquire authentication token atau kesalahan penyimpanan kredensial.

Penyebab: CLI tidak masuk, atau lingkungan tidak menyediakan penyimpanan kredensial yang didukung sistem operasi.

Solution:

Masuk lagi:

npx rayfin login

Untuk lingkungan pengembangan lokal terbatas tanpa penyimpanan kredensial, Anda dapat mengaktifkan cadangan enkripsi:

npx rayfin login --encryption-fallback-enabled

Warning

Cadangan enkripsi menyimpan cache token dalam bentuk teks asli. Gunakan hanya di lingkungan pengembangan yang tepercaya. Jangan gunakan di lingkungan produksi atau bersama.

Gejala: Pengguna keluar segera setelah autentikasi.

Menyebabkan: Klien tidak dikonfigurasi dengan URL dasar yang benar atau kunci yang dapat diterbitkan.

Solution:

Pastikan konfigurasi RayfinClient sesuai dengan backend Anda:

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

Symptom: Browser memblokir jendela portal Fabric selama masuk.

Menyebabkan:ensureSignedInWithFabric() tidak dipanggil dari handler gerakan pengguna.

Solution:

Panggil fungsi dari penanganan aktivitas sinkron:

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

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

Waktu autentikasi Fabric habis

Gejala: Autentikasi Fabric gagal setelah lima menit.

Penyebab: Portal Fabric tidak mengembalikan kode serah terima sebelum alur berakhir.

Solution:

Pastikan bahwa returnOrigin cocok dengan origin aplikasi Anda, tutup pop-up, lalu mulai lagi alur login.

Fabric SSO melaporkan ketidaksesuaian asal

Gejala: Handoff Fabric SSO menolak respons karena asalnya tidak cocok.

Penyebab:returnOrigin, allowedRedirectUris, atau fabricPortalUrl tidak sesuai dengan lingkungan tempat aplikasi dan portal Fabric berjalan.

Solution:

Setel returnOrigin ke origin dasar aplikasi Anda.
Pastikan bahwa sumber muncul di services.auth.allowedRedirectUris.
Gunakan URL portal Fabric untuk lingkungan produksi, pratinjau, atau pengembangan yang benar.
Jalankan npx rayfin up setelah mengubah rayfin.yml.

Untuk informasi lebih lanjut, lihat Konfigurasikan URI pengalihan autentikasi.

`initEmbeddedAuth()` menghasilkan `null`

Gejala: Autentikasi tertanam tidak membuat sesi.

Penyebab: SDK tidak mendeteksi bahwa aplikasi berjalan di dalam Fabric.

Solution:

Sertakan ?fabricEmbedded=true dalam URL aplikasi, atau atur fabricEmbedded: true di FabricAuthOptions.

Autentikasi Fabric melaporkan ketidaksesuaian status

Gejala: Masuk gagal karena status respons tidak sesuai dengan status permintaan.

Penyebab: Respons ini terkait dengan alur yang telah kedaluwarsa atau upaya masuk yang sebelumnya.

Solution:

Tutup popup Fabric dan restart alur masuk. Jangan menggunakan kembali URL callback atau nilai status dari upaya sebelumnya.

Masalah model data

Data API mengembalikan kesalahan server internal setelah penerapan

Gejala:npx rayfin up atau npx rayfin up db apply berhasil, tetapi API data GraphQL atau REST mengembalikan kesalahan server internal.

Penyebab: Di Microsoft SQL Server, sebuah @text() bidang tanpa max menghasilkan NVARCHAR(MAX) kolom, yang dapat mencegah pembuatan skema GraphQL.

Solution:

Tambahkan panjang maksimum eksplisit pada setiap bidang teks yang terpengaruh:

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

Kemudian tinjau dan terapkan perubahan skema:

npx rayfin up db apply --force

Caution

Tinjau semua operasi yang dilaporkan sebelum menggunakan --force. Opsi ini dapat menyebabkan kehilangan data permanen.

Layanan data memerlukan dialek

Gejala: Penerapan gagal dengan respons HTTP 400 dan melaporkan Dialect is required when Data module is enabled.

Penyebab:services.data.enabled adalah true, tetapi rayfin.yml tidak mendefinisikan dialek.

Solution:

Konfigurasikan Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

Entitas baru tidak tersedia setelah penerapan

Gejala: Penerapan berhasil, tetapi kueri terhadap entitas baru atau yang diubah gagal atau berperilaku seolah-olah entitas tersebut tidak ada.

Penyebab: Skema basis data mungkin masih berlaku, atau frontend mungkin menggunakan tipe yang dihasilkan lama atau konfigurasi cache.

Solution:

Periksa penerapan:
```
npx rayfin up status
```
Tunggu sampai penempatan dalam kondisi sehat.
Perbarui atau bangun ulang frontend.
Jika entitas masih gagal, terapkan skema secara eksplisit:
```
npx rayfin up db apply
```

Untuk alur kerja lengkap, lihat Terapkan dan verifikasi perubahan skema.

Hubungan tidak muncul di API

Gejala: Bidang entitas terkait tidak tersedia saat mengkueri.

Menyebabkan: Dekorator navigasi hilang atau skema tidak diterapkan.

Solution:

Verifikasi bahwa dekorator hubungan ada:

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

Terapkan kembali skema.

Kebijakan otorisasi tidak berfungsi

Gejala: Pengguna dapat mengakses rekaman yang seharusnya tidak mereka lihat.

Menyebabkan: Ekspresi kebijakan salah atau nama klaim tidak cocok.

Solution:

Verifikasi kebijakan menggunakan nama klaim yang benar (sub, , emailrole):
```
policy: (claims, item) => claims.sub.eq(item.user_id)
```
Catat JWT yang didekode untuk memverifikasi nilai klaim yang cocok dengan kode Anda.

Respons API kedaluarsa

Gejala: Frontend mengembalikan bentuk data yang kedaluarsa setelah perubahan skema.

Menyebabkan: Konfigurasi yang dihasilkan di-cache.

Solution:

Hentikan proses backend.
.temp/ Hapus direktori di rayfin/:
```
rm -rf rayfin/.temp/
```
Mulai ulang layanan dan terapkan ulang skema.

Masalah CLI

Perintah tidak ditemukan

Gejala: Menjalankan npx rayfin mengembalikan "perintah tidak ditemukan."

Menyebabkan: CLI tidak diinstal atau npm tidak ada di PATH Anda.

Solution:

Pastikan Node.js dan npm sudah terinstal:
```
node --version
npm --version
```
Instal ulang dependensi:
```
npm install
```

Ketidakcocokan versi CLI

Gejala: Perintah CLI gagal dengan kesalahan tak terduga setelah memperbarui.

Menyebabkan: Versi CLI yang di-cache sudah kedaluarsa.

Solution:

Perbarui dan instal ulang:

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

Ketidakcocokan versi global dan lokal CLI

Gejala: Perintah CLI gagal dengan kesalahan tak terduga di berbagai proyek.

Penyebab: CLI diinstal secara global dan lokal, dan versinya tidak cocok.

Solusi: Validasikan versi lokal npm list @microsoft/rayfin-cli. Ini menunjukkan versi dalam node_modules proyek Anda saat ini. Periksa versi global npm list -g @microsoft/rayfin-cli. Ini menunjukkan versi yang diinstal di seluruh sistem. Gunakan npm uninstall -g dengan paket Rayfin CLI untuk menghapus versi global dan menggunakan versi lokal Anda.

Masalah manajemen rahasia

Perintah rahasia tidak muncul

Gejala:npx rayfin secret set <NAME> keluar tanpa meminta nilai.

Penyebab: Input standar bukanlah terminal interaktif, atau CI variabel lingkungan diatur ke true. Perintah ini menggunakan perintah interaktif tersamarkan.

Solution:

Gunakan salah satu alternatif yang didukung berikut untuk pembuatan rahasia noninteraktif:

Atur satu rahasia dengan mengarahkan nilainya ke perintah:

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

Atur beberapa rahasia dari file lingkungan:

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

Jaga agar nilai rahasia tidak masuk ke riwayat shell Anda dan jangan melakukan commit secret.txt atau .\secrets.env ke kontrol versi.

Perintah rahasia mengembalikan akses ditolak

Gejala:npx rayfin secret set atau npx rayfin secret list mengembalikan kesalahan izin.

Penyebab: Aplikasi belum diterapkan, atau akun yang digunakan untuk masuk tidak memiliki akses ke ruang kerja Fabric target.

Solution:

Jalankan npx rayfin up untuk menyediakan aplikasi.
Jalankan npx rayfin login dan pilih akun yang memiliki akses ke ruang kerja.
Coba ulang perintah rahasia.

Untuk informasi lebih lanjut, lihat Kelola rahasia fungsi.

Masalah pembangunan dan pemaketan

Perintah build gagal

Gejala: Penyebaran hosting statis gagal karena perintah build tidak menghasilkan output.

Menyebabkan: Kesalahan build atau perintah build yang salah dikonfigurasi.

Solution:

Jalankan perintah build secara manual:
```
npm run build
```
Perbaiki kesalahan yang dilaporkan.
Pastikan bahwa folder output berisi file.

Folder statis kosong

Gejala: Penyebaran statis gagal dengan kesalahan "folder kosong".

Menyebabkan: Jalur yang dikonfigurasi folder salah.

Solution:

Pastikan jalur folder di rayfin.yml sesuai dengan hasil build Anda:

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

Masalah database

Penerapan skema database gagal

Gejala: Menjalankan npx rayfin up db apply atau npx rayfin up db apply --force gagal.

Penyebab: Skema di database jarak jauh dan skema yang didefinisikan dalam kode aplikasi tidak sinkron. Kode aplikasi adalah sumber kebenaran untuk aplikasi Fabric.

Jangan mengubah skema database jarak jauh melalui portal Fabric, SQL Server Management Studio (SSMS), ekstensi SQL Server untuk Visual Studio Code, atau alat SQL lainnya. Perubahan berikut pada kolom dalam entitas data tidak didukung:

Mengganti nama kolom.
Mengubah tipe data kolom.
Menghapus kolom.

Penambahan kolom didukung. Menghapus atau mengubah kolom yang sudah ada dapat merusak aplikasi dan penyebarannya ke Fabric.

Solution:

Kembalikan perubahan manual pada skema database jarak jauh agar sesuai dengan skema dalam kode aplikasi.
Jika agen pengkode melakukan perubahan skema yang tidak didukung pada kode aplikasi, instruksikan agen untuk mengembalikan perubahan tersebut.
Jalankan perintah schema apply lagi:
```
npx rayfin up db apply
```
Untuk penggantian nama kolom, --force mungkin memungkinkan pembaruan skema selesai:
```
npx rayfin up db apply --force
```
Caution

Menggunakan --force dapat menyebabkan kehilangan data permanen. Tinjau operasi yang diusulkan dan pastikan Anda menerima risiko kehilangan data sebelum melanjutkan.

Koneksi ditolak

Gejala: Operasi data gagal dengan kesalahan koneksi.

Menyebabkan: Kontainer database tidak berjalan atau pemeriksaan kesehatan gagal.

Solution:

Tinjau log kontainer:
```
docker compose logs -f
```
Mulai ulang layanan.

Kehilangan data setelah menghidupkan ulang

Gejala: Data menghilang setelah menghentikan dan memulai layanan.

Penyebab: Volume dihapus dengan --purge.

Solution:

Gunakan --down alih-alih --purge untuk mempertahankan data.

Batasan yang diketahui

Untuk batasan saat ini dan solusi yang direkomendasikan, lihat:

count() tidak tersedia pada klien GraphQL yang fasih—gunakan results.length.
Hubungan banyak-ke-banyak tidak didukung—gunakan entitas penghubung yang eksplisit.
Objek sesi tidak transparan—periksa properti di isAuthenticated atau user.
Setelah mengaktifkan atau menonaktifkan autentikasi di rayfin.yml, hidupkan ulang backend.

Dapatkan bantuan

Jika masalah berlanjut:

Tinjau dokumentasi Fabric Apps.
Periksa repositori GitHub untuk masalah yang diketahui.
Ajukan laporan bug dengan log terperinci dan langkah-langkah reproduksi.

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-29

Memecahkan masalah aplikasi Fabric

Masalah penerapan

Penerapan gagal dengan error 401 atau 403

Penyebaran statis melebihi batas ukuran

Penerapan statis tidak memiliki endpoint jarak jauh

Masalah autentikasi

Akuisisi token autentikasi gagal

Sesi tidak berlanjut setelah masuk

popup SSO Fabric diblokir

Waktu autentikasi Fabric habis

Fabric SSO melaporkan ketidaksesuaian asal

initEmbeddedAuth() menghasilkan null

Autentikasi Fabric melaporkan ketidaksesuaian status

Masalah model data

Data API mengembalikan kesalahan server internal setelah penerapan

Layanan data memerlukan dialek

Entitas baru tidak tersedia setelah penerapan

Hubungan tidak muncul di API

Kebijakan otorisasi tidak berfungsi

Respons API kedaluarsa

Masalah CLI

Perintah tidak ditemukan

Ketidakcocokan versi CLI

Ketidakcocokan versi global dan lokal CLI

Masalah manajemen rahasia

Perintah rahasia tidak muncul

Perintah rahasia mengembalikan akses ditolak

Masalah pembangunan dan pemaketan

Perintah build gagal

Folder statis kosong

Masalah database

Penerapan skema database gagal

Koneksi ditolak

Kehilangan data setelah menghidupkan ulang

Batasan yang diketahui

Dapatkan bantuan

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan:

`initEmbeddedAuth()` menghasilkan `null`