🏔️ گراول — کتابخانهٔ آموزش گام‌به‌گام

n8n خودت را با ngrok به اینترنت وصل کن

«برای رسیدن به قله باید از سنگ‌ریزه عبور کرد.»
قراره چی یاد بگیریم؟
از صفرِ صفر و بدون هیچ پیش‌نیاز اضافه: یک حساب ngrok می‌سازیم، کلید NGROK_AUTHTOKEN را می‌گیریم، یک آدرس ثابت NGROK_DOMAIN رزرو می‌کنیم و آن را طوری به n8n داخل داکر وصل می‌کنیم که آدرس عمومی https://${NGROK_DOMAIN} واقعاً باز شود و وبهوک‌ها کار کنند.
⚙️ دستهٔ اتوماسیون 🕒 حدود ۵۰ دقیقه 🎯 سطح: مبتدی 💻 ویندوز / مک / لینوکس

قبل از هر چیز: این کار به چه دردی می‌خورد؟ 🤔

یک مثال ساده تا خیالت راحت شود که چرا این آموزش لازم است.

فرض کن n8n را روی کامپیوتر خودت با داکر بالا آورده‌ای و در مرورگر با آدرس http://localhost:5678 بازش می‌کنی. تا وقتی فقط خودت با آن کار می‌کنی همه‌چیز خوب است. اما وقتی می‌خواهی یک سرویس بیرونی (مثل تلگرام، اسلک، یا یک فروشگاه) به n8n تو پیام بفرستد، آن سرویس هیچ راهی برای رسیدن به کامپیوتر تو ندارد.

پانویس ۱ — «localhost» یعنی چه؟
localhost یعنی «همین کامپیوترِ خودم». آدرسی است که فقط از داخل همین دستگاه در دسترس است؛ مثل تلفن داخلیِ یک ساختمان که از بیرونِ ساختمان نمی‌شود آن را گرفت.
پانویس ۲ — «وبهوک» (Webhook) یعنی چه؟
وبهوک مثل یک زنگِ در است. تو یک آدرس به یک سرویس بیرونی می‌دهی و می‌گویی «هر وقت اتفاقی افتاد، این زنگ را بزن». اما زنگ باید روی درِ خانه‌ای باشد که از بیرون پیدا شود؛ و localhost از بیرون پیدا نیست.

راه‌حل: یک ابزار به اسم ngrok یک تونل امن می‌سازد و به کامپیوترِ تو یک آدرس عمومیِ اینترنتی (با قفل HTTPS) می‌دهد. هر کس آن آدرس را باز کند، ngrok پشت‌پرده او را به n8n داخل کامپیوترِ تو وصل می‌کند.

سرویس بیرونیتلگرام / اسلک
→
https://${NGROK_DOMAIN}آدرس عمومی و ثابت
→
ngrok tunnelتونل امن
→
n8nروی کامپیوتر تو
پانویس ۳ — «تونل» (Tunnel) یعنی چه؟
یک مسیرِ امن و رمزگذاری‌شده بین آدرس عمومیِ ngrok و کامپیوتر تو. انگار یک لولهٔ نامرئی از اینترنت مستقیم وصل می‌شود به برنامهٔ روی دستگاهت.

پیش‌نیازها ✅ (اول این‌ها را چک کن)

این آموزش فرض می‌کند داکر و n8n را از قبل داری؛ اگر نداری، مسیرِ رسیدن به آن‌ها را پایین گفته‌ایم.

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

docker --version
✅ ایست بازرسی اگر چیزی شبیه Docker version 27.x.x دیدی، عالی است. اگر پیام خطا دیدی یا دستور شناخته نشد، هنوز داکر نصب یا روشن نیست؛ اول آن را درست کن.
📖 نداری؟ اشکالی ندارد اگر هنوز داکر یا n8n نداری، اول آموزش «داکر و n8n» در گراول را کامل کن و بعد به این آموزش برگرد. این آموزش دقیقاً از همان‌جا شروع می‌شود.
مرحله ۱ از ۸
۱

ساخت حساب رایگان ngrok

⏱️ حدود ۵ دقیقه
  1. مرورگر را باز کن و به این آدرس برو:
    https://dashboard.ngrok.com/signup
  2. یکی از راه‌های ثبت‌نام را انتخاب کن: با Google، با GitHub، یا با ایمیل و رمز.
  3. اگر با ایمیل ثبت‌نام کردی، به صندوق ایمیلت برو و روی لینک تأیید کلیک کن.
  4. حالا وارد داشبورد ngrok می‌شوی — همان صفحهٔ اصلی مدیریت حساب.
