ورقة مرجعية Docker Compose (2026): كل مفاتيح الخدمة وأوامر CLI

نظرة عامة

يحدد Docker Compose تطبيقات متعددة الحاويات في ملف YAML واحد. تغطي هذه الورقة المرجعية بنية compose.yaml، كل مفاتيح الخدمة، خيارات البيئة والإعدادات، الشبكات والأحجام، CLI الكامل، ملفات الإلغاء، والملفات الشخصية. جميع الأمثلة موجهة نحو Docker Compose v2 (المكوّن docker compose) ومواصفات Compose؛ المفتاح version: القديم عفا عليه الزمن ويتم تجاهله.

هيكل compose.yaml

البنية الأساسية لملف Compose:

services:      # تحديد الخدمات المحتوية
volumes:       # تحديد الأحجام المسماة
networks:      # تحديد الشبكات المخصصة
configs:       # تحديد الإعدادات (للغواصة، اختياري)
secrets:       # تحديد الأسرار (للغواصة، اختياري)

الخدمات: مفاتيح أساسية

الشبكات والمنافذ

البيئة والإعدادات

التخزين: الأحجام والربط

ملاحظة: حدد الأحجام المسماة على المستوى الأعلى:

volumes:
  my_data:
    driver: local

حدود الموارد

فحوصات صحية

مثال كامل:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 5s
  start_period: 10s
  retries: 3

التبعيات وترتيب البدء

تحذير: condition: service_healthy يتطلب أن تحتوي الخدمة على healthcheck. بدونها، يفشل الشرط على الفور.

مثال كامل:

services:
  web:
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started

الأمان: الأسرار والإعدادات

التعريف على المستوى الأعلى:

secrets:
  db_password:
    file: ./secrets/db_password.txt

configs:
  nginx_config:
    file: ./nginx.conf

الوصول في الحاوية:

# في shell: cat /run/secrets/db_password

الملفات الشخصية

تسمح الملفات الشخصية بتضمين الخدمات بشكل مشروط.

services:
  web:
    image: nginx:latest
    # يتم تضمينها دائماً

  debug:
    image: busybox:latest
    profiles: [debug]
    # يتم تضمينها فقط مع --profile debug

  monitoring:
    image: prom/prometheus:latest
    profiles: [monitoring, prod]
    # يتم تضمينها مع --profile monitoring أو --profile prod

الاستخدام:

docker compose up                        # تضمين الخدمات بدون ملفات شخصية فقط
docker compose --profile debug up        # تضمين web + debug
docker compose --profile monitoring up   # تضمين web + monitoring
docker compose --profile debug --profile monitoring up  # تضمين الجميع

الشبكات (على المستوى الأعلى)

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: br0

استخدام الخدمة:

services:
  web:
    networks: [frontend, backend]
  db:
    networks: [backend]

الأحجام (على المستوى الأعلى)

volumes:
  db_data:
    driver: local
  shared_cache:
    driver: local
    driver_opts:
      type: tmpfs
      device: tmpfs

ملفات الإلغاء

يحمّل Docker Compose تلقائياً docker-compose.override.yaml ويدمجها مع compose.yaml.

compose.yaml (الإنتاج):

services:
  web:
    image: myapp:latest
    environment:
      LOG_LEVEL: warn

docker-compose.override.yaml (التطوير المحلي):

services:
  web:
    build: .
    ports:
      - "8000:8000"
    environment:
      LOG_LEVEL: debug

النتيجة عند تشغيل docker compose up:
– تم بناء الصورة من ./Dockerfile (يلغي image: myapp:latest)
– يتم كشف المنفذ 8000 على المضيف
– تم تعيين LOG_LEVEL إلى debug
– يتم دمج تعيين المنفذ و LOG_LEVEL

ملف إلغاء صريح:

docker compose -f compose.yaml -f compose.prod.yaml up

أوامر CLI

الأنماط التي ستعاد استخدامها

# التطوير مع ملف override
# compose.yaml: إعداد الإنتاج
# docker-compose.override.yaml: تعديلات التطوير المحلي

# قاعدة البيانات مع فحص صحي و depends_on
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
  web:
    depends_on:
      db:
        condition: service_healthy

# تطبيق متعدد الطبقات
services:
  web:
    networks: [frontend, backend]
  cache:
    networks: [backend]
  db:
    networks: [backend]

# حمّل البيئة من ملف مع الإلغاءات
services:
  app:
    env_file: .env
    environment:
      LOG_LEVEL: debug  # تجاوز من .env

# الملفات الشخصية للخدمات الاختيارية
  monitoring:
    profiles: [monitoring]
  debug:
    profiles: [debug]

# استخدم compose watch لإعادة التحميل المباشرة (Compose 2.22+)
# docker compose watch
watch:
  - path: ./src
    action: sync
    target: /app/src
  - path: ./requirements.txt
    action: rebuild

الأسئلة الشائعة

ما الفرق بين docker-compose.yml و compose.yaml؟

كلاهما مدعوم. يفضل Docker compose.yaml (بدون شرطة). كلاهما متكافئ؛ اختر عرفاً واحداً والتزم به. تستخدم التوثيق الحديثة compose.yaml.

كيف أعيّن متغيرات البيئة في Docker Compose؟

استخدم مفتاح environment في الخدمة، أو حمّل من ملف باستخدام env_file: .env. يمكن أن تكون المتغيرات مرمّزة أو من shell المضيف (${VAR_NAME}) أو من ملفات .env. استخدم الأسرار للقيم الحساسة.

كيف أتأكد من بدء خدمة واحدة قبل أخرى؟

استخدم depends_on: db: condition: service_healthy (يتطلب HEALTHCHECK). لمجرد ترتيب البدء بدون التحقق من الجاهزية، استخدم الصيغة القصيرة depends_on: [db]؛ يرتب البدء فقط ولا ينتظر الجاهزية.

كيف أستخدم ملفات override في Docker Compose؟

أنشئ docker-compose.override.yaml في نفس المجلد. يحمّله Compose تلقائياً ويدمجه مع compose.yaml. تجاوز خدمات محددة بدون تعديل الملف الرئيسي. مفيد للتطوير المحلي مقابل الإنتاج.

ما هي ملفات تعريف Docker Compose؟

تسمح الملفات الشخصية بتضمين الخدمات بشكل مشروط. عيّن profiles: [debug] في خدمة، ثم استخدم docker compose --profile debug up لتضمينها. مفيد لخدمات تصحيح أخطاء أو أكوام مراقبة اختيارية.