Saltar al contenido principal

Solución de Problemas On-Premise

Esta guía proporciona pasos diagnósticos de Nivel 1 (L1) para solucionar problemas en despliegues On-Premise de EKB. Estos pasos ayudan a identificar problemas comunes con contenedores, bases de datos, servicios y recursos del sistema.

aviso

Requisitos previos: Necesita acceso SSH a la VM/servidor del cliente donde está desplegado EKB, y permisos apropiados para ejecutar comandos Docker y acceder a registros de contenedores.

Verificaciones de Estado de Contenedores​

Verificar Estado de Todos los Contenedores​

Primero, verifique qué contenedores están ejecutándose y su estado de salud:

# Verificar estado de todos los contenedores
docker ps -a

# Verificar contenedores con estado de salud
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Health}}"

# Verificar estado de un contenedor específico
docker ps -a | grep <container_name>

Contenedores Esperados:

  • web - Aplicación frontend
  • api o fastapi_backend - Servidor API backend
  • worker o celery_worker - Worker(s) de Celery
  • redis - Caché Redis
  • rabbitmq - Cola de mensajes RabbitMQ
  • supabase-studio - Supabase Studio
  • supabase-kong - API Gateway Kong
  • supabase-auth - Servicio de autenticación
  • supabase-db o postgres - Base de datos PostgreSQL
  • Otros servicios de Supabase (almacenamiento, meta, etc.)

Qué Verificar:

  • Todos los contenedores deben estar en estado "Up"
  • Ningún contenedor debe estar en estado "Restarting" o "Exited"
  • Las verificaciones de salud deben mostrar "healthy" donde corresponda

Reiniciar Contenedores Fallidos​

Si los contenedores están detenidos o reiniciándose:

# Reiniciar un contenedor específico
docker restart <container_name>

# Reiniciar todos los contenedores
docker compose restart

# Reiniciar un servicio específico
docker compose restart <service_name>

Registros del Contenedor Backend​

Verificar Registros del Contenedor API​

Los registros del contenedor API backend contienen información crítica sobre errores, conexiones de base de datos y problemas de servicio:

# Ver registros recientes (últimas 100 líneas)
docker logs --tail 100 api

# O para fastapi_backend
docker logs --tail 100 fastapi_backend

# Seguir registros en tiempo real
docker logs -f api

# Ver registros con marcas de tiempo
docker logs -t api

# Ver registros desde un momento específico
docker logs --since 30m api

# Ver registros entre marcas de tiempo
docker logs --since "2024-01-01T00:00:00" --until "2024-01-01T23:59:59" api

Qué Buscar:

  • Errores de conexión a base de datos
  • Fallos de conexión Redis
  • Problemas de conexión RabbitMQ
  • Errores de autenticación
  • Errores de endpoints API (500, 503, etc.)
  • Errores de importación/exportación
  • Errores de procesamiento de Base de Conocimiento
  • Fallos de tareas de workers

Verificar Registros del Contenedor Worker​

Los contenedores worker manejan tareas en segundo plano (procesamiento de KB, embeddings, etc.):

# Ver registros del worker
docker logs --tail 100 worker

# O para celery_worker
docker logs --tail 100 celery_worker

# Ver todas las instancias de worker
docker ps | grep worker
docker logs <worker_container_name>

Qué Buscar:

  • Errores de ejecución de tareas
  • Problemas de memoria
  • Errores de tiempo de espera agotado
  • Errores de conexión a base de datos en workers
  • Fallos de sincronización de Base de Conocimiento
  • Errores de generación de embeddings

Verificar Registros del Contenedor Web​

Los registros del contenedor frontend pueden revelar problemas de conexión con la UI y la API:

# Ver registros del contenedor web
docker logs --tail 100 web

# Seguir registros
docker logs -f web

Qué Buscar:

  • Errores de compilación
  • Fallos de conexión API
  • Problemas de variables de entorno
  • Errores de enlace de puertos

