مرجع أوامر Docker Compose للخوادم الحقيقية

الأوامر التي تستخدمها فعلياً في Compose

يوفّر Docker Compose أكثر من 40 أمراً فرعياً. لكن العمل اليومي على الخادم يستخدم نحو 12 أمراً منها. تجمع هذه الصفحة الأوامر حسب المهمة التي تنفذها، وتوضح سبباً بسيطاً لاستخدام كل أمر، وتحيلك إلى الشرح المتعمق عندما يخفي الأمر مشكلة محتملة.

تستخدم جميع الأمثلة هنا Compose V2: docker compose مع مسافة، وليس السكربت القديم docker-compose. الإصدار V2 هو إضافة مكتوبة بلغة Go وتُثبَّت مع Docker Engine. أما الإصدار V1 فلم يعد متاحاً في الحزم الحالية، لذلك فإن ظهور docker-compose: command not found على خادم Ubuntu جديد في يوليو 2026 أمر متوقع، وليس دليلاً على وجود خلل. تحقّق باستخدام docker compose version. إذا لم يُخرج الأمر شيئاً، فثبّت الحزمة docker-compose-plugin.

تُنفَّذ كل الأوامر أدناه من الدليل الذي يحتوي على compose.yaml، لأن Compose يستخرج اسم المشروع من ذلك الدليل ويبحث عن الملف بالنسبة إليه. إذا نفّذت الأمر نفسه من مستوى أعلى بدليل واحد، يتوقف Compose ويعرض no configuration file provided: not found. إذا كان تنسيق الملف نفسه جديداً عليك، فابدأ بقراءة أول ملف Compose على VPS، ثم عد إلى هنا للاطلاع على الأوامر.

دورة الحياة: الأوامر الأربعة التي تكتبها، والأمر الذي يزيل الحاويات

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

ينشئ up -d الشبكة والحاويات، ويشغّلها، ثم يعود. ويعود فور إنشاء الحاويات، ولذلك يفشل غالباً في المحاولة الأولى برنامج النشر الذي ينفّذ بعده فحصاً باستخدام curl. يحظر up -d --wait التنفيذ حتى تُبلغ كل خدمة تعرّف healthcheck عن حالتها السليمة، ويخرج برمز غير صفري إذا لم تصل إحداها إلى هذه الحالة. لا يكون هذا الخيار أفضل من الفحص الذي يقف خلفه، لذلك اكتب healthcheck يمكن لـCompose الوثوق به قبل الاعتماد عليه في التشغيل الآلي.

يوقف stop الحاويات ويُبقيها، ولذلك يعيد start تشغيل الحاويات نفسها مع طبقة الكتابة نفسها. يوقف down الحاويات ثم يزيلها ويزيل شبكة المشروع. كل ما كُتب داخل الحاوية وخارج volume يُحذف معها. هذا أكثر مواضع سوء الفهم تكلفة في Compose، وتوضح الفروق الكاملة بين down وstop أين تظهر آثاره.

ليس restart عملية إعادة تحميل. فهو يوقف الحاوية نفسها ثم يشغّلها بالإعدادات الموجودة لديها، ولذلك لا يؤثر إطلاقاً تغيير متغير بيئة، أو وسم صورة جديد، أو تعديل ربط منفذ. لتطبيق تغيير في الملف، شغّل up -d مرة أخرى. يقارن Compose كل خدمة بالحاوية قيد التشغيل، ويعيد إنشاء الحاويات التي تغيّرت إعداداتها فقط.

تطبيق تغيير: إعادة الإنشاء أو السحب أو البناء

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

لا ينفّذ up -d أي إجراء عندما لا يتغير شيء، وهذا ما يجعله آمناً للتشغيل بشكل متكرر. يتجاوز --force-recreate هذه المقارنة ويستبدل كل حاوية حتى عندما يكون الإعداد مطابقاً، لذلك فهو أسرع طريقة لمسح الحالة غير المعتادة داخل الحاوية.

يتطلب تحديث صورة خطوتين لأن كل أمر ينفّذ إجراءً مختلفاً. ينزّل pull الصورة الحالية لكل وسم مذكور في الملف. بعد ذلك يلاحظ up -d أن معرّف صورة الخدمة لم يعد مطابقاً للحاوية قيد التشغيل، فيعيد إنشاءها. إذا تخطيت السحب، فسيُبقي up -d آخر latest من الشهر الماضي قيد التشغيل من دون خطأ.

ينطبق build على الخدمات التي تعرّف قسماً باسم build: بدلاً من image:. ينشئ up -d --build الصورة ويبدأ الخدمة في خطوة واحدة، وهذا هو المسار المعتاد أثناء تعديل الشفرة. استخدم --no-cache فقط عندما تكون طبقة مخزّنة مؤقتاً قديمة بوضوح، لأنه يعيد بناء كل طبقة من البداية.

عرض ما يعمل

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

