Resolver problemas de aplicações do Fabric

Diagnostice problemas comuns quando desenvolve ou implementa um projeto de Fabric Apps. Este artigo aborda questões relacionadas com início de sessão, serviços locais, alterações de esquema, alojamento estático e a CLI.

Problemas de implementação

A implementação falha com erro 401 ou 403

Sintoma: Executar npx rayfin up devolve um erro de autenticação.

Causa: A tua sessão de autenticação expirou ou não estás logado.

Solution:

Reautentique e tente novamente a implementação:

npx rayfin login
npx rayfin up

A implementação estática excede o limite de tamanho

Sintoma: A implementação de conteúdo estático falha devido a um erro de limite de tamanho.

Causa: O arquivo comprimido ultrapassa os 100 MB.

Solution:

Reduzir o tamanho do resultado da compilação através de:

  • Excluindo os mapas de origem das builds de produção
  • Otimização ou remoção de imagens e vídeos grandes
  • Mover ficheiros binários para armazenamento em vez de os agrupar
  • Verifique se a configuração do seu empacotador exclui artefactos de desenvolvimento

A implementação estática não tem endpoint remoto

Sintoma: Ao executar npx rayfin up staticapp deploy, é apresentada a mensagem de que nenhum endpoint remoto está configurado.

Causa: A implementação apenas estática atualiza uma implementação existente. Não consegue provisionar a aplicação remota inicial.

Solution:

Efetue uma implantação completa uma única vez:

npx rayfin up

Depois de concluído o aprovisionamento, use npx rayfin up staticapp deploy para atualizações subsequentes exclusivamente estáticas.

Problemas de autenticação

Falha na aquisição do token de autenticação

Sintoma:npx rayfin login ou outro comando CLI autenticado indica Failed to acquire authentication token ou um erro de armazenamento de credenciais.

Causa: A CLI não tem sessão iniciada, ou o ambiente não fornece armazenamento de credenciais suportado pelo sistema operativo.

Solution:

Inicie sessão novamente:

npx rayfin login

Para um ambiente de desenvolvimento local restrito sem armazenamento de credenciais, pode ativar o recurso de encriptação:

npx rayfin login --encryption-fallback-enabled

Warning

O recurso de contingência da encriptação armazena a cache de tokens em texto simples. Use-o apenas num ambiente de desenvolvimento de confiança. Não o uses em produção ou em ambientes partilhados.

A sessão não é mantida após o início de sessão

Sintoma: Os utilizadores são desconectados imediatamente após a autenticação.

Causa: O cliente não está configurado com a URL base correta nem a chave publicável.

Solution:

Verifica se a RayfinClient configuração corresponde ao teu backend:

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

Pop-up do Fabric SSO bloqueado

Sintoma: O navegador bloqueia a janela do portal de Fabric durante o início de sessão.

Causa:ensureSignedInWithFabric() não foi chamado a partir de um processador de gestos do utilizador.

Solution:

Chame a função a partir de um gestor de eventos síncrono:

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

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

A autenticação Fabric expira

Sintoma: A autenticação Fabric falha após cinco minutos.

Causa: O portal Fabric não retornou o código de transferência antes de o fluxo expirar.

Solution:

Confirma que returnOrigin corresponde à origem da tua aplicação, fecha a janela pop-up e reinicia o fluxo de início de sessão.

Fabric SSO reporta uma incompatibilidade de origem

Sintoma: A transferência SSO do Fabric rejeita a resposta porque a sua origem não corresponde.

Causa:returnOrigin, allowedRedirectUris, ou fabricPortalUrl não corresponde ao ambiente onde a aplicação e o portal do Fabric estão a correr.

Solution:

  1. Defina returnOrigin como a origem simples da tua aplicação.
  2. Confirme que a origem aparece em services.auth.allowedRedirectUris.
  3. Use o URL do portal Fabric para o ambiente correto de produção, pré-visualização ou desenvolvimento.
  4. Execute npx rayfin up depois de alterar rayfin.yml.

Para mais informações, consulte Configurar URIs de redirecionamento de autenticação.

initEmbeddedAuth() retorna null

Sintoma: A autenticação incorporada não cria uma sessão.

Causa: O SDK não detetou que a aplicação estava a correr dentro do Fabric.

Solution:

Inclua ?fabricEmbedded=true no URL da aplicação ou defina fabricEmbedded: true em FabricAuthOptions.

