📌 قبل از شروع، این‌ها را بدانیم

داکر (Docker) چیست؟ تصور کنید هر نرم‌افزار داخل یک «جعبهٔ دربسته» اجرا شود که همه‌چیزِ موردنیازش را با خودش دارد. به این جعبه‌ها «کانتینر»^۱ می‌گویند. نتیجه: نصبِ تمیز، بدون به‌هم‌ریختن سیستم، و حذفِ یک‌ضربه‌ای.
n8n چیست؟ ابزار اتوماسیون است: کارهای تکراری (مثل «هر ایمیل جدید را در تلگرام بفرست») را به‌صورت ورک‌فلو^۲ خودکار می‌کند. ما آن را داخل داکر اجرا می‌کنیم.
خط فرمان کجاست؟ در ویندوز از PowerShell استفاده می‌کنیم و در مک از Terminal (پوستهٔ پیش‌فرض zsh). دستورات مک را دقیقاً برای ترمینال نوشته‌ایم؛ نیازی به نصب پاورشل روی مک نیست.
فرض‌های ما: ویندوز ۱۰ (نسخهٔ 22H2 به بعد) یا ویندوز ۱۱ / مک با macOS 14 به بعد، دسترسی ادمین، و اینترنت پایدار. اگر سیستم شما قدیمی‌تر است، بخش رفع اشکال را ببینید.

📖 پانویس‌ها ۱) کانتینر (Container): محیط ایزولهٔ سبک برای اجرای یک برنامه با همهٔ وابستگی‌هایش.
۲) ورک‌فلو (Workflow): زنجیره‌ای از مراحل خودکار؛ مثل دستور آشپزی که کامپیوتر خودش اجرایش می‌کند.

🧭 نقشهٔ کلی مسیر

💻 سیستم شماویندوز / مک

←

🐳 Docker Desktopموتور کانتینرها

←

📦 کانتینر n8nروی پورت 5678

←

💾 n8n_data + بکاپداده‌های شما

داکر مثل «نیروگاه» است و n8n مثل «دستگاهی» که به آن وصل می‌شود. داده‌ها هم در انباری جدا (Volume) نگه‌داری می‌شوند تا با خاموش‌شدن دستگاه از بین نروند.

بررسی پیش‌نیازهای سیستم هر دو

⏱ ۱۰ دقیقه

🪟 ویندوز — سه بررسی ساده

روی دکمهٔ Start کلیک راست کنید و گزینهٔ Terminal (Admin) یا Windows PowerShell (Admin) را بزنید. (پنجرهٔ آبی یا مشکی که باز می‌شود، همان پاورشل است. اجرای «به‌عنوان ادمین» برای مراحل بعد ضروری است.)
نسخهٔ ویندوز را ببینید:
```
winver
```
پنجرهٔ کوچکی باز می‌شود. باید ویندوز ۱۱، یا ویندوز ۱۰ نسخهٔ 22H2 به بعد باشد.
بررسی فعال‌بودن مجازی‌سازی^۳:
```
systeminfo | Select-String "Virtualization"
```
اگر جلوی Virtualization Enabled In Firmware نوشته بود Yes، عالی است. اگر No بود، به بخش رفع اشکال (خطای شمارهٔ ۲) بروید — باید از تنظیمات BIOS فعالش کنید.
بررسی وجود winget^۴:
```
winget --version
```
اگر شماره‌ای مثل v1.28.x دید، آماده‌اید. اگر خطای «not recognized» گرفتید → رفع اشکال، خطای ۵.

🍎 مک — دو بررسی ساده

ترمینال را باز کنید: کلیدهای Cmd + Space را بزنید، بنویسید Terminal و Enter بزنید.
نسخهٔ macOS و نوع چیپ را ببینید:
```
sw_vers -productVersion
uname -m
```
خروجی اول باید 14 به بالا باشد (مثلاً 15.5). خروجی دوم اگر arm64 بود یعنی چیپ اپل (M1 تا M4) دارید و اگر x86_64 بود یعنی اینتل — هر دو پشتیبانی می‌شوند و ادامهٔ مسیر یکی است.

📖 پانویس‌ها ۳) مجازی‌سازی (Virtualization): قابلیتی در سخت‌افزار که اجازه می‌دهد یک «کامپیوتر کوچک مجازی» داخل کامپیوتر شما اجرا شود؛ داکر به آن نیاز دارد.
۴) winget: «فروشگاه خط فرمانی» رسمی مایکروسافت؛ با یک دستور، نرم‌افزار نصب می‌کند.

✅ ایست بازرسی ۱ الان باید: نسخهٔ سیستم‌عامل مناسب باشد، مجازی‌سازی Yes باشد (ویندوز) و winget --version یا sw_vers جواب داده باشند. اگر نه → بخش رفع اشکال.

فعال‌سازی WSL2 فقط ویندوز

⏱ ۱۰ دقیقه + ری‌استارت

داکر در ویندوز، کانتینرها را داخل یک لینوکسِ کوچک به نام WSL2^۵ اجرا می‌کند. پس اول باید آن را فعال کنیم. کاربران مک این مرحله را رد کنند و به مرحلهٔ ۴ بروند.

در همان پاورشلِ ادمین، این دستور را اجرا کنید:
```
wsl --install --no-distribution
```
سوییچ --no-distribution یعنی «فقط موتور WSL را نصب کن، لینوکس جدا نمی‌خواهم» — چون داکر خودش لینوکس خودش را می‌آورد و این‌طوری حجم کمتری دانلود می‌شود.
وقتی نصب تمام شد، کامپیوتر را ری‌استارت کنید. (این ری‌استارت اجباری است — بدون آن، داکر بالا نمی‌آید.)
بعد از ری‌استارت، دوباره پاورشل ادمین را باز کنید و WSL را به آخرین نسخه برسانید:
```
wsl --update
wsl --status
```
در خروجی wsl --status باید عبارتی شبیه Default Version: 2 ببینید. اگر عدد ۱ بود:
```
wsl --set-default-version 2
```

💡 نکته اگر قبلاً WSL داشتید، دستور wsl --install به شما می‌گوید «already installed» — هیچ اشکالی ندارد؛ فقط wsl --update را بزنید و ادامه دهید.

📖 پانویس ۵) WSL2 (Windows Subsystem for Linux 2): فناوری رسمی مایکروسافت برای اجرای لینوکس واقعی داخل ویندوز، بدون نصب جداگانه.

✅ ایست بازرسی ۲ خروجی wsl --status نسخهٔ پیش‌فرض ۲ را نشان می‌دهد و هیچ پیغام خطایی ندارید. اگر خطای 0x80370102 یا مشابه دیدید → رفع اشکال، خطای ۲.

نصب Docker Desktop با winget فقط ویندوز

⏱ ۱۵ دقیقه

در پاورشل ادمین، این دستور را اجرا کنید (یک خط کامل است؛ کپی کنید و Enter بزنید):
```
winget install -e --id Docker.DockerDesktop --accept-source-agreements --accept-package-agreements
```
حجم دانلود بالاست (بیش از ۵۰۰ مگابایت) — بسته به سرعت اینترنت، صبور باشید. دو سوییچ آخر یعنی «توافق‌نامه‌ها را قبول دارم؛ وسط کار سؤال نپرس».
وقتی پیام Successfully installed دیدید، یک‌بار دیگر کامپیوتر را ری‌استارت کنید تا گروه کاربری docker-users روی حساب شما اعمال شود.

⚠️ مواظب باش اگر winget پیام «No package found matching input criteria» داد، اول منبع‌ها را تازه‌سازی کنید: winget source update و دوباره امتحان کنید. اگر دانلود وسط راه قطع شد، همان دستور نصب را دوباره اجرا کنید؛ winget ادامه می‌دهد یا از نو می‌گیرد.

💡 ترفند برای دیدن نسخهٔ نصب‌شده و آپدیت‌های بعدی: winget list Docker.DockerDesktop و winget upgrade Docker.DockerDesktop. در زمان نگارش این آموزش، نسخهٔ جاری Docker Desktop حدود 4.83 است؛ اگر عدد شما بالاتر بود کاملاً طبیعی است.

حالا به مرحلهٔ ۵ بروید.

نصب Docker Desktop با Homebrew فقط مک

⏱ ۱۵ دقیقه

اول ببینید Homebrew^۶ دارید یا نه:
```
brew --version
```
اگر شماره نسخه دید، به قدم ۳ بپرید. اگر خطای command not found گرفتید، قدم ۲ را انجام دهید.
نصب Homebrew با دستور رسمی (کل خط را یک‌جا کپی کنید؛ وسط کار رمز مک را می‌پرسد و هنگام تایپِ رمز چیزی نمایش داده نمی‌شود — طبیعی است):
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
در پایان، اگر ترمینال دو خط شبیه eval "$(/opt/homebrew/bin/brew shellenv)" به شما داد، همان‌ها را هم اجرا کنید تا دستور brew شناخته شود. سپس ترمینال را ببندید و دوباره باز کنید.
حالا Docker Desktop را نصب کنید:
```
brew install --cask docker-desktop
```

⚠️ مواظب باش — نام جدید cask نام رسمی این بسته اکنون docker-desktop است (قبلاً فقط docker بود و هنوز در خیلی از آموزش‌های قدیمی همان را می‌بینید). اگر brew install docker بزنید فقط ابزار خط فرمان نصب می‌شود، نه خودِ برنامه — و بعداً خطای «Cannot connect to the Docker daemon» می‌گیرید. اگر اشتباهاً نصبش کردید: brew uninstall --formula docker و بعد دستور درست را بزنید.

📖 پانویس ۶) Homebrew: محبوب‌ترین «مدیر بسته» در مک؛ معادل winget ویندوز — نصب نرم‌افزار با یک دستور.

اجرای اولیهٔ داکر و راستی‌آزمایی هر دو

⏱ ۱۰ دقیقه

ویندوز: از منوی Start برنامهٔ Docker Desktop را باز کنید. مک: در ترمینال بنویسید open -a Docker (یا از Launchpad بازش کنید).
بار اول یک صفحهٔ توافق‌نامه می‌آید — Accept را بزنید. اگر پیشنهاد ورود به حساب Docker داد، می‌توانید Skip کنید؛ برای این آموزش حساب لازم نیست.
منتظر بمانید تا آیکون نهنگ 🐳 در نوار پایین ویندوز یا بالای مک ثابت شود (وقتی تکان می‌خورد یعنی هنوز در حال روشن‌شدن است — گاهی ۱ تا ۲ دقیقه طول می‌کشد).
حالا در پاورشل/ترمینال (این‌بار ادمین‌بودن لازم نیست) راستی‌آزمایی کنید:
```
docker --version
docker run hello-world
```

✅ ایست بازرسی ۳ — مهم‌ترین ایست کل مسیر دستور دوم باید متنی چاپ کند که داخلش نوشته: Hello from Docker!. یعنی داکر سالم است: تصویر^۷ را دانلود کرد، کانتینر ساخت و اجرا کرد. اگر به‌جای آن خطا دیدید:

error during connect یا cannot connect to the Docker daemon → داکر دسکتاپ باز نیست یا هنوز کامل بالا نیامده → رفع اشکال، خطای ۳.
خطای دانلود / timeout / 403 → مشکل دسترسی به مخزن تصاویر → رفع اشکال، خطای ۴.

📖 پانویس ۷) ایمیج/تصویر (Image): «قالب آماده» یک برنامه؛ کانتینر از روی آن ساخته می‌شود — مثل قالب کیک و خودِ کیک.

ساخت Volume و پوشه‌های پشتیبان هر دو

⏱ ۵ دقیقه

