Alojamento de conteúdos estáticos para aplicações Fabric

O Fabric Apps inclui um serviço de alojamento de conteúdos estáticos que constrói, empacota e serve a sua aplicação frontend juntamente com as APIs backend. Quando o alojamento estático está ativado, a CLI implementa os seus ativos construídos no Fabric e fornece uma URL de alojamento. Pode exigir que os utilizadores iniciem sessão e tenham permissão para ver a aplicação Fabric, ou pode permitir o acesso anónimo aos ativos alojados.

Pré-requisitos

Um projeto Fabric Apps com uma aplicação frontend (por exemplo, React, Vue ou o TypeScript padrão).
Um comando build que produz saída estática (por exemplo, npm run build).

Como funciona o alojamento estático

Quando implementas com alojamento estático ativado, a CLI executa estes passos:

Executa o comando de build configurado (por exemplo, npm run build).
Valida que a pasta de saída existe e contém ficheiros.
Empacota todos os ficheiros num arquivo ZIP comprimido (máximo 100 MB).
Carrega o arquivo para o anfitrião do Fabric Apps.
Aplica a definição de acesso configurado e devolve um URL de alojamento.

Configurar alojamento estático

Adicione uma staticHosting secção sob services no seu ficheiro rayfin/rayfin.yml:

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

Opções de configuração

Opção	Obrigatório	Predefinição	Description
`enabled`	Yes	—	Defina como `true` para ativar o alojamento estático.
`folder`	Yes	—	Pasta de saída contendo ficheiros estáticos construídos, relativamente a `root`.
`root`	No	Raiz do projeto	Diretório raiz do projeto frontend, em relação à raiz do projeto.
`buildCommand`	No	—	Comando shell para executar antes de empacotar (por exemplo, `npm run build`).
`indexDocument`	No	—	Documento predefinido a apresentar para pedidos ao diretório (por exemplo, `index.html`).
`assetAccess`	No	`protected` para implementações não interativas	Controla o acesso a ativos alojados. Utilize `protected` para exigir início de sessão e permissão para ver a aplicação Fabric, ou utilize `public` para permitir acesso anónimo.

Configurar o acesso aos ativos alojados

Defina assetAccess para um dos seguintes valores:

protected- Exige que os utilizadores iniciem sessão e tenham permissão para visualizar a aplicação Fabric antes de poderem recuperar os ativos alojados.
public - Permite que qualquer pessoa com o URL de alojamento recupere ativos alojados sem iniciar sessão.

O alojamento protegido controla o acesso aos ficheiros estáticos que o Fabric Apps serve. Não substitui a autenticação e autorização na sua aplicação ou APIs.

A primeira implementação interativa npx rayfin up pede-te para escolheres uma definição de acesso se assetAccess não estiver configurado. Implementações não interativas usam protected e guardam essa definição em rayfin.yml.

Para alterar a definição de acesso após a implementação, atualize assetAccess, e depois execute uma implementação completa:

npx rayfin up

O npx rayfin up staticapp deploy comando atualiza apenas o conteúdo. Não aplica um novo valor assetAccess.

Exemplo com um diretório frontend separado

Se o seu código frontend está num subdiretório:

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

Esta configuração resolve o caminho de saída para <project-root>/frontend/dist.

Implementação de conteúdo estático

Implantação completa

Quando executa npx rayfin up, o conteúdo estático é implementado automaticamente como parte da implementação full stack:

npx rayfin up

A CLI constrói o teu frontend, empacota a saída e carrega-a juntamente com a configuração do backend. Após a implementação, a CLI imprime a URL de alojamento e grava-a no seu .env.fabric-* ficheiro como VITE_RAYFIN_HOSTING_URL.

Implementação estática autónoma

Use o staticapp deploy subcomando para redistribuir apenas o seu conteúdo estático sem repetir a implementação completa:

npx rayfin up staticapp deploy

Este comando é útil quando só mudaste o código do frontend e queres um ciclo de iteração mais rápido.

Salta a etapa de construção

Se já construiu o seu frontend e quer implementar a saída existente sem reconstruir:

npx rayfin up staticapp deploy --skip-build

Ativar registo detalhado

Mostrar resultados detalhados durante a implantação:

npx rayfin up staticapp deploy --verbose

Configuração da chamada de retorno de autenticação

Quando tanto o alojamento estático como a autenticação estão ativados, o CLI Rayfin regista automaticamente um URI de retorno de autenticação com base no URL do seu alojamento.

Por exemplo, se o seu URL de alojamento for https://example.webapp.com, a CLI adiciona este URI de callback:

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

Não precisa de configurar manualmente o URI de callback de autenticação — a CLI atualiza a configuração e envia-a durante a implementação.

Limites de tamanho de implantação

O arquivo ZIP comprimido não deve exceder 100 MB.
A CLI utiliza compressão máxima para minimizar o tamanho de upload.
Se o resultado da compilação exceder o limite, otimize os seus recursos da seguinte forma:
- Excluindo os mapas de origem das builds de produção.
- Comprimir ou remover imagens e vídeos grandes.
- Mover ficheiros binários para o armazenamento do Fabric Apps em vez de os agrupar.

Exemplo completo

Uma configuração completa rayfin.yml com alojamento estático, autenticação e serviços de dados ativados:

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

Testar localmente

Antes de implementar, verifica se a tua build estática funciona localmente:

Construa o seu frontend:
```
npm run build
```
Verifique se a pasta de saída contém os ficheiros esperados:
```
ls dist
```
Servir os ficheiros compilados com um servidor estático local:
```
npx serve dist
```
Abra o URL impresso pelo servidor e verifique se a sua aplicação carrega corretamente.

Solucionar problemas de implantação

Pasta estática não encontrada

Se a CLI reportar que a pasta estática não existe:

Verifica se o folder caminho em rayfin.yml está correto e relativo a root (ou a raiz do projeto se root não estiver definido).
Assegura-te de que o teu comando build correu com sucesso e produziu a saída no diretório esperado.

Pasta estática vazia

Uma pasta de saída vazia normalmente significa que o comando de compilação falhou ou não produziu saída. Execute manualmente o comando build para verificar erros:

npm run build

A implementação excede o limite de tamanho

Se o ZIP exceder 100 MB:

Reveja o resultado da compilação para detetar ficheiros desnecessários (mapas de origem, recursos de desenvolvimento).
Configura o teu bundler para excluir os mapas de origem em builds de produção.
Mover ficheiros binários grandes para o armazenamento do Fabric Apps.

Nenhum endpoint remoto está configurado

O npx rayfin up staticapp deploy comando requer uma implantação remota já existente. Executa npx rayfin up primeiro para configurar o endpoint remoto e depois usa staticapp deploy para as atualizações seguintes.

Comentários

Esta página foi útil?

Última atualização a 2026-09-29