Estado de la Base de Datos​

Verificar Estado de PostgreSQL/Supabase Database​

# Ver estado del contenedor de base de datos
docker ps | grep -E "(db|postgres|supabase-db)"

# Ver registros del contenedor de base de datos
docker logs --tail 100 supabase-db

# O para el contenedor postgres
docker logs --tail 100 postgres

# Conectar a la base de datos (si psql está disponible)
docker exec -it supabase-db psql -U postgres

# Verificar conexiones de base de datos
docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"

# Verificar tamaño de la base de datos
docker exec supabase-db psql -U postgres -c "SELECT pg_size_pretty(pg_database_size('postgres'));"

Qué Verificar:

  • El contenedor de base de datos está ejecutándose
  • No hay errores de conexión en los registros
  • La base de datos no está llena (verifique el espacio en disco)
  • Las conexiones activas están dentro de los límites
  • No hay consultas de larga ejecución bloqueando operaciones

Verificar Conectividad de Base de Datos desde la API​

# Probar conexión de base de datos desde el contenedor API
docker exec api python -c "
import os
from sqlalchemy import create_engine
try:
    engine = create_engine(os.environ.get('DATABASE_URL'))
    conn = engine.connect()
    print('Database connection successful')
    conn.close()
except Exception as e:
    print(f'Database connection failed: {e}')
"

Verificar Migraciones de Base de Datos​

# Verificar si las migraciones están actualizadas
docker exec api alembic current

# Ver historial de migraciones
docker exec api alembic history

# Ver migraciones pendientes
docker exec api alembic heads

Estado de Redis​

Verificar Contenedor Redis​

# Ver estado del contenedor Redis
docker ps | grep redis

# Ver registros de Redis
docker logs --tail 100 redis

# Probar conexión Redis
docker exec redis redis-cli ping

# Debería devolver: PONG

# Ver información de Redis
docker exec redis redis-cli info

# Ver uso de memoria de Redis
docker exec redis redis-cli info memory

# Ver clientes conectados
docker exec redis redis-cli info clients

Qué Verificar:

  • Redis responde al ping
  • El uso de memoria está dentro de los límites
  • No hay errores de conexión
  • No hay errores de expulsión (memoria llena)

Probar Redis desde el Contenedor API​

# Probar conexión Redis desde la API
docker exec api python -c "
import redis
import os
try:
    r = redis.Redis(host='redis', port=6379, decode_responses=True)
    r.ping()
    print('Redis connection successful')
except Exception as e:
    print(f'Redis connection failed: {e}')
"

Estado de RabbitMQ​

Verificar Contenedor RabbitMQ​

# Ver estado del contenedor RabbitMQ
docker ps | grep rabbitmq

# Ver registros de RabbitMQ
docker logs --tail 100 rabbitmq

# Ver gestión de RabbitMQ (si es accesible)
# Acceder: http://<server-ip>:15672
# Credenciales predeterminadas: user/password

Qué Verificar:

  • El contenedor está ejecutándose
  • No hay errores de conexión
  • Las colas están procesando mensajes
  • No hay acumulación de mensajes

Verificar RabbitMQ desde la API​

# Probar conexión RabbitMQ
docker exec api python -c "
import pika
try:
    connection = pika.BlockingConnection(
        pika.ConnectionParameters('rabbitmq', 5672, '/',
            pika.PlainCredentials('user', 'password'))
    )
    print('RabbitMQ connection successful')
    connection.close()
except Exception as e:
    print(f'RabbitMQ connection failed: {e}')
"

Recursos del Sistema​

Verificar Espacio en Disco​

El espacio bajo en disco puede causar problemas de base de datos, almacenamiento y contenedores:

# Ver uso general del disco
df -h

# Ver uso del disco para volúmenes Docker
docker system df

# Ver uso de un volumen específico
docker volume inspect <volume_name>

