آموزش n8n از صفر تا ایجنت هوش مصنوعی (AI Agent) یک تله‌ی رایج دارد: تازه‌کارها وقتشان را صرف حفظ کردن نام نودها (Node) می‌کنند، در حالی که منحنی یادگیری واقعی در درک تبدیل داده‌ی JSON بین نودهاست. دقیقاً همان‌جا به دیوار می‌خورند. این راهنما معماری نود‌محور، نصب با Docker و ساخت اولین ورک‌فلو (Workflow) عملیاتی را حول همین نقطه‌ی شکست می‌چیند.

معماری node-based در n8n و جریان داده JSON بین نودها#

آموزش n8n یعنی فهم معماری نود‌محور (Node-based): هر نود یک آرایه از آبجکت‌های JSON دریافت می‌کند، فیلدها را استخراج یا تبدیل می‌کند و خروجی را به نود بعدی پاس می‌دهد. حفظ نام نودها ارزشی ندارد؛ درک جریان داده‌ی JSON همه‌چیز است.

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

ساختار Item پایه‌ی همه‌چیز در n8n است. اگر نود اول 3 آیتم بدهد، نود دوم برای هر 3 آیتم یک بار اجرا می‌شود. این رفتار «multi-item execution» نام دارد و بخش عمده‌ای از باگ‌های تازه‌کارها از درک نادرست همین یک مفهوم ناشی می‌شود. نه از نود اشتباه، نه از تنظیمات غلط — از فرض اینکه خروجی همیشه یک آیتم است.

ورک‌فلوی نمونه‌ای که باید در ذهن داشته باشید:

  1. Webhook Trigger — نقطه‌ی ورود. یک URL اختصاصی ایجاد می‌کند و درخواست HTTP را می‌گیرد.
  2. Set Node — فیلدهای موردنیاز (email، message) را از JSON خام استخراج و به نام‌های تمیز تبدیل می‌کند.
  3. Code Node — در صورت نیاز، تبدیل منطقی یا فیلتر انجام می‌دهد.
  4. HTTP Request Node — داده‌ی ساختاریافته را به API بیرونی ارسال می‌کند.
  5. Google Sheets Node — نتیجه را لاگ می‌گیرد.

Expression در n8n یک لایه‌ی JavaScript سبک است که داخل هر نود قابل استفاده می‌شود. برای استخراج فیلد تودرتو از JSON، شرط‌گذاری ساده و تبدیل نوع داده کافی است. اما وقتی منطق تبدیل پیچیده می‌شود، Code Node جایگزین بهتری است. مرز عملی: اگر Expression بیش از دو خط شد، به Code Node بروید.

مقایسه‌ی n8n با Node-RED یک اشتباه محتوایی رایج در فارسی است. هر دو node-based هستند، اما Node-RED برای IoT و edge computing ساخته شده و n8n برای API orchestration و SaaS integration. اگر نیازتان اتصال به سرویس‌های ابری و ساخت ایجنت هوشمند است، Node-RED ابزار اشتباهی است — نه ضعیف‌تر، بلکه برای مسئله‌ای کاملاً متفاوت طراحی شده.

اشتباه میدانی که در پروژه‌های اعضای کامیونیتی n8n مکرر تکرار می‌شود: تازه‌کارها نودها را می‌چینند اما خروجی JSON هر نود را بررسی نمی‌کنند. کلیک روی هر نود و دیدن تب خروجی (Output) باید عادت شود، نه مرحله‌ی آخر دیباگ.

n8n یا Zapier؟ مقایسه‌ای که بیشتر سایت‌ها اشتباه می‌کنند#

n8n یا Zapier: این دو جایگزین یکدیگر نیستند. Zapier برای اتوماسیون‌های ساده‌ی تک‌خطی و کاربر غیرتکنیکال ساخته شده. n8n برای ورک‌فلوهای چندشاخه با data transformation پیچیده قدرت دارد. انتخاب بین این دو، تصمیم فنی است نه سلیقه‌ای.

معیار n8n Zapier Make (Integromat) Activepieces
مدل قیمت‌گذاری Self-hosted رایگان / Cloud اشتراکی اشتراکی بر اساس task اشتراکی بر اساس operation Self-hosted رایگان / Cloud اشتراکی
انعطاف در data transformation بالا — Code Node و Expression محدود — Formatter و Code step متوسط — Functions پایین‌تر از n8n
تعداد integration بیش از 400 نود رسمی + community (در زمان نگارش این راهنما) بیش از 6000 اپلیکیشن (در زمان نگارش این راهنما) بیش از 1000 اپلیکیشن (در زمان نگارش این راهنما) در حال رشد، کمتر از n8n
منحنی یادگیری متوسط تا بالا پایین متوسط پایین تا متوسط
مناسب برای تیم‌های فنی، AI Agent، workflow چندشاخه اتوماسیون ساده، کاربر غیرتکنیکال اتوماسیون میانی با نیاز بصری اتوماسیون ساده با self-hosting

