Cómo actualizar n8n en Docker sin perder workflows ni credenciales

Respuesta directa: sí, puedes actualizar n8n en Docker Compose sin perder workflows ni credenciales si la nueva instancia vuelve a usar exactamente la misma base de datos, el mismo volumen o bind mount persistente y la misma clave de cifrado. Una actualización controlada no parte de asumir que n8n borró datos: primero identifica dónde viven, crea un respaldo coherente, fija una versión estable, actualiza y valida antes de retirar el punto de restauración.

La documentación oficial de bases de datos de n8n indica que SQLite guarda por defecto credenciales, ejecuciones y workflows, y que PostgreSQL también es compatible. Por eso, cambiar solo la imagen del contenedor no basta para proteger la instancia: el activo recuperable es la combinación de base de datos, almacenamiento persistente y N8N_ENCRYPTION_KEY o archivo de configuración que contiene la clave.

Respuesta corta: la ruta segura en siete pasos

1. Haz inventario del proyecto Compose, servicios, versión, imagen, base de datos y montajes reales.
2. Localiza el origen de N8N_ENCRYPTION_KEY sin mostrar su valor.
3. Define una ventana de mantenimiento y detén todos los procesos n8n que puedan escribir.
4. Respalda el volumen o bind mount y crea una copia coherente de SQLite o un pg_dump de PostgreSQL.
5. Fija una versión estable concreta; no dejes una etiqueta flotante como única estrategia de actualización.
6. Ejecuta docker compose pull y docker compose up -d, y comprueba estado, logs, HTTP y funciones reales.
7. Conserva la versión y el respaldo anteriores hasta completar las pruebas; si falla, restaura la base previa antes de iniciar la imagen anterior cuando exista riesgo de migraciones incompatibles.

Los comandos de esta guía son procedimientos documentados y adaptables. Sustituye cada placeholder, confirma nombres y rutas en tu propio Compose y pruébalos en un entorno de ensayo. No se presentan como comandos ejecutados por Teramont.

Cuándo actualizar y cuándo conviene esperar

n8n recomienda mantener la instalación al día, revisar las notas de versión e intentar actualizar al menos una vez al mes. Eso no significa desplegar cualquier etiqueta en producción en cuanto aparece.

Como referencia temporal, GitHub Releases de n8n mostraba 2.31.6 como versión estable publicada el 24 de julio de 2026 y 2.32.5 como pre-release. Verifica siempre cuál es la última estable en el momento de ejecutar; no copies esa cifra como una versión permanente.

SQLite frente a PostgreSQL: qué debes preservar

No es obligatorio migrar de SQLite a PostgreSQL para una actualización corriente. Ambos están contemplados por n8n; una migración de motor es un proyecto separado y debe justificarse por requisitos operativos, no mezclarse innecesariamente con el cambio de versión.

Prerrequisitos antes de tocar la instancia

• Acceso al directorio y a los mismos archivos Compose y .env que usa producción.
• Permisos para leer montajes, detener servicios, crear backups y restaurar en un recurso separado.
• Espacio libre para el backup, la nueva imagen y una copia restaurada sin borrar el estado fallido.
• La versión actual, la versión objetivo estable y las notas de cambios entre ambas.
• Una lista de pruebas: acceso a UI, workflows representativos, credenciales, webhook, agenda, workers y task runners si aplican.
• Una ventana de mantenimiento comunicada y un criterio claro de seguir o revertir.

Si usas queue mode o múltiples workers, identifica todos los procesos que escriben y detén o drena todos ellos, no solo el servicio principal. Si hay datos binarios en filesystem, almacenamiento de objetos, mounts adicionales o nodos comunitarios, incorpóralos al inventario.

1. Inventario: verifica la instancia y el mount reales

Ejecuta el inventario desde el directorio y con los mismos argumentos -f, --env-file y nombre de proyecto de producción. Un nombre de proyecto Compose o directorio distinto puede crear nombres de volumen distintos. La guía oficial de n8n con Docker Compose muestra la persistencia de /home/node/.n8n; tu fuente real debe confirmarse, no suponerse.

