آموزش n8n در محیط self-hosted یعنی ساخت ورک‌فلو (Workflow) و ایجنت هوش مصنوعی (AI Agent) روی سرور شخصی، نه در پلتفرم ابری. برای کاربر ایرانی، این تنها مسیر عملی است؛ محدودیت پرداخت ارزی، Cloud را عملاً از دسترس خارج کرده. اما یک هشدار جدی: n8n ابزار no-code واقعی نیست. بدون درک API، JSON و Expression، ساده‌ترین ورک‌فلو هم به کابوس تبدیل می‌شود. این مقاله دقیقاً همان مرز را مشخص می‌کند.

آموزش n8n بدون برنامه‌نویسی: مرز واقعی کجا است؟#

آموزش n8n بدون برنامه‌نویسی سنتی ممکن است، اما سه مهارت پیش‌نیاز دارد که آموزش‌های فارسی معمولاً از آن‌ها عبور می‌کنند: درک ساختار JSON، توانایی خواندن پاسخ HTTP، و نوشتن Expression ساده. بدون این سه، عملاً نمی‌توانید داده را بین نودها منتقل کنید. برنامه‌نویسی لازم نیست؛ سواد فنی لازم است. این دو یکی نیستند.

معماری node-based n8n و جایگاه هر مفهوم#

n8n یک موتور مبتنی بر نود (Node-Based Engine) است. هر نود واحدی مستقل با ورودی و خروجی مشخص دارد. داده به‌صورت JSON از نودی به نود بعدی جریان می‌یابد. شما کد نمی‌نویسید، اما باید ساختار این JSON را بخوانید و بفهمید کدام فیلد در کدام نود قرار دارد.

یک مثال که این را ملموس می‌کند: Webhook Trigger داده‌ای دریافت می‌کند که در نود بعدی به‌صورت {{ $json.body.email }} قابل‌دسترسی است. اگر ندانید این مسیر داده (Data Path) چیست، ایمیل را استخراج نمی‌کنید. نه با کلیک، نه با drag-and-drop.

سه مهارت پیش‌نیازی که آموزش‌های فارسی نادیده می‌گیرند#

  • HTTP و REST API: باید بدانید GET و POST چه تفاوتی دارند، status code یعنی چه، و بدنه‌ی پاسخ چگونه ساختار دارد. این پیش‌نیاز نیست؛ شرط ورود است.
  • JSON: آشنایی با object، array، nesting و دسترسی به فیلدهای تودرتو. بدون این، داده از یک نود به نود بعدی نمی‌رسد و ورک‌فلوی شما فقط یک نمودار زیباست.
  • Expression: نوشتن عبارات ساده مانند {{ $json.name + " " + $json.family }} برای ترکیب فیلدها. کدنویسی نیست، اما منطق برنامه‌نویسی دارد و همین مرز را مبهم می‌کند.

چه سطحی از کدنویسی واقعاً لازم است؟#

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

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

نصب n8n با Docker روی سرور شخصی: گام‌به‌گام#

نصب self-hosted n8n با Docker چهار مرحله اصلی دارد: آماده‌سازی سرور، اجرای container، اتصال دیتابیس PostgreSQL و تنظیم پروکسی معکوس (Reverse Proxy). بدون این چهار گام، ورک‌فلوی شما در محیط production قابل‌اتکا نیست. با اولین restart سرور، اگر volume تنظیم نکرده باشید، همه‌چیز از بین می‌رود.

حداقل مشخصات سرور و چرا RAM تعیین‌کننده است#

n8n به‌صورت single-threaded اجرا می‌شود و مصرف RAM آن مستقیماً با تعداد ورک‌فلوهای همزمان و حجم داده‌ی هر execution رشد می‌کند. سرور با 2 گیگابایت RAM برای شروع کافی است، اما اگر چند ورک‌فلوی سنگین دارید یا از Queue Mode استفاده می‌کنید، به RAM بالاتر نیاز دارید. CPU کمتر از دو هسته گلوگاه ایجاد می‌کند.

