Docker Compose depends_on لا ينتظر؟ إليك الحل (2026)

إن depends_on العادية تنتظر فقط حتى يعمل الحاوية (container is running) الخاصة بالتبعية، وليس حتى تصبح الخدمة بداخلها جاهزة (ready) — لذا يتسابق تطبيقك مع قاعدة البيانات وينتهي الأمر بانهياره. الحل: استخدام الصيغة الطويلة مع condition: service_healthy بالإضافة إلى healthcheck حقيقي على التبعية.¹²

ملخص: depends_on: [db] يبدأ db قبل web ولكنه لا ينتظر حتى يبدأ Postgres في قبول الاستعلامات. انتقل إلى الصيغة الطويلة (depends_on: { db: { condition: service_healthy } }) وامنح db فحص حالة healthcheck مثل pg_isready. اضبط start_period بقيمة كافية حتى لا يتم اعتبار قاعدة البيانات التي تبدأ ببطء غير صحية في وقت مبكر جدًا. إذا رأيت dependency failed to start: container ... is unhealthy، فهذا يعني أن فحص حالة التبعية قد فشل أو أنه مفقود. يتم احترام depends_on بواسطة Docker compose up ولكن يتم تجاهلها بواسطة Docker stack deploy الخاصة بـ Swarm.

ما ستتعلمه

• لماذا لا ينتظر depends_on حتى تصبح خدمتك جاهزة
• الفرق بين service_started و service_healthy و service_completed_successfully
• كيفية إضافة healthcheck وربط عملية التشغيل بها (مع مثال عملي)
• لماذا تعلق الحاوية في حالة health: starting ولا تتقدم أبدًا
• ماذا يعني dependency failed to start: container is unhealthy وكيفية إصلاحه
• قيم interval و timeout و retries و start_period و start_interval التي يجب استخدامها
• ما إذا كان depends_on يعمل مع Docker compose run و Docker stack deploy
• متى تلجأ إلى استخدام wait-for-it.sh أو إعادة المحاولة على مستوى التطبيق بدلاً من ذلك

لماذا لا ينتظر Docker compose depends_on خدمتي؟

لأن "بدأت" لا تعني "جاهزة". التوثيق الرسمي لـ Docker صريح في ذلك: "عند التشغيل، لا ينتظر Compose حتى تصبح الحاوية 'جاهزة'، بل فقط حتى تبدأ في العمل."² مع الصيغة القصيرة، يقوم Compose بإنشاء التبعية أولاً ثم يبدأ الخدمة المعتمدة عليها فوراً — فهو لا ينتظر حتى تصبح التبعية صحية (healthy).¹

هذا التمييز مهم جداً للخدمات التي تحفظ الحالة (stateful services). حاوية Postgres تبلغ عن أنها "تعمل" في غضون أجزاء من الثانية، ولكن عملية قاعدة البيانات تحتاج إلى وقت إضافي قبل أن تقبل استعلامات SQL. يحاول تطبيقك الاتصال في هذه الفجوة الزمنية ثم ينهار. هذه الصيغة القصيرة هي الفخ:

services:
  web:
    build: .
    depends_on:
      - db     # only waits for the container to START, not to be READY
  db:
    image: postgres:18

يضمن Compose إنشاء db قبل web، وهذا كل شيء. وكما ورد في التوثيق: "مع الصيغة القصيرة، لا ينتظر Compose خدمات التبعية حتى تصبح 'صحية' قبل بدء الخدمة المعتمدة عليها."¹ لانتظار الجاهزية، تحتاج إلى الصيغة الطويلة بالإضافة إلى فحص الحالة (healthcheck).

ما الفرق بين service_started و service_healthy و service_completed_successfully؟

إنها القيم الثلاث لـ condition في صيغة depends_on الطويلة، وهي تحدد معنى "تم الاستيفاء" بالنسبة للتبعية:¹²

