كيفية تحديث n8n بأمان (Docker Compose)

لتحديث n8n بأمان باستخدام Docker Compose، خذ أولًا نسخة احتياطية من بيانات n8n وقاعدة البيانات، ثم اقرأ ملاحظات الإصدار وغيّر صورة n8n في docker-compose.yml إلى وسم (tag) إصدار جديد محدد. بعد ذلك نفّذ docker compose pull وdocker compose up -d، وتابع السجلات حتى تنتهي عمليات ترحيل قاعدة البيانات. احتفظ بالصورة السابقة حتى تتأكد من نجاح التحديث، لتتمكن من التراجع عن طريق استعادة النسخة الاحتياطية والعودة إلى الوسم القديم. ينطبق هذا الشرح على أي نسخة n8n مستضافة ذاتيًا تعمل عبر Docker Compose على Ubuntu 22.04 أو 24.04، بما في ذلك استضافة n8n من Cloudesta، حيث يأتي n8n مثبتًا مسبقًا داخل Docker على VPS سحابي.

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

• وصول SSH بصلاحيات root أو sudo إلى السيرفر الذي يعمل عليه n8n.
• تشغيل n8n عبر Docker Compose (إضافة docker compose، الإصدار v2).
• مساحة فارغة لا تقل عن 3 جيجابايت للصورة الجديدة والنسخ الاحتياطية. تحقق من ذلك باستخدام df -h /.
• فترة زمنية هادئة، إذ تتوقف عمليات التنفيذ الجارية أثناء إعادة تشغيل الحاوية.

1. لماذا يجب تحديث n8n، وكيف تقرأ ملاحظات الإصدار؟

يصدر n8n تحديثات متكررة. تجلب التحديثات إصلاحات أمنية وعُقدًا (nodes) جديدة وإصلاحات للتكاملات التي تغيّرت واجهات API الخاصة بها لدى الأطراف الخارجية. إذا تخطيت إصدارات كثيرة، تتراكم لديك تغييرات كثيرة دفعة واحدة، ما يجعل تتبّع المشكلات أصعب. قبل كل تحديث، اقرأ هذين المصدرين:

• ملاحظات الإصدار على docs.n8n.io/release-notes/ أو في صفحة الإصدارات الخاصة بـ n8n على GitHub.
• ملف التغييرات الجذرية (breaking changes) في مستودع n8n على المسار packages/cli/BREAKING-CHANGES.md. يسرد هذا الملف التغييرات التي تتطلب إجراءً منك، مثل متغيرات البيئة التي تغيّرت أسماؤها أو العُقد المحذوفة أو القيم الافتراضية الجديدة.

راجع كل إصدار يقع بين إصدارك الحالي والإصدار المستهدف، وليس الإصدار المستهدف وحده. القفزات بين الإصدارات الرئيسية (مثل الانتقال من 1.x إلى 2.x) تأتي في الغالب مع دليل ترحيل. اقرأ هذا الدليل كاملًا قبل أن تبدأ.

2. كيف آخذ نسخة احتياطية من n8n قبل التحديث؟

انتقل إلى المجلد الذي يحتوي على ملف Compose. إذا لم تكن متأكدًا من مكانه، فاسأل Docker:

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

استبدل n8n باسم الحاوية لديك إذا كان مختلفًا. بعد ذلك، خذ نسخة احتياطية من ملف Compose وملف البيئة. ثم أوقف n8n وأنشئ أرشيفًا لوحدة تخزين البيانات (volume) الخاصة به. تحتوي وحدة التخزين على قاعدة بيانات SQLite (إذا كنت تستخدم SQLite) وعلى ملف مفتاح التشفير.

cd /path/to/compose-dir
mkdir -p ~/n8n-backups
cp docker-compose.yml .env ~/n8n-backups/ 2>/dev/null
docker volume ls          # find the exact volume name, e.g. n8n_n8n_data
docker compose stop n8n
sudo docker run --rm -v n8n_n8n_data:/data -v ~/n8n-backups:/backup alpine \
  tar czf /backup/n8n_data-$(date +%F).tar.gz -C /data .

إذا كان n8n يستخدم PostgreSQL، فخذ أيضًا نسخة (dump) من قاعدة البيانات بينما لا تزال حاوية Postgres تعمل. عدّل أسماء الخدمة والمستخدم وقاعدة البيانات لتطابق ملفك.

docker compose exec -T postgres pg_dump -U n8n -d n8n > ~/n8n-backups/n8n-db-$(date +%F).sql