Activepieces در برابر n8n: هر دو open-source و node-based هستند. Activepieces برای اتوماسیون ساده‌تر و رابط کاربری سبک‌تر طراحی شده. n8n برای workflow چندشاخه، tool-calling و ایجنت‌های هوشمند ابزار کامل‌تری است. اگر نیازتان صرفاً «وقتی ایمیل آمد، در Sheets ثبت کن» است، Activepieces کافی است و پیچیدگی n8n را بی‌دلیل به پروژه تحمیل نکنید.

لایسنس fair-code n8n یک نکته‌ی حقوقی است که مستندات رسمی n8n.io توضیح داده: استفاده‌ی تجاری بدون محدودیت مجاز است، اما فروش خودِ n8n به‌عنوان سرویس (مثلاً ارائه به مشتری با برند خودتان) نیاز به قرارداد خاص دارد. این مرز را اکثر مقایسه‌های فارسی نادیده می‌گیرند.

نصب n8n با Docker: هزینه‌ی پنهانِ «رایگان»#

نصب n8n با Docker در چند دقیقه انجام می‌شود، اما «رایگان» فقط به لایسنس نرم‌افزار اشاره دارد. نگهداری self-hosted شامل هزینه‌ی سرور، بکاپ، آپدیت و monitoring است که اکثر مقایسه‌ها شفاف نمی‌گویند. هزینه‌ی کل عملیاتی را محاسبه کنید، نه فقط هزینه‌ی لایسنس را.

مراحل نصب با Docker Compose:

  1. یک فایل docker-compose.yml بسازید. Image اصلی: n8nio/n8n.
  2. برای persistence یک volume تعریف کنید. بدون volume، با هر restart همه‌ی workflow‌ها از بین می‌روند.
  3. PostgreSQL را به‌عنوان database تنظیم کنید. SQLite برای محیط production توصیه نمی‌شود.
  4. Redis را برای queue scaling اضافه کنید، به‌خصوص اگر workflow‌های پرتعداد اجرا می‌کنید.
  5. یک reverse proxy (مثل Nginx یا Caddy) برای HTTPS و authentication جلوی n8n بگذارید.

مدیریت credential و secret یکی از تصمیمات معماری مهم است. n8n یک Credential store داخلی دارد که رمزها را در database ذخیره و رمزنگاری می‌کند. استفاده از Environment Variable به‌جای Credential store یک اشتباه رایج است: workflow‌هایی که با env var ساخته شده‌اند قابل export و transfer به محیط دیگر نیستند. اگر بخواهید workflow را از dev به production منتقل کنید، باید همه‌چیز را دستی بازسازی کنید — و این دقیقاً همان کاری است که باید از ابتدا جلویش را بگیرید.

n8n Cloud در برابر self-hosted: چه زمانی کدام مناسب‌تر است#

n8n Cloud برای کسی که می‌خواهد بدون درگیر شدن با زیرساخت، فقط workflow بسازد مناسب است. self-hosted وقتی منطقی است که داده‌ی حساس دارید، نیاز به customization عمیق دارید، یا volume workflow‌هایتان آن‌قدر بالاست که هزینه‌ی اشتراک Cloud از هزینه‌ی سرور بیشتر می‌شود. برای شروع یادگیری، Cloud سریع‌تر است. برای تولید، self-hosted انعطاف بیشتری می‌دهد.

اولین workflow عملی: از Webhook تا AI Agent با tool-calling#

ساخت اولین workflow عملی در n8n که واقعاً کار انجام دهد — نه فقط متن تولید کند — از AI Agent node با tool-calling می‌گذرد. این node بر پایه‌ی LangChain ساخته شده و بدون tool-calling، ایجنت صرفاً یک chatbot است. تفاوت کلیدی در همین یک ویژگی است.

ورک‌فلوی کامل برای یک سناریوی واقعی (پاسخ خودکار به ایمیل پشتیبانی):

  1. Webhook Trigger — درخواست POST با فیلدهای email و message می‌گیرد.
  2. Set Node — فیلدهای خام را استخراج و به نام‌های تمیز تبدیل می‌کند.
  3. AI Agent Node — با LLM و tool-calling به Gmail و Google Sheets وصل است. ایجنت تصمیم می‌گیرد آیا پاسخ بدهد، لاگ کند، یا escalation بزند.
  4. Gmail Node — پاسخ نهایی را ارسال می‌کند.
  5. Google Sheets Node — رکورد کامل را لاگ می‌گیرد.