یک اشتباه رایج در انتخاب سرور: کاربران ایرانی سراغ ارزان‌ترین VPS می‌روند و بعد از فعال‌سازی چند ورک‌فلوی همزمان، OOM Kill می‌گیرند. RAM ارزان‌تر از downtime است.

فایل docker-compose با PostgreSQL و Redis برای Queue Mode#

نصب n8n را در چند گام انجام دهید:

  1. یک سرور لینوکسی (Ubuntu یا Debian) با دسترسی SSH تهیه کنید.
  2. Docker و Docker Compose را نصب کنید.
  3. فایل docker-compose.yml را بسازید. در این فایل، سه سرویس تعریف می‌شود: n8n، PostgreSQL (برای ذخیره‌ی ورک‌فلوها و execution log) و Redis (برای Queue Mode و توزیع بار بین workerها).
  4. متغیرهای محیطی کلیدی را تنظیم کنید: N8N_ENCRYPTION_KEY برای رمزنگاری credentialها، EXECUTIONS_MODE=queue برای فعال‌سازی worker، و DB_TYPE=postgresdb برای اتصال به PostgreSQL.
  5. با docker-compose up -d سرویس‌ها را بالا بیاورید.

نکته‌ای که آموزش‌ها نمی‌گویند و هزینه‌اش سنگین است: اگر N8N_ENCRYPTION_KEY را تنظیم نکنید، n8n خودش یک کلید تصادفی می‌سازد. با هر restart container، کلید عوض می‌شود و همه‌ی credentialهای ذخیره‌شده غیرقابل‌خواندن می‌شوند. نه بازیابی ممکن است، نه لاگ مفید. این کلید را در یک فایل env خارج از container ذخیره کنید.

تنظیم reverse proxy و HTTPS#

n8n روی پورت 5678 اجرا می‌شود و خودش HTTPS ندارد. باید یک reverse proxy جلوی آن بگذارید. Nginx رایج‌ترین گزینه است، اما Caddy ساده‌تر است چون HTTPS خودکار با Let's Encrypt را بدون تنظیم دستی گواهی (Certificate) انجام می‌دهد.

در تنظیمات reverse proxy، حتماً WebSocket را فعال کنید. بدون آن، صفحه‌ی Editor در مرورگر باز می‌شود اما ورک‌فلوها اجرا نمی‌شوند و خطای اتصال (Connection Error) می‌گیرید. این یکی از رایج‌ترین مشکلات نصب self-hosted است و دقیقاً همان چیزی است که باعث می‌شود تازه‌واردها فکر کنند n8n خراب است.

مدیریت آپدیت بدون downtime#

اگر از Volume برای ذخیره‌ی داده‌های n8n استفاده کنید، آپدیت به‌سادگی با تغییر تگ image و اجرای docker-compose up -d انجام می‌شود. اما قبل از آپدیت، حتماً database را backup بگیرید. آپدیت‌های major (مثلاً از نسخه‌ی 1 به 2) ممکن است migration schema داشته باشند و بدون backup، ورک‌فلوهای شما آسیب ببینند.

قاعده‌ی ساده: قبل از هر تغییر تگ image، یک pg_dump بگیرید. دو دقیقه وقت می‌برد، یک هفته ریکاوری را نجات می‌دهد.

ساخت اولین workflow: از Trigger تا Output با ترتیب نودها#

ساخت اولین workflow در n8n یعنی چیدن نودها به‌ترتیب: Webhook Trigger برای دریافت داده، IF Node برای بررسی شرط، HTTP Request Node برای فراخوانی API خارجی، و نود خروجی برای ارسال نتیجه. این پنج نود، ستون فقرات بخش عمده‌ای از ورک‌فلوهای واقعی است. تغییر فقط در پارامترها است، نه در ساختار.

تعریف Trigger: Webhook در مقابل Schedule در مقابل Event-based#