💡 نکته حساب رایگان برای این آموزش کاملاً کافی است و کارت بانکی نمی‌خواهد. با همین حساب رایگان یک دامنهٔ ثابت هم می‌گیری.
✅ ایست بازرسی الان باید داخل صفحه‌ای به اسم Dashboard باشی و منویی سمت صفحه ببینی که گزینه‌هایی مثل Domains و Your Authtoken دارد. اگر هنوز در صفحهٔ ورود گیر کرده‌ای، به بخش رفع اشکال برو.
مرحله ۲ از ۸
۲

گرفتن کلید NGROK_AUTHTOKEN

⏱️ حدود ۳ دقیقه

این کلید مثل کارت شناسایی توست؛ به ngrok ثابت می‌کند که این تونل مالِ توست.

  1. در همان داشبورد به این صفحه برو:
    https://dashboard.ngrok.com/get-started/your-authtoken
  2. یک رشتهٔ بلندِ تصادفی می‌بینی (چیزی شبیه 2Xy...aBcD). این همان authtoken است.
  3. روی دکمهٔ Copy کنار آن بزن تا کامل کپی شود.
  4. موقتاً آن را در یک فایل متنی یا جای امن نگه دار؛ چند مرحله بعد به آن نیاز داریم.
پانویس ۴ — «authtoken» یعنی چه؟
کوتاه‌شدهٔ authentication token یعنی «نشانهٔ احراز هویت». مثل یک رمزِ یک‌بار‌نمایش که ثابت می‌کند تو مجازی از این سرویس استفاده کنی.
⚠️ مواظب باش این کلید مثل رمز عبور است. آن را در عکس، پیام عمومی، یا فایلی که روی گیت‌هاب public می‌گذاری قرار نده. هر کس آن را داشته باشد می‌تواند از حساب تو تونل بسازد.
✅ ایست بازرسی باید یک رشتهٔ بلند را کپی کرده و جایی امن ذخیره کرده باشی. اگر یادت رفت کجا بود، همیشه می‌توانی به همین صفحه برگردی.
مرحله ۳ از ۸
۳

رزرو دامنهٔ ثابت NGROK_DOMAIN

⏱️ حدود ۵ دقیقه

اگر دامنهٔ ثابت نگیری، هر بار که ngrok را دوباره روشن کنی آدرست عوض می‌شود و باید همه‌جا آدرس جدید را بروزرسانی کنی. خوشبختانه حساب رایگان یک دامنهٔ ثابت به تو می‌دهد که همیشه یکی می‌ماند.

  1. در داشبورد به بخش Domains برو:
    https://dashboard.ngrok.com/domains
  2. روی دکمهٔ New + (یا Create Domain) بزن.
  3. ngrok یک دامنهٔ ثابتِ رایگان به تو پیشنهاد می‌دهد؛ چیزی شبیه:
    happy-panda-1234.ngrok.app
  4. آن را تأیید و کپی کن. این همان NGROK_DOMAIN ماست.
📖 آدرس کاملِ سایتت این می‌شود اگر دامنه‌ات happy-panda-1234.ngrok.app باشد، آدرس عمومیِ نهایی که در مرورگر باز می‌شود می‌شود:
https://happy-panda-1234.ngrok.app
یعنی همان الگوی https://${NGROK_DOMAIN} که در عنوان این آموزش دیدی.
پانویس ۵ — چرا «دامنهٔ ثابت» مهم است؟
وبهوک‌ها را یک بار در سرویس‌های بیرونی ثبت می‌کنی. اگر آدرست هر بار عوض شود، همهٔ آن ثبت‌ها خراب می‌شوند. دامنهٔ ثابت یعنی یک بار تنظیم، برای همیشه.
✅ ایست بازرسی الان باید سه چیز داشته باشی و کنار هم یادداشت کرده باشی: کلید NGROK_AUTHTOKEN، دامنهٔ NGROK_DOMAIN، و بدانی آدرس نهایی https://${NGROK_DOMAIN} است.
مرحله ۴ از ۸
۴

ساخت فایل .env (جای نگه‌داری تنظیمات)

⏱️ حدود ۷ دقیقه

یک پوشهٔ خالی بساز (مثلاً روی دسکتاپ اسمش را n8n-ngrok بگذار). همهٔ کارها را داخل همین پوشه انجام می‌دهیم.

  1. داخل این پوشه یک فایل جدید بساز و اسمش را دقیقاً بگذار .env (با یک نقطه در ابتدا، بدون هیچ پسوند دیگری).
  2. این محتوا را داخلش بریز و مقدارها را با مقدار خودت جایگزین کن:
# © Mehdi Rezghi — Gravel | فایل .env # دامنهٔ ثابتی که در مرحله ۳ رزرو کردی (بدون https) NGROK_DOMAIN=happy-panda-1234.ngrok.app # کلیدی که در مرحله ۲ کپی کردی NGROK_AUTHTOKEN=2Xy...کلیدِ_خودت...aBcD # تنظیمات لازم n8n N8N_HOST=happy-panda-1234.ngrok.app WEBHOOK_URL="https://happy-panda-1234.ngrok.app/" N8N_RUNNERS_ENABLED=true N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true # منطقهٔ زمانی (برای ایران): TZ="Asia/Tehran" GENERIC_TIMEZONE="Asia/Tehran"
⚠️ مهم‌ترین اشتباه رایج این آموزش داخل فایل .env، جلوی WEBHOOK_URL و N8N_HOST باید خودِ دامنه را کامل تایپ کنی؛ اینجا نوشتنِ ${NGROK_DOMAIN} کار نمی‌کند، چون فایل .env متغیرها را داخل خودش جایگزین نمی‌کند. الگوی ${NGROK_DOMAIN} فقط در فایل بعدی (docker-compose.yaml) معنا دارد.
💡 دو نکتهٔ ریز ولی مهم • دور و برِ علامت = فاصله نگذار (بنویس TZ=Asia/Tehran نه TZ = Asia/Tehran).
• آدرس WEBHOOK_URL باید با https:// شروع شود و به یک / ختم شود.
پانویس ۶ — «فایل .env» یعنی چه؟
یک فایل متنی ساده که «تنظیمات» را نگه می‌دارد تا مجبور نباشی آن‌ها را وسط دستورها تکرار کنی. داکر خودش این فایل را می‌خواند. env کوتاه‌شدهٔ environment (محیط) است.
پانویس ۷ — چرا WEBHOOK_URL لازم است؟
اگر این را ست نکنی، n8n آدرسِ وبهوک‌ها را با localhost می‌سازد و سرویس‌های بیرونی نمی‌توانند به آن برسند. با ست‌کردنِ آن روی دامنهٔ عمومی، آدرس وبهوک درست و قابل‌دسترسی می‌شود.
✅ ایست بازرسی باید یک فایل به اسم .env داخل پوشه‌ات داشته باشی که ۴ مقدار مهمش (دامنه، توکن، هاست، آدرس وبهوک) با مقدار واقعیِ خودت پر شده باشد.
مرحله ۵ از ۸
۵

ساخت فایل docker-compose.yaml

⏱️ حدود ۸ دقیقه

این فایل به داکر می‌گوید «دو تا برنامه را با هم بالا بیاور»: یکی n8n و یکی ngrok. داخل همان پوشه یک فایل جدید بساز و اسمش را بگذار docker-compose.yaml. این محتوا را داخلش بریز:

# © Mehdi Rezghi — Gravel | docker-compose.yaml services: n8n: image: docker.n8n.io/n8nio/n8n restart: always ports: - "127.0.0.1:5678:5678" env_file: .env volumes: - n8n_data:/home/node/.n8n ngrok: image: ngrok/ngrok:latest restart: always depends_on: - n8n env_file: .env # اینجا ${NGROK_DOMAIN} از فایل .env خوانده و جایگزین می‌شود command: http --url=${NGROK_DOMAIN} n8n:5678 ports: - "4040:4040" # پنل مانیتورینگ ngrok volumes: n8n_data:
⚠️ نکتهٔ طلایی: چرا n8n:5678 و نه localhost:5678؟ داخل داکر، وقتی یک ظرف (container) می‌خواهد با ظرف دیگر حرف بزند، localhost اشتباه است؛ چون localhost برای هر ظرف یعنی «خودِ همان ظرف». برای اینکه ظرفِ ngrok به ظرفِ n8n برسد، باید از اسم سرویس یعنی n8n استفاده کنی. داکر خودش این اسم را به آدرس درست وصل می‌کند.
پانویس ۸ — «ظرف / container» یعنی چه؟
هر برنامه در داکر داخل یک «جعبهٔ جدا» به اسم container اجرا می‌شود. این جعبه‌ها همسایه‌اند ولی هرکدام دنیای خودشان را دارند.
پانویس ۹ — این خط‌ها یعنی چه؟
• image: کدام برنامه را دانلود و اجرا کند.
• ports: کدام درگاه (port) باز باشد؛ مثلاً 5678 درگاهِ n8n است.
• volumes: جایی که اطلاعاتِ n8n ذخیره می‌شود تا با خاموش‌شدن پاک نشود.
• command: دستوری که به ngrok می‌گوید تونلِ HTTP روی دامنهٔ تو به سمت n8n بساز.
✅ ایست بازرسی حالا باید داخل پوشه‌ات دو فایل کنار هم باشند: .env و docker-compose.yaml.
مرحله ۶ از ۸
۶

