تثبيت n8n على VPS مع Docker: دليل شامل 2026

‏لماذا تستضيف n8n على VPS الخاص بك

‏تفرض النسخة السحابية من n8n رسومًا على كل عملية تنفيذ تتجاوز الخطة وتحدّ من عدد مسارات العمل النشطة. على VPS الخاص بك، التكلفة الوحيدة هي تكلفة الخادم، بصرف النظر عن عدد الأتمتات أو استدعاءات API. كما تحتفظ بالتحكم الكامل في بيانات الاعتماد وحمولات webhooks وتاريخ التنفيذ — لا تنتقل أي بيانات عبر بنية تحتية خارجية.

‏الفوائد الملموسة لـ n8n مُستضاف ذاتيًا

عمليات تنفيذ غير محدودة: دون سقف شهري ودون تكلفة على الحجم.
بيانات الاعتماد وحمولات webhooks محصورة في خادمك دون عبور خارجي.
‏الوصول إلى العقد المجتمعية وتنفيذ الكود المخصص دون قيود.
‏Webhooks على نطاقك الخاص، قابلة للإعداد لكل تكامل وارد.
‏تكلفة قابلة للتنبؤ: سعر VPS ثابت مستقل عن حجم الأتمتات.
استمرارية مُدارة لمسارات العمل والسجل في وحدات تخزين تأخذ منها نسخًا احتياطية.
‏توافق مع Ollama وFlowise وأي خدمة Docker أخرى على نفس الشبكة الداخلية.

المتطلبات بالأرقام

‏قبل البدء، تأكّد من أن VPS الخاص بك يستوفي المتطلبات التالية. للاستخدام المعتدل، 1 vCPU و1 GB من RAM كافيان؛ خطّط لـ 2 vCPU و2 GB حين تنفّذ مسارات عمل ثقيلة أو متزامنة، و4 GB إذا ربطت قاعدة بيانات PostgreSQL مخصّصة أو دمجت نموذج ذكاء اصطناعي محلي. خصّص 10 GB من القرص كحدٍّ أدنى لـ Docker والأحجام والسجلات. يجب ألا يكون المنفذ 5678 مكشوفًا مباشرةً — لا يستمع n8n إلا على 127.0.0.1:5678. يُلزم وجود نطاق فرعي (مثل n8n.your-domain.com) يشير إلى IP الـ VPS لـ HTTPS وwebhooks الواردة.

التثبيت خطوة بخطوة

‏تحديث VPS وتثبيت Docker

‏اتصل عبر SSH وحدّث الحزم: apt update && apt upgrade -y. ثم ثبّت Docker عبر السكريبت الرسمي: curl -fsSL https://get.docker.com | sh. تحقّق من التثبيت: docker --version && docker compose version. أنشئ مجلد العمل: mkdir -p /opt/n8n && cd /opt/n8n.

‏إنشاء ملف docker-compose.yaml

‏أنشئ docker-compose.yaml مع خدمة n8n، وحجم مسمّى للاستمرارية والمتغيّرات البيئية الأساسية. أعلن image: n8nio/n8n:latest، restart: unless-stopped، وارفق n8n_data:/home/node/.n8n. اكشف فقط على 127.0.0.1:5678:5678 لتجنّب أي كشف عام مباشر للمنفذ.

ضبط المتغيّرات البيئية الحرجة

‏في قسم environment للخدمة، أعلن على الأقل: N8N_HOST=n8n.your-domain.com، N8N_WEBHOOK_URL=https://n8n.your-domain.com/، N8N_PROXY_HOPS=1، N8N_BASIC_AUTH_ACTIVE=true، N8N_BASIC_AUTH_USER=<login> وN8N_BASIC_AUTH_PASSWORD=<كلمة-مرور-قوية>. للإنتاج، خزّن هذه القيم في ملف .env مجاور واستدعه عبر env_file: .env.

تشغيل الحاوية

‏نفّذ: docker compose up -d. تحقّق من تشغيل الحاوية: docker compose ps. راجع السجلات: docker compose logs -f n8n. يكون n8n جاهزًا حين تظهر السطر Editor is now accessible via: http://localhost:5678/ في السجلات.

‏إعداد الوكيل العكسي مع Caddy (موصى به)

‏Caddy هو أبسط وكيل عكسي لـ n8n: يتولّى شهادة Let's Encrypt والتجديد دون إعداد إضافي. ثبّت Caddy (apt install caddy) ثم حرّر /etc/caddy/Caddyfile لإضافة: n8n.your-domain.com { reverse_proxy localhost:5678 }. أعد التحميل: systemctl reload caddy. مع nginx، أضف في كتلة server: proxy_set_header X-Forwarded-Host $host; وproxy_set_header X-Forwarded-Proto $scheme; وproxy_set_header X-Real-IP $remote_addr;.

