آموزش n8n در بیشتر منابع به ساخت یک ورک‌فلو ساده خلاصه می‌شود. اما فاصله‌ی واقعی بین «یک ورک‌فلو زدن» و «معماری قابل‌نگهداری در پروداکشن» سه تصمیم معماری است که هیچ‌جا صریح توضیح داده نشده: تقسیم به sub-workflow، انتخاب آگاهانه بین Code Node و Expression، و تنظیم Error Workflow. این مقاله همین سه تصمیم را با مثال عملی باز می‌کند.

n8n چیست و چه چیزی آن را از Zapier و Make جدا می‌کند؟#

n8n یک پلتفرم اتوماسیون مبتنی بر نود (Node-Based Automation Platform) است که برخلاف Zapier و Make، اجرای کد دلخواه، self-hosting و معماری چند-نودی را ممکن می‌کند. این سه ویژگی، n8n را به ابزار متفاوتی تبدیل کرده‌اند، نه صرفاً نسخه‌ی ارزان‌تر رقیب.

معماری Node-Based در مقابل Workflow خطی#

Zapier و Make ورک‌فلو را به‌صورت خطی تعریف می‌کنند: یک Trigger، چند Action، بدون انشعاب منطقی عمیق. n8n هر نود را به‌عنوان یک واحد پردازش مستقل با ورودی و خروجی JSON مدل می‌کند. یعنی می‌توانید چند نود را به یک نود وصل کنید (fan-out) یا خروجی چند نود را در یک نود جمع کنید (fan-in). این تفاوت معماری است که اجازه می‌دهد منطق شرطی چندلایه و حلقه‌ها را بدون محدودیت پلتفرم پیاده کنید.

جدول مقایسه‌ی سه‌تایی n8n، Zapier، Make#

معیارn8nZapierMake (Integromat)
اجرای کد دلخواهCode Node با JavaScriptمحدود (Code by Zapier)محدود (Function Node)
Self-hostingبله، با Docker یا npmخیرخیر
AI Agent Nodeبله، nativeAI Actions (محدود)AI Module
تعداد نودهای آمادهبیش از 400بیش از 6000بیش از 1500
مدل قیمت‌گذاریExecution-based یا self-host رایگانTask-basedOperation-based

مجوز Sustainable Use License و معنای عملی آن#

n8n تحت مجوز Sustainable Use License منتشر شده. معنای عملی: سورس‌کد باز است و می‌توانید self-host کنید، اما اگر بخواهید n8n را به‌عنوان بخشی از یک سرویس تجاری به مشتریان ثالث بفروشید، باید مجوز جداگانه بگیرید. برای استفاده‌ی داخلی شرکت یا اتوماسیون پروژه‌های شخصی، محدودیتی وجود ندارد. نکته‌ای که کمتر دیده می‌شود: این مجوز مانع از آن است که کسی n8n را به‌عنوان «زیرساخت» یک SaaS رقیب استفاده کند، اما برای اتوماسیون داخلی هیچ قفلی ندارد.

نصب n8n: cloud یا self-hosted؟ تصمیمی که بیشتر مبتدی‌ها اشتباه می‌گیرند#

برای شروع و تست، n8n Cloud با ثبت‌نام یک‌دقیقه‌ای مناسب‌ترین گزینه است. self-hosting فقط زمانی به‌صرفه می‌شود که حجم ترافیک بالا باشد و تیم DevOps برای نگهداری سرور داشته باشید. اشتباه رایج مبتدی‌ها: نصب روی VPS در روز اول، سپس غرق شدن در تنظیم reverse proxy، SSL و بکاپ قبل از ساختن اولین ورک‌فلو.

نصب سریع با Docker (دستور یک‌خطی)#

اگر Docker روی سیستم نصب است، اجرای n8n محلی با یک دستور ممکن می‌شود:

  1. docker run -it --rm -p 5678:5678 -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n
  2. مرورگر را روی http://localhost:5678 باز کنید
  3. اکانت محلی بسازید و وارد شوید

این روش برای توسعه‌ی محلی و تست عالی است، اما برای پروداکشن باید volume را روی دیسک پایدار تنظیم کنید و یک reverse proxy (مانند Caddy یا Nginx) در جلوی آن بگذارید.

نصب با npm برای محیط توسعه‌ی محلی#

اگر Node.js روی سیستم دارید، npx n8n ساده‌ترین راه شروع است. برای کسی که می‌خواهد فقط ورک‌فلو بسازد و با Docker سروکار ندارد، کافی است.