سه نوع Trigger اصلی دارید و انتخاب بین آن‌ها بستگی به ماهیت رویداد دارد، نه ترجیح شخصی:

  • Webhook Trigger: وقتی یک فرم پر می‌شود، یک ایمیل می‌آید یا یک سرویس بیرونی درخواست POST می‌فرستد. مناسب برای اتوماسیون رویدادمحور.
  • Schedule Trigger: هر N دقیقه یا ساعت اجرا می‌شود. مناسب برای گزارش‌دهی دوره‌ای و sync داده. اگر داده‌ی شما بلادرنگ نیست، Schedule ساده‌تر و قابل‌پیش‌بینی‌تر است.
  • Event-based Trigger: نودهای اختصاصی مثل Gmail Trigger، Telegram Trigger یا Slack Trigger. ساده‌ترین گزینه چون authentication داخلی دارند.

زنجیره نودها در یک مثال عملی#

سناریو: دریافت lead از فرم وب‌سایت، بررسی امتیاز، و ارسال به Telegram.

  1. Webhook Trigger — endpoint /lead تعریف می‌کنید. فرم وب‌سایت POST می‌فرستد.
  2. Set Node — فیلدهای JSON را به نام‌های خوانا تغییر می‌دهید (مثلاً body.name به fullName).
  3. IF Node — شرط: اگر امتیاز lead از آستانه‌ی مشخص بالاتر باشد، ادامه بده؛ وگرنه به نود «رد» برو.
  4. HTTP Request Node — فراخوانی API یک ابزار CRM برای ثبت lead.
  5. Telegram Node — ارسال پیام به کانال فروش با خلاصه‌ی lead.

این ترتیب نودها را در هر ورک‌فلوی واقعی تکرار می‌کنید.

استفاده از Credential Manager به‌جای hardcode کردن API Key#

هرگز API Key را مستقیم در نود HTTP Request ننویسید. در بخش Credentials، کلید را ذخیره کنید و در نود به آن ارجاع دهید. دلیل فنی: اگر ورک‌فلو را export کنید یا در محیط staging تست کنید، کلید واقعی در فایل JSON شما باقی می‌ماند و در Git commit می‌شود. Credential Manager این مشکل را حل می‌کند چون کلید رمزنگاری‌شده در database ذخیره می‌شود.

یک قاعده‌ی بی‌استثنا: هیچ کلید API نباید در فایل JSON خروجی ورک‌فلو ظاهر شود. اگر در export شما رشته‌ای شبیه sk-... یا Bearer می‌بینید، فوراً کلید را revoke کنید.

n8n Cloud یا Self-hosted؟ تصمیم بر اساس مقیاس و محدودیت پرداخت#

n8n Cloud یا Self-hosted؟ برای کاربر ایرانی، self-hosted تنها گزینه‌ی عملی است. محدودیت پرداخت ارزی، تحریم سرویس‌های ابری و ریسک قطع حساب، Cloud را عملاً بی‌استفاده می‌کند. حتی اگر پرداخت ممکن باشد، در مقیاس متوسط و بالا، self-hosted از نظر هزینه به‌طور قابل‌توجهی ارزان‌تر است چون هزینه‌ی هر execution اضافی ندارد.

جدول مقایسه‌ای#

معیار n8n Cloud n8n Self-hosted Zapier Make
مدل قیمت‌گذاری بر اساس تعداد execution رایگان (فقط هزینه سرور) بر اساس تعداد task بر اساس تعداد operation
دسترسی برای کاربر ایرانی محدود (پرداخت ارزی) کاملاً آزاد محدود محدود
کنترل روی داده روی سرور n8n روی سرور شما روی سرور Zapier روی سرور Make
تعداد integration چند صد چند صد + سفارشی چند هزار بیش از هزار
پیچیدگی راه‌اندازی کم متوسط کم کم
مناسب برای ایجنت AI بله بله (با محدودیت RAM) محدود محدود

فرمول محاسبه نقطه بهای Cloud در مقابل Self-hosted#

