نصب n8n روی لوکال‌هاست؛ راه‌اندازی با Docker و npm قدم‌به‌قدم

n8n یک ابزار ساخت گردش‌کار (Workflow) و اتوماسیون است: سرویس‌ها و برنامه‌ها را به هم وصل می‌کند تا کارهای تکراری خودکار انجام شوند؛ مثلاً هر فرم جدید سایت در یک جدول ثبت شود و برای کارشناس پیام برود، یا گزارشی هر صبح آماده شود. n8n را می‌شود روی سرور خود سازمان نصب کرد، و همین آن را برای مجموعه‌هایی که نمی‌خواهند داده‌هایشان روی سرویس‌های خارجی برود جذاب می‌کند.

این مقاله نصب n8n را روی کامپیوتر خودتان (لوکال‌هاست) توضیح می‌دهد؛ برای یادگیری، ساخت و آزمایش گردش‌کارها پیش از بردن آن‌ها روی سرور. دستورها بر اساس مستندات رسمی n8n در زمان نوشتن این مقاله است.

کدام روش نصب؟

سه راه اصلی هست:

• Docker: روشی که خود n8n توصیه می‌کند. n8n جدا از بقیهٔ سیستم اجرا می‌شود، نصب و حذفش ساده است و به نسخهٔ Node.js کامپیوتر شما وابسته نیست.
• Docker Compose: همان Docker، ولی تنظیمات در یک فایل نوشته می‌شود و n8n بعد از ری‌استارت کامپیوتر خودش بالا می‌آید. برای استفادهٔ روزمره بهترین انتخاب است.
• npm: اگر Node.js دارید و فقط می‌خواهید سریع امتحان کنید. طبق مستندات n8n، نصب با npm از نسخهٔ ۳ کنار گذاشته می‌شود؛ برای استفادهٔ طولانی‌مدت Docker را انتخاب کنید.

پیش‌نیازها

• ویندوز و مک: Docker Desktop را نصب کنید؛ Docker Compose هم همراهش نصب می‌شود. در ویندوز، Docker Desktop از WSL 2 استفاده می‌کند.
• لینوکس بدون محیط گرافیکی: Docker Engine و افزونهٔ Docker Compose را جداگانه نصب کنید.
• برای روش npm: Node.js نسخهٔ ۲۰٫۱۹ تا ۲۴.

بعد از نصب Docker، در ترمینال این دستور را بزنید تا مطمئن شوید کار می‌کند:

docker --version
docker compose version

اگر از ایران ایمیج را دریافت می‌کنید و Docker خطای 403 یا عدم دسترسی می‌دهد، مشکل از تنظیمات شما نیست؛ Docker Hub دسترسی از ایران را محدود کرده و باید از یک میرور (Registry Mirror) استفاده کنید.

روش اول: اجرای n8n با Docker

اول یک Volume بسازید تا داده‌ها و گردش‌کارها بعد از حذف کانتینر باقی بمانند:

docker volume create n8n_data

بعد n8n را اجرا کنید (در ویندوز، هر سطر را بدون \ در یک خط بنویسید):

docker run -it --rm \
  --name n8n \
  -p 127.0.0.1:5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Tehran" \
  -e TZ="Asia/Tehran" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

معنی هر بخش:

• -p 127.0.0.1:5678:5678: پورت ۵۶۷۸ فقط روی خود کامپیوتر باز می‌شود و دیگران در شبکه به آن دسترسی ندارند. مستندات n8n -p 5678:5678 می‌نویسد که پورت را روی همهٔ کارت‌های شبکه باز می‌کند؛ برای لوکال‌هاست، محدود کردنش امن‌تر است.
• GENERIC_TIMEZONE: منطقهٔ زمانی گره‌های زمان‌بندی‌شده مثل Schedule Trigger. اگر تنظیم نشود، گردش‌کاری که باید ساعت ۸ صبح اجرا شود، ساعت دیگری اجرا می‌شود.
• TZ: منطقهٔ زمانی خود سیستم داخل کانتینر.
• -v n8n_data:/home/node/.n8n: همهٔ داده‌های n8n (پایگاه داده، گردش‌کارها، اطلاعات اتصال‌ها و کلید رمزنگاری) در Volume ذخیره می‌شود.
• --rm: کانتینر بعد از توقف حذف می‌شود؛ داده‌ها در Volume می‌مانند.

حالا مرورگر را باز کنید و به http://localhost:5678 بروید. برای متوقف کردن، در همان ترمینال Ctrl+C بزنید.

روش دوم: Docker Compose برای استفادهٔ روزمره

یک پوشه بسازید، مثلاً n8n، و داخلش فایلی به نام compose.yaml با این محتوا بسازید:

services:
  n8n:
    image: n8nio/n8n
    container_name: n8n
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - GENERIC_TIMEZONE=Asia/Tehran
      - TZ=Asia/Tehran
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

در همان پوشه:

docker compose up -d

n8n در پس‌زمینه اجرا می‌شود و با restart: unless-stopped بعد از روشن شدن دوبارهٔ کامپیوتر هم خودش بالا می‌آید. چند دستور کاربردی:

docker compose ps
docker compose logs -f n8n
docker compose down

اولی وضعیت را نشان می‌دهد، دومی گزارش‌ها (لاگ) را و سومی n8n را متوقف می‌کند؛ داده‌ها در Volume می‌مانند.

