Instalar n8n en un VPS con Docker: guía completa 2026

La versión cloud de n8n factura por ejecución más allá del plan y limita el número de workflows activos. En su VPS, el único coste es el del servidor, con independencia del número de automatizaciones o de llamadas API. Conserva además el control total sobre los credentials, las cargas útiles de los webhooks y el historial de ejecuciones — ningún dato transita por una infraestructura de terceros.

Antes de empezar, compruebe que su VPS cumple los requisitos siguientes. Para un uso moderado, 1 vCPU y 1 GB de RAM bastan; prevea 2 vCPU y 2 GB en cuanto ejecute workflows pesados o concurrentes, y 4 GB si conecta una base PostgreSQL dedicada o integra un modelo de IA local. Cuente con 10 GB de disco como mínimo para Docker, los volúmenes y los logs. El puerto 5678 no debe exponerse directamente — n8n solo escucha en 127.0.0.1:5678 y todas las peticiones pasan por el reverse proxy en el puerto 443. Se requiere un subdominio (por ejemplo n8n.su-dominio.com) que apunte a la IP del VPS para HTTPS y los webhooks entrantes. Son necesarios Docker Engine 24+ y Docker Compose v2.

En agosto de 2026, el advisory GHSA-vrv8-j27g-g7cr reveló que tres nodes vuelcan los credentials descifrados en los datos de ejecución persistidos en caso de error: el node Strapi (tokens OAuth escritos en claro en execution_data), el node SeaTable (claves API inscritas en los logs de ejecución de error) y el node Mailcheck (credenciales SMTP persistidas en execution_data). Estos secretos quedan legibles para cualquier usuario con acceso a los logs de ejecución en la interfaz de n8n. En una instancia sin pruning, se acumulan indefinidamente.

Síntoma. La instancia n8n se detiene bruscamente con el error FATAL ERROR: invalid-mark-compact are transition en los logs de Docker. El contenedor se reinicia si restart: unless-stopped está configurado, pero el crash se reproduce en cuanto la carga vuelve a pasar el mismo umbral.

Causa. Este error es un pánico del motor V8 durante un ciclo de garbage collection. Se desencadena cuando el heap de V8 está saturado — típicamente a partir de 30 workflows ejecutándose simultáneamente en un VPS con menos de 2 GB de RAM.

Corrección inmediata. Añada NODE_OPTIONS=--max-old-space-size=2048 en el entorno. Reinicie el contenedor: docker compose restart n8n.

Corrección estructural. Asigne al menos 2 GB de RAM a la VM por encima de 30 workflows activos. Para más de 50 workflows, prefiera el modo queue con Redis. Fuente: community.n8n.io thread #308425.

Síntoma. Las peticiones cortas tienen éxito pero ciertos workflows devuelven 502 Bad Gateway desde nginx exactamente 60 segundos después del inicio de la ejecución.

Causa. nginx espera por defecto 60 segundos una respuesta del backend (proxy_read_timeout = 60 s). Si la ejecución tarda más, nginx corta la conexión.

Corrección. Añada en el bloque location de nginx:

proxy_read_timeout 300;
proxy_send_timeout 300;

Recargue nginx: nginx -t && systemctl reload nginx. Fuente: community.n8n.io thread #274581.

Tres cambios de las versiones recientes pueden romper silenciosamente una instancia existente.

Renombrado del parámetro OAuth 2.0 en HTTP Request. Las peticiones autenticadas con OAuth 2.0 pueden dejar de funcionar sin mensaje de error explícito.

Formato de la URL de webhook. Si ha copiado URL de webhook fijas en servicios de terceros, vuelva a comprobarlas tras la actualización.

Obsolescencia de $item(). Su reemplazo es $input.item o $('Nombre del node').item.

La lista completa está disponible en la documentación oficial de n8n.

El puerto 5678 es inaccesible. Compruebe que el contenedor funciona y que escucha en 127.0.0.1:5678.

Los webhooks muestran localhost. La variable N8N_WEBHOOK_URL está ausente — añádala con la barra final y reinicie.

Error de permisos en el volumen. chown -R 1000:1000 /opt/n8n/data y reinicie el contenedor.

La base PostgreSQL rechaza la conexión. Compruebe la red Docker y las variables de entorno.

