n8n چیست و چگونه کار می‌کند؟

n8n ابزاری برای ساخت گردش‌کار (workflow) است: چند «گره» را به هم وصل می‌کنید تا وقتی اتفاقی افتاد (یک وب‌هوک، یک زمان‌بندی، یک ایمیل)، کارهایی به ترتیب انجام شود. این مقاله ساختار n8n را به زبان ساده می‌گوید، آنچه را تجربهٔ کار با آن تعیین می‌کند (داده، اجرا، خطا، وب‌هوک، مقیاس) توضیح می‌دهد و می‌گوید کدام اتوماسیون‌ها برایش مناسب‌اند.

مرجع و نسخه: تمام ادعاهای این مقاله از مستندات رسمی n8n (docs.n8n.io) است که در ۱۹ اکتبر ۲۰۲۶ خوانده شده است. در آن روز مستندات «نسخهٔ پایدار فعلی ۲٫۴۳٫۷ و بتای ۲٫۴۴٫۳» را اعلام می‌کرد و صفحه‌ها «۵ تا ۶ روز پیش» به‌روز شده بودند. n8n تقریباً هر هفته نسخهٔ جدیدی می‌دهد؛ پیش از استفاده، مستندات و یادداشت‌های انتشار نسخهٔ خودتان را دوباره بخوانید. ما مقایسهٔ قیمت یا ادعای عملکرد نداریم و تنها اصول معماری را از مستندات نقل می‌کنیم. برای مفهوم API API چیست را ببینید.

n8n چیست؟

مستندات می‌گوید workflow مجموعه‌ای از گره‌های متصل است که یک فرایند را خودکار می‌کند. گره‌ها در عمل سه نقش دارند (دسته‌بندی ما، نه عبارت مستندات): ماشه (چیزی که اجرا را شروع می‌کند، مثل وب‌هوک یا زمان‌بندی)، عملیات (ارتباط با یک سرویس یا پردازش داده) و منطق (شرط، حلقه، ادغام). هر بار اجرای گردش‌کار یک «اجرا» (execution) است که می‌توانید در بخش اجراها ببینید.

داده چگونه حرکت می‌کند

این مهم‌ترین مفهوم برای ساختن چیزی که درست کار کند است. مستندات توضیح می‌دهد داده بین گره‌ها همیشه آرایه‌ای از شیءهاست؛ هر آیتم کلید json دارد و داده‌های دودویی (فایل) زیر کلید binary می‌آیند. هر گره هر آیتم ورودی را جداگانه پردازش می‌کند. نتیجهٔ عملی: اگر گرهٔ ورودی ۱۰۰ سطر بدهد، یک گرهٔ «ساخت کارت» ۱۰۰ بار اجرا می‌شود. این هم قدرت n8n است و هم منبع خطای رایج (مثلاً ۱۰۰ پیامک به‌جای یک پیامک).

ماشه‌ها: وب‌هوک و زمان‌بندی

گرهٔ Webhook به سرویس‌های بیرونی اجازه می‌دهد گردش‌کار را فراخوانی کنند و حتی می‌تواند مثل یک API پاسخ برگرداند. نکات مستندات:

• دو آدرس دارد: آزمایشی (هنگام «Listen for test event» و فقط برای ساخت) و تولیدی (پس از انتشار گردش‌کار).
• روش‌های HTTP: DELETE, GET, HEAD, PATCH, POST, PUT.
• حداکثر اندازهٔ payload ۱۶ مگابایت (با متغیر محیطی در خودمیزبانی قابل‌تغییر).
• احراز هویت: Basic، Header، JWT یا هیچ؛ و گزینه‌های «فهرست مجاز IP» و «فقط اگر…».
• پاسخ: فوری («Workflow got started»)، پس از آخرین گره، یا با گرهٔ Respond to Webhook.

خطا و اجرای ناموفق

مستندات توصیه می‌کند هنگام طراحی جریان، خطا را از قبل در نظر بگیرید. برای هر گردش‌کار می‌توانید یک «گردش‌کار خطا» تعیین کنید که با گرهٔ Error Trigger شروع می‌شود و هنگام شکست اجرا می‌شود (مثلاً هشدار ایمیل یا اسلک). گرهٔ Stop and Error هم شکست را عمداً ایجاد می‌کند.هر گردش‌کار تولیدی مسیر خطا و مالک داشته باشد.

انتظار و فرایندهای طولانی

گرهٔ Wait گردش‌کار را متوقف می‌کند و داده اجرا را در پایگاه داده نگه می‌دارد؛ وقتی شرط ادامه برقرار شد، داده بازیابی می‌شود. برای انتظار کوتاه‌تر از ۶۵ ثانیه، اجرا در حافظه باقی می‌ماند و در پایگاه ذخیره نمی‌شود. این برای فرایندهای «منتظر تأیید انسان» یا «ادامه پس از چند روز» مفید است، اما پایگاه داده شما را هم پر می‌کند؛ ظرفیت و حذف اجراها را برنامه‌ریزی کنید.

اجرا در مقیاس: queue mode

