> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Warning>
  **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.
</Warning>

## Verificaciones de Estado de Contenedores

### Verificar Estado de Todos los Contenedores

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

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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.):

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# Ver uso de CPU
top
# o
htop

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

## Conectividad de Red

### Verificar Red de Contenedores

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
#!/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](mailto:support@automationanywhere.com)

## Recursos Adicionales

* [Guía de Instalación On-Premise](/offerings/on-premise/installation)
* [Documentación de Docker](https://docs.docker.com/)