--- título: «Configuración del sistema» descripción: «Arquitectura de seguridad, configuración de aplicaciones y opciones de implementación» ---

Configuración del sistema

La configuración del sistema controla el comportamiento de toda la aplicación, los parámetros de seguridad y la configuración de implementación. En esta sección se tratan la arquitectura de seguridad, la configuración de la aplicación y los modelos de implementación alternativos.

Arquitectura de seguridad

Aptli utiliza un modelo de seguridad de cuatro capas con aplicación de renderización del lado del servidor (SSR):

Capa 1: Autenticación Quién eres: verifica la identidad del usuario antes de permitirle el acceso. - Inicio de sesión con contraseña (con requisitos de complejidad). - Proveedores de OAuth (GitHub, Google). - Autenticación de dos factores (TOTP). - Se requiere validación por correo electrónico. - Gestión de sesiones con caducidad. - Bloqueo permanente tras intentos fallidos.

Capa 2: Derechos de administrador (permisivos) Lo que PUEDE modificar - Concesiones de permisos explícitos. - Crear/actualizar/eliminar permisos por modelo - Superderechos: `appSettingSchemasModify`, `adminRightsModify`, `viewDeleted` - Limitado a acciones (se puede crear, pero no eliminar) - Predeterminado: acceso de solo lectura

Capa 3: Restricciones de roles (restrictivas) Lo que NO se puede ver - Filtros de datos a nivel de campo. - Filtros de modelo + campo + comparación + valor - Se aplican en el lado del servidor antes de la consulta a la base de datos - No se pueden eludir mediante llamadas a la API, exportaciones o capturas de pantalla - Se combinan múltiples restricciones (lógica AND)

Capa 4: Aplicación del renderizado del lado del servidor (SSR) a nivel de API - Los datos realmente no existen para los usuarios no autorizados. - Todas las consultas se filtran del lado del servidor (API del servidor Nuxt). - Se aplican restricciones de roles antes de la búsqueda en MongoDB. - No hay filtrado del lado del cliente (no se puede eludir). - La API devuelve un error 404 para los registros no autorizados (incluso si el atacante conoce el ID).

Por qué es importante el SSR: - Filtrado del lado del cliente: datos enviados al navegador, ocultos con JavaScript (se pueden eludir mediante herramientas de desarrollo). - Filtrado del lado del servidor: los datos nunca se envían a usuarios no autorizados (seguro).

Aptli utiliza SSR: los datos no autorizados nunca llegan al cliente.

Configuración de la aplicación

Acceso requerido: derecho de administrador appSettingSchemasModify

Navega a: Admin → Configuración de la aplicación

Configuración de autenticación

Dominios permitidos: - Lista de dominios de correo electrónico que pueden registrar cuentas - Ejemplo: ["company.com", "contractor.com"] - Solo los correos electrónicos de estos dominios pueden registrarse - Predeterminado: su dominio de implementación

Permitir registro: - true: los usuarios pueden registrarse por sí mismos si el dominio coincide. - false: el administrador debe crear las cuentas manualmente. - Predeterminado: false (acceso controlado).

Métodos de inicio de sesión activos: - Nombre de usuario/Contraseña (casilla de verificación) - GitHub OAuth (casilla de verificación) - Google OAuth (casilla de verificación) - Se debe habilitar al menos un método - Predeterminado: solo nombre de usuario/contraseña

Requerir autenticación de dos factores: - true: todos los usuarios deben habilitar la autenticación de dos factores (2FA) (período de gracia configurable). - false: 2FA opcional. - Predeterminado: false.

Seguridad de la sesión

Número máximo de intentos de inicio de sesión: - Número de intentos fallidos antes del bloqueo definitivo - Rango válido: 3-10 intentos - Valor predeterminado: 5

Tiempo de cierre de sesión automático: - Tiempo de inactividad en segundos - La lectura/escritura de datos reinicia la cuenta atrás - Rango válido: 1 hora - 7 días - Valor predeterminado: 86400 (1 día)