‏التحقق من الـ webhooks الواردة

‏في محرّر n8n، أنشئ سير عمل اختباريًا بعقدة Webhook. يجب أن يكون العنوان المعروض في وضع الإنتاج تمامًا https://n8n.your-domain.com/webhook/<مسارك>. شغّل الاستدعاء من جهازك المحلي: curl -X POST https://n8n.your-domain.com/webhook/test -d '{}'. إذا احتوى العنوان على localhost أو المنفذ 5678، فالمتغيّر N8N_WEBHOOK_URL غير مُطبَّق.

ربط PostgreSQL للإنتاج

‏SQLite مناسب للاختبار؛ في الإنتاج افضل PostgreSQL. أضف خدمة postgres:15 إلى نفس docker-compose.yaml مع حجم مخصّص pg_data. في خدمة n8n أضف: DB_TYPE=postgresdb، DB_POSTGRESDB_HOST=postgres، DB_POSTGRESDB_DATABASE=n8n، DB_POSTGRESDB_USER=n8n وDB_POSTGRESDB_PASSWORD=<كلمة-مرور>. أعد التشغيل بـ docker compose up -d.

‏التصليب ووضع queue

‏ثلاثة ردود فعل للإنتاج: (1) لا تكشف أبدًا المنفذ 5678 على الواجهة العامة — احتفظ بالربط 127.0.0.1:5678. (2) فعّل المصادقة: في v1.x، N8N_BASIC_AUTH_ACTIVE=true؛ في v1.27+، افضل المصادقة الأصلية عبر الواجهة (الإعدادات → الأمان). (3) لمسارات العمل الطويلة أو مسارات الذكاء الاصطناعي، انتقل إلى وضع queue مع نسخة worker منفصلة وطابور Redis.

‏عطل V8 الحرج مع أكثر من 30 مسار عمل نشط

‏الأعراض. تتوقف نسخة n8n فجأة برسالة الخطأ FATAL ERROR: invalid-mark-compact are transition في سجلات Docker. تعيد الحاوية تشغيلها إذا كان restart: unless-stopped مضبوطًا، لكن العطل يتكرر حين تتخطى الحمل نفس الحد. لا تظهر أي رسالة خطأ في الواجهة.

السبب. هذا الخطأ هو تعطّل محرك V8 (محرك JavaScript المدمج في Node.js) خلال دورة جمع البيانات المهملة. يحدث حين يمتلئ كومة ذاكرة V8 — عادةً عند 30 مسار عمل تعمل بالتزامن على VPS بأقل من 2 GB من الذاكرة المخصصة للعملية. لا يوجد استعادة تلقائية لهذه المشكلة.

الإصلاح الفوري. زد حد كومة V8 بإضافة متغيّر البيئة التالي في خدمة n8n في docker-compose.yaml: NODE_OPTIONS=--max-old-space-size=2048. هذا يخصص 2 GB لكومة V8. أعد تشغيل الحاوية: docker compose restart n8n.

الإصلاح الهيكلي. يجب أن يتوافق حد ذاكرة الحاوية مع حد V8. القاعدة: خصّص ما لا يقل عن 2 GB من الذاكرة للـ VM عند تجاوز 30 مسار عمل نشط، ومرّر NODE_OPTIONS=--max-old-space-size=1536. للمنشآت التي تضم أكثر من 50 مسار عمل، افضّل وضع queue (نسخة Redis worker منفصلة). ‏المصدر: community.n8n.io thread #308425.

‏خطأ 502 Bad Gateway المستمر خلف nginx

‏الأعراض. تنجح الطلبات القصيرة لكن بعض مسارات العمل ترجع 502 Bad Gateway من nginx — لا سيما المسارات التي تستدعي واجهات API خارجية بطيئة أو تعالج كميات كبيرة من البيانات. يحدث 502 بعد 60 ثانية بالضبط من بدء التنفيذ.

السبب. ينتظر nginx افتراضيًا 60 ثانية للحصول على رد من الخادم الخلفي قبل إغلاق الاتصال (proxy_read_timeout = 60 ث). إذا استغرق تنفيذ المسار أكثر من 60 ثانية، يقطع nginx الاتصال ويرجع 502. يستمر n8n في التنفيذ في الخلفية، لكن العميل لا يتلقى الرد أبدًا.

الإصلاح. أضف هذين التوجيهين في كتلة location بإعداد nginx التي توكّل إلى n8n:

proxy_read_timeout 300;
proxy_send_timeout 300;

‏قيمة 300 ثانية (5 دقائق) تغطي الغالبية العظمى من مسارات العمل الطويلة. أعد تحميل nginx: nginx -t && systemctl reload nginx.

