أخطاء n8n الشائعة على سيرفر مستضاف ذاتيًا وطريقة إصلاحها

ترجع معظم الأخطاء على سيرفر n8n المستضاف ذاتيًا إلى سبب من بضعة أسباب: حاوية Docker لا تعمل، أو إعدادات الـ reverse proxy أو HTTPS غير صحيحة، أو السيرفر يعاني نقصًا في الذاكرة أو المساحة، أو أن أحد متغيرات البيئة مثل WEBHOOK_URL أو GENERIC_TIMEZONE أو N8N_ENCRYPTION_KEY مفقود أو خاطئ. يكون الحل عادةً بقراءة سجلات الحاوية، ثم تصحيح المتغير في ملف compose أو ملف .env، ثم إعادة إنشاء الحاوية باستخدام docker compose up -d. هذا الدليل مُرتَّب حسب العَرَض، وينطبق على n8n الذي يعمل داخل Docker على Ubuntu 22.04 أو 24.04، بما في ذلك استضافة n8n من Cloudesta وn8n الذي ثبّتّه بنفسك على VPS سحابي.

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

• وصول عبر SSH بصلاحيات root أو بمستخدم لديه صلاحيات sudo.
• تشغيل n8n باستخدام Docker Compose v2 (الأمر docker compose).
• نسخة احتياطية حديثة من وحدة تخزين بيانات n8n قبل إجراء أي تغيير.

نفّذ جميع الأوامر من المجلد الذي يحتوي على ملف docker-compose.yml. إذا كنت لا تعرف مكانه، فاعرف اسم الحاوية باستخدام docker ps ثم اطلب من Docker مسار المجلد. تفترض الأوامر في هذا الدليل أن اسم الخدمة واسم الحاوية كليهما n8n. استبدل هذا الاسم إذا كان مختلفًا لديك.

docker ps --format '{{.Names}}  {{.Image}}  {{.Status}}'
docker inspect n8n --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'

1. لماذا لا تفتح صفحة n8n؟

ابدأ بالتحقق من أن الحاوية تعمل وأن n8n يستجيب محليًا.

docker compose ps
docker compose logs --tail=100 n8n
curl -s http://127.0.0.1:5678/healthz

• الحاوية متوقفة أو تعيد التشغيل باستمرار: اقرأ السجلات وراجع القسم 6.
• يُرجع /healthz القيمة {"status":"ok"} لكن الموقع لا يفتح: المشكلة في الـ reverse proxy أو DNS أو الجدار الناري. افحص الـ proxy باستخدام sudo nginx -t وsudo systemctl status nginx (أو ما يقابلهما في Caddy أو Traefik). وتأكد من أن نطاقك يشير إلى عنوان IP الخاص بالسيرفر.
• افحص الجدار الناري:

sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

المنافذ التي ينشرها Docker تتجاوز قواعد UFW. إذا كان n8n يعمل خلف proxy، فاربطه بـ localhost فقط باستخدام "127.0.0.1:5678:5678" تحت ports:، حتى لا يكون المنفذ 5678 مكشوفًا على الإنترنت.

2. كيف أُصلح رسالة "Your n8n server is configured to use a secure cookie"؟

تظهر هذه الرسالة عند فتح n8n عبر HTTP العادي، مثل http://203.0.113.10:5678. الحل الصحيح هو تقديم n8n عبر HTTPS من خلال reverse proxy بشهادة صالحة، ثم ضبط هذه المتغيرات:

N8N_HOST=n8n.example.com
N8N_PROTOCOL=https
N8N_PROXY_HOPS=1

لإجراء اختبار قصير على شبكة خاصة فقط، يمكنك ضبط N8N_SECURE_COOKIE=false. لا تترك هذا الإعداد مفعّلًا على سيرفر يمكن الوصول إليه من الإنترنت.

3. لماذا لا تعمل الـ webhooks في n8n؟

• رابط خاطئ يظهر في عقدة Webhook. إذا كانت العقدة تعرض localhost:5678، فاضبط الرابط العام وأعد إنشاء الحاوية: WEBHOOK_URL=https://n8n.example.com/
• سير العمل غير مُفعَّل. روابط الإنتاج (/webhook/...) لا تعمل إلا أثناء تفعيل سير العمل. أما روابط الاختبار (/webhook-test/...) فلا تعمل إلا أثناء الاستماع داخل المحرر.
• مشكلات الـ proxy. يجب أن يمرّر الـ proxy ترويسات المضيف والبروتوكول الأصلية. ولكي يظل المحرر متصلًا، يجب أيضًا أن يسمح بترقية الاتصال إلى WebSocket. يبدو الحد الأدنى من إعدادات Nginx كالتالي:

location / {
    proxy_pass http://127.0.0.1:5678;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
}

لاختبار webhook من خارج السيرفر، أرسل إليه طلبًا باستخدام curl -X POST https://n8n.example.com/webhook/your-path.

4. لماذا تفشل عمليات التنفيذ بأخطاء في الذاكرة أو تعمل ببطء؟

تعني رسائل مثل "JavaScript heap out of memory" أو "n8n may have run out of memory" أن سير العمل عالج بيانات أكثر مما تسمح به ذاكرة RAM المتاحة. افحص الاستهلاك الحالي أولًا:

free -h
docker stats --no-stream

ثم طبّق هذه الحلول بالترتيب:

• قلّل البيانات في كل تشغيل. عالج مجموعات البيانات الكبيرة على دفعات باستخدام عقدة Loop Over Items، وتجنّب تمرير ملفات ثنائية كبيرة بين العقد.
• ارفع حد ذاكرة heap في Node.js. اجعله أقل من ذاكرة RAM الخاصة بالسيرفر، مثل NODE_OPTIONS=--max-old-space-size=2048.
• حدّد عدد عمليات التشغيل المتوازية. على سبيل المثال، يحدّد N8N_CONCURRENCY_PRODUCTION_LIMIT=5 الحد الأقصى لعمليات تنفيذ الإنتاج التي تعمل في الوقت نفسه.
• احتفظ بسجل تنفيذ أقل:

EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=168
EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000
EXECUTIONS_DATA_SAVE_ON_SUCCESS=none

تُقاس قيمة EXECUTIONS_DATA_MAX_AGE بالساعات، لذا فإن القيمة 168 تحتفظ بسجل أسبوع واحد. إذا استمر نفاد الذاكرة في سير العمل بعد هذه التغييرات، فالسيرفر يحتاج إلى ذاكرة RAM أكبر. تتم ترقية الخطط عبر فتح تذكرة دعم.

5. ماذا أفعل عندما تكبر قاعدة البيانات أو تمتلئ المساحة؟

امتلاء المساحة يجعل n8n يفشل بطرق غريبة، مثل تغييرات محفوظة لا تُطبَّق أو أخطاء "disk I/O" في SQLite. اعرف ما الذي يستهلك المساحة:

df -h
docker system df
sudo du -sh /var/lib/docker/volumes/* | sort -h | tail
sudo journalctl --vacuum-size=200M
docker image prune -f

عادةً ما يكون سجل التنفيذ هو السبب الرئيسي، لذا فعّل إعدادات التنظيف المذكورة في القسم 4. يُحرّر التنظيف صفوفًا داخل SQLite لكنه لا يُصغّر حجم الملف نفسه. أضف DB_SQLITE_VACUUM_ON_STARTUP=true مرة واحدة وأعد إنشاء الحاوية لضغط الملف.

لمنع سجلات الحاويات من التضخم بلا حدود، أضف ما يلي إلى /etc/docker/daemon.json، ثم نفّذ sudo systemctl restart docker:

{ "log-driver": "json-file", "log-opts": { "max-size": "10m", "max-file": "3" } }

لا يُطبَّق حد السجلات إلا على الحاويات التي تُنشأ بعد التغيير، لذا نفّذ docker compose up -d --force-recreate بعد ذلك.

6. لماذا يعلق n8n في حلقة إعادة تشغيل بعد التحديث؟

نفّذ docker compose logs --tail=200 n8n وابحث عن أحد هذه الأسباب الثلاثة:

• رفض الصلاحيات (Permission denied) على /home/node/.n8n. يعمل n8n بمعرّف المستخدم 1000. إذا كنت تستخدم bind mount، فأصلح الملكية باستخدام sudo chown -R 1000:1000 ./n8n_data (استبدله بمجلدك).
• عدم تطابق مفاتيح التشفير. متغير البيئة N8N_ENCRYPTION_KEY لم يعد يطابق المفتاح المخزّن في مجلد البيانات. استعد المفتاح الأصلي (راجع قسم المشكلات الشائعة أدناه).
• خطأ في ترحيل قاعدة البيانات. استعد نسختك الاحتياطية وثبّت الإصدار السابق، مثل image: docker.n8n.io/n8nio/n8n:1.xx.x. ثم راجع ملاحظات الإصدار قبل الترقية مرة أخرى.

7. كيف أجمع السجلات لإرفاقها بتذكرة دعم؟

docker compose ps > n8n-report.txt
docker compose exec n8n n8n --version >> n8n-report.txt
docker compose logs --no-color --tail=500 n8n >> n8n-report.txt 2>&1
df -h >> n8n-report.txt; free -h >> n8n-report.txt

لمزيد من التفاصيل، اضبط N8N_LOG_LEVEL=debug مؤقتًا وأعد إحداث المشكلة. قبل إرفاق n8n-report.txt، احذف منه أي كلمات مرور أو مفاتيح API أو رموز وصول (tokens).

التحقق من نجاح الإصلاح

• يعرض docker compose ps حالة n8n على أنها Up وليس Restarting.
• يُرجع curl -s https://n8n.example.com/healthz القيمة {"status":"ok"}.
• يفتح المحرر عبر HTTPS دون ظهور تحذير الـ secure cookie.
• يستجيب سير عمل اختباري مُفعَّل يحتوي على عقدة Webhook لطلب curl خارجي، ويظهر التشغيل ضمن Executions.

المشكلات الشائعة

خطأ ECONNREFUSED عند الاتصال بخدمة محلية

داخل الحاوية، يشير localhost إلى حاوية n8n نفسها وليس إلى السيرفر. استخدم اسم خدمة Compose بدلًا منه، مثل http://postgres:5432. وللوصول إلى خدمة تعمل مباشرةً على السيرفر المضيف، أضف extra_hosts: ["host.docker.internal:host-gateway"] إلى خدمة n8n واستخدم http://host.docker.internal:PORT.

أخطاء DNS من نوع ENOTFOUND أو EAI_AGAIN في العقد

اختبر تحليل الأسماء من داخل الحاوية:

docker compose exec n8n node -e "require('dns').lookup('api.example.com',(e,a)=>console.log(e||a))"

إذا فشل الاستعلام داخل الحاوية لكنه نجح على السيرفر المضيف، فأضف dns: ["1.1.1.1", "8.8.8.8"] إلى خدمة n8n وأعد إنشاءها.

عقدة Schedule Trigger تعمل في ساعة خاطئة

اضبط كلًا من GENERIC_TIMEZONE=Africa/Cairo وTZ=Africa/Cairo (استخدم منطقتك الزمنية)، ثم أعد إنشاء الحاوية. وتحقق أيضًا من المنطقة الزمنية الخاصة بسير العمل نفسه ضمن Workflow settings، لأن هذا الإعداد يتجاوز الإعداد الافتراضي للسيرفر.

بيانات الاعتماد "could not be decrypted" بعد النقل إلى سيرفر آخر

يستخدم السيرفر الجديد مفتاح تشفير مختلفًا عن المفتاح الذي شُفّرت به بيانات الاعتماد. اقرأ المفتاح الأصلي على السيرفر القديم:

docker compose exec n8n cat /home/node/.n8n/config

اضبط القيمة نفسها في N8N_ENCRYPTION_KEY على السيرفر الجديد، ثم أعد إنشاء الحاوية. بدون المفتاح الأصلي، لا يمكن استعادة بيانات الاعتماد المخزّنة ويجب إدخالها من جديد.

تحتاج إلى مساعدة؟ افتح تذكرة دعم عبر https://cloudesta.com/submitticket.php وأرفق ملف n8n-report.txt. الطلبات التي لا يمكن تنفيذها إلا من جانب Cloudesta، مثل ترقية الخطط ووضع الإنقاذ (rescue mode) وإعادة تثبيت نظام التشغيل وتغيير عنوان IP، تتم أيضًا عبر التذاكر. تتوفر شروحات أخرى في مكتبة الشروحات.

الأسئلة الشائعة

أين أضبط متغيرات البيئة الخاصة بـ n8n؟

اضبطها في قسم environment: داخل docker-compose.yml أو في ملف .env الموجود بجانبه. بعد الحفظ، نفّذ docker compose up -d حتى تُعاد إنشاء الحاوية بالقيم الجديدة.

هل ضبط N8N_SECURE_COOKIE=false آمن؟

فقط للاختبارات القصيرة على شبكة خاصة. على السيرفر العام، استخدم HTTPS عبر reverse proxy بدلًا من ذلك.

هل يؤدي تنظيف سجل التنفيذ إلى حذف سير العمل الخاص بي؟

لا. التنظيف يحذف سجلات التنفيذ السابقة فقط، ولا يمسّ سير العمل أو بيانات الاعتماد.