قبل از اجرای n8n، دو «انبار» می‌سازیم: یکی Volume^۸ که داکر داده‌های زندهٔ n8n را در آن نگه می‌دارد، و یکی پوشه‌های پشتیبان روی خودِ سیستم شما که نسخه‌های بکاپ آن‌جا می‌روند.

قدم ۱ — ساخت Volume (هر دو سیستم، دستور یکسان)

docker volume create n8n_data

قدم ۲ — ساخت پوشه‌های پشتیبان

🪟 ویندوز (پاورشل):

New-Item -ItemType Directory -Force -Path "$HOME\n8n-backups\workflows"
New-Item -ItemType Directory -Force -Path "$HOME\n8n-backups\credentials"
New-Item -ItemType Directory -Force -Path "$HOME\n8n-backups\volume"

🍎 مک (ترمینال):

mkdir -p "$HOME/n8n-backups/workflows" "$HOME/n8n-backups/credentials" "$HOME/n8n-backups/volume"

ساختار ساخته‌شده: پوشهٔ n8n-backups داخل پوشهٔ خانگی شما، با سه زیرپوشه: workflows (بکاپ ورک‌فلوها)، credentials (بکاپ اتصال‌ها) و volume (بکاپ کامل انبار داده).

✅ ایست بازرسی ۴ دستور docker volume ls باید n8n_data را در فهرست نشان دهد؛ و در ویندوز dir $HOME\n8n-backups (در مک: ls $HOME/n8n-backups) سه پوشه را نشان دهد.

📖 پانویس ۸) Volume: فضای ذخیره‌سازی جدا از کانتینر. کانتینر را می‌شود حذف کرد و دوباره ساخت، ولی Volume سر جایش می‌ماند — پس ورک‌فلوها و رمزها گم نمی‌شوند.

اجرای n8n با دستور رسمی هر دو

⏱ ۱۰ دقیقه

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

