Hosting statischer Inhalte für Fabric Apps

Fabric Apps enthält einen statischen Inhaltshostingdienst, der Ihre Frontend-Anwendung zusammen mit Ihren Back-End-APIs erstellt, packt und bereitstellt. Wenn statisches Hosting aktiviert ist, deployt die CLI deine gebauten Assets auf Fabric und stellt eine Hosting-URL bereit. Du kannst von den Nutzern verlangen, sich anzumelden und die Berechtigung zur Ansicht der Fabric-App zu haben, oder du kannst anonymen Zugriff auf die gehosteten Assets gewähren.

Voraussetzungen

• Ein Fabric Apps-Projekt mit einer Frontend-Anwendung (z. B. React, Vue oder Vanilla TypeScript).
• Ein Build-Befehl, der statische Ausgabe erzeugt (z. B. npm run build).

Funktionsweise des statischen Hostings

Wenn Sie mit aktiviertem statischen Hosting bereitstellen, führt die CLI die folgenden Schritte aus:

1. Führt den konfigurierten Buildbefehl aus (z. B. npm run build).
2. Überprüft, ob der Ausgabeordner vorhanden ist und Dateien enthält.
3. Packt alle Dateien in ein komprimiertes ZIP-Archiv (maximal 100 MB).
4. Lädt das Archiv auf den Fabric Apps-Host hoch.
5. Verwendet die konfigurierte Zugriffseinstellung und gibt eine Hosting-URL zurück.

Konfigurieren des statischen Hostings

Fügen Sie unter staticHosting in Ihrer services-Datei einen rayfin/rayfin.yml-Abschnitt hinzu:

services:
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html
    assetAccess: protected

Konfigurationsoptionen

Zugriff auf gehostete Assets konfigurieren

Legen Sie assetAccess auf einen dieser Werte fest:

• protected- Erfordert, dass Nutzer sich anmelden und die Berechtigung haben, die Fabric-App anzusehen, bevor sie gehostete Assets abrufen können.
• public - Ermöglicht es jedem mit der Hosting-URL, gehostete Assets abzurufen, ohne sich anzumelden.

Protected Hosting kontrolliert den Zugriff auf die statischen Dateien, die Fabric Apps bereitstellt. Sie ersetzt nicht die Authentifizierung und Autorisierung in deiner Anwendung oder APIs.

Die erste interaktive npx rayfin up Bereitstellung fordert dich auf, eine Zugriffseinstellung auszuwählen, falls assetAccess sie nicht konfiguriert ist. Nicht-interaktive Deployments verwenden protected und speichern diese Einstellung auf rayfin.yml.

Um die Zugriffseinstellung nach der Bereitstellung zu ändern, aktualisieren Sie assetAccess, und führen Sie dann eine vollständige Bereitstellung aus:

npx rayfin up

Der Befehl npx rayfin up staticapp deploy aktualisiert nur den Inhalt. Es wendet keinen neuen assetAccess Wert an.

Beispiel mit einem separaten Front-End-Verzeichnis

Wenn ihr Frontend-Code in einem Unterverzeichnis gespeichert ist:

services:
  staticHosting:
    enabled: true
    root: frontend
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html
    assetAccess: protected

Diese Konfiguration löst den Ausgabepfad zu <project-root>/frontend/dist auf.

Bereitstellen statischer Inhalte

Vollständige Bereitstellung

Wenn Sie npx rayfin up ausführen, werden statische Inhalte automatisch als Teil der Full-Stack-Bereitstellung bereitgestellt:

npx rayfin up

Die CLI erstellt Ihr Frontend, packt die Ausgabe und lädt sie zusammen mit Ihrer Back-End-Konfiguration hoch. Nach der Bereitstellung druckt die CLI die Hosting-URL und schreibt sie in Ihre .env.fabric-* Datei als VITE_RAYFIN_HOSTING_URL.

Eigenständige statische Bereitstellung

Verwenden Sie den staticapp deploy Unterbefehl, um nur Ihre statischen Inhalte erneut bereitzustellen, ohne die vollständige Bereitstellung erneut durchzuführen:

npx rayfin up staticapp deploy

Dieser Befehl ist nützlich, wenn Sie nur den Frontend-Code geändert haben und einen schnelleren Iterationszyklus wünschen.

