n8n 3.0: migrar de npm a Docker antes de octubre de 2026

Qué cambia con n8n 3.0 y por qué actuar ahora

Riesgos de posponer la migración a octubre

• Migración bajo presión — migrar en urgencia mientras corren automatizaciones críticas expone a errores de configuración difíciles de diagnosticar.
• Pérdida de datos SQLite — el issue #22341 de GitHub documenta casos donde contenedores Docker actualizados sin precauciones provocaron una regresión de la base de datos: los flujos de trabajo vuelven al estado de una copia de seguridad antigua.
• Sin parches de seguridad — una instancia npm congelada en 2.x no recibe parches de seguridad ni correcciones de estabilidad para la rama 3.x.
• Incompatibilidad creciente — las integraciones, nodos comunitarios y webhooks dependen de APIs que evolucionan; quedarse en una versión muerta genera deuda de incompatibilidad creciente.
• Duración impredecible — una migración bien preparada tarda una hora; una improvisada puede ocupar un día entero con los flujos de trabajo parados.

Requisitos previos antes de empezar

Lo que necesitas

• VPS con acceso root — Ubuntu 22.04 o Debian 12 recomendados, mínimo 2 vCPU y 2 GB de RAM para n8n solo, 4 GB si añades PostgreSQL en el mismo servidor.
• Docker Engine y Docker Compose v2 — comprueba con docker --version y docker compose version (sintaxis sin guión, plugin v2).
• PostgreSQL recomendado — n8n admite SQLite y PostgreSQL, pero SQLite en Docker conlleva riesgos de pérdida de datos en actualizaciones mal gestionadas (cf. issue #22341).
• Acceso a la instancia npm actual — la migración requiere exportar los flujos de trabajo mediante la API REST antes de detener la instancia antigua.
• Un nombre de dominio y un certificado TLS — your-domain.com con Let's Encrypt vía Nginx como reverse proxy.
• Una ventana de mantenimiento planificada — aunque sea breve, evita perder ejecuciones en curso.

Detectar tu modo de lanzamiento actual

Detectar, exportar, desplegar y validar

1. 01

   Identificar el proceso n8n

   Busca el ejecutable en ejecución: which n8n muestra la ruta si n8n está instalado globalmente vía npm. Luego comprueba si un servicio del sistema lo supervisa: systemctl status n8n. Si no existe servicio systemd, busca un proceso activo: ps aux | grep n8n. Un resultado con npx n8n confirma una instalación npm.

2. 02

   Localizar el archivo de configuración y la base de datos

   El directorio de datos predeterminado es ~/.n8n/. Comprueba su contenido: ls -la ~/.n8n/. El archivo database.sqlite indica una base SQLite. Anota la ruta completa — la necesitarás para la exportación.

3. 03

   Exportar todos tus flujos de trabajo mediante la API REST

   Obtén primero una clave API desde la interfaz (Settings → API → Create API Key), luego exporta: curl -s -H 'X-N8N-API-KEY: TU_CLAVE' http://localhost:5678/api/v1/workflows | python3 -m json.tool > workflows-export-$(date +%Y%m%d).json. Verifica que el archivo contiene tus flujos antes de cualquier operación.

4. 04

   Detener correctamente la instancia npm

   Si está supervisada por systemd: systemctl stop n8n && systemctl disable n8n. Si está lanzada manualmente, identifica el PID (pgrep -f n8n) y luego kill -SIGTERM <PID>. Espera unos segundos a que n8n termine las ejecuciones en curso.

5. 05

   Crear el archivo docker-compose.yml con PostgreSQL

   Crea un directorio dedicado: mkdir -p /opt/n8n && cd /opt/n8n. Luego crea el archivo docker-compose.yml con el contenido completo mostrado en la versión francesa, adaptando contraseñas y usando your-domain.com. La versión está fijada en n8nio/n8n:2.38.4 (estable a 2026-09-09). Nunca uses :latest.

6. 06

   Arrancar el stack e importar los flujos de trabajo

   Lanza el stack: docker compose up -d. Espera a que ambos contenedores estén sanos: docker compose ps. Una vez n8n accesible en http://127.0.0.1:5678, importa los flujos de trabajo vía API y verifica en la interfaz que están presentes y activos.

7. 07

   Configurar Nginx como reverse proxy con TLS

   Instala Nginx y Certbot: apt install nginx certbot python3-certbot-nginx -y. Crea la configuración Nginx con proxy_pass a http://127.0.0.1:5678, cabeceras WebSocket y timeout de lectura de 300 segundos. Activa el sitio y obtén el certificado: certbot --nginx -d your-domain.com.

8. 08

   Validar que la migración ha tenido éxito

   Realiza estas comprobaciones en orden: 1) accede a https://your-domain.com — la página de inicio de sesión aparece sin advertencia TLS; 2) verifica que tus flujos de trabajo están presentes y activos; 3) lanza manualmente un flujo simple para validar la ejecución completa; 4) actualiza los webhooks si servicios externos apuntan a la URL o puerto anteriores; 5) revisa los logs después de 24 horas: docker compose logs n8n --since 24h | grep -i error.

Resolución de problemas: casos comunes tras la migración

Problemas y soluciones

• Flujos vacíos tras la importación — verifica que el formato JSON exportado coincide con lo que espera la API de importación; algunas versiones de n8n exportan { data: [] }, otras un array directo.
• Webhooks que no responden — WEBHOOK_URL debe coincidir exactamente con la URL pública de tu instancia (con https://).
• Credenciales inaccesibles — las credenciales están cifradas con N8N_ENCRYPTION_KEY. Recupérala desde ~/.n8n/.n8n_encryption_key en la instancia npm y configúrala como variable de entorno.
• Regresión de la base SQLite (issue #22341) — si has conservado SQLite temporalmente, asegúrate de que el volumen Docker esté montado de forma persistente. La migración a PostgreSQL sigue siendo la solución definitiva.
• Error ECONNREFUSED en PostgreSQL — la condición depends_on.postgres.condition: service_healthy y el healthcheck pg_isready garantizan que n8n espere a que PostgreSQL esté listo.

Una migración que hacer ahora, no en octubre