نقطه‌ی بهای Cloud در مقابل Self-hosted به دو متغیر بستگی دارد: تعداد execution ماهانه و هزینه‌ی سرور. اگر هزینه‌ی ماهانه‌ی سرور شما ثابت است (مثلاً VPS با قیمت مشخص)، هرچه execution بیشتر شود، self-hosted ارزان‌تر می‌شود چون هزینه‌ی execution اضافی ندارد. در مقیاس پایین، تفاوت محسوس نیست؛ اما از چند هزار execution در ماه، self-hosted برنده می‌شود.

محدودیت‌های عملی Cloud برای کاربر ایرانی#

سه مشکل جدی و بی‌راه‌حل: پرداخت ارزی (ویزا یا مسترکارت لازم است)، ریسک شناسایی IP و قطع حساب، و عدم امکان دسترسی به API داخلی سرویس‌های ایرانی. اگر ورک‌فلوی شما نیاز به اتصال به درگاه پرداخت ایرانی، سامانه‌ی پیامک داخلی یا API سازمانی دارد، Cloud عملاً بی‌فایده است. نه به‌خاطر تحریم، بلکه به‌خاطر اینکه شبکه‌ی داخلی از بیرون قابل‌دسترس نیست.

ایجنت هوش مصنوعی (AI Agent) در n8n: فراتر از یک پرامپت ساده#

ایجنت هوش مصنوعی در n8n با AI Agent Node و LangChain ساخته می‌شود و سه لایه دارد: ابزارهای قابل‌فراخوانی (Tool Calling)، حافظه (Memory) و حلقه‌ی تصمیم‌گیری. اتصال صرف به OpenAI با یک پرامپت، ایجنت نیست؛ فقط یک فراخوانی API است. اگر ورک‌فلوی شما تصمیم نمی‌گیرد، ایجنت نیست.

ایجنت هوش مصنوعی به‌صورت گوی نورانی مرکزی با مسیرهای عصبی ساطع‌شده در محیط سرور تاریک
لایه‌ی تصمیم‌گیری ایجنت، نودها را از اجرای خطی به واکنش هوشمند تبدیل می‌کند

ساختار AI Agent Node و جایگاه LangChain در معماری n8n#

n8n از LangChain به‌عنوان لایه‌ی زیرساختی استفاده می‌کند. AI Agent Node یک wrapper روی LangChain است که در UI بصری n8n قابل‌پیکربندی است. شما مدل زبانی (LLM) را انتخاب می‌کنید، ابزارها را وصل می‌کنید و حافظه را تعریف می‌کنید. LangChain مدیریت prompt، function calling و memory را انجام می‌دهد.

Tool Calling: چگونه ایجنت به ابزارهای خارجی دسترسی بگیرد#

هر نود در n8n می‌تواند به‌عنوان Tool برای ایجنت تعریف شود. HTTP Request Node، Google Sheets Node، Database Query Node — همه قابل‌اتصال‌اند. ایجنت بر اساس task، تصمیم می‌گیرد کدام ابزار را فراخوانی کند و با چه پارامترهایی. این تفاوت اصلی با یک chatbot ساده است: ایجنت عمل می‌کند، نه فقط پاسخ می‌دهد.

نکته‌ی عملی که کمتر جایی نوشته شده: هرچه تعداد Toolها بیشتر باشد، پنجره‌ی زمینه (Context Window) ایجنت سریع‌تر پر می‌شود و هزینه‌ی هر execution بالا می‌رود. حداکثر 5 تا 8 Tool به ایجنت بدهید و بقیه را در sub-workflow جداگانه بپیچید. ایجنتی با 20 Tool، در عمل نمی‌تواند تصمیم درست بگیرد چون prompt system آن آنقدر شلوغ می‌شود که مدل گیج می‌خورد.

Memory و چالش context window در workflowهای چندمرحله‌ای#

