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

# Solução de Problemas On-Premise

> Etapas diagnósticas de nível 1 para solução de problemas em implantações On-Premise do EKB

Este guia fornece etapas diagnósticas de Nível 1 (L1) para solução de problemas em implantações On-Premise do EKB. Essas etapas ajudam a identificar problemas comuns com containers, bancos de dados, serviços e recursos do sistema.

<Warning>
  **Pré-requisitos**: Você precisa de acesso SSH ao servidor/VM do cliente onde o EKB está implantado, e permissões apropriadas para executar comandos Docker e acessar logs de containers.
</Warning>

## Verificações de Status dos Containers

### Verificar Status de Todos os Containers

Primeiro, verifique quais containers estão em execução e seu status de saúde:

```bash theme={null}
# Check all containers status
docker ps -a

# Check containers with health status
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Health}}"

# Check specific container status
docker ps -a | grep <container_name>
```

**Containers Esperados:**

* `web` - Aplicação frontend
* `api` ou `fastapi_backend` - Servidor API backend
* `worker` ou `celery_worker` - Worker(s) do Celery
* `redis` - Cache Redis
* `rabbitmq` - Fila de mensagens RabbitMQ
* `supabase-studio` - Supabase Studio
* `supabase-kong` - API Gateway Kong
* `supabase-auth` - Serviço de autenticação
* `supabase-db` ou `postgres` - Banco de dados PostgreSQL
* Outros serviços Supabase (storage, meta, etc.)

**O Que Verificar:**

* Todos os containers devem estar no status "Up"
* Nenhum container deve estar no estado "Restarting" ou "Exited"
* Verificações de saúde devem mostrar "healthy" quando aplicável

### Reiniciar Containers com Falha

Se os containers estiverem parados ou reiniciando:

```bash theme={null}
# Restart a specific container
docker restart <container_name>

# Restart all containers
docker compose restart

# Restart specific service
docker compose restart <service_name>
```

## Logs dos Containers Backend

### Verificar Logs do Container API

Os logs do container API do backend contêm informações críticas sobre erros, conexões de banco de dados e problemas de serviço:

```bash theme={null}
# View recent logs (last 100 lines)
docker logs --tail 100 api

# Or for fastapi_backend
docker logs --tail 100 fastapi_backend

# Follow logs in real-time
docker logs -f api

# View logs with timestamps
docker logs -t api

# View logs from specific time
docker logs --since 30m api

# View logs between timestamps
docker logs --since "2024-01-01T00:00:00" --until "2024-01-01T23:59:59" api
```

**O Que Procurar:**

* Erros de conexão com banco de dados
* Falhas de conexão com Redis
* Problemas de conexão com RabbitMQ
* Erros de autenticação
* Erros de endpoint da API (500, 503, etc.)
* Erros de importação/exportação
* Erros de processamento da Base de Conhecimento
* Falhas de tarefas do worker

### Verificar Logs do Container Worker

Os containers worker lidam com tarefas em segundo plano (processamento de KB, embeddings, etc.):

```bash theme={null}
# Check worker logs
docker logs --tail 100 worker

# Or for celery_worker
docker logs --tail 100 celery_worker

# Check all worker instances
docker ps | grep worker
docker logs <worker_container_name>
```

**O Que Procurar:**

* Erros de execução de tarefas
* Problemas de memória
* Erros de tempo limite
* Erros de conexão com banco de dados nos workers
* Falhas de sincronização da Base de Conhecimento
* Erros de geração de embeddings

### Verificar Logs do Container Web

Os logs do container frontend podem revelar problemas de conexão com UI e API:

```bash theme={null}
# Check web container logs
docker logs --tail 100 web

# Follow logs
docker logs -f web
```

**O Que Procurar:**

* Erros de build
* Falhas de conexão com API
* Problemas com variáveis de ambiente
* Erros de vinculação de porta

## Status do Banco de Dados

### Verificar Status do Banco de Dados PostgreSQL/Supabase

```bash theme={null}
# Check database container status
docker ps | grep -E "(db|postgres|supabase-db)"

# Check database container logs
docker logs --tail 100 supabase-db

# Or for postgres container
docker logs --tail 100 postgres

# Connect to database (if psql is available)
docker exec -it supabase-db psql -U postgres

# Check database connections
docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"

# Check database size
docker exec supabase-db psql -U postgres -c "SELECT pg_size_pretty(pg_database_size('postgres'));"
```

**O Que Verificar:**

* O container do banco de dados está em execução
* Sem erros de conexão nos logs
* O banco de dados não está cheio (verifique o espaço em disco)
* Conexões ativas estão dentro dos limites
* Sem consultas longas bloqueando operações

### Verificar Conectividade do Banco de Dados a partir da API

```bash theme={null}
# Test database connection from API container
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 Migrações do Banco de Dados

```bash theme={null}
# Check if migrations are up to date
docker exec api alembic current

