Datos binarios grandes: por qué 100 PDFs matan el servidor

Cuando un flujo de trabajo de repente debe procesar 100 PDFs de una sola vez, parece una tarea sencilla sobre el papel: leer archivos, extraer texto, pasar adelante. En la práctica, este flujo de trabajo a menudo se bloquea en medio de la ejecución, el contenedor de n8n se reinicia, y el registro solo muestra un sobrio "Out of memory". La razón casi siempre se encuentra en el mismo lugar: n8n mantiene datos binarios en el memoria RAM de forma predeterminada, no en el disco.

Para archivos individuales o imágenes pequeñas, esto apenas se nota. Pero tan pronto como procesas docenas o cientos de PDFs, escaneos o archivos adjuntos en una ejecución, cada archivo individual se suma al consumo de RAM del proceso hasta que el servidor o contenedor alcanza su límite. Puedes evitar reproduciblemente esto sin reconstruir el flujo de trabajo si sabes dónde girar la palanca adecuada. Este artículo muestra por qué ocurre la explosión de memoria y cómo puedes controlarla mediante el modo de datos binarios correcto.

Por qué 100 PDFs agotan la memoria RAM

n8n distingue técnicamente entre el flujo de datos actual del flujo de trabajo y los llamados datos binarios, es decir, archivos como PDFs, imágenes o adjuntos de Excel que pasan a través de un flujo de trabajo. Según la documentación oficial sobre datos binarios n8n mantiene estos datos en memoria RAM de forma predeterminada, lo cual es inofensivo con pequeñas cantidades de datos, pero rápidamente causa problemas de rendimiento con archivos grandes o muchos archivos simultáneamente. No hay freno incorporado: n8n no limita cuántos archivos un flujo de trabajo mantiene simultáneamente, ni la software reserva memoria automáticamente para un nodo. Un flujo de trabajo que lee 100 PDFs de un buzón o carpeta y los procesa con el nodo Extract-from-File puede así ocupar más memoria RAM archivo por archivo hasta que el contenedor alcanza su límite y se bloquea.

Exactamente este patrón lo describe también un usuario en el foro de la comunidad n8n: Durante la migración de alrededor de 2.000 registros con entre 150 y 200 adjuntos cada uno, el flujo de trabajo se bloqueaba regularmente en un VPS de 8 GB después de procesar aproximadamente 50 archivos porque el modo predeterminado mantenía todos los datos binarios en RAM. El efecto es el mismo con 100 PDFs que con 2.000 adjuntos, solo más visible si tu servidor ya está ajustado de forma limitada.

Los modos de datos binarios en resumen

n8n ofrece varios modos de almacenamiento para datos binarios, controlados a través de la variable de entorno `N8N_DEFAULT_BINARY_DATA_MODE`:

• memory (Predeterminado): Todos los archivos permanecen en la memoria RAM del proceso de n8n. Simple, pero sin ningún límite hacia arriba.
• filesystem: n8n escribe datos binarios en el disco en lugar del RAM. Esto previene según la documentación bloqueos con archivos grandes porque la demanda de memoria por ejecución disminuye significativamente.
• s3: Los datos binarios van a un bucket S3 compatible externamente en lugar del disco local o la RAM.
• database: Se utiliza cuando el modo Filesystem no está disponible, por ejemplo en el modo de colas.

Importante para configuraciones con múltiples workers: Según la documentación, n8n no admite el modo Filesystem en el modo de colas, en su lugar se debe usar el modo de base de datos, siempre que no haya almacenamiento compartido disponible.

Cambiar al modo Filesystem: la solución más rápida

Para la mayoría de configuraciones de una única instancia, es suficiente cambiar el modo a Filesystem:

• Establece la variable de entorno `N8N_DEFAULT_BINARY_DATA_MODE` a `filesystem`.
• Reinicia la instancia n8n para que la variable surta efecto.
• Asegúrate de que el volumen subyacente tiene suficiente espacio en disco, porque ahora los PDFs van al disco en lugar de RAM.
• Planifica limpieza regular porque n8n no vacía la carpeta con datos binarios automáticamente, sino que controla esto a través de la limpieza de datos de ejecución.

El usuario de la comunidad del hilo anterior describe el efecto de modo que la curva de memoria se mantuvo permanentemente baja después del cambio y el pico anterior desapareció por completo. Para un flujo de trabajo que procesa 100 PDFs de una sola vez, esto generalmente ya es la solución completa, completamente sin cambio de código en el flujo de trabajo en sí.