Caducidad del token CSRF: - Tiempo de espera de la sesión del servidor en minutos - Obliga a volver a iniciar sesión independientemente de la actividad - Intervalo válido: 1 hora - 4 semanas - Valor predeterminado: 10080 (1 semana)

Caducidad de la sesión: - Duración máxima absoluta de la sesión - Se alinea con el token CSRF para usuarios de un solo dispositivo - Los usuarios de varios dispositivos pueden tener diferentes caducidades - Por defecto: 10080 minutos (1 semana)

Retención de datos

Retención de eliminación temporal: - Cuánto tiempo permanecen los registros eliminados temporalmente en la base de datos - Opciones: 30 días, 90 días, 1 año, indefinido - Predeterminado: 90 días - Se aplica a asignaciones, informes, usuarios, funciones (cuando se establece deletedAt)

Programa de compresión de versiones: - Frecuencia con la que se comprimen las versiones antiguas de las funciones - Opciones: semanal, mensual, trimestral - Predeterminado: mensual - Las versiones comprimidas siguen siendo reconstruibles (compresión sin pérdida).

Historial de transacciones: - Las transacciones de inventario nunca se eliminan (registro de auditoría inmutable). - Se pueden archivar en una base de datos independiente (configuración avanzada).

Valores predeterminados para nuevos usuarios

Roles para nuevos usuarios: - Matriz de ID de roles asignados automáticamente - Matriz vacía = sin restricciones automáticas - Predeterminado: [] (el administrador los asigna manualmente)

Derechos de administrador para nuevos usuarios: - Objeto con concesión de permisos - Objeto vacío = acceso solo para lectura - Predeterminado: {} (sin permisos de escritura)

Ejemplos de configuraciones:

Valores predeterminados del trabajador de campo: json { "roles": ["field_worker_role_id"], "adminRights": { "reportsCreate": true } }

Valores predeterminados del coordinador de oficina: json { "roles": [], "adminRights": { "assignmentsCreate": true, "ordersCreate": true, "stockItemsView": true } }

Claves API

Las claves API permiten que un sistema externo llame a Aptli sin que un humano inicie sesión — para sincronización ArcGIS/Postgres, exportación a data warehouse o sus propias herramientas. Gestión en Admin → Configuración de la aplicación → Claves API. Requiere appSettingSchemasModify.

Límites

Máximo 3 claves por despliegue. Revoque una clave existente antes de crear una nueva.
Cada clave tiene su propio bucket de límite de velocidad aislado (mismos umbrales que un usuario interactivo: ~2.700 solicitudes/minuto en lectura, ~900/minuto en escritura).

Claves de solo lectura

Al crear una clave puede activar Solo lectura. Una clave de solo lectura bloquea todas las solicitudes de escritura (POST / PUT / PATCH / DELETE) en la capa de sesión, incluso si se otorgaron derechos de escritura.

Revocar una clave

Haga clic en Revocar junto a la clave en la tabla. La revocación es inmediata.

Estado de las comunicaciones

La página de configuración incluye una sección plegada Estado de las comunicaciones (entre la lista de entornos y la Zona de peligro). Ábrala para ver el estado en vivo de los canales de mensajería:

Entrega de correo electrónico / SMS / push: indica si las credenciales del proveedor están configuradas y cuántos mensajes están pendientes o en reintento en cada cola. La falta de una clave de proveedor no produce errores: los mensajes se quedan en cola silenciosamente para siempre, y este panel es donde eso se hace visible.
Cuota de SMS: cuando se establece un límite mensual de SMS para la implementación, la fila de SMS muestra usados/límite del mes en curso y se vuelve ámbar cuando se alcanza el límite.
Backend de colas: indica si el almacén de tareas (Valkey) está conectado; una advertencia de respaldo en memoria significa que los mensajes en cola se perderán al reiniciar.
Destinatarios de alertas de seguridad: cuántas direcciones recibirán las alertas de bloqueo de cuentas y de cuota. Cero significa que esas alertas no llegan a ninguna parte; configure los destinatarios en esta misma página.
Cobertura de dominios de correo electrónico: cuando hay una lista de dominios permitidos activa, el número de usuarios activos cuyo dominio de correo electrónico ha quedado fuera de la lista (no pueden recibir ningún correo electrónico hasta que se actualice la lista o sean archivados).

