Concurrency w n8n: limity równoległości i kolizje zasobów

Kiedy instancja n8n zaczyna przetwarzać dziesiątki webhooków na sekundę, domyślne założenia o sekwencyjności przestają obowiązywać. Asynchroniczna natura środowiska Node.js, na którym opiera się n8n, sprawia, że równoległe egzekucje tego samego workflow mogą bez problemu przeplatać się w czasie. O ile przy prostych transformacjach danych nie stanowi to problemu, o tyle przy interakcjach z zewnętrznymi systemami – bazami danych, arkuszami czy API o restrykcyjnych limitach – brak kontroli nad concurrency to prosta droga do katastrofy.

W środowiskach produkcyjnych zjawisko to objawia się na kilka sposobów: nadpisywanie danych (klasyczny problem Read-Modify-Write), błędy 429 Too Many Requests z zewnętrznych API, a w skrajnych przypadkach wyczerpanie puli połączeń do bazy PostgreSQL obsługującej samą instancję n8n. Rozwiązanie tych problemów wymaga zrozumienia, jak n8n kolejkuje zadania pod maską i wdrożenia odpowiednich wzorców architektonicznych na poziomie samych workflow.

W tym artykule rozłożymy na czynniki pierwsze mechanizmy współbieżności w n8n. Zobaczymy, jak tryb queue mode wpływa na zrównoleglenie pracy, dlaczego dodanie workerów nie rozwiązuje problemu wyścigów o zasoby oraz jak zaimplementować niezawodne semafory i kolejki zewnętrzne, aby chronić krytyczne sekcje naszych automatyzacji.

Architektura egzekucji: Event Loop a Queue Mode

Aby zrozumieć, dlaczego w n8n dochodzi do kolizji, musimy zajrzeć pod maskę silnika egzekucji. W domyślnej konfiguracji (zmienna środowiskowa EXECUTIONS_PROCESS=main), n8n uruchamia wszystkie workflow w głównym procesie Node.js. Ponieważ Node.js jest jednowątkowy, wykorzystuje pętlę zdarzeń (Event Loop) do obsługi operacji wejścia/wyjścia. Kiedy node wykonuje zapytanie HTTP, proces nie blokuje się – n8n zawiesza stan tej konkretnej egzekucji i przechodzi do obsługi kolejnego webhooka. Gdy odpowiedź z sieci wraca, egzekucja jest wznawiana.

Skalowanie pionowe szybko napotyka tu barierę, dlatego wdrożenia produkcyjne korzystają z trybu kolejkowego (EXECUTIONS_MODE=queue). W tej architekturze główna instancja n8n działa jedynie jako router: przyjmuje webhooki, zapisuje stan do bazy PostgreSQL i wysyła identyfikator zadania do systemu Redis. Flota workerów nasłuchuje na listach w Redis i pobiera zadania do przetworzenia.

Warto tu podkreślić kluczowy fakt: uruchomienie Queue Mode zwiększa przepustowość, ale drastycznie potęguje ryzyko kolizji zasobów. Jeśli 50 webhooków trafi do n8n w tej samej sekundzie, 10 workerów może natychmiast rozpocząć ich równoległe przetwarzanie. Jeśli wszystkie te egzekucje próbują zaktualizować ten sam wiersz w Google Sheets lub ten sam rekord w CRM, zewnętrzny system otrzyma falę równoległych żądań, co nieuchronnie doprowadzi do wyścigu (race condition).

Anatomia wyścigu o zasoby (Race Condition)

Wyobraźmy sobie workflow, który aktualizuje saldo punktów lojalnościowych klienta w zewnętrznej bazie. Logika wydaje się prosta: 1. Pobierz obecne saldo (np. 100 pkt). 2. Dodaj nowe punkty z payloadu webhooka (np. +20). 3. Zapisz nowe saldo (120 pkt). Co się stanie, gdy dwa webhooki dla tego samego klienta uderzą w n8n w odstępie kilku milisekund?

Egzekucja A oraz Egzekucja B uruchamiają się równolegle. Egzekucja A odpytuje bazę i otrzymuje wartość 100. Zanim Egzekucja A zdąży zapisać wynik, Event Loop przełącza kontekst do Egzekucji B, która również odpytuje bazę i otrzymuje wartość 100. Następnie Egzekucja A oblicza 100 + 20 i zapisuje 120. Ułamek sekundy później Egzekucja B oblicza 100 + 15 i zapisuje 115. Zamiast poprawnych 135 punktów, system trwale traci dane z pierwszego zdarzenia. To klasyczny problem Read-Modify-Write.