# Check migration history
docker exec api alembic history

# View pending migrations
docker exec api alembic heads
```

## Status do Redis

### Verificar Container Redis

```bash theme={null}
# Check Redis container status
docker ps | grep redis

# Check Redis logs
docker logs --tail 100 redis

# Test Redis connection
docker exec redis redis-cli ping

# Should return: PONG

# Check Redis info
docker exec redis redis-cli info

# Check Redis memory usage
docker exec redis redis-cli info memory

# Check connected clients
docker exec redis redis-cli info clients
```

**O Que Verificar:**

* O Redis está respondendo ao ping
* Uso de memória está dentro dos limites
* Sem erros de conexão
* Sem erros de evição (memória cheia)

### Testar Redis a partir do Container API

```bash theme={null}
# Test Redis connection from 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}')
"
```

## Status do RabbitMQ

### Verificar Container RabbitMQ

```bash theme={null}
# Check RabbitMQ container status
docker ps | grep rabbitmq

# Check RabbitMQ logs
docker logs --tail 100 rabbitmq

# Check RabbitMQ management (if accessible)
# Access: http://<server-ip>:15672
# Default credentials: user/password
```

**O Que Verificar:**

* O container está em execução
* Sem erros de conexão
* As filas estão processando mensagens
* Sem acumulação de mensagens

### Verificar RabbitMQ a partir da API

```bash theme={null}
# Test RabbitMQ connection
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 do Sistema

### Verificar Espaço em Disco

Pouco espaço em disco pode causar problemas no banco de dados, armazenamento e containers:

```bash theme={null}
# Check overall disk usage
df -h

# Check disk usage for Docker volumes
docker system df

# Check specific volume usage
docker volume inspect <volume_name>

# Check directory sizes
du -sh /var/lib/docker/volumes/*
du -sh ./supabase/docker/volumes/*

# Check in-container disk usage (for database)
docker exec supabase-db df -h
```

**O Que Verificar:**

* A partição raiz tem espaço suficiente (>20% livre recomendado)
* Os volumes Docker não estão cheios
* O diretório de dados do banco de dados tem espaço
* O armazenamento Supabase tem espaço

### Verificar Uso de Memória

```bash theme={null}
# Check system memory
free -h

# Check container memory usage
docker stats --no-stream

# Check specific container memory
docker stats <container_name> --no-stream
```

**O Que Verificar:**

* O sistema tem memória disponível
* Os containers não estão atingindo os limites de memória
* Sem kills OOM (Out of Memory) nos logs

### Verificar Uso de CPU

```bash theme={null}
# Check CPU usage
top
# or
htop

# Check container CPU usage
docker stats --no-stream
```

## Conectividade de Rede

### Verificar Rede dos Containers

```bash theme={null}
# Check Docker network
docker network ls

# Inspect network configuration
docker network inspect <network_name>

# Check if containers can communicate
docker exec api ping -c 3 redis
docker exec api ping -c 3 rabbitmq
docker exec api ping -c 3 supabase-db
```

### Verificar Disponibilidade de Portas

```bash theme={null}
# Check if ports are in use
netstat -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

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

# Check port from container
docker exec api curl -I http://localhost:8001/health
```

## Variáveis de Ambiente

### Verificar Configuração de Ambiente

```bash theme={null}
# Check environment variables for a container
docker exec api env | grep -E "(DATABASE|REDIS|RABBITMQ|API)"

# Check .env files (if accessible)
cat ./env/.env.server | grep -v "PASSWORD\|SECRET\|KEY"  # Exclude sensitive data
cat ./env/.env.web | grep -v "PASSWORD\|SECRET\|KEY"

# Check environment from docker-compose
docker compose config
```

**O Que Verificar:**

* As strings de conexão do banco de dados estão corretas
* Os nomes de host do Redis e RabbitMQ estão corretos
* As URLs da API estão configuradas corretamente
* As variáveis de ambiente necessárias estão definidas
* Sem erros de digitação nos nomes das variáveis

## Permissões de Arquivos

### Verificar Permissões de Arquivos e Diretórios

```bash theme={null}
# Check permissions on key directories
ls -la ./alignment-project-server
ls -la ./ai-content-creator
ls -la ./supabase/docker/volumes

# Check Docker socket permissions
ls -la /var/run/docker.sock

# Check certificate files (if using HTTPS)
ls -la ./certs/
```

**O Que Verificar:**

* Os diretórios da aplicação são legíveis
* O socket Docker tem permissões corretas
* Os mounts de volumes têm permissões apropriadas
* Os arquivos de certificado são acessíveis

## Verificações Específicas por Serviço

### Problemas com Base de Conhecimento

Se a Base de Conhecimento não estiver atualizando ou processando:

```bash theme={null}
# Check worker logs for KB processing
docker logs --tail 200 worker | grep -i "knowledge\|kb\|embedding"

# Check for embedding model issues
docker logs api | grep -i "embedding\|model"

# Check Supabase storage
docker logs supabase-storage

# Check file upload limits
docker exec supabase-db psql -U postgres -c "
SELECT name, file_size_limit 
FROM storage.buckets;
"
```

### Problemas com Chat/Agente

```bash theme={null}
# Check API logs for agent errors
docker logs --tail 200 api | grep -i "agent\|chat\|llm"

# Check worker logs for agent tasks
docker logs --tail 200 worker | grep -i "agent\|chat"
```

### Problemas de Autenticação

```bash theme={null}
# Check auth service logs
docker logs --tail 100 supabase-auth

# Check database for auth issues
docker exec supabase-db psql -U postgres -c "
SELECT * FROM auth.users LIMIT 5;
"
```

## Padrões Comuns de Erros

### Erros de Conexão com Banco de Dados

**Sintomas:**

* Erros "Connection refused"
* Erros "Too many connections"
* Erros de tempo limite

**Etapas Diagnósticas:**

1. Verifique se o container do banco de dados está em execução: `docker ps | grep db`
2. Verifique os logs do banco de dados: `docker logs supabase-db`
3. Verifique os limites de conexão: `docker exec supabase-db psql -U postgres -c "SHOW max_connections;"`
4. Verifique as conexões ativas: `docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"`
5. Verifique o DATABASE\_URL nas variáveis de ambiente

### Erros de Conexão com Redis

**Sintomas:**

* "Connection refused" para Redis
* Falhas de cache
* Problemas de sessão

**Etapas Diagnósticas:**

1. Verifique o container Redis: `docker ps | grep redis`
2. Teste o Redis: `docker exec redis redis-cli ping`
3. Verifique os logs do Redis: `docker logs redis`
4. Verifique o nome de host do Redis nas variáveis de ambiente

### Falhas de Tarefas do Worker

**Sintomas:**

* Tarefas não sendo concluídas
* Base de Conhecimento não sincronizando
* Tarefas em segundo plano falhando

**Etapas Diagnósticas:**

1. Verifique os logs do worker: `docker logs worker`
2. Verifique o status do container worker: `docker ps | grep worker`
3. Verifique as filas do RabbitMQ: Acesse a interface de gerenciamento do RabbitMQ
4. Verifique problemas de memória: `docker stats worker`

### Problemas de Armazenamento/Upload de Arquivos

**Sintomas:**

* Uploads de arquivo falhando
* Erros "File too large"
* Cota de armazenamento excedida

**Etapas Diagnósticas:**

1. Verifique o espaço em disco: `df -h`
2. Verifique os logs do armazenamento Supabase: `docker logs supabase-storage`
3. Verifique os limites de tamanho de arquivo na configuração do Supabase
4. Verifique a configuração do bucket de armazenamento

## Script de Diagnóstico Rápido

Crie um script de diagnóstico para executar todas as verificações de uma vez:

```bash theme={null}
#!/bin/bash
echo "=== EKB On-Premise Diagnostics ==="
echo ""
echo "1. Container Status:"
docker ps --format "table {{.Names}}\t{{.Status}}"
echo ""
echo "2. Disk Space:"
df -h | grep -E "(Filesystem|/dev/)"
echo ""
echo "3. Memory:"
free -h
echo ""
echo "4. Redis:"
docker exec redis redis-cli ping 2>/dev/null || echo "Redis not responding"
echo ""
echo "5. Database:"
docker exec supabase-db psql -U postgres -c "SELECT version();" 2>/dev/null || echo "Database not responding"
echo ""
echo "6. Recent API Errors (last 20 lines):"
docker logs --tail 20 api 2>/dev/null | grep -i error || echo "No recent errors"
echo ""
echo "=== Diagnostics Complete ==="
```

Salve como `diagnostics.sh`, torne executável: `chmod +x diagnostics.sh`, e execute: `./diagnostics.sh`

## Informações de Escalação

Ao escalar para suporte L2, forneça:

1. **Status dos Containers**: Saída de `docker ps -a`
2. **Logs Recentes**: Últimas 100-200 linhas dos containers relevantes
3. **Recursos do Sistema**: Saída de `df -h` e `free -h`
4. **Mensagens de Erro**: Mensagens de erro específicas dos logs
5. **Configuração**: Nomes das variáveis de ambiente (não valores) que estão definidos
6. **Linha do Tempo**: Quando o problema começou
7. **Impacto**: Qual funcionalidade está afetada

**Entre em Contato com o Suporte**: [support@automationanywhere.com](mailto:support@automationanywhere.com)

## Recursos Adicionais

* [Guia de Instalação On-Premise](/offerings/on-premise/installation)
* [Documentação do Docker](https://docs.docker.com/)