SSD Nodes Learn Hosting plans →
الأدلة Matt Connorبقلم Matt Connor

الفرق بين build وimage في Docker Compose على VPS

افهم ماذا يفعل image وbuild على VPS، ولماذا يتجاهل compose up تغييرات Dockerfile، ومتى تستخدم docker compose build أو --build لإصلاح ذلك.

Docker Compose: الفرق بين build وimage باختصار

في ملف Docker Compose، يحدّد image: الصورة المطلوب استخدامها، بما في ذلك صورة محلية أو tag أو مرجع digest، بينما يوضّح build: لـCompose كيفية بنائها من المصدر. عند ضبط image: فقط، يستخدم Compose الصورة أو يسحبها وفقاً لـpull_policy. عند ضبط build: فقط، يبني Compose الصورة باستخدام أداة البناء المهيّأة، ويمنحها اسماً مشتقاً من اسم المشروع واسم الخدمة. عند ضبط الخيارين معاً، يحدّد pull_policy ما إذا كان Compose سيسحب الصورة أو يبنيها؛ وعند بنائها، يضع لها tag بالاسم الموجود في image:. هذه هي الطريقة لبناء صورة ثم دفعها باسم تختاره. يمكن لأداة البناء أن تعمل محلياً أو على Docker host بعيد.

هذا هو الفرق بالكامل. يوضّح كل ما يلي آثاره التشغيلية على الخادم. يفترض هذا أن Docker Engine وCompose plugin مثبتان مسبقاً؛ يشرح تشغيل Docker على VPS هذا الجزء.

الأشكال الثلاثة كاملة

استخدم وسمًا منشورًا، واسحبه إذا لم يكن موجودًا وفق سياسة السحب الافتراضية. لا يُستخدم Dockerfile في أي مرحلة.

services:
  web:
    image: nginx:1.27
    restart: unless-stopped
    ports:
      - "80:80"

أنشئ الصورة من Dockerfile موجود في دليل المشروع. ويمكن لعملية الإنشاء أيضًا سحب الصور وتنزيل التبعيات التي يتطلبها Dockerfile.

services:
  web:
    build: .
    restart: unless-stopped
    ports:
      - "80:80"

أنشئ الصورة ووسم النتيجة باستخدام docker compose build؛ عند عدم تحديد سياسة سحب صريحة، يحاول up سحب هذه الصورة قبل إنشائها. ويمكن لـdocker compose push بعد ذلك إرسال هذا الوسم نفسه إلى سجل.

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: registry.example.com/acme/web:1.4.2
    restart: unless-stopped
    ports:
      - "80:80"

context هو الدليل الذي يُرسل إلى أداة الإنشاء. ويُحل dockerfile بالنسبة إلى ذلك السياق، لذا فإن استخدام context: . مع dockerfile: docker/prod.Dockerfile أمر طبيعي وصحيح. شغّل docker compose images لعرض اسم الصورة ومعرّف الصورة المرتبطين بكل حاوية خدمة؛ وافحص ملف Compose للتأكد مما إذا كانت الخدمة تستخدم image: أو build: أو كليهما.

لماذا لا يعيد docker compose up إنشاء الصورة بعد تغيير Dockerfile؟

لأن الأمر العادي up يعيد استخدام صورة موجودة، ما لم تطلب إنشاءها أو تضبط سياسة تتطلب ذلك.

عندما يشغّل Compose خدمة تحتوي على قسم build: فقط، فإنه يستخدم الصورة الموجودة إذا كانت متاحة. ولا يقرأ Dockerfile أو يقارن ملفات المصدر أو يفحص أي طابع زمني. عند وجود image: وbuild: معاً ومن دون pull_policy صريح، يحاول Compose السحب أولاً، ثم ينشئ الصورة إذا لم تكن متاحة في السجل أو في ذاكرة التخزين المؤقت للمنصة. ويُعامل وجود الصورة على أنه كافٍ.

لذلك تعدّل app.py، ثم تشغّل docker compose up -d، وتراقب Compose وهو يعلن أن الحاوية قيد التشغيل، لكن التطبيق يقدّم الشفرة القديمة. لم يحدث أي فشل، لذلك لم يظهر أي تحذير. والمؤشر الحاسم هو كلمة الحالة التي يطبعها Compose بجانب اسم الحاوية: الحاوية التي استبدلها Compose تظهر حالتها على أنها أُعيد إنشاؤها أو بدأت، أما الحاوية التي قرر Compose تركها دون تغيير فتظهر حالتها على أنها قيد التشغيل.