• service_started — حاوية التبعية قيد التشغيل. هذا يطابق الصيغة القصيرة: الترتيب فقط، دون التحقق من الجاهزية.
• service_healthy — أبلغ الـ healthcheck الخاص بالتبعية أنها سليمة (healthy). استخدم هذا لقواعد البيانات، والوسطاء (brokers)، والمخازن المؤقتة (caches) التي تحتاج وقتاً للإحماء.
• service_completed_successfully — انتهت التبعية من التشغيل وخرجت بالكود 0. استخدم هذا لمهام التهيئة أو الترحيل (migration) التي تُنفذ لمرة واحدة ويجب أن تنتهي قبل بدء التطبيق.

فقط service_healthy هو الذي ينتظر الجاهزية الفعلية، وهو يعمل فقط إذا كانت التبعية تحدد healthcheck. بدون ذلك، لا توجد حالة صحية لاستيفائها — وهذا هو السبب الأكثر شيوعاً لكون بوابات بدء التشغيل "لا تفعل شيئاً".¹

كيف أجعل depends_on ينتظر حتى تصبح الخدمة سليمة (healthy)؟

خطوتان: أضف healthcheck إلى التبعية، ثم أشر إليها باستخدام condition: service_healthy. هذا هو المثال الرسمي لـ Docker، حيث تنتظر خدمة web وصول db لحالة سليمة، وبدء تشغيل Redis:²

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
        restart: true
      redis:
        condition: service_started
  redis:
    image: redis
  db:
    image: postgres:18
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s

الآن ينتظر Compose نجاح الـ healthcheck الخاص بـ db قبل إنشاء web.² فحص pg_isready يعيد نتيجة "نجاح" فقط عندما يكون Postgres يقبل الاتصالات فعلياً، وبذلك يختفي سباق التشغيل. الرمز $$ يقوم بعمل escape للمتغير بحيث يمرر Compose قيمة $POSTGRES_USER إلى الشل (shell) داخل الحاوية بدلاً من معالجتها بنفسه.

الخيار الفرعي الاختياري restart: true (الذي تم تقديمه في Docker Compose 2.17.0) يعني أنه إذا تمت إعادة تشغيل db بواسطة عملية Compose صريحة مثل Docker compose restart، فسيتم إعادة تشغيل web أيضاً، ليعيد إنشاء اتصالاته.¹ وهناك خيار فرعي مرتبط، وهو required: false (Docker Compose 2.20.0)، والذي يخفض درجة التبعية المفقودة من "خطأ" إلى "تحذير".¹ كل هذا محدث حتى إصدار Docker Compose v5.3.1، الذي صدر في 7 يوليو 2026.³

لماذا تظل الحاوية الخاصة بي عالقة في حالة "health: starting"؟

تظل الحاوية في حالة health: starting حتى ينجح أول فحص صحي (healthcheck) أو حتى تنتهي فترة start_period وتبدأ الإخفاقات في الاحتساب. إذا لم تبدأ الخدمة التابعة أبداً وكانت التبعية عالقة في حالة "starting"، فإن الأسباب المعتادة هي:

• التبعية لا تحتوي على healthcheck على الإطلاق، ولكن هناك شيء يشير إليها باستخدام condition: service_healthy. بدون وجود فحص (probe)، لا يمكنها أبدًا الوصول إلى حالة healthy، لذا تظل البوابة في حالة انتظار — أو تفشل — إلى الأبد.¹
• أمر فحص الصحة (healthcheck command) خاطئ — الملف الثنائي (binary) غير موجود في الصورة، أو أن الاختبار لا يعيد أبدًا القيمة exit 0.
• start_period قصيرة جدًا، لذا فإن قاعدة البيانات التي تحتاج إلى 40 ثانية للتهيئة يتم تعليمها بأنها غير صحية (unhealthy) قبل أن تنتهي.

