Solución de problemas de aplicaciones de Fabric

Diagnostique problemas comunes al desarrollar o implementar un proyecto de Fabric Apps. En este artículo se tratan los problemas relacionados con el inicio de sesión, los servicios locales, los cambios de esquema, el hospedaje estático y la CLI.

Problemas de implementación

La implementación falla con el error 401 o 403

Síntoma: La ejecución npx rayfin up devuelve un error de autenticación.

Causa: Su sesión de autenticación ha caducado o no ha iniciado sesión.

Solution:

Vuelva a autenticar y vuelva a intentar la implementación:

npx rayfin login
npx rayfin up

La implementación estática supera el límite de tamaño

Síntoma: Se produce un error de implementación de contenido estático con un error de límite de tamaño.

Causa: El archivo comprimido supera los 100 MB.

Solution:

Reduzca el tamaño de salida de la compilación por:

  • Excluir los mapas de código fuente de las compilaciones de producción
  • Optimización o eliminación de imágenes y vídeos grandes
  • Mover archivos binarios al almacenamiento en lugar de agruparlos
  • Verificar que la configuración del empaquetador excluya los artefactos de desarrollo

El despliegue estático no tiene un punto final remoto

Síntoma: Al ejecutar npx rayfin up staticapp deploy, se indica que no hay ningún endpoint remoto configurado.

Causa: El despliegue solo estático actualiza un despliegue existente. No puede aprovisionar la aplicación remota inicial.

Solution:

Ejecuta un despliegue completo una vez:

npx rayfin up

Una vez completado el aprovisionamiento, use npx rayfin up staticapp deploy para posteriores actualizaciones únicamente estáticas.

Problemas de autenticación.

Falla la adquisición de tokens de autenticación

Síntoma:npx rayfin login u otro comando CLI autenticado muestra Failed to acquire authentication token o un error de almacenamiento de credenciales.

Causa: La CLI no está conectada, o el entorno no proporciona almacenamiento de credenciales respaldado por el sistema operativo.

Solution:

Inicia sesión de nuevo:

npx rayfin login

Para un entorno de desarrollo local restringido sin almacenamiento de credenciales, puedes activar el sistema de respaldo de cifrado:

npx rayfin login --encryption-fallback-enabled

Warning

La alternativa de cifrado almacena la caché de tokens en texto plano. Úsalo solo en un entorno de desarrollo confiable. No lo uses en producción ni en entornos compartidos.

La sesión no se mantiene después de iniciar sesión

Síntoma: Los usuarios se desconectan inmediatamente después de autenticarse.

Causa: El cliente no está configurado con la dirección URL base correcta ni la clave que se puede publicar.

Solution:

Compruebe que la configuración RayfinClient coincide con su backend:

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

Ventana emergente de SSO de Fabric bloqueada

Symptom: Browser bloquea la ventana del portal de Fabric durante el inicio de sesión.

Causa:ensureSignedInWithFabric() no se invocó desde un gestor de gestos del usuario.

Solution:

Llame a la función desde un controlador de eventos sincrónico:

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

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

La autenticación Fabric expira

Síntoma: La autenticación Fabric falla tras cinco minutos.

Causa: El portal de Fabric no devolvió el código de transferencia antes de que expirara el flujo.

Solution:

Confirma que coincide returnOrigin con el origen de tu app, cierra la ventana emergente y vuelve a iniciar sesión.

Fabric SSO informa de una descoordinación de origen

Síntoma: La transferencia SSO de Fabric rechaza la respuesta porque su origen no coincide.

Causa:returnOrigin, allowedRedirectUris, o fabricPortalUrl no coincide con el entorno donde están ejecutando la app y el portal de Fabric.

Solution:

  1. Configura returnOrigin con el origen base de tu aplicación.
  2. Confirma que el origen aparece en services.auth.allowedRedirectUris.
  3. Utiliza la URL del portal Fabric para el entorno correcto de producción, vista previa o desarrollo.
  4. Ejecuta npx rayfin up después de cambiar rayfin.yml.

Para más información, consulte Configurar URIs de redirección de autenticación.

initEmbeddedAuth() devuelve null.

Síntoma: La autenticación incrustada no crea una sesión.

Causa: El SDK no detectó que la app se ejecuta dentro de Fabric.

Solution:

Incluye ?fabricEmbedded=true en la URL de la app o establece fabricEmbedded: true en FabricAuthOptions.

La autenticación de Fabric informa de una discordancia de estado

Síntoma: El inicio de sesión falla porque el estado de respuesta no coincide con el estado de la solicitud.

Causa: La respuesta corresponde a un flujo caducado o a un intento previo de inicio de sesión.

Solution:

Cierra la ventana emergente de Fabric y reinicia el flujo de inicio de sesión. No reutilices URLs de callback ni valores de estado de un intento anterior.

Problemas del modelo de datos

La API de datos devuelve un error interno del servidor tras el despliegue

Síntoma:npx rayfin up o npx rayfin up db apply tiene éxito, pero la API de datos GraphQL o REST devuelve un error interno del servidor.

Causa: En Microsoft SQL Server, un campo @text() sin max genera una columna NVARCHAR(MAX), lo que puede impedir la generación del esquema de GraphQL.

Solution:

Añade una longitud máxima explícita a cada campo de texto afectado:

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

Luego revisa y aplica el cambio de esquema:

npx rayfin up db apply --force

Caution

Revisa todas las operaciones reportadas antes de usar --force. La opción puede causar una pérdida permanente de datos.

El servicio de datos requiere un dialecto

Síntoma: El despliegue falla con una respuesta HTTP 400 y reporta Dialect is required when Data module is enabled.

Causa:services.data.enabled es true, pero rayfin.yml no define un dialecto.

Solution:

Configurar Microsoft SQL Server:

services:
  data:
    enabled: true
    dialect: mssql

La nueva entidad no está disponible tras el despliegue

Síntoma: El despliegue tiene éxito, pero las consultas contra una entidad nueva o modificada fallan o se comportan como si la entidad no existiera.

Causa: El esquema de la base de datos podría seguir aplicándose, o el frontend podría estar usando tipos generados obsoletos o una configuración en caché.

Solution:

  1. Consulta el despliegue:

    npx rayfin up status

  2. Espera hasta que el despliegue esté operativo.

  3. Actualiza o reconstruye el front-end.

  4. Si la entidad sigue fallando, aplica el esquema explícitamente:

    npx rayfin up db apply

Para el flujo de trabajo completo, consulte Aplicar y verificar cambios en el esquema.

Relaciones que no aparecen en la API

Síntoma: Los campos de entidad relacionados no están disponibles al realizar consultas.

Causa: Falta el decorador de navegación o no se aplicó el esquema.

Solution:

  1. Compruebe que los decoradores de relaciones están presentes:

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

  2. Vuelva a aplicar el esquema.

La directiva de autorización no funciona

Síntoma: Los usuarios pueden acceder a los registros que no deberían ver.

Causa: La expresión de directiva es incorrecta o los nombres de las notificaciones no coinciden.

Solution:

  1. Compruebe que la directiva usa nombres de notificación correctos (sub, email, role):

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

  2. Registra el JWT decodificado para verificar que los valores de las declaraciones coincidan con los de tu código.

Respuestas de API obsoletas

Síntoma: Front-end devuelve formas de datos obsoletas después de los cambios de esquema.

Causa: La configuración generada se almacena en caché.

Solution:

  1. Detenga el backend.

  2. Elimine el .temp/ directorio en rayfin/:

    rm -rf rayfin/.temp/

  3. Reinicie los servicios y vuelva a aplicar el esquema.

Problemas de la CLI

No se encontró el comando

Síntoma: La ejecución npx rayfin devuelve "comando no encontrado".

Causa: La CLI no está instalada o npm no está en la ruta de acceso.

Solution:

  1. Compruebe que Node.js y npm están instalados:

    node --version
npm --version

  2. Reinstale las dependencias:

    npm install

Incompatibilidad de versión de la CLI

Síntoma: Los comandos de la CLI producen errores inesperados después de la actualización.

Causa: La versión de la CLI almacenada en caché está obsoleta.

Solution:

Actualice y vuelva a instalar:

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

Discrepancia entre la versión global y la versión local de la CLI

Síntoma: Los comandos de la CLI producen errores inesperados en los proyectos.

Causa: Instalación global y local de las versiones de la CLI y no coinciden.

Solución: Validar la versión local npm list @microsoft/rayfin-cli. Esto muestra la versión de la node_modules del proyecto actual. Compruebe la versión global npm list -g @microsoft/rayfin-cli. Esto muestra la versión instalada en todo el sistema. Utiliza npm uninstall -g con el paquete Rayfin CLI para eliminar la versión global y usar tus versiones locales.

Cuestiones de gestión secreta

El comando secreto no solicita confirmación

Síntoma:npx rayfin secret set <NAME> Sale sin que se indique un valor.

