لماذا يكسر Docker v29 المكدسات الحالية — ولماذا الآن
تقع وكالة تُدير أسطول VPS لعملائها في موقف صعب: التحديث الخارجي (Docker أو Ubuntu أو Debian) يصل من الخارج بصرف النظر عمّن يُدير الخادم. حين يتلقّى VPS العميل apt upgrade دون رقابة، تصل ثلاثة تغييرات كاسرة في آنٍ واحد.
الكسر الأول — الحد الأدنى لإصدار API. يرفع Docker Engine v29 الحد الأدنى لإصدار API إلى 1.44. تفشل العملاء التي تعمل بالنسخة المستقلة القديمة docker-compose v1 (الملف /usr/local/bin/docker-compose) فوراً: تعليماتها البرمجية مُترجَمة لإصدارات API أقدم، ويرفض daemon الاتصال برسالة عدم توافق.
الكسر الثاني — خلفية شبكة nftables. يُفعّل Docker v29 nftables افتراضياً عوضاً عن iptables لإدارة قواعد جدار حماية شبكات Docker. لا ترى النصوص البرمجية الخارجية التي تفحص سلاسل iptables مباشرةً (نصوص المراقبة، وجدران الحماية المُخصّصة، وبعض قواعد UFW) قواعد Docker بعد الآن — ليس لأنها اختفت، بل لأنها تعيش الآن في nftables.
الكسر الثالث — مخزن صور containerd. ينتقل خلفية تخزين الصور إلى مخزن containerd. وهو قيد التفعيل الاختياري منذ v29، وسيصبح الافتراضي في v30.
الاعتراض الكلاسيكي — «عملاؤنا يُديرون VPS بأنفسهم» — لا يوفر حمايةً. يأتي الكسر من الخارج، والوكالة هي من يتصل بها العميل حين يتوقف موقعه.
ما يُمكّنك هذا الدليل من فعله
- اكتشاف التوتر في إصدار API بين عميل
dockerالخاص بك وdaemon VPS، قبل أن تُنتج الأوامر التالية خطأً غامضاً. - تحديد في 30 ثانية ما إذا كان VPS يعمل بـ
docker-composev1 المستقل — الملف الثنائي المُهمَل منذ Docker Desktop 3.6 والمُزال من الحزم الرسمية. - الهجرة إلى إضافة
docker composev2 بأمرَين محدَّدَين، ثم التحقق من عمل ملفاتdocker-compose.ymlالحالية دون تغيير في البنية. - فهم تأثير nftables على مكدّساتك: ما يستمر في العمل (شبكات Docker)، وما قد يتعطّل (نصوصك التي تقرأ iptables)، وأمر التشخيص الحاسم.
- تفعيل أو تأجيل مخزن containerd وفق جدول هجرتك، مع مفتاح الإعداد الدقيق وأمر التحقق.
- تقييم توافق Dockge وPortainer وCasaOS App Store مع v29، لتجنّب اكتشاف عدم التوافق أثناء حادثة لدى العميل.
- تجهيز أسطول VPS العملاء كي يكون
apt upgradeالتالي حدثاً مُخطَّطاً، لا طارئاً ليليّاً.
المتطلبات قبل البدء
يُطبَّق هذا الدليل على أي VPS يعمل بـ Ubuntu 22.04/24.04 أو Debian 11/12 مع تثبيت Docker Engine من المستودعات الرسمية لـ Docker Inc. (وليس حزمة docker.io التابعة للتوزيعة). تحتاج إلى وصول SSH كمستخدم root أو sudo. لا يتطلب تشخيص المشكلات أي انقطاع في الخدمة؛ أما نقل إضافة compose فيستغرق ثوانٍ خلالها تكون أوامر docker compose غير متاحة. التقط لقطة VPS قبل تعديل /etc/docker/daemon.json إذا كنت ستُفعّل مخزن containerd.
الخطوة 1 — تشخيص إصدار API
التحقق من إصداري API للعميل وdaemon
شغّل الأمرَين التاليَين على كل VPS تريد فحصه:
docker version --format '{{.Client.APIVersion}}'
docker version --format '{{.Server.APIVersion}}'إذا كان إصدار العميل أقل من 1.44 وكان daemon يعمل بـ v29، ستحصل على خطأ عند الأوامر التالية. العتبة 1.44 هي الحد الأدنى الذي يقبله Docker Engine v29: يفشل عميل مُترجَم لـ 1.43 أو أقدم بالخطأ Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44, please upgrade your client.
إذا أظهر السطران 1.44 أو أعلى، فعميلك متوافق. انتقل إلى الخطوة التالية.
الكشف عن وجود docker-compose v1 المستقل
أمر docker-compose بالشَرطة وأمر docker compose بدون شَرطة ليسا الشيء ذاته. v1 ملف ثنائي Python مستقل، أما v2 فإضافة Go مُدمَجة في واجهة Docker.
which docker-compose && docker-compose --versionإذا أعاد الأمر مساراً في /usr/local/bin/ أو /usr/bin/ مع إصدار 1.x.x، لديك الملف الثنائي المستقل المُهمَل.
docker compose versionإذا أعاد هذا الأمر Docker Compose version v2.x.x، فإضافة v2 موجودة بالفعل.
الخطوة 2 — الهجرة من docker-compose v1 إلى إضافة v2
إزالة الملف الثنائي v1 وتثبيت الإضافة
apt remove docker-compose
apt install docker-compose-pluginعلى VPS يعمل بـ Debian أو Ubuntu ويستخدم المستودعات الرسمية لـ Docker Inc. (download.docker.com)، تتوفر حزمة docker-compose-plugin بدون إعداد إضافي.
للتحقق بعد الهجرة:
docker compose version
# Docker Compose version v2.36.0التحقق من توافق بنية ملفات Compose الحالية
الغالبية العظمى من ملفات docker-compose.yml المكتوبة لـ v1 تعمل دون تعديل مع إضافة v2. التحقق من ملفاتك:
docker compose configيُحلّ هذا الأمر متغيرات البيئة ويُتحقق من البنية ويعرض الإعداد المُحلَّل. إخراج بلا أخطاء يعني أن ملفك متوافق.
إذا كانت فريقك يستخدم نصوص shell تحتوي docker-compose بالشَرطة، أضف اختصاراً في /etc/bash.bashrc على VPS:
alias docker-compose='docker compose'الخطوة 3 — فهم تغيير خلفية الشبكة nftables والتكيّف معه
التحقق من أن شبكات Docker لا تزال تعمل
البشرى السارة: docker network يعمل بشكل صحيح مع nftables. يستمر مرور حركة البيانات بين الحاويات، وترجمة عناوين الشبكة (NAT)، وكشف المنافذ في العمل. ما يتغيّر هو الأداة الأساسية التي تكتب القواعد.
docker network lsشبكات bridge الحالية لا تزال مُدرَجة. للتحقق من أن حاوية تستقبل حركة البيانات على المنفذ المتوقع:
curl -s http://localhost:8080/healthتشخيص التأثير على نصوص iptables البرمجية
تظهر المشكلة حين يفحص نص برمجي خارجي (مراقبة، أو Ansible، أو قواعد UFW) iptables للتحقق من وجود قواعد Docker:
iptables -L DOCKER 2>&1مع خلفية nftables، هذه السلسلة فارغة أو غائبة. يُعيد النص خطأً بينما Docker يعمل بشكل مثالي. هذا ليس فشلاً في Docker — أداة التدقيق لم تعد تنظر في المكان الصحيح.
لفحص القواعد الفعلية:
nft list ruleset | grep -A 20 'docker'الخطوة 4 — تقييم مخزن صور containerd وتفعيله
التحقق من برنامج تشغيل التخزين الحالي
docker info | grep 'Storage Driver'على VPS مُحدَّث إلى v29 بدون تغييرات في الإعداد، تحصل عادةً على Storage Driver: overlay2. مخزن containerd اختياري في v29 — لا يُفعَّل تلقائياً. سيصبح الافتراضي في v30.
تفعيل مخزن containerd (اختياري، يُنصح به قبل v30)
لتفعيل مخزن containerd في v29 والاستعداد للهجرة قبل فرضها في v30، أضف المفتاح التالي إلى /etc/docker/daemon.json:
{
"features": {
"containerd-snapshotter": true
}
}أعد تشغيل daemon:
systemctl restart dockerللتحقق:
docker info | grep 'Storage Driver'
# Storage Driver: overlayfsتوافق الأدوات الخارجية مع Docker Engine v29
| الأداة | حالة التوافق مع v29 | الإجراء الموصى به |
|---|---|---|
| **Dockge** (حتى 1.4.1 مشمولاً) | غير متوافق: يستدعي daemon الخاص بـ Dockge مسارات API مُزالة في v29. لا يبدأ اللوحة بعد تحديث Docker. | تحديث Dockge إلى الإصدار 1.4.2 أو أعلى. التحقق من ملاحظات الإصدار قبل `apt upgrade` على أي VPS يستضيفه. |
| **Portainer** (Community Edition < 2.21) | متوافق جزئياً: الواجهة تعمل، لكن بيئات Docker المستقلة قد تُظهر أخطاءً في عروض الشبكة. الإصدار 2.21 يُصلح استدعاءات nftables. | تحديث Portainer عبر `docker pull portainer/portainer-ce:latest` ثم `docker compose up -d` قبل ترقية Docker Engine. |
| **CasaOS App Store** | توافق جزئي موثَّق: التطبيقات المُنشَرة تستمر في العمل، لكن مدير التطبيقات قد يُبلّغ عن أخطاء عند فحص الصور إذا كان مخزن containerd مُفعَّلاً. | إبقاء مخزن containerd في وضع الإيقاف (افتراضي v29) على VPS التي تعمل بـ CasaOS حتى صدور إصدار تصحيحي. الاختبار على بيئة نسخة قبل أي تحديث. |
اختبر الهجرة على لقطة قبل لمس بيئة الإنتاج
يتيح لك VPS بصلاحية root ولقطات فورية التحقق من كل خطوة في هذه الهجرة دون مخاطرة. أنشئ لقطة باسم before-docker-v29، نفّذ الهجرة الكاملة، تحقق من مكدّساتك، ثم احذف اللقطة. إذا حدث خطأ في الطريق، يُعيد الاستعادة VPS إلى حالته الأولية في أقل من خمس دقائق.
استكشاف الأخطاء — أخطاء حقيقية وحلول
تُغطّي السيناريوهات التالية غالبية الحوادث المُلاحَظة خلال هجرات Docker v29 على أساطيل VPS.
سيناريوهات الأخطاء الشائعة
الخطأ: `client version X.XX is too old. Minimum supported API version is 1.44`
السبب: الملف الثنائي المستقل docker-compose v1 لا يزال موجوداً ويحاول التواصل مع daemon الإصدار v29.
الحل:
apt remove docker-compose
apt install docker-compose-plugin
docker compose versionإذا كان الملف الثنائي مُثبَّتاً يدوياً (خارج apt)، ابحث عنه:
which docker-compose
rm /usr/local/bin/docker-composeالخطأ: `docker-compose: command not found` بعد `apt upgrade`
السبب: تمت إزالة حزمة docker-compose (v1) أثناء التحديث، ولم تُثبَّت إضافة v2.
الحل:
apt install docker-compose-pluginالخطأ: `iptables: No chain/target/match by that name` في نص مراقبة
السبب: نصك البرمجي يفحص سلسلة DOCKER في iptables، لكن Docker v29 مع nftables لا يكتبها هناك بعد الآن.
الحل: استبدل فحص iptables بفحص nftables:
nft list ruleset | grep -c 'docker'إذا كان العدد أكبر من صفر، فقواعد Docker موجودة في nftables.
Dockge لا يبدأ بعد التحديث
السبب: Dockge 1.4.1 وما قبله يستدعي مسارات API غائبة من Docker Engine v29.
الحل:
cd /opt/dockge
docker compose pull
docker compose up -dالحاويات لا تستجيب على منافذها بعد إعادة تشغيل daemon
السبب: عند أول إعادة تشغيل لـ dockerd في وضع nftables، تُعاد كتابة قواعد NAT في الخلفية الصحيحة، لكن بعض التوزيعات تعاني تعارضاً بين خدمة iptables-legacy وnftables.
الحل:
systemctl stop docker
systemctl disable iptables
systemctl start dockerثم تحقق من إعادة تشغيل الحاويات وكشف المنافذ:
docker compose up -d
docker ps --format 'table {{.Names}}\t{{.Ports}}'تجهيز أسطولك لتجنّب الحادثة التالية
هجرة Docker v29 المُدارة جيداً ليست حدثاً منفرداً — بل فرصة لوضع الممارسات التي تمنع الطارئ الليلي التالي.
أوقف تحديث Docker تلقائياً في apt. على VPS العملاء، امنع Docker من التحديث أثناء apt upgrade غير المُشرَف عليها:
apt-mark hold docker-ce docker-ce-cli containerd.ioأزل الإيقاف (apt-mark unhold) فقط حين تكون مستعداً للهجرة، بعد الاختبار على لقطة.
أتمتة تدقيق الأسطول. يستغرق playbook Ansible الذي يتحقق من إصدار API على كل VPS أقل من ساعة لكتابته.