Crash V8 brutal. Añada NODE_OPTIONS=--max-old-space-size=2048. Vea la sección dedicada.

502 Bad Gateway persistente. Lleve proxy_read_timeout a 300 s. Vea la sección dedicada.

Credentials visibles en los logs. Actualice n8n y active el pruning. Vea la sección dedicada.

Rollback silencioso de SQLite bajo carga. Síntoma: ejecuciones desaparecidas o resultados inconsistentes sin error visible bajo alta concurrencia. Causa: SQLite no soporta escrituras concurrentes (issue GitHub n8n #32284). Solución única: migrar a PostgreSQL.

SQLite es un motor de pruebas, no un motor de producción. Es perfectamente adecuado para descubrir n8n en local o validar un workflow antes de desplegarlo. En cuanto su instancia recibe tráfico real — múltiples workflows lanzados en paralelo, webhooks entrantes, ejecuciones planificadas simultáneas — SQLite se convierte en un riesgo. El issue GitHub n8n #32284 documenta rollbacks silenciosos bajo carga concurrente: las ejecuciones desaparecen del historial sin mensajes de error, y los resultados intermedios se escriben de forma parcial.

Migrar a PostgreSQL. El procedimiento en tres pasos:

1. Exporte los workflows existentes: n8n export:workflow --all --output=/opt/n8n/workflows-backup.json
2. Modifique el .env para cambiar el motor: DB_TYPE=postgresdb con las variables correspondientes.
3. Reinicie todo (docker compose up -d) e importe: n8n import:workflow --input=/opt/n8n/workflows-backup.json.

Almacenamiento persistente independiente. El volumen PostgreSQL (pg_data) debe montarse en un almacenamiento persistente independiente del host. Verifique siempre con docker volume ls que el volumen existe.

Dimensionamiento. PostgreSQL consume entre 50 y 100 MB de RAM adicional en carga ligera. Planifique al menos 2 GB de RAM para n8n + PostgreSQL en el mismo VPS; 4 GB si ejecuta regularmente workflows de IA o importaciones voluminosas.

Estos cuatro puntos concentran la mayor parte de los incidentes reportados en community.n8n.io y DEV Community en 2026. Cada uno es independiente y puede aplicarse a una instancia existente sin redespliegue completo.

1. N8N_WEBHOOK_URL es obligatorio en el .env. Sin esta variable, n8n reconstruye la URL de webhook combinando el hostname interno del contenedor y el puerto 5678. El resultado es una URL inutilizable desde cualquier servicio externo. Además, la URL cambia en cada recreación del contenedor. Establezca N8N_WEBHOOK_URL=https://n8n.su-dominio.com/ (con barra final) y no la omita nunca.

2. RAM mínima 2 GB, recomendada de 4 a 8 GB. Un VPS con 1 GB de RAM es insuficiente en cuanto n8n ejecuta varios workflows simultáneamente. El OOM killer de Linux termina el proceso Node.js sin log explícito en n8n, creando un ciclo de crashes difícil de diagnosticar. El mínimo documentado por n8n para producción es 2 GB; 4 a 8 GB se recomiendan para instancias con workflows de IA o más de 20 workflows activos.

3. Headers WebSocket de nginx son obligatorios para el editor. La interfaz de n8n se comunica con el backend vía WebSocket para la ejecución en tiempo real. Sin estos dos headers en el bloque location de nginx, la conexión WebSocket es rechazada y el editor queda inaccesible o se congela:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Caddy los gestiona automáticamente; con nginx deben añadirse explícitamente.

4. Purga automática del historial de ejecución. Sin purga, la tabla de ejecuciones crece indefinidamente. En una instancia activa durante meses puede llegar a varios gigabytes y degradar significativamente el rendimiento. Active la purga con:

EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=168

El valor 168 corresponde a 7 días expresados en horas. Ajuste según su necesidad de retención.

Para las actualizaciones, dos enfoques: Watchtower o una tarea cron manual (docker pull n8nio/n8n:latest && docker compose up -d). En ambos casos, lea las notas de versión antes de una actualización mayor. Mantenga sus exportaciones de workflows al día en un repositorio git.

Para los advisories de seguridad, siga la página GitHub Security Advisories del repositorio n8n.