‫n8n‬ خارج الذاكرة: التشخيص والإصلاح على ‫VPS‬

لماذا يتعطل ‫n8n‬ بسبب الذاكرة، وليس للسبب الذي تظنه

علامات تؤكد عطل ‫OOM‬ في ‫n8n‬

• رسالة الخروج الدقيقة: ‫FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory‬ في سجلات الحاوية (‫docker logs n8n‬)
• توقف صامت تحت ‫systemd‬: تعيد الخدمة التشغيل تلقائياً دون أثر إذا كان ‫Restart=always‬ مفعلاً — تحقق عبر ‫journalctl -u n8n --since "1 hour ago"‬
• ‫OOM kill‬ النواة: ‫dmesg | grep -i oom‬ يظهر ‫Killed process <pid> (node)‬ قبل إعادة التشغيل، بمعزل عن ‫Node‬
• ارتباط بسير عمل ثقيل: يحدث العطل دائماً أثناء تنفيذات من نوع «معالجة ملف» أو «حلقة على آلاف العناصر»
• ‫heap‬ ثابت لساعات ثم ارتفاع مفاجئ: سير عمل يُشغَّل دورياً يتراكم فيه ‫closure‬ غير محررة — يرتفع ‫heap‬ في كل تشغيل ولا يعود كاملاً
• حمل ذاكرة طبيعي في ‫htop‬: ذاكرة ‫RAM‬ النظام غير مستنفدة وقت العطل، ما يؤكد أن المشكلة في ‫V8‬ لا الجهاز

المتطلبات قبل التدخل

إصلاح ‫OOM‬: من التشخيص إلى الإعداد الثابت

1. 01

   تأكيد السبب من السجلات

   اقرأ آخر 200 سطر من الحاوية وقت العطل:

   docker logs n8n --tail 200 2>&1 | grep -E "FATAL|heap|OOM|Killed"

   إن رأيت ‫FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory‬ فالمشكلة في ‫V8‬. إن رأيت ‫Killed‬ وحده دون رسالة ‫Node‬، فهو ‫OOM killer‬ النواة — قد يتزامن الاثنان في نفس الحادثة.

2. 02

   تعيين حد ‫V8‬ عبر ‫NODE_OPTIONS‬

   في ‫docker-compose.yml‬، أضف متغير البيئة ‫NODE_OPTIONS‬ إلى خدمة ‫n8n‬. القيمة الموصى بها حسب ‫RAM‬ الـ‫VPS‬:

   - ‫VPS‬ 4 غيغابايت: ‫--max-old-space-size=2048‬
   - ‫VPS‬ 8 غيغابايت: ‫--max-old-space-size=4096‬
   - ‫VPS‬ 16 غيغابايت: ‫--max-old-space-size=8192‬

   القاعدة: احجز ما يقارب نصف الذاكرة المتاحة بعد النظام والخدمات المساندة (‫Redis‬، البروكسي). لا تتجاوز 70% من إجمالي الـ‫RAM‬.

   services:
     n8n:
       image: n8nio/n8n:latest
       environment:
         - NODE_OPTIONS=--max-old-space-size=4096
         # ... متغيرات أخرى

3. 03

   التحقق من قراءة القيمة فعلياً

   بعد ‫docker compose up -d‬، تحقق من أن ‫Node‬ يقرأ الحد:

   docker exec n8n node -e "const v8=require('v8'); console.log(v8.getHeapStatistics().heap_size_limit / 1024 / 1024, 'MB')"

   يجب أن تقترب القيمة المعروضة من ‫--max-old-space-size‬. إن عرضت 512 أو 1500 مجدداً، فمتغير البيئة غير مُمرَّر للعملية — تحقق من أن ‫NODE_OPTIONS‬ في قسم ‫environment:‬ للخدمة.

