Saltar al contenido principal

Troubleshooting

Guía completa para resolver problemas comunes en Floutic.

Problemas de Inicio​

Los servicios no inician​

Síntomas:

  • Los contenedores no se levantan
  • Errores al ejecutar docker compose up
  • Timeouts en la conexión

Soluciones:

  1. Verificar que Docker esté ejecutándose
  2. Verificar espacio en disco: df -h
  3. Revisar los logs: docker compose logs
  4. Asegúrate de que los puertos no estén en uso: 
    # Verificar puertos
    netstat -tulpn | grep -E ':(3000|8000|5432|6379|5080)'
  5. Verificar las variables de entorno en .env
  6. Reconstruir imágenes: docker compose build --no-cache

Error de conexión a la base de datos​

Síntomas:

  • Backend no puede conectarse a PostgreSQL
  • Errores de conexión en los logs
  • Connection refused o timeout

Soluciones:

  1. Verificar que PostgreSQL esté saludable: 
    docker compose ps postgres
    docker compose logs postgres
  2. Verificar DATABASE_URL en variables de entorno
  3. Verificar que el volumen de PostgreSQL esté montado: 
    docker volume ls | grep postgres
  4. Reiniciar PostgreSQL: 
    docker compose restart postgres
  5. Verificar permisos del volumen: 
    ls -la docker-volumes/postgres/

Frontend no carga​

Síntomas:

Soluciones:

  1. Verificar que el backend esté saludable primero: 
    curl http://localhost:8000/health
  2. Revisar los logs del frontend: 
    docker compose logs frontend
  3. Verificar variables de entorno: 
    docker compose exec frontend env | grep VITE
  4. Limpiar el caché: 
    docker compose exec frontend npm run clear
  5. Reconstruir el frontend: 
    docker compose up -d --build frontend

Documentación no se construye​

Síntomas:

  • Errores al construir Docusaurus
  • El sitio no se sirve correctamente
  • Errores de compilación

Soluciones:

  1. Verificar que Node.js 20+ esté disponible: 
    docker compose exec docs node --version
  2. Limpiar el caché: 
    docker compose exec docs npm run clear
  3. Reconstruir: 
    docker compose exec docs npm run build
  4. Revisar los logs: 
    docker compose logs docs
  5. Verificar que los archivos markdown no tengan errores de sintaxis

Problemas de Autenticación​

No puedo iniciar sesión​

Síntomas:

  • Error al hacer login
  • "Invalid credentials"
  • Rate limiting activado

Soluciones:

  1. Verificar credenciales (username, no email)
  2. Verificar que el usuario esté activo
  3. Verificar rate limiting: 
    # Ver logs de rate limiting
    docker compose logs backend | grep rate
  4. Esperar si hay rate limiting activo
  5. Verificar que Redis esté funcionando (necesario para rate limiting)

Sesión expirada constantemente​

Síntomas:

  • Sesión se cierra automáticamente
  • Necesito hacer login frecuentemente
  • Tokens expiran muy rápido

Soluciones:

  1. Verificar configuración de tokens: 
    # Verificar variables de entorno
    docker compose exec backend env | grep JWT
  2. Verificar que JWT_ACCESS_EXPIRE_MINUTES no sea muy bajo
  3. Verificar que JWT_REFRESH_EXPIRE_DAYS esté configurado
  4. Verificar que el refresh token funcione correctamente

Error de CSRF​

Síntomas:

  • "CSRF token invalid"
  • Errores 403 en requests POST/PUT/DELETE

Soluciones:

  1. Verificar que las cookies se estén enviando correctamente
  2. Verificar que el frontend esté usando HTTPS en producción
  3. Verificar configuración de CORS
  4. Limpiar cookies del navegador y volver a intentar

Problemas de Base de Datos​

Migraciones fallan​

Síntomas:

  • Error al ejecutar docker compose exec backend alembic upgrade head
  • Conflictos de migración
  • Errores de esquema

Soluciones:

  1. Verificar estado de migraciones: 
    docker compose exec backend alembic current
  2. Ver historial de migraciones: 
    docker compose exec backend alembic history
  3. Aplicar migraciones manualmente: 
    docker compose exec backend alembic upgrade head
  4. Si hay conflictos, revisar las migraciones: 
    docker compose exec backend alembic merge -m "merge_heads" heads

Datos no se guardan​

Síntomas:

  • Los cambios no persisten
  • Datos se pierden al reiniciar
  • Errores de transacción

Soluciones:

  1. Verificar que los volúmenes estén montados: 
    docker volume ls
  2. Verificar permisos de escritura: 
    docker compose exec postgres ls -la /var/lib/postgresql/data
  3. Verificar logs de PostgreSQL: 
    docker compose logs postgres | grep ERROR
  4. Verificar que las transacciones se estén commitando