Causa: La entrada estándar no es un terminal interactivo, o la CI variable de entorno está configurada como true. El comando utiliza un prompt interactivo enmascarado.

Solution:

Utiliza una de las siguientes alternativas soportadas para la creación de secretos no interactivos:

  • Establecer un secreto redireccionando su valor al comando:

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

  • Establece varios secretos de un archivo de entorno:

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

Mantén los valores confidenciales fuera del historial de tu shell y no confirmes secret.txt ni .\secrets.env en el control de versiones.

El comando secreto devuelve un error de permiso denegado

Síntoma:npx rayfin secret set o npx rayfin secret list devuelve un error de permiso.

Causa: La app no está desplegada, o la cuenta iniciada no tiene acceso al espacio de trabajo de Fabric de destino.

Solution:

  1. Ejecuta npx rayfin up para aprovisionar la aplicación.
  2. Ejecuta npx rayfin login y selecciona una cuenta con acceso al espacio de trabajo.
  3. Vuelve a intentar el comando secreto.

Para más información, consulta Administrar secretos de funciones.

Problemas de compilación y empaquetado

Error en el comando de compilación

Síntoma: Se produce un error en la implementación de hospedaje estático porque el comando de compilación no produjo ninguna salida.

Causa: Errores de compilación o comando de compilación mal configurado.

Solution:

  1. Ejecute el comando de compilación manualmente:

    npm run build

  2. Corrija los errores notificados.

  3. Compruebe que la carpeta de salida contiene archivos.

Carpeta estática vacía

Síntoma: El despliegue estático falla con el mensaje de error «carpeta vacía».

Causa: La ruta de acceso configurada folder es incorrecta.

Solution:

Compruebe que la ruta de acceso de folder coincide con la salida de compilación de rayfin.yml:

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

Problemas de la base de datos

Falla la aplicación del esquema de base de datos

Síntoma: Ejecutar npx rayfin up db apply o npx rayfin up db apply --force falla.

Causa: El esquema de la base de datos remota y el esquema definido en el código de la aplicación no están sincronizados. El código de la aplicación es la fuente de referencia para una aplicación de Fabric.

No modifiques el esquema remoto de la base de datos a través del portal Fabric, SQL Server Management Studio (SSMS), la extensión SQL Server para Visual Studio Code u otras herramientas SQL. No se soportan los siguientes cambios en las columnas de una entidad de datos:

  • Cambiar el nombre de una columna.
  • Cambiar el tipo de dato de una columna.
  • Eliminar una columna.

Se permite añadir una columna. Eliminar o modificar una columna existente puede romper la aplicación y su despliegue en Fabric.

Solution:

  1. Revertir cualquier cambio manual en el esquema remoto de la base de datos para que coincida con el esquema del código de la app.

  2. Si un agente codificador ha realizado un cambio de esquema no soportado en el código de la app, indícale que revierta ese cambio.

  3. Ejecuta de nuevo el comando schema apply:

    npx rayfin up db apply

    Para un cambio de nombre de columna, --force podría permitir que la actualización del esquema se complete:

    npx rayfin up db apply --force

    Caution

    El uso --force puede provocar una pérdida de datos permanente. Revisa las operaciones propuestas y confirma que aceptas el riesgo de pérdida de datos antes de continuar.

Conexión rechazada

Síntoma: Las operaciones de datos fallan con errores de conexión.

Causa: El contenedor de base de datos no se está ejecutando o se han producido errores en las comprobaciones de estado.

Solution:

  1. Revise los registros de contenedor:

    docker compose logs -f

  2. Reinicie los servicios.

Pérdida de datos después del reinicio

Síntoma: Los datos desaparecen después de detener e iniciar los servicios.

Causa: Los volúmenes se eliminaron con --purge.

Solution:

Use --down en lugar de --purge para conservar los datos.

Limitaciones conocidas

Para conocer las limitaciones actuales y las soluciones alternativas recomendadas, consulte:

  • count() no está disponible en el cliente fluent GraphQL: use results.length.
  • No se admiten las relaciones de varios a varios: use una entidad de combinación explícita.
  • Los objetos Session son opacos; consulte las propiedades isAuthenticated o user.
  • Después de habilitar o deshabilitar la autenticación en rayfin.yml, reinicie el back-end.

Obtención de ayuda

Si el problema persiste:

  1. Revise la documentación de Fabric Apps.
  2. Compruebe el repositorio GitHub para ver si hay problemas conocidos.
  3. Registre un informe de errores con registros detallados y pasos de reproducción.

Contenido relacionado

  • Se actualizó por última vez el