Solución de Problemas

Esta guía recopila los problemas más frecuentes al instalar, configurar y operar NoxPanel, junto con sus soluciones.

Problemas de Conexión 

Connection Refused al acceder al panel 

Síntoma: Al acceder a https://tu-dominio/ el navegador muestra «Connection Refused» o «This site can’t be reached».

Posibles causas y soluciones:

Servicios no están corriendo:

docker-compose ps
# Verificar que web, nginx y db están "Up"

# Si algún servicio está detenido, reiniciar
docker-compose up -d

Puerto no expuesto / firewall:

# Verificar que los puertos están abiertos
ss -tlnp | grep -E '(80|443)'

# Abrir puertos en UFW
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Traefik no está corriendo:

docker ps | grep traefik
# Si no aparece, asegurarse de que la red traefik-public existe
docker network create traefik-public

DNS no apunta al servidor:

# Verificar resolución DNS
dig +short tu-dominio
# Debe devolver la IP de tu servidor

Connection Refused al Motor de Hosting 

Síntoma: Las operaciones de hosting fallan con «Connection Refused» al comunicarse con el motor de hosting.

Soluciones:

Verificar que el contenedor hosting-core está corriendo y sano:

docker-compose ps hosting-core
docker-compose logs --tail=50 hosting-core

El motor de hosting tarda varios minutos en iniciar (la primera vez puede tardar hasta 5-10 minutos). Verificar el healthcheck:
```
docker inspect --format='{{.State.Health.Status}}' \
  $(docker-compose ps -q hosting-core)
```

Verificar que la contraseña del motor de hosting está configurada:

docker-compose exec web python -c \
  "from django.conf import settings; print(bool(settings.ISPCONFIG_PASSWORD))"

Errores HTTP 500 

Error 500 Internal Server Error 

Síntoma: El panel muestra un error 500 genérico.

Diagnóstico:

Revisar logs del servidor web:

docker-compose logs --tail=100 web
# Buscar tracebacks de Python

Revisar logs de Nginx:
```
docker-compose logs --tail=50 nginx
```
Activar modo debug temporalmente (solo desarrollo):
```
# En .env
DEBUG=True

# Reiniciar
docker-compose restart web
```
Danger

NUNCA dejes DEBUG=True en producción. Expone información sensible del sistema.

Error en las migraciones: Si hay migraciones pendientes, Django puede dar error 500 en cualquier endpoint:

docker-compose exec web python manage.py showmigrations | grep "\[ \]"
docker-compose exec web python manage.py migrate

Error 500 al crear sitio/base de datos 

Generalmente indica un problema de comunicación con el motor de hosting:

# Verificar conexión al motor de hosting
docker-compose exec web python -c "
from integrations.ispconfig_client import ISPConfigClient
api = ISPConfigClient()
print(api._login())
"

Problemas de Migraciones 

Migraciones no aplicadas 

Síntoma: Errores de «relation does not exist» o «column does not exist».

# Ver estado de migraciones
docker-compose exec web python manage.py showmigrations

# Aplicar todas las migraciones pendientes
docker-compose exec web python manage.py migrate

Conflicto de migraciones 

Síntoma: Error «Conflicting migrations detected».

# Recrear migraciones (solo en desarrollo)
docker-compose exec web python manage.py makemigrations --merge

Migración falla con datos existentes 

Si una migración falla porque hay datos incompatibles:

# Opción 1: Migración en falso (marcar como aplicada sin ejecutar)
docker-compose exec web python manage.py migrate hosting 0006 --fake

# Opción 2: Rollback a migración anterior
docker-compose exec web python manage.py migrate hosting 0005

Problemas con Celery 

Celery no procesa tareas 

Síntoma: Las tareas programadas (facturación, fetch emails, SLA) no se ejecutan.

Verificar que el worker está corriendo:

docker-compose ps celery_worker celery_beat
docker-compose logs --tail=30 celery_worker

Verificar conexión a Redis:

docker-compose exec redis redis-cli ping
# Debe responder: PONG

Reiniciar los workers:

docker-compose restart celery_worker celery_beat

Verificar tareas programadas:

docker-compose exec web python manage.py shell -c "
from django_celery_beat.models import PeriodicTask
for t in PeriodicTask.objects.all():
    print(f'{t.name}: enabled={t.enabled}, last_run={t.last_run_at}')
"

Tarea falla con error de importación 

# Verificar que el módulo se puede importar
docker-compose exec celery_worker python -c "import billing.tasks"
docker-compose exec celery_worker python -c "import ticketing.tasks"

Problemas de Base de Datos 

PostgreSQL no arranca 

docker-compose logs db
# Si muestra errores de permisos en data directory:
sudo chown -R 999:999 ./postgres_data

# Si muestra "database files are incompatible":
# Backup y recrear volumen
docker-compose down
mv postgres_data postgres_data.old
docker-compose up -d db

Conexión rechazada a PostgreSQL 

# Verificar que db está sano
docker-compose exec db pg_isready -U noxpanel

# Verificar credenciales en .env
grep POSTGRES .env

Problemas de Email (Tickets)

Emails de tickets no se reciben 

Verificar que el servicio de fetch está activo:

docker-compose logs celery_worker | grep "fetch_emails"

Verificar la configuración de la cuenta de email desde el admin:
- Ir a /admin/ > Ticketing > Cuentas de Email
- Usar el botón Test Connection para verificar
Para OAuth2 (Microsoft/Google), verificar que los tokens no han expirado.

Problemas de SSL 

Let’s Encrypt no genera certificado 

Verificar que el dominio apunta correctamente a la IP del servidor
Verificar que el puerto 80 está accesible (necesario para validación ACME)

Revisar logs de Traefik:

docker logs traefik 2>&1 | grep -i "acme\|certificate\|letsencrypt"

Problemas de Rendimiento 

Panel lento 

Verificar uso de recursos:
```
docker stats --no-stream
```

Verificar cache:

docker-compose exec web python manage.py shell -c "
from django.core.cache import cache
cache.set('test', 'ok', 10)
print(cache.get('test'))
"

Verificar conexiones a BD:

docker-compose exec db psql -U noxpanel -c \
  "SELECT count(*) FROM pg_stat_activity;"

Logs y Diagnóstico 

Comandos útiles para diagnóstico general:

# Ver todos los logs
docker-compose logs -f

# Logs de un servicio específico
docker-compose logs -f web

# Estado de todos los servicios
docker-compose ps

# Entrar al shell del contenedor web
docker-compose exec web python manage.py shell

# Verificar configuración cargada
docker-compose exec web python -c "
from django.conf import settings
print(f'DEBUG: {settings.DEBUG}')
print(f'HOSTING_PROVIDER: {settings.HOSTING_PROVIDER}')
print(f'ISPCONFIG_URL: {settings.ISPCONFIG_URL}')
print(f'CELERY_BROKER: {settings.CELERY_BROKER_URL}')
"