Solucionar problemas de aplicativos Fabric

Diagnosticar problemas comuns ao desenvolver ou implantar um projeto de aplicativos Fabric. Este artigo aborda problemas com entrada, serviços locais, alterações de esquema, hospedagem estática e CLI.

Problemas de implantação

A implantação falha com erro 401 ou 403

Sintoma: A execução npx rayfin up retorna um erro de autenticação.

Causa: Sua sessão de autenticação expirou ou você não está conectado.

Solution:

Autentique-se novamente e tente a implantação outra vez:

npx rayfin login
npx rayfin up

Relatórios de aplicação do banco de dados indicam alterações destrutivas

Sintoma: Executando npx rayfin up db apply blocos com um aviso sobre a perda de dados.

Causa: A CLI detectou alterações de esquema que poderiam excluir dados (descartando colunas, renomeando tabelas).

Solution:

Examine cuidadosamente as operações listadas. Se você aceitar a perda de dados, use --force:

npx rayfin up db apply --force

Caution

O uso --force pode causar perda permanente de dados. Verifique as operações antes de prosseguir.

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

Sintoma: A implantação de conteúdo estático falha com um erro de limite de tamanho.

Causa: O arquivo compactado excede 100 MB.

Solution:

Reduza o tamanho da saída do build em:

  • Excluindo mapas de código-fonte das compilações de produção
  • Otimizando ou removendo vídeos e imagens grandes
  • Movendo arquivos binários para o armazenamento em vez de agrupar-os
  • Verificar se a configuração do empacotador exclui artefatos de desenvolvimento

Problemas de autenticação

Sessão não é mantida após fazer login

Sintoma: Os usuários são desconscritos imediatamente após a autenticação.

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

Solution:

Verifique se a RayfinClient configuração corresponde ao back-end:

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 SSO do Fabric bloqueado

Symptom: Browser bloqueia a janela do portal Fabric durante a entrada.

Causa:ensureSignedInWithFabric() não foi invocado em um manipulador de gesto do usuário.

Solution:

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

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

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

Problemas de modelo de dados

Relações que não aparecem na API

Sintoma: Os campos de entidade relacionados não estão disponíveis durante a consulta.

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

Solution:

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

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

  2. Reaplicar o esquema.

A política de autorização não está funcionando

Sintoma: Os usuários podem acessar registros que não devem ver.

Causa: A expressão de política está incorreta ou os nomes de declaração não correspondem.

Solution:

  1. Verifique se a política usa nomes de declaração corretos (sub, email, role):

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

  2. Registre o JWT decodificado para verificar se os valores de declaração correspondem ao seu código.

Respostas de API obsoletas

Sintoma: O front-end retorna formas de dados desatualizadas após alterações de esquema.

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

Solution:

  1. Interrompa o servidor.

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

    rm -rf rayfin/.temp/

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

Problemas da CLI

Comando não encontrado

Sintoma: A execução npx rayfin retorna "comando não encontrado".

Causa: A CLI não está instalada ou o npm não está em seu PATH.

Solution:

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

    node --version
npm --version

  2. Reinstalar dependências:

    npm install

Incompatibilidade de versão da CLI

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

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

Solution:

Atualizar e reinstalar:

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

Incompatibilidade entre versões global e local da CLI

Sintoma: Os comandos da CLI falham com erros inesperados em projetos.

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

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

Problemas de build e empacotamento

Falha no comando build

Sintoma: A implantação de hospedagem estática falha porque o comando de build não produziu nenhuma saída.

Causa: Erros de build ou comando de build mal configurado.

Solution:

  1. Execute o comando de build manualmente:

    npm run build

  2. Corrija os erros relatados.

  3. Verifique se a pasta de saída contém arquivos.

Pasta estática vazia

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

Causa: O caminho configurado folder está incorreto.

Solution:

Verifique se o caminho em rayfin.yml corresponde à saída da compilação: folder

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

Problemas de banco de dados

Conexão recusada

Sintoma: As operações de dados falham com erros de conexão.

Causa: O contêiner de banco de dados não está em execução ou as verificações de integridade falharam.

Solution:

  1. Examine os logs de contêineres:

    docker compose logs -f

  2. Reinicie os serviços.

Perda de dados após a reinicialização

Sintoma: Os dados desaparecem depois de parar e iniciar serviços.

Causa: Os volumes foram excluídos com --purge.

Solution:

Use --down em vez de --purge para preservar dados.

Limitações conhecidas

Para obter as limitações atuais e as soluções alternativas recomendadas, consulte:

  • count() não está disponível no cliente Fluent GraphQL — use results.length.
  • Não há suporte para relações muitos para muitos: use uma entidade de junção explícita.
  • Os objetos de sessão são opacos—verifique as propriedades isAuthenticated ou user.
  • Depois de habilitar ou desabilitar a autenticação no rayfin.yml, reinicie o backend.

Obter ajuda

Se o problema persistir:

  1. Examine a documentação Fabric Apps.
  2. Verifique o GitHub repositório para problemas conhecidos.
  3. Envie um relatório de erro com logs detalhados e etapas de reprodução.

Conteúdo relacionado

  • Last updated on