يكفي فحصان لحسم الأمر. يطبع docker compose images معرّف الصورة التي تستخدمها كل حاوية، لذا سجّل المعرّف قبل النشر وقارنه بعده. ويحتوي docker image ls على عمود CREATED، لكن عمليات الإنشاء المخزّنة مؤقتاً والطوابع الزمنية القابلة لإعادة الإنتاج تعني أن التاريخ وحده لا يثبت أن أحدث مصدر لديك استُخدم في الإنشاء.

ما الخيارات التي تفرض إعادة البناء

  • docker compose up -d --build ينفّذ البناء أولاً، ثم يعيد إنشاء أي حاوية تغيّرت صورتها. هذا هو الخيار الذي يبحث عنه معظم المستخدمين.
  • docker compose build web يبني خدمة واحدة ولا يبدأ أي شيء. استخدمه مع docker compose up --no-deps -d web لاستبدال تلك الحاوية فقط وترك بقية الحزمة قيد التشغيل.
  • docker compose build --no-cache web يتجاوز الطبقات المخزنة مؤقتاً ويعيد بناء الخدمة.
  • docker compose build --pull يحاول سحب إصدار أحدث من الصورة الأساسية في FROM، ولذلك تلتقط علامة متحركة مثل node:22 محتواها الحالي بدلاً من النسخة التي نزّلتها في مارس.
  • docker compose up -d --force-recreate يفرض إعادة إنشاء الحاوية حتى إذا لم يتغير الإعداد أو الصورة. لا يطلب هذا الخيار عملية بناء بحد ذاته، لكن up قد ينفّذ البناء إذا كانت الصورة مفقودة أو كانت سياسة السحب تتطلب ذلك. استخدامه عندما يكون المقصود هو --build يؤدي غالباً إلى طريق مسدود.

يمكنك أيضاً نقل هذا القرار إلى الملف. وفقاً لمواصفة Compose، يعني pull_policy: build أن Compose يبني الصورة ويعيد بناءها إذا كانت موجودة مسبقاً. عندئذٍ تدفع تكلفة البناء في كل up، وهذا مناسب على حاسوب محمول ونادراً ما يكون مناسباً على خادم.

services:
  web:
    build: .
    image: registry.example.com/acme/web:dev
    pull_policy: build

تجدر معرفة تفاعل آخر. يحاول docker compose pull سحب صور الخدمات التي تحتوي أيضاً على قسم build، وإذا فشل السحب فإنه يخبرك بضرورة بناء الصورة بدلاً من ذلك. مرّر --ignore-buildable لتخطي تلك الخدمات بصمت.

كيف تحدد ذاكرة التخزين المؤقت للبناء مدة النشر

يفحص builder كل تعليمة في Dockerfile بحثاً عن نتيجة مخزنة مؤقتاً قابلة لإعادة الاستخدام، ما دامت التعليمة ومدخلاتها لم تتغيرا. بالنسبة إلى COPY، تشمل المدخلات محتوى الملفات والبيانات الوصفية، باستثناء أوقات التعديل. بعد فشل العثور على نتيجة مخزنة لإحدى الطبقات، يُعاد بناء الخطوات اللاحقة التي تعتمد عليها.

تحدد هذه القاعدة وحدها ما إذا كان النشر سيستغرق ثواني أو دقائق. رتّب Dockerfile بدءاً بما يتغير نادراً، وانتهاءً بما يتغير مع كل commit.

FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]

يأتي npm ci قبل COPY . .، لذلك يترك تعديل ملف مصدر طبقة التثبيت مخزنة مؤقتاً، ويستأنف البناء عند خطوة النسخ. إذا بدّلت ترتيب هذين السطرين، فإن تغيير حرف واحد يعيد تثبيت كل dependency، لأن COPY . . يبطل صلاحية الطبقة التي يعتمد عليها npm ci. ينطبق الترتيب نفسه على pip install -r requirements.txt وعلى go mod download.