# Ver tamaños de directorios
du -sh /var/lib/docker/volumes/*
du -sh ./supabase/docker/volumes/*

# Ver uso del disco dentro del contenedor (para base de datos)
docker exec supabase-db df -h

Qué Verificar:

  • La partición raíz tiene espacio suficiente (se recomienda >20% libre)
  • Los volúmenes Docker no están llenos
  • El directorio de datos de la base de datos tiene espacio
  • El almacenamiento de Supabase tiene espacio

Verificar Uso de Memoria​

# Ver memoria del sistema
free -h

# Ver uso de memoria de contenedores
docker stats --no-stream

# Ver memoria de un contenedor específico
docker stats <container_name> --no-stream

Qué Verificar:

  • El sistema tiene memoria disponible
  • Los contenedores no están alcanzando los límites de memoria
  • No hay muertes OOM (Out of Memory) en los registros

Verificar Uso de CPU​

# Ver uso de CPU
top
# o
htop

# Ver uso de CPU de contenedores
docker stats --no-stream

Conectividad de Red​

Verificar Red de Contenedores​

# Ver red Docker
docker network ls

# Inspeccionar configuración de red
docker network inspect <network_name>

# Verificar si los contenedores pueden comunicarse
docker exec api ping -c 3 redis
docker exec api ping -c 3 rabbitmq
docker exec api ping -c 3 supabase-db

Verificar Disponibilidad de Puertos​

# Verificar si los puertos están en uso
netstat -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

# O usando ss
ss -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

# Verificar puerto desde el contenedor
docker exec api curl -I http://localhost:8001/health

Variables de Entorno​

Verificar Configuración de Entorno​

# Ver variables de entorno de un contenedor
docker exec api env | grep -E "(DATABASE|REDIS|RABBITMQ|API)"

# Ver archivos .env (si son accesibles)
cat ./env/.env.server | grep -v "PASSWORD\|SECRET\|KEY"  # Excluir datos sensibles
cat ./env/.env.web | grep -v "PASSWORD\|SECRET\|KEY"

# Ver entorno desde docker-compose
docker compose config

Qué Verificar:

  • Las cadenas de conexión a la base de datos son correctas
  • Los nombres de host de Redis y RabbitMQ son correctos
  • Las URL de la API están configuradas correctamente
  • Las variables de entorno requeridas están establecidas
  • No hay errores tipográficos en los nombres de variables

Permisos de Archivos​

Verificar Permisos de Archivos y Directorios​

# Verificar permisos en directorios clave
ls -la ./alignment-project-server
ls -la ./ai-content-creator
ls -la ./supabase/docker/volumes

# Verificar permisos del socket Docker
ls -la /var/run/docker.sock

# Verificar archivos de certificado (si usa HTTPS)
ls -la ./certs/

Qué Verificar:

  • Los directorios de la aplicación son legibles
  • El socket Docker tiene permisos correctos
  • Los montajes de volumen tienen permisos adecuados
  • Los archivos de certificado son accesibles

Verificaciones Específicas por Servicio​

Problemas de Base de Conocimiento​

Si la Base de Conocimiento no se actualiza o procesa:

# Ver registros del worker para procesamiento de KB
docker logs --tail 200 worker | grep -i "knowledge\|kb\|embedding"

# Ver problemas del modelo de embeddings
docker logs api | grep -i "embedding\|model"

# Ver almacenamiento de Supabase
docker logs supabase-storage

# Ver límites de carga de archivos
docker exec supabase-db psql -U postgres -c "
SELECT name, file_size_limit 
FROM storage.buckets;
"

Problemas de Chat/Agente​

# Ver registros de API para errores de agentes
docker logs --tail 200 api | grep -i "agent\|chat\|llm"

# Ver registros de worker para tareas de agentes
docker logs --tail 200 worker | grep -i "agent\|chat"

Problemas de Autenticación​

# Ver registros del servicio de autenticación
docker logs --tail 100 supabase-auth

# Verificar base de datos para problemas de autenticación
docker exec supabase-db psql -U postgres -c "
SELECT * FROM auth.users LIMIT 5;
"

Patrones de Errores Comunes​

Errores de Conexión a Base de Datos​

Síntomas:

  • Errores de "Connection refused"
  • Errores de "Too many connections"
  • Errores de tiempo de espera agotado

Pasos Diagnósticos:

  1. Verificar que el contenedor de base de datos esté ejecutándose: docker ps | grep db
  2. Verificar registros de la base de datos: docker logs supabase-db
  3. Verificar límites de conexión: docker exec supabase-db psql -U postgres -c "SHOW max_connections;"
  4. Verificar conexiones activas: docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"
  5. Verificar DATABASE_URL en las variables de entorno

Errores de Conexión Redis​

Síntomas:

  • "Connection refused" a Redis
  • Fallos de caché
  • Problemas de sesión

Pasos Diagnósticos:

  1. Verificar contenedor Redis: docker ps | grep redis
  2. Probar Redis: docker exec redis redis-cli ping
  3. Verificar registros de Redis: docker logs redis
  4. Verificar el nombre de host Redis en las variables de entorno

Fallos de Tareas de Workers​

Síntomas:

  • Las tareas no se completan
  • La Base de Conocimiento no se sincroniza
  • Trabajos en segundo plano fallan

Pasos Diagnósticos:

  1. Verificar registros del worker: docker logs worker
  2. Verificar estado del contenedor worker: docker ps | grep worker
  3. Verificar colas RabbitMQ: Acceder a la interfaz de gestión de RabbitMQ
  4. Verificar problemas de memoria: docker stats worker

Problemas de Almacenamiento/Carga de Archivos​

Síntomas:

  • Las cargas de archivos fallan
  • Errores de "File too large"
  • Cuota de almacenamiento excedida

Pasos Diagnósticos:

  1. Verificar espacio en disco: df -h
  2. Verificar registros de almacenamiento de Supabase: docker logs supabase-storage
  3. Verificar límites de tamaño de archivo en la configuración de Supabase
  4. Verificar configuración del bucket de almacenamiento

Script de Diagnóstico Rápido​

Cree un script de diagnóstico para ejecutar todas las verificaciones a la vez:

#!/bin/bash
echo "=== Diagnóstico On-Premise de EKB ==="
echo ""
echo "1. Estado de Contenedores:"
docker ps --format "table {{.Names}}\t{{.Status}}"
echo ""
echo "2. Espacio en Disco:"
df -h | grep -E "(Filesystem|/dev/)"
echo ""
echo "3. Memoria:"
free -h
echo ""
echo "4. Redis:"
docker exec redis redis-cli ping 2>/dev/null || echo "Redis no responde"
echo ""
echo "5. Base de Datos:"
docker exec supabase-db psql -U postgres -c "SELECT version();" 2>/dev/null || echo "Base de datos no responde"
echo ""
echo "6. Errores Recientes de API (últimas 20 líneas):"
docker logs --tail 20 api 2>/dev/null | grep -i error || echo "No hay errores recientes"
echo ""
echo "=== Diagnóstico Completo ==="

Guarde como diagnostics.sh, hágalo ejecutable: chmod +x diagnostics.sh, y ejecute: ./diagnostics.sh

Información de Escalación​

Al escalar al soporte Nivel 2, proporcione:

  1. Estado de Contenedores: Salida de docker ps -a
  2. Registros Recientes: Últimas 100-200 líneas de los contenedores relevantes
  3. Recursos del Sistema: Salida de df -h y free -h
  4. Mensajes de Error: Mensajes de error específicos de los registros
  5. Configuración: Nombres de variables de entorno (no valores) que están configuradas
  6. Cronología: Cuándo comenzó el problema
  7. Impacto: Qué funcionalidad se ve afectada

Contactar Soporte: support@automationanywhere.com

Recursos Adicionales​