🪟 ویندوز — پاورشل (چندخطی با بک‌تیک `)

docker run -d --name n8n `
  --restart unless-stopped `
  -p 5678:5678 `
  -e GENERIC_TIMEZONE="Asia/Tehran" `
  -e TZ="Asia/Tehran" `
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true `
  -e N8N_RUNNERS_ENABLED=true `
  -v n8n_data:/home/node/.n8n `
  docker.n8n.io/n8nio/n8n

🍎 مک — ترمینال (چندخطی با بک‌اسلش `\`)

docker run -d --name n8n \
  --restart unless-stopped \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Tehran" \
  -e TZ="Asia/Tehran" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_RUNNERS_ENABLED=true \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

⚠️ مواظب باش — تفاوت مهم پاورشل و ترمینال در پاورشل، علامت ادامهٔ خط «بک‌تیک» ` است ولی در مک/لینوکس «بک‌اسلش» \. اگر دستورِ مک را در پاورشل کپی کنید، خطاهای عجیبی مثل docker: invalid reference format می‌گیرید. اگر شک دارید، این نسخهٔ تک‌خطی را در هر دو سیستم بزنید:

docker run -d --name n8n --restart unless-stopped -p 5678:5678 -e GENERIC_TIMEZONE="Asia/Tehran" -e TZ="Asia/Tehran" -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true -e N8N_RUNNERS_ENABLED=true -v n8n_data:/home/node/.n8n docker.n8n.io/n8nio/n8n

این دستور دقیقاً چه می‌کند؟

بخش دستور	معنی به زبان ساده
`-d`	در پس‌زمینه اجرا شو؛ ترمینال را اشغال نکن.
`--name n8n`	اسم کانتینر «n8n» باشد تا بعداً راحت صدایش کنیم.
`--restart unless-stopped`	اگر سیستم ری‌استارت شد، خودت دوباره روشن شو — مگر خودم خاموشت کرده باشم.
`-p 5678:5678`	درِ شمارهٔ 5678 کانتینر را به همان در روی سیستم من وصل کن (آدرس مرورگر).
`GENERIC_TIMEZONE` و `TZ`	ساعت ایران؛ تا زمان‌بندی‌های n8n (مثلاً «هر روز ۸ صبح») درست کار کنند.
`N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS`	تنظیم امنیتی توصیه‌شدهٔ خود n8n برای فایل تنظیمات.
`N8N_RUNNERS_ENABLED`	اجراکننده‌های کد را فعال می‌کند (روش جدید و امن‌تر اجرای کد در n8n).
`-v n8n_data:/home/node/.n8n`	انبار `n8n_data` را به پوشهٔ دادهٔ n8n وصل کن — راز ماندگاری داده‌ها.
`docker.n8n.io/n8nio/n8n`	آدرس رسمی تصویر n8n (مخزن خودِ شرکت n8n).

✅ ایست بازرسی ۵ دستور docker ps باید یک ردیف با نام n8n و وضعیت Up نشان دهد. اگر ردیفی نبود، با docker logs n8n دلیل را ببینید و به رفع اشکال بروید.

ورود به n8n و ساخت حساب مدیر هر دو

⏱ ۵ دقیقه

مرورگر را باز کنید و این آدرس را بزنید: http://localhost:5678
صفحهٔ خوش‌آمد n8n می‌آید و اطلاعات «حساب مالک» (Owner) را می‌پرسد: ایمیل، نام و یک رمز قوی وارد کنید. این حساب فقط روی کامپیوتر خودتان است و جایی ارسال نمی‌شود.
فرم را ثبت کنید — وارد محیط اصلی n8n می‌شوید: بوم سفیدی که ورک‌فلوها را روی آن می‌سازید. 🎉

💡 نکته رمز حساب مالک را جایی امن یادداشت کنید. اگر فراموشش کنید، بازیابی آن روی نصب محلی دردسر دارد.

📘 خوب است بدانید این n8n فقط از داخل کامپیوتر شما در دسترس است؛ سرویس‌های بیرونی (مثل تلگرام) نمی‌توانند مستقیم به localhost پیام بفرستند. برای وب‌هوک‌های بیرونی به ابزار تونل (مثل ngrok) نیاز است — که آموزش جداگانه‌اش در گراول هست.

پشتیبان‌گیری واقعی هر دو

⏱ ۱۰ دقیقه

دو نوع بکاپ می‌گیریم: بکاپ سبک (فایل JSON ورک‌فلوها و اتصال‌ها — برای جابه‌جایی و نگه‌داری روزمره) و بکاپ کامل (کل Volume در یک فایل فشرده — بیمه‌نامهٔ نهایی شما).

الف) بکاپ سبک — ورک‌فلوها و اتصال‌ها

🪟 ویندوز (پاورشل):

# 1) خروجی گرفتن داخل کانتینر
docker exec n8n n8n export:workflow --all --output=/home/node/.n8n/wf-backup.json
docker exec n8n n8n export:credentials --all --output=/home/node/.n8n/cred-backup.json
# 2) کپی به پوشه‌های پشتیبان روی سیستم شما
docker cp n8n:/home/node/.n8n/wf-backup.json "$HOME\n8n-backups\workflows\"
docker cp n8n:/home/node/.n8n/cred-backup.json "$HOME\n8n-backups\credentials\"

🍎 مک (ترمینال): همان چهار دستور، فقط مسیر مقصد با اسلش معمولی:

docker exec n8n n8n export:workflow --all --output=/home/node/.n8n/wf-backup.json
docker exec n8n n8n export:credentials --all --output=/home/node/.n8n/cred-backup.json
docker cp n8n:/home/node/.n8n/wf-backup.json "$HOME/n8n-backups/workflows/"
docker cp n8n:/home/node/.n8n/cred-backup.json "$HOME/n8n-backups/credentials/"

💡 نکته اگر هنوز هیچ ورک‌فلویی نساخته‌اید، دستور export ممکن است بگوید چیزی برای خروجی نیست — طبیعی است؛ بعد از ساخت اولین ورک‌فلو دوباره امتحان کنید.

ب) بکاپ کامل — کل Volume در یک فایل فشرده