Resultado esperado: Compose valida sin imprimir toda la configuración; reconoces el servicio correcto, la versión actual y un mount persistente que llega al destino previsto. docker compose exec recibe el nombre del servicio Compose; docker inspect recibe el ID o nombre del contenedor. No los intercambies.

Registra además la ruta de SQLite o, en PostgreSQL, el nombre del servicio Compose de la base y el nombre lógico de la base. Si PostgreSQL es externo, registra el endpoint y el método de autenticación, pero nunca copies contraseñas a tickets o logs.

Comprueba el origen de la clave sin revelarla

n8n documenta N8N_ENCRYPTION_KEY como la clave usada para cifrar credenciales. Si no proporcionas una clave personalizada, n8n genera una en el primer arranque y la guarda en su carpeta de configuración. La base sin esa clave puede conservar workflows, pero no permite descifrar correctamente las credenciales.

Estos comandos solo comprueban presencia. Evita printenv, env, un docker inspect de todas las variables o la salida completa de docker compose config en una terminal grabada: podrían exponer secretos. Respalda la fuente real de la clave —archivo .env, secreto administrado o archivo de configuración persistente— con acceso restringido.

2. Prepara el punto de restauración

Crea un directorio privado y registra versión, imágenes y archivos declarativos. Ajusta <COMPOSE_FILE> al nombre real. La copia de .env puede contener secretos: protégela, cifra el backup en reposo y envía una copia fuera del host después de verificarla.

Exportaciones CLI: capa adicional, no backup completo

La CLI oficial de n8n permite exportar workflows y credenciales. Úsala como una segunda capa legible o versionable antes de detener la instancia, pero no como sustituto del backup de base, clave y archivos. La exportación normal de credenciales permanece cifrada; no recomendamos --decrypted por defecto porque dejaría secretos en texto plano.

Resultado esperado: se crean archivos de exportación sin mostrar credenciales en pantalla. Incluye ese directorio en el archivo del mount. Recuerda que las exportaciones conservan IDs y que una importación posterior puede sobrescribir entidades con IDs coincidentes.

3. Detén escritores y respalda el almacenamiento persistente

Detén explícitamente el servicio principal y todos los workers o escritores n8n. Los ejemplos usan <N8N_SERVICE> <N8N_WORKER_SERVICE>: elimina el segundo placeholder si no tienes workers o añade todos los nombres de servicio si tienes varios. Mantén <POSTGRES_SERVICE> en ejecución para poder hacer pg_dump; no lo incluyas en el comando stop. Para un volumen nombrado, el siguiente ejemplo usa una imagen auxiliar fijada; tenla disponible antes de la ventana y sustituye los placeholders.

Para un bind mount, archiva la ruta de origen que devolvió docker inspect, también con el servicio principal y todos los workers detenidos. $BACKUP_DIR debe quedar fuera de <N8N_BIND_SOURCE>: si está dentro, aborta y redefine o mueve el directorio de backup antes de continuar para evitar que el archivo tar intente incluirse a sí mismo.

Si SQLite está dentro de ese mount, detener n8n antes de archivarlo evita presentar la copia de una base activa como coherente. Si DB_SQLITE_DATABASE apunta a otro mount, respáldalo también. Un listado de tar sin errores solo demuestra que el archivo es legible; una restauración de ensayo es la prueba más útil.

Backup de PostgreSQL

Con los escritores n8n detenidos, crea un dump en formato personalizado. En este ejemplo <POSTGRES_SERVICE> es el nombre del servicio Compose, no container_name. No incluyas una contraseña en el comando: usa el mecanismo de autenticación ya configurado, .pgpass con permisos correctos o un secreto administrado.

Resultado esperado: pg_dump termina con código cero, el archivo no está vacío y pg_restore --list puede leerlo. La documentación de PostgreSQL explica que el formato custom es flexible para restauraciones. Si la base es externa, ejecuta una versión compatible de pg_dump desde un cliente autorizado y conserva el mismo criterio de no exponer contraseñas.

El dump de PostgreSQL no reemplaza el archivo del mount n8n: la clave generada automáticamente, los binarios en filesystem y los nodos comunitarios pueden seguir allí. Conserva ambos respaldos.