يعرض ps الحاويات قيد التشغيل فقط. تكون الخدمة التي تعطّلت أثناء بدء التشغيل غير ظاهرة هناك حتى تضيف -a، لذلك فإن اختفاء حاوية من ps بينما يعرضها ps -a بالحالة Exited (1) هو الشكل المعتاد لفشل بدء التشغيل. اقرأ رمز الخروج، ثم اقرأ السجلات.

يتابع logs -f جميع الخدمات في الوقت نفسه، ويضيف اسم الخدمة إلى بداية كل سطر. هذه هي الطريقة المناسبة عندما تتواصل الخدمات مع بعضها ويكون ترتيب الأحداث مهماً. اذكر اسم خدمة لتضييق النطاق. يكون --tail=100 مهماً للحاوية التي تعمل منذ شهر، لأن الإعداد الافتراضي يعرض السجل الكامل ويغمر الطرفية بالمخرجات. يجيب --since 15m عن السؤال المعتاد: ماذا حدث أثناء إعادة التشغيل التي نفذتها للتو؟

يعرض top العمليات داخل كل حاوية. وبذلك يميّز بين «الحاوية قيد التشغيل» و«العملية داخلها قيد التشغيل». يخرج ls من الدليل الحالي ويعرض جميع مشاريع Compose على الخادم مع حالتها، حتى تتمكن من العثور على المكدس الذي شغّلته قبل ثلاثة أشهر.

الدخول إلى shell داخل خدمة

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

ينفّذ exec أمراً داخل حاوية قيد التشغيل بالفعل. ويبدأ run حاوية جديدة من تعريف الخدمة نفسه، وهذا ما تحتاج إليه عندما لا تبقى الخدمة قيد التشغيل مدة كافية لتنفيذ أمر داخلها. اربط run دائماً بـ--rm، لأن تركه سيؤدي إلى إنشاء حاوية متوقفة بعد كل استدعاء، وستتراكم هذه الحاويات حتى يصبح docker compose ps -a غير مقروء.

جرّب sh قبل bash. لا تتضمن الصور المبنية على Alpine أي bash، ويظهر الفشل بالرسالة exec: "bash": executable file not found in $PATH. تؤدي إضافة --no-deps إلى run إلى تخطي تبعيات الخدمة، ما يمنع فحص إعداد سريعاً من تشغيل قاعدة البيانات بالكامل.

يُعد run --rm web env أسرع طريقة لمعرفة البيئة التي حصلت عليها الخدمة فعلياً، بعد دمج كل ملف .env وكتلة environment: ومتغير shell. عندما تكون قيمة ما غير صحيحة، يكون ترتيب الدمج هو السبب عادةً، وتوضّح كيفية حل Compose لملفات البيئة والأسرار أي مصدر له الأولوية.

الشبكات والمنافذ وحل الأسماء

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

يضع Compose كل خدمة على شبكة واحدة للمشروع، ويكون اسم كل خدمة اسماً في DNS على هذه الشبكة. يؤدي تشغيل getent hosts db داخل web إلى عرض عنوان IP للحاوية عند نجاح الحل، ولا يعرض شيئاً عند فشله. لذلك يجيب خلال ثانيتين عن سؤال: «هل تستطيع هذه الحاويات رؤية بعضها؟» إذا حُلَّ الاسم لكن رُفض الاتصال، تكون العملية داخل db مرتبطة بـ127.0.0.1 بدلاً من 0.0.0.0. لذلك لا تقبل أي حزمة من حاوية أخرى. يشرح كيفية عمل شبكات Compose وDNS الخاص بالخدمات بقية هذا النموذج.

يعرض port web 80 عنوان المضيف والمنفذ الذي نُشر عليه منفذ الحاوية. وهذا يلغي الحاجة إلى التخمين عندما يأتي الربط من متغير. يؤدي نشر منفذ أيضاً إلى إنشاء قاعدة جدار ناري يديرها Docker بنفسه. وتأتي هذه القاعدة قبل قواعدك. لذلك قد تصبح خدمة اعتقدت أنها خاصة متاحة على الإنترنت. تشرح لماذا تتجاوز منافذ Docker المنشورة ufw هذه الحالة.

المجلدات ووحدات التخزين والبيانات

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

تعرض config --volumes وحدات التخزين المُسمّاة التي يعرّفها المشروع، بحيث تظهر كل وحدة في سطر مستقل. هذه هي القائمة التي يجب نسخها احتياطياً. تنسخ cp ملفاً إلى حاوية أو منها دون فتح shell، باستخدام الصيغة service:path في الجهة التي تكون فيها الحاوية.

تزيل down -v وحدات التخزين المُسمّاة مع الحاويات. وهذا هو الأمر المناسب لإزالة مكدس اختباري، والخيار الخاطئ لأي مكوّن يحتوي على بيانات مهمة، لأنه لا يطلب تأكيداً ولا يتيح التراجع. تبقى bind mounts موجودة بعد تنفيذ هذا الأمر، لأنها محفوظة في نظام ملفات المضيف. ويُعد هذا الاختلاف في نطاق التأثير أحد أسباب الاختيار المتعمد بين bind mounts ووحدات التخزين المُسمّاة.