در حالت queue، چند نمونه n8n دارید: نمونهٔ اصلی تایمرها و فراخوان وب‌هوک‌ها را می‌گیرد و اجرا را «تولید» می‌کند، شناسهٔ اجرا را به Redis می‌دهد و workerها اجرا را برمی‌دارند و نتیجه را در پایگاه داده می‌نویسند. مستندات تأکید می‌کند کلید رمزنگاری نمونهٔ اصلی باید با همهٔ workerها مشترک باشد. برای شروع، لازم نیست؛ اما بدانید مسیر رشد وجود دارد.

میزبانی: Cloud یا خودمیزبان

مستندات خودمیزبانی با Docker Compose، نصب یک‌خطی و چند ارائه‌دهندهٔ ابری را پوشش می‌دهد و می‌گوید بدون کلید مجوز، n8n همان نسخهٔ Community رایگان اجرا می‌شود؛ ویرایش‌های Business و Enterprise با کلید مجوز فعال می‌شوند. هشدار صریح مستندات: خودمیزبانی برای کاربران باتجربه است و اشتباه می‌تواند به از دست رفتن داده، مشکل امنیتی و قطعی بینجامد. نصب npm هم از نسخهٔ 3.0 منسوخ اعلام شده است.

مثال کوچک: از وب‌هوک فرم تا اعلان

گردش‌کاری فرضی (مثال نویسنده) را در نظر بگیرید: فرم سایت یک POST به وب‌هوک می‌فرستد؛ گردش‌کار فیلدها را بررسی می‌کند؛ سرنخ را در CRM می‌سازد؛ برای فروش اعلان می‌فرستد؛ و به فرم پاسخ می‌دهد. نکته‌هایی که از مستندات می‌آیند و روی طراحی اثر می‌گذارند:

1. ماشه: گرهٔ Webhook با روش POST و احراز هویت Header. چون فرم از مرورگر می‌آید، گزینهٔ «Allowed Origins (CORS)» را به دامنهٔ سایت محدود کنید (مستندات پیش‌فرض را «همهٔ مبداها» می‌گوید).
2. داده: بدنهٔ درخواست در body می‌آید؛ اگر چند سرنخ در یک درخواست باشد، گره‌های بعدی برای هر کدام جدا اجرا می‌شوند. اگر فقط یک اعلان می‌خواهید، آن گره را برای یک بار اجرا تنظیم کنید یا ابتدا داده را تجمیع کنید.
3. پاسخ: بین «فوری» (سریع‌تر، ولی نتیجه را نمی‌داند) و «پس از آخرین گره» (کند، ولی نتیجه را برمی‌گرداند) یکی را انتخاب کنید؛ برای فرم، معمولاً پاسخ سریع بهتر است و خطا بعداً در گردش‌کار خطا هشدار می‌دهد.
4. خطا: گردش‌کار خطا که به مالک ایمیل یا پیام می‌دهد.

این مثال کوچک نشان می‌دهد چرا فهم «داده آرایه‌ای از آیتم‌هاست» و «پاسخ وب‌هوک را خودمان تعیین می‌کنیم» از ابتدا لازم است.

چه زمانی workflow مناسب است؟

این جدول توصیهٔ نویسنده است و از مستندات نیامده است. اصل: هر چه منطق شما پیچیده‌تر و بحرانی‌تر شود، آزمون‌پذیری مهم‌تر می‌شود؛ برای انتخاب بین API مستقیم، workflow و RPA، معیار «استثناها» را در نظر بگیرید.

شروع ایمن

1. یک فرایند کوچک و کم‌خطر را انتخاب کنید (مثلاً اعلان داخلی).
2. مسیر خطا و مالک را از ابتدا بسازید.
3. با داده نمونهٔ ساختگی تست کنید؛ داده واقعی مشتری را وارد محیط آزمایشی نکنید.
4. پایش اجرای موفق/ناموفق را برقرار کنید؛ اصول در پایش سیستم با متریک و هشدار آمده است.
5. نسخهٔ n8n را ثبت کنید و پیش از ارتقا یادداشت‌های انتشار را بخوانید.

اشتباهات رایج

• غافل از اینکه هر گره هر آیتم را جدا پردازش می‌کند.
• تکیه بر آدرس آزمایشی وب‌هوک در محیط واقعی.
• وب‌هوک بدون احراز هویت.
• نبودن گردش‌کار خطا.
• خودمیزبانی بدون پشتیبان، پایش و برنامهٔ ارتقا.
• ثبت‌نکردن نسخه و خواندن مستندات نسخهٔ دیگر.

چک‌لیست

1. نسخهٔ n8n و تاریخ خواندن مستندات ثبت شده است.
2. داده بین گره‌ها به‌صورت آرایهٔ آیتم‌ها درک و تست شده است.
3. وب‌هوک تولیدی احراز هویت و محدودیت IP/شرط دارد.
4. گردش‌کار خطا و مالک تعیین شده است.
5. برای انتظارهای طولانی ظرفیت پایگاه داده و حذف اجراها برنامه‌ریزی شده است.
6. تصمیم Cloud یا خودمیزبان با توجه به توان عملیات تیم گرفته شده است.

منابع و مراجع

• Understand workflows — n8n Docs، 2026-10-19.
• Understand n8n's data structure — n8n Docs، 2026-10-19.
• Webhook node — n8n Docs، 2026-10-19.
• Handle errors gracefully — n8n Docs، 2026-10-19.
• Enable queue mode — n8n Docs، 2026-10-19.
• Host n8n — n8n Docs، 2026-10-19.
• Wait node — n8n Docs، 2026-10-19.