4. Fija la versión estable antes de actualizar

Guarda la versión en una variable o escribe la etiqueta directamente en Compose. El objetivo es que la versión anterior y la objetivo sean inequívocas. Si usas task runners externos, fija una versión compatible para su imagen y revisa las instrucciones oficiales específicas.

Reemplaza el placeholder por la versión estable verificada en las notas de versión. Guarda también <PREVIOUS_VERSION> y, si tu política lo requiere, el digest de la imagen. No cambies al mismo tiempo el motor de base, el proxy, Docker y n8n: separar cambios reduce la ambigüedad si algo falla.

5. Actualiza con Docker Compose

Con el backup validado y n8n detenido, valida la sintaxis, descarga solo las imágenes de n8n que deseas cambiar y levanta el proyecto. Añade el servicio de runners al pull si corresponde; evita actualizar PostgreSQL accidentalmente como parte del mismo cambio.

Resultado esperado: el servicio aparece Up o healthy, la versión coincide con el objetivo y los logs no muestran fallos de conexión, descifrado o migración. La documentación de Docker Compose up señala que, al recrear un servicio por cambio de imagen o configuración, preserva los volúmenes montados.

No uses docker compose down -v en una actualización corriente. Docker documenta que la opción -v elimina volúmenes nombrados declarados y volúmenes anónimos adjuntos. Tampoco hagas prune de volúmenes durante la ventana.

6. Valida en capas antes de declarar éxito

Estado de contenedor, logs y HTTP

n8n expone por defecto /healthz y una comprobación de readiness. Ajusta la URL si modificaste N8N_ENDPOINT_HEALTH o usas un subpath.

Un código HTTP correcto es necesario, pero no suficiente. Los endpoints de monitorización de n8n confirman disponibilidad técnica; no demuestran que cada integración siga funcionando.

Checklist funcional

Define antes del cambio cuánto dura la observación y qué fallo activa rollback. Conserva el backup hasta superar tanto las pruebas inmediatas como al menos un ciclo representativo de webhooks o tareas programadas.

7. Rollback exacto si la actualización falla

Volver a fijar la imagen anterior no siempre basta. Una versión nueva puede haber aplicado migraciones de esquema; iniciar una imagen antigua contra esa base ya migrada puede ser inseguro. Lee las notas de versión y, si no puedes demostrar compatibilidad hacia atrás, restaura el punto previo y arranca la imagen anterior sobre esa restauración.

Rollback conservador con SQLite

Preserva el volumen fallido para diagnóstico. Crea un volumen nuevo, restaura el archivo previo allí y cambia Compose para montar ese volumen junto con <PREVIOUS_VERSION>. Detén el servicio principal y todos los workers antes de restaurar; elimina <N8N_WORKER_SERVICE> si no existe o añade todos los nombres si hay varios. Así no sobrescribes la única evidencia del fallo.

Fija N8N_VERSION=<PREVIOUS_VERSION> e incorpora este fragmento en tu Compose existente. Elimina el servicio de worker si no aplica o replica el mount en todos los workers que lo necesiten; conserva sus demás opciones.

external: true y name: <N8N_RESTORE_VOLUME> obligan a Compose a usar el volumen que acabas de restaurar. Sin name: externo, Compose puede resolver un volumen prefijado por el proyecto distinto y n8n podría arrancar como una instancia vacía. Valida el archivo y solo entonces inicia los servicios:

Para un bind mount, extrae el backup a un directorio nuevo y apunta Compose a él; no lo extraigas sobre el directorio fallido. Confirma que la fuente de la clave coincide con la del backup antes de iniciar.

Rollback conservador con PostgreSQL

Crea una base nueva, vacía y con nombre único; restaura el dump, cambia DB_POSTGRESDB_DATABASE a esa base, recupera también el mount n8n previo cuando sea necesario y fija la imagen anterior. Elimina <N8N_WORKER_SERVICE> del comando si no existe o añade todos los escritores. No detengas <POSTGRES_SERVICE>: debe permanecer disponible para createdb y pg_restore.