يُعد --no-cache الأداة المناسبة عندما تشك في أن طبقة قديمة تخفي إصلاحك. لكنه ليس الخيار الافتراضي المناسب، لأنه يتخلص من إعادة الاستخدام التي يهدف ترتيب Dockerfile إلى تحقيقها.

هناك إعداد واحد يمكن لمجموعات image وCompose تجاوزه: تحدد CMD في Dockerfile ما تشغّله image افتراضياً، ويستبدله مفتاح command: في الخدمة. وتهم هنا صفحة كيفية تفاعل command وentrypoint، لأن تجاوزاً في Compose قد يجعل image المبنية حديثاً تتصرف تماماً مثل image القديمة.

سياق البناء وملف .dockerignore

يتيح context: . دليل المشروع لأداة البناء. من دون الاستبعادات، يشمل ذلك .git وأي دليل بيانات قد تحتفظ به بجوار الشيفرة المصدرية، مع أن BuildKit يتجاوز الملفات غير المستخدمة وينقل التغييرات بشكل تزايدي. إذا توقفت عملية البناء عند خطوة نقل السياق في مشروع لم يتغير، فهذا يعني أن السياق كبير جداً.

يستبعد ملف .dockerignore الموجود في جذر السياق المسارات من عملية النقل. وتشبه صياغته صياغة .gitignore.

.git
node_modules
*.log
data/
.env

توجد فائدتان لذلك. يصغر حجم النقل، وينخفض الوقت المستغرق في إرسال هذه الملفات. كما لن يتمكن COPY . . بعد ذلك من نسخ .env إلى الصورة، حيث يستطيع أي شخص يسحب تلك الصورة قراءة محتواه.

الحالة التي تتباطأ فيها عملية البناء مع مرور الوقت هي mount من نوع bind. يوجد volume مسمّى خارج دليل المشروع، لكن bind mount مثل ./data:/var/lib/postgresql/data يوجد داخل سياق البناء، لذلك تصبح عمليات البناء أبطأ كل أسبوع مع نمو قاعدة البيانات. يعالج سطر واحد في .dockerignore هذه المشكلة. يشرح bind mounts مقابل volumes المسمّاة المفاضلة الأوسع.

تتضمن معاملات البناء نسخة أصغر من الخطر نفسه. يمكن أن تستمر القيم التي تُمرَّر عبر args: في سجل الصورة أو في بيانات provenance الوصفية، لذلك ضع فيها رقم إصدار، ولا تضع token. تُستبعد معاملات proxy المحددة مسبقاً من ذاكرة التخزين المؤقت للبناء ومن docker history افتراضياً، ما لم تتم الإشارة إليها صراحةً في Dockerfile. يشرح ملفات البيئة والأسرار في Compose المكان المناسب لبيانات الاعتماد بدلاً من ذلك.

هل ينبغي أن تبني على VPS أم تبني في مكان آخر وتسحب الصورة؟

يكون البناء على الخادم الذي يقدّم حركة الشبكة هو الخيار الافتراضي، لأنه أقصر مسار: git pull، ثم docker compose up -d --build. وهذا مناسب لخادم صغير لا يعتمد عليه أحد بعد. لكنه يصبح غير مناسب لسببين يمكن قياسهما، وسبب ثالث لا يظهر إلا في يوم سيئ.

الذاكرة. يشغّل البناء المصرّفات وأدوات التجميع بجوار تطبيقك الفعلي، وهذه الأدوات تستهلك معظم الذاكرة في أغلب حزم البرمجيات. يمكن لأداة تجميع JavaScript أو عملية ترجمة Rust أن تستنفد الذاكرة المتاحة على VPS بسعة 1 GB. عند نفاد الذاكرة، تختار النواة عملية ضحية بسبب نفاد الذاكرة باستخدام درجة خطورة تعتمد على استخدام الذاكرة، وسياق التخصيص، وoom_score_adj؛ ولا تقتل ببساطة العملية الأكبر. قد يتوقف البناء مع Killed وحالة خروج 137، أو قد تُقتل قاعدة البيانات بدلاً منه، فيتوقف الموقع أثناء عملية النشر. يبحث dmesg -T | grep -i oom في سجل النواة عن رسائل نفاد الذاكرة؛ ويتطلب الوصول إذناً لقراءة ذلك السجل.

