آموزش n8n از صفر یعنی سه چیز: نصب ابزار روی سرور یا ابر، ساخت اولین ورک‌فلوی قابل‌اتکا با error handling، و فهمیدن اینکه کجا ادعای «بدون کدنویسی» تمام می‌شود و باید JavaScript بنویسید. اگر به‌دنبال ساخت ایجنت هوش مصنوعی (AI Agent) هستید، الگوی درست یک نود واحد نیست؛ ترکیب Router، Sub-workflow و Aggregation است. سه مسیر را با مثال عملی و مرزهای واقعی‌شان پیش می‌بریم.

n8n چیست و چرا ادعای «بدون کدنویسی» گمراه‌کننده است؟#

n8n یک ابزار اتوماسیون نود-محور (Node-based) است که workflowها را به‌صورت گراف بصری می‌سازد، اما ادعای «بدون کدنویسی» در مرز مشخصی فرو می‌ریزد: وقتی بیش از سه سطح شرط یا داده‌ی nested وارد کار شود، کاربر ناچار به نوشتن JavaScript در Code Node می‌شود.

معماری نود-محور چطور کار می‌کند؟#

هر workflow در n8n یک گراف جهت‌دار (Directed Graph) است. نودها گره‌های پردازش‌اند و یال‌ها مسیر جریان داده. یک نود Webhook ورودی می‌گیرد، داده را به نود بعدی پاس می‌دهد و هر نود می‌تواند داده را transform کند.

معماری حالت‌دار (Stateful) n8n یعنی هر execution در دیتابیس داخلی — معمولاً SQLite یا PostgreSQL — ذخیره می‌شود. پیامد عملی‌اش دو چیز است: می‌توانید execution قبلی را بازبینی و re-run کنید، و اگر workflow در نود پنجم خطا دهد، چهار نود اول اجرا شده و داده‌شان از بین نرفته است.

مرز واقعی «بدون کدنویسی» کجاست؟#

تا زمانی که workflow خطی باشد — Trigger، چند Action، یک IF ساده — واقعاً بدون کد کار می‌کند. اما سه نقطه شکست وجود دارد:

  • شرط‌بندی تودرتو: وقتی IF داخل IF داخل IF می‌شود، UI نود-محور دیگر خوانا نیست. در این نقطه نوشتن یک switch-case در Code Node تمیزتر است.
  • داده‌ی JSON nested: اگر API پاسخ عمیق‌تر از دو سطح می‌دهد، extraction با Expression Syntax n8n به‌سرعت غیرقابل‌مدیریت می‌شود.
  • منطق ریاضی یا الگوریتمی: محاسبه‌ی فاصله، رتبه‌بندی یا deduplication بدون loop نمی‌شود.

الگویی که در پروژه‌های اعضای کامیونیتی بارها تکرار شده: کاربران بعد از ساخت workflow با بیش از 15 نود، ناچار می‌شوند حداقل یک Code Node اضافه کنند. این نقطه‌ی شکست واقعی است، نه تبلیغات.

لایسنس Sustainable Use License و تفاوتش با open-source#

n8n تحت لایسنس Sustainable Use License منتشر می‌شود که تحت مفهوم Fair-code معرفی می‌شود. استفاده‌ی شخصی، آموزشی و داخلی سازمانی آزاد است، اما embed کردن مستقیم کد n8n در محصول SaaS تجاری بدون مجوز ممنوع.

تفاوت عملی: اگر n8n را روی سرور خودتان اجرا کنید و برای مشتریان خودتان workflow بسازید، مشکلی ندارید. اما اگر بخواهید n8n را به‌عنوان بخشی از محصول تجاری‌تان به مشتریان بدهید، باید مجوز جداگانه بگیرید.

نصب n8n: خودمیزبانی با Docker یا n8n Cloud؟#

نصب n8n دو مسیر اصلی دارد: خودمیزبانی با Docker که کنترل کامل و هزینه‌ی صفر نرم‌افزار می‌دهد اما نگهداری سرور را بر عهده‌ی شما می‌گذارد، و n8n Cloud که بدون سرور است ولی محدودیت workflow فعال و وابستگی به اینترنت دارد.

پیش‌نیازهای فنی نصب با Docker#