Podobny problem występuje przy użyciu node'a Google Sheets z operacją Append or Update. Jeśli dwa równoległe procesy nie znajdą wiersza, oba spróbują wykonać operację Append, co skutkuje duplikacją danych w arkuszu. n8n samo w sobie nie wie, że operujesz na współdzielonym zasobie, więc nie założy żadnej blokady.

Wbudowane limity w n8n: Concurrency i Capacity

Od nowszych wersji n8n oferuje wbudowane mechanizmy kontroli współbieżności na poziomie ustawień samego workflow. W panelu Settings znajdziemy sekcję Execution Capacity oraz Concurrency. Możemy tam zdefiniować maksymalną liczbę jednocześnie trwających egzekucji dla danego workflow (np. Max Active Executions = 1).

Ustawienie limitu na 1 wymusza przetwarzanie sekwencyjne (FIFO). Każda nowa egzekucja czeka w wewnętrznej kolejce na zakończenie poprzedniej. Jest to najprostsza metoda na uniknięcie kolizji, ale niesie ze sobą poważne kompromisy architektoniczne:

• Wyczerpanie połączeń HTTP: Jeśli workflow jest wyzwalany przez Webhook node ustawiony na Respond: When Last Node Finishes, połączenie HTTP pozostaje otwarte przez cały czas oczekiwania w kolejce. Przy nagłym piku ruchu (spike), setki otwartych połączeń mogą doprowadzić do błędów 504 Gateway Timeout na poziomie reverse proxy (np. Nginx lub Traefik), zanim n8n w ogóle zdąży je przetworzyć.
• Blokowanie workerów: W trybie queue mode, zadania oczekujące w kolejce n8n nadal konsumują zasoby i mogą prowadzić do nierównomiernego obciążenia workerów.
• Brak granularności: Limit dotyczy całego workflow. Jeśli zablokujesz workflow do 1 egzekucji, to aktualizacja danych Klienta A zablokuje aktualizację danych Klienta B, mimo że te operacje są od siebie całkowicie niezależne i mogłyby biec równolegle.

Wzorzec bufora: RabbitMQ i Redis jako warstwa pośrednia

Zamiast polegać na wewnętrznym kolejkowaniu n8n, w architekturach o dużej skali stosuje się wzorzec bufora (Message Broker). Rozdzielamy w nim odbiór danych od ich przetwarzania, tworząc dwa osobne workflow.

Pierwszy workflow (Ingestion) składa się tylko z dwóch node'ów: Webhook oraz RabbitMQ (lub Redis). Jego jedynym zadaniem jest odebranie payloadu, autoryzacja, wrzucenie danych na kolejkę i natychmiastowe zwrócenie kodu 200 OK do klienta. Ten workflow wykonuje się w kilka milisekund i może obsługiwać tysiące żądań na sekundę bez ryzyka timeoutów.

Drugi workflow (Processing) korzysta z node'a RabbitMQ Trigger (lub harmonogramu odpytującego listę Redis). Tutaj konfigurujemy parametr Parallel Message Processing. Jeśli zależy nam na ścisłej sekwencyjności, ustawiamy pobieranie pojedynczych wiadomości (prefetch count = 1) i brak równoległości. Broker wiadomości gwarantuje nam, że żadna wiadomość nie zginie, nawet jeśli n8n zostanie zrestartowane, a my zyskujemy pełną kontrolę nad tempem konsumowania danych, chroniąc zewnętrzne API przed limitami rate-limitingu.

Semafory i blokady rozproszone na bazie Redis

Co w sytuacji, gdy musimy zachować wysoką przepustowość i równoległość (np. 50 workerów), ale chcemy zapobiec kolizjom tylko dla tych samych zasobów (np. tego samego userId)? Wtedy z pomocą przychodzą blokady rozproszone (Distributed Locks), potocznie zwane semaforami.

Ponieważ w środowisku produkcyjnym n8n (Queue Mode) mamy już podniesioną instancję Redis, możemy ją wykorzystać do zakładania blokad. Używamy do tego komendy SET z parametrami NX (Set if Not eXists) oraz EX (Expire). Parametr expire jest krytyczny – zapobiega zjawisku dead-locka w sytuacji, gdy worker n8n ulegnie awarii (np. OOM kill) i nie zwolni blokady.

W n8n realizujemy to za pomocą node'a Redis z operacją Custom Command. Wyrażenie konfiguracyjne wygląda następująco:

[
  "SET",
  "lock:user_{{$json.userId}}",
  "{{$execution.id}}",
  "NX",
  "EX",
  "30"
]

Logika workflow z semaforem wymaga wdrożenia pętli próbkowania (Polling Loop):

1. Wykonaj próbę założenia blokady (Custom Command w Redis).
2. Użyj node'a If. Jeśli Redis zwrócił OK, zasób jest twój. Przejdź do modyfikacji danych.
3. Jeśli Redis zwrócił null (blokada istnieje), przejdź do node'a Wait, odczekaj np. 2 sekundy i wróć do punktu 1.

Po zakończeniu operacji na zewnętrznym systemie, bezwzględnie musimy zwolnić blokadę. Używamy do tego komendy DEL lock:user_{{$json.userId}}.

Obsługa błędów i gwarancja zwolnienia blokady

Największym ryzykiem przy implementacji semaforów na poziomie workflow n8n jest obsługa błędów. Jeśli node aktualizujący bazę danych rzuci błędem, domyślnie workflow przerwie egzekucję, omijając node'a zdejmującego blokadę (DEL). Zasób pozostanie zablokowany aż do wygaśnięcia czasu TTL (np. 30 sekund).

Aby zbudować solidny mechanizm try/finally w n8n, należy zamknąć niebezpieczną logikę w pod-workflow (sub-workflow) i wywołać ją za pomocą node'a Execute Workflow. W ustawieniach tego node'a zmieniamy parametr On Error na Continue On Fail. Dzięki temu, niezależnie od tego, czy pod-workflow zakończy się sukcesem, czy błędem, główny workflow przejdzie do kolejnego kroku, którym będzie node Redis wykonujący komendę DEL. Dopiero po zwolnieniu blokady możemy sprawdzić status egzekucji pod-workflow i ewentualnie rzucić wyjątek za pomocą node'a Stop, aby poprawnie oflagować główną egzekucję jako błędną.

Checklista: Bezpieczne skalowanie concurrency w n8n

Wdrażając automatyzacje podatne na kolizje w rozproszonym środowisku n8n, stosuj się do poniższych zasad inżynieryjnych:

• Zidentyfikuj wąskie gardła: Nie każdy workflow wymaga blokad. Stosuj je tylko tam, gdzie występuje wzorzec Read-Modify-Write lub restrykcyjny rate-limiting na zewnętrznym API.
• Unikaj blokowania Webhooków: Jeśli spodziewasz się skoków ruchu, nigdy nie używaj wbudowanego limitowania concurrency w połączeniu z synchronicznym webhookiem. Zastosuj architekturę buforową z RabbitMQ lub Redis.
• Zawsze używaj TTL dla blokad: Zakładając semafor w Redis lub bazie danych, zawsze definiuj czas wygaśnięcia (Expire). W architekturze rozproszonej workery bywają ubijane przez orkiestrator (np. Kubernetes), co bez TTL doprowadzi do permanentnego dead-locka.
• Enkapsuluj logikę w sub-workflow: Izoluj procesy modyfikujące stan w pod-workflow, aby zagwarantować wykonanie logiki czyszczącej (teardown/cleanup) w głównym procesie, naśladując działanie bloku finally ze standardowych języków programowania.
• Monitoruj kolejki: W trybie Queue Mode używaj narzędzi takich jak BullMQ Dashboard lub metryk Prometheus do monitorowania długości głównej kolejki n8n. Rosnąca kolejka to sygnał do doskalowania liczby workerów, a nie zmiany logiki workflow.

Opanowanie concurrency w n8n to moment przejścia od prostego łączenia klocków do budowania dojrzałych, odpornych na awarie systemów rozproszonych. Świadome zarządzanie cyklem życia egzekucji i współdzielonymi zasobami to fundament niezawodnej automatyzacji na produkcyjną skalę.

Summary in English

Managing concurrency in n8n at a production scale requires moving beyond default execution assumptions. This article explores the internal mechanics of n8n's asynchronous Event Loop and Queue Mode, highlighting why scaling workers does not solve resource collisions and the Read-Modify-Write problem. We deep dive into architectural patterns for high-throughput environments, comparing built-in execution limits with robust message broker buffering using RabbitMQ. Furthermore, the article provides a practical guide to implementing distributed locks (semaphores) via Redis SETNX commands directly within n8n workflows. By utilizing sub-workflows for robust error handling and guaranteed lock release, automation engineers can prevent deadlocks, avoid API rate limits, and ensure data integrity across external systems.

#n8n #DevOps #workflow #selfhosting #API #automatyzacja