4. 04

   الانتقال إلى وضع ‫queue‬ مع ‫Redis‬

   وضع ‫main‬ (الافتراضي) ينفذ كل شيء في عملية واحدة. للخوادم التي تتعامل مع أكثر من 20 سير عمل متزامناً أو حمولات كبيرة، افصل الأدوار:

   services:
     redis:
       image: redis:7-alpine
       restart: unless-stopped
       volumes:
         - redis_data:/data
   
     n8n:
       image: n8nio/n8n:latest
       environment:
         - NODE_OPTIONS=--max-old-space-size=2048
         - EXECUTIONS_MODE=queue
         - QUEUE_BULL_REDIS_HOST=redis
         - QUEUE_BULL_REDIS_PORT=6379
       depends_on:
         - redis
       ports:
         - "5678:5678"
   
     n8n-worker:
       image: n8nio/n8n:latest
       command: worker
       environment:
         - NODE_OPTIONS=--max-old-space-size=4096
         - EXECUTIONS_MODE=queue
         - QUEUE_BULL_REDIS_HOST=redis
         - QUEUE_BULL_REDIS_PORT=6379
       depends_on:
         - redis
       scale: 2
   
   volumes:
     redis_data:

   تصبح خدمة ‫n8n‬ هي العملية الرئيسية (‫API‬ + واجهة + ‫webhook‬) بحد معتدل. تتولى خدمة ‫n8n-worker‬ التنفيذات بحد أعلى. ‫scale: 2‬ يشغل عاملَين — اضبط حسب احتياجاتك.

5. 05

   فصل عملية ‫webhook‬ إذا تطلب الحجم ذلك

   على الخوادم التي تستقبل ‫webhook‬ متوازياً بكثرة، قد تكون العملية الرئيسية مشبعة دون تنفيذ سير عمل. ‫n8n‬ يوفر وضع ‫webhook‬ مخصصاً:

     n8n-webhook:
       image: n8nio/n8n:latest
       command: webhook
       environment:
         - NODE_OPTIONS=--max-old-space-size=1024
         - EXECUTIONS_MODE=queue
         - QUEUE_BULL_REDIS_HOST=redis
         - QUEUE_BULL_REDIS_PORT=6379
         - N8N_DISABLE_UI=true
       depends_on:
         - redis
       ports:
         - "5679:5678"

   ثم اضبط البروكسي لتوجيه ‫/webhook/‬ إلى المنفذ 5679 وباقي الطلبات إلى المنفذ 5678 للعملية الرئيسية. وضع ‫webhook‬ متاح من ‫n8n‬ 1.0.

6. 06

   تفعيل ‫garbage collection‬ الصريح للسير الثقيلة

   للسير العمل التي تعالج ملفات كبيرة أو حلقات طويلة، يمكنك مساعدة ‫V8‬ على تحرير الذاكرة بشكل أكثر حدة:

   NODE_OPTIONS="--max-old-space-size=4096 --expose-gc"

   هذا يكشف ‫global.gc()‬ — يمكن لـ‫n8n‬ استدعاؤه بين خطوات سير العمل. اجمعه مع ‫EXECUTIONS_DATA_SAVE_ON_SUCCESS=none‬ إن لم تحتج لتاريخ التنفيذ: بيانات التنفيذ المحتجزة كثيراً ما تمثل 30-50% من ‫heap‬.

7. 07

   مراقبة ‫heap‬ بعد الإصلاح

   فعّل مقاييس ‫n8n‬ لمتابعة ‫heap‬ دون تدخل يدوي:

   N8N_METRICS=true
   N8N_METRICS_PREFIX=n8n_

   نقطة الوصول ‫/metrics‬ (المنفذ 5678) تكشف حينئذٍ ‫nodejs_heap_size_used_bytes‬ و‫nodejs_heap_size_total_bytes‬، متوافقة مع ‫Prometheus‬. لوحة ‫Grafana‬ بسيطة على هذين المقياسين ستنبهك قبل العطل التالي.

الإعداد بعد الإصلاح: متغيرات البيئة المفيدة

استكشاف الأخطاء — أخطاء حقيقية وأسبابها

المصادر والخطوات التالية