Pular para o conteúdo principal

Troubleshooting

Guia de resolução de problemas comuns do sistema Acesso ao Emprego.

Problemas de Inicialização​

Container não inicia​

Sintoma: O container não inicia ou reinicia constantemente.

Diagnóstico:

docker-compose -f docker-compose.dev.yml logs backend
docker-compose -f docker-compose.dev.yml ps

Soluções:

  1. Verificar variáveis de ambiente:
docker-compose -f docker-compose.dev.yml exec backend env | grep -E "DB_|REDIS_|SECRET"
  1. Rebuild do container:
docker-compose -f docker-compose.dev.yml build --no-cache backend
docker-compose -f docker-compose.dev.yml up -d backend
  1. Verificar conectividade com dependências:
docker-compose -f docker-compose.dev.yml exec backend python -c "
from django.db import connection
connection.ensure_connection()
print('Database OK!')
"

Erro de conexão com banco de dados​

Sintoma: django.db.utils.OperationalError: could not connect to server

Diagnóstico:

docker-compose -f docker-compose.dev.yml logs postgres
docker-compose -f docker-compose.dev.yml exec postgres pg_isready

Soluções:

  1. Aguardar inicialização completa do PostgreSQL:
docker-compose -f docker-compose.dev.yml restart postgres
sleep 10
docker-compose -f docker-compose.dev.yml restart backend
  1. Verificar credenciais:
docker-compose -f docker-compose.dev.yml exec postgres psql -U postgres -c "\l"
  1. Recriar banco de dados:
docker-compose -f docker-compose.dev.yml down -v
docker-compose -f docker-compose.dev.yml up -d
docker-compose -f docker-compose.dev.yml exec backend python manage.py migrate

Porta já em uso​

Sintoma: Error starting userland proxy: Bind for 0.0.0.0:8080: address already in use

Diagnóstico:

# Windows
netstat -ano | findstr :8080

# Linux/Mac
lsof -i :8080

Soluções:

  1. Matar processo usando a porta:
# Linux/Mac
kill -9 $(lsof -t -i:8080)

# Windows (substituir PID pelo número encontrado)
taskkill /PID <PID> /F
  1. Alterar porta no docker-compose:
ports:
  - "8081:8080"

Problemas de Performance​

API lenta​

Sintoma: Endpoints demorando mais de 500ms para responder.

Diagnóstico:

docker-compose -f docker-compose.dev.yml exec backend python manage.py shell
>>> from django.db import connection
>>> from django.db import reset_queries
>>> reset_queries()
>>> # Execute a operação lenta
>>> print(len(connection.queries))
>>> for q in connection.queries: print(q['time'], q['sql'][:100])

Soluções:

  1. Otimizar queries com select_related/prefetch_related
  2. Adicionar índices nas colunas mais consultadas
  3. Implementar cache para dados frequentes:
from django.core.cache import cache
cache.set('key', 'value', timeout=3600)

Memória alta​

Sintoma: Container backend usando mais de 80% da memória.

Diagnóstico:

docker stats

Soluções:

  1. Reiniciar o serviço:
docker-compose -f docker-compose.dev.yml restart backend
  1. Aumentar limite de memória:
deploy:
  resources:
    limits:
      memory: 2G
  1. Verificar memory leaks:
docker-compose -f docker-compose.dev.yml exec backend python -c "
import tracemalloc
tracemalloc.start()
# Execute operação suspeita
snapshot = tracemalloc.take_snapshot()
for stat in snapshot.statistics('lineno')[:10]:
    print(stat)
"

Problemas com Celery​

Tasks não sendo processadas​

Sintoma: Tasks ficam pendentes na fila indefinidamente.

Diagnóstico:

docker-compose -f docker-compose.dev.yml logs worker
docker-compose -f docker-compose.dev.yml exec backend celery -A app inspect active
docker-compose -f docker-compose.dev.yml exec redis redis-cli LLEN celery

Soluções:

  1. Reiniciar worker:
docker-compose -f docker-compose.dev.yml restart worker
  1. Verificar conexão com Redis:
docker-compose -f docker-compose.dev.yml exec redis redis-cli ping
  1. Limpar fila e reprocessar:
docker-compose -f docker-compose.dev.yml exec backend celery -A app purge

Tasks falhando repetidamente​

Sintoma: Tasks entram em loop de retry ou falham com exceções.

Diagnóstico:

docker-compose -f docker-compose.dev.yml logs worker | grep -i error

Soluções:

  1. Verificar logs detalhados da task:
docker-compose -f docker-compose.dev.yml exec backend celery -A app events
  1. Executar task manualmente para debug:
docker-compose -f docker-compose.dev.yml exec backend python manage.py shell
>>> from app.apps.your_app.tasks import your_task
>>> your_task()

Problemas de Autenticação​

Token JWT inválido​

Sintoma: 401 Unauthorized - Token is invalid or expired

Diagnóstico: Verificar se o token está expirado ou malformado.

Soluções:

  1. Gerar novo token:
curl -X POST http://localhost:8080/api/auth/token/ \
  -H "Content-Type: application/json" \
  -d '{"email": "user@test.com", "password": "senha@1234"}'
  1. Refresh do token:
curl -X POST http://localhost:8080/api/auth/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{"refresh": "seu_refresh_token"}'

Erro de CORS​

Sintoma: Access to XMLHttpRequest has been blocked by CORS policy

Diagnóstico:

docker-compose -f docker-compose.dev.yml exec backend python -c "
from django.conf import settings
print('CORS Origins:', settings.CORS_ALLOWED_ORIGINS)
"

Soluções:

  1. Adicionar origem ao .env:
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
  1. Reiniciar backend:
docker-compose -f docker-compose.dev.yml restart backend

Problemas de Migrations​

Migration em conflito​

Sintoma: django.db.migrations.exceptions.InconsistentMigrationHistory

Diagnóstico:

docker-compose -f docker-compose.dev.yml exec backend python manage.py showmigrations

Soluções:

  1. Fake migration específica:
docker-compose -f docker-compose.dev.yml exec backend python manage.py migrate --fake app_name migration_name
  1. Reset migrations da app:
docker-compose -f docker-compose.dev.yml exec backend python manage.py migrate app_name zero
docker-compose -f docker-compose.dev.yml exec backend python manage.py migrate app_name

Erro ao criar migration​

Sintoma: No changes detected

Soluções:

  1. Especificar a app:
docker-compose -f docker-compose.dev.yml exec backend python manage.py makemigrations app_name
  1. Verificar se a app está no INSTALLED_APPS

Problemas do Sistema Fuzzy​

Word embeddings não encontrados​

Sintoma: FileNotFoundError: Word embeddings file not found

Soluções:

  1. Download manual:
docker-compose -f docker-compose.dev.yml exec backend python -c "
import nltk
nltk.download('punkt')
nltk.download('stopwords')
"
  1. Instalar modelo spaCy:
docker-compose -f docker-compose.dev.yml exec backend python -m spacy download pt_core_news_sm
  1. Limpar e recarregar:
docker-compose -f docker-compose.dev.yml exec backend rm -rf /app/fuzzy_files/*
docker-compose -f docker-compose.dev.yml restart worker

Logs e Debugging​

Habilitar modo debug​

# No .env
DEBUG=True
DJANGO_LOG_LEVEL=DEBUG

Analisar logs estruturados​

docker-compose -f docker-compose.dev.yml logs -f | grep -E "\[ERROR\]|\[CRITICAL\]"

docker-compose -f docker-compose.dev.yml logs --since="1h" backend

docker-compose -f docker-compose.dev.yml logs backend 2>&1 | tee backend_logs.txt

Debug remoto com pdb​

import pdb; pdb.set_trace()
docker-compose -f docker-compose.dev.yml run --service-ports backend python manage.py runserver 0.0.0.0:8080

Contato de Suporte​

Se o problema persistir após seguir este guia:

  1. Colete logs relevantes
  2. Documente os passos de reprodução
  3. Abra uma issue no repositório
  4. Contate o time de suporte: suporte@portal-talentos.gov.br
Prevenção

A maioria dos problemas pode ser evitada com monitoramento proativo e manutenção regular. Consulte o guia de Procedimentos de Manutenção.