Problemas de Integraciones​

Stripe no funciona​

Síntomas:

  • Pagos no se procesan
  • Errores de Stripe API
  • Webhooks no se reciben

Soluciones:

  1. Verificar API keys: 
    docker compose exec backend env | grep STRIPE
  2. Verificar que las keys sean del mismo modo (test/live)
  3. Verificar webhook en Stripe Dashboard
  4. Verificar STRIPE_WEBHOOK_SECRET
  5. Probar webhook manualmente desde Stripe Dashboard

GoHighLevel no sincroniza​

Síntomas:

  • Contactos no se crean en GHL
  • Etiquetas no se sincronizan
  • Errores de API

Soluciones:

  1. Verificar API key: 
    docker compose exec backend env | grep GHL
  2. Verificar que GHL_LOCATION_ID sea correcto
  3. Verificar webhook en GHL:
    • URL: https://api.haorp.es/api/webhooks/ghl
    • Secret: Debe coincidir con GHL_WEBHOOK_SECRET
  4. Usar diagnóstico: 
    # Desde el dashboard admin
    GET /api/admin/users/{user_id}/ghl-diagnosis

n8n webhooks no funcionan​

Síntomas:

  • Webhooks no se reciben en n8n
  • Errores de autenticación
  • Timeouts

Soluciones:

  1. Verificar que la URL sea HTTPS
  2. Verificar autenticación JWT:
    • Algoritmo: HS256
    • Secreto: Debe coincidir
  3. Probar webhook desde Floutic:
    • Ir a /configuracion
    • Hacer clic en "Probar Webhook"
  4. Verificar que n8n esté accesible desde internet
  5. Verificar logs de n8n

Problemas de Rendimiento​

La aplicación es lenta​

Síntomas:

  • Requests tardan mucho
  • Timeouts frecuentes
  • Carga lenta de páginas

Soluciones:

  1. Verificar recursos del sistema: 
    docker stats
  2. Verificar que Redis esté funcionando (cache)
  3. Verificar logs de errores: 
    docker compose logs backend | grep ERROR
  4. Verificar conexiones a base de datos: 
    docker compose exec postgres psql -U floutic -c "SELECT count(*) FROM pg_stat_activity;"
  5. Aumentar recursos si es necesario

Redis no funciona​

Síntomas:

  • Cache no funciona
  • Rate limiting no funciona
  • Errores de conexión a Redis

Soluciones:

  1. Verificar que Redis esté ejecutándose: 
    docker compose ps redis
  2. Verificar conexión: 
    docker compose exec redis redis-cli ping
  3. Verificar REDIS_URL en variables de entorno
  4. Reiniciar Redis: 
    docker compose restart redis

Problemas de Despliegue​

Build falla​

Síntomas:

  • Error al construir imágenes
  • Dependencias no se instalan
  • Errores de compilación

Soluciones:

  1. Limpiar build cache: 
    docker compose build --no-cache
  2. Verificar que Docker tenga suficiente espacio
  3. Verificar logs de build: 
    docker compose build 2>&1 | tee build.log
  4. Verificar que las dependencias estén actualizadas

Variables de entorno incorrectas​

Síntomas:

  • Errores de configuración
  • Servicios no inician
  • Funcionalidades no funcionan

Soluciones:

  1. Verificar formato de .env:
    • Sin espacios alrededor del =
    • Sin comillas innecesarias
    • Valores correctos
  2. Verificar que todas las variables requeridas estén presentes
  3. Consultar Variables de Entorno
  4. Verificar que no haya caracteres especiales problemáticos

Comandos Útiles​

# Ver estado de todos los servicios
docker compose ps

# Ver logs de un servicio específico
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f postgres

# Reiniciar un servicio
docker compose restart backend

# Reconstruir un servicio
docker compose up -d --build backend

# Limpiar todo y empezar de nuevo
docker compose down -v
docker compose up -d

# Verificar salud de servicios
curl http://localhost:8000/health
curl http://localhost:3000

# Ejecutar comandos dentro de contenedores
docker compose exec backend bash
docker compose exec frontend sh
docker compose exec postgres psql -U floutic

# Ver uso de recursos
docker stats

# Limpiar imágenes y contenedores no usados
docker system prune -a

Obtener Ayuda​

Si no puedes resolver el problema:

  1. Revisar logs completos:

    docker compose logs > logs.txt

  2. Consultar documentación específica:

  3. Verificar issues conocidos:

    • Revisar GitHub Issues
    • Buscar en la documentación

  4. Abrir un issue en GitHub:

    • Incluir logs completos
    • Incluir versión de Docker
    • Incluir sistema operativo
    • Describir pasos para reproducir

  5. Contactar soporte: