Gros fichiers binaires : pourquoi 100 PDFs tuent le serveur

Quand un workflow doit tout d'un coup traiter 100 PDFs à la fois, cela ressemble sur le papier à une tâche simple : lire les fichiers, extraire le texte, transmettre. En pratique, exactement ce workflow plante souvent au milieu de l'exécution, le conteneur n8n redémarre, et le log ne dit que sobrement « Out of memory ». La raison se trouve presque toujours au même endroit : n8n garde les données binaires par défaut en mémoire de travail, pas sur le disque.

Pour les fichiers individuels ou les petites images, cela passe presque inaperçu. Mais dès que tu traites des dizaines ou des centaines de PDFs, des scans ou des pièces jointes en une seule exécution, chaque fichier s'ajoute à la consommation RAM du processus jusqu'à ce que le serveur ou le conteneur atteigne sa limite. Tu peux éviter reproductiblement cela sans refondre le workflow lui-même, si tu sais à quelle vis tu dois tourner. Cet article explique pourquoi l'explosion de mémoire se produit et comment tu peux la maîtriser via le bon mode de données binaires.

Pourquoi 100 PDFs surcharge la mémoire de travail

Techniquement, n8n distingue le flux de données du workflow lui-même des données binaires dites, c'est-à-dire les fichiers comme les PDFs, les images ou les pièces jointes Excel qui passent par un workflow. Selon la documentation officielle sur les données binaires, n8n garde ces données par défaut en mémoire de travail, ce qui est sans problème avec de petites quantités de données, mais conduit rapidement à des problèmes de performance avec de gros fichiers ou de nombreux fichiers simultanément. Il n'y a aucun frein intégré : n8n ne limite ni combien de fichiers un workflow garde simultanément, ni la software ne réserve automatiquement de mémoire pour un nœud. Un workflow qui lit 100 PDFs d'une boîte aux lettres ou d'un dossier et les traite avec le nœud Extract-from-File peut de ce fait occuper plus de mémoire de travail fichier par fichier jusqu'à ce que le conteneur atteigne sa limite et plante.

Exactement ce modèle est décrit aussi par un utilisateur dans le forum communautaire n8n : lors de la migration d'environ 2.000 enregistrements avec chacun 150 à 200 pièces jointes, le workflow sur un VPS de 8 GB s'arrêtait régulièrement après environ 50 fichiers traités parce que le mode par défaut gardait toutes les données binaires en RAM. L'effet avec 100 PDFs est le même qu'avec 2.000 pièces jointes, juste visible plus rapidement si ton serveur est déjà serré.

Vue d'ensemble des modes de données binaires

n8n offre plusieurs modes de stockage pour les données binaires, contrôlés par la variable d'environnement `N8N_DEFAULT_BINARY_DATA_MODE` :

• memory (Standard): Tous les fichiers restent en mémoire de travail du processus n8n. Simple, mais sans aucune limite vers le haut.
• filesystem: n8n écrit les données binaires sur le disque au lieu de la RAM. Cela prévient selon la documentation les plantages avec de gros fichiers parce que la consommation mémoire par exécution diminue nettement.
• s3: Les données binaires passent dans un bucket S3 compatible externe au lieu du disque local ou de la RAM.
• database: Est utilisé quand le mode Filesystem n'est pas disponible, par exemple en mode Queue.

Important pour les setups avec plusieurs workers : selon la documentation, n8n ne supporte pas le mode Filesystem en mode Queue, là il faut utiliser le mode base de données si aucun stockage partagé n'est disponible.

Passage au mode Filesystem : la solution la plus rapide

Pour la plupart des setups single-instance, il suffit de passer le mode à Filesystem :

• Définis la variable d'environnement `N8N_DEFAULT_BINARY_DATA_MODE` sur `filesystem`.
• Redémarre l'instance n8n pour que la variable prenne effet.
• Assure-toi que le volume sous-jacent a assez d'espace disque, car maintenant les PDFs se retrouvent sur le disque au lieu de la RAM.
• Prévois un nettoyage régulier car n8n ne vide pas automatiquement le dossier avec les données binaires, mais le contrôle via le nettoyage des données d'exécution.

L'utilisateur de la communauté du fil de discussion mentionné ci-dessus décrit l'effet de sorte que la courbe de mémoire était durablement basse après le changement et le précédent pic a complètement disparu. Pour un workflow qui traite 100 PDFs d'un coup, c'est en règle générale déjà la solution complète, tout sans changement de code dans le workflow lui-même.

Mode S3, quand Filesystem ne suffit pas

Si ton instance n8n s'exécute en mode Queue avec plusieurs workers sur des machines séparées, le stockage local sur disque aide seulement partiellement car pas tous les workers n'ont accès automatiquement aux mêmes fichiers. Pour ce cas, la documentation sur le stockage externe décrit la connexion S3. Elle se configure via plusieurs variables d'environnement :

• `N8N_EXTERNAL_STORAGE_S3_HOST`, `N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME` et `N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION` pour l'infrastructure cible.
• `N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY` et `N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET` pour les identifiants d'accès.
• `N8N_AVAILABLE_BINARY_DATA_MODES=filesystem,s3` et `N8N_DEFAULT_BINARY_DATA_MODE=s3` pour vraiment activer le mode.

Important à savoir : selon la documentation, la connexion S3 nécessite une licence Enterprise valide, sans laquelle n8n ne démarre pas en ce mode. De plus, tu devrais configurer une lifecycle-policy dans le bucket qui supprime automatiquement les anciennes données binaires, car n8n ne nettoie pas lui-même.

N'oublie pas de nettoyer : nettoyage des données d'exécution

Même avec le mode Filesystem ou S3, tes besoins de stockage continuent de croître si les anciennes exécutions ne sont jamais supprimées. La documentation sur la gestion des données d'exécution décrit pour cela les variables suivantes :

• `EXECUTIONS_DATA_PRUNE` active le nettoyage automatique.
• `EXECUTIONS_DATA_MAX_AGE` définit après combien d'heures une exécution terminée est considérée comme supprimable, valeur par défaut 336 heures, soit 14 jours.
• `EXECUTIONS_DATA_PRUNE_MAX_COUNT` limite en plus le nombre maximal d'exécutions conservées, valeur par défaut 10.000.
• `EXECUTIONS_DATA_HARD_DELETE_BUFFER` crée une période de grâce de une heure par défaut avant la suppression définitive des données.

Un détail facilement oublié : selon la documentation, le nettoyage n'agit que sur le mode de données binaires actuellement actif. Si tu passes donc de Filesystem à S3, d'anciens fichiers peuvent rester sur le disque local et doivent être supprimés manuellement.

Si tu ne sais pas lequel des modes correspond à ta configuration ou si un workflow n8n existant plante régulièrement avec des quantités de PDFs plus grandes, nous examinons cela volontiers dans le cadre de notre automatisation n8n. En tant que collaborateurs numériques, nous configurons correctement la configuration une fois, la documentons et nous te la remettons de sorte que tu gardes ensuite le contrôle de tes ressources serveur.

Questions fréquemment posées

Pourquoi n8n ne plante qu'à partir d'un certain nombre de PDFs, pas immédiatement ?

Parce qu'en mode par défaut chaque fichier individuel occupe de la mémoire de travail supplémentaire. Avec quelques petits fichiers, il reste assez d'espace libre, mais avec chaque PDF supplémentaire dans la même exécution, la consommation RAM augmente davantage jusqu'à ce que la mémoire disponible du conteneur ou du serveur soit épuisée et le processus s'arrête.

Est-ce que le passage au mode Filesystem suffit pour 100 PDFs par exécution ?

Dans la plupart des setups single-instance oui, parce que les fichiers se trouvent alors sur le disque au lieu de la mémoire de travail et la consommation RAM par exécution diminue nettement. Si tu travailles en mode Queue avec plusieurs workers séparés, tu as besoin en plus soit d'un stockage partagé, soit du mode S3, car n8n ne supporte pas le mode Filesystem.

Ai-je besoin d'une licence n8n spécifique pour le stockage S3 ?

Oui. Selon la documentation officielle, la connexion S3 pour les données binaires est liée à une licence Enterprise valide, sans laquelle l'instance ne démarre pas en mode S3. Pour les configurations plus petites sans plusieurs machines worker, le mode Filesystem gratuit est en règle générale la solution plus simple et suffisante.

Dois-je supprimer manuellement le dossier des données binaires ?

n8n ne nettoie pas le dossier automatiquement, mais lie le nettoyage aux paramètres de pruning des données d'exécution comme `EXECUTIONS_DATA_PRUNE` et `EXECUTIONS_DATA_MAX_AGE`. Si le pruning est actif, les anciennes exécutions y compris leurs données binaires en mode actif sont supprimées régulièrement, si le pruning est désactivé, le dossier continue de croître sans limites.