برای اجرای n8n روی سرور خودتان به Node.js نسخه‌ی 18 یا بالاتر، حداقل 2 گیگابایت RAM و پورت 5678 آزاد نیاز دارید. Docker Compose ساده‌ترین مسیر است:

  1. فایل docker-compose.yml با image رسمی n8nio/n8n بسازید.
  2. متغیرهای محیطی شامل N8N_ENCRYPTION_KEY و DB_TYPE را تنظیم کنید.
  3. دستور docker compose up -d را اجرا کنید.
  4. به آدرس localhost:5678 بروید و اکانت ادمین بسازید.

نکته‌ای که در آموزش‌ها کم دیده می‌شود: N8N_ENCRYPTION_KEY را حتماً در فایل .env ذخیره کنید. گم کردن این کلید یعنی تمام credentialهای ذخیره‌شده‌ی workflowهای شما غیرقابل‌بازیابی می‌شوند.

مقایسه‌ی Cloud و Self-hosted#

معیار n8n Cloud Self-hosted (Docker)
هزینه‌ی نرم‌افزار پلن رایگان محدود + پلن‌های پولی رایگان (فقط هزینه‌ی سرور)
نگهداری و آپدیت خودکار توسط n8n مسئولیت شما
دسترسی به فایل سیستم محدود کامل
Community Nodes محدود به لیست تأییدشده هر نودی که نصب کنید
Embed در SaaS نیاز به مجوز نیاز به مجوز (لایسنس یکسان)

محدودیت‌های لایسنس برای استفاده‌ی تجاری#

استفاده‌ی سازمانی داخلی — مثلاً workflowهای داخلی شرکت — لایسنس فعلی اجازه می‌دهد. اما embed کردن n8n در محصول SaaS برای مشتریان، مذاکره با تیم n8n را لازم دارد. این محدودیت در self-hosted هم اعمال می‌شود، نه فقط در Cloud.

ساخت اولین workflow واقعی: از Trigger تا Error Handling#

ساخت اولین workflow قابل‌اتکا در n8n از سه جزء تشکیل شده: Trigger (نقطه‌ی شروع)، Actionها (مراحل پردازش) و Error Handler (مسیر خطا). حذف هر یک از این سه، workflow را در اولین خطای واقعی متوقف می‌کند.

انتخاب Trigger: Webhook، Cron Schedule یا Manual#

Webhook Trigger رایج‌ترین انتخاب برای اتصال به سرویس‌های خارجی است. URL اختصاصی می‌دهد و هر درخواست HTTP به آن URL، workflow را فعال می‌کند. Cron Schedule برای کارهای زمان‌بندی‌شده مناسب است. Manual Trigger فقط برای تست و debugging به‌کار می‌آید.

الگوی تکرارشونده در پروژه‌های اعضای کامیونیتی: مبتدیان با Manual Trigger شروع می‌کنند، workflow را کار می‌اندازند، بعد به Webhook تغییر می‌دهند. این الگو درست است — اما حتماً قبل از deploy، Webhook URL را با curl یا Postman تست کنید.

زنجیره‌ی Actionها و اتصال نودها#

نودها را با کشیدن خط از خروجی نود قبلی به ورودی نود بعدی متصل می‌کنید. هر نود یک input و یک یا چند output دارد. نودهای IF و Switch چند خروجی دارند و مسیر اجرا بر اساس شرط انتخاب می‌شود.

Error Handling و retry logic#

این بخشی است که اکثر آموزش‌های n8n نادیده می‌گیرند — و دقیقاً همان‌جا که workflow در production می‌میرد.

بدون error handler، اگر نود HTTP Request به دلیل timeout خطا دهد، workflow متوقف می‌شود و هیچ اعلانی نمی‌گیرید. راه‌حل: یک نود Error Workflow (یا Error Trigger) در انتهای workflow اضافه کنید که در صورت خطا نوتیفیکیشن ارسال کند. همچنین در تنظیمات هر نود، گزینه‌ی Retry را فعال کنید تا n8n چند بار تلاش مجدد انجام دهد.

ورک‌فلو نمونه#

ترتیب نودها در یک workflow قابل‌اتکا:

  1. Webhook Trigger → دریافت داده از سرویس خارجی
  2. HTTP Request Node → ارسال داده به API مقصد
  3. IF Node → بررسی status code پاسخ
  4. اگر موفق: Respond to Webhook با status 200
  5. اگر ناموفق: Error Workflow → ارسال اعلان به Slack یا Email

چطور با n8n ایجنت هوش مصنوعی بسازیم؟#