حافظه‌ی ایجنت در n8n به‌صورت Buffer Memory یا Summary Memory تنظیم می‌شود. Buffer Memory آخرین N پیام را نگه می‌دارد. Summary Memory پیام‌های قدیمی را خلاصه می‌کند و خلاصه را نگه می‌دارد. در ورک‌فلوهای چندمرحله‌ای که ایجنت باید از نتایج مراحل قبلی آگاه باشد، Summary Memory گزینه‌ی بهتری است چون context window را مدیریت می‌کند.

انتخاب بین این دو یک قضاوت ساده دارد: اگر مکالمه کوتاه است، Buffer. اگر ایجنت باید بعد از ده مرحله هنوز نتیجه‌ی مرحله‌ی اول را بداند، Summary. Buffer Memory در ورک‌فلوهای بلند، اطلاعات کلیدی را دور می‌ریزد.

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

  1. Gmail Trigger — دریافت ایمیل جدید.
  2. AI Agent Node — با مدل زبانی تنظیم‌شده، موضوع و لحن ایمیل را تحلیل می‌کند.
  3. Tool: HTTP Request — ایجنت تصمیم می‌گیرد آیا نیاز به بررسی وضعیت سفارش در CRM دارد.
  4. Tool: Google Sheets — ایجنت نتیجه‌ی دسته‌بندی را در شیت ثبت می‌کند.
  5. Gmail Send Node — پاسخ پیشنهادی ایجنت به‌عنوان draft ذخیره می‌شود.

این ورک‌فلو یک ایجنت واقعی است چون تصمیم‌گیری دارد (کدام Tool را فراخوانی کند)، حافظه دارد (از مکالمات قبلی آگاه است) و عمل می‌کند (نه فقط پاسخ متنی تولید می‌کند).

مدیریت خطا و retry: چرا workflowهای شما در production می‌شکنند#

مدیریت خطا در n8n یعنی تنظیم Error Workflow، Retry Strategy و استفاده از Sub-workflow. بدون این سه، یک خطای موقت API — مثلاً timeout یا rate limit — باعث توقف کامل ورک‌فلو و از دست رفتن داده می‌شود. الگوی صحیح، error handling لایه‌ای است: هر لایه یک نوع خطا را می‌گیرد.

تنظیم Error Workflow#

در تنظیمات هر ورک‌فلو، می‌توانید یک ورک‌فلوی مجزا را به‌عنوان Error Workflow مشخص کنید. هر خطا در ورک‌فلوی اصلی، به این ورک‌فلوی خطا هدایت می‌شود. در Error Workflow می‌توانید: پیام خطا را به Telegram بفرستید، execution را در database ثبت کنید، یا retry دستی را فعال کنید.

بدون Error Workflow، خطاها بی‌صدا می‌مانند. شما متوجه نمی‌شوید که ورک‌فلو از چند روز پیش قطع شده مگر اینکه خودتان execution log را چک کنید. این یعنی داده‌ی شما در این مدت گم شده و کسی نمی‌داند.

Retry Strategy#

در تنظیمات نود، می‌توانید تعداد تلاش مجدد و فاصله‌ی بین تلاش‌ها را مشخص کنید. اما نه هر خطایی retry‌پذیر است:

  • Retry‌پذیر: خطاهای شبکه (timeout، connection reset)، rate limit موقت (status code 429).
  • غیرretry‌پذیر: خطای authentication (401، 403)، خطای داده (400 Bad Request)، خطای منطق (422).

Retry برای خطای غیرretry‌پذیر فقط زمان و هزینه‌ی API را هدر می‌دهد. قبل از تنظیم retry، نوع خطاهای رایج API مقصد را بشناسید. یک retry بی‌مورد روی خطای 401، ده بار کلید اشتباه را می‌فرستد و ممکن است حساب شما قفل شود.

Sub-workflow به‌عنوان واحد قابل‌استفاده مجدد#

بخش‌هایی از ورک‌فلو که چند بار تکرار می‌شوند — مثلاً ارسال لاگ، اعتبارسنجی داده یا فراخوانی یک API خاص — را در Sub-workflow جداگانه ببرید. با Execute Workflow Node آن‌ها را صدا بزنید. مزیت: یک‌بار دیباگ می‌کنید، همه‌جا کار می‌کند. بدون sub-workflow، هر تغییر باید در ده جای مختلف اعمال شود.