A autenticação Fabric reporta uma incompatibilidade de estado

Sintoma: O início de sessão falha porque o estado da resposta não coincide com o estado do pedido.

Causa: A resposta pertence a um fluxo expirado ou a uma tentativa anterior de início de sessão.

Solution:

Feche a janela de pop-up do Fabric e reinicie o processo de início de sessão. Não reutilize URLs de callback ou valores de estado de uma tentativa anterior.

Problemas com modelos de dados

A API de dados devolve um erro interno do servidor após a implementação

Sintoma:npx rayfin up ou npx rayfin up db apply consegue, mas a API de dados GraphQL ou REST devolve um erro interno do servidor.

Causa: No Microsoft SQL Server, um @text() campo sem max gera uma NVARCHAR(MAX) coluna, o que pode impedir a geração de esquemas GraphQL.

Solution:

Adicione um comprimento máximo explícito a cada campo de texto afetado:

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

Depois revê e aplica a alteração do esquema:

npx rayfin up db apply --force

Atenção

Revise todas as operações reportadas antes de usar --force. A opção pode causar perda permanente de dados.

O serviço de dados requer um dialeto

Sintoma: A implementação falha com uma resposta HTTP 400 e reporta Dialect is required when Data module is enabled.

Causa:services.data.enabled é true, mas rayfin.yml não define um dialeto.

Solution:

Configurar Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

A nova entidade não está disponível após a implementação

Sintoma: A implementação tem sucesso, mas as consultas contra uma entidade nova ou alterada falham ou comportam-se como se a entidade não existisse.

Causa: O esquema da base de dados pode ainda estar a aplicar-se, ou a interface pode estar a usar tipos gerados obsoletos ou configuração em cache.

Solution:

  1. Verifique a implementação:

    npx rayfin up status

  2. Aguarde até a implementação estar operacional.

  3. Atualizar ou reconstruir o frontend.

  4. Se a entidade ainda falhar, aplicar o esquema explicitamente:

    npx rayfin up db apply

Para o fluxo de trabalho completo, consulte Aplicar e verificar alterações de esquema.

Relações que não aparecem na API

Sintoma: Os campos de entidades relacionadas não estão disponíveis ao fazer consultas.

Causa: O decorador de navegação está em falta ou o esquema não foi aplicado.

Solution:

  1. Verifique se os decoradores de relacionamentos estão presentes:

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

  2. Reaplique o esquema.

Política de autorização não funciona

Sintoma: Os utilizadores podem aceder a registos que não deveriam ver.

Causa: A expressão da apólice está incorreta ou os nomes das reclamações não coincidem.

Solution:

  1. Verifique se a apólice utiliza nomes de reclamação corretos (sub, email, role):

    policy: (claims, item) => claims.sub.eq(item.user_id)

  2. Regista o JWT decodificado para verificar se os valores das reclamações correspondem ao teu código.

Respostas obsoletas da API

Sintoma: O frontend devolve formas de dados desatualizadas após alterações no esquema.

Causa: A configuração gerada é armazenada em cache.

Solution:

  1. Pare o backend.

  2. Apague o .temp/ diretório em rayfin/:

    rm -rf rayfin/.temp/

  3. Reinicie os serviços e reaplique o esquema.

Problemas da CLI

Comando não encontrado

Sintoma: Executar npx rayfin devolve a mensagem "command not found."

Causa: O CLI não está instalado ou o npm não está no teu PATH.

Solution:

  1. Verifique Node.js e npm estão instalados:

    node --version
npm --version

  2. Reinstalar dependências:

    npm install

Incompatibilidade de versões da CLI

Sintoma: Os comandos CLI falham com erros inesperados após a atualização.

Causa: A versão da CLI em cache está desatualizada.

Solution:

Atualização e reinstalação:

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

Incompatibilidade entre a versão global e a versão local da CLI

Sintoma: Os comandos CLI falham com erros inesperados entre projetos.

Causa: Instalação global e local das versões CLI e elas não coincidem.

Solução: Valide a versão local npm list @microsoft/rayfin-cli. Isto mostra a versão no node_modules do seu projeto atual. Verifique a versão global npm list -g @microsoft/rayfin-cli. Isto mostra a versão instalada em todo o sistema. Use npm uninstall -g com o pacote Rayfin CLI para remover a versão global e utilizar as versões locais.

Questões de gestão secreta

O comando secreto não solicita confirmação

Sintoma:npx rayfin secret set <NAME> Sai sem indicar um valor.