Las filas muestran una marca verde cuando todo está en orden y una advertencia ámbar en caso contrario. Utilice Actualizar para volver a consultar el estado después de cambiar la configuración del entorno.

Implementación autohospedada

Aptli admite la implementación autohospedada (requiere licencia en modo autohospedado).

Modos de implementación

Modo SaaS (predeterminado): bash NUXT_REQUIRE_LICENSE=false - Sin validación de licencia - Aptli gestiona la infraestructura - Actualizaciones automáticas - Asistencia profesional incluida

Modo autohospedado: bash NUXT_REQUIRE_LICENSE=true NUXT_LICENSE_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..." - Se requiere validación de la licencia - El cliente gestiona la infraestructura - Actualizaciones manuales (se sustituye la carpeta .output) - Se requiere la clave de licencia de Aptli

Sistema de licencias

Cómo funciona: 1. Implemente la carpeta .output/ en su servidor. 2. El servidor genera un ID de implementación único (huella digital del hardware + nombre de host). 3. El periodo de prueba de 30 días comienza automáticamente. 4. Envíe el ID de implementación por correo electrónico a [email protected]. 5. Aptli genera una licencia JWT con los ID de implementación autorizados. 6. Actívela a través de la página /admin/license o la variable de entorno NUXT_LICENSE_KEY.

Implementación múltiple: - Cada servidor tiene un ID de implementación único - La licencia incluye una lista de todos los ID de implementación autorizados - No se puede clonar el servidor sin una nueva licencia - Impide la distribución no autorizada

Validación de la licencia: - Se comprueba al iniciar el servidor. - Si la licencia no es válida, la aplicación no se iniciará. - Si la versión de prueba caduca, se mostrará una advertencia durante 7 días y, a continuación, se bloqueará. - Renovación de la licencia por correo electrónico.

Variables de entorno (autoalojadas)

Requisitos: bash NUXT_MONGODB_URI=mongodb://localhost:27017/aptli NUXT_SESSION_PASSWORD=min-32-char-random-string

Opcional - OAuth:bash NUXT_OAUTH_GITHUB_CLIENT_ID=... NUXT_OAUTH_GITHUB_CLIENT_SECRET=... NUXT_OAUTH_GOOGLE_CLIENT_ID=... NUXT_OAUTH_GOOGLE_CLIENT_SECRET=...

Opcional - Correo electrónico: bash NUXT_RESEND_API_KEY=... [email protected]

Opcional - Escaneo de archivos: bash NUXT_ENABLE_FILE_SCAN=true NUXT_CLAMAV_HOST=localhost NUXT_CLAMAV_PORT=3310

Opcional - Licencia: bash NUXT_REQUIRE_LICENSE=true NUXT_LICENSE_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----..." NUXT_LICENSE_KEY=eyJhbGc... (auto-activate)

Requisitos de infraestructura

Mínimo: - 2 núcleos de CPU - 4 GB de RAM - 20 GB de almacenamiento (aumenta con los datos) - MongoDB 5.0+ - Node.js 20+

Recomendado: - 4 núcleos de CPU - 8 GB de RAM - 100 GB de almacenamiento SSD - Conjunto de réplicas MongoDB (alta disponibilidad) - Equilibrador de carga (escalado horizontal)

Servicios opcionales: - Daemon ClamAV (escaneo de archivos) - Redis (almacenamiento en caché de sesiones - mejora del rendimiento) - Servidor SMTP (notificaciones por correo electrónico)

Pasos de implementación