روش سوم: نصب با npm

اگر Node.js نسخهٔ مناسب را دارید، برای امتحان سریع بدون نصب:

npx n8n

یا نصب دائمی و اجرا:

npm install n8n -g
n8n start

در این روش داده‌ها در پوشهٔ .n8n داخل پوشهٔ کاربری شما ذخیره می‌شوند.

اولین ورود

با باز کردن http://localhost:5678، n8n از شما می‌خواهد حساب مالک (Owner) را بسازید: ایمیل، نام و رمز عبور. این حساب مدیر نمونهٔ n8n شماست؛ رمز قوی بگذارید، حتی روی لوکال‌هاست.

ساخت یک گردش‌کار ساده برای آزمایش

1. روی Create Workflow بزنید.
2. گره Manual Trigger را اضافه کنید تا گردش‌کار با دکمه اجرا شود.
3. گره HTTP Request را اضافه کنید و یک نشانی عمومی، مثلاً یک API آزمایشی، را با روش GET درخواست کنید.
4. روی Execute Workflow بزنید؛ خروجی هر گره کنار آن نمایش داده می‌شود.

بعد از این‌که کار کرد، می‌توانید Manual Trigger را با Schedule Trigger عوض کنید تا گردش‌کار در زمان مشخص خودش اجرا شود.

داده‌ها کجا هستند و چطور پشتیبان بگیریم؟

n8n به‌طور پیش‌فرض از پایگاه دادهٔ SQLite داخل پوشهٔ .n8n استفاده می‌کند. در روش Docker همهٔ این‌ها در Volume n8n_data است. برای گرفتن نسخهٔ پشتیبان از کل Volume (در لینوکس و مک):

docker run --rm -v n8n_data:/data -v "$PWD":/backup alpine tar czf /backup/n8n-backup.tgz -C /data .

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

docker exec -u node n8n n8n export:workflow --all --output=/home/node/.n8n/workflows-backup.json

فایل کلید رمزنگاری (config داخل .n8n) را هم نگه دارید. بدون آن، اطلاعات اتصال‌های ذخیره‌شده (Credentials) روی نصب جدید قابل بازگشایی نیست.

به‌روزرسانی n8n

با Docker Compose:

docker compose pull
docker compose down
docker compose up -d

با Docker تنها، ایمیج تازه را با docker pull n8nio/n8n بگیرید و کانتینر را دوباره اجرا کنید. با npm، دستور npm update -g n8n کافی است. پیش از به‌روزرسانی نسخهٔ اصلی، یادداشت‌های انتشار را بخوانید و نسخهٔ پشتیبان بگیرید.

خطاهای رایج

• پورت ۵۶۷۸ اشغال است: برنامهٔ دیگری از این پورت استفاده می‌کند. پورت سمت چپ را عوض کنید، مثلاً 127.0.0.1:5679:5678، و n8n را روی http://localhost:5679 باز کنید.
• ساعت اجرای زمان‌بندی‌ها اشتباه است: GENERIC_TIMEZONE تنظیم نشده یا مقدار اشتباه دارد.
• از کامپیوتر دیگری در شبکه وارد نمی‌شود: n8n روی HTTP فقط از خود localhost اجازهٔ ورود می‌دهد، چون کوکی امن لازم دارد. راه درست برای دسترسی از شبکه، نصب روی سرور با HTTPS است. غیرفعال کردن این محدودیت با N8N_SECURE_COOKIE=false فقط برای آزمایش در شبکهٔ امن داخلی قابل قبول است.
• Webhook از بیرون کار نمی‌کند: نشانی localhost از اینترنت در دسترس نیست. برای دریافت Webhook از سرویس‌های بیرونی، n8n باید روی سرور با دامنه و HTTPS نصب شود.
• خطای دسترسی به فایل تنظیمات: متغیر N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true را مثل نمونه‌های بالا تنظیم کنید.

نکته‌های امنیتی

• پورت n8n را فقط روی 127.0.0.1 باز کنید. n8n به حساب‌ها و داده‌های سازمان وصل می‌شود و نباید بدون HTTPS و رمز قوی در شبکه یا اینترنت در دسترس باشد.
• اطلاعات اتصال‌ها را فقط داخل بخش Credentials خود n8n نگه دارید، نه داخل متن گره‌ها.
• برای استفادهٔ واقعی در سازمان، n8n را روی سرور جدا با HTTPS، پشتیبان‌گیری منظم و دسترسی محدود نصب کنید.

از لوکال‌هاست تا اتوماسیون واقعی سازمان

لوکال‌هاست برای یادگیری و ساخت نمونه عالی است؛ اما گردش‌کاری که باید شبانه‌روز اجرا شود، Webhook بگیرد یا به سامانه‌های داخلی وصل شود، به سرور، دامنه، HTTPS و برنامهٔ پشتیبان‌گیری نیاز دارد. اگر می‌خواهید کارهای تکراری مجموعه‌تان را با n8n یا ایجنت‌های هوش مصنوعی خودکار کنید، صفحهٔ اجرای اتوماسیون بر پایه هوش مصنوعی و ساخت ایجنت هوش مصنوعی را ببینید. برای مقایسهٔ مدل‌های هوش مصنوعی که در n8n به کار می‌آیند هم مقالهٔ مقایسهٔ Claude، ChatGPT، Gemini، Grok و Codex را بخوانید.