حالات الصحة في Docker هي starting، و healthy، و unhealthy، وتعتمد على كود الخروج الخاص بالفحص: 0 يعني صحي، و 1 يعني غير صحي. الإخفاقات التي تحدث خلال start_period لا تُحتسب ضمن حد إعادة المحاولة، والنجاح خلال تلك الفترة ينهي فترة السماح مبكرًا. تحقق من الحالة الحالية باستخدام Docker inspect --format '{{.State.Health.Status}}' <container> أو تابعها مباشرة عبر Docker compose ps.

ماذا يعني "dependency failed to start: container is unhealthy"؟

هذا يعني أن بوابة condition: service_healthy قد فشلت: استنفد فحص الصحة الخاص بالتبعية عدد retries (إعادة المحاولات) دون أن ينجح أبدًا (أو أن التبعية لا تحتوي على فحص صحة لتحقيق الشرط).⁴ يقوم Compose الحديث بالفشل سريعًا هنا بدلاً من التعليق إلى أجل غير مسمى. لإصلاح ذلك، تعامل مع التبعية نفسها:

1. تأكد من أن التبعية تحتوي فعليًا على healthcheck. إذا كانت مشار إليها بـ service_healthy ولكنها لا تحدد أي فحص، قم بإضافة واحد.
2. قم بتشغيل الفحص يدويًا داخل الحاوية: Docker compose exec db pg_isready -U postgres. إذا فشل هناك، فإن أمر الاختبار الخاص بك خاطئ.
3. ارفع قيمة start_period للخدمات التي تستغرق وقتًا في التشغيل. غالبًا ما تحتاج خدمة Postgres الباردة أو خدمة JVM إلى 60 ثانية أو أكثر قبل أول فحص ناجح.
4. خفف قيود retries/interval إذا كانت الخدمة صحية ولكنها غير مستقرة تحت الضغط أثناء التشغيل.

هذا الخطأ هو عرض لحالة صحة التبعية، وليس الخدمة المعتمدة عليها — قم دائمًا بتصحيح أخطاء الخدمة المذكورة في الرسالة.

ما هي قيم interval و retries و start_period التي يجب أن أستخدمها؟

ابدأ من القيم الافتراضية لـ HEALTHCHECK في Docker Engine وقم بضبطها من هناك. القيم الافتراضية هي interval 30s، و timeout 30s، و retries 3، و start_period 0s.⁵ القيمة الافتراضية لـ start_period التي تساوي صفرًا هي السبب في اعتبار قواعد البيانات غير صحية عند التشغيل البارد — قم بتعيينها دائمًا.

نقاط بداية منطقية حسب نوع الخدمة:

• قواعد البيانات (Postgres, MySQL): interval: 10s, timeout: 5s, retries: 5, start_period: 30s–60s.
• واجهات HTTP APIs: اختبار curl -f http://localhost:PORT/health, interval: 15s, timeout: 5s, retries: 3, start_period: 20s.
• خدمات JVM الثقيلة / خدمات الذاكرة المخبئية الباردة: ارفع start_period إلى 60s–120s.

هناك أيضًا start_interval، والتي تحدد عدد مرات تشغيل الفحص خلال start_period — بحيث يمكنك الفحص كل ثانية عند التشغيل ثم العودة إلى interval الأبطأ بمجرد أن تصبح الخدمة صحية. يتطلب ذلك Docker Compose 2.20.2+ و Docker Engine 25.0+:⁶

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 30s        # steady-state cadence
      timeout: 5s
      retries: 5
      start_period: 60s    # grace window; failures here don't count
      start_interval: 1s   # poll every 1s during the grace window

يفضل استخدام صيغة exec ["CMD", "bin", "arg"] عندما لا تحتاج إلى shell، وصيغة ["CMD-SHELL", "..."] عندما تحتاج إلى pipes أو متغيرات بيئة. استخدم test: ["NONE"] لتعطيل فحص الحالة (healthcheck) الذي ورثته الصورة من صورتها الأساسية.⁵

هل يعمل depends_on مع Docker compose run و Docker stack deploy؟

