آموزش n8n مسیر عملی از نصب روی سرور شخصی تا ساخت ایجنت هوش مصنوعی (AI Agent) با حافظه است. برخلاف Zapier، n8n معماری ایجنت و ارکستراسیون چندمرحلهای را در خودش دارد؛ یعنی یک سکوی اتوماسیون node-based که هم ورک‌فلوی خطی می‌سازید و هم ایجنت stateful. اما دو شکست معماری مشخص — دام Expression و حلقه بیپایان ایجنت — هستند که بدون آگاهی ازشان، هفته‌ها وقتتان را می‌بلعند.
آموزش n8n از کجا شروع شود؟ پیش‌نیازهای واقعی بدون کدنویسی سنگین#
آموزش n8n به سه مفهوم پایه نیاز دارد: خواندن JSON، درک HTTP request و مفهوم API. کدنویسی JavaScript فقط در Code Node اختیاری است و اکثر ورک‌فلوها بدون آن ساخته می‌شوند. اگر این سه مفهوم را بلد نیستید، n8n برایتان فرسایشی خواهد بود و هر نودی که اضافه می‌کنید، به‌جای سرعت، سردرگمی می‌سازد.
سه پیش‌نیاز واقعی: JSON، HTTP، مفهوم API#
هر نود در n8n ورودی و خروجی JSON دارد. وقتی Gmail Trigger یک ایمیل را می‌گیرد، خروجی‌اش یک آبجکت JSON با فیلدهای subject، from، body و attachments است. اگر ندانید این ساختار چیست، در Expression گیر می‌کنید — همان دامی که در بخش «رایج‌ترین اشتباهات n8n» مفصلاً تحلیل شده.
HTTP request هم ستون فقرات اینتگریشن‌هاست. هر API که n8n صدا می‌زند، یک request با method (GET یا POST)، header و body می‌فرستد. درک این ساختار، نه نوشتن کد، شرط لازم است.
چه چیزهایی لازم نیست: فریمورک، فریمورک UI، الگوریتم#
n8n یک ابزار low-code است. شما نمی‌نویسید؛ کانفیگ می‌کنید. نیازی به React، Vue، Node.js یا الگوریتم‌های پیچیده نیست. تنها جایی که JavaScript واقعی لازم میشود Code Node است و آن هم برای تبدیل‌های داده‌ای است که Expression از عهده‌شان برنمی‌آید.
مسیر پیشنهادی یادگیری: ورکفلو ساده → Expression → Code Node → AI Agent#
تجربهی میدانی از پروژه‌های اعضای کامیونیتی نشان میدهد مسیری که جواب میدهد این است:
- یک ورک‌فلوی خطی ساده بسازید (مثلاً Gmail → Google Sheets) تا با UI و ترتیب نودها آشنا شوید.
- Expression را عمیق یاد بگیرید؛ این لایه‌ی مستقلی است که اکثر کاربران تازه‌کار در آن گیر می‌کنند.
- Code Node را فقط برای تبدیل‌هایی که Expression نمی‌تواند انجام دهد استفاده کنید.
- بعد از تسلط بر سه مرحله‌ی بالا، سراغ AI Agent node بروید.
برای درک عمیق‌تر JSON، مقاله‌ی آموزش JSON برای مبتدیان را بخوانید. برای مفهوم REST API، مقاله‌ی REST API در یک دقیقه کفایت میکند.
نصب n8n با Docker: گام‌به‌گام روی سرور لینوکس#
نصب n8n با Docker روی سرور لینوکس، سریع‌ترین و قابل‌تکرارترین روش است. با یک فایل docker-compose در کمتر از 5 دقیقه n8n Community Edition بالا می‌آید. اما اگر قصد استفاده از AI Agent node با مدل محلی دارید، حداقل 4 گیگابایت RAM لازم است و 1 گیگابایت فقط برای ورک‌فلوهای ساده کافی است.
حداقل سخت‌افزار: 1GB RAM برای ورکفلو ساده، 4GB برای ایجنت#
تجربهی عملی از سرورهای members نشان میدهد: ورک‌فلوهای ساده با 1 گیگابایت RAM بدون مشکل اجرا می‌شوند. به محض اضافه کردن AI Agent node با مدل محلی (مثلاً Ollama)، مصرف RAM به بالای 3 گیگابایت می‌رسد. 4 گیگابایت حداقل امن است.
گام‌های نصب با docker-compose#
فایل نمونه‌ی docker-compose.yml:
در این فایل، volume برای persist کردن داده‌ها و environment variables برای تنظیمات پایه تعریف شده‌اند:
- data: مسیر پایگاه داده SQLite یا PostgreSQL
- N8N_BASIC_AUTH_ACTIVE: فعال‌سازی احراز هویت پایه
- N8N_HOST: دامنه‌ی سرور شما
- WEBHOOK_URL: آدرس وبهوک برای triggerهای خارجی
گام‌های نصب:
- سرور لینوکس (Ubuntu 22.04+) با Docker و Docker Compose نصب‌شده آماده کنید.
- فایل docker-compose.yml را در یک دایرکتوری بسازید.
- دستور docker compose up -d را اجرا کنید.
- پورت 5678 را در فایروال باز کنید.
- مرورگر را روی http://your-server:5678 باز کنید.
- اکانت ادمین بسازید و وارد داشبورد شوید.
تنظیم reverse proxy و HTTPS با Nginx#
برای دسترسی امن از بیرون، Nginx را بهعنوان reverse proxy جلوی n8n قرار دهید. یک server block با proxy_pass به localhost:5678 و گواهی SSL از Let's Encrypt کافی است. بدون HTTPS، وبهوک‌ها در سرویس‌های خارجی (مثل Gmail) کار نمی‌کنند.
اولین ورکفلو n8n: اتصال Gmail به Google Sheets#
اولین ورکفلو n8n که همه‌ی مفاهیم پایه را پوشش میدهد این است: Gmail Trigger → IF (فیلتر موضوع) → Google Sheets Append → Error Workflow. این ترکیب، trigger، شرط‌گذاری، عملیات روی داده و مدیریت خطا را یکجا آموزش میدهد و بهعنوان اولین پروژه‌ی عملی، تمام لایه‌های n8n را لمس می‌کنید.
Trigger Node و مفهوم Webhook در n8n#
Webhook (وبهوک) مکانیزمی است که در آن سرویس خارجی، وقتی رویدادی رخ میدهد، به آدرس مشخصی درخواست HTTP می‌فرستد. Gmail Trigger در n8n از این مکانیزم استفاده میکند: شما یک URL به گوگل می‌دهید و هر ایمیل جدید، آن URL را صدا می‌زند.
نکته‌ی عملی: اگر روی سرور شخصی هستید، webhook URL باید از بیرون قابل‌دسترس باشد. یعنی HTTPS و reverse proxy حتماً تنظیم شده باشد.
سیستم Expression: خواندن داده از نود قبلی بدون حفظ JSON path#
Expression در n8n یک لایه‌ی یادگیری مستقل است. وقتی می‌خواهید فیلدی از خروجی نود قبلی را در نود بعدی استفاده کنید، باید مسیر آن فیلد را در JSON بنویسید. مثال: اگر خروجی Gmail Trigger آبجکتی با ساختار {{ $json.body.content }} است، در نود بعدی باید دقیقاً همین مسیر را بنویسید.
اشتباه رایج: کاربران تازه‌کار مسیر JSON را از ذهن حفظ می‌کنند. روش درست این است که در پنل output نود قبلی، روی فیلد موردنظر drag کنید تا Expression بهصورت خودکار ساخته شود. این کار خطای تایپی را حذف میکند.
Code Node برای تبدیل‌هایی که Expression از عهده‌شان برنمی‌آید#
Expression برای خواندن یک فیلد و ساده‌سازی آن کافی است. اما اگر باید آرایه‌ای را فیلتر کنید، رشته‌ای را با regex تغییر دهید یا چند فیلد را به یک آبجکت جدید تبدیل کنید، Code Node با JavaScript واقعی لازم میشود.
مثال: ایمیل‌های Gmail گاهی body را بهصورت multipart/alternative برمی‌گردانند. استخراج بخش text/plain از این ساختار با Expression ممکن نیست و باید در Code Node بنویسید.
Credentials و مدیریت احراز هویت OAuth#
n8n از طریق Credentials Manager، توکن‌های OAuth را ذخیره و refresh میکند. برای Gmail، یک credential از نوع OAuth2 بسازید، به اکانت گوگل متصل شوید و توکن‌ها خودکار تمدید می‌شوند. در محیط production، credential rotation را فراموش نکنید.
n8n یا Zapier؟ مقایسه‌ای که بیشتر آموزش‌ها نمی‌گویند#
n8n یا Zapier؟ پاسخ بستگی به نوع ورکفلو دارد. n8n در ورک‌فلوهای شاخه‌دار، ارکستراسیون ایجنت و محیط‌های self-hosted برتری دارد. Zapier در اتوماسیون‌های خطی ساده با 2-3 مرحله و بدون نیاز به زیرساخت، سریع‌تر جواب میدهد. انتخاب Zapier برای ایجنت هوش مصنوعی، انتخاب شکست از قبل‌تصمیم‌گرفته‌شده است.
مدل معماری: node-based باز در برابر connector-based بسته#
معماری n8n node-based است: هر نود یک واحد مستقل با ورودی و خروجی مشخص دارد و شما آزادی دارید هر نودی را به هر نود دیگری وصل کنید. Zapier connector-based است: شما یک trigger و یک action انتخاب می‌کنید و منطق داخلی پنهان است.
هزینه: Community Edition رایگان در برابر اشتراک ماهانه Zapier#
n8n Community Edition کاملاً رایگان و متن‌باز است و بدون محدودیت تعداد ورکفلو روی سرور شخصی اجرا میشود. Zapier مدل اشتراک ماهانه دارد که با افزایش تعداد task، هزینه بالا می‌رود.
انعطاف: Code Node در n8n در برابر محدودیت Zapier#
Code Node در n8n به شما اجازه میدهد JavaScript بنویسید. Zapier Code steps محدودیت‌هایی در زمان اجرا و دسترسی به کتابخانه‌ها دارد.
چه زمانی Make گزینه‌ی بهتری است#
Make (سابقاً Integromat) بین n8n و Zapier قرار می‌گیرد. اگر نمی‌خواهید سرور مدیریت کنید ولی از Zapier پیچیده‌تر نیاز دارید، Make منطقی‌تر است.
| معیار | n8n | Zapier | Make |
|---|---|---|---|
| Self-hosted | بله، رایگان | خیر | خیر |
| AI Agent با حافظه | بله، native | محدود | محدود |
| ورکفلو خطی ساده | سنگین | سریع | سریع |
| هزینه مقیاس بالا | هزینه‌ی سرور | اشتراک ماهانه | اشتراک ماهانه |
| Code Node | JavaScript کامل | محدود | محدود |
ایجنت هوش مصنوعی در n8n: معماری Loop، Tool و Memory#
ایجنت هوش مصنوعی در n8n از طریق LangChain به مدلهای زبانی بزرگ (LLM) وصل میشود. برخلاف ورکفلو معمولی که stateless و خطی است، AI Agent stateful و loop-based عمل میکند: state بین اجراها حفظ میشود و ایجنت می‌تواند چند بار Tool صدا بزند تا به جواب برسد. بدون درک این معماری، هر ایجنتی که بسازید، یک بمب ساعتی روی سرورتان است.
تفاوت Stateless Workflow و Stateful Agent در n8n#
ورک‌فلوی معمولی: trigger می‌آید، نودها یکی‌یکی اجرا می‌شوند، تمام. هیچ حافظه‌ای بین دو اجرا وجود ندارد. AI Agent: ایجنت یک goal دارد، Tool صدا می‌زند، نتیجه را بررسی میکند، اگر کافی نبود دوباره Tool صدا می‌زند. این loop تا رسیدن به جواب یا رسیدن به Max Iterations ادامه دارد.
Tool Calling: تعریف ابزار برای ایجنت#
Tool در n8n یک ورک‌فلوی جداگانه است که ایجنت آن را صدا می‌زند. مثال: یک Tool برای جستجوی وب، یک Tool برای خواندن Google Sheets، یک Tool برای ارسال ایمیل. ایجنت بر اساس context تصمیم می‌گیرد کدام Tool را صدا بزند.
نکته‌ی حیاتی: تعریف ناقص Tool (بدون توضیح واضح یا بدون محدودیت ورودی) شایع‌ترین علت حلقه بیپایان است. ایجنت نمی‌فهمد چه زمانی باید Tool را صدا نزند.
Memory Node و ساخت ایجنت چت با حافظه#
Memory Node در n8n، مکالمه‌ی قبلی را ذخیره میکند تا ایجنت در دور بعدی، context قبلی را بداند. بدون Memory، هر اجرا برای ایجنت مثل اولین بار است. برای ساخت چت‌بات، ترکیب Chat Trigger + AI Agent + Memory Node الگوی استاندارد است.
تنظیم Max Iterations برای جلوگیری از حلقه بیپایان#
Max Iterations سقف تعداد دورهای loop ایجنت را تعیین میکند. بدون این تنظیم، اگر Tool تعریف‌شده مشکل داشته باشد، ایجنت تا ابد loop می‌زند و سرور را از پا می‌اندازد. مقدار منطقی: 5 تا 10. بیشتر از آن یعنی Tool شما بد تعریف شده.
اتصال به OpenAI API و مدلهای محلی#
n8n از طریق LangChain node به OpenAI، Anthropic و مدلهای محلی (Ollama) وصل میشود. برای مدل محلی، RAM بیشتری لازم است. برای OpenAI، یک API key کافی است و هزینه بر اساس توکن محاسبه میشود.
برای درک عمیق‌تر LangChain، مقاله‌ی آموزش LangChain برای مبتدیان را ببینید.
رایج‌ترین اشتباهات n8n: دام Expression و حلقه بیپایان ایجنت#
رایج‌ترین اشتباهات n8n دو شکست معماری مشخص است: اول، گیر کردن در درک JSON path در Expression؛ دوم، حلقه بیپایان ایجنت به‌خاطر تعریف ناقص Tool یا نبود حد Iteration. این دو، بیشترین وقت کاربران تازه‌کار را می‌بلعند و اگر از اول نشناسیدشان، به‌جای 2 هفته، 2 ماه درگیر دیباگ بیپایان می‌شوید.
دام Expression: چرا drag-and-drop از output نود قبلی بهتر از حفظ مسیر JSON است#
بسیاری از کاربران تازه‌کار، خروجی نود قبلی را نگاه می‌کنند، مسیر JSON را از ذهن حفظ می‌کنند و در نود بعدی تایپ می‌کنند. نتیجه: یک کاراکتر اشتباه، کل ورکفلو می‌شکند و دیباگ کردنش دردناک است.
روش درست: در پنل output نود قبلی، روی فیلد موردنظر drag کنید. n8n خودش Expression را با مسیر دقیق می‌سازد. این کار خطای انسانی را حذف میکند.
Agent Loop: نشانه‌ها، علت و راه‌حل#
نشانه‌ی حلقه بیپایان: ورکفلو اجرا میشود، لاگ‌ها پر از فراخوانی Tool هستند، ولی نتیجه نهایی هرگز تولید نمی‌شود. علت: Tool بدون توضیح کافی تعریف شده و ایجنت نمی‌فهمد چه زمانی کار تمام است.
راه‌حل سه‌مرحله‌ای:
- Max Iterations را روی 5 تا 10 تنظیم کنید.
- یک Fallback Node بعد از AI Agent بگذارید که اگر ایجنت به جواب نرسید، خطای مشخصی برگرداند.
- توضیح Tool را بازنویسی کنید: مشخص بگویید چه زمانی نباید صدا زده شود.
اشتباه رایج: استفاده از Code Node برای کاری که Expression انجام میدهد#
اگر فقط یک فیلد از خروجی نود قبلی لازم دارید، Expression کافی است. Code Node اضافه، ورکفلو را کند و دیباگ را سخت میکند. Code Node فقط برای تبدیل‌های چندمرحلهای یا regex پیچیده.
اشتباه رایج: نادیده گرفتن Error Workflow در محیط production#
در محیط development، اگر نودی fail شود، در لاگ میبینید. در production، اگر Error Workflow تنظیم نکرده باشید، ورکفلو بی‌صدا شکست می‌خورد و شما تا هفته‌ی بعد متوجه نمی‌شوید.
مدیریت خطا و Error Workflow در n8n#
مدیریت خطا در n8n از طریق Error Workflow انجام میشود: یک ورک‌فلوی جداگانه که در صورت شکست هر نود در ورک‌فلوهای دیگر، خودکار اجرا میشود. ترکیب آن با Retry و اعلان Slack، کمترین زمان تشخیص خطا را در محیط production میدهد و بدون آن، ورک‌فلوهای شما در تاریکی اجرا می‌شوند.
تنظیم Retry روی نودهای حساس#
نودهایی که به API خارجی وصل هستند (مثلاً HTTP Request) گاهی به‌خاطر قطعی موقت fail می‌شوند. با فعال‌سازی Retry (مثلاً 3 بار با فاصله‌ی 5 ثانیه)، بخش عمده‌ای از خطاهای transient بدون نیاز به مداخله‌ی انسانی حل می‌شوند.
ساخت Error Workflow: Trigger → IF (نوع خطا) → اعلان Slack#
Error Workflow خودش یک ورک‌فلوی معمولی است با این ترتیب: Error Trigger → IF (بررسی نوع خطا) → Slack Notification. می‌توانید بر اساس نوع خطا، کانال‌های مختلف Slack را صدا بزنید: خطای credential به کانال ops، خطای timeout به کانال dev.
تفاوت مدیریت خطا در n8n Cloud و self-hosted#
در self-hosted، لاگ‌ها روی سرور شما هستند و دسترسی کامل دارید. در n8n Cloud، لاگ‌ها محدود و در داشبورد وب قابل‌مشاهده‌اند. اگر به لاگ‌های سفارشی یا alerting پیچیده نیاز دارید، self-hosted دست‌بازتر است.
Credential Rotation در محیط production#
توکن‌های OAuth در n8n خودکار refresh می‌شوند، اما در صورت revocation (لغو دسترسی توسط سرویس خارجی)، ورکفلو با خطای authentication fail میشود. Error Workflow باید این نوع خطا را جدا تشخیص دهد و اعلان بفرستد تا سریع credential جدید بسازید.
n8n Cloud یا self-hosted؟ محدودیت‌ها و هزینه#
n8n Cloud یا self-hosted؟ انتخاب بستگی به نیاز شما دارد. n8n Cloud طرح رایگان با محدودیت تعداد اجرا دارد و برای شروع سریع مناسب است. self-hosted بدون محدودیت workflow و execution رایگان است اما مدیریت سرور، آپدیت و Credential Rotation را خودتان بر عهده دارید.
مقایسه هزینه و محدودیت: Cloud free tier در برابر Community Edition#
n8n Cloud free tier تعداد محدودی اجرا در ماه دارد. Community Edition self-hosted هیچ محدودیت تعداد اجرا ندارد ولی هزینه‌ی سرور و زمان مدیریت را خودتان می‌پردازید. اگر ماهانه چند صد اجرا دارید، Cloud منطقی‌تر است. اگر هزاران اجرا یا ورک‌فلوی پیچیده دارید، self-hosted ارزان‌تر تمام میشود.
چه زمانی self-hosted اجباری است: داده حساس، مقیاس، هزینه#
سه حالت که self-hosted تنها گزینه است: داده‌ی حساسی دارید که نمی‌تواند از سرور شما خارج شود؛ مقیاس‌تان آنقدر بالاست که اشتراک Cloud گران میشود؛ یا به Code Node و کتابخانه‌های سفارشی نیاز دارید که در Cloud محدود هستند.
چه زمانی Cloud منطقی‌تر است: تست سریع، بدون زیرساخت#
اگر می‌خواهید یک ایده را در یک بعدازظهر تست کنید و سرور ندارید، Cloud free tier شروع سریع‌تری است. بعد از تأیید ایده، اگر به مقیاس رسیدید، مهاجرت به self-hosted با export/import ورک‌فلوها ساده است.
محدودیت‌های self-hosted که آموزش‌ها نمی‌گویند#
نکته‌ای که کمتر جایی نوشته میشود: در self-hosted، هر آپدیت n8n ریسک breaking change دارد. قبل از آپدیت، حتماً snapshot از volume بگیرید. همچنین webhook URL باید از بیرون قابل‌دسترس باشد؛ یعنی فایروال، DNS و SSL همگی باید درست تنظیم باشند. این‌ها در Cloud خودکار هستند.
جمع‌بندی عملی#
n8n ابزاری است که اگر با معماری ایجنت آن آشنا شوید، در ارکستراسیون AI و اتوماسیون پیچیده، جایگزین‌ناپذیر میشود. اما اگر فقط یک ورک‌فلوی خطی 2-3 مرحله‌ای نیاز دارید، Zapier یا Make را انتخاب کنید و وقتتان را صرف n8n نکنید.
دو نقطه‌ی عطف یادگیری را به‌خاطر بسپارید: اول، Expression را با drag-and-drop یاد بگیرید نه با حفظ مسیر JSON. دوم، AI Agent را بدون Max Iterations و Fallback Node هرگز به production نفرستید.
اگر می‌خواهید این مسیر را سریع‌تر و با پشتیبانی طی کنید، دوره‌ی «ساخت AI Agent با n8n» در کامیونیتی n8n اسکول، 51 جلسه و 10 فصل دارد که از ورک‌فلوی ساده تا ایجنت با حافظه را پوشش میدهد.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته می‌شوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.