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

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

A implantação estática não possui endpoint remoto

Sintoma: Ao executar npx rayfin up staticapp deploy, é informado que nenhum endpoint remoto está configurado.

Causa: Implantação apenas estática atualiza uma implantação existente. Ele não consegue provisionar o app remoto inicial.

Solution:

Execute uma implantação completa uma vez:

npx rayfin up

Após a conclusão do provisionamento, use npx rayfin up staticapp deploy para atualizações subsequentes somente estáticas.

Problemas de autenticação

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

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

Causa: A CLI não está logada, ou o ambiente não oferece armazenamento de credenciais apoiado no sistema operacional.

Solution:

Faça login novamente:

npx rayfin login

Para um ambiente de desenvolvimento local restrito sem armazenamento de credenciais, você pode ativar o recurso de respaldo da criptografia:

npx rayfin login --encryption-fallback-enabled

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>

A autenticação do 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:

Confirme se returnOrigin corresponde à origem do seu app, feche o popup e reinicie o fluxo de login.

Fabric SSO informa incompatibilidade de origem

Sintoma: O encaminhamento de SSO do Fabric rejeita a resposta porque a origem dela não corresponde.

Causa:returnOrigin, allowedRedirectUris, ou fabricPortalUrl não corresponde ao ambiente onde o app e o portal do Fabric estão rodando.

Solution:

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

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

initEmbeddedAuth() retorna null

Sintoma: Autenticação embutida não cria uma sessão.

Causa: O SDK não detectou que o app está rodando dentro do Fabric.

Solution:

Inclua ?fabricEmbedded=true na URL do app, ou defina fabricEmbedded: true em FabricAuthOptions.

A autenticação do Fabric indica uma incompatibilidade de estado

Sintoma: O login falha porque o estado da resposta não corresponde ao estado da solicitação.

Causa: A resposta pertence a um fluxo expirado ou a uma tentativa anterior de log-in.

Solution:

Feche o pop-up do Fabric e reinicie o fluxo de login. Não reutilize URLs de callback ou valores de estado de uma tentativa anterior.

Problemas de modelo de dados

A API de dados retorna um erro interno no servidor após a implantação

Sintoma:npx rayfin up ou npx rayfin up db apply tem sucesso, mas a API de dados GraphQL ou REST retorna 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 do GraphQL.

Solution:

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

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

Depois, revise e aplique a mudança de esquema:

npx rayfin up db apply --force

O serviço de dados requer um dialeto

Sintoma: A implantaçã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

Nova entidade não está disponível após a implantação

Sintoma: A implantação é bem-sucedida, mas consultas contra uma entidade nova ou alterada falham ou se comportam como se a entidade não existisse.

Causa: O esquema do banco de dados pode ainda estar se aplicando, ou a interface pode estar usando tipos gerados obsoletos ou configuração em cache.

Solution:

1. Confira a implantação:

   npx rayfin up status
   

2. Aguarde até que a implantação esteja íntegra.

3. Atualize ou reconstrua o frontend.

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

   npx rayfin up db apply
   

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

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.

Questões de gestão secreta

Comando secreto não faz o pedido

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

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

Solution:

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

• Defina um segredo enviando seu valor para o comando:

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

• Defina múltiplos segredos de um arquivo de ambiente:

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

Mantenha os segredos fora do histórico do seu shell e não faça commit de secret.txt nem de .\secrets.env no controle de versão.

Comando secreto devolve permissão negada

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

Causa: O aplicativo não está implantado, ou a conta logada não tem acesso ao workspace Fabric de destino.

Solution:

1. Execute npx rayfin up para provisionar o app.
2. Execute npx rayfin login e selecione uma conta com acesso ao espaço de trabalho.
3. Tente novamente o comando secreto.

Para mais informações, veja Gerenciar segredos de função.

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 folder corresponde à saída da compilação: rayfin.yml

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

Problemas de banco de dados

Falha na aplicação do esquema de banco de dados

Sintoma: Ao executar npx rayfin up db apply ou npx rayfin up db apply --force, ocorre uma falha.

Causa: O esquema no banco de dados remoto e o esquema definido no código do aplicativo não estão sincronizados. O código do aplicativo é a fonte oficial para um aplicativo Fabric.

Não modifique o esquema do banco de dados remoto pelo portal Fabric, SQL Server Management Studio (SSMS), a extensão SQL Server para Visual Studio Code ou outras ferramentas SQL. As seguintes alterações nas colunas de uma entidade de dados não são suportadas:

• Renomeando uma coluna.
• Mudando o tipo de dado de uma coluna.
• Removendo uma coluna.

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

Solution:

1. Reverta quaisquer alterações manuais no esquema remoto do banco de dados para que ele corresponda ao esquema do código do app.

2. Se um agente de codificação fez uma alteração de esquema não suportada no código do app, instrua o agente 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
   

   Caution

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

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

• Referência da CLI
• Aplicar e verificar as alterações no esquema
• Configure URIs de redirecionamento de autenticação.
• Gerencie segredos de funções.
• Implantar no Fabric
• Configurar a autenticação