Compilar la aplicación: bash npm run build
Copiar salida: bash scp -r .output/ user@server:/aptli/
Establecer variables de entorno: Crear /aptli/.env con las variables necesarias.
Iniciar el servidor: bash cd /aptli/.output node server/index.mjs
Activar licencia: - Vaya a https://your-domain/admin/license - Copie el ID de implementación - Envíe un correo electrónico a [email protected] - Pegue la clave de licencia recibida - Haga clic en «Activar»
Configurar el proxy inverso: Nginx/Apache para el puerto proxy 3000 → HTTPS
Configurar el gestor de procesos: PM2 o systemd para mantener el servidor en funcionamiento.

Actualizaciones (autohospedadas)

Proceso de actualización manual: 1. Copia de seguridad de la base de datos: mongodump 2. Copia de seguridad del archivo .env 3. Descarga de la nueva carpeta .output/ desde Aptli 4. Detener el servidor: pm2 stop aptli 5. Reemplazar la carpeta .output/ 6. Restaurar el archivo .env 7. Iniciar el servidor: pm2 start aptli 8. Verificar: comprobar la versión en /admin/license

Aptli proporciona: - Notas de la versión con cambios importantes - Scripts de migración (si hay cambios en la base de datos) - Instrucciones de reversión - Asistencia profesional durante las actualizaciones

Mejores prácticas de seguridad

SSL/TLS requerido: - Utilizar HTTPS en producción (no HTTP) - Certificados gratuitos: Let's Encrypt - Rechazar conexiones HTTP (redirigir a HTTPS)

Configuración del cortafuegos: - Permitir: HTTPS (443), SSH (22) - Denegar: puerto MongoDB (27017) desde Internet público - Restringir: páginas de administración a VPN o lista blanca de IP

Seguridad de la sesión: - NUXT_SESSION_PASSWORD - mínimo 32 caracteres aleatorios - Rotación trimestral de la contraseña de sesión - Caducidad de sesión corta para entornos de alta seguridad

Seguridad de la base de datos: - Autenticación MongoDB habilitada - Credenciales de usuario independientes (no root) - Conexiones cifradas (MongoDB TLS) - Copias de seguridad periódicas (automatizadas, restauración probada)

Secretos de OAuth: - Almacenarlos en variables de entorno (no en código). - Rotarlos trimestralmente. - Revocar las aplicaciones OAuth que no se utilicen.

Seguridad en la carga de archivos: - Escaneo ClamAV habilitado en producción - Límites de tamaño de archivo aplicados - Tipos de archivo permitidos restringidos - Cuarentena de almacenamiento para archivos sospechosos

Supervisión: - Intentos fallidos de inicio de sesión (detección de fuerza bruta) - Fallos de autorización (detección de intentos de acceso no autorizado) - Patrones inusuales de uso de la API - Fallos de conexión a la base de datos

Consideraciones sobre el cumplimiento normativo

Residencia de datos: El modo autohospedado permite controlar la ubicación de los datos: - Alojamiento en una región geográfica específica - Cumplimiento de los requisitos normativos (RGPD, HIPAA, etc.) - Control físico del acceso a los datos

Registro de auditoría: Aptli mantiene registros de auditoría para: - Intentos de autenticación (éxitos/fracasos) - Uso de derechos de administrador (quién modificó qué) - Cambios en las restricciones de roles - Historial de transacciones (movimientos de inventario) - Historial de versiones (cambios en las funciones) - Eliminaciones temporales (quién eliminó qué y cuándo)

Exportación de datos: Todos los datos se pueden exportar para cumplir con la normativa: - Exportación CSV para datos no geográficos - Exportación GeoJSON para características (mediante el botón «Transferencia de datos» de la barra de herramientas del mapa) - Informes de transacciones (auditoría de inventario) - Registros de acceso de usuarios

Retención de datos: Políticas de retención configurables: - Período de retención de eliminación temporal - Compresión de versiones (sin pérdida) - Historial de transacciones (inmutable, nunca se elimina) - Registros de auditoría (archivo configurable)