اجرا با یک دستور

⏱️ حدود ۴ دقیقه
  1. ترمینال را باز کن و با دستور cd برو داخل همان پوشه. مثلاً اگر روی دسکتاپ است:
    cd Desktop/n8n-ngrok
  2. این دستور را بزن تا هر دو برنامه با هم بالا بیایند:
    docker compose up -d
پانویس ۱۰ — این -d ته دستور چیست؟
یعنی «در پس‌زمینه اجرا کن» تا ترمینال آزاد بماند. اگر آن را نگذاری، همه‌چیز کار می‌کند ولی ترمینال مشغول می‌ماند و پیام‌ها را زنده می‌بینی (برای بستن باید Ctrl + C بزنی).

برای دیدن اینکه همه‌چیز روشن است، این را بزن:

docker compose ps
✅ ایست بازرسی در خروجی باید دو ردیف ببینی — یکی برای n8n و یکی برای ngrok — که وضعیت‌شان running یا Up باشد. اگر یکی Exited بود، به رفع اشکال برو.
مرحله ۷ از ۸
۷

تست آدرس عمومی و پنل ngrok

⏱️ حدود ۵ دقیقه
  1. مرورگر را باز کن و آدرس عمومیِ خودت را برو (همان دامنهٔ مرحله ۳):
    https://happy-panda-1234.ngrok.app
  2. باید صفحهٔ خوش‌آمدِ n8n باز شود و از تو بخواهد یک حساب مدیر بسازی. همان‌جا نام، ایمیل و رمز بده.
  3. برای دیدن ترافیکِ زنده، پنل داخلیِ ngrok را هم باز کن:
    http://localhost:4040
پانویس ۱۱ — پنل 4040 چیست؟
یک صفحهٔ بازرسی که هر درخواستی که به تونلت می‌رسد را نشان می‌دهد. وقتی وبهوک کار نکرد، اینجا اولین جایی است که سر می‌زنی تا ببینی درخواست اصلاً رسیده یا نه.
✅ ایست بازرسی اگر با آدرس https://${NGROK_DOMAIN} صفحهٔ n8n باز شد، تونل کار می‌کند 🎉. می‌توانی همین آدرس را روی گوشیِ خودت هم باز کنی؛ چیزی که با localhost ممکن نبود.
مرحله ۸ از ۸
۸

تست یک وبهوک واقعی

⏱️ حدود ۶ دقیقه

حالا بیایید ثابت کنیم که وبهوک‌ها هم درست شده‌اند.

  1. در n8n یک Workflow جدید بساز.
  2. یک گره (Node) از نوع Webhook اضافه کن.
  3. در تنظیمات آن گره، آدرسِ Test URL یا Production URL را نگاه کن؛ باید حالا با دامنهٔ ngrok تو شروع شود، مثل:
    https://happy-panda-1234.ngrok.app/webhook/....
  4. روی Listen for test event بزن.
  5. آن آدرس وبهوک را در یک تب دیگرِ مرورگر باز کن (یا با Postman صدا بزن).
پانویس ۱۲ — «گره / Node» یعنی چه؟
در n8n هر کار یک «گره» است؛ مثل قطعه‌های لِگو که کنار هم می‌چینی تا یک اتوماسیون کامل بسازی.
✅ ایست بازرسی نهایی اگر بعد از صدا زدنِ آن آدرس، در n8n پیام موفقیت دیدی و درخواست در پنل localhost:4040 ثبت شد، یعنی همه‌چیز کامل کار می‌کند و n8n تو آمادهٔ اتصال به سرویس‌های بیرونی است.
💡 قدم بعدی طبیعی حالا که وبهوک عمومی داری، می‌توانی n8n را به تلگرام، اسلک یا سرویس‌های دیگر وصل کنی — همه به این آدرسِ ثابتِ عمومی زنگ می‌زنند و اتوماسیونت اجرا می‌شود.

🔒 (اختیاری) قفلِ اضافه روی درِ خانه

آدرست حالا عمومی است؛ اگر خواستی امن‌ترش کنی، این دو راه ساده هست.

۱) فقط اجازه به IP خودت. می‌توانی به ngrok بگویی فقط اینترنتِ خودت اجازهٔ باز کردنِ پنل n8n را داشته باشد. اول IP عمومی‌ات را از این ابزار بگیر:

https://ipv4.ngrok.com/

بعد کنار فایل‌ها یک فایل به اسم n8n.yaml بساز:

# © Mehdi Rezghi — Gravel | n8n.yaml — فقط IP خودت اجازه دارد on_http_request: - actions: - type: restrict-ips config: enforce: true allow: - "IP_خودت/32"

سپس در docker-compose.yaml، خط دستورِ ngrok و بخش volumes آن را این‌طور کن:

command: http --url=${NGROK_DOMAIN} --traffic-policy-file /etc/n8n.yaml n8n:5678 volumes: - ./n8n.yaml:/etc/n8n.yaml

و برای اعمال تغییر:

docker compose down docker compose up -d
⚠️ حواست باشد اگر IP خودت را محدود کنی و بعداً بخواهی از یک سرویس بیرونی وبهوک بگیری، آن سرویس دیگر اجازه ندارد. در آن حالت باید مسیرِ /webhook/ را از محدودیت IP جدا کنی (سیاست کامل‌ترش در مستندات رسمی ngrok هست).
پانویس ۱۳ — «IP عمومی» یعنی چه؟
شمارهٔ خانهٔ تو در اینترنت. هر اتصالِ اینترنتی یک IP عمومی دارد که او را از بقیه جدا می‌کند.

🔧 رفع اشکال — اگر جایی گیر کردی

پرتکرارترین مشکل‌ها و راه‌حلِ ساده‌شان.

نشانه (چه می‌بینی؟)علتراه‌حل
آدرس عمومی باز نمی‌شود و خطای ERR_NGROK می‌بینی authtoken اشتباه یا جا‌افتاده مقدار NGROK_AUTHTOKEN در فایل .env را دوباره از داشبورد کپی کن؛ فاصلهٔ اضافه نباشد. بعد docker compose down و دوباره up -d.
ظرف ngrok بالا می‌آید ولی سریع Exited می‌شود دامنه اشتباه تایپ شده یا قبلاً جای دیگری استفاده شده مقدار NGROK_DOMAIN را عیناً با چیزی که در بخش Domains رزرو کردی مطابقت بده (بدون https://).
صفحهٔ n8n باز می‌شود ولی وبهوک آدرسِ localhost می‌دهد WEBHOOK_URL ست نشده یا اشتباه است در .env مطمئن شو WEBHOOK_URL با https:// شروع و به / ختم می‌شود؛ سپس کانتینرها را ری‌استارت کن.
خطای port is already allocated درگاه 5678 یا 4040 را برنامهٔ دیگری گرفته آن برنامه را ببند، یا سمت چپِ نگاشتِ درگاه را عوض کن (مثلاً 5679:5678).
وبهوک از بیرون به n8n نمی‌رسد یا محدودیت IP فعال است، یا درخواست اصلاً نرسیده اول در پنل localhost:4040 ببین درخواست ثبت شده یا نه. اگر نه، محدودیت IP یا فایروال را چک کن.
docker compose up می‌گوید فایل پیدا نشد در پوشهٔ اشتباه هستی با cd برو داخل همان پوشه‌ای که دو فایل در آن است، بعد دستور را بزن.

📚 واژه‌نامهٔ کوتاه

tunnel (تونل)
مسیر امنی که کامپیوترِ تو را از راهِ یک آدرس عمومی به اینترنت وصل می‌کند.
authtoken
کلید شناساییِ تو نزد ngrok؛ مثل رمز عبور، محرمانه نگهش دار.
NGROK_DOMAIN
دامنهٔ ثابتِ رایگانِ تو، مثل happy-panda-1234.ngrok.app.
webhook (وبهوک)
آدرسی که به سرویس بیرونی می‌دهی تا هر وقت اتفاقی افتاد به تو خبر بدهد.
container (ظرف)
جعبهٔ جدا و مستقلی که یک برنامه داخل داکر در آن اجرا می‌شود.
localhost
«همین کامپیوترِ خودم»؛ از بیرونِ دستگاه در دسترس نیست.
docker compose
ابزاری برای بالا آوردنِ چند برنامه با هم، با یک فایل تنظیمات.
.env
فایل ساده‌ای که تنظیمات (دامنه، توکن و…) را نگه می‌دارد.

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

✍️ طراحی و تدوین: Mehdi Rezghi — مهدی رزقی

🏔️ بخشی از گراول — کتابخانهٔ آموزش گام‌به‌گام  |  © 2026 Mehdi Rezghi — @Mehdirezghi