القرص. تترك عمليات البناء طبقات الصور وذاكرة البناء المؤقتة خلفها. يعرض docker system df استخدام القرص؛ وتستعيد عملية جمع البيانات المهملة الدورية في BuildKit ذاكرة التخزين المؤقت وفق السياسات المكوّنة لها. استعد المساحة باستخدام docker image prune للصور المعلّقة، وdocker builder prune لطبقات ذاكرة التخزين المؤقت. لا يوقف امتلاء القرص عملية البناء فقط. بل تتوقف قاعدة البيانات عن الكتابة أيضاً، وتكلّف هذه المشكلة أكثر بكثير من بطء النشر.

قابلية إعادة الإنتاج. من دون دفع الصورة أو تصديرها، لا توجد الصورة المبنية على الخادم إلا على ذلك الخادم. إذا لم تعد الصورة القديمة متاحة، فإن التراجع يعني سحب commit القديم وبناء الصورة من جديد. وليس مضموناً أن ينتج ذلك البناء الصورة نفسها، لأن وسم الصورة الأساسية تغيّر، وتغيّرت معه مستودعات الحزم. أما البناء في مكان آخر ودفع وسم، فيحوّل التراجع إلى تعديل: وجّه image: إلى الوسم السابق وشغّل docker compose up -d.

الترتيب الذي يصمد عملي وواضح. ينفّذ نظام التكامل المستمر لديك عملية البناء ويدفع registry.example.com/acme/web:<git-sha>، بينما يحتوي ملف Compose على VPS على image: من دون مفتاح build: إطلاقاً. يصبح النشر عندئذ مؤلفاً من أمرين لا يحتاجان إلا إلى قدر ضئيل من الذاكرة.

docker compose pull
docker compose up -d

نفّذ docker login registry.example.com على الخادم لحفظ بيانات الاعتماد اللازمة لسحب الوسوم الخاصة.

أبقِ قسم البناء مخصّصاً للتطوير بدلاً من حذفه، في ملف تختار اسمه بنفسك.

# compose.dev.yaml
services:
  web:
    build:
      context: .
    pull_policy: build
docker compose -f compose.yaml -f compose.dev.yaml up -d --build

سمِّ ذلك الملف compose.dev.yaml وليس compose.override.yaml. يحمّل Compose ملف التجاوز تلقائياً متى كان موجوداً، ولذلك فإن نسخ ملف تجاوز متروك على الخادم سيؤدي بهدوء إلى بدء البناء هناك من جديد. يشرح تجميع عدة ملفات Compose كيفية حل الدمج لكل مفتاح.

فخ المعمارية عند الإنشاء على جهاز آخر

تحمل صورة المنصة الواحدة معمارية وحدة المعالجة المركزية التي أُنشئت لها. إذا أنشأت صورة ARM على حاسوب محمول مزوّد بمعالج Apple Silicon، ثم دفعتها واستخدمتها على VPS بمعمارية x86_64، فسيعرض Docker تحذيراً أثناء إنشاء الحاوية إذا استخدم صورة مخزّنة مؤقتاً وغير متوافقة من دون تحديد المنصة صراحةً. من دون المحاكاة، تفشل العملية بالخطأ exec format error، الذي يوحي بأن الملف الثنائي تالف، لكنه ليس كذلك. أنشئ الصورة للهدف صراحةً:

docker buildx build --platform linux/amd64 \
  -t registry.example.com/acme/web:1.4.2 --push .

يحدث عدم التطابق نفسه بالعكس إذا كان حاسوبك المحمول بمعمارية x86 وشغّلت VPS بمعمارية ARM بدلاً من VPS بمعمارية x86. يزيل جعل CI ينشئ الصورة على المعمارية التي تنشر عليها هذه المشكلة. وتحل الصورة متعددة المنصات المشكلة أيضاً؛ إذ يختار Docker النسخة المطابقة عند سحبها.