Modo S3, cuando Filesystem no es suficiente

Si tu instancia de n8n se ejecuta en modo de colas con múltiples workers en máquinas separadas, el almacenamiento de disco local solo ayuda parcialmente porque no todos los workers tienen acceso automático a los mismos archivos. Para este caso, la documentación sobre almacenamiento externo describe la integración de S3. Se configura a través de varias variables de entorno:

• `N8N_EXTERNAL_STORAGE_S3_HOST`, `N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME` y `N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION` para la infraestructura de destino.
• `N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY` y `N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET` para las credenciales de acceso.
• `N8N_AVAILABLE_BINARY_DATA_MODES=filesystem,s3` y `N8N_DEFAULT_BINARY_DATA_MODE=s3` para activar realmente el modo.

Importante de saber: Según la documentación, la integración de S3 requiere una licencia Enterprise válida, sin la cual n8n no se inicia en este modo. Además, debes establecer una política de ciclo de vida en el bucket que elimine automáticamente los datos binarios antiguos, porque n8n mismo no lo hace.

No olvides limpiar: gestión de datos de ejecución

Incluso con modo Filesystem o S3, tu demanda de almacenamiento continúa creciendo si las ejecuciones antiguas nunca se eliminan. La documentación sobre gestión de datos de ejecución describe las siguientes variables para esto:

• `EXECUTIONS_DATA_PRUNE` activa la limpieza automática.
• `EXECUTIONS_DATA_MAX_AGE` establece después de cuántas horas una ejecución completada se considera eliminable, valor predeterminado 336 horas, es decir 14 días.
• `EXECUTIONS_DATA_PRUNE_MAX_COUNT` limita adicionalmente el número máximo de ejecuciones almacenadas, valor predeterminado 10.000.
• `EXECUTIONS_DATA_HARD_DELETE_BUFFER` proporciona un período de gracia de predeterminadamente una hora antes de que los datos se eliminen permanentemente.

Un detalle que fácilmente se pasa por alto: La limpieza según la documentación siempre solo funciona en el modo de datos binarios actualmente activo. Si cambias de Filesystem a S3, es posible que los archivos antiguos en el disco local permanezcan y deban eliminarse manualmente.

Si no estás seguro de qué modo se ajusta a tu configuración, o un flujo de trabajo de n8n existente se bloquea regularmente con cantidades de PDF más grandes, analizaremos esto juntos como parte de nuestros servicios de automatización n8n. Como colaboradores digitales, configuramos la configuración una vez limpiamente, la documentamos y te la entregamos de modo que mantengas el control sobre los recursos de tu servidor.

Preguntas frecuentes

¿Por qué n8n se bloquea solo después de una cierta cantidad de PDFs, no inmediatamente?

Porque en el modo predeterminado, cada archivo individual ocupa memoria RAM adicional. Con pocos archivos pequeños, queda suficiente amortiguador, pero con cada PDF adicional en la misma ejecución, el consumo de RAM aumenta hasta que se agota la memoria disponible del contenedor o servidor y el proceso se interrumpe.

¿Es suficiente cambiar al modo Filesystem para 100 PDFs por ejecución?

En la mayoría de las configuraciones de una única instancia, sí, porque los archivos se encuentran en el disco en lugar de la memoria RAM y el consumo de RAM por ejecución disminuye significativamente. Si ejecutas en modo de colas con múltiples workers separados, necesitas adicionalmente almacenamiento compartido o el modo S3, porque n8n no admite el modo Filesystem allí.

¿Necesito una licencia de n8n específica para almacenamiento S3?

Sí. Según la documentación oficial, la integración de S3 para datos binarios está vinculada a una licencia Enterprise válida, sin la cual la instancia no se inicia en modo S3. Para configuraciones más pequeñas sin múltiples máquinas de worker, el modo Filesystem gratuito suele ser la solución más simple y suficiente.

¿Debo eliminar manualmente la carpeta de datos binarios?

n8n no limpia automáticamente la carpeta, sino que acopla la limpieza a la configuración de poda de datos de ejecución como `EXECUTIONS_DATA_PRUNE` y `EXECUTIONS_DATA_MAX_AGE`. Si la poda está activa, las ejecuciones antiguas se eliminarán regularmente junto con sus datos binarios en el modo activo, si la poda está deshabilitada, la carpeta sigue creciendo sin límite.