🪟 ویندوز (پاورشل):

docker run --rm -v n8n_data:/data -v "${HOME}\n8n-backups\volume:/backup" alpine tar czf /backup/n8n-volume-backup.tar.gz -C /data .

🍎 مک (ترمینال):

docker run --rm -v n8n_data:/data -v "$HOME/n8n-backups/volume:/backup" alpine tar czf /backup/n8n-volume-backup.tar.gz -C /data .

ترجمهٔ دستور: «یک کانتینر موقت (alpine) بساز، انبار n8n و پوشهٔ بکاپ من را به آن وصل کن، همه‌چیز را در فایل n8n-volume-backup.tar.gz فشرده کن، بعد خودت را حذف کن.»

ج) بازگردانی (اگر روز مبادا رسید)

# ویندوز — پاورشل:
docker run --rm -v n8n_data:/data -v "${HOME}\n8n-backups\volume:/backup" alpine sh -c "cd /data && tar xzf /backup/n8n-volume-backup.tar.gz"
# مک — ترمینال:
docker run --rm -v n8n_data:/data -v "$HOME/n8n-backups/volume:/backup" alpine sh -c "cd /data && tar xzf /backup/n8n-volume-backup.tar.gz"

⚠️ مواظب باش — کلید رمزنگاری داخل Volume فایلی هست که «کلید رمزنگاری» اتصال‌های شما را نگه می‌دارد. اگر Volume را بدون بکاپ حذف کنید، حتی با داشتن فایل JSON اتصال‌ها، رمزهای ذخیره‌شده دیگر بازگشایی نمی‌شوند. پس بکاپ کامل (بخش ب) را جدی بگیرید — مخصوصاً قبل از هر آپدیت یا حذف.

✅ ایست بازرسی ۶ در پوشهٔ n8n-backups/volume باید فایل n8n-volume-backup.tar.gz با حجم غیر صفر باشد. در ویندوز: dir $HOME\n8n-backups\volume — در مک: ls -lh $HOME/n8n-backups/volume

۱۰

به‌روزرسانی و مدیریت روزمره هر دو

⏱ ۵ دقیقه

دستورهای روزمره (هر دو سیستم یکسان)

# وضعیت کانتینرها
docker ps
# توقف / شروع n8n
docker stop n8n
docker start n8n
# دیدن گزارش‌ها (برای عیب‌یابی)
docker logs n8n --tail 50

آپدیت n8n به آخرین نسخه (بدون از دست دادن داده)

# 0) اول بکاپ کامل بگیرید (مرحله ۹ - بخش ب)!
docker pull docker.n8n.io/n8nio/n8n
docker stop n8n
docker rm n8n
# حالا دوباره همان دستور اجرای مرحله ۷ را بزنید — چون Volume سر جایش است، همه‌چیز برمی‌گردد

💡 ترفند حذف کانتینر (docker rm) داده‌ها را پاک نمی‌کند؛ داده‌ها در Volume هستند. فقط دستور docker volume rm n8n_data است که واقعاً داده‌ها را نابود می‌کند — آن را هرگز بدون بکاپ نزنید.

🔧

رفع اشکال — ۹ خطای رایج و راه‌حل دقیق

خطای ۱: WSL 2 installation is incomplete یا WSL update needed (ویندوز)

نشانه: داکر دسکتاپ باز می‌شود ولی پنجرهٔ خطای WSL می‌دهد.
علت: WSL نصب نشده، قدیمی است، یا بعد از نصب ری‌استارت نکرده‌اید.
درمان: پاورشل ادمین → wsl --update → ری‌استارت کامپیوتر → باز کردن دوبارهٔ Docker Desktop. اگر باز هم نشد: wsl --install --no-distribution و دوباره ری‌استارت.

خطای ۲: Virtualization support is disabled / کد 0x80370102 (ویندوز)

