===============================
Solución de Problemas
===============================

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

.. contents:: En esta página
   :local:
   :depth: 2

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:**

1. **Servicios no están corriendo**:

   .. code-block:: bash

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

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

2. **Puerto no expuesto / firewall**:

   .. code-block:: bash

      # 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

3. **Traefik no está corriendo**:

   .. code-block:: bash

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

4. **DNS no apunta al servidor**:

   .. code-block:: bash

      # 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:**

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

   .. code-block:: bash

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

2. El motor de hosting tarda varios minutos en iniciar (la primera vez puede tardar
   hasta 5-10 minutos). Verificar el healthcheck:

   .. code-block:: bash

      docker inspect --format='{{.State.Health.Status}}' \
        $(docker-compose ps -q hosting-core)

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

   .. code-block:: bash

      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:**

1. **Revisar logs del servidor web**:

   .. code-block:: bash

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

2. **Revisar logs de Nginx**:

   .. code-block:: bash

      docker-compose logs --tail=50 nginx

3. **Activar modo debug temporalmente** (solo desarrollo):

   .. code-block:: bash

      # En .env
      DEBUG=True

      # Reiniciar
      docker-compose restart web

   .. danger::

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

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

   .. code-block:: bash

      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:

.. code-block:: bash

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

.. code-block:: bash

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

.. code-block:: bash

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

.. code-block:: bash

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

1. **Verificar que el worker está corriendo**:

   .. code-block:: bash

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

2. **Verificar conexión a Redis**:

   .. code-block:: bash

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

3. **Reiniciar los workers**:

   .. code-block:: bash

      docker-compose restart celery_worker celery_beat

4. **Verificar tareas programadas**:

   .. code-block:: bash

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

.. code-block:: bash

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

.. code-block:: bash

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

.. code-block:: bash

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

1. Verificar que el servicio de fetch está activo:

   .. code-block:: bash

      docker-compose logs celery_worker | grep "fetch_emails"

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

3. Para OAuth2 (Microsoft/Google), verificar que los tokens no han expirado.

Problemas de SSL
==================

Let's Encrypt no genera certificado
--------------------------------------

1. Verificar que el dominio apunta correctamente a la IP del servidor
2. Verificar que el puerto 80 está accesible (necesario para validación ACME)
3. Revisar logs de Traefik:

   .. code-block:: bash

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

Problemas de Rendimiento
==========================

Panel lento
------------

1. **Verificar uso de recursos**:

   .. code-block:: bash

      docker stats --no-stream

2. **Verificar cache**:

   .. code-block:: bash

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

3. **Verificar conexiones a BD**:

   .. code-block:: bash

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

Logs y Diagnóstico
===================

Comandos útiles para diagnóstico general:

.. code-block:: bash

   # 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}')
   "