3. كيف أعرف إصدار n8n الذي أستخدمه؟

شغّل الحاوية مرة أخرى واطلب من n8n عرض إصداره:

docker compose start n8n
docker compose exec n8n n8n --version

دوّن هذا الرقم، فهو الإصدار الذي ستعود إليه عند التراجع.

4. هل أثبّت وسم إصدار محددًا أم أستخدم latest؟

ثبّت إصدارًا محددًا. مع latest، قد تنقلك أي عملية pull أو إعادة بناء بصمت إلى إصدار رئيسي جديد، ولن تتمكن من معرفة الإصدار الذي كنت تستخدمه من قبل. عدّل docker-compose.yml بحيث يحدد سطر الصورة إصدارًا دقيقًا:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:1.110.1   # example: use the version you chose
    restart: unless-stopped

إذا كنت تستخدم وضع الطابور (queue mode) مع خدمات worker أو webhook منفصلة، فاستخدم الوسم نفسه لكل خدمات n8n. اختلاف الإصدارات بين النسخة الرئيسية والـ workers يسبب أعطالًا.

5. كيف أسحب إصدار n8n الجديد وأشغّله؟

docker compose pull
docker compose up -d

يعيد up -d إنشاء الحاويات التي تغيّرت صورتها أو إعداداتها فقط، وتبقى وحدات التخزين والبيانات كما هي.

6. هل تعمل عمليات ترحيل قاعدة بيانات n8n تلقائيًا؟

نعم. عند التشغيل الأول، يحدّث الإصدار الجديد بنية (schema) قاعدة البيانات تلقائيًا. تابع السجلات أثناء ذلك:

docker compose logs -f --tail=100 n8n

قد تظهر لك الرسالة Migrations in progress, please do NOT stop the process. انتظر حتى يشير السجل إلى أن المحرر أصبح متاحًا. في قواعد البيانات الكبيرة قد يستغرق ذلك عدة دقائق. لا تُعِد تشغيل الحاوية أثناء الترحيل، لأن الترحيل المتقطع هو السبب الأكثر شيوعًا لتلف قاعدة بيانات n8n. اضغط Ctrl+C للتوقف عن متابعة السجلات، وهذا لا يوقف الحاوية.

7. كيف أحذف صور n8n القديمة؟

تشغل كل صورة من صور n8n عدة مئات من الميجابايت من المساحة. احتفظ بالصورة السابقة لبضعة أيام تحسبًا لحاجتك إلى التراجع، وبعد ذلك احذفها:

docker image ls docker.n8n.io/n8nio/n8n
docker image rm docker.n8n.io/n8nio/n8n:1.105.3   # the old tag
docker image prune -f                             # removes dangling layers
docker system df

8. كيف أعيد n8n إلى الإصدار السابق؟

بعد تنفيذ عمليات الترحيل، قد لا يعمل إصدار n8n الأقدم مع البنية الأحدث لقاعدة البيانات. الطريقة الموثوقة للتراجع هي استعادة النسخة الاحتياطية ثم تشغيل الوسم القديم:

docker compose stop n8n
# set image back to the old tag in docker-compose.yml, then restore data:
sudo docker run --rm -v n8n_n8n_data:/data -v ~/n8n-backups:/backup alpine \
  sh -c "rm -rf /data/* /data/.[!.]* ; tar xzf /backup/n8n_data-YYYY-MM-DD.tar.gz -C /data"
docker compose up -d

في حالة PostgreSQL، احذف قاعدة البيانات وأعد إنشاءها، ثم حمّل النسخة باستخدام psql قبل تشغيل n8n. يوفّر n8n أيضًا الأمر n8n db:revert الذي يتراجع عن عملية ترحيل واحدة في كل مرة، ويجب تشغيله بالإصدار الأحدث قبل تغيير الوسم. لكن استعادة النسخة الاحتياطية أبسط وأكثر أمانًا.

9. كيف أحدّث Ubuntu وDocker نفسه؟

يتم تحديث Docker Engine وإضافة Compose عبر apt مع نظام التشغيل:

sudo apt update && sudo apt upgrade -y
docker version && docker compose version
[ -f /var/run/reboot-required ] && echo "Reboot needed"