نشانه: داکر یا WSL می‌گوید مجازی‌سازی خاموش است.
علت: قابلیت VT-x/AMD-V در BIOS/UEFI سیستم غیرفعال است.
درمان: کامپیوتر را ری‌استارت کنید و هنگام روشن‌شدن، کلید ورود به BIOS را بزنید (بسته به برند: معمولاً F2، F10، Del یا Esc — ممکن است در دستگاه شما فرق کند). دنبال گزینه‌ای شبیه Intel Virtualization Technology، VT-x یا SVM Mode بگردید (اغلب در تب Advanced یا CPU Configuration)، آن را Enabled کنید، ذخیره کنید (F10) و بیرون بیایید.

خطای ۳: error during connect / cannot connect to the Docker daemon (هر دو)

نشانه: هر دستور docker این خطا را می‌دهد.
علت: موتور داکر روشن نیست — برنامهٔ Docker Desktop باز نیست یا هنوز کامل بالا نیامده.
درمان: Docker Desktop را باز کنید و صبر کنید آیکون نهنگ ثابت شود؛ بعد دستور را دوباره بزنید. در ویندوز اگر همیشه تکرار می‌شود، از تنظیمات داکر گزینهٔ Start Docker Desktop when you sign in را فعال کنید. در مک اگر تازه با brew نصب کرده‌اید، یادتان باشد برنامه باید حداقل یک‌بار به‌صورت گرافیکی باز شده و توافق‌نامه تأیید شده باشد.

خطای ۴: گیر کردن دانلود ایمیج / timeout / 403 Forbidden هنگام docker pull (هر دو)

نشانه: docker run hello-world یا docker pull در دانلود گیر می‌کند یا خطای دسترسی می‌دهد.
علت: برای کاربران داخل ایران، دسترسی مستقیم به Docker Hub معمولاً محدود است.
درمان: از یک «آینهٔ رجیستری» داخلی استفاده کنید. در Docker Desktop: آیکون چرخ‌دنده → Docker Engine → در متن JSON این بخش را اضافه کنید و Apply & restart بزنید:

{
  "registry-mirrors": ["https://docker.arvancloud.ir"]
}

(این فقط یک نمونهٔ شناخته‌شده است؛ سرویس‌های آینهٔ دیگری هم وجود دارند و آدرس‌ها ممکن است در طول زمان تغییر کنند — اگر کار نکرد، عبارت «docker registry mirror ایران» را جست‌وجو کنید.) توجه: ایمیج n8n از دامنهٔ خود n8n یعنی docker.n8n.io گرفته می‌شود که معمولاً بدون مشکل در دسترس است.

خطای ۵: winget is not recognized (ویندوز)

نشانه: پاورشل winget را نمی‌شناسد.
علت: ویندوز شما قدیمی است یا بستهٔ «App Installer» ندارد.
درمان: Microsoft Store را باز کنید، عبارت App Installer را جست‌وجو و نصب/آپدیت کنید؛ سپس پاورشل را ببندید و دوباره باز کنید. اگر Store ندارید، ویندوز را از Settings → Windows Update به‌روز کنید.

خطای ۶: port is already allocated / Bind for 0.0.0.0:5678 failed (هر دو)

نشانه: هنگام docker run می‌گوید پورت 5678 اشغال است.
علت: یا یک n8n قبلی در حال اجراست، یا برنامهٔ دیگری این پورت را گرفته.
درمان: اول ببینید کانتینر قبلی هست یا نه: docker ps -a. اگر کانتینری به نام n8n بود: docker start n8n (لازم نیست دوباره بسازید!). اگر می‌خواهید از نو بسازید: docker rm -f n8n و بعد دستور اجرای مرحلهٔ ۷. اگر برنامهٔ دیگری پورت را گرفته، در دستور اجرا به‌جای -p 5678:5678 بنویسید -p 5679:5678 و در مرورگر به http://localhost:5679 بروید.

خطای ۷: docker: invalid reference format یا unknown flag (هر دو)