محدودیت Queue Mode در self-hosted#

n8n به‌صورت پیش‌فرض در حالت Single Process اجرا می‌شود. اگر ورک‌فلوی سنگین یا چند ورک‌فلوی هم‌زمان دارید، UI قفل می‌شود. راه‌حل: فعال‌سازی Queue Mode با Redis و Worker Process جداگانه. این تنظیم در مستندات رسمی آمده، اما اکثر آموزش‌ها نادیده می‌گیرند. نتیجه‌ی نادیده گرفتن: ورک‌فلوی 10 دقیقه‌ای شما، کل پنل مدیریت را برای بقیه‌ی تیم غیرقابل‌استفاده می‌کند.

چه زمانی cloud به‌صرفه‌تر است؟#

اگر تیم DevOps ندارید، حجم executions ماهانه پایین است، و نمی‌خواهید وقت روی آپدیت و بکاپ صرف کنید، n8n Cloud انتخاب منطقی‌تری است. self-hosting ارزان‌تر به‌نظر می‌رسد، اما هزینه‌ی پنهان نگهداری سرور، آپدیت امنیتی و زمانِ آن را در مقیاس کوچک گران‌تر می‌کند.

برای شروع n8n باید برنامه‌نویسی بلد باشم؟#

خیر. برای ساخت اکثر ورک‌فلوها کافی است منطق بصری نودها و Expressionهای ساده را یاد بگیرید. JavaScript فقط وقتی لازم است که تبدیل داده‌ی پیچیده یا منطق شرطی چندلایه دارید. n8n دقیقاً برای همین ساخته شده که بدون کدنویسی اتوماسیون بسازید.

Expression چیست و چه کارهایی بدون کد می‌شود کرد#

Expression یک فرمول کوچک است که با {{ }} در فیلدهای نودها نوشته می‌شود. مثال: {{ $json.email }} مقدار فیلد email از خروجی نود قبلی را برمی‌دارد. با Expression می‌توانید رشته‌ها را concat کنید، شرط ساده بگذارید و از توابع built-in مانند $now، $items و $json استفاده کنید.

Code Node چه زمانی جای Expression را می‌گیرد؟#

وقتی منطق تبدیل داده بیش از 2-3 شرط تودرتو دارد یا نیاز به حلقه روی آرایه دارید، Code Node جایگزین بهتری است. دلیل اصلی: دیباگ‌پذیری. Code Node با console.log و خروجی قابل‌بازبینی در Execution Log، خطا را قابل‌ردیابی می‌کند. Expression فقط یک خط قرمز در فیلد نشان می‌دهد و باید حدس بزنید کدام بخش از فرمول شکسته.

تفاوت عملی دیباگ: Code Node در مقابل Expression#

در یک پروژه‌ی واقعی، ورک‌فلویی با 15 Expression پیچیده داشتیم که یک فیلد تاریخ را به‌صورت اشتباه فرمت می‌کرد. پیدا کردن خطا 2 ساعت طول کشید چون فقط خط قرمز داشتیم. بعد از تبدیل به Code Node، همان خطا با یک console.log در 5 دقیقه شناسایی شد. این الگو در پروژه‌های اعضای کامیونیتی n8n بارها تکرار شده است.

مفاهیم پایه: Node، Connection، Trigger و Execution#

هر ورک‌فلو در n8n از سه عنصر ساخته می‌شود: Trigger (نقطه‌ی شروع)، Node (واحد پردازش) و Connection (مسیر داده بین نودها). Execution هر بار که Trigger فعال می‌شود، یک رکورد کامل از داده‌ها تولید می‌کند.

انواع Trigger: Webhook، Schedule، Manual و Event-based#

Trigger نودی است که ورک‌فلو را شروع می‌کند. چهار نوع اصلی دارد:

  • Webhook Trigger: یک URL HTTP دریافت می‌کند. مناسب برای اتصال به سرویس‌های خارجی.
  • Schedule Trigger: بر اساس Cron یا فاصله‌ی زمانی اجرا می‌شود.
  • Manual Trigger: فقط با کلیک روی Execute Workflow اجرا می‌شود. برای تست.
  • Event-based Trigger: با رویداد خاصی در سرویس خارجی فعال می‌شود (مثلاً ایمیل جدید در Gmail).

ساختار داده‌ی Execution و مسیر JSON در نودها#

