Solución de Problemas On-Premise

Pasos diagnósticos de nivel L1 para solucionar problemas en despliegues On-Premise de EKB

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.

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: [e-mail]

​

Recursos Adicionales

• Guía de Instalación On-Premise
• Documentación de Docker