ایجنت هوش مصنوعی (AI Agent) در n8n معمولاً با یک AI Agent Node واحد ساخته نمی‌شود؛ الگوی تکرارشونده در جامعه‌ی کاربری، تقسیم مسئولیت بین Router Node، چند Sub-workflow تخصصی و یک نود Merge برای جمع‌بندی پاسخ نهایی است.

یک گره‌ی مغزمانند که شاخه‌های مختلف جریان کار را تغذیه می‌کند، نماد ایجنت هوشمند در قلب workflow
ایجنت نقطه‌ی مرکزی است، اما بدون شاخه‌های اطرافش فقط یک ایده‌ی خام باقی می‌ماند

الگوی Router → Sub-workflow → Aggregation#

در الگوی Router → Sub-workflow → Aggregation، یک نود AI Agent با دسترسی به Tools نقش Router را بازی می‌کند: درخواست کاربر را می‌خواند و تصمیم می‌گیرد کدام Sub-workflow را فعال کند. هر Sub-workflow یک وظیفه‌ی تخصصی دارد — مثلاً خلاصه‌سازی، ترجمه یا جستجو. در انتها یک نود Merge پاسخ‌ها را جمع می‌کند.

چرا این الگو بهتر از یک نود واحد است؟ چون وقتی workflow تک‌نودی با هزار خط منطق می‌سازید، debugging عملاً غیرممکن می‌شود. تقسیم به Sub-workflowهای کوچک، هر کدام با error handler مستقل، هم قابل‌نگهداری‌تر است و هم قابل‌تست جداگانه.

یکپارچگی با OpenAI، Anthropic و مدل‌های محلی#

n8n از طریق نودهای رسمی به OpenAI و Anthropic متصل می‌شود. برای مدل‌های محلی مثل Ollama، دو مسیر دارید: نود HTTP Request برای صدا زدن API محلی Ollama، یا Community Node مخصوص Ollama که wrapper ساده‌تری ارائه می‌دهد.

نکته‌ی عملی: اگر مدل محلی استفاده می‌کنید، latency بالاتر از API‌های ابری است. در workflowهایی که کاربر منتظر پاسخ است، timeout نود HTTP Request را افزایش دهید.

Sub-workflow و modularization#

نود Execute Workflow در n8n اجازه می‌دهد یک workflow را از داخل workflow دیگر صدا بزنید. این ابزار کلیدی modularization است. هر Sub-workflow می‌تواند خودش Trigger مستقل داشته باشد (برای تست) و هم‌زمان از workflow والد فراخوانی شود.

ورک‌فلو نمونه: ایجنت چندمرحله‌ای#

  1. Webhook Trigger ← دریافت درخواست کاربر
  2. AI Agent Node (Router) ← تصمیم‌گیری درباره‌ی نوع درخواست
  3. Execute Workflow Node A ← Sub-workflow خلاصه‌سازی (اگر درخواست خلاصه است)
  4. Execute Workflow Node B ← Sub-workflow ترجمه (اگر درخواست ترجمه است)
  5. Merge Node ← جمع‌آوری خروجی هر Sub-workflow
  6. HTTP Response ← ارسال پاسخ نهایی به کاربر

n8n در برابر Zapier و Make: تفاوت معماری مهم‌تر از قیمت است#

تفاوت اصلی n8n با Zapier و Make در مدل اجرای stateful آن است: n8n execution history را در دیتابیس نگه می‌دارد و workflowها قابل resume و retry هستند، در حالی که Zapier و Make stateless اجرا می‌کنند و خطا یعنی از دست دادن کامل داده.

مقایسه‌ی stateful vs stateless execution#

در n8n، اگر workflow در نود پنجم خطا دهد، چهار نود اول اجرا شده و خروجی‌شان در دیتابیس ذخیره است. می‌توانید فقط از نود پنجم re-run کنید. در Zapier، خطا یعنی کل task شکست خورده و باید از اول اجرا شود.

پیامد عملی: در workflowهای چندمرحله‌ای با APIهای کند، این تفاوت معنادار است. re-run کردن سه نود اول که هر کدام 20 ثانیه طول می‌کشد، وقت‌گیر است.

مقایسه‌ی سه ابزار#

