depends_on، وأبقِ منطق إعادة المحاولة في التطبيق مع ذلك.","html":"كل إقلاع بارد لبيئة notes-api كانت له الدقيقة الأولى المتقلّبة نفسها: يبدأ الـ API، ويحاول الاتصال بـ Postgres، فيحصل على ECONNREFUSED، وينهار. السطر depends_on: [db] في الملف بدا وكأنه كان يجب أن يمنع ذلك. لم يمنعه، لأن «بدأ» و«جاهز» شيئان مختلفان، وCompose لم يكن يعرف إلا الأول.
الصيغة المختصرة تقول: شغّل db قبل api.
services:\n api:\n depends_on:\n - dbيفعل Compose ذلك بالضبط: يشغّل container الـ db ثم container الـ api، بفارق ثانية تقريبًا. لكن Postgres يحتاج إلى عدّة ثوانٍ بعد بدء عمليته ليتهيّأ، وأكثر في التشغيل الأول حين ينشئ قاعدة البيانات ويشغّل سكربتات التهيئة. يتّصل الـ API خلال تلك النافذة فيُرفض.
لكي ينتظر Compose الجاهزية، يحتاج إلى طريقة لاختبارها. وهذا هو الـ healthcheck (فحص الصحة).
\nالـ healthcheck أمر يشغّله Docker داخل الـ container وفق جدول زمني. رمز الخروج 0 يعني سليم؛ وأي رمز آخر يُعدّ فشلًا.
\n db:\n image: postgres:17\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notes\n volumes:\n - pgdata:/var/lib/postgresql/data\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U notes -d notes\"]\n interval: 10s\n timeout: 3s\n retries: 5\n start_period: 30s\n start_interval: 1sيأتي pg_isready مع image Postgres ويخرج بالرمز 0 حالما يقبل الخادم الاتصالات. حقول التوقيت:
interval: كم مرة يُشغَّل الفحص بعد أن يعمل الـ container بشكل طبيعي.timeout: المدة التي قد يستغرقها فحص واحد قبل أن يُعدّ فاشلًا.retries: عدد الإخفاقات المتتالية قبل أن يُعلَّم الـ container بأنه unhealthy.start_period: مهلة سماح بعد البدء لا تُحتسب خلالها الإخفاقات ضمن retries.start_interval: كم مرة يُفحص خلال مهلة البدء، حتى يُكتشف البدء السريع بسرعة بدلًا من انتظار interval كامل.يعرض docker compose ps الآن (healthy) أو (unhealthy) بجوار الحالة. وحين يفشل فحص وتريد معرفة السبب، تُحفظ آخر بضع نتائج، مع مخرجاتها، على الـ container:
docker inspect notes-db-1 --format '{{json .State.Health}}'هناك شيء لا تفعله الـ healthchecks في Docker أو Compose العاديين: إنها لا تعيد تشغيل الـ container غير السليم. الحالة معلومة فقط، تستخدمها شروط depends_on وتستخدمها أنت. Kubernetes مختلف، كما سترى مع الـ liveness probes في القسم الخامس، حيث يؤدّي الفحص الفاشل فعلًا إلى إعادة التشغيل. معرفة أي أداة تتصرّف عند فشل الفحص وأيها تكتفي بالإبلاغ عنه أمر مهمّ في الثالثة فجرًا.
الصيغة الطويلة لـ depends_on تتيح لك تحديد ما تنتظره:
services:\n migrate:\n image: notes-api:dev\n command: [\"node\", \"dist/migrate.js\"]\n environment:\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n depends_on:\n db:\n condition: service_healthy\n\n api:\n build: .\n image: notes-api:dev\n ports:\n - \"8080:3000\"\n environment:\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n depends_on:\n db:\n condition: service_healthy\n restart: true\n migrate:\n condition: service_completed_successfullyهناك ثلاثة شروط: service_started (سلوك الصيغة المختصرة)، وservice_healthy، وservice_completed_successfully الذي ينتظر container يُنفَّذ مرة واحدة حتى يخرج بالرمز 0. هنا تعمل الـ migration حالما يصبح Postgres سليمًا، ولا يبدأ الـ API إلا بعد نجاح الـ migration. إذا فشلت الـ migration فلن يبدأ api أبدًا، وسترى السبب في docker compose logs migrate. أما restart: true فيعني أن Compose إذا أعاد تشغيل db (مثلًا بعد تغيير إعداداته)، فسيعيد تشغيل api أيضًا.
الـ API يستحق healthcheck هو الآخر. قد تكون image التشغيل من نوع distroless بلا curl، لكنها تحتوي دائمًا على Node، وNode 24 فيه fetch مدمجة. على node:24-slim يكون node ضمن الـ PATH؛ أما على distroless فاستدعِه بمساره الكامل /nodejs/bin/node:
healthcheck:\n test: [\"CMD\", \"node\", \"-e\", \"fetch('http://localhost:3000/healthz').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))\"]\n interval: 10s\n timeout: 3s\n retries: 3في الـ CI، الأمر docker compose up -d --wait لا يعود إلا حين تصبح كل خدمة لها healthcheck سليمة، ويفشل إن صارت إحداها غير سليمة. هذه هي الطريقة الصحيحة لتشغيل البيئة قبل اختبارات التكامل، بدلًا من sleep 15.
كل هذا يغطّي التشغيل الأول. لا شيء يمنع Postgres من إعادة التشغيل في الثالثة عصرًا من يوم ثلاثاء، وحين تنتقل إلى Kubernetes في القسم الرابع، لن تجد depends_on أصلًا: تبدأ الـ Pods بأي ترتيب تُجدوَل به. لذا يتّصل notes-api مع إعادة محاولة وbackoff، ويُبلغ «غير جاهز» على /readyz حتى تجيب قاعدة البيانات. الـ healthchecks والشروط تجعل الإقلاع المعتاد سريعًا؛ وإعادة المحاولة تجعل التطبيق يصمد حين تسوء الأمور.
البيئة الآن تقلع بالترتيب الصحيح في كل مرة. درس Compose الأخير يرتّب الإعدادات ويعطيك حلقة سريعة للتعديل وإعادة التحميل.
\n","toc":[{"id":"sec-1","text":"ما الذي ينتظره depends_on فعلًا","level":2},{"id":"sec-2","text":"الـ Healthchecks","level":2},{"id":"sec-3","text":"الانتظار على شروط","level":2},{"id":"sec-4","text":"إعادة المحاولة مكانها التطبيق مع ذلك","level":2}],"takeaways":["الصيغة المختصرة لـdepends_on لا تنتظر إلا بدء container الاعتمادية، لا جاهزيته للخدمة.","الـ healthcheck يخبر Docker كيف يختبر الـ container؛ والشرط condition: service_healthy يجعل الخدمة المعتمِدة تنتظر نجاح ذلك الاختبار.","الشرط condition: service_completed_successfully يشغّل المهام التي تُنفَّذ مرة واحدة، مثل الـ migrations، قبل بدء التطبيق.","في صيغة exec يكون كل معامل عنصرًا مستقلًا في القائمة؛ واستخدم CMD-SHELL حين يكون الاختبار نصّ أمر shell واحدًا.","ترتيب الإقلاع لا يغطّي إلا التشغيل الأول، لذا يجب أن يعيد التطبيق محاولة الاتصال بقاعدة البيانات؛ وKubernetes ليس فيه depends_on أصلًا."],"further":[{"title":"Control startup order in Compose","url":"https://docs.docker.com/compose/how-tos/startup-order/"},{"title":"Compose services reference (healthcheck)","url":"https://docs.docker.com/reference/compose-file/services/#healthcheck"},{"title":"docker compose up","url":"https://docs.docker.com/reference/cli/docker/compose/up/"}],"quiz":[{"q":"الخدمة api فيها depends_on: [db] بالصيغة المختصرة. عند الإقلاع البارد يكتب الـ API في سجلّه ECONNREFUSED مرة واحدة، ثم يعمل. لماذا؟
db تبدأ أولًا فعلًا. لكن البدء ليس هو الجاهزية."},{"text":"الصيغة المختصرة تنتظر بدء container الـ db، لا قبول Postgres للاتصالات.","why":"صحيح. يحتاج Postgres إلى بضع ثوانٍ للتهيئة. أضف healthcheck والشرط condition: service_healthy."},{"text":"كلمة مرور قاعدة البيانات خاطئة في المحاولة الأولى.","why":"كلمة المرور الخاطئة تعطي خطأ مصادقة، لا اتصالًا مرفوضًا، ولن تُصلح نفسها."}],"answer":2},{"q":"أي healthcheck يختبر جاهزية Postgres بشكل صحيح في خدمة db؟
test: ["CMD-SHELL", "pg_isready -U notes -d notes"]","why":"صحيح. CMD-SHELL يشغّل النصّ عبر shell الـ container، وpg_isready يخرج بالرمز 0 حالما يقبل الخادم الاتصالات."},{"text":"test: ["CMD", "pg_isready -U notes -d notes"]","why":"صيغة exec تعامل النصّ كاملًا كاسم للبرنامج، فيبحث Docker عن ملف تنفيذي اسمه حرفيًا pg_isready -U notes -d notes ويفشل الفحص دائمًا."},{"text":"test: ["CMD", "curl", "-f", "http://localhost:5432"]","why":"لا يتحدّث Postgres بـ HTTP، وimage Postgres لا تشحن curl."},{"text":"test: ["CMD", "ping", "-c", "1", "db"]","why":"الـ ping يثبت أن الشبكة تعمل، لا أن Postgres يقبل الاستعلامات."}],"answer":0},{"q":"خدمة migrate تطبّق تغييرات المخطّط ثم تخرج. كيف يجب أن تعتمد api عليها؟
condition: service_healthy","why":"المهمة التي تخرج لا تصبح سليمة أبدًا، فستنتظر api حالة لا تأتي أبدًا."},{"text":"condition: service_completed_successfully","why":"صحيح. ينتظر Compose أن تخرج migrate بالرمز 0، ويرفض تشغيل api إن فشلت."},{"text":"condition: service_started","why":"هذا لا ينتظر إلا بداية الـ migration، فقد يبدأ الـ API على مخطّط نصف مُرحَّل."},{"text":"restart: always على migrate","why":"هذا يعيد تشغيل المهمة إلى الأبد بعد انتهائها؛ ولا يرتّب أي شيء."}],"answer":1},{"q":"بيئتك تستخدم healthchecks وservice_healthy. لماذا يجب أن يعيد notes-api محاولة الاتصالات الفاشلة بقاعدة البيانات مع ذلك؟
docker compose build.","why":"إنها تعمل باستمرار ما دام الـ container يعمل، بالفاصل الزمني المضبوط."},{"text":"لأن إعادة المحاولة شرط لنجاح pg_isready.","why":"الأمر pg_isready يعمل داخل container الـ db ولا علاقة له بمنطق الاتصال في الـ API."},{"text":"لأن Compose يعطّل depends_on بعد الدقيقة الأولى.","why":"لا شيء يُعطَّل. إنها ببساطة ميزة خاصة بوقت الإقلاع."},{"text":"لأن الترتيب لا يسري إلا عند الإقلاع؛ قد يُعاد تشغيل قاعدة البيانات لاحقًا، وKubernetes لا يرتّب الإقلاع أصلًا.","why":"صحيح. التطبيق المرن يعيد المحاولة مع backoff؛ وترتيب الإقلاع راحة إضافية، لا ضمانة."}],"answer":3}],"exercise":{"kind":"spot-bug","language":"yaml","code":"services:\n api:\n build: .\n depends_on:\n - db\n environment:\n DATABASE_URL: postgres://notes:notes@db:5432/notes\n db:\n image: postgres:17\n environment:\n POSTGRES_USER: notes\n POSTGRES_PASSWORD: notes\n POSTGRES_DB: notes\n healthcheck:\n test: [\"CMD\", \"pg_isready -U notes -d notes\"]\n interval: 10s\n retries: 5","bugLines":[5,15],"title":"سليم على الورق","prompt":"مع ملف compose.yaml هذا، تظهر db بحالة (unhealthy) إلى الأبد رغم أن psql يعمل جيدًا، وما زال الـ API ينهار عند الإقلاع البارد برسالة ECONNREFUSED. اختر السطرين الاثنين اللذين يجب إصلاحهما.
CMD)، كم معاملًا يرى Docker في تلك القائمة؟","أي صيغة من depends_on لا تنتظر إلا بدء الـ container؟"],"explanation":"السطر 15 يستخدم صيغة exec مع نصّ واحد، فيبحث Docker عن برنامج اسمه حرفيًا pg_isready -U notes -d notes ولا ينجح الفحص أبدًا. استخدم CMD-SHELL مع النصّ، أو قسّم المعاملات.
السطر 5 يستخدم الصيغة المختصرة لـ depends_on، التي لا تنتظر إلا بدء db. انتظر الـ healthcheck بدلًا من ذلك:
api:\n depends_on:\n db:\n condition: service_healthy\n db:\n healthcheck:\n test: [\"CMD-SHELL\", \"pg_isready -U notes -d notes\"]