هر نود یک آرایه از Object‌ها به نام items دریافت می‌کند و یک آرایه برمی‌گرداند. هر item یک فیلد json دارد. وقتی در فیلدی می‌نویسید {{ $json.name }}، در واقع مقدار فیلد name از jsonِ item فعلی را می‌خوانید. این مدل داده‌ی واحد است که همه‌چیز را ساده نگه می‌دارد.

Sub-workflow چیست و چرا مهم است#

Sub-workflow یک ورک‌فلوی مستقل است که از طریق Execute Workflow Node یا Webhook از ورک‌فلوی دیگر صدا زده می‌شود. ورودی و خروجی‌اش مشخص است، مثل یک تابع. بدون sub-workflow، ورک‌فلوهای بزرگ به یک گراف 50 نودی غیرقابل‌فهم تبدیل می‌شوند.

ساخت اولین ورک‌فلو: دریافت ایمیل، استخراج داده و ذخیره در Google Sheets#

ورک‌فلوی نمونه: Gmail Trigger → Email Read → Set Node (استخراج فیلدها) → Google Sheets Append. این چهار نود ساده، الگوی تمام ورک‌فلوهای داده‌محور n8n است: دریافت ورودی، تبدیل، ذخیره.

گام‌به‌گام#

  1. یک Workflow جدید بسازید و Gmail Trigger را به‌عنوان نود اول اضافه کنید.
  2. حساب Gmail را با OAuth2 وصل کنید و فیلتر «ایمیل‌های جدید از آدرس خاص» تنظیم کنید.
  3. نود Set را اضافه کنید. در فیلدهای آن، با Expression فیلدهای مورد نظر را از خروجی Gmail استخراج کنید: {{ $json.subject }}، {{ $json.from }}، {{ $json.body }}.
  4. نود Google Sheets را اضافه کنید و Operation را روی Append set کنید.
  5. Mapping فیلدها را انجام دهید: هر فیلد Set Node را به ستون مربوطه در Sheet وصل کنید.
  6. روی Execute Workflow کلیک کنید و خروجی هر نود را در Execution Log بررسی کنید.

تبدیل فرمت داده بین نودها#

خروجی Gmail یک Object تودرتو است. Google Sheets یک آرایه‌ی خطی از مقادیر می‌خواهد. Set Node دقیقاً همین کار را می‌کند: Object پیچیده را به ساختار تخت (flat) تبدیل می‌کند که هر فیلدش یک ستون در Sheet می‌شود.

اشتباه رایج: فراموش کردن mapping فیلدها#

بیشترین خطای مبتدی‌ها در نود Google Sheets است: فیلدها را map نمی‌کنند و Sheet خالی پر می‌شود. قبل از فعال‌سازی ورک‌فلو، حتماً در Execution Log بررسی کنید که خروجی Set Node شامل تمام فیلدهای مورد نیاز است.

ساخت ایجنت هوش مصنوعی (AI Agent) با n8n#

AI Agent Node در n8n با پشتیبانی از tool calling و memory، امکان ساخت ایجنت‌هایی را می‌دهد که مستقیماً با OpenAI، Anthropic و مدل‌های محلی کار می‌کنند و ابزارهای خارجی را صدا می‌زنند. برخلاف LangChain که یک کتابخانه‌ی کد است، n8n این معماری را به‌صورت بصری و بدون کدنویسی ارائه می‌دهد.

ایجنت‌های هوشمند به‌صورت موجودات نورانی در حال انتخاب مسیرهای مختلف در شبکه‌ی ورک‌فلو
هر ایجنت مسیر متفاوتی را بر اساس تصمیم‌گیری مستقل خود انتخاب می‌کند.

معماری ایجنت: Agent Node + Tool Nodes + Memory#

سه جزء اصلی: Agent Node (مغز ایجنت که تصمیم می‌گیرد کدام tool را صدا بزند)، Tool Nodes (نودهایی که عملیات واقعی انجام می‌دهند: جست‌وجوی وب، فراخوانی API، خواندن دیتابیس)، و Memory Node (حافظه‌ی مکالمه برای حفظ context بین پیام‌ها).

اتصال به OpenAI API و تنظیم Model Parameters#

در Agent Node، مدل را انتخاب کنید (gpt-4o، claude-3-5-sonnet و...). System Prompt را بنویسید. Temperature و Max Tokens را تنظیم کنید. Tool Calling به‌صورت خودکار فعال است و n8n schema هر Tool Node را به مدل پاس می‌دهد.