Valida el rollback con el mismo checklist. Todo dato creado después del punto de respaldo quedará fuera de la restauración; por eso la ventana, el drenaje y el registro de la hora de corte importan. No elimines la base migrada ni el volumen fallido hasta cerrar la investigación.

Fallos comunes y diagnóstico

Mantenimiento mensual que hace más fácil la próxima actualización

• Revisa al menos mensualmente la versión estable y las notas de cambios; prueba primero en staging cuando el impacto lo justifique.
• Automatiza backups de la base y del almacenamiento persistente, pero supervisa fallos y ensaya restauraciones.
• Mantén un inventario versionado de Compose, mounts, nombres de servicio, versión y ubicación de secretos, sin guardar valores secretos en el repositorio.
• Conserva una copia fuera del host y una política de retención acorde con tus requisitos.
• Vigila disco, tamaño de base, ejecuciones retenidas, reinicios y salud de workers.
• Separa la actualización de n8n de cambios de PostgreSQL, sistema operativo, Docker, proxy o DNS siempre que sea posible.
• Documenta RTO, RPO, responsable de la ventana y criterio de rollback.

¿Cuándo revisar la infraestructura del VPS?

Una actualización segura necesita espacio para dos estados, margen de I/O para el backup y visibilidad durante la restauración. Si el host actual no permite conservar una copia adicional o probar un restore sin agotar recursos, el problema ya no es solo el comando de actualización. Al evaluar VPS hosting, prioriza capacidad suficiente, almacenamiento persistente bien identificado, copias externas y un procedimiento reproducible de recuperación; la elección de plan debe partir de tu carga real.

Preguntas frecuentes

¿Actualizar n8n borra los workflows?

No debería hacerlo por el simple cambio de imagen cuando la base persistente correcta vuelve a montarse. Si aparecen workflows “perdidos”, verifica primero si arrancaste otra base, volumen, ruta o proyecto Compose. Los casos comunitarios son señales de diagnóstico, no una tasa ni una causalidad universal.

¿Basta con copiar el volumen Docker?

Depende. Con SQLite puede contener base, configuración y clave, pero la copia debe ser coherente y abarcar cualquier ruta personalizada. Con PostgreSQL necesitas además el dump de la base. Los datos binarios en almacenamiento externo también requieren su propia política.

¿Debo migrar de SQLite a PostgreSQL antes de actualizar?

No como requisito general. Haz la actualización y una posible migración como cambios separados, salvo que una instrucción oficial específica para tu versión indique otra cosa.

¿Puedo hacer rollback cambiando solo la etiqueta de imagen?

Solo si confirmas que la base no fue migrada de forma incompatible. El rollback conservador combina la imagen anterior con la base o volumen restaurados desde el punto previo.

¿Los exports CLI reemplazan el backup?

No. Son una capa adicional útil, pero no sustituyen la base completa, la clave de cifrado, los binarios ni la configuración. Evita exports de credenciales desencriptadas salvo un procedimiento excepcional y fuertemente protegido.

Conclusión: actualiza solo después de poder restaurar

La pregunta correcta no es “¿qué comando descarga n8n?”, sino “¿puedo demostrar qué datos usa esta instancia y devolverlos a un estado conocido?”. Haz inventario, detén escritores, respalda base y clave, fija una versión estable, usa pull y up -d, prueba salud y automatizaciones reales, y conserva un rollback que restaure el estado previo. Si cualquiera de esas piezas falta, espera: una ventana pospuesta cuesta menos que una recuperación improvisada.

Fuentes

1. n8n Docs: Update n8n.
2. n8n Docs: Use Docker Compose.
3. n8n Docs: Supported databases settings y su ubicación oficial actual.
4. n8n Docs: Deployment environment variables.
5. n8n Docs: Use the command line.
6. n8n en GitHub: Releases.
7. n8n Docs: Monitor n8n.
8. Docker Docs: docker compose config.
9. Docker Docs: docker compose up.
10. Docker Docs: docker compose down.
11. Docker Docs: docker volume inspect.
12. PostgreSQL Docs: pg_dump.