Migración de n8n a Traefik 3.3 y Postgres 16: guía técnica

# Migración segura de n8n: Actualizando Traefik a 3.3 y Postgres a 16 sin pérdida de datos

Migrar n8n desde versiones desactualizadas de Traefik y Postgres a un stack moderno requiere abordar problemas críticos de compatibilidad. Este artículo ofrece una guía técnica para preservar los datos y credenciales al actualizar desde Traefik 1.x y Postgres 11 a las versiones más recientes.

Preparación: Copia de seguridad y clave de cifrado

La etapa clave de la migración es exportar correctamente los datos y preservar la clave de cifrado. Sin ella, las credenciales quedarán inaccesibles tras la transferencia. Para n8n, esto es crítico: el sistema utiliza cifrado simétrico para almacenar tokens y contraseñas.

Realiza estas dos acciones obligatorias:

• Crea un volcado de la base de datos en formato custom para una restauración adecuada:

docker exec -t postgres_db pg_dump -U root -d n8n -Fc > /tmp/n8n_backup.dump
docker cp postgres_db:/tmp/n8n_backup.dump ./n8n_backup.dump

• Extrae la clave de cifrado actual de la configuración. Puede estar en dos lugares:

- Variable N8N_ENCRYPTION_KEY en docker-compose.yml

- Parámetro encryptionKey en el archivo ~/.n8n/config

Ignorar este paso provocará un error de Needs first setup al iniciar. El sistema reconocerá la base de datos, pero no podrá descifrar las credenciales almacenadas.

Desplegando el stack: Problemas con Traefik 3.3

Al desplegar Traefik 3.3, surge un problema crítico de incompatibilidad con la API de Docker. El enrutador usa por defecto una versión antigua de la API (1.24), mientras que los demonios modernos de Docker requieren la versión 1.41 o superior. Esto genera errores 404 al intentar descubrir contenedores.

Solución: fuerza la versión de la API en las variables de entorno:

environment:
  - DOCKER_API_VERSION=1.41

Este cambio permite que Traefik interactúe correctamente con Docker Engine. Sin él, el enrutador no ve los contenedores de n8n y Postgres, lo que hace imposible la configuración automática de rutas mediante el proveedor Docker.

Nota sobre el aislamiento de red: todos los servicios deben estar en la misma red personalizada (n8n_net). Esto garantiza una interacción estable entre contenedores sin conflictos de enrutamiento. Ejemplo de configuración correcta:

networks:
  n8n_net:
    name: n8n_net

services:
  traefik:
    networks:
      - n8n_net
  n8n:
    networks:
      - n8n_net
  postgres_db:
    networks:
      - n8n_net

Restaurando la base de datos en Postgres 16: Solucionando problemas de permisos

Postgres 16 introduce cambios en la política de seguridad predeterminada. El esquema public ahora tiene permisos restringidos, lo que causa un error de permission denied for schema public al iniciar n8n.

Tras restaurar el volcado, ejecuta:

docker cp n8n_backup.dump postgres_db:/tmp/
docker exec -i postgres_db pg_restore -U root -d n8n -1 /tmp/n8n_backup.dump

Luego, otorga permisos completos en el esquema al propietario de la base de datos:

docker exec -it postgres_db psql -U root -d n8n -c "GRANT ALL ON SCHEMA public TO root;"

Esto es necesario porque n8n utiliza activamente el esquema public para almacenar metadatos. Omitir este paso hará que el contenedor de n8n se caiga repetidamente.

Solucionando credenciales: Evitando el error "Needs first setup"

Incluso al pasar correctamente N8N_ENCRYPTION_KEY mediante variables de entorno, n8n puede ignorarla. La razón es un conflicto entre la variable de entorno y el archivo de configuración local. En el primer inicio, el sistema genera un nuevo archivo ~/.n8n/config que sobrescribe la clave de las variables.

Solución:

• Elimina el archivo de configuración dentro del contenedor:

docker exec -it n8n rm /home/node/.n8n/config

• Reinicia el servicio:

docker compose restart n8n

Esto obliga a n8n a usar la clave de las variables de entorno en lugar del archivo local. Asegúrate de que la variable original N8N_ENCRYPTION_KEY esté especificada en docker-compose.yml.

Detalles adicionales: Procesos en segundo plano y SQLite

Durante la migración, pueden surgir problemas con tareas en segundo plano que usan SQLite (por ejemplo, analizadores de Telegram basados en Telethon). Tras la transferencia, verás sqlite3.OperationalError: database is locked.

Causa: archivos residuales de journaling (.session-journal, .session-wal) que bloquean la base de datos. Solución:

• Instala la utilidad psmisc:

apt install psmisc -y

• Mata forzosamente los procesos que mantienen el bloqueo:

fuser -k -v /root/parser_folder/session_name.session

• Elimina los archivos temporales:

rm -f /root/parser_folder/session_name.session-journal
rm -f /root/parser_folder/session_name.session-wal

• Reinicia el servicio:

systemctl restart service_name.service

Importante: Eliminar los journals no afecta el archivo de sesión principal. La autorización de Telegram permanece intacta.

Puntos clave

• La clave de cifrado es obligatoria — sin la original N8N_ENCRYPTION_KEY, todas las credenciales quedarán inaccesibles.
• Traefik requiere especificación explícita de la API — el parámetro DOCKER_API_VERSION=1.41 es crítico para el descubrimiento de contenedores.
• Postgres 16 restringe permisos — otorga manualmente GRANT ALL ON SCHEMA public.
• Conflictos en la configuración local de n8n — eliminar ~/.n8n/config resuelve el problema de la clave de cifrado.
• Bloqueos de SQLite requieren limpieza — eliminar archivos .journal y .wal restaura los procesos en segundo plano.

Tras completar todos los pasos, n8n se iniciará con todos los flujos de trabajo, webhooks y credenciales preservados. La migración entre versiones mayores de software siempre conlleva riesgos, pero seguir estos procedimientos minimiza el tiempo de inactividad y la pérdida de datos.

— Editorial Team