الگوی پیشرفته: n8n به‌عنوان لایه‌ی ارکستراتور روی LangChain یا CrewAI#

اگر ایجنت شما به چند ایجنت تخصصی با نقش‌های مختلف نیاز دارد (مثلاً یک ایجنت تحلیل‌گر + یک ایجنت نویسنده)، می‌توانید CrewAI یا LangChain را در Code Node اجرا کنید و n8n را به‌عنوان لایه‌ی ارکستراتور و Trigger استفاده کنید. این الگو زمانی به‌درد می‌خورد که منطق ایجنت از حد Agent Node ساده فراتر رفته باشد.

مثال عملی: ایجنت پاسخ‌گوی تیکت با دسترسی به CRM#

Trigger: Webhook از سیستم تیکت. Agent Node با System Prompt «تو یک پشتیبان فنی هستی». Tool 1: HTTP Request به CRM برای خواندن تاریخچه‌ی مشتری. Tool 2: Google Search برای پیدا کردن مستندات محصول. خروجی: پاسخ در تیکت + ثبت در CRM. کل این ورک‌فلو بدون یک خط کد JavaScript ساخته می‌شود.

این مثال و الگوهای مشابه، بخش‌هایی از دورهٔ ساخت Ai Agent با N8N در کامیونیتی اسکول هستند.

معماری ورک‌فلو بزرگ: الگوی Sub-workflow که آموزش‌ها نمی‌گویند#

وقتی ورک‌فلو از 15-20 نود عبور می‌کند، الگوی صحیح تقسیم به ورک‌فلوهای کوچک با خروجی استاندارد + یک ورک‌فلوی ارکستراتور بزرگ است. ورک‌فلوی 50 نودی بدون تقسیم، غیرقابل‌نگهداری می‌شود. این الگو در مستندات رسمی n8n ذکر شده، اما به‌عنوان «توصیه» نه «ضرورت معماری».

الگوی «ورک‌فلو کوچک با خروجی استاندارد + Orchestration Workflow»#

هر sub-workflow یک ورودی مشخص و یک خروجی مشخص دارد. Orchestration Workflow فقط sub-workflowها را به ترتیب صدا می‌زند و خروجی هر کدام را به ورودی بعدی پاس می‌دهد. نتیجه: هر sub-workflow مستقل تست می‌شود، مستقل دیباگ می‌شود و مستقل قابل جابه‌جایی است.

تجربه‌ی واقعی: ورک‌فلوهای 30+ نودی که به sub-workflow تقسیم شدند#

این الگو در پروژه‌های اعضای کامیونیتی مکرر دیده شده: ابتدا یک ورک‌فلوی بزرگ ساخته می‌شود، سپس بعد از 2-3 هفته‌ی استفاده، تیم مجبور می‌شود آن را به 4-5 sub-workflow تقسیم کند. هزینه‌ی این بازسازی معمولاً بیشتر از طراحی اولیه‌ی modular است. درس عملی: از روز اول sub-workflow بچینید، حتی اگر الان 5 نود دارید.

ارتباط بین sub-workflowها با Webhook یا Execute Workflow Node#

دو روش اصلی: Execute Workflow Node (ساده‌تر، هم‌زمان) و Webhook (مناسب برای ارتباط async یا بین سرورهای جداگانه). برای محیط‌های self-hosted با چند instance، Webhook انعطاف بیشتری می‌دهد.

چه زمانی n8n مناسب نیست؟#

اگر به microservice واقعی با scaling خودکار، latency زیر 50 میلی‌ثانیه و ترافیک هزاران request هم‌زمان نیاز دارید، n8n ابزار مناسبی نیست. n8n برای orchestration و اتوماسیون طراحی شده، نه به‌عنوان API gateway با کارایی بالا.

مدیریت خطا و Error Workflow: چیزی که بدون آن ورک‌فلوهایتان بی‌صدا می‌میرند#

بدون تنظیم Error Trigger، خطاهای ورک‌فلو در پروداکشن بی‌صدا از بین می‌روند. الگوی ضروری: یک Error Workflow جداگانه که خطا را در Slack یا ایمیل گزارش می‌دهد، به‌علاوه تنظیم Retry با Exponential Backoff برای فراخوانی‌های موقت API.

تنظیم Error Trigger و ساخت Error Workflow#

