تشغيل n8n محلياً باستخدام Docker: دليل شامل مع PostgreSQL و Ngrok

لماذا تشغّل n8n محلياً؟

منصة n8n هي أداة أتمتة مفتوحة المصدر تتيح لك بناء سير عمل ذكي بواجهة مرئية — بدون كتابة كود. بينما توفر n8n خدمة سحابية مدفوعة، فإن تشغيلها محلياً على جهازك يمنحك تحكماً كاملاً في البيانات وسرعة أكبر في التطوير وعدم الحاجة لاشتراك مدفوع. هذا مثالي لورشات العمل والتدريب والتجارب الشخصية.

مكونات الحزمة (Stack)

تتكون الحزمة من ثلاث خدمات تعمل معاً داخل Docker:

1. n8n — محرك الأتمتة الرئيسي. الواجهة المرئية التي تبني فيها سير العمل بالسحب والإفلات. يدعم أكثر من 400 تكامل جاهز مع خدمات مثل Telegram و Gmail و Google Sheets والذكاء الاصطناعي.

2. PostgreSQL — قاعدة بيانات احترافية بدلاً من SQLite الافتراضي. تضمن أداء أفضل واستقرار أعلى خصوصاً مع سير العمل المعقد والبيانات الكبيرة.

3. Ngrok — نفق يكشف خادمك المحلي للإنترنت. ضروري لاستقبال الويب هوكات من خدمات خارجية مثل Telegram و Stripe. بدونه لا يمكن لهذه الخدمات إرسال البيانات لجهازك المحلي.

المتطلبات المسبقة

قبل البدء تحتاج شيئين فقط:

أولاً: تثبيت Docker Desktop من الموقع الرسمي docker.com — متاح لأنظمة Windows و Mac و Linux. تأكد من تشغيله بعد التثبيت.

ثانياً: إنشاء حساب مجاني على ngrok.com والحصول على Authtoken من لوحة التحكم. هذا التوكن يربط حاوية Ngrok بحسابك ويفعّل النفق.

ملف Docker Compose الكامل

الحزمة تُعرّف في ملف docker-compose.yml واحد يحتوي تعريف الخدمات الثلاث والمجلدات المشتركة (Volumes) لحفظ البيانات. كل خدمة معزولة عن الأخرى لكنها متصلة عبر شبكة Docker الداخلية.

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=${DB_POSTGRESDB_USER:-n8n}
      - POSTGRES_PASSWORD=${DB_POSTGRESDB_PASSWORD:-n8n_password}
      - POSTGRES_DB=${DB_POSTGRESDB_DATABASE:-n8n}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -h localhost -U ${DB_POSTGRESDB_USER:-n8n}']
      interval: 5s
      timeout: 5s
      retries: 10

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${DB_POSTGRESDB_DATABASE:-n8n}
      - DB_POSTGRESDB_USER=${DB_POSTGRESDB_USER:-n8n}
      - DB_POSTGRESDB_PASSWORD=${DB_POSTGRESDB_PASSWORD:-n8n_password}
      - N8N_HOST=${N8N_HOST:-localhost}
      - N8N_PORT=5678
      - WEBHOOK_URL=${WEBHOOK_URL:-}
    ports:
      - "5678:5678"
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - n8n_data:/home/node/.n8n

  ngrok:
    image: ngrok/ngrok:latest
    restart: unless-stopped
    command:
      - "http"
      - "http://n8n:5678"
      - "--log"
      - "stdout"
    environment:
      - NGROK_AUTHTOKEN=${NGROK_AUTHTOKEN}
    ports:
      - "4040:4040"
    depends_on:
      - n8n

volumes:
  postgres_data:
  n8n_data:

خطوات التشغيل

الخطوة 1: إعداد ملف المتغيرات

أنشئ ملف .env في نفس المجلد وأضف فيه توكن Ngrok الخاص بك:

NGROK_AUTHTOKEN=your_ngrok_auth_token_here
GENERIC_TIMEZONE=Asia/Amman

الخطوة 2: تشغيل الحزمة

افتح الطرفية (Terminal) في مجلد المشروع وشغّل أمر واحد:

docker compose up -d

Docker سيحمّل الصور اللازمة ويشغّل الحاويات الثلاث. PostgreSQL يبدأ أولاً وينتظر حتى يكون جاهزاً (Health Check)، ثم يبدأ n8n، وأخيراً Ngrok.