تنظيف يحرّر مساحة على القرص دون فقدان البيانات

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

يحذف --remove-orphans الحاويات التابعة للمشروع التي لم تعد تظهر في الملف، وهذا ما يحدث تحديداً بعد إعادة تسمية خدمة. من دونه، تستمر تلك الحاويات في العمل من دون أن تظهر في docker compose ps.

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

لا يلمس أي من هذه الأوامر وحدة تخزين مسماة. الأمران docker volume prune وdocker compose down -v فقط يفعلان ذلك.

التحقق من الملف قبل أن يسبب مشكلة

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

يتحقق config --quiet من الملف ولا يطبع شيئاً عند النجاح، لذلك ضعه في خطوة ما قبل النشر أو في git hook. يطبع config العادي الملف المدمج والموسَّع بالكامل. بهذه الطريقة تتأكد من حلّ المتغير ومن تطبيق ملف التجاوز بالطبقات المتوقعة. يظهر المتغير غير المعيّن كقيمة فارغة، إلى جانب التحذير The "X" variable is not set. Defaulting to a blank string.

يُعد --dry-run خياراً عاماً، وليس خياراً للأمر الفرعي، لذلك يجب وضعه قبل up. يطبع كل إجراء سينفذه Compose ولا يغيّر شيئاً. وهذه ثلاثون ثانية تستحق قضاءها قبل تنفيذ down على حزمة مهمة.

العمل عبر الملفات وملفات التعريف والمشاريع

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

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

تبدأ --profile الخدمات المعلّمة بملف التعريف المحدد إلى جانب الخدمات غير المعلّمة، وبذلك تبقى أدوات التصحيح خارج up العادي. تعيّن -p اسم المشروع، لذلك يمكن تشغيل نسختين من المكدس نفسه جنباً إلى جنب مع شبكات منفصلة وأسماء وحدات تخزين منفصلة. استعادة المكدس بعد إعادة التشغيل ليست أمراً تكتبه يدوياً، بل وحدة تشغّل أمراً نيابةً عنك، كما هو موضح في بدء تشغيل مكدسات Compose عند الإقلاع.

FAQ

ما الذي حل محل docker-compose الذي يحتوي على شرطة؟

Compose V2، ويُستدعى عبر docker compose مع وجود مسافة. وهو مكوّن إضافي مضمّن في Docker Engine، ولم تعد أداة V1 المكتوبة بلغة Python مثبّتة ضمن الحزم الحالية. إذا لم يُظهر الشكل الذي يحتوي على مسافة أي مخرجات، فثبّت الحزمة docker-compose-plugin الخاصة بتوزيعتك. حدّث البرامج النصية القديمة لاستخدام الشكل الذي يحتوي على مسافة بدلاً من إضافة اسم مستعار، لأن V2 يتضمن خيارات لم تكن متاحة في V1.

لماذا لا يلتقط docker compose restart التغيير الذي أجريته على الإعدادات؟

يوقف restart الحاوية الحالية ويعيد تشغيلها باستخدام الإعدادات التي أُنشئت بها، ولا يعيد قراءة compose.yaml مطلقاً. يتطلب أي تغيير في متغيرات البيئة أو المنافذ أو وحدات التخزين أو وسم الصورة استخدام docker compose up -d، الذي يقارن كل خدمة بالحاوية قيد التشغيل ويعيد إنشاء الحاويات المختلفة. أضف --force-recreate عندما تريد تنفيذ الاستبدال حتى إذا لم يتغير أي شيء في الملف.

كيف أحدّث خدمة إلى صورة أحدث؟

شغّل docker compose pull، ثم docker compose up -d. يجلب أمر السحب الصورة الحالية لكل وسم في الملف، ويعيد up -d إنشاء أي خدمة لم يعد معرّف صورتها مطابقاً لحاويتها. يؤدي تشغيل up -d بمفرده إلى إعادة استخدام الصورة الموجودة على القرص، ولذلك قد تظل حزمة مثبّتة على latest تعمل بإصدار بُني قبل عدة أشهر من دون عرض أي خطأ.

ما أوامر التنظيف الآمنة على خادم قيد التشغيل؟

يزيل docker system df وdocker image prune -a وdocker builder prune الصور وذاكرة التخزين المؤقت فقط، لذلك تواصل الخدمات قيد التشغيل عملها ولا تتأثر وحدات التخزين المسماة. أما docker compose down -v وdocker volume prune فهما الأمران الخطِران، لأنهما يحذفان وحدات التخزين المسماة من دون طلب تأكيد. شغّل docker compose config --volumes أولاً لمعرفة العناصر المعرّضة للخطر.

هل يمكنني تشغيل أمر واحد من دون بدء الحزمة كاملة؟

نعم. يشغّل docker compose run --rm --no-deps web sh حاوية واحدة من تعريف الخدمة web، ويتجاوز تبعياتها، ويزيل الحاوية عند الخروج. استخدم exec بدلاً منه عندما تكون الحاوية قيد التشغيل بالفعل، لأن exec ينضم إلى العملية الحية ويعرض الحالة الفعلية للخدمة.