ما الذي يجب التحقق منه بعد النشر

  • يطبع docker compose images الصورة والوسم المستخدمين خلف كل حاوية قيد التشغيل. يبيّن تغيّر معرّف الصورة أن الإصدار الجديد منشور.
  • يطبع docker compose config الملف المدمج بعد استبدال المتغيرات، كي تتمكن من قراءة اسم الصورة النهائي الذي سيستخدمه Compose قبل تشغيل أي شيء.
  • نفّذ docker compose logs -f web خلال أول نصف دقيقة بعد التبديل. لا تعيد الحاوية التي تبدأ ثم تتوقف التشغيل إلا إذا كانت سياسة إعادة تشغيلها تطلب ذلك؛ راجع السجلات لمعرفة السبب.
  • يعرض docker image ls عمود CREATED. تحقّق أيضاً من مخرجات البناء ومعرّف الصورة المنشورة، لأن الطابع الزمني للإنشاء وحده لا يثبت ما إذا كانت عملية إعادة البناء قد نُفّذت.

إذا كنت لا تزال تُعدّ الملف الذي ستعمل عليه عمليات التحقق هذه، فتغطي أساسيات ملف Compose على VPS المفاتيح ذات الصلة، وتعرض ورقة الغش لأوامر Compose بقية الأوامر الفرعية.

FAQ

هل يمكنني استخدام build وimage في الخدمة نفسها؟

نعم، وهذا هو الإعداد المعتاد لمشروع تبنيه بنفسك. عندما ينشئ Compose الصورة من قسم build:، فإنه يضع عليها الوسم الذي تحدده قيمة image:؛ ومن دون pull_policy صريح، يحاول up السحب أولاً. هذا الوسم هو ما يرسله docker compose push إلى مستودع الصور، وهو ما تسحبه آلة أخرى. ومن دون مفتاح image:، يواصل Compose إنشاء الصورة، لكنه يسمّيها باستخدام اسم المشروع واسم الخدمة، ويحذّر من أن غياب هذه السمة يمنع دفع الصورة.

لماذا لا يلتقط docker compose up التغيير الذي أجريته على Dockerfile؟

لأن up العادي يعيد استخدام صورة موجودة، ما لم تطلب إنشاء الصورة أو تضبط سياسة تتطلب ذلك. فهو لا يقارن تلك الصورة بملف Dockerfile أو بملفات المصدر ليقرر ما إذا كانت إعادة الإنشاء مطلوبة. شغّل docker compose up -d --build، أو شغّل docker compose build web ثم docker compose up --no-deps -d web لاستبدال خدمة واحدة. يؤدي ضبط pull_policy: build على الخدمة إلى إعادة الإنشاء في كل up، وهذا مناسب لآلة التطوير.

ما الفرق بين --build و--force-recreate؟

يعيد --build إنشاء الصورة، ثم يعيد إنشاء الحاويات التي تغيّرت صورتها. يفرض --force-recreate إعادة إنشاء الحاويات حتى إذا لم يتغير الإعداد أو الصورة؛ ولا يطلب إنشاء الصورة بحد ذاته. إذا كان التغيير في المصدر أو في Dockerfile، فإن --build هو الخيار المطلوب. أما --force-recreate فمخصص لإعادة ضبط الحاوية نفسها، مثل مسح طبقتها القابلة للكتابة مع الإبقاء على الصورة نفسها.

هل ينبغي أن أنشئ صور Docker على VPS أم في مكان آخر؟

أنشئ الصورة في مكان آخر، ثم اسحب الوسم بعد أن يبدأ الخادم أيضاً في تمرير حركة الشبكة. تتنافس عملية الإنشاء مع تطبيقك على الذاكرة، وعند نفاد الذاكرة يختار kernel عملية لإيقافها باستخدام قيمة OOM قابلة للضبط، وقد تكون عملية الإنشاء أو قاعدة البيانات. كما تترك عمليات الإنشاء ذاكرة تخزين مؤقت على القرص، رغم أن BuildKit يستعيدها تلقائياً وفق سياسات جمع البيانات المهملة لديه. يظل الإنشاء على الخادم مناسباً لمشروع صغير بلا مستخدمين، ويكون الانتقال لاحقاً سهلاً إذا أبقيت قسم build: في ملف Compose مخصص للتطوير فقط.

كيف أمنع ذاكرة تخزين Docker المؤقتة الخاصة بالإنشاء من ملء القرص؟

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

هل كان هذا المقال مفيدًا؟