عند ترقية Docker، تُعاد تشغيل خدمة daemon. الحاويات المضبوطة على restart: unless-stopped أو always تعود للعمل تلقائيًا. نفّذ تحديثات نظام التشغيل وتحديثات n8n كلًّا على حدة، حتى تعرف أي تغيير تسبب في المشكلة إذا حدث عطل. أعد تشغيل السيرفر عند تحديث النواة (kernel). إذا لم يعد السيرفر للعمل بعد إعادة التشغيل، افتح تذكرة دعم، إذ تتولى Cloudesta وضع الإنقاذ (rescue mode) والوصول عبر الكونسول.

التحقق من نجاح التحديث

• يعرض docker compose ps حالة n8n على أنها Up وليس Restarting.
• يطبع docker compose exec n8n n8n --version الإصدار الجديد.
• يمكنك تسجيل الدخول إلى المحرر على https://n8n.example.com وتظهر مسارات العمل (workflows) وبيانات الاعتماد الخاصة بك.
• يمكنك فتح أحد مسارات العمل المهمة وتشغيله يدويًا، ويستجيب رابط URL لـ webhook تجريبي.
• خلال الساعة التالية، تُظهر قائمة Executions أن مسارات العمل المجدولة تعمل.

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

ظهور أخطاء في إحدى العُقد أو رسالة "unrecognized node type" بعد التحديث

تم تغيير اسم العقدة أو حذفها أو تعديلها. ابحث عن اسم العقدة في ملف التغييرات الجذرية. ثم افتح مسار العمل، واستبدل العقدة أو أعد إضافتها، وأعد ربط حقولها. بالنسبة لعُقد المجتمع (community nodes)، حدّثها من Settings → Community nodes لتكون متوافقة مع الإصدار الجديد.

توقف مسارات العمل عن العمل بعد إصدار رئيسي

تغيّر الإصدارات الرئيسية القيم الافتراضية ومتغيرات البيئة، وقد تعطّل بعض الميزات. راجع دليل الترحيل لمعرفة الإعدادات التي يجب إضافتها إلى .env. إذا تأثرت بيئة الإنتاج، فتراجع كما هو موضح في القسم 8. ثم اختبر الترقية أولًا على نسخة من بياناتك على VPS ثانٍ.

فشل عملية pull برسالة "no space left on device"

امتلأت المساحة بالصور القديمة وذاكرة البناء المؤقتة (build cache). نفّذ docker system df لمعرفة ما يستهلك المساحة. ثم احذف الصور غير المستخدمة باستخدام docker image prune -a. لا تنفّذ هذا الأمر طالما ما زلت بحاجة إلى الصورة القديمة للتراجع. احذف أيضًا أرشيفات النسخ الاحتياطية القديمة التي نسختها بالفعل خارج السيرفر. إذا احتجت إلى مساحة إضافية بشكل دائم، فاطلب ترقية الباقة عبر تذكرة دعم.

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

اعرف السبب باستخدام docker compose logs --tail=200 n8n. يعتمد الحل على الرسالة:

• Mismatching encryption keys: استعد قيمة N8N_ENCRYPTION_KEY الأصلية.
• EACCES على /home/node/.n8n مع استخدام bind mount: أصلح الملكية باستخدام sudo chown -R 1000:1000 ./n8n_data.
• خطأ في الترحيل: استعد النسخة الاحتياطية وتراجع إلى الإصدار السابق، ثم أبلغ n8n بالخطأ.

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

كم مرة يجب أن أحدّث n8n؟

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

هل يحذف تحديث n8n مسارات العمل أو بيانات الاعتماد؟

لا. فهي محفوظة في قاعدة البيانات ووحدة تخزين البيانات، ويحافظ عليهما docker compose up -d. ومع ذلك يجب أن تأخذ نسخة احتياطية أولًا، لأن فشل الترحيل قد يجعل البيانات غير قابلة للاستخدام.

هل يمكنني تخطي عدة إصدارات في تحديث واحد؟

نعم. تعمل عمليات الترحيل بالترتيب، لذا يمكنك القفز عدة إصدارات فرعية مرة واحدة. اقرأ التغييرات الجذرية لكل إصدار تتخطاه، واتبع دليل الترحيل الرسمي في حالة الإصدارات الرئيسية.

هل تحتاج إلى مساعدة؟ إذا فشل التحديث أو احتجت إلى مساعدة من جهة مزوّد الخدمة مثل وضع الإنقاذ أو مساحة إضافية، افتح تذكرة دعم على https://cloudesta.com/submitticket.php. أرفق إصدار n8n الحالي والإصدار المستهدف وآخر 50 سطرًا من docker compose logs n8n.