الگوی شکست رایج که در گفتگوهای اعضای کامیونیتی n8n بارها برمی‌گردد: ساخت AI Agent بدون tool-calling درست. تازه‌کار LLM را وصل می‌کند، prompt می‌نویسد و فکر می‌کند ایجنت ساخته. اما ایجنت واقعی تصمیم می‌گیرد کدام tool را صدا بزند، با چه پارامترهایی، و چه زمانی از tool بعدی استفاده کند. این تصمیم‌گیری، نه تولید متن، تعریف ایجنت است.

اتصال به مدل‌های زبانی در n8n#

n8n به‌صورت native به OpenAI، Anthropic و مدل‌های محلی (مثل Ollama) وصل می‌شود. برای مدل‌های محلی، یک HTTP Request node به endpoint Ollama کافی است. نکته‌ی عملی: مدل‌های محلی برای workflow‌هایی که داده‌ی حساس دارند (مثلاً اطلاعات مشتری) گزینه‌ی امن‌تری هستند، چون داده از سرور خارج نمی‌شود.

Error Handling و retry logic#

هر workflow واقعی با خطای API مواجه می‌شود. n8n دو لایه‌ی error handling دارد:

  • Retry on Fail — در تنظیمات نود فعال می‌شود. تعداد retry و فاصله‌ی زمانی قابل تنظیم است.
  • Error Workflow — یک workflow مستقل که وقتی workflow اصلی fail می‌کند، اجرا می‌شود. می‌تواند نوتیفیکیشن بفرستد یا fallback logic اجرا کند.

بدون error handling، یک خطای موقت در API کل workflow را متوقف می‌کند و هیچ‌کس متوجه نمی‌شود. اصل عملی: هر workflow که به API بیرونی وابسته است، باید retry logic داشته باشد. بدون استثنا.

چقدر زمان می‌برد تا با n8n اتوماسیون واقعی بسازم؟#

با n8n، نقشه‌ی یادگیری 3 هفته‌ای برای ساخت اتوماسیون واقعی کافی است — به شرط آشنایی با مفاهیم پایه‌ی API و JSON. هفته اول trigger و action ساده، هفته دوم Expression و data mapping، هفته سوم AI Agent و error handling. این زمان‌بندی بر اساس مشاهده‌ی الگوی پیشرفت اعضای کامیونیتی n8n استخراج شده است.

هفته اول — ساخت 3 workflow ساده بدون Expression:

  1. Lead capture — Webhook → Set → Google Sheets. هدف: درک ساختار Item و multi-item execution.
  2. گزارش‌دهی — Cron Trigger → HTTP Request → Slack. هدف: درک scheduling و response parsing.
  3. نوتیفیکیشن — Gmail Trigger → IF → Telegram. هدف: درک شرط‌گذاری ساده با IF node.

هفته دوم — data mapping و Expression:

  • خروجی هر نود را بررسی کنید. JSON Output را با چشم بخوانید.
  • Expression‌های ساده بنویسید: {{ $json.email }}، {{ $items()[0].json.name }}.
  • Code Node را امتحان کنید: یک function بنویسید که آرایه‌ی items را فیلتر یا transform کند.
  • اشتباه رایج: فرض کردن اینکه خروجی نود قبلی همیشه یک آیتم است. بررسی کنید.

هفته سوم — AI Agent و error handling:

  • AI Agent node را به workflow‌های هفته اول اضافه کنید.
  • Tool-calling را فعال کنید: حداقل یک tool (Gmail یا Sheets) به ایجنت بدهید.
  • Retry logic و Error Workflow اضافه کنید.
  • Fallback logic بنویسید: اگر ایجنت نتوانست پاسخ دهد، چه اتفاقی بیفتد؟

چه زمانی n8n ابزار اشتباهی است؟ سه حالت: اتوماسیون زیر 2 step (ساده‌تر از حد نیاز)، نیاز به UI سفارشی، و حجم بالای داده‌ی غیرساختاریافته. در این موارد نوشتن کد مستقیم یا استفاده از ابزار تخصصی منطقی‌تر است.

نتیجه‌ی عملی: n8n را جدی بگیرید اگر نیازتان فراتر از «وقتی X شد، Y بکن» است. اگر درک جریان JSON بین نودها را یاد بگیرید — نه فقط چیدن نودها — بعد از 3 هفته می‌توانید ایجنت‌های واقعی بسازید. اگر می‌خواهید این مسیر را با ساختار مشخص و پروژه‌ی عملی طی کنید، دوره‌ی «ساخت Ai Agent با N8N» در کامیونیتی اسکول دقیقاً برای همین طراحی شده: 51 جلسه، 41 ساعت، از نصب تا ایجنت با tool-calling. برای شروع دورهٔ ساخت Ai Agent با N8N و آشنایی با شرایط عضویت، صفحهٔ کامیونیتی را ببینید.