Solución de problemas de instalación

La mayoría de los problemas de instalación provienen de discrepancias de URL, SMTP faltante, puertos bloqueados o secretos perdidos. Empieza con la URL visible en tu navegador y trabaja hacia dentro.

Los enlaces públicos se abren en mi equipo pero no para los clientes

Comprueba qué URL se copió o envió.

• http://localhost/... funciona solo en el mismo equipo.
• http://192.168.x.x/... funciona solo en la red local o VPN. La VPN puede ser un puente válido para equipos internos, pero no es una estrategia de enlaces públicos para clientes.
• https://crm.example.com/... funciona públicamente solo cuando DNS, HTTPS, proxy y firewall son correctos.

Para enlaces públicos de clientes, despliega con un dominio público usando servidor público Ubuntu o Coolify.

El navegador muestra errores de CORS

CORS_ALLOWED_ORIGINS debe coincidir exactamente con el origen del navegador. Estos son orígenes diferentes:

https://crm.example.com
https://www.crm.example.com
http://crm.example.com
https://crm.example.com:8443

Corrige la variable, redespliega y reintenta en una sesión de navegador nueva.

El correo no se entrega

Comprueba esto primero:

• SMTP_HOST y SMTP_PORT son correctos.
• SMTP_AUTH=true cuando tu proveedor requiere autenticación.
• SMTP_STARTTLS=true para el puerto 587.
• SMTP_USERNAME y SMTP_PASSWORD son válidos.
• El proveedor permite el inicio de sesión SMTP/contraseña de aplicación.
• NOTIFICATIONS_EMAIL_ENABLED=true cuando los correos de notificación deben enviarse.

El compartido manual de enlaces públicos y la descarga de PDF pueden seguir funcionando sin SMTP.

Los enlaces de preferencias de notificación son incorrectos

Configura:

NOTIFICATIONS_PUBLIC_PREFERENCES_URL=https://<frontend-domain>/notifications/preferences

No lo dejes apuntando a localhost en un despliegue público.

Los contenedores Docker no están saludables

Ejecuta:

docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f gotenberg

Causas comunes:

• PostgreSQL aún está iniciándose.
• DB_PASSWORD difiere entre PostgreSQL y el backend.
• DB_ENCRYPTION_KEY falta o está malformada.
• Gotenberg no está saludable, por lo que la generación de PDF no puede iniciarse.
• Los puertos 80/443 del host ya están usados por otro servicio.

Tras corregir la configuración, reinicia el servicio afectado o el stack:

docker compose restart backend
docker compose up -d

Mi IP está bloqueada — no puedo iniciar sesión

Hay dos causas comunes: la lista de IP permitidas bloqueó el acceso o la protección contra fuerza bruta bloqueó tu IP tras demasiados intentos fallidos de inicio de sesión.

Bloqueo por lista de IP permitidas

QuoteNode tiene una lista de IP permitidas configurable en Configuración > Seguridad > Lista de IP permitidas (o mediante la variable SECURITY_IP_WHITELIST). Cuando está activada, protege toda la superficie de administración — incluidas las pantallas de inicio de sesión y 2FA — por lo que una dirección excluida recibe 403 IP_NOT_ALLOWED y ni siquiera puede iniciar sesión. (Los health checks y los enlaces públicos de ofertas para clientes siguen accesibles.)

Primero espera dos minutos si acabas de cambiarla en la aplicación. Una activación o restricción en la aplicación está protegida contra bloqueos: tu sesión debe volver a confirmarla dentro de una ventana corta (120 s por defecto), y si tu dirección actual no está incluida, la lista se revierte automáticamente a la anterior. Así, un autobloqueo accidental desde la pantalla de Seguridad se cura solo — espera y vuelve a intentarlo. (Esta red de seguridad no se aplica a la variable SECURITY_IP_WHITELIST, que se aplica al arrancar.)

Recuperación (anulación del operador): si sigues bloqueado — p. ej. una SECURITY_IP_WHITELIST del operador, una lista almacenada inválida o no puedes esperar — añade esta variable al entorno del contenedor backend (.env o sección environment: en docker-compose) y reinicia:

SECURITY_IP_WHITELIST_FORCE_DISABLE=true

docker compose restart backend

Esto desactiva completamente la lista de permitidos y permite iniciar sesión. Una vez dentro, corrige la lista en Configuración > Seguridad, luego elimina SECURITY_IP_WHITELIST_FORCE_DISABLE y reinicia de nuevo.