نشانه: دستور چندخطی خطای عجیب نحوی می‌دهد.
علت: علامت ادامهٔ خطِ اشتباه — دستور مک (\) در پاورشل یا برعکس؛ یا کپی‌شدن کاراکترهای نامرئی.
درمان: از نسخهٔ تک‌خطی دستور در مرحلهٔ ۷ استفاده کنید — در هر دو سیستم بدون تغییر کار می‌کند.

خطای ۸: Conflict. The container name "/n8n" is already in use (هر دو)

نشانه: می‌گوید کانتینری با نام n8n از قبل وجود دارد.
علت: قبلاً یک‌بار دستور اجرا را زده‌اید (حتی اگر شکست خورده باشد، اسم رزرو شده).
درمان: اگر می‌خواهید همان قبلی روشن شود: docker start n8n. اگر می‌خواهید از نو: docker rm -f n8n و اجرای دوبارهٔ دستور. داده‌ها در Volume محفوظ‌اند.

خطای ۹: بعد از آپدیت، اتصال‌ها (Credentials) خطای رمزگشایی می‌دهند (هر دو)

نشانه: پیام‌هایی دربارهٔ encryption key یا باز نشدن اتصال‌های ذخیره‌شده.
علت: کانتینر جدید بدون اتصال به Volume قبلی ساخته شده و n8n کلید رمزنگاری تازه‌ای ساخته است.
درمان: کانتینر جدید را حذف کنید (docker rm -f n8n) و دستور اجرای مرحلهٔ ۷ را دقیقاً با همان -v n8n_data:/home/node/.n8n بزنید. اگر Volume را از دست داده‌اید، از بکاپ کامل (مرحلهٔ ۹ - بخش ج) بازگردانی کنید.

🎉 تمام شد! حالا تو بلدی…

✅ داکر را فقط با خط فرمان نصب و راستی‌آزمایی کنی (ویندوز و مک)
✅ n8n را با دستور رسمی، ماندگار و با ساعت ایران اجرا کنی
✅ برای داده‌هایت Volume و پوشه‌های پشتیبان بسازی و بکاپ کامل بگیری
✅ ۹ خطای رایج را خودت تشخیص بدهی و درمان کنی

🏔️ سنگ‌ریزهٔ بعدی در مسیر: ساخت اولین ورک‌فلو در n8n — مثلاً اتصال تلگرام به هوش مصنوعی. سراغ آموزش‌های اتوماسیون گراول برو!

📌 قبل از شروع، این‌ها را بدانیم

🧭 نقشهٔ کلی مسیر

بررسی پیش‌نیازهای سیستم هر دو

🪟 ویندوز — سه بررسی ساده

🍎 مک — دو بررسی ساده

فعال‌سازی WSL2 فقط ویندوز

نصب Docker Desktop با winget فقط ویندوز

نصب Docker Desktop با Homebrew فقط مک

اجرای اولیهٔ داکر و راستی‌آزمایی هر دو

ساخت Volume و پوشه‌های پشتیبان هر دو

قدم ۱ — ساخت Volume (هر دو سیستم، دستور یکسان)

قدم ۲ — ساخت پوشه‌های پشتیبان

اجرای n8n با دستور رسمی هر دو

🪟 ویندوز — پاورشل (چندخطی با بک‌تیک `)

🍎 مک — ترمینال (چندخطی با بک‌اسلش \)

این دستور دقیقاً چه می‌کند؟

ورود به n8n و ساخت حساب مدیر هر دو

پشتیبان‌گیری واقعی هر دو

الف) بکاپ سبک — ورک‌فلوها و اتصال‌ها

ب) بکاپ کامل — کل Volume در یک فایل فشرده

ج) بازگردانی (اگر روز مبادا رسید)

به‌روزرسانی و مدیریت روزمره هر دو

دستورهای روزمره (هر دو سیستم یکسان)

آپدیت n8n به آخرین نسخه (بدون از دست دادن داده)

رفع اشکال — ۹ خطای رایج و راه‌حل دقیق

🎉 تمام شد! حالا تو بلدی…

🍎 مک — ترمینال (چندخطی با بک‌اسلش `\`)