Docker: استكشاف المشكلات الشائعة
حاوية تُعاد تشغيلها باستمرار، ومنفذ مستخدم، ولا مساحة متبقية، و«permission denied»، وخدمة لا ترى جارتها — جدول بالأعراض وإجراء لاستكشاف الأخطاء.
آخر تحديث 23 أغسطس 2026
تكاد مشكلات الحاويات كلها تعود إلى اثنتي عشرة مشكلة شائعة. تبدأ عملية التشخيص دائمًا بالأوامر الثلاثة نفسها.
الأوامر الثلاثة الأولى
docker compose ps
docker compose logs --tail 100 <service>
docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' <container>
تكفي الحالة وآخر أسطر السجل ورمز الخروج للإجابة عن معظم الأسئلة. بعد ذلك، انطلق من العَرَض.
جدول الأعراض
| العَرَض | السبب المحتمل | ما ينبغي فعله |
|---|---|---|
Restarting باستمرار | التطبيق ينهار عند بدء التشغيل | docker compose logs --tail 200، واقرأ الخطأ الأول لا الأخير |
رمز الخروج 137، OOMKilled: true | نفاد الذاكرة | ارفع الحد أو اعثر على التسريب، انظر حدود الموارد |
| رمز الخروج 1 فور بدء التشغيل | خطأ في الإعدادات أو المتغيرات | docker compose config — تحقق من الاستبدالات |
port is already allocated | المنفذ مشغول بعملية أخرى | sudo ss -tulpn | grep :<port> |
no space left on device | نفاد مساحة القرص أو الـ inodes | df -h وdf -i، انظر مساحة القرص |
permission denied على ملف في وحدة تخزين | عدم تطابق UID | docker compose exec app id، ثم chown أو PUID/PGID |
| التطبيق لا يرى قاعدة البيانات | شبكات مختلفة أو طلب إلى localhost | انظر شبكات Docker |
Cannot connect to the Docker daemon | الخدمة لا تعمل أو تنقصك الصلاحيات | sudo systemctl status docker، ومجموعة docker |
| كل شيء بطيء والحمل منخفض | عنق زجاجة في القرص | iostat -x 2، انظر سرعة القرص |
الحاوية تنهار، لكن السجل فارغ
يحدث هذا عندما تموت العملية قبل أن تطبع أي شيء. شغّل الصورة يدويًا مع صدفة بدلًا من الأمر الرئيسي:
docker run --rm -it --entrypoint sh <image>
بالداخل، شغّل أمر بدء التشغيل يدويًا — سيظهر الخطأ على الشاشة. وبينما أنت هناك، تحقق مما إذا كانت ملفات الإعدادات في مكانها:
docker compose run --rm app cat /app/config.yaml
التغييرات لا تُطبَّق
الحالة الكلاسيكية: تعدّل ملفًا، تعيد التشغيل، ولا يتغير شيء.
docker compose config # does Compose see your changes
docker compose up -d --force-recreate app
docker compose exec app cat /etc/app/config.yaml
ثمة سببان عادةً: الملف مُثبَّت في مكان غير الذي تظنه، أو أن الحاوية ترى نسخة دخلت الصورة أثناء البناء.
لا تعالج المشكلة بـ
docker system prune -a. فهو يحذف الصور والشبكات وذاكرة التخزين المؤقت للبناء غير المستخدمة، ومع الخيار--volumesيحذف وحدات التخزين التي تحتوي على بيانات أيضًا. تصبح وحدة التخزين «غير مستخدمة» بمجرد إيقاف حاويتها. اكتشف السبب أولًا، ثم نظّف.
متى تنظّف بعد كل ذلك
docker system df
docker image prune
docker builder prune
docker container prune
سيوضح docker system df ما الذي يستهلك المساحة بالضبط: الصور، أو ذاكرة التخزين المؤقت للبناء، أو وحدات التخزين، أو سجلات الحاويات. غالبًا تكون ذاكرة التخزين المؤقت للبناء هي السبب — وحذفها آمن.
إذا كانت الآلة لا تستجيب
لا يتصل SSH، ولا يفتح الموقع — عادةً تكون حاوية قد استهلكت الذاكرة ودخل النظام في swap. سجّل الدخول عبر الطرفية في لوحة الآلة. ولأجل htop وbtop تحتاج وضع «Screen»: لا يُمرَّر حجم النافذة عبر سطر نصي، لذا يكون دائمًا 80×24.
free -h
sudo dmesg -T | tail -40
sudo systemctl restart docker
إذا لم يُقلع النظام إطلاقًا، فبدّل وضع الإقلاع إلى قرص الاسترداد SystemRescue في تبويب «الوصول»: ستُعاد الآلة الإقلاع إليه، ودخول root دون كلمة مرور، وسيظهر القرص باسم /dev/sda. من هناك يمكنك تثبيت القسم واستعادة البيانات.
ما ينبغي التحقق منه قبل لا بعد
- حدود حجم السجلات مضبوطة — انظر سجلات الحاويات.
- حدود الذاكرة مضبوطة لجميع الخدمات.
- إصدارات الصور مثبَّتة، والصورة القديمة لم تُحذف — انظر تحديثات الحاويات.
- توجد نسخة من البيانات وتم التحقق منها — انظر تمرين الاستعادة.