Build-Schritt überspringen

Wenn Sie ihr Frontend bereits erstellt haben und die vorhandene Ausgabe ohne Neuerstellung bereitstellen möchten:

npx rayfin up staticapp deploy --skip-build

Ausführliche Protokollierung aktivieren

Detaillierte Ausgabe während der Bereitstellung anzeigen:

npx rayfin up staticapp deploy --verbose

Konfiguration des Authentifizierungsrückrufs

Wenn sowohl statisches Hosting als auch die Authentifizierung aktiviert sind, registriert die Rayfin CLI automatisch einen Authentifizierungsrückruf-URI basierend auf Ihrer Hosting-URL.

Wenn Ihre Hosting-URL beispielsweise lautet https://example.webapp.com, fügt die CLI diesen Rückruf-URI hinzu:

services:
  auth:
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
      - https://example.webapp.com/auth/callback

Sie müssen den Authentifizierungsrückruf-URI nicht manuell konfigurieren– die CLI aktualisiert die Konfiguration und pusht ihn während der Bereitstellung.

Grenzwerte für die Bereitstellungsgröße

• Das komprimierte ZIP-Archiv darf 100 MB nicht überschreiten.
• Die CLI verwendet die maximale Komprimierung, um die Uploadgröße zu minimieren.
• Wenn Ihre Build-Ausgabe das Limit überschreitet, optimieren Sie Ihre Assets folgendermaßen:
  • Ausschließen von Source-Maps aus Produktions-Builds.
  • Komprimieren oder Entfernen großer Bilder und Videos.
  • Verschieben von Binärdateien in Fabric Apps-Speicher, anstatt sie zu bündeln.

Vollständiges Beispiel

Eine vollständige rayfin.yml Konfiguration mit aktiviertem statischem Hosting, Authentifizierung und Datendiensten:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    fabric:
      enabled: true
  data:
    enabled: true
    dialect: mssql
  staticHosting:
    enabled: true
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html
    assetAccess: protected

Lokales Testen

Überprüfen Sie vor der Bereitstellung, ob Ihr statischer Build lokal funktioniert:

1. Erstellen Sie Ihr Frontend:

   npm run build
   

2. Überprüfen Sie, ob der Ausgabeordner die erwarteten Dateien enthält:

   ls dist
   

3. Bereitstellen der erstellten Dateien mit einem lokalen statischen Server:

   npx serve dist
   

4. Öffnen Sie die vom Server gedruckte URL, und überprüfen Sie, ob die Anwendung ordnungsgemäß geladen wird.

Bereitstellungsprobleme beheben

Statischer Ordner nicht gefunden

Wenn die CLI meldet, dass der statische Ordner nicht vorhanden ist:

• Überprüfen Sie, ob der folder Pfad in rayfin.yml korrekt und relativ zu root ist (oder zum Projektstammverzeichnis, wenn root nicht festgelegt ist).
• Stellen Sie sicher, dass der Buildbefehl erfolgreich ausgeführt und die Ausgabe im erwarteten Verzeichnis erstellt wurde.

Leerer statischer Ordner

Ein leerer Ausgabeordner bedeutet in der Regel, dass der Buildbefehl fehlgeschlagen ist oder keine Ausgabe erzeugt hat. Führen Sie den Buildbefehl manuell aus, um auf Fehler zu überprüfen:

npm run build

Die Bereitstellung überschreitet die Größenbeschränkung.

Wenn die ZIP-Datei 100 MB überschreitet:

• Überprüfen Sie Ihre Buildausgabe auf unnötige Dateien (Source-Maps, Entwicklungs-Assets).
• Konfigurieren Sie den Bundler so, dass Source-Maps in Produktiv-Builds ausgeschlossen werden.
• Verschieben Sie große Binärdateien in Fabric Apps-Speicher.

Es ist kein Remoteendpunkt konfiguriert.

Der Befehl npx rayfin up staticapp deploy setzt eine vorhandene Remote-Bereitstellung voraus. Führen Sie zuerst npx rayfin up aus, um den Remote-Endpunkt zu konfigurieren, und verwenden Sie dann staticapp deploy für nachfolgende Updates.

Verwandte Inhalte

• In Fabric bereitstellen
• Authentifizierung konfigurieren
• Erstellen Ihres ersten Projekts