ليس في كل مكان. depends_on هي ميزة تنسيق خاصة بـ Compose، وهناك سياقان لا يلتزمان بها بنفس الطريقة التي يفعلها Docker compose up:

• Docker stack deploy (وضع Swarm) يتجاهل depends_on تماماً — دون أي تحذير. لا يمتلك Swarm مفهوماً لبدء التشغيل المرتب، لذا يتم إسقاط التبعيات المعلنة بصمت.⁷ في Swarm، يجب عليك جعل الخدمات مرنة تجاه التبعيات المفقودة بدلاً من ذلك.
• Docker compose run <service> يبدأ خدمات depends_on ولكن لا ينتظر تقارير فحص الحالة لتكون سليمة (healthy)، بينما يقوم --no-deps بتخطي بدء تشغيلها تماماً.⁸

كما أن depends_on تقوم بترتيب الخدمات داخل مشروع Compose واحد فقط — ولا يمكنها ترتيب الحاويات التي تشغلها بأوامر Docker run منفصلة أو في مشروع آخر.

مقارنة بين depends_on و wait-for-it.sh وإعادة المحاولة على مستوى التطبيق (app-level retries)

الثلاثة يحلون مشكلة "انتظار الجاهزية"، ولكن في طبقات مختلفة:

• depends_on + service_healthy هو الخيار التصريحي المدمج. وهو الخيار الافتراضي الصحيح لأن فحص الجاهزية يكون مرتبطاً بالتبعية وكل تابع يرثه.²
• سكربتات التغليف (Wrapper scripts) مثل wait-for-it.sh، أو wait-for، أو dockerize تقوم بالتوقف عند منفذ TCP مفتوح قبل تشغيل تطبيقك. هي بسيطة، ولكن فتح المنفذ أضعف من فحص الحالة الحقيقي: فمثلاً Postgres يقبل اتصالات TCP قبل أن يقبل الاستعلامات، لذا قد ينجح فحص المنفذ في وقت مبكر جداً.
• إعادة المحاولة على مستوى التطبيق (Application-level retries) هي الطبقة الأكثر متانة. إرشادات Docker طويلة الأمد هي جعل التطبيق مرناً — إعادة الاتصال مع تراجع تدريجي (backoff) — لأن ترتيب بدء التشغيل وحده لا يمكنه ضمان الجاهزية عند إعادة التشغيل في منتصف العمل. استخدام قاطع دائرة (circuit breaker) أو غلاف إعادة محاولة ضروري في بيئة الإنتاج بغض النظر عن إعدادات Compose الخاصة بك.

أفضل الممارسات في 2026: استخدم service_healthy لبدء تشغيل نظيف محلياً وفي بيئة CI، ولا تزال بحاجة لإضافة منطق إعادة المحاولة في التطبيق حتى لا يتوقف service عند حدوث failover لقاعدة البيانات في الساعة 3 فجراً.

الخلاصة

إن depends_on بمفردها تقوم فقط بترتيب بدء تشغيل الحاويات — وهي لا تنتظر أبداً الجاهزية. انتقل إلى الصيغة الطويلة، واعتمد على condition: service_healthy، وامنح كل تبعية ذات حالة (stateful) فحص صحة healthcheck حقيقي مع start_period سخي، وحافظ على منطق إعادة المحاولة (retry logic) داخل التطبيق للحالات التي لا يستطيع Compose تغطيتها. إذا كنت تقوم بربط هذا في بيئة إنتاج، فادمجها مع إعداد Docker Compose HTTPS محصن، وتعامل مع فحوصات الصحة بنفس الطريقة التي تتعامل بها مع فحوصات الجاهزية في Kubernetes عند النشر بدون توقف. وبالنسبة لتبعيات قواعد البيانات تحديداً، فإن وجود طبقة تجميع اتصالات (connection-pooling layer) مرنة لا يقل أهمية عن ترتيب بدء التشغيل.