سه اشتباه رایج#

  • Code Node به‌جای Expression: وقتی می‌توانید با {{ $json.field }} داده را بخوانید، Code Node ننویسید. Code Node در محیط production کندتر است و دیباگ آن سخت‌تر.
  • عدم استفاده از Queue Mode: بدون Redis و Worker، اگر 50 execution همزمان بیاید، همه در یک thread صف می‌شوند و timeout می‌گیرند. Queue Mode را از روز اول فعال کنید.
  • ذخیره credential در environment variable: اگر API Key را در env variable سرور ذخیره کنید و container restart شود، credential گم می‌شود. از Credential Manager داخلی n8n استفاده کنید.

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

n8n ابزار درست نیست وقتی به latency زیر یک‌صانیه نیاز دارید، محاسبات سنگین داده‌ای انجام می‌دهید، یا منطق پروژه در کد سفارشی تمیزتر نوشته می‌شود. n8n برای orchestration چند-سیستمی با حجم execution متوسط تا بالا ساخته شده است، نه برای جایگزینی کدنویسی. این را بپذیرید: ابزار بصری همیشه جایگزین ابزار متنی نیست.

مقایسه با Power Automate برای سازمان‌های مایکروسافتی#

اگر سازمان شما روی Microsoft 365، Azure AD و SharePoint کار می‌کند، Power Automate integration عمیق‌تری دارد. n8n هم به این سرویس‌ها وصل می‌شود، اما مدیریت دسترسی و لاگ در محیط سازمانی مایکروسافتی، Power Automate را گزینه‌ی طبیعی‌تر می‌کند.

محدودیت‌های ذاتی node-based#

منطق‌هایی که در نود نمی‌گنجند:

  • حلقه‌های تودرتوی عمیق (nested loop) روی داده‌ی بزرگ.
  • State management پیچیده بین چند execution.
  • عملیات ریاضی یا تحلیلی سنگین که در JavaScript تمیزتر نوشته می‌شود.
  • نیاز به streaming داده به‌صورت بلادرنگ (real-time).

در این موارد، n8n را به‌عنوان لایه‌ی orchestration نگه دارید و منطق سنگین را به یک میکروسرویس (Microservice) اختصاصی بسپارید. n8n با HTTP Request Node آن microservice را صدا بزند. این الگو، معماری تمیزتر و قابل‌نگهداری‌تری نسبت به ورک‌فلوی 40 نودی می‌سازد.

تصمیم‌گیری: چه زمانی به کدنویسی سفارشی برویم؟#

اگر ورک‌فلوی شما بیش از 20 نود دارد، منطق شرطی تودرتو دارد و تیمی از آن نگهداری می‌کند که JavaScript بلد است، احتمالاً کدنویسی سفارشی (مثلاً با Node.js یا Python) قابل‌نگهداری‌تر است. n8n در این حالت تبدیل به «کد بصری» می‌شود که دیباگ آن از کد متنی سخت‌تر است. هرچه نودها بیشتر، هرچه تودرتو، هرچه تیم بزرگ‌تر — مزیت بصری n8n محو می‌شود.

جمع‌بندی عملی: n8n یک ابزار قدرتمند برای ساخت ورک‌فلو و ایجنت AI است، اما نه no-code واقعی است و نه جایگزین کدنویسی. اگر API، JSON و Expression را بلد باشید، self-hosted n8n روی سرور شخصی، ارزان‌ترین و انعطاف‌پذیرترین گزینه برای کاربر ایرانی است. اگر می‌خواهید این مسیر را گام‌به‌گام و با پروژه‌های واقعی طی کنید، دورهٔ ساخت Ai Agent با N8N در کامیونیتی اسکول دقیقاً برای همین طراحی شده — 51 جلسه عملی که از نصب تا ایجنت‌های تولیدی را پوشش می‌دهد.