معیار n8n Zapier Make
مدل اجرا Stateful (قابل resume) Stateless Stateless
کدنویسی Code Node (JavaScript) محدود به Formatter محدود به Functions
خودمیزبانی بله (Docker) خیر خیر
AI Agent AI Agent Node + Tools AI Actions (محدود) AI Modules (محدود)
لایسنس Sustainable Use License تجاری بسته تجاری بسته

n8n برای چه پروژه‌هایی مناسب نیست؟#

اگر فقط یک ابزار ساده‌ی «اگر این شد آن را بکن» می‌خواهید — مثلاً وقتی فرم پر شد، ایمیل بفرست — Zapier سریع‌تر راه می‌افتد و نیاز به سرور ندارد. اگر می‌خواهید اتوماسیون را در محصول SaaS خود embed کنید، محدودیت لایسنس n8n مانع است و ابزارهایی با لایسنس بازتر مناسب‌ترند.

اشتباهات رایج مبتدیان و debugging workflowها#

رایج‌ترین اشتباه مبتدیان در n8n، hardcode کردن API Key داخل Code Node به‌جای استفاده از Credential Store داخلی است. در self-hosted این یعنی کلید در workflow JSON ذخیره می‌شود و هر بار export/import آن را لو می‌دهد — در حالی که n8n مکانیزم امن‌تری برای این کار دارد.

مدیریت Credential و ذخیره‌ی امن API Key#

n8n یک Credential Store داخلی دارد. API Keyها را در بخش Credentials ذخیره کنید و در نودها به‌صورت متغیر به آن‌ها ارجاع دهید. دو فایده: اول، اگر workflow را export کنید، کلیدها در JSON نیستند. دوم، یک credential را در چند workflow استفاده کنید و با یک بار تغییر، همه به‌روز شوند.

debugging با Execution Log واقعی#

بسیاری از مبتدیان فقط با دکمه‌ی «Execute Workflow» تست می‌کنند. اما Execution Log واقعی — که از منوی سمت چپ قابل‌دسترسی است — ورودی و خروجی هر نود را در هر اجرای واقعی نشان می‌دهد. این تنها راه debugging در production است.

الگویی که در پروژه‌های اعضای کامیونیتی مکرر دیده شده: قبل از deploy، سه execution دستی با داده‌های edge case (ورودی خالی، JSON غیرمنتظره، timeout) انجام دهید و خروجی هر نود را در Execution Log چک کنید.

Community Nodes و اکوسیستم افزونه#

نودهای رسمی n8n محدودند. Community Nodes — که توسط جامعه ساخته می‌شوند — اتصال به سرویس‌های خاص‌تر را ممکن می‌کنند. اما نصب آن‌ها فقط در self-hosted ممکن است و باید از مخزن رسمی n8n (npm package با پیشوند n8n-nodes-) استفاده کنید. نود ناشناخته نصب نکنید؛ در self-hosted، هر نود به فایل سیستم و دیتابیس شما دسترسی دارد.

مسیر یادگیری واقع‌بینانه#

زمان واقعی یادگیری اولین workflow با error handling قابل‌اتکا، بین 2 تا 4 هفته است — نه یک بعدازظهر. این بازه شامل یادگیری UI، درک Expression Syntax، ساخت workflow، مواجهه با خطاهای واقعی و اضافه کردن retry logic است.

مسیر پیشنهادی:

  1. هفته‌ی اول: نصب + ساخت workflow خطی ساده (Webhook → HTTP Request → Response)
  2. هفته‌ی دوم: اضافه کردن IF، Switch و چند مسیر
  3. هفته‌ی سوم: Error Handling، Credential و Execution Log
  4. هفته‌ی چهارم: اولین AI Agent با الگوی Router + Sub-workflow

جمع‌بندی عملی: n8n ابزار قدرتمندی است اما «بدون کدنویسی» نیست. مرز واقعی‌اش جایی است که شرط‌بندی تودرتو یا داده‌ی nested وارد می‌شود. ایجنت‌سازی با الگوی Router → Sub-workflow → Aggregation جواب می‌دهد، نه با یک نود واحد. و debugging واقعی فقط با Execution Log ممکن است، نه با تست live.

اگر می‌خواهید این مسیر را گام‌به‌گام و با پروژه‌های واقعی طی کنید، دوره‌ی «ساخت Ai Agent با N8N» در n8n School — با 51 جلسه و 10 فصل — دقیقاً همین مرزها را پوشش می‌دهد: از نصب تا ساخت ایجنت چندمرحله‌ای و debugging.