Visión General de la Arquitectura ================================== NoxPanel es una plataforma modular de gestión de infraestructura cloud construida con **Django 5.0**, desplegada como un conjunto de contenedores Docker orquestados con Docker Compose. La arquitectura sigue un patrón **multi-tenant** donde cada organización (tenant) opera de forma aislada con sus propios recursos y cuotas. Aplicaciones Django -------------------- El proyecto se organiza en las siguientes aplicaciones Django: .. list-table:: :header-rows: 1 :widths: 20 80 * - App - Descripción * - ``accounts`` - Modelo de usuario personalizado (``AbstractUser``), roles (admin/client), control de acceso por módulo, perfiles de usuario. * - ``vms`` - Gestión de máquinas virtuales vía Proxmox VE. Templates, pools, nodos. * - ``hosting`` - Panel cPanel-like multi-tenant con motor de hosting. Sites, DNS, mail, FTP, bases de datos, certificados SSL, usuarios shell. * - ``billing`` - Facturación: planes de precios, suscripciones, facturas, pagos, integración con Stripe y PayPal, registro de uso por horas. * - ``ticketing`` - Helpdesk completo: tickets, departamentos, SLA, recepción de emails vía IMAP/POP3 y OAuth2 (Microsoft 365, Google), respuestas predefinidas. * - ``admin_panel`` - Panel de administración extendido con Jazzmin. Middleware de protección y vistas administrativas personalizadas. Diagrama de Servicios Docker ------------------------------ El siguiente diagrama muestra la relación entre los servicios Docker que componen NoxPanel: .. code-block:: text ┌─────────────────────────────┐ │ Internet / CDN │ └──────────────┬──────────────┘ │ ▼ ┌──────────────────────────────┐ │ Traefik (Reverse Proxy) │ │ SSL/TLS · Let's Encrypt │ └────────┬────────────┬────────┘ │ │ ┌──────────▼──┐ ┌─────▼──────────┐ │ nginx │ │ hosting-core │ │ static+proxy│ │ (hosting engine)│ └──────┬──────┘ │ SMTP/IMAP/FTP │ │ │ DNS/MySQL │ ▼ └────────┬────────┘ ┌─────────────┐ │ │ web │ │ │ (Django / │◄───────────┘ │ Gunicorn) │ API JSON └──┬───┬──┬──┘ │ │ │ ┌───────────┘ │ └───────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ db │ │ redis │ │ celery_worker│ │(Postgres │ │ (broker │ │ (tareas │ │ 15) │ │ + cache)│ │ async) │ └──────────┘ └──────────┘ └──────────────┘ │ ┌──────▼───────┐ │ celery_beat │ │ (scheduler) │ └──────────────┘ ┌──────────────┐ ┌──────────────┐ │ roundcube │ │ phpmyadmin │ │ (webmail) │ │ (DB admin) │ └──────────────┘ └──────────────┘ Servicios Docker ----------------- .. list-table:: :header-rows: 1 :widths: 20 15 65 * - Servicio - Imagen - Función * - ``web`` - noxpanel:testing - Aplicación Django principal servida con Gunicorn. Expone la API REST y las vistas del panel. * - ``db`` - postgres:15-alpine - Base de datos PostgreSQL. Almacena todos los modelos Django, sesiones, caché y datos de Celery Beat. * - ``redis`` - redis:7-alpine - Broker de mensajes para Celery y backend de resultados. También se usa para Channel Layers de WebSocket. * - ``celery_worker`` - noxpanel:testing - Worker de Celery con concurrencia 2. Ejecuta tareas asíncronas: facturación, sincronización con el motor de hosting, fetching de emails. * - ``celery_beat`` - noxpanel:testing - Planificador de tareas periódicas usando ``django_celery_beat``. Genera facturas mensuales, rastrea uso, verifica SLA. * - ``hosting-core`` - hosting-core:latest - Contenedor privilegiado con el motor de hosting completo. Incluye Apache, Postfix, Dovecot, BIND, Pure-FTPd, MySQL. * - ``nginx`` - nginx:alpine - Proxy reverso interno. Sirve archivos estáticos y reenvía peticiones a Django. Traefik lo expone al exterior. * - ``roundcube`` - roundcubemail:latest - Cliente webmail conectado al servidor IMAP del motor de hosting. Accesible en ``/webmail/``. * - ``phpmyadmin`` - phpmyadmin:latest - Interfaz web para gestionar las bases de datos MySQL del motor de hosting. Accesible en ``/phpmyadmin/``. * - ``filebrowser`` - filebrowser:latest - Gestor de archivos web para los sitios alojados en el motor de hosting. Permite navegación y edición de archivos del hosting. Redes Docker ------------- NoxPanel utiliza dos redes Docker: - **traefik-public** (externa): Conecta Traefik con ``nginx`` y ``hosting-core`` para exponer servicios al exterior con SSL/TLS automático. - **noxpanel-internal** (bridge): Red interna que conecta todos los servicios entre sí. Aísla el tráfico interno del exterior. Flujo de Datos --------------- 1. **Petición HTTP/S**: El usuario accede a ``https://dominio``. Traefik termina SSL y enruta a ``nginx`` (prioridad 10) o ``hosting-core`` (prioridad 100 para ``/hosting-admin/``). 2. **Nginx → Django**: ``nginx`` sirve archivos estáticos directamente y reenvía el resto a ``web`` (Gunicorn). 3. **Django procesa**: La petición pasa por los middleware (CORS, CSRF, autenticación, aislamiento de tenant) y llega a la vista o ViewSet. 4. **Operaciones del motor de hosting**: Para hosting, ``HostingService`` utiliza ``ISPConfigClient`` para comunicarse con la API JSON del motor de hosting en ``hosting-core:8080/remote/json.php``. 5. **Tareas asíncronas**: Operaciones largas (facturación, emails, sincronización) se encolan en Redis y Celery Worker las ejecuta en segundo plano. 6. **Base de datos**: Todos los modelos persisten en PostgreSQL. El motor de hosting mantiene su propia base MySQL interna para su funcionamiento. Arquitectura Multi-Tenant --------------------------- El sistema multi-tenant se implementa mediante: - **HostingTenant**: Modelo central que representa una organización. Cada tenant tiene cuotas independientes (sitios, bases de datos, dominios, storage, etc.). - **TenantUser**: Relación muchos-a-muchos entre usuarios y tenants con roles (admin, member, viewer) que determinan los permisos dentro del tenant. - **TenantIsolationMiddleware**: Middleware que inyecta el tenant activo en cada petición basándose en la membresía del usuario autenticado. - **TenantQuerySetMixin**: Mixin para ViewSets que filtra automáticamente los querysets por el tenant del usuario, garantizando aislamiento de datos. - **HostingPackage**: Paquetes predefinidos (S, M, XL, XXL) con cuotas estándar que se pueden asignar a tenants con ``apply_package_quotas()``. .. note:: El aislamiento estricto de tenant se controla mediante la variable de entorno ``TENANT_ISOLATION_STRICT``. Cuando está activo, los usuarios no-admin solo pueden acceder a recursos de su propio tenant. Integraciones Externas ----------------------- .. list-table:: :header-rows: 1 :widths: 20 80 * - Integración - Descripción * - **Motor de hosting** - API JSON en ``/remote/json.php``. Gestiona sites, DNS, mail, FTP, bases de datos, usuarios shell y certificados SSL. * - **Proxmox VE** - API REST para gestión de máquinas virtuales, templates y nodos. Soporta consola VNC/noVNC vía WebSocket. * - **Stripe** - Pasarela de pago principal. Suscripciones, cobros y webhooks para sincronización de estado de pagos. * - **PayPal** - Pasarela de pago alternativa. Modo sandbox para desarrollo y modo live para producción. * - **OAuth2** - Autenticación para cuentas de email: Microsoft 365 (Azure AD) y Google / Gmail para el sistema de ticketing. * - **IMAP/SMTP** - Protocolo estándar para recepción y envío de emails en ticketing. Soporta SSL/TLS y autenticación PLAIN. Stack Tecnológico ------------------ - **Backend**: Django 5.0, Django REST Framework, Django Channels - **Base de datos**: PostgreSQL 15 - **Cola de tareas**: Celery + Redis 7 - **Servidor web**: Gunicorn + Nginx + Traefik - **Frontend**: HTML5, CSS3 (tema Nova personalizado), JavaScript vanilla - **Admin**: Django Admin con tema Jazzmin (tema Darkly) - **Monitorización**: django-prometheus, Sentry (opcional) - **Contenerización**: Docker + Docker Compose 3.9