Hosting di contenuto statico per app di Fabric

Fabric App include un servizio di hosting di contenuti statici che compila, crea pacchetti e gestisce l'applicazione front-end insieme alle API back-end. Quando l'hosting statico è abilitato, la CLI distribuisce i tuoi asset costruiti su Fabric e fornisce un URL di hosting. Puoi richiedere agli utenti di accedere e avere il permesso di visualizzare l'app Fabric, oppure puoi consentire l'accesso anonimo agli asset ospitati.

Prerequisiti

Progetto app Fabric con un'applicazione front-end ( ad esempio React, Vue o vanilla TypeScript).
Comando di compilazione che produce output statico, ad esempio npm run build.

Funzionamento dell'hosting statico

Quando si esegue la distribuzione con hosting statico abilitato, l'interfaccia della riga di comando esegue questi passaggi:

Esegue il comando di compilazione configurato, ad esempio npm run build.
Verifica che la cartella di output esista e contenga file.
Inserisce tutti i file in un archivio ZIP compresso (massimo 100 MB).
Carica l'archivio nell'host app di Fabric.
Applica l'impostazione di accesso configurato e restituisce un URL di hosting.

Configurare l'hosting statico

Aggiungere una sezione staticHosting sotto services nel file rayfin/rayfin.yml:

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

Opzioni di configurazione

Opzione	Obbligatorio	Impostazione predefinita	Description
`enabled`	Sì	—	Impostalo su `true` per abilitare l'hosting statico.
`folder`	Sì	—	Cartella di output contenente i file statici generati, relativa a `root`.
`root`	No	Radice del progetto	Directory principale del progetto front-end, rispetto alla radice del progetto.
`buildCommand`	No	—	Comando Shell da eseguire prima della creazione del pacchetto , ad esempio `npm run build`.
`indexDocument`	No	—	Documento predefinito da gestire per le richieste di directory , ad esempio `index.html`.
`assetAccess`	No	`protected` per implementazioni non interattive	Controlla l'accesso agli asset ospitati. Usare `protected` per richiedere l'accesso e l'autorizzazione per visualizzare l'app Fabric, oppure usare `public` per consentire l'accesso anonimo.

Configura l'accesso agli asset ospitati

Imposta assetAccess su uno di questi valori:

protected- Richiede agli utenti di accedere e avere il permesso di visualizzare l'app Fabric prima di poter recuperare gli asset ospitati.
public - Permette a chiunque abbia l'URL di hosting di recuperare asset ospitati senza effettuare l'accesso.

L'hosting protetto controlla l'accesso ai file statici che le app Fabric servono. Non sostituisce l'autenticazione e l'autorizzazione nella tua applicazione o nelle API.

La prima distribuzione interattiva npx rayfin up richiede di scegliere un'impostazione di accesso se assetAccess non è configurata. Le implementazioni non interattive usano protected e salvano quell'impostazione su rayfin.yml.

Per modificare l'impostazione di accesso dopo il deployment, aggiorna assetAccess, e poi esegui un deployment completo:

npx rayfin up

Il npx rayfin up staticapp deploy comando aggiorna solo il contenuto. Non applica un nuovo assetAccess valore.

Esempio con una directory front-end separata

Se il codice front-end si trova in una sottodirectory:

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

Questa configurazione determina il percorso di output come <project-root>/frontend/dist.

Distribuire contenuto statico

Distribuzione completa

Quando si esegue npx rayfin up, il contenuto statico viene distribuito automaticamente come parte della distribuzione completa dello stack:

npx rayfin up

La CLI genera il frontend, impacchetta l'output e lo carica insieme alla configurazione del backend. Dopo la distribuzione, la CLI visualizza l'URL di hosting e lo scrive nel tuo file .env.fabric-* come VITE_RAYFIN_HOSTING_URL.

Distribuzione statica autonoma

Usare il staticapp deploy sottocomando per ridistribuire solo il contenuto statico senza eseguire nuovamente la distribuzione completa:

npx rayfin up staticapp deploy

Questo comando è utile quando è stato modificato solo il codice front-end e si vuole un ciclo di iterazione più veloce.

Ignora la fase di compilazione

Se il front-end è già stato compilato e si vuole distribuire l'output esistente senza ricompilare:

npx rayfin up staticapp deploy --skip-build

Abilitare la registrazione dettagliata

Mostra output dettagliato durante la distribuzione:

npx rayfin up staticapp deploy --verbose

Configurazione del callback di autenticazione

Quando l'hosting statico e l'autenticazione sono abilitati, l'interfaccia della riga di comando di Rayfin registra automaticamente un URI di callback di autenticazione in base all'URL di hosting.

Ad esempio, se l'URL di hosting è https://example.webapp.com, l'interfaccia della riga di comando aggiunge questo URI di callback:

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

Non è necessario configurare manualmente l'URI di callback di autenticazione. L'interfaccia della riga di comando aggiorna la configurazione ed esegue il push durante la distribuzione.

Limiti di dimensione della distribuzione

L'archivio ZIP compresso non deve superare i 100 MB.
L'interfaccia della riga di comando usa la compressione massima per ridurre al minimo le dimensioni di caricamento.
Se l'output di compilazione supera il limite, ottimizza le risorse in questo modo:
- Esclusione delle source map dalle build di produzione.
- Compressione o rimozione di immagini e video di grandi dimensioni.
- Spostare i file binari nell'archiviazione delle app di Fabric invece di includerli nel bundle.

Esempio completo

Configurazione completa rayfin.yml con hosting statico, autenticazione e servizi dati abilitati:

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

Testare localmente

Prima della distribuzione, verificare che la compilazione statica funzioni localmente:

Compilare il front-end:
```
npm run build
```
Verificare che la cartella di output contenga i file previsti:
```
ls dist
```
Gestire i file compilati con un server statico locale:
```
npx serve dist
```
Aprire l'URL stampato dal server e verificare che l'applicazione venga caricata correttamente.

Risolvere i problemi relativi alla distribuzione

Cartella statica non trovata

Se l'interfaccia della riga di comando segnala che la cartella statica non esiste:

Verificare che il folder percorso in rayfin.yml sia corretto e relativo a root (o alla radice del progetto se root non è impostato).
Verificare che il comando di compilazione sia stato eseguito correttamente e prodotto l'output nella directory prevista.

Cartella statica vuota

Una cartella di output vuota indica in genere che il comando di compilazione non è riuscito o non ha prodotto l'output. Eseguire manualmente il comando di compilazione per verificare la presenza di errori:

npm run build

La distribuzione supera il limite di dimensioni

Se il file ZIP supera i 100 MB:

Esaminare l'output di compilazione per i file non necessari (mappe di origine, asset di sviluppo).
Configurare il bundler per escludere le mappe di origine nelle compilazioni di produzione.
Spostare file binari di grandi dimensioni nell'archiviazione di app di Fabric.

Nessun endpoint remoto configurato

Il npx rayfin up staticapp deploy comando richiede una distribuzione remota esistente. Eseguire npx rayfin up prima di tutto per configurare l'endpoint remoto, quindi usare staticapp deploy per gli aggiornamenti successivi.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-09-29