التحقق. شغّل مسار عمل بطيئًا متعمدًا (عقدة Wait مضبوطة على 90 ث) وتحقق من وصول الرد بعد 60 ثانية دون خطأ. ‏المصدر: community.n8n.io thread #274581.

‏الانتقال من npm إلى Docker قبل n8n v3.0

‏إذا كانت نسختك تعمل عبر npx n8n أو npm install -g n8n، تصرّف قبل أكتوبر 2026. يتخلّى n8n v3.0 نهائيًا عن وضع npm/npx. تتمّ عملية الانتقال في أربع خطوات دون فقدان أي بيانات.

الخطوة 1 — تصدير مسارات عملك. في الواجهة، اذهب إلى الإعدادات → استيراد/تصدير أو: n8n export:workflow --all --output=workflows.json. صدّر أيضًا بيانات الاعتماد: n8n export:credentials --all --output=credentials.json.

الخطوة 2 — إيقاف نسخة npm. أوقف العملية (pm2 stop n8n أو systemctl stop n8n).

الخطوة 3 — نشر حاوية Docker باتباع الخطوات أعلاه. إذا نسخت ~/.n8n مباشرةً إلى الحجم، يُعيد n8n استخدام مسارات العمل وبيانات الاعتماد دون استيراد يدوي.

الخطوة 4 — الاستيراد والتحقق. استورد عبر: docker exec n8n n8n import:workflow --input=workflows.json. تحقّق من أن كل مسار عمل نشط يُشغَّل بشكل صحيح.

الموعد النهائي: أكتوبر 2026. نسخة npm لا تتلقى أي تحديثات بعد إصدار v3.0 — بما فيها تصحيحات الأمان.

‏التغييرات الكاسرة التي يجب معرفتها (v1.27–v1.31)

‏ثلاثة تغييرات في الإصدارات الأخيرة يمكن أن تكسر نسخة موجودة بصمت.

إعادة تسمية معامل OAuth 2.0 في HTTP Request. أُعيدت تسمية الحقل oauthTokenData في الإصدارات 1.27-1.31. قد تتوقف الطلبات المصادق عليها عبر OAuth 2.0 دون رسالة خطأ صريحة. تحقّق من كل مسار عمل يستخدم هذه العقدة بعد التحديث.

تنسيق عنوان URL لـ webhook. تغيّر تنسيق عنوان URL الذي تنشئه عقد Webhook. إذا نسخت عناوين URL بشكل ثابت في خدمات خارجية، أعد التحقق منها بعد التحديث.

إهمال $item(). وظيفة $item() محدّدة كمهملة. بديلها $input.item أو $('اسم العقدة').item. ستُزال في v3.0.

‏القائمة الكاملة متاحة على وثائق n8n الرسمية.

استكشاف الأخطاء الشائعة وإصلاحها

‏المنفذ 5678 غير متاح. تحقّق من تشغيل الحاوية (docker compose ps) ومن أنك تستمع على 127.0.0.1:5678.

تعرض الـ webhooks localhost بدلًا من النطاق. أضف N8N_WEBHOOK_URL=https://n8n.your-domain.com/ وأعد التشغيل: docker compose restart n8n.

N8N_PROXY_HOPS مفقود: خطأ 502 أو تكرار. أضف N8N_PROXY_HOPS=1 في بيئة الحاوية.

خطأ في أذونات الحجم. تعمل حاوية n8n تحت UID 1000: chown -R 1000:1000 /opt/n8n/data ثم docker compose restart n8n.

PostgreSQL يرفض الاتصال. تأكّد من أن خدمة postgres على نفس شبكة Docker وأن المتغيّرات تطابق تمامًا تلك المحدّدة في خدمة postgres.

‏عطل V8 الحرج (FATAL ERROR: invalid-mark-compact). كومة ذاكرة V8 ممتلئة: أكثر من 30 مسار متزامن مع ذاكرة غير كافية. أضف NODE_OPTIONS=--max-old-space-size=2048 وزد ذاكرة VPS إلى 2 GB كحد أدنى. راجع القسم المخصص أعلاه.

‏خطأ 502 Bad Gateway المستمر (60 ثانية بالضبط). proxy_read_timeout لـ nginx عند القيمة الافتراضية. ارفعه إلى 300 ثانية في كتلة location التي توكّل إلى n8n. راجع القسم المخصص أعلاه.

الصيانة والتوسع

‏للتحديثات، مقاربتان: Watchtower (مراقبة تلقائية للصورة وإعادة التشغيل) أو مهمة cron يدوية (docker pull n8nio/n8n:latest && docker compose up -d). في كلتا الحالتين، اقرأ ملاحظات الإصدار قبل أي تحديث رئيسي. احتفظ بتصديرات مسارات عملك محدّثة في مستودع git.