آموزش n8n گام‌به‌گام یعنی دو تصمیم را از هم جدا کردن: اول، تشخیص اینکه ورک‌فلوی شما اتوماسیون خطی است یا ایجنت حلقه‌ای؛ دوم، انتخاب بین نود بومی و Code node بر اساس نوع منطق. اکثر راهنماها این دو را یکی می‌گیرند و نتیجه‌اش تنظیم اشتباه نود AI Agent است. این مقاله هر دو تصمیم را با مثال عملی باز میکند.
n8n چیست و چرا بدون کدنویسی هم کار میکند؟#
n8n یک ابزار اتوماسیون ورک‌فلو (Workflow Automation Tool) بصری است که با اتصال نودها (Node) به هم، زنجیره‌ی دستورات می‌سازد؛ بیش از 400 integration بومی دارد و نسخه‌ی Community آن با مجوز Fair-code رایگان است. منطق اصلی: هر نود یک کار مشخص انجام میدهد و خروجی‌اش ورودی نود بعدی می‌شود.
نود، ورک‌فلو و کانکشن — سه مفهوم پایه#
نود (Node) واحد اجرایی است: یک Webhook، یک HTTP Request، یک Gmail، یک Code. ورک‌فلو (Workflow) زنجیره‌ی نودهاست که با کانکشن (Connection) به هم وصل شده‌اند. کانکشن جهت دارد — از خروجی نود قبلی به ورودی نود بعدی. اگر این سه مفهوم را درست ندانید، دیباگ کردن ورک‌فلو در پروداکشن تبدیل به کابوس می‌شود.
آیا باید JavaScript بلد باشم؟ پاسخ کوتاه: برای اکثر سناریوهای رایج نه#
نودهای بومی بخش عمده‌ی اتوماسیون را بدون کد پوشش می‌دهند. Set node برای تبدیل شکل داده، Filter node برای شرط‌های ساده، Merge node برای ترکیب شاخه‌ها. Code node فقط وقتی لازم است که منطق ترکیبی دارید — مثلاً حلقه روی آرایه با شرط‌های تودرتو، یا تبدیل داده‌ای که با نودهای بومی سه مرحله‌ای قابل‌انجام نیست.
راستش را بخواهید، مرز بین «نیاز به کد» و «نیاز نداشتن به کد» در n8n مبهم‌تر از آن است که راهنماها نشان می‌دهند. خیلی از نودهای بومی در ظاهر ساده‌اند، اما وقتی با داده‌ی واقعی سروکار دارید، خروجی‌شان آن‌قدر آشفته می‌شود که Set node دیگر جواب نمی‌دهد. در کلاس‌ها و گفتگوهای اعضای کامیونیتی، مکرر دیده می‌شود که کاربر ابتدا Set node می‌گذارد، بعد از سه بار تنظیم مجدد فیلدها، ناامید به Code node میرود و همان کار را در دو خط JavaScript انجام میدهد.
الگوی تصمیم‌گیری — نود بومی یا Code node؟#
معیار ساده: اگر کاری که می‌خواهید «تبدیل شکل داده» است (فیلد A را به فیلد B نگاشت کنید)، نود بومی کافی است. اگر «شرط‌های ترکیبی یا حلقه» دارد (برای هر آیتم در لیست، اگر شرط X آنگاه Y وگرنه Z)، Code node. اشتباه رایج در پروژههای واقعی: استفاده از Code node برای کاری که Set node انجام میدهد، یا برعکس — زور زدن برای انجام منطق حلقه‌ای با چند Filter node پشتسرهم.
نکته‌ای که کمتر گفته می‌شود: Filter node برای حذف آیتمها ساخته شده، نه برای مسیردهی شرطی. وقتی سه Filter node پشتسرهم میگذارید تا «اگر A، برو شاخه ۱؛ اگر B، برو شاخه ۲»، در واقع دارید IF/ELSE را با حذف تدریجی شبیهسازی می‌کنید. نتیجه‌اش ورک‌فلویی است که با هر تغییر منطق، باید سه نود را همزمان ویرایش کنید. Switch node دقیقاً برای همین ساخته شده.
نصب n8n با Docker یا استفاده از n8n Cloud؟#
نصب n8n با Docker Compose سریع‌ترین مسیر برای سرور شخصی است؛ اما اگر حجم اجرا پایین است و داده حساس ندارید، n8n Cloud از نظر هزینه-زمان منطقی‌تر است چون نگهداری سرور حذف می‌شود. تصمیم نهایی به حجم اجرا و الزامات امنیتی دادههای شما بستگی دارد.
مراحل نصب با Docker Compose#
- یک سرور با حداقل 2 گیگابایت RAM و Docker نصب‌شده آماده کنید.
- فایل docker-compose.yml بسازید؛ service اصلی n8n با image n8nio/n8n و port 5678.
- متغیر محیطی N8N_ENCRYPTION_KEY را تنظیم کنید.
- با دستور docker compose up -d سرویس را بالا بیاورید.
- در مرورگر به آدرس http://your-server:5678 بروید و اکانت ادمین بسازید.
- برای HTTPS، یک reverse proxy مثل Caddy یا Nginx در جلوی پورت 5678 بگذارید.
هزینه پنهان خودمیزبانی: آپدیت، بکاپ، مانیتورینگ#
نصب رایگان است، اما نگهداری رایگان نیست. آپدیت image هر چند هفته یک‌بار، بکاپ منظم دیتابیس SQLite یا PostgreSQL، مانیتورینگ سلامت سرویس (health check) و مدیریت crash recovery — همه این‌ها زمان می‌برند. در پروژههای خودمیزبانی که این سه کار را جدی نگرفته‌اند، از‌دست‌رفتن دادههای اجرا الگوی تکرارشونده‌ای است، نه استثنایی نادر.
چه‌وقت self-host اجباری است؟#
سه حالت: دادههای حساس دارید که نباید از سرور شما خارج شود (GDPR، دادههای بانکی)؛ حجم اجرا بالاست و هزینه Cloud به‌صرفه نیست؛ یا نیاز به نودهای سفارشی دارید که در Cloud قابل‌نصب نیستند. اگر هیچ‌کدام را ندارید، Cloud گزینه‌ی کم‌دردسرتر است.
یک استثنا که راهنماها نمی‌گویند: حتی اگر هیچ‌کدام از سه حالت بالا را ندارید، اگر ورکفلوهای شما به شبکه‌ی داخلی (intranet) دسترسی میخواهند — مثلاً فراخوانی API داخلی یا کوئری به دیتابیس on-premise — Cloud عملاً بیفایده است. چون ترافیک از اینترنت وارد سرور شما نمیشود و باید تونل بزنید. در آن حالت، خودمیزبانی نه «انتخاب» که «اجبار فنی» است.
اولین ورک‌فلو: از Webhook تا ارسال ایمیل#
اولین ورک‌فلو در n8n معمولاً این ساختار را دارد: یک نود Webhook Trigger داده را از فرم یا API میگیرد، یک نود Set فیلدها را نرمال میکند، و یک نود Gmail خروجی را می‌فرستد. سه نود، بدون کد، بدون پیچیدگی — و همین پایه‌ی ساخت ایجنت است.
ترتیب نودها: Webhook Trigger → Set → Gmail#
Webhook Trigger یک URL اختصاصی تولید میکند. وقتی درخواست POST به آن URL بیاید، بدنه‌ی JSON وارد نود بعدی می‌شود. نود Set فیلدهای خام را به ساختار تمیز تبدیل میکند — مثلاً نام و ایمیل را از بدنه‌ی فرم استخراج کنید. Gmail node با استفاده از Credential ذخیرهشده، ایمیل را ارسال میکند. هر نود در Execution Log ورودی و خروجی‌اش را نشان میدهد.
تنظیم Credential برای Gmail در n8n#
در بخش Credentials، نوع Gmail OAuth2 را انتخاب کنید. به Google Cloud Console بروید، یک OAuth Client ID بسازید، URI ریدایرکت را از صفحه‌ی Credential n8n کپی کنید، و در Google آن را به‌عنوان Authorized redirect URI ثبت کنید. بعد از اتصال حساب، Credential در n8n ذخیره می‌شود و در هر ورک‌فلو قابل‌استفاده است.
تست با curl و مشاهده‌ی خروجی در Execution Log#
URL وب‌هوک را از نود Webhook Trigger کپی کنید. با curl یک درخواست POST بفرستید:
curl -X POST https://your-n8n/webhook/test -H "Content-Type: application/json" -d '{"name":"Ali","email":"ali@example.com"}'
در صفحه‌ی ورک‌فلو، روی Execute Workflow کلیک کنید تا در حالت test mode اجرا شود. Execution Log هر نود را با داده‌ی ورودی و خروجی نشان میدهد — اینجا جایی است که اشتباهات mapping فیلد را پیدا می‌کنید.
تفاوت اتوماسیون و ایجنت: چرا ورک‌فلوی شما «ایجنت» نیست#
تفاوت اتوماسیون و ایجنت در یک چیز خلاصه می‌شود: حلقه. اتوماسیون یک مسیر خطی است — trigger فعال می‌شود، نودها به ترتیب اجرا میشوند، تمام. ایجنت حلقه‌ای است: LLM تصمیم میگیرد کدام ابزار را صدا بزند، نتیجه را می‌بیند، دوباره تصمیم میگیرد. اگر ورک‌فلو شما حلقه ندارد، ایجنت نیست — حتی اگر به GPT-4 وصل باشد.
الگوی خطی: Trigger → Action → Action → End#
در اتوماسیون خطی، ترتیب اجرا ثابت است. شما از قبل می‌دانید نود اول چه میکند، نود دوم چه میکند، و خروجی نهایی چیست. مثال: وقتی فرم پر شد، ایمیل بفرست + در CRM ثبت کن. هیچ تصمیمی در زمان اجرا گرفته نمیشود.
الگوی حلقه‌ای: Observe → Reason → Act → Observe#
ایجنت در هر دور، وضعیت فعلی را می‌خواند (Observe)، با LLM فکر میکند (Reason)، یک ابزار صدا می‌زند (Act)، نتیجه را می‌بیند، و اگر به پاسخ نرسیده، دوباره شروع میکند. این حلقه تا رسیدن به پاسخ نهایی یا رسیدن به حداکثر تکرار ادامه دارد.
چرا این تفکیک مهم است؟ چون بسیاری از کاربران n8n، یک نود LLM (مثلاً OpenAI Chat Model) را وسط ورک‌فلو می‌گذارند و فکر می‌کنند «ایجنت» ساخته‌اند. نه، نکرده‌اند. یک نود LLM در مسیر خطی، فقط خروجی‌اش را به نود بعدی میدهد — مثل هر نود دیگری. ایجنت واقعی وقتی است که LLM خودش تصمیم بگیرد چه ابزاری صدا بزند و چند دور تکرار کند.
نود AI Agent در n8n چطور حلقه را پیاده میکند#
نود AI Agent در n8n یک حلقه‌ی داخلی دارد: LLM با توجه به System Prompt و Tools تعریف‌شده تصمیم میگیرد کدام Tool را صدا بزند. خروجی Tool به LLM برمی‌گردد، LLM دوباره تصمیم میگیرد. این چرخه تا وقتی ادامه دارد که LLM خروجی نهایی تولید کند یا به حداکثر تکرار برسد. بدون Tool، این حلقه بی‌معنی است — LLM فقط حرف می‌زند.
ساخت ایجنت هوش مصنوعی با نود AI Agent و Tool Use#
نود AI Agent در n8n روی LangChain سوار است و با تعریف ابزار (Tool) به LLM، ایجنتی می‌سازد که خودش تصمیم میگیرد کدام API را صدا بزند. بدون Tool، این نود فقط یک چت‌بات با context است — نه ایجنت.
تنظیم نود AI Agent: انتخاب LLM، System Prompt و Memory#
در نود AI Agent، ابتدا مدل زبانی (LLM) را انتخاب کنید — OpenAI، Anthropic، یا هر provider سازگار با LangChain. System Prompt نقش ایجنت را تعریف میکند: «تو یک دستیار پشتیبانی هستی که با جستجو در پایگاه دانش، پاسخ می‌دهی.» Memory نوع حافظه است — Simple Memory برای یک اجرا، Postgres Chat Memory برای حفظ مکالمه بین اجراها.
اضافه کردن Tool: HTTP Request Tool، Database Tool، Web Search#
Toolها را در بخش Tools نود AI Agent اضافه می‌کنید. هر Tool یک توضیح (description) دارد که LLM با خواندن آن تصمیم میگیرد از این ابزار استفاده کند یا نه. مثال عملی: یک HTTP Request Tool برای فراخوانی API داخلی، یک Database Tool برای کوئری SQL، و یک SerpAPI Tool برای جستجوی وب. LLM خودش انتخاب میکند کدام را صدا بزند.
یک اشتباه پرهزینه که در تنظیم Toolها مکرر تکرار می‌شود: description مبهم یا عمومی. اگر بنویسید «این ابزار اطلاعات میدهد»، LLM هرگز آن را صدا نمیزند. description باید دقیقاً بگوید چه ورودی میگیرد و چه خروجی میدهد — مثل یک مستندات API واقعی. در پروژههای عملی، تفاوت بین ایجنتی که کار میکند و ایجنتی که در حلقه گیر کرده، اغلب فقط همین یک خط description است.
ورک‌فلوی کامل ایجنت: Webhook → AI Agent → Code → Slack#
سناریوی واقعی: یک درخواست از طریق Webhook وارد می‌شود. نود AI Agent با سه Tool (HTTP Request، Database، Web Search) تصمیم میگیرد چه‌طور پاسخ دهد. خروجی ایجنت یک JSON است. نود Code این JSON را پارس و فرمت میکند. نود Slack پیام نهایی را ارسال میکند. ترتیب نودها: Webhook Trigger → AI Agent (با 3 Tool) → Code (JSON.parse و فرمت‌دهی) → Slack Send Message.
ساخت RAG با n8n و Vector Store#
برای ایجنتی که روی دادههای شما پاسخ میدهد، RAG (Retrieval Augmented Generation) لازم است. در n8n: یک نود Vector Store (مثل Pinecone یا Qdrant) به‌عنوان Tool به AI Agent اضافه می‌شود. LLM قبل از پاسخ‌دهی، در Vector Store جستجو میکند و context مرتبط را میگیرد. نود Document Loader برای ورودی اولیه و Embedding Model برای تبدیل متن به بردار هم لازم است.
مقایسه n8n با Zapier و Make: معماری، نه فقط قیمت#
مقایسه n8n با Zapier و Make باید بر پایه‌ی معماری باشد، نه صرفاً قیمت: n8n open-source است، self-host می‌شود، LangChain native دارد، و نود Code داخلی. مقایسه‌ی صرف بر اساس قیمت، تفاوت‌های بنیادین را پنهان میکند.
جدول مقایسه‌ای: معماری، AI، مقیاس‌پذیری، هزینه، امنیت#
| معیار | n8n | Zapier | Make |
|---|---|---|---|
| مدل استقرار | Self-host + Cloud | فقط SaaS | فقط SaaS |
| منبع‌باز بودن | بله (Fair-code) | خیر | خیر |
| ایجنت AI بومی | بله (LangChain native) | محدود (AI Actions) | محدود (AI modules) |
| نود Code داخلی | بله (JavaScript/Python) | Path Formatter محدود | بله |
| مقیاس‌پذیری | Queue Mode + Worker | مدیریت‌شده | مدیریت‌شده |
| امنیت داده | داده روی سرور شما | داده روی سرور Zapier | داده روی سرور Make |
چه‌وقت Zapier بهتر است؟ چه‌وقت n8n؟#
برای اتوماسیون‌های بسیار ساده‌ی تک‌مرحله‌ای (مثل «وقتی ایمیل آمد، فوروارد کن»)، Zapier سریعتر راه‌اندازی می‌شود. برای پردازش داده‌ی حجیم ETL، ابزارهای تخصصی مثل Apache Airflow مناسب‌ترند. n8n وقتی بهترین است که منطق ترکیبی دارید، نیاز به self-host دارید، یا ایجنت AI با Tool Use می‌سازید.
محدودیت‌های n8n: چه‌کارهایی را نمی‌تواند بکند#
n8n برای streaming data (مثل پردازش لحظه‌ای هزاران رویداد در ثانیه) ساخته نشده — برای این کار Kafka + Flink مناسب‌ترند. برای batch processing عظیم (میلیونها رکورد)، ابزارهای ETL تخصصی کارآمدترند. و اگر تیم شما اصلاً با مفاهیم API و JSON آشنا نیست، منحنی یادگیری n8n از Zapier شیب‌دارتر است.
یک محدودیت که کمتر کسی صریح می‌گوید: n8n ابزار event-driven است، نه data-driven. یعنی برای سناریوهایی که در آن‌ها باید میلیونها رکورد را «بخوانید، تبدیل کنید، بنویسید»، n8n نود به نود اجرا میکند و مصرف حافظهاش خطی با حجم داده بالا میرود. در چنین سناریوهایی، یک اسکریپت Python ساده + Airflow schedule، هم سریعتر است هم قابلپیشبینیتر. n8n را برای این کار‌ها استفاده نکنید.
دیباگ و مدیریت خطا: اشتباهات معماری که ورک‌فلو را در پروداکشن می‌کشند#
دیباگ و مدیریت خطا در n8n سه اشتباه معماری تکرارشونده دارد: استفاده از Single Instance بدون Queue Mode در محیط پروداکشن، نگذاشتن Timeout روی HTTP Request node، و نبود Retry Logic. این سه، ورک‌فلوی تستی را در اجرا زنده نگه نمی‌دارند.
Error Workflow: فعال‌سازی نود Error Trigger#
در تنظیمات ورک‌فلو، یک Error Workflow جداگانه تعریف کنید. نود Error Trigger در آن ورک‌فلو، جزئیات خطا (نود فیل‌شده، پیام خطا، داده‌ی ورودی) را میگیرد و به Slack یا ایمیل می‌فرستد. بدون این، خطا در سکوت می‌میرد و شما تا کاربر شکایت نکند، متوجه نمی‌شوید.
تنظیم Timeout و Retry روی HTTP Request node#
HTTP Request node یک timeout پیش‌فرض طولانی دارد که در محیط پروداکشن کافی نیست — اگر API مقصد کند پاسخ دهد، ورک‌فلو برای مدت زیادی قفل می‌ماند. Timeout را روی 30 ثانیه تنظیم کنید. Retry را فعال کنید (حداقل 2 تلاش مجدد با backoff). این دو تنظیم ساده، بخش عمده‌ای از قطعی‌های پروداکشن را حذف می‌کنند.
Queue Mode و Worker: چه‌وقت لازم می‌شود#
وقتی هم‌زمانی اجراها بالاست یا ورکفلوهای طولانی دارید، Single Instance کافی نیست. در Queue Mode، نود اصلی (n8n) درخواست‌ها را در صف Redis می‌گذارد و Workerها اجرا می‌کنند. بدون Queue Mode، ورک‌فلوها صف میشوند و timeout می‌گیرند. فعال‌سازی: متغیر EXECUTIONS_MODE=queue و نصب Redis + یک یا چند Worker container.
دیباگ با Execution Log و breakpoint در نود Code#
Execution Log هر نود، داده‌ی ورودی و خروجی را نشان میدهد. اگر خروجی نود قبلی را در ورودی نود بعدی نمی‌بینید، mapping فیلد اشتباه است. در نود Code، می‌توانید با console.log دادههای میانی را چاپ کنید و در Output panel ببینید. این روش برای سناریوهای حلقه‌ای و تبدیل داده‌ی پیچیده ضروری است.
امنیت و مدیریت کلید API در n8n#
امنیت و مدیریت کلید API در n8n بر پایه‌ی نود Credential است: کلیدها در Credential ذخیره میشوند و در ورک‌فلو بهصورت متنی نشان داده نمی‌شوند. برای self-host، رمزنگاری با ENCRYPTION_KEY ضروری است؛ بدون آن، کلیدها در دیتابیس بهصورت plain text ذخیره میشوند.
تنظیم ENCRYPTION_KEY در Docker Compose#
در docker-compose.yml، متغیر N8N_ENCRYPTION_KEY را با یک رشته‌ی تصادفی حداقل 32 کاراکتری تنظیم کنید. این کلید، دادههای Credential را در دیتابیس رمزنگاری میکند. اگر این متغیر را بعداً عوض کنید، تمام Credentialهای ذخیرهشده غیرقابلبازگشت میشوند. آن را در یک password manager ذخیره کنید.
بهترین الگو: یک Credential مشترک در ورکفلوهای متعدد#
الگوی اشتباه: در هر ورک‌فلو یک Credential جداگانه بسازید. الگوی درست: یک Credential مشترک برای هر سرویس بسازید و در همهی ورک‌فلوها از همان استفاده کنید. اگر کلید API عوض شد، یک‌بار در Credential آپدیت می‌کنید و همهی ورک‌فلوها خودکار درست میشوند.
محدودیت‌های دسترسی: پروژه‌ها و سطح‌بندی کاربر#
در نسخه‌ی Enterprise و Cloud، قابلیت Projects وجود دارد که ورک‌فلوها را در فضاهای جداگانه با دسترسی‌های متفاوت سازمان میدهد. در Community Edition، این قابلیت محدودتر است. اگر تیم چند نفره دارید و می‌خواهید هر نفر فقط به ورکفلوهای خودش دسترسی داشته باشد، Projects را جدی بگیرید.
جمع‌بندی عملی: n8n ابزاری است که مرز بین اتوماسیون و ایجنت را با معماری مشخصی جدا میکند. اگر حلقه و Tool Use ندارید، ایجنت نساخته‌اید. اگر Timeout و Error Handling ندارید، ورک‌فلوی پروداکشن ندارید. این دو معیار، فاصله‌ی بین یک demo و یک سیستم واقعی است.
اگر می‌خواهید این مسیر را گام‌به‌گام و با پروژه‌ی واقعی طی کنید، دوره‌ی «ساخت Ai Agent با N8N» در کامیونیتی اسکول دقیقاً همین دو تصمیم — اتوماسیون یا ایجنت، نود بومی یا Code node — را در 51 جلسه و 10 فصل باز میکند.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته میشوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.