Causa: A entrada padrão não é um terminal interativo, ou a CI variável de ambiente está definida para true. O comando utiliza um prompt interativo mascarado.

Solution:

Use uma das seguintes alternativas suportadas para criação de segredos não interativas:

  • Defina um segredo enviando o seu valor para o comando:

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

  • Defina múltiplos segredos a partir de um ficheiro de ambiente:

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

Mantenha os valores secretos fora do histórico da sua shell e não faça commit de secret.txt nem de .\secrets.env no controlo de versões.

Comando secreto devolve permissão negada

Sintoma:npx rayfin secret set ou npx rayfin secret list devolve um erro de permissão.

Causa: A aplicação não está implantada, ou a conta com sessão iniciada não tem acesso ao espaço de trabalho do Fabric de destino.

Solution:

  1. Executa npx rayfin up para aprovisionar a aplicação.
  2. Executa npx rayfin login e seleciona uma conta com acesso ao espaço de trabalho.
  3. Tenta novamente o comando secreto.

Para mais informações, consulte Gerir segredos de função.

Problemas de montagem e embalagem

O comando de build falha

Sintoma: A implementação de alojamento estático falha porque o comando de compilação não produziu saída.

Causa: Erros de compilação ou comandos de compilação mal configurados.

Solution:

  1. Executa manualmente o comando de compilação:

    npm run build

  2. Corrija quaisquer erros reportados.

  3. Verifica se a pasta de saída contém ficheiros.

Pasta estática vazia

Sintoma: A implementação estática falha com o erro de "pasta vazia".

Causa: O caminho configurado folder está incorreto.

Solution:

Verifica se o folder caminho corresponde rayfin.yml ao resultado da tua build:

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

Problemas com bases de dados

A aplicação do esquema da base de dados falha

Sintoma: A execução de npx rayfin up db apply ou npx rayfin up db apply --force falha.

Causa: O esquema na base de dados remota e o esquema definido no código da aplicação estão fora de sincronização. O código da aplicação é a fonte da verdade para uma aplicação Fabric.

Não modifique o esquema da base de dados remota através do portal Fabric, SQL Server Management Studio (SSMS), da extensão SQL Server para Visual Studio Code ou de outras ferramentas SQL. As seguintes alterações às colunas numa entidade de dados não são suportadas:

  • Renomear uma coluna.
  • Alterar o tipo de dado de uma coluna.
  • Remover uma coluna.

A adição de uma coluna é suportada. Remover ou alterar uma coluna existente pode quebrar a aplicação e a sua implementação no Fabric.

Solution:

  1. Reverta quaisquer alterações manuais ao esquema da base de dados remota para que corresponda ao esquema do código da aplicação.

  2. Se um agente de codificação fez uma alteração de esquema não suportada no código da aplicação, instrua-o a reverter essa alteração.

  3. Execute novamente o comando schema apply:

    npx rayfin up db apply

    Para uma renomeação de coluna, --force pode permitir que a atualização do esquema seja concluída:

    npx rayfin up db apply --force

    Atenção

    O uso --force pode causar perda permanente de dados. Revise as operações propostas e confirme que aceita o risco de perda de dados antes de prosseguir.

Ligação recusada

Sintoma: As operações de dados falham devido a erros de ligação.

Causa: O contentor da base de dados não está a correr ou as verificações de saúde falharam.

Solution:

  1. Rever registos de contentores:

    docker compose logs -f

  2. Reiniciar os serviços.

Perda de dados após o reinício

Sintoma: Os dados desaparecem após a interrupção e início dos serviços.

Causa: Os volumes foram eliminados com --purge.

Solution:

Utilize --down em vez de --purge para preservar os dados.

Limitações conhecidas

Para limitações atuais e soluções recomendadas, veja:

  • count() não está disponível no cliente fluent GraphQL — use results.length.
  • As relações muitos-para-muitos não são suportadas—use uma entidade de associação explícita.
  • Os objetos de sessão são opacos — verifique as propriedades isAuthenticated ou user.
  • Depois de ativar ou desativar a autenticação em rayfin.yml, reinicia o backend.

Obter ajuda

Se o problema persistir:

  1. Consulte a documentação Fabric Apps.
  2. Verifique o repositório GitHub para problemas conhecidos.
  3. Faça um relatório de bugs com registos detalhados e passos de reprodução.

Conteúdo relacionado

  • Última atualização a