الخطوة 3: الوصول لـ n8n

افتح المتصفح على العنوان http://localhost:5678 — ستظهر شاشة إعداد حساب المدير. أنشئ حسابك وابدأ بناء سير العمل الأول!

الخطوة 4: الحصول على رابط Ngrok العام

لمعرفة الرابط العام الذي أنشأه Ngrok، افتح http://localhost:4040/api/tunnels — ابحث عن قيمة public_url واستخدمها عند ربط الويب هوكات مع خدمات خارجية مثل Telegram.

فهم البنية التقنية

لماذا PostgreSQL بدل SQLite؟ الإعداد الافتراضي لـ n8n يستخدم SQLite وهو كافٍ للتجارب البسيطة. لكن PostgreSQL يتفوق في الأداء مع سير العمل المعقد ويدعم الاستعلامات المتزامنة ويحافظ على استقرار البيانات عند إيقاف وتشغيل الحاويات بشكل متكرر.

لماذا Ngrok؟ عندما تشغّل n8n محلياً، عنوانك هو localhost:5678 — وهذا غير قابل للوصول من الإنترنت. خدمات مثل Telegram تحتاج إرسال ويب هوكات لعنوان عام. Ngrok ينشئ نفقاً آمناً يحوّل الطلبات من رابط عام إلى خادمك المحلي.

Docker Volumes: البيانات محفوظة في مجلدات Docker مستقلة (postgres_data و n8n_data). هذا يعني أنك تستطيع إيقاف وحذف الحاويات بدون خسارة بياناتك — سير العمل والحسابات والتنفيذات كلها محفوظة.

إيقاف وإعادة التشغيل

# إيقاف مؤقت (البيانات محفوظة)
docker compose stop

# إعادة التشغيل
docker compose start

# إزالة الحاويات (البيانات تبقى في Volumes)
docker compose down

# إزالة كل شيء بما فيه البيانات (استخدم بحذر!)
docker compose down -v

نصائح للورشات التدريبية

إذا كنت تستخدم هذه الحزمة في ورشة تدريبية، إليك بعض النصائح المهمة:

أولاً: اطلب من المشاركين تثبيت Docker Desktop وإنشاء حساب Ngrok قبل يوم الورشة — تحميل الصور يحتاج وقتاً وإنترنت جيد.

ثانياً: جهّز ملف .env مسبقاً واطلب منهم فقط إضافة توكن Ngrok الخاص بهم.

ثالثاً: تذكّر أن رابط Ngrok يتغير كل مرة تعيد تشغيل الحاوية (في النسخة المجانية). إذا كنت تستخدم رابط Ngrok ثابت (Static Domain)، أضفه في أمر التشغيل.

رابعاً: أضف WEBHOOK_URL في ملف .env بعد الحصول على رابط Ngrok — هذا يجعل n8n يعرض الرابط الصحيح تلقائياً عند بناء سير العمل.

أمثلة على سير عمل يمكن بناؤه

بمجرد تشغيل الحزمة، يمكنك بناء سير عمل متقدم مثل:

بوت Telegram ذكي — يستقبل أسئلة عبر Telegram ويجيب باستخدام الذكاء الاصطناعي ويسجل المحادثات في Google Sheets.

نظام طلبات إجازة تلقائي — نموذج ويب يستقبل الطلبات والذكاء الاصطناعي يقرر ويرسل الإشعارات عبر البريد و Telegram.

محلل سيرة ذاتية (CV) — بوت يستقبل ملف PDF عبر Telegram ويحلله ويعطي تقييماً فورياً مع نصائح تحسين.

مراقب أسعار منتجات — بوت يتابع أسعار المنتجات على المتاجر الإلكترونية ويبلغك عند تغير السعر.

كل هذه الأمثلة تعمل بشكل كامل على الحزمة المحلية مع Ngrok لاستقبال الويب هوكات من Telegram.

الخلاصة

تشغيل n8n محلياً باستخدام Docker Compose مع PostgreSQL و Ngrok يمنحك بيئة أتمتة احترافية كاملة — مجانية ومفتوحة المصدر وتحت سيطرتك الكاملة. سواء كنت تتعلم الأتمتة لأول مرة أو تجهّز ورشة تدريبية أو تطوّر حلولاً للإنتاج، هذه الحزمة نقطة انطلاق ممتازة. حمّل الملفات وشغّل أمر واحد وابدأ البناء!