در تنظیمات هر ورک‌فلو، فیلد Error Workflow را پر کنید. این ورک‌فلو باید با Error Trigger شروع شود و اطلاعات خطا (نود شکسته، پیام خطا، داده‌ی ورودی) را به کانال اطلاع‌رسانی بفرستد. بدون این تنظیم، ورک‌فلوی شما با خطا متوقف می‌شود و هیچ‌کس متوجه نمی‌شود.

الگوی Retry با Exponential Backoff#

وقتی یک API موقتاً down است، ورک‌فلو باید با فاصله‌ی افزایشی دوباره تلاش کند. در n8n این کار را با Loop Node + Wait Node پیاده می‌کنید: تلاش اول، اگر خطا داد 1 دقیقه صبر، تلاش دوم، اگر خطا داد 5 دقیقه صبر، تلاش سوم، اگر باز خطا داد به Error Workflow برو. این الگو در مستندات رسمی کم توضیح داده شده.

دیباگ در production: Execution Log و Pin Data#

وقتی ورک‌فلو در پروداکشن خطا می‌دهد: Execution Log را باز کنید، نود خطا را پیدا کنید. سپس با Pin Data، ورودی نود بعدی را ثابت کنید و مرحله‌به‌مرحله اجرا کنید. اگر از Code Node استفاده کرده‌اید، console.log در Execution Log قابل‌مشاهده است.

هزینه‌ی واقعی n8n: مقایسه‌ی صادقانه در مقیاس‌های مختلف#

در ترافیک پایین، n8n Cloud ساده‌تر و ارزان‌تر تمام می‌شود. در ترافیک بالا، self-hosted روی VPS به‌صرفه‌تر است، به شرطی که هزینه‌ی پنهان نگهداری را محاسبه کنید.

جدول مقایسه‌ی هزینه: Cloud vs Self-hosted#

سطح ترافیکn8n CloudSelf-hosted (VPS)توصیه
کم (زیر 1000 execution/ماه)پلن رایگان یا StarterVPS + زمان نگهداریCloud — ساده‌تر
متوسط (1000 تا 10000)پلن ProVPS + Redis + Workerبستگی به تیم DevOps
بالا (بیش از 10000)پلن EnterpriseVPS + Queue Mode + مانیتورینگSelf-hosted معمولاً ارزان‌تر

هزینه‌ی پنهان self-hosting#

آپدیت امنیتی n8n، بکاپ منظم دیتابیس، مانیتورینگ uptime و زمانِ سرور. اگر تیم DevOps ندارید، این هزینه‌ها به شکل ساعت کاری شما برگشت داده می‌شوند. در مقیاس کوچک، cloud با پرداخت ماهانه، معمولاً ارزان‌تر تمام می‌شود.

آیا n8n برای کسب‌وکارهای کوچک مقرون‌به‌صرفه است؟#

بله. پلن رایگان Cloud برای شروع و تست کافی است. وقتی به ترافیک واقعی رسیدید، پلن Starter با هزینه‌ی معقول، تمام نیازهای یک کسب‌وکار کوچک را پوشش می‌دهد. خودِ ابزار رایگان نیست، اما ارزشی که در اتوماسیون فرآیندها ایجاد می‌کند، معمولاً چند برابر هزینه‌ی آن است.

جمع‌بندی: سه تصمیمی که ورک‌فلوی شما را از تست به معماری تبدیل می‌کند#

فاصله‌ی بین «یک ورک‌فلو زدن» و «معماری قابل‌نگهداری ساختن» در سه تصمیم است: تقسیم به sub-workflow از روز اول، انتخاب Code Node به‌جای Expression وقتی دیباگ‌پذیری مهم است، و تنظیم Error Workflow قبل از اولین deploy. هر سه در مستندات رسمی وجود دارند، اما هیچ‌جا به‌عنوان «ضرورت معماری» نه «توصیه» مطرح نشده‌اند. اگر این سه را رعایت کنید، ورک‌فلوهایتان در ماه سوم هم قابل‌نگهداری هستند.

اگر می‌خواهید این الگوها را در پروژه‌های واقعی تمرین کنید و از تجربه‌ی بقیه‌ی اعضای کامیونیتی استفاده کنید، دوره‌ی «ساخت Ai Agent با N8N» در کامیونیتی N8N اسکول دقیقاً همین مسیر را از صفر تا ایجنت پروداکشن پوشش می‌دهد.