No dejes SECURITY_IP_WHITELIST_FORCE_DISABLE=true en producción. Desactiva todo el control de acceso por IP.

Bloqueo por protección contra fuerza bruta

QuoteNode bloquea direcciones IP tras demasiados intentos fallidos de inicio de sesión en una hora:

Umbral	Fallos en 1 h	Efecto
Soft	10	Retraso progresivo (1 s por intento adicional, máx. 30 s)
Bloqueo temporal	20	Bloqueado durante 5 minutos
Bloqueo permanente	50	Bloqueado hasta desbloqueo manual

Cómo desbloquear:

1. Panel de administración — otro administrador abre Configuración > Panel de seguridad > IPs bloqueadas y hace clic en Desbloquear.
2. Esperar — los bloqueos temporales expiran tras SECURITY_TEMP_LOCK_MINUTES (5 minutos por defecto). Los bloqueos permanentes no expiran por sí solos.
3. Elevar umbrales temporalmente si estás bloqueado y ningún otro admin puede ayudar. Añade al .env, reinicia, inicia sesión y luego elimina:

SECURITY_MAX_FAILED_LOGINS_SOFT=9999
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK=9999
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK=9999

Restaura los valores predeterminados tras recuperar el acceso.

Bloqueos de IP en enlaces públicos

El limitador de tasa de enlaces públicos bloquea direcciones IP que exceden los límites de intentos. Estos bloqueos están en memoria y expiran tras PUBLIC_RATE_LIMIT_IP_BLOCK_MINUTES (60 minutos por defecto) o tras un reinicio del backend.

El certificado HTTPS no se emite

Para despliegues públicos:

• DNS debe apuntar al servidor de despliegue.
• Los puertos 80 y 443 deben ser alcanzables desde internet.
• Solo un proxy debe terminar HTTPS para el mismo dominio.
• En Coolify, asigna el dominio al servicio frontend.

Perdí el archivo .env

Si perdiste .env, detente y evalúa antes de rotar valores.

• DB_PASSWORD puede restablecerse normalmente con acceso de administrador a PostgreSQL.
• TIMING_TOKEN_SECRET y PUBLIC_LINK_PASSWORD_SESSION_SECRET pueden regenerarse, pero las sesiones/tokens existentes pueden expirar.
• DB_ENCRYPTION_KEY es crítica. Sin la clave original, los valores cifrados no pueden descifrarse.
• Si el cifrado de PII está habilitado, los campos de cliente/contacto cifrados dependen de DB_ENCRYPTION_KEY.

Restaura .env desde backup siempre que sea posible.

Recuperación si se pierde .env pero existe copia de seguridad de la base de datos

1. Crea un nuevo .env con nuevos secretos.
2. Restaura la base de datos desde tu copia de seguridad (pg_dump / pg_restore).
3. Todos los datos de negocio (clientes, ofertas, productos, usuarios) serán totalmente accesibles.
4. Solo se pierden unos pocos campos: códigos MFA (los usuarios se vuelven a registrar), contraseña SMTP (volver a introducir en ajustes), clave API FX (volver a introducir). Si ENCRYPT_PII=true estaba habilitado, los datos de clientes cifrados también se pierden.

Si tus copias de seguridad están cifradas con age (por defecto), necesitas el archivo de identidad age de tu kit de recuperación para descifrarlas. Consulta la guía Backup y Restauración.

Olvidé la contraseña del administrador

Usa una ruta de recuperación no destructiva:

1. Si SMTP está configurado, usa la página de inicio de sesión: ¿Olvidaste tu contraseña?
2. Si otro administrador puede iniciar sesión, abre Usuarios en el panel de administración y restablece la contraseña.
3. Si ningún administrador puede iniciar sesión y el flujo de restablecimiento por correo no está disponible, restaura el acceso desde una copia de seguridad en buen estado o usa tu procedimiento de mantenimiento interno.

docker compose down -v no es un procedimiento de restablecimiento de contraseña. Elimina todos los datos — usuarios, ofertas, clientes, ajustes y copias de seguridad. Úsalo solo para entornos de prueba desechables.

Falla la verificación de licencia

Para despliegues reales, mantén:

LICENSE_SKIP_SIGNATURE_CHECK=false

Si una licencia válida aún falla, comprueba que el despliegue tiene la versión de aplicación esperada y un reloj de sistema sincronizado con NTP. Confirma que la licencia coincide con la edición/versión desplegada, luego contacta con soporte o reemplaza el archivo de licencia a través de la ruta de operador documentada. No configures el bypass de firma a true como solución temporal en producción.