الحاويات Containers وتنسيقها مع Kubernetes الأدلة التقنية

كتابة Dockerfile صحيح: Multi-stage وLayer Caching

خمس نسخ من Dockerfile للتطبيق نفسه نزلت بال Image من 641 ميجابايت إلى 66 وبالبناء بعد تعديل سطر من خمس دقائق إلى أقل من أربع ثوان، مع شرح كل سطر والأرقام المقاسة.

كتابة Dockerfile صحيح: Multi-stage وLayer Caching

إذا كتبت أول Dockerfile لتطبيقك فالغالب أنه بدأ بالسطر FROM ثم COPY . . ثم RUN npm install، وعمل التطبيق من أول مرة، فانتقلت إلى المهمة التالية. ثم تبدأ الملاحظات الصغيرة بالظهور واحدة بعد الأخرى: كل تعديل في سطر واحد من الكود يعيد تثبيت الحزم من البداية، وخط CI يأخذ دقائق في خطوة البناء وحدها، وال Image أكبر من نظام التشغيل الذي يشغلها، والأمر docker stop ينتظر في كل مرة حتى يقتل التطبيق بدل أن يوقفه، ثم يكتشف أحد الزملاء أن ملف .env بكلمات المرور موجود داخل ال Image التي رفعتها إلى ال Registry قبل أسابيع.

وكل هذه المشكلات تأتي من الملف نفسه، وكل واحدة منها لها سبب واضح في طريقة عمل البناء. وقد شرحنا في تثبيت Docker على Ubuntu كيف تجهز المحرك، وفي شبكات Docker كيف تتصل ال Containers ببعضها، واستخدمنا Dockerfile متعدد المراحل في خدمة Go الحقيقية وخدمة Node.js الحقيقية دون أن نقف عند كل سطر فيه. وفي هذا المقال سوف نقف عند كل سطر، فنأخذ تطبيقاً صغيراً واحداً، ونكتب له خمس نسخ من ال Dockerfile، من النسخة التي يكتبها أغلبنا أول مرة إلى نسخة صغيرة وسريعة، ونقيس في كل نسخة حجم ال Image وعدد الطبقات ووقت البناء، ونرى بالأوامر نفسها لماذا تغيرت الأرقام.

وسوف نناقش في هذا المقال ما يلي:

  • كيف يبني Docker ال Image من طبقات Layers، ومتى يستخدم ال Build Cache ومتى يعيد البناء، وما هو سياق البناء Build Context.
  • خمس نسخ للتطبيق نفسه: النسخة البسيطة، ثم ترتيب الطبقات، ثم البناء متعدد المراحل Multi-stage Build، ثم ملف .dockerignore، ثم ذاكرة BuildKit المؤقتة Cache Mounts، مع الأرقام المقاسة لكل نسخة.
  • الفرق بين ARG وENV، ولماذا لا تمرر كلمة مرور أو Token عبر ARG.
  • الفرق بين ENTRYPOINT وCMD، والصيغة exec والصيغة shell، وتجربة تبين من يستقبل الإشارة SIGTERM عند الإيقاف.
  • التعليمة USER، وفحص الصحة HEALTHCHECK، وفحص ال Dockerfile قبل البناء بالأمر docker build --check.
  • الأخطاء الشائعة، وقائمة تحقق تراجع بها أي Dockerfile قبل أن يصل إلى خط CI.
دليلما هي ال Containers؟ الفرق بينها وبين الأجهزة الافتراضيةنفتح Container حقيقياً من الخارج ثم نبني واحداً بأيدينا بـ unshare وchroot وcgroup v2، لنفهم ما الذي يعزله فعلاً وأين تقف حدوده أمام الجهاز الافتراضي.دليلأوامر Docker الأساسية: التشغيل والسجلات والإيقافنشغل خدمة صغيرة ونتابعها بأوامر Docker اليومية، ثم نفهم لماذا ينتظر docker stop ثم يقتل، وماذا تعني رموز الخروج 0 و1 و127 و137 و143.

كيف يبني Docker ال Image؟ الطبقات Layers وال Build Cache

ال Dockerfile قائمة تعليمات تقرأ من الأعلى إلى الأسفل، وكل تعليمة تغير نظام الملفات، مثل RUN وCOPY وADD، تنتج طبقة Layer جديدة، وهي أرشيف يحتوي الملفات التي أضيفت أو تغيرت أو حذفت مقارنة بالطبقة التي تحتها. أما التعليمات التي لا تلمس الملفات، مثل ENV وEXPOSE وCMD وUSER، فتغير إعدادات ال Image فقط Image Config ولا تضيف طبقة. وعندما يشغل Docker ال Container فإنه يضع هذه الطبقات فوق بعضها للقراءة فقط، ويضيف فوقها طبقة رقيقة قابلة للكتابة خاصة بال Container، فيرى البرنامج نظام ملفات واحداً، وهو في الحقيقة مجموعة طبقات.

ولهذا التصميم نتيجتان مهمتان لكل ما سيأتي. الأولى أن الحذف في طبقة لاحقة لا يصغر ال Image، فإذا نزلت ملفاً حجمه 300 ميجابايت في سطر RUN ثم حذفته في السطر التالي، فالملف ما زال موجوداً في الطبقة الأولى، والطبقة الثانية تحتوي فقط علامة تقول إنه محذوف، وال Image تحمل الحجم كاملاً إلى كل سيرفر يسحبها. والثانية أن الطبقات تعاد استخدامها، فإذا كانت عشر Images على السيرفر تبدأ من ال Base Image نفسها فطبقاتها المشتركة تخزن وتسحب مرة واحدة.

متى يستخدم Docker ال Cache ومتى يعيد البناء؟

البناء اليوم يقوم به BuildKit، وهو محرك البناء الافتراضي منذ Docker Engine 23، كما في وثائق BuildKit. وقبل أن ينفذ BuildKit أي تعليمة يسأل: هل نفذت هذه التعليمة من قبل فوق الطبقة نفسها وبالمدخلات نفسها؟ فإذا كان الجواب نعم أخذ النتيجة من ال Build Cache وكتب في المخرج CACHED، وإلا نفذها من جديد. والمدخلات تختلف بحسب نوع التعليمة، كما تشرح صفحة إبطال ال Cache:

  • RUN: المدخل هو نص الأمر نفسه فقط. فالأمر RUN apt-get update يبقى في ال Cache شهوراً ولو صدرت مئات التحديثات في مستودعات Debian، لأن نصه لم يتغير، و Docker لا يعرف ماذا يفعل الأمر ولا ينظر إلى الشبكة.
  • COPY وADD: المدخل هو محتوى الملفات المنسوخة وصلاحياتها، فيحسب Docker بصمة Checksum لكل ملف، وأي تغيير في ملف واحد يبطل التعليمة. ولاحظ أن وقت التعديل Modification Time لا يدخل في الحساب، فلمس الملف دون تغيير محتواه لا يبطل ال Cache.
  • ARG وENV: قيمتها تدخل في مدخلات كل تعليمة RUN بعدها، فتغيير قيمة ARG عند البناء يبطل كل RUN يأتي بعد تعريفه.

والقاعدة التي تحكم كل شيء هي أن إبطال تعليمة واحدة يبطل كل التعليمات التي بعدها في المرحلة نفسها، حتى لو لم تتغير مدخلاتها، لأن كل طبقة مبنية فوق التي قبلها، فإذا تغيرت الطبقة الأساس تغير كل ما فوقها. ومن هذه القاعدة وحدها يأتي أهم مبدأ في كتابة ال Dockerfile: ضع ما يتغير نادراً في الأعلى، وما يتغير مع كل Commit في الأسفل.

سياق البناء Build Context: ما الذي يرسل إلى BuildKit؟

عندما تكتب docker build . فالنقطة في آخر الأمر ليست تفصيلاً، وإنما هي سياق البناء Build Context، أي المجلد الذي يستطيع BuildKit أن ينسخ منه. وأمر docker الذي تكتبه هو كلاينت، أما البناء فيحدث في BuildKit داخل المحرك، وقد يكون على جهاز آخر تماماً، مثل سيرفر بناء بعيد أو Docker Desktop داخل آلة افتراضية. لذلك يرسل الكلاينت الملفات التي تحتاجها تعليمات COPY إلى BuildKit قبل أن تنفذ، ويظهر ذلك في المخرج في سطر transferring context. والملف .dockerignore هو الذي يحدد ما يستثنى من هذا السياق، كما في وثائق سياق البناء، فإذا لم يكن موجوداً أرسل المجلد كاملاً بما فيه .git وnode_modules وبيانات الاختبار، وأصبح كل ذلك متاحاً للسطر COPY . ..

التطبيق الذي سنبنيه: API بلغة Node وملف Go صغير

التطبيق خدمة طلبات صغيرة بلغة Node.js على Express 5، فيها ثلاثة مسارات: /health وGET /orders وPOST /orders، ومعها أداة صغيرة بلغة Go اسمها healthcheck نستخدمها لفحص الصحة كما سيأتي. واخترنا هذا المزيج لأنه يشبه مشاريع حقيقية كثيرة: لغة لها مدير حزم ومجلد node_modules، ولغة مترجمة تحتاج مترجماً أثناء البناء ولا تحتاجه عند التشغيل. والملفات كاملة في مجلد lab مع المقال، وهذا شكل المجلد كما هو على جهاز المطور، بعد أن شغل npm install ليجرب التطبيق محلياً، ومعه مستودع Git وملف بيانات اختبار وملف .env فيه كلمات مرور التطوير:

orders/
├── .env                      72 B   (DB_PASSWORD, STRIPE_KEY)
├── .git/                     41 MB
├── .gitignore
├── Dockerfile.v1 … Dockerfile.v5
├── api/
│   ├── package.json          express 5.2.1, eslint 10.15.0 (dev)
│   ├── package-lock.json
│   ├── server.js
│   └── node_modules/         20 MB (144 packages, dev included)
├── healthcheck/
│   ├── go.mod
│   └── main.go
├── npm-debug.log
└── test/fixtures/orders-dump.sql   52 MB

وكل البناءات في هذا المقال تمت بالأمر docker build --progress=plain لكي يظهر وقت كل خطوة، على Docker Engine 29.8 مع BuildKit، وقسنا كل نسخة مرتين: بناء بارد Cold Build بالخيار --no-cache، ثم بناء دافئ Warm Build بعد تعديل سطر واحد في server.js، وهو ما يحدث في كل Commit تقريباً. والأوقات المطلقة تختلف من جهاز إلى آخر ومن شبكة إلى أخرى، لذلك انظر إلى النسبة بين النسخ أكثر من الرقم نفسه، أما الأحجام وعدد الطبقات فثابتة.

النسخة الأولى: Dockerfile البسيط

هذه هي النسخة التي يكتبها أغلبنا أول مرة، ولا يوجد فيها سطر غريب، فكل سطر يفعل شيئاً مفهوماً: نبدأ من Image Node الكاملة، وننسخ المشروع، ونثبت مترجم Go من مستودعات Debian لنبني أداة الفحص، ثم نثبت حزم Node ونشغل التطبيق:

# v1: the first Dockerfile most of us write
FROM node:24.22.1-bookworm
WORKDIR /app
COPY . .
RUN apt-get update
RUN apt-get install -y golang-go
RUN cd healthcheck && go build -o /usr/local/bin/healthcheck .
RUN cd api && npm install
ENV PORT=3000
EXPOSE 3000
CMD cd api && npm start

والبناء البارد لهذه النسخة أخذ 8 دقائق و26 ثانية، وهذه أهم الأسطر من مخرجه مع وقت كل خطوة:

#4 transferring context: 110.66MB 91.9s done
#7 [3/7] COPY . .
#7 DONE 3.1s
#8 [4/7] RUN apt-get update
#8 DONE 21.3s
#9 [5/7] RUN apt-get install -y golang-go
#9 DONE 165.0s
#10 [6/7] RUN cd healthcheck && go build -o /usr/local/bin/healthcheck .
#10 DONE 9.7s
#11 [7/7] RUN cd api && npm install
#11 DONE 21.7s
#12 exporting layers 95.3s done
#12 unpacking to docker.io/library/ct2-d-orders:v1 87.7s done
real	8m26.412s

في المخرج أعلاه لاحظ التالي:

  • أول دقيقة ونصف ذهبت قبل أن تبدأ أي تعليمة، في إرسال سياق البناء: 110 ميجابايت هي المجلد كله بما فيه .git وبيانات الاختبار وnode_modules، ولا يحتاج التطبيق منها إلا بضعة كيلوبايتات.
  • أطول خطوة هي تثبيت مترجم Go، ثلاث دقائق تقريباً، من أجل بناء ملف واحد صغير.
  • بعد انتهاء التعليمات بقيت ثلاث دقائق أخرى في exporting layers وunpacking، أي ضغط الطبقات وكتابتها، وهذا الوقت يتناسب مع حجم ال Image، فال Image الكبيرة بطيئة في البناء أيضاً وليس في السحب فقط.

ثم نظرنا إلى الحجم والطبقات:

docker images ct2-d-orders:v1
docker history ct2-d-orders:v1 --format 'table {{.CreatedBy}}\t{{.Size}}'
IMAGE             ID             DISK USAGE   CONTENT SIZE   EXTRA
ct2-d-orders:v1   bd3604973b08       2.51GB          641MB

CREATED BY                                      SIZE
CMD ["/bin/sh" "-c" "cd api && npm start"]      0B
EXPOSE [3000/tcp]                               0B
ENV PORT=3000                                   0B
RUN /bin/sh -c cd api && npm install # build…   2.85MB
RUN /bin/sh -c cd healthcheck && go build -o…   9.11MB
RUN /bin/sh -c apt-get install -y golang-go …   500MB
RUN /bin/sh -c apt-get update # buildkit        19.9MB
COPY . . # buildkit                             117MB
WORKDIR /app                                    8.19kB
CMD ["node"]                                    0B
ENTRYPOINT ["docker-entrypoint.sh"]             0B
…

والعمودان في docker images يحتاجان شرحاً، لأن Docker 29 يستخدم مخزن containerd لل Images: العمود CONTENT SIZE هو حجم الطبقات مضغوطة، أي ما ينتقل عبر الشبكة عند الدفع والسحب، والعمود DISK USAGE هو ما تشغله ال Image على القرص، أي الطبقات المضغوطة مع نسختها المفكوكة. فهذه ال Image تنقل 641 ميجابايت إلى كل سيرفر، وتشغل هناك قرابة 1.9 جيجابايت مفكوكة. ومن الجدول لاحظ التالي:

  • أسفل الجدول، أي الأسطر التي حذفناها بعد …، هي طبقات ال Base Image نفسها، ومنها طبقات بمئات الميجابايت، لأن node:24.22.1-bookworm هي Image كاملة فيها مترجمات C وأدوات بناء ومكتبات تطوير، وحجمها 426 ميجابايت مضغوطة قبل أن نضيف شيئاً.
  • طبقة مترجم Go وحدها 500 ميجابايت، وهي باقية في ال Image رغم أن التطبيق لا يحتاجها عند التشغيل أبداً.
  • طبقة COPY . . حجمها 117 ميجابايت، وفيها كل المجلد.
  • طبقة npm install 2.85 ميجابايت فقط، والسبب أن node_modules نسخت من جهاز المطور مع COPY . .، فلم يجد npm إلا القليل ليفعله، وهذه بداية مشكلة سنراها كاملة في النسخة الثالثة.

ماذا يوجد داخل ال Image؟

الأرقام وحدها لا تقول كل شيء، فلننظر داخل ال Image نفسها:

docker run --rm ct2-d-orders:v1 sh -c 'id; cat /app/.env; ls -a /app; du -sh /app/test /app/.git /app/api/node_modules /usr/lib/go-1.19; go version'
uid=0(root) gid=0(root) groups=0(root)
DB_PASSWORD=S3cret-from-dev-laptop
STRIPE_KEY=sk_test_51Hx9fakefakefake
.
..
.env
.git
.gitignore
Dockerfile.v1
Dockerfile.v2
Dockerfile.v3
Dockerfile.v4
Dockerfile.v5
api
dockerignore.v4
healthcheck
npm-debug.log
test
52M	/app/test
41M	/app/.git
20M	/app/api/node_modules
328M	/usr/lib/go-1.19
go version go1.19.8 linux/amd64

وهذا أسوأ ما في النسخة الأولى، وليس الحجم. فملف .env بكلمات المرور داخل ال Image، وكل من يستطيع أن يسحبها من ال Registry يستطيع أن يقرأه بأمر واحد. ومعه تاريخ Git كاملاً، وقد يكون فيه سر حذفته من الكود قبل سنة ولكنه باق في Commit قديم. والتطبيق يعمل بالمستخدم root. وفي ال Image مترجم Go بالإصدار 1.19، وهو ما توفره مستودعات Debian 12، وهو إصدار قديم انتهى دعمه، فسوف يظهر في أي فحص للثغرات رغم أن التطبيق لا يستخدمه.

ماذا يحدث عند تعديل سطر واحد؟

عدلنا اسم منتج في server.js، أي سطراً واحداً، وأعدنا البناء دون --no-cache، فأخذ 4 دقائق و48 ثانية:

#4 transferring context: 110.59MB 69.8s done
#6 [2/7] WORKDIR /app
#6 CACHED
#7 [3/7] COPY . .
#7 DONE 1.4s
#8 [4/7] RUN apt-get update
#8 DONE 9.0s
#9 [5/7] RUN apt-get install -y golang-go
#9 DONE 123.7s
#10 [6/7] RUN cd healthcheck && go build -o /usr/local/bin/healthcheck .
#10 DONE 5.7s
#11 [7/7] RUN cd api && npm install
#11 DONE 6.0s
#12 exporting layers 37.1s done
real	4m47.654s

في المخرج أعلاه لاحظ التالي:

  • آخر سطر CACHED هو WORKDIR، ثم تغيرت مدخلات COPY . . لأن ملفاً واحداً تغير، فأعيد كل ما بعده: تحديث قائمة الحزم، وتثبيت مترجم Go كاملاً في دقيقتين، والبناء، وتثبيت حزم Node، رغم أن شيئاً من ذلك لم يتغير.
  • السياق أرسل كاملاً مرة أخرى، 110 ميجابايت في 70 ثانية. وفي العادة يحتفظ BuildKit بنسخة من آخر سياق أرسل من المجلد نفسه، ويطلب من الكلاينت الملفات التي تغيرت فقط، وقد رأينا ذلك في تجربة سابقة حيث نزل السياق إلى 147 كيلوبايت. ولكن بين البناءين بنينا النسخ الأخرى من المجلد نفسه بملف .dockerignore مختلف، فتغير ما يحفظه BuildKit، فأرسل كل شيء. وفي خط CI يبدأ كل مهمة على جهاز جديد يرسل السياق كاملاً في كل بناء دائماً.

أي أن كل Commit يدفع ثمن البناء كاملاً تقريباً. وهذه هي القاعدة التي ذكرناها في البداية، ونراها الآن بالأرقام.

عمودان من الطبقات بعد تعديل سطر في server.js: في النسخة الأولى تغير COPY . . في الطبقة الثالثة فأعيدت كل الطبقات فوقها ومنها تثبيت golang-go وnpm install، وفي النسخة الثانية جاء COPY . . في الأعلى فأعيدت طبقة واحدة وبقيت الطبقات الأخرى CACHED
الترتيب يحدد ما يعاد: تغيير في طبقة يعيد كل ما فوقها، فضع ما يتغير مع كل Commit في الأعلى

النسخة الثانية: ترتيب الطبقات Layer Ordering

في هذه النسخة لا نغير ال Base Image ولا الأدوات، وإنما نغير الترتيب فقط، بحسب عدد مرات التغير: أدوات النظام أولاً لأنها تتغير نادراً، ثم كود أداة الفحص، ثم ملفات تعريف الحزم وحدها وتثبيت الحزم، وأخيراً بقية الكود الذي يتغير مع كل Commit:

# v2: same base, but the layers are ordered from "rarely changes" to "changes every commit"
FROM node:24.22.1-bookworm
RUN apt-get update && apt-get install -y --no-install-recommends golang-go \
 && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY healthcheck/ healthcheck/
RUN cd healthcheck && go build -o /usr/local/bin/healthcheck .
COPY api/package.json api/package-lock.json api/
RUN cd api && npm ci
COPY . .
ENV PORT=3000
EXPOSE 3000
CMD cd api && npm start

في الإعداد أعلاه لاحظ التالي:

  • السطر COPY api/package.json api/package-lock.json api/ هو قلب هذه النسخة: خطوة npm ci تعتمد الآن على هذين الملفين فقط، فلا تعاد إلا إذا تغيرت الحزم نفسها.
  • npm ci بدل npm install، لأنه يثبت ما في ملف القفل بالضبط، ويحذف node_modules قبل التثبيت، ويفشل إذا لم يطابق الملفان بعضهما.
  • apt-get update وinstall في سطر واحد، والسبب في القسم التالي، ومعهما --no-install-recommends الذي يمنع تثبيت الحزم المقترحة، وrm -rf /var/lib/apt/lists/* الذي يحذف قوائم الحزم في الطبقة نفسها التي أنشأتها، فلا تبقى في ال Image.

والبناء البارد أخذ 6 دقائق و24 ثانية، والفرق عن النسخة الأولى جاء من السياق الذي أرسل من قبل، أما البناء الدافئ بعد تعديل السطر نفسه في server.js فكان كما يلي:

#4 transferring context: 143.63kB 0.3s done
#6 [5/8] RUN cd healthcheck && go build -o /usr/local/bin/healthcheck .
#6 CACHED
#7 [6/8] COPY api/package.json api/package-lock.json api/
#7 CACHED
#8 [2/8] RUN apt-get update && apt-get install -y --no-install-recommends golang-go  && rm -rf /var/lib/apt/lists/*
#8 CACHED
#9 [3/8] WORKDIR /app
#9 CACHED
#10 [4/8] COPY healthcheck/ healthcheck/
#10 CACHED
#11 [7/8] RUN cd api && npm ci
#11 CACHED
#12 [8/8] COPY . .
#12 DONE 1.3s
#13 exporting layers 12.7s done
real	0m21.141s

كل الخطوات CACHED ما عدا COPY . . الأخيرة، ولاحظ أن BuildKit يطبع الخطوات بترتيب انتهائها وليس بترتيب الملف، فالأرقام بين القوسين مثل [5/8] هي مكانها في الملف، فلم يثبت مترجم Go ولم تنزل حزمة واحدة. ولكن لاحظ أن البناء الدافئ ما زال يأخذ 21 ثانية، ومعظمها في exporting layers، لأن طبقة COPY . . ما زالت تحمل 117 ميجابايت من .git وبيانات الاختبار، ويجب ضغطها من جديد في كل بناء لأن محتواها تغير. فترتيب الطبقات حل مشكلة إعادة التثبيت، ولم يحل مشكلة ما ننسخه، ولا حجم ال Image: 632MB مضغوطة مقابل 641 في النسخة الأولى، والفرق كله من حذف قوائم apt والحزم المقترحة.

لماذا apt-get update وinstall في سطر واحد؟

تذكر أن ال Cache لتعليمة RUN يعتمد على نص الأمر فقط. فإذا كان RUN apt-get update في سطر مستقل، فإنه يدخل ال Cache في أول بناء ويبقى فيها شهوراً، ثم تضيف يوماً حزمة جديدة إلى سطر apt-get install فيتغير نصه، فيعاد تنفيذه وحده فوق قائمة حزم عمرها أشهر من ال Cache. والنتيجة إما خطأ 404 Not Found لأن الإصدار القديم حذف من المستودع، أو تثبيت إصدار قديم فيه ثغرات أصلحت منذ زمن. وتشرح أفضل ممارسات البناء في وثائق Docker هذه المشكلة بالاسم، والحل أن يكون التحديث والتثبيت في أمر واحد، فإذا تغير أي منهما أعيد الاثنان معاً.

إبطال ال Cache Cache Invalidation عملياً

طبقنا ثلاثة أنواع من التغيير على النسخة الثانية، كل تغيير في Commit مستقل، ونتيجة كل منها تتبع القاعدة نفسها:

ما الذي تغيرأول خطوة أعيدتما أعيد بعدهاالبناء كله
سطر في server.jsCOPY . .لا شيء، فهي الأخيرة21 ثانية
حزمة جديدة في package.json وملف القفلCOPY api/package.json …npm ci في 108.2 ثانية، ثم COPY . .2 دقيقة و33 ثانية
سطر في healthcheck/main.goCOPY healthcheck/البناء، ثم npm ci في 18.9 ثانية رغم أن الحزم لم تتغير3 دقائق و15 ثانية

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

النسخة الثالثة: البناء متعدد المراحل Multi-stage Build

الفكرة بسيطة: ال Dockerfile الواحد يمكن أن يحتوي عدة تعليمات FROM، وكل واحدة تبدأ مرحلة Stage جديدة لها اسم، والمرحلة الأخيرة هي ال Image الناتجة، وتنسخ من المراحل السابقة ما تحتاجه فقط بالتعليمة COPY --from، وكل ما بقي في تلك المراحل لا يصل إلى ال Image، كما في وثائق البناء متعدد المراحل:

# v3: multi-stage. Build tools stay in the build stages; the runtime stage gets only what runs.
FROM golang:1.27-alpine AS healthcheck
WORKDIR /src
COPY healthcheck/ .
RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/healthcheck .

FROM node:24.22.1-alpine AS deps
WORKDIR /app
COPY api/package.json api/package-lock.json ./
RUN npm ci --omit=dev

FROM node:24.22.1-alpine
ENV NODE_ENV=production PORT=3000
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=healthcheck /out/healthcheck /usr/local/bin/healthcheck
COPY . .
USER node
EXPOSE 3000
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 CMD ["healthcheck"]
CMD ["node", "api/server.js"]

في الإعداد أعلاه لاحظ التالي:

  • المرحلة healthcheck: فيها مترجم Go 1.27 الحديث بدل 1.19 القديم من Debian، والخيار CGO_ENABLED=0 ينتج ملفاً ثابتاً Static Binary لا يحتاج أي مكتبة C، و-trimpath يحذف مسارات جهاز البناء من الملف، و-ldflags="-s -w" يحذف رموز التصحيح فيصغر الملف.
  • المرحلة deps: تثبت حزم الإنتاج فقط بالخيار --omit=dev، فلا يدخل eslint ولا غيره من أدوات التطوير.
  • المرحلة الأخيرة: تبدأ من node:24.22.1-alpine، وحجمها 62.8 ميجابايت مضغوطة مقابل 426 للنسخة الكاملة، ولا يوجد فيها مترجم ولا أدوات بناء.
  • المراحل تبنى بالتوازي: لاحظ في المخرج أدناه أن خطوتي npm ci وgo build تعملان في الوقت نفسه، لأن BuildKit يرى أن المرحلتين لا تعتمدان على بعضهما، فيبنيهما معاً، ويتجاهل أي مرحلة لا تحتاجها المرحلة الأخيرة.
  • USER وHEALTHCHECK وCMD بالصيغة exec: شرحنا كل واحدة منها في قسم مستقل بعد النتائج.
#13 [deps 4/4] RUN npm ci --omit=dev
#13 25.44 added 68 packages, and audited 69 packages in 19s
#13 DONE 26.7s
#12 [healthcheck 4/4] RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/healthcheck .
#12 DONE 71.8s
#16 [stage-2 5/5] COPY . .
#16 DONE 4.1s
#17 exporting layers 26.9s done
real	2m11.497s

البناء البارد نزل إلى دقيقتين و11 ثانية، والحجم إلى 152 ميجابايت مضغوطة بعد 641، وعدد الطبقات من 14 إلى 8. ولاحظ أن npm ci ثبت هنا 68 حزمة، بينما ثبت في النسخة الثانية 144 حزمة، والفرق كله أدوات التطوير. ولكن 152 ميجابايت ما زال رقماً أكبر من المتوقع لتطبيق بهذا الحجم.

ثلاث مراحل: المرحلة healthcheck من golang:1.27-alpine تبني الملف التنفيذي، والمرحلة deps من node:24.22.1-alpine تثبت حزم الإنتاج، والمرحلة الأخيرة تأخذ منهما بالتعليمة COPY --from الملف التنفيذي وnode_modules فقط، مع كود التطبيق والمستخدم node
المترجم وذاكرة npm يبقيان في مراحل البناء، وما يصل إلى السيرفر هو ما تنسخه COPY --from فقط

مفاجأة: الحزم التي لم نطلبها

لكي نعرف من أين جاء الحجم الزائد، نظرنا داخل ال Image:

docker run --rm --entrypoint sh ct2-d-orders:v3 -c 'ls /app/node_modules | wc -l; ls /app/api/node_modules | wc -l; ls -d /app/api/node_modules/eslint; du -sh /app/node_modules /app/api/node_modules /app/test /app/.git; head -1 /app/.env; node -e "console.log(require.resolve(\"express\",{paths:[\"/app/api\"]}))"'
65
127
/app/api/node_modules/eslint
4.4M	/app/node_modules
19.5M	/app/api/node_modules
51.5M	/app/test
40.3M	/app/.git
DB_PASSWORD=S3cret-from-dev-laptop
/app/api/node_modules/express/index.js

وهذه نتيجة لا يتوقعها من يقرأ ال Dockerfile. ففي ال Image مجلدان للحزم: /app/node_modules الذي ثبتته المرحلة deps بعناية، 65 مجلداً بحجم 4.4 ميجابايت، و/app/api/node_modules الذي جاء من جهاز المطور مع COPY . .، 127 مجلداً بحجم 19.5 ميجابايت وفيه eslint. والسطر الأخير هو الأهم: عندما يطلب التطبيق express فإن Node يبحث أولاً في node_modules الأقرب إلى الملف، فيجده في المجلد الذي جاء من الجهاز. أي أن التطبيق في الإنتاج يعمل بحزم ثبتت على جهاز المطور، بإصدارات قد تختلف عن ملف القفل، وربما لنظام تشغيل آخر إذا كان في الحزم ملفات مترجمة Native Modules، أما الحزم التي ثبتها البناء فلا يستخدمها أحد. ومعها ما زال .env و.git وبيانات الاختبار في ال Image.

والبناء متعدد المراحل لم يخطئ هنا، فقد فعل ما طلبناه بالضبط، والمشكلة في السطر COPY . . وفي سياق البناء الذي يحتوي كل شيء. وهذا ما تحله النسخة الرابعة.

النسخة الرابعة: ملف .dockerignore

الملف .dockerignore يوضع بجانب ال Dockerfile، ويكتب فيه ما يستثنى من سياق البناء بأنماط تشبه أنماط .gitignore، فلا يرسل الكلاينت هذه الملفات إلى BuildKit أصلاً، وبالتالي لا يستطيع أي COPY أن ينسخها حتى لو كتبت COPY . .. وهذا ملف التجربة:

# Everything the image does not need: keeps the build context small and secrets out of the image
.git
.env
.env.*
**/node_modules
test/
*.log
Dockerfile*
.dockerignore

في الإعداد أعلاه لاحظ التالي:

  • **/node_modules يستثني المجلد في أي مستوى، أما node_modules وحده فيستثني المجلد في جذر السياق فقط، وفي مشروعنا المجلد داخل api/، فلو كتبناه دون **/ لبقيت المشكلة كما هي.
  • .env.* يغطي .env.local و.env.production وأمثالها، وهي الملفات التي ينساها الناس.
  • استثناء Dockerfile* و.dockerignore لا يمنع البناء، فإن BuildKit يقرأ ال Dockerfile بطريق مستقل، والاستثناء يمنع فقط نسخهما إلى ال Image، ويمنع أن يبطل تعديل ال Dockerfile طبقة COPY.
  • ويمكن أن يكون لكل Dockerfile ملف استثناء خاص به بالاسم Dockerfile.v4.dockerignore بجانبه، فيستخدمه BuildKit بدل الملف العام، وهذا مفيد عندما يكون في المستودع أكثر من Dockerfile لأغراض مختلفة، كما في وثائق سياق البناء.

ومع الملف غيرنا أيضاً COPY . . في المرحلة الأخيرة إلى COPY api/ ./، أي أننا ننسخ المجلد الذي يحتاجه التطبيق بالاسم، وCMD ["node", "server.js"]. فالملف .dockerignore شبكة أمان تمنع ما لم تفكر فيه، والنسخ بالاسم هو الذي يحدد ما تريده، وتحتاج الاثنين، لأن أحداً سوف يضيف يوماً ملفاً جديداً حساساً إلى المجلد ولن يتذكر أن يضيفه إلى .dockerignore.

ولكي نقيس أثر الملف على السياق بدقة، بنينا النسخة نفسها من نسخة جديدة من المجلد لم يرها BuildKit من قبل، مرة دون .dockerignore ومرة معه:

# a fresh copy of the folder, no .dockerignore, Dockerfile.v3
#5 transferring context: 110.72MB 32.3s done
# a fresh copy of the folder, with .dockerignore, Dockerfile.v3
#5 transferring context: 73.08kB 0.0s done

# Dockerfile.v4 (COPY api/ ./) with and without .dockerignore
ct2-d-ctx:a4 294MB     (no .dockerignore)
ct2-d-ctx:b4 270MB     (with .dockerignore)

السياق نزل من 110.72 ميجابايت في 32 ثانية إلى 73 كيلوبايت في لحظة، أي إلى ما يحتاجه البناء فعلاً. والسطران الأخيران يبينان لماذا تحتاج الملف حتى مع النسخ بالاسم: النسخة الرابعة دون .dockerignore خرجت أكبر، لأن COPY api/ ./ نسخ معه api/node_modules من جهاز المطور، فاندمج فوق المجلد الذي ثبتته المرحلة deps، وظهر eslint في ال Image مرة أخرى، و141 مجلداً في node_modules بدل 79. فالنسخ بالاسم وحده لا يكفي إذا كان داخل المجلد الذي تنسخه شيء لا تريده.

وعلى Windows ظهرت مشكلة إضافية قبل كل هذا، فعندما بنينا النسخة الأولى من مجلد على قرص Windows توقف البناء في مرحلة إرسال السياق بالخطأ invalid file request api/node_modules/.bin/eslint، لأن المجلد .bin فيه روابط رمزية Symlinks أنشأها npm داخل Container Linux، ولم يستطع الكلاينت على Windows أن يرسلها. ومع .dockerignore لا يحاول الكلاينت أن يرسل node_modules أصلاً، فتختفي المشكلة.

مجلد المشروع على جهاز المطور فيه api وhealthcheck باللون الأخضر، وnode_modules وtest/fixtures و.git و.env وnpm-debug.log باللون الأحمر، يمر عبر ملف .dockerignore الذي يستثني الأحمر قبل الإرسال إلى BuildKit، فيصل دونه 110.66 ميجابايت ومعه بضعة كيلوبايتات
ملف .dockerignore يعمل قبل الإرسال، فما يستثنيه لا يصل إلى BuildKit ولا يمكن لأي COPY أن ينسخه

ثم تحققنا من ال Image نفسها:

$ docker run --rm --entrypoint sh ct2-d-orders:v4 -c 'ls -a /app; ls /app/node_modules | wc -l; ls -d /app/node_modules/eslint; cat /app/.env; node -e "console.log(require.resolve(\"express\",{paths:[\"/app\"]}))"'
.
..
node_modules
package-lock.json
package.json
server.js
79
ls: /app/node_modules/eslint: No such file or directory
cat: can't open '/app/.env': No such file or directory
/app/node_modules/express/index.js

الآن يحتوي /app ما يحتاجه التطبيق فقط: الكود وملفا الحزم ومجلد node_modules واحد ثبته البناء، ولا يوجد eslint، ولا .env، ولا .git، و Node يجد express في المكان الصحيح. والحجم نزل من 152 ميجابايت مضغوطة إلى 66، أي أن أكثر من نصف حجم النسخة الثالثة كان ملفات لم يطلبها أحد. والبناء الدافئ بعد تعديل السطر نفسه في server.js أخذ 3.7 ثانية، لأن طبقة الكود الآن 90 كيلوبايت بدل 117 ميجابايت، فلا يوجد ما يضغط.

النسخة الخامسة: BuildKit Cache Mounts

بقيت مشكلة واحدة في النسخة الرابعة: عندما يتغير ملف القفل، ولو بحزمة واحدة، تعاد خطوة npm ci كاملة، فتنزل كل الحزم من الشبكة من جديد، لأن ذاكرة npm المؤقتة ~/.npm كانت داخل طبقة قديمة أبطلت. والأمر نفسه مع Go، فكل تعديل في main.go يعيد ترجمة المكتبة القياسية كلها، ومنها حزمة net/http الكبيرة، لأن ذاكرة الترجمة ~/.cache/go-build ضاعت مع الطبقة. والحل هو ال Cache Mount: مجلد يربطه BuildKit بخطوة RUN أثناء تنفيذها فقط، ويحفظه بين البناءات خارج طبقات ال Image، كما في وثائق تحسين ال Cache:

# syntax=docker/dockerfile:1
# v5: v4 plus BuildKit cache mounts: the npm and Go caches survive between builds without entering the image
FROM golang:1.27-alpine AS healthcheck
WORKDIR /src
COPY healthcheck/ .
RUN --mount=type=cache,id=orders-gobuild,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/healthcheck .

FROM node:24.22.1-alpine AS deps
WORKDIR /app
COPY api/package.json api/package-lock.json ./
RUN --mount=type=cache,id=orders-npm,target=/root/.npm \
    npm ci --omit=dev --prefer-offline --no-audit --no-fund

FROM node:24.22.1-alpine
ENV NODE_ENV=production PORT=3000
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=healthcheck /out/healthcheck /usr/local/bin/healthcheck
COPY api/ ./
USER node
EXPOSE 3000
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 CMD ["healthcheck"]
CMD ["node", "server.js"]

في الإعداد أعلاه لاحظ التالي:

  • السطر الأول # syntax=docker/dockerfile:1 يطلب أحدث إصدار مستقر من صيغة Dockerfile من السلسلة الأولى، فيعمل الملف بالميزات نفسها على أي محرك حديث.
  • id=orders-npm اسم ال Cache Mount، فكل خطوة في أي Dockerfile على المحرك نفسه تستخدم الاسم نفسه تشارك الذاكرة نفسها. والاسم الصريح يمنع أن يختلط مشروعك بمشروع آخر على سيرفر البناء نفسه.
  • --prefer-offline يجعل npm يأخذ الحزمة من الذاكرة إذا كانت فيها، ولا يسأل ال Registry إلا عن الجديدة.
  • محتوى ال Cache Mount لا يدخل ال Image، فحجم النسخة الخامسة هو حجم الرابعة بالضبط.

ولنرى الفرق أضفنا مكتبة السجلات pino إلى الحزم، وعدلنا سطراً في main.go، أي تغييراً في الاعتماديات وتغييراً في الكود المترجم معاً، ثم بنينا النسختين الرابعة والخامسة بعد أن بنيت كل منهما من قبل:

== Dockerfile.v4 (no cache mounts)
#12 [healthcheck 4/4] RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/healthcheck .
#12 DONE 110.7s
#13 [deps 4/4] RUN npm ci --omit=dev
#13 12.36 added 82 packages, and audited 83 packages in 11s
real	3m29.618s

== Dockerfile.v5 (cache mounts)
#14 [healthcheck 4/4] RUN --mount=type=cache,id=orders-gobuild,target=/root/.cache/go-build ...
#14 DONE 5.5s
#15 [deps 4/4] RUN --mount=type=cache,id=orders-npm,target=/root/.npm ...
#15 17.04 added 82 packages in 15s
real	0m28.067s

في المخرج أعلاه لاحظ التالي:

  • الفرق الكبير جاء من Go: الترجمة نزلت من 110.7 ثانية إلى 5.5، لأن المترجم وجد المكتبة القياسية وحزمة net/http مترجمة في ال Cache Mount من البناء السابق، فترجم ملفنا الصغير وحده. والبناء كله نزل من ثلاث دقائق ونصف إلى 28 ثانية.
  • أما npm فلم يستفد هنا، فقد كتب in 11s دون ذاكرة وin 15s معها، والسبب أن npm ci يحذف node_modules ويفك كل الحزم ويكتبها من جديد في الحالتين، والذاكرة توفر التنزيل فقط، والتنزيل لمشروع فيه 82 حزمة على اتصال سريع جزء صغير من الوقت. والفائدة تظهر مع المشاريع التي فيها مئات الحزم، أو على سيرفر بناء باتصال بطيء أو محدود، أو عندما يكون ال Registry نفسه بطيئاً أو معطلاً.
  • والفرق بين وقت الخطوة كما يحسبه npm ووقتها في سطر DONE هو وقت تجهيز ال Container الخاص بالخطوة وكتابة الطبقة، ويكبر عندما يكون الجهاز مشغولاً ببناءات أخرى.
BuildKit يحفظ ال Cache Mount بالاسم orders-gobuild في المجلد /root/.cache/go-build خارج طبقات ال Image، فعندما تغير main.go وأعيدت خطوة go build وجد المكتبة القياسية مترجمة، فنزلت الخطوة من 110.7 ثانية إلى 5.5، ولم يتغير وقت npm ci تقريباً، 11 ثانية دون الذاكرة و15 معها
ال Cache Mount يعيش في BuildKit وليس في ال Image، فتعاد الخطوة ولكن دون أن تبدأ من الصفر، والفائدة الكبيرة هنا كانت في ترجمة Go

وماذا عن خط CI؟ Cache Backends

كل ما سبق عن ال Cache يعمل على جهاز يحتفظ ب BuildKit بين البناءات، مثل جهازك أو سيرفر بناء ثابت. أما في خط CI الذي يبدأ كل مهمة على Runner جديد فارغ، فلا توجد طبقات قديمة ولا Cache Mounts، وكل بناء بارد. والحل أن تحفظ ال Build Cache خارج ال Runner، فيصدره البناء في آخره ويستورده البناء التالي في أوله، بالخيارين --cache-to و--cache-from، وأشهر مكان لحفظه هو ال Registry نفسه:

docker buildx build \
  --cache-from type=registry,ref=registry.example.com/orders:buildcache \
  --cache-to type=registry,ref=registry.example.com/orders:buildcache,mode=max \
  -t registry.example.com/orders:1.4.0 --push .

والخيار mode=max يصدر طبقات كل المراحل وليس المرحلة الأخيرة فقط، وهو ما تحتاجه مع البناء متعدد المراحل، لأن طبقة npm ci في المرحلة deps لا تظهر في ال Image النهائية. والخيارات وأماكن الحفظ الأخرى في وثائق Cache Backends. ولاحظ أن ال Cache Mounts لا تدخل في هذا التصدير، كما تذكر وثائق ال Cache في GitHub Actions التي تقترح حلاً التفافياً لذلك، فهي مصممة لسيرفر البناء الثابت، ولذلك يبقى ترتيب الطبقات وفصل المراحل هو الأهم في خط CI. وقد شرحنا بناء ال Images ورفعها من خط CI على سيرفرك في Gitea Actions.

النتائج في جدول واحد Results

هذه أرقام النسخ الخمس من الجولة الأخيرة، وكلها للتطبيق نفسه بالحزم نفسها:

النسخةCONTENT SIZEDISK USAGEالطبقاتبناء باردبعد تعديل سطر
v1 البسيطة641MB2.51GB148m 26s4m 48s
v2 ترتيب الطبقات632MB2.51GB156m 24s21s
v3 متعدد المراحل152MB460MB82m 11s23s
v4 مع .dockerignore66MB261MB81m 36s3.7s
v5 مع Cache Mounts66MB261MB81m 56s6.9s
ثلاثة رسوم أعمدة للنسخ الخمس: الحجم المضغوط 641 و632 و152 و66 و66 ميجابايت، والبناء البارد 506 و384 و132 و96 و116 ثانية، والبناء بعد تعديل سطر 288 و21 و23 و3.7 و6.9 ثانية
الحجم نزل من 641 إلى 66 ميجابايت مضغوطة بالمراحل و.dockerignore، والبناء الدافئ نزل بترتيب الطبقات

في الجدول أعلاه لاحظ التالي:

  • الحجم نزل في خطوتين فقط: البناء متعدد المراحل أخرج المترجم وال Base Image الكاملة، و.dockerignore أخرج ما نسخ من الجهاز. أما ترتيب الطبقات وال Cache Mounts فلا يغيران الحجم، وهذا متوقع، فهما يغيران وقت البناء.
  • البناء بعد تعديل سطر، وهو الرقم الذي يهمك كل يوم، نزل من خمس دقائق تقريباً إلى 21 ثانية بترتيب الطبقات وحده، أي بتغيير ترتيب أربعة أسطر، ثم إلى أقل من 4 ثوان مع .dockerignore.
  • النسخة الخامسة كانت أبطأ قليلاً من الرابعة في البناء البارد والدافئ، والسبب السطر # syntax=docker/dockerfile:1 الذي يجعل BuildKit يسأل Docker Hub عن أحدث إصدار للصيغة في كل بناء، وفرق ثانيتين أو ثلاث في بناءات على جهاز واحد لا يعني الكثير. وفائدتها ظهرت في الحالة التي صممت لها: تغيير الاعتماديات والكود المترجم، حيث نزلت من ثلاث دقائق ونصف إلى 28 ثانية.
  • عدد الطبقات زاد في النسخة الثانية رغم أنها أفضل، فعدد الطبقات وحده ليس مقياساً، والمهم ما في كل طبقة وكم مرة تتغير. ونصيحة دمج كل الأوامر في سطر RUN واحد لتقليل الطبقات قديمة، من أيام كان فيها عدد الطبقات محدوداً، وهي تضر بال Cache إذا جمعت ما يتغير مع ما لا يتغير.

ARG أم ENV؟ متغيرات البناء Build Arguments ومتغيرات البيئة Environment Variables

التعليمتان تعرفان متغيراً، ولكن عمر كل متغير مختلف، وهذا هو الفرق كله. فالمتغير ARG يعيش أثناء البناء فقط، وتعطيه قيمته عند البناء بالخيار --build-arg، وتراه تعليمات RUN التي بعده في المرحلة نفسها، ثم لا يبقى في ال Container عند التشغيل. أما ENV فيكتب في إعدادات ال Image، فيراه البناء بعد تعريفه، ويراه التطبيق عند التشغيل، ويمكن تغييره عند التشغيل بالخيار -e أو بملف Compose، كما في وثائق متغيرات البناء. والاستخدام الشائع أن تجمع بينهما: ARG ليأخذ القيمة من خط CI، وENV ليحفظها في ال Image، مثل رقم الإصدار:

ARG NODE_TAG=24.22.1
FROM node:${NODE_TAG}-alpine
ARG NPM_TOKEN
ARG APP_VERSION=1.0.0
ENV APP_VERSION=${APP_VERSION}
RUN echo "node arg inside the stage: [${NODE_TAG}]"
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /root/.npmrc \
 && echo "npm ci would run here" && rm /root/.npmrc

بنينا هذا الملف بالأمر docker build --build-arg NPM_TOKEN=npm_FAKEtoken123 --build-arg APP_VERSION=1.4.2 -t ct2-d-argdemo .، والمخرج سوف يكون كما يلي، أولاً من خطوة RUN الأولى ثم من إعدادات ال Image ومن Container يعمل بها:

#5 2.214 node arg inside the stage: []
["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin","NODE_VERSION=24.22.1","YARN_VERSION=1.22.22","APP_VERSION=1.4.2"]
APP_VERSION=1.4.2 NPM_TOKEN=[]

في المخرج أعلاه لاحظ التالي:

  • المتغير NODE_TAG المعرف قبل FROM فارغ داخل المرحلة، لأن ARG قبل FROM يصلح لسطر FROM فقط، فإذا أردته داخل المرحلة فأعد تعريفه بسطر ARG NODE_TAG بلا قيمة بعد FROM.
  • وفي المحاولة الأولى سمينا المتغير NODE_VERSION، فطبع السطر نفسه [24.22.1] وكدنا نستنتج العكس، والسبب أن ال Image الرسمية لـ Node تعرف متغير بيئة بالاسم نفسه بالتعليمة ENV، وهو الذي ظهر وليس ARG. لذلك اختر لمتغيرات البناء أسماء لا تتعارض مع ما تعرفه ال Base Image.
  • APP_VERSION وصل إلى ال Container لأنه نسخ إلى ENV، أما NPM_TOKEN فلا يظهر عند التشغيل، وقد يظن البعض أن هذا يجعله مكاناً آمناً للأسرار، وهذا غير صحيح كما في القسم التالي.

لماذا لا تمرر Token أو كلمة مرور عبر ARG؟

لأن قيمة ARG تحفظ في تاريخ ال Image نفسها. فكل سطر RUN يسجل معه قيم ال Build Arguments التي استخدمها، ويستطيع أي شخص يسحب ال Image أن يقرأها بالأمر docker history كما في وثائق docker history:

docker history --no-trunc --format "{{.CreatedBy}}" ct2-d-argdemo | head -4
RUN |2 NPM_TOKEN=npm_FAKEtoken123 APP_VERSION=1.4.2 /bin/sh -c echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /root/.npmrc  && echo "npm ci would run here" && rm /root/.npmrc # buildkit
RUN |2 NPM_TOKEN=npm_FAKEtoken123 APP_VERSION=1.4.2 /bin/sh -c echo "node arg inside the stage: [${NODE_TAG}]" # buildkit
ENV APP_VERSION=1.4.2
ARG APP_VERSION=1.4.2

ال Token مكتوب بنصه في السطرين الأولين، رغم أننا حذفنا الملف .npmrc في السطر نفسه الذي أنشأه، ورغم أنه لا يظهر في ال Container. ولاحظ الجزء |2 في أول السطر، وهو عدد ال Build Arguments التي دخلت في هذه الخطوة. وقبل البناء نفسه حذرنا BuildKit من ذلك بقاعدة الفحص SecretsUsedInArgOrEnv، فقد ظهر هذا التحذير عند البناء: Do not use ARG or ENV instructions for sensitive data (ARG "NPM_TOKEN")، ولكنه تحذير وليس خطأ، فلا يوقف البناء.

والطريقة الصحيحة هي ال Secret Mount، حيث يعطي BuildKit السر لخطوة RUN واحدة كملف أو متغير بيئة أثناء تنفيذها فقط، ولا يكتبه في أي طبقة ولا في التاريخ، كما في وثائق Build Secrets:

# syntax=docker/dockerfile:1
FROM node:24.22.1-alpine
RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN \
    echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /root/.npmrc \
 && echo "token length: ${#NPM_TOKEN}" && rm /root/.npmrc
export NPM_TOKEN=npm_FAKEtoken123
docker build --secret id=npm_token,env=NPM_TOKEN -f Dockerfile.secret -t ct2-d-argdemo:secret .
docker history --no-trunc --format "{{.CreatedBy}}" ct2-d-argdemo:secret | head -1
#7 4.655 token length: 16
RUN /bin/sh -c echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > /root/.npmrc  && echo "token length: ${#NPM_TOKEN}" && rm /root/.npmrc # buildkit

الخطوة رأت ال Token بطوله الصحيح، 16 حرفاً، والتاريخ يحتوي نص الأمر فقط دون أي قيمة. ولاحظ أن حذف .npmrc في السطر نفسه ما زال مهماً هنا، لأن الملف الذي تكتبه أنت بيدك يدخل في الطبقة كأي ملف آخر، أما السر الذي يضعه BuildKit فلا يدخل. وقد شرحنا في اكتشاف الأسرار المسربة كيف تبحث عن الأسرار التي وصلت إلى طبقات Images قديمة، وماذا تفعل إذا وجدتها.

🔑
في أبريل 2021 أعلنت شركة Codecov أن مهاجماً عدل سكربت Bash Uploader الذي يشغله آلاف العملاء داخل خطوط CI، فصار يرسل متغيرات البيئة في هذه الخطوط، بما فيها من Tokens ومفاتيح، إلى سيرفر المهاجم لمدة شهرين تقريباً. وذكرت الشركة في بيانها عن الحادثة أن المهاجم وصل إلى ذلك بسبب خطأ في طريقة إنشاء ال Docker Image الخاصة بها سمح له باستخراج بيانات الدخول التي يحتاجها لتعديل السكربت. والدرس أن ال Image التي تنشرها تعامل كأنها علنية، وأن أي سر دخل إلى إحدى طبقاتها أو تاريخها يجب أن يعتبر مكشوفاً ويغير فوراً.

ENTRYPOINT وCMD: الصيغة exec والصيغة shell

التعليمتان تحددان ما يعمل عندما يبدأ ال Container، والفرق بينهما في الدور. فالتعليمة ENTRYPOINT هي البرنامج الثابت، والتعليمة CMD هي القيمة الافتراضية التي تضاف بعده ويمكن استبدالها من سطر الأوامر. فإذا كان في ال Image السطران ENTRYPOINT ["docker-entrypoint.sh"] وCMD ["node"]، وهو بالضبط ما في Image Node الرسمية، فإن الأمر docker run image يشغل docker-entrypoint.sh node، والأمر docker run image node server.js يستبدل CMD فقط فيشغل docker-entrypoint.sh node server.js، ولا يتغير ENTRYPOINT إلا بالخيار --entrypoint. والسكربت docker-entrypoint.sh في Node يجهز بعض الأشياء ثم يشغل ما وصله بالأمر exec، فيحل البرنامج محل السكربت ولا يبقى السكربت عملية وسيطة.

ولكل تعليمة صيغتان، والفرق بينهما أهم مما يبدو، كما في مرجع Dockerfile:

  • الصيغة exec: مصفوفة JSON مثل CMD ["node", "server.js"]، فيشغل Docker البرنامج مباشرة، ويصبح البرنامج العملية الأولى PID 1 في ال Container. ولا يوجد Shell، فلا تعمل فيها المتغيرات مثل $PORT ولا &&، لأن من يفهم هذه الرموز هو ال Shell.
  • الصيغة shell: نص عادي مثل CMD cd api && npm start، فيحوله Docker إلى /bin/sh -c "cd api && npm start"، ويصبح ال Shell هو PID 1، وتطبيقك عملية فرعية تحته.

وهنا يدخل موضوع الإشارات Signals. فعندما تكتب docker stop يرسل Docker الإشارة SIGTERM إلى PID 1 وحده، ثم ينتظر مهلة، فإذا لم يخرج ال Container أرسل SIGKILL الذي لا يمكن تجاهله، كما في وثائق docker stop. والمهلة الافتراضية 10 ثوان على Linux. وللعملية PID 1 في Linux وضع خاص، فالنواة لا تطبق عليها السلوك الافتراضي للإشارات، فإذا لم يسجل البرنامج معالجاً Handler للإشارة SIGTERM فإنها تتجاهلها ببساطة، بينما أي عملية أخرى كانت ستموت بها. وهذا يجعل السؤال «من هو PID 1؟» سؤالاً عملياً جداً.

تجربة: من يستقبل SIGTERM؟

شغلنا التطبيق نفسه بخمس طرق، وفي كل مرة عرضنا العمليات داخل ال Container بالأمر ps، ثم أوقفناه بالأمر docker stop -t 10، وقسنا الوقت من إرسال SIGTERM إلى خروج ال Container من أحداث المحرك docker events. والكود في server.js لا يسجل معالجاً للإشارة إلا إذا كان المتغير HANDLE_SIGTERM=1:

if (process.env.HANDLE_SIGTERM === '1') {
  process.on('SIGTERM', () => {
    console.log('SIGTERM received, closing server');
    server.close(() => process.exit(0));
  });
}

وهذه شجرة العمليات مع الصيغة shell، أي النسخة الأولى كما هي:

  PID  PPID USER     COMMAND
    1     0 root     /bin/sh -c cd api && npm start
    8     1 root     npm start
   19     8 root     sh -c node server.js
   20    19 root     node server.js

أربع عمليات، وتطبيقنا هو الأخير منها برقم 20، وبينه وبين الإشارة ثلاث عمليات. والنتائج الخمس كانت كما يلي:

طريقة التشغيلPID 1من SIGTERM إلى الخروجرمز الخروج
CMD cd api && npm start (shell)/bin/sh -c12.0 ثانية، وSIGKILL بعد 10.1137
["npm", "start"] (exec)npm start2.8 ثانية1
["node", "server.js"] دون معالجnode12.9 ثانية، وSIGKILL137
["node", "server.js"] مع معالجnode1.9 ثانية0
docker run --init دون معالجdocker-init1.7 ثانية143
أربع حالات لإيقاف ال Container: الصيغة shell حيث PID 1 هو sh ولا تصل الإشارة إلى node فيقتل بعد المهلة، والصيغة exec دون معالج حيث node هو PID 1 ويتجاهل الإشارة، والصيغة exec مع معالج حيث يغلق التطبيق ويخرج بالرمز 0، وdocker run --init حيث يمرر tini الإشارة إلى node فيخرج بالرمز 143
الإشارة تصل إلى PID 1 وحده، والنتيجة تعتمد على من يكون PID 1 وماذا يفعل بها

في النتائج أعلاه لاحظ التالي:

  • الصيغة shell: ال Shell تلقى الإشارة ولم يمررها إلى أحد، وبقي التطبيق يعمل حتى انتهت المهلة، فقتله Docker بالإشارة SIGKILL، والرمز 137 يعني 128 + 9، أي أنه مات بالإشارة 9. أي أن كل إيقاف أو تحديث لهذا ال Container يأخذ عشر ثوان، ويقطع الطلبات الجارية في منتصفها بدل أن ينهيها.
  • npm في الصيغة exec: npm نفسه مرر الإشارة إلى العملية الفرعية فخرج التطبيق سريعاً، ولكن npm خرج بالرمز 1 وكتب في السجل npm error signal SIGTERM وnpm error command failed، فكل إيقاف عادي يظهر في السجلات كخطأ، ويربك أي نظام مراقبة يعد الأخطاء. وهذا سبب إضافي لأن يكون CMD هو node مباشرة وليس npm start.
  • node دون معالج: هذه الحالة تفاجئ كثيرين، فتطبيقنا هو PID 1 هذه المرة، والإشارة وصلته فعلاً، ولكنه تجاهلها لأنه PID 1 ولا يوجد معالج مسجل، فانتظر Docker المهلة وقتله. أي أن الصيغة exec وحدها لا تكفي، فهي توصل الإشارة إلى تطبيقك، وتطبيقك يجب أن يعرف ماذا يفعل بها.
  • node مع معالج: التطبيق أغلق السيرفر وأنهى الطلبات الجارية وخرج بالرمز 0، وهذه هي الحالة الصحيحة، وقد شرحنا ما يجب أن يفعله المعالج في الإيقاف النظيف Graceful Shutdown.
  • الخيار --init: وضع Docker عملية init صغيرة مبنية على tini في مكان PID 1، فأصبح التطبيق عملية عادية برقم 7، فمرر tini الإشارة إليه، فمات بالسلوك الافتراضي سريعاً بالرمز 143، أي 128 + 15. وهذا حل جيد للبرامج التي لا تستطيع تعديلها، وهو أيضاً ينظف العمليات المنتهية Zombie Processes التي يتركها برنامج يشغل عمليات فرعية. وفي Compose يقابله السطر init: true.
⏱️
إذا جربت هذا على Docker Desktop فقد تجد أن docker stop يقتل التطبيق بعد 3 ثوان وليس 10، والسبب أن Docker Desktop يضع في إعداد المحرك القيمة "default-stop-timeout": 3، بينما القيمة الافتراضية لـ Docker Engine على سيرفرات Linux هي 10 ثوان. لذلك اكتب المهلة صراحة عندما تقيس، بالخيار -t، أو في Compose بالخاصية stop_grace_period، حتى يكون سلوك جهازك مثل سلوك السيرفر.

ومتى تستخدم ENTRYPOINT إذن؟ عندما تكون ال Image أداة لها أمر واحد، مثل أداة سطر أوامر تريد أن تمرر لها الخيارات مباشرة: docker run my-tool --help، أو عندما تحتاج سكربت بدء يجهز شيئاً قبل التطبيق، مثل انتظار قاعدة البيانات أو كتابة ملف إعداد من متغيرات البيئة. وفي الحالة الثانية يجب أن ينتهي السكربت بالسطر exec "$@"، لكي يحل التطبيق محل السكربت ويصبح هو PID 1، وإلا عادت مشكلة ال Shell التي لا يمرر الإشارات. وتنبهك أداة الفحص في BuildKit إلى الصيغة shell بقاعدة JSONArgsRecommended كما سنرى بعد قليل.

USER: لا تشغل التطبيق بالمستخدم root

إذا لم تكتب التعليمة USER فكل شيء في ال Container يعمل بالمستخدم root، وهذا ما رأيناه في النسخة الأولى: uid=0(root). صحيح أن root داخل ال Container محاط بقيود Namespaces وCapabilities، ولكنه ما زال root على الملفات التي يراها، وعلى أي مجلد من السيرفر ربطته بال Container، وأي ثغرة تسمح بالخروج من ال Container تبدأ عندها بصلاحيات root. لذلك فالقاعدة أن يعمل التطبيق بمستخدم عادي، وأغلب ال Images الرسمية فيها مستخدم جاهز، مثل المستخدم node برقم 1000 في Image Node، فيكفي السطر USER node قبل CMD.

وانتبه إلى ترتيب الصلاحيات. فالملفات التي تنسخها بالتعليمة COPY تكون ملكاً لل root ما لم تكتب --chown، وهذا جيد للكود، لأن التطبيق يقرؤه ولا يحتاج أن يغيره، فإذا استطاع مخترق أن ينفذ أوامر بصلاحيات التطبيق فلن يستطيع أن يعدل الكود نفسه. وهذا ما ظهر عندما حاولنا الكتابة داخل النسخة الرابعة:

uid=1000(node) gid=1000(node) groups=1000(node),1000(node)
-rw-r--r--    1 root     root           989 Nov 18 16:20 server.js
touch: /app/x: Permission denied

أما إذا كان التطبيق يحتاج أن يكتب فعلاً، مثل ملفات الرفع أو ملفات مؤقتة، فلا تعطه ملكية /app كلها، وإنما أنشئ له مجلداً واحداً بملكيته، أو الأفضل أن تجعل هذا المجلد Volume، لأن ما يكتب داخل ال Container يضيع عند حذفه. والتفاصيل الأعمق، مثل تشغيل ال Container بنظام ملفات للقراءة فقط وإسقاط ال Capabilities، تجدها في المقالات التالية من هذه المرحلة.

دليلتقليل حجم ال Docker Images وتأمينها Hardeningكيف تبني Image فيها ما يحتاجه تطبيقك فقط، وتقيس الفرق بين slim وalpine وdistroless وscratch بالحجم والثغرات، ثم تشغلها بمستخدم عادي وتوقعها قبل النشر.دليلبيانات ال Containers: Volumes وBind Mounts والنسخ الاحتياطيأين تذهب ملفات ال Container وما الذي يحذفها، مع قياس حقيقي لسرعة مسارات Windows وLinux ونسخة احتياطية مستعادة لملفات Volume وقاعدة PostgreSQL.

HEALTHCHECK: هل التطبيق سليم فعلاً؟

عندما يبدأ ال Container يعتبره Docker «يعمل» ما دامت العملية الأولى حية، حتى لو كان التطبيق داخلها عالقاً أو لا يستمع على المنفذ الصحيح أو فقد اتصاله بقاعدة البيانات. والتعليمة HEALTHCHECK تضيف سؤالاً دورياً: أمر يشغله Docker داخل ال Container كل فترة، فإذا خرج بالرمز 0 فال Container سليم healthy، وإذا فشل عدة مرات متتالية أصبح unhealthy، كما في مرجع Dockerfile في قسم HEALTHCHECK. وهذه الحالة يقرؤها docker ps، ويقرؤها Compose في الشرط condition: service_healthy، ويقرؤها الأمر docker compose up --wait قبل أن يعلن نجاح النشر.

والطريقة المنتشرة أن يكون الأمر curl -f http://localhost:3000/health، وهذه تعمل إذا كان curl موجوداً في ال Image، وهو غير موجود في Image Node المبنية على Alpine، وغير موجود في Images مثل distroless التي لا يوجد فيها Shell أصلاً. وتثبيت curl في Image الإنتاج من أجل فحص الصحة وحده يضيف برنامجاً شبكياً كاملاً ومكتباته وثغراته المحتملة. لذلك كتبنا في التجربة ملفاً صغيراً بلغة Go يطلب /health ويخرج بالرمز 0 أو 1، وبنيناه في مرحلة مستقلة، فوصل إلى ال Image ملف واحد حجمه 5.9 ميجابايت، ثابت لا يحتاج أي مكتبة، ويعمل في أي Image حتى scratch. والسطر في ال Dockerfile:

HEALTHCHECK --interval=10s --timeout=3s --start-period=5s --retries=3 CMD ["healthcheck"]

في الإعداد أعلاه لاحظ التالي:

  • --interval=10s: الفحص كل 10 ثوان، والقيمة الافتراضية 30 ثانية.
  • --timeout=3s: إذا لم ينته الأمر خلال 3 ثوان يعتبر فاشلاً، لذلك جعلنا مهلة الطلب داخل البرنامج نفسه أقل منها.
  • --start-period=5s: الفشل في الثواني الأولى لا يحسب، لكي لا يعتبر تطبيق بطيء البدء معطلاً قبل أن يكمل تشغيله.
  • --retries=3: ثلاث محاولات فاشلة متتالية قبل أن تصبح الحالة unhealthy، حتى لا يغير طلب واحد بطيء حالة ال Container.
  • الأمر بالصيغة exec، فلا يحتاج Shell داخل ال Image.

ثم نظرنا ماذا يحدث إذا كان التطبيق يعمل ولكن ليس كما نتوقع، فشغلنا Container سليماً وآخر بالمتغير PORT=4000، فيستمع التطبيق على 4000 بينما الفحص يطلب 3000، وهي حالة تحدث فعلاً عندما يتغير متغير في ملف Compose ولا يتغير الفحص معه:

docker run -d --name ct2-d-ok ct2-d-orders:v4
docker run -d --name ct2-d-bad -e PORT=4000 ct2-d-orders:v4
docker ps --filter name=ct2-d-ok --filter name=ct2-d-bad --format 'table {{.Names}}\t{{.Status}}'
# after about 50 seconds
docker ps --filter name=ct2-d-ok --filter name=ct2-d-bad --format 'table {{.Names}}\t{{.Status}}'
docker inspect ct2-d-bad --format '{{json .State.Health}}'
docker inspect ct2-d-bad -f 'restarts={{.RestartCount}} running={{.State.Running}}'
NAMES       STATUS
ct2-d-bad   Up 4 seconds (health: starting)
ct2-d-ok    Up 7 seconds (healthy)

NAMES       STATUS
ct2-d-bad   Up 55 seconds (unhealthy)
ct2-d-ok    Up 58 seconds (healthy)

{"Status":"unhealthy","FailingStreak":5,"Log":[
 {"Start":"2026-11-18T17:06:54.75496973Z","End":"2026-11-18T17:06:54.973082745Z","ExitCode":1,
  "Output":"unhealthy: Get \"http://127.0.0.1:3000/health\": dial tcp 127.0.0.1:3000: connect: connection refused
"},
 … four more entries, ten seconds apart …]}

restarts=0 running=true

في المخرج أعلاه لاحظ التالي:

  • في البداية كانت الحالة health: starting، ثم أصبحت unhealthy بعد ثلاث محاولات فاشلة، بينما بقي ال Container الآخر healthy.
  • الحقل FailingStreak هو عدد المحاولات الفاشلة المتتالية، والحقل Log يحفظ آخر خمس محاولات مع وقت كل منها ورمز خروجها ومخرجها.
  • المخرج connection refused يقول السبب مباشرة. وفي النسخة الأولى من برنامج الفحص لم نكن نطبع شيئاً، فكان الحقل Output فارغاً في كل المحاولات، ولا تعرف منه هل المشكلة في المنفذ أم في المهلة أم في رد التطبيق، فأضفنا سطراً يطبع الخطأ. لذلك اجعل أمر الفحص يقول لماذا فشل.
  • والأهم أن RestartCount بقي 0 والحالة running=true: فحالة unhealthy وحدها لا تجعل Docker يعيد تشغيل ال Container، فهي معلومة لمن يقرؤها، مثل Compose وأدوات المراقبة وخطوة النشر. أما إعادة التشغيل التلقائية عند unhealthy فهي من سلوك Docker Swarm وKubernetes، وليست من سلوك المحرك وحده.

وفحص الصحة الجيد خفيف وسريع، ويسأل التطبيق نفسه ولا يسأل كل ما يعتمد عليه. فإذا جعلت /health يفحص قاعدة البيانات، ثم تأخرت قاعدة البيانات ثانيتين، أصبحت كل Containers التطبيق unhealthy في اللحظة نفسها، وقد يعيد منسق مثل Kubernetes تشغيلها كلها معاً، فتتحول مشكلة صغيرة في قاعدة البيانات إلى توقف كامل.

فحص ال Dockerfile قبل البناء: docker build --check

منذ Buildx 0.15 وصيغة Dockerfile 1.8 يستطيع BuildKit أن يفحص ال Dockerfile بقواعد ثابتة دون أن يبني شيئاً، بالأمر docker build --check .، كما في وثائق Build Checks. وعندما شغلناه على النسخة الأولى كان المخرج كما يلي:

Check complete, 1 warning has been found!

WARNING: JSONArgsRecommended - https://docs.docker.com/go/dockerfile/rule/json-args-recommended/
JSON arguments recommended for CMD to prevent unintended behavior related to OS signals
Dockerfile.v1:11
--------------------
   9 |     ENV PORT=3000
  10 |     EXPOSE 3000
  11 | >>> CMD cd api && npm start

التحذير يشير بالضبط إلى مشكلة الإشارات التي قسناها، ويظهر أيضاً في آخر كل بناء عادي في سطر 1 warning found الذي يتجاهله الجميع. ومن القواعد المفيدة الأخرى SecretsUsedInArgOrEnv التي رأيناها، وFromAsCasing وUndefinedVar التي تكتشف متغيراً تستخدمه ولم تعرفه، وهي من أكثر الأخطاء الصامتة في ال Dockerfile. وتستطيع أن تجعل التحذيرات أخطاء توقف البناء في خط CI بالسطر # check=error=true في أول الملف. وللفحص الأعمق هناك أداة Hadolint، وقد استخدمناها في فحص ال Docker Images مع Trivy.

أخطاء شائعة Common Mistakes

  • COPY . . في أول الملف: كل تعديل في أي ملف يبطل كل ما بعده، فيعاد تثبيت الحزم مع كل Commit، كما رأيت في النسخة الأولى.
  • لا يوجد ملف .dockerignore: يرسل المجلد كاملاً إلى BuildKit، ويدخل .env و.git وnode_modules الخاصة بجهازك إلى ال Image، وفي النسخة الثالثة استخدم التطبيق مكتبات الجهاز بدل المكتبات التي ثبتها البناء دون أن ينتبه أحد.
  • apt-get update في سطر مستقل: يبقى في ال Cache بقائمة حزم قديمة، فيفشل التثبيت بعد أشهر أو يثبت إصدارات قديمة، والصحيح أن يكون مع install في سطر واحد ثم حذف /var/lib/apt/lists.
  • الحذف في طبقة لاحقة: لا يصغر ال Image، فالملف باق في الطبقة التي أنشأته.
  • أدوات البناء في Image الإنتاج: مترجم Go حجمه مئات الميجابايت كان في النسخة الأولى ليبني ملفاً واحداً، والحل مرحلة بناء مستقلة.
  • npm install بدل npm ci: الأول قد يغير ملف القفل ويثبت إصدارات أحدث مما اختبرته، والثاني يثبت ما في package-lock.json بالضبط ويفشل إذا لم يطابق package.json، كما في وثائق npm ci.
  • مكتبات التطوير في الإنتاج: نسيان --omit=dev يضيف أدوات مثل eslint إلى ال Image، وقد كانت أكثر من نصف عدد الحزم في تجربتنا.
  • Token أو كلمة مرور في ARG أو ENV: يظهر في docker history لكل من يسحب ال Image، والصحيح Secret Mount.
  • CMD بالصيغة shell أو npm start: الإشارة لا تصل إلى التطبيق، فيقتل بعد المهلة في كل إيقاف وتحديث.
  • الصيغة exec دون معالج للإشارة: التطبيق PID 1 يتجاهل SIGTERM، فأضف معالجاً أو استخدم --init.
  • لا توجد التعليمة USER: التطبيق يعمل بالمستخدم root دون حاجة.
  • فحص صحة يحتاج curl أو يفحص كل الاعتماديات: الأول يضيف برنامجاً لا يحتاجه التطبيق، والثاني يجعل مشكلة صغيرة في قاعدة البيانات توقف كل شيء.
  • الوسم latest في سطر FROM: قد يتغير تحتك بين بناءين، فاكتب الإصدار الكامل، والأفضل معه البصمة Digest كما شرحنا في تحديث ال Containers بأمان.

قائمة تحقق Checklist

راجع بها أي Dockerfile قبل أن تضيفه إلى المستودع:

البندكيف تتحقق منه
ال Base Image بإصدار كامل، وصغيرة بقدر ما يسمح التطبيقسطر FROM لا يحتوي latest، والحجم في docker images معقول
ملف .dockerignore يستثني .git و.env وnode_modules والاختباراتسطر transferring context في مخرج البناء بالكيلوبايت
ملفات الاعتماديات تنسخ وتثبت قبل الكودتعديل سطر في الكود يعيد طبقة واحدة، والباقي CACHED
أدوات البناء في مرحلة مستقلةdocker history لا يحتوي مترجماً ولا مكتبات تطوير
التثبيت ب npm ci --omit=dev أو ما يقابله في لغتكلا توجد أدوات تطوير في node_modules داخل ال Image
Cache Mounts لمدير الحزم والمترجمتغيير اعتمادية واحدة لا ينزل كل شيء من جديد
لا توجد أسرار في ARG أو ENV أو أي طبقةdocker build --check بلا تحذير SecretsUsedInArgOrEnv، وdocker history --no-trunc نظيف
CMD بالصيغة exec ويشغل البرنامج مباشرةps داخل ال Container يبين التطبيق PID 1 أو تحت init
التطبيق يعالج SIGTERMdocker stop ينتهي في أقل من ثانيتين برمز 0
التعليمة USER بمستخدم عاديdocker run --rm image id لا يطبع uid=0
HEALTHCHECK خفيف بالصيغة exec، ويطبع سبب الفشلdocker ps يبين healthy، والحقل Output مفيد عند الفشل
لا توجد تحذيرات من الفحصdocker build --check .

إزالة التجربة Cleanup

كل ما أنشأناه يحمل البادئة ct2-d-، فنحذفه بالاسم:

docker rm -f $(docker ps -aq --filter name=ct2-d-)
docker rmi ct2-d-orders:v1 ct2-d-orders:v2 ct2-d-orders:v3 ct2-d-orders:v4 ct2-d-orders:v5 ct2-d-argdemo ct2-d-argdemo:secret
docker volume rm ct2-d-work

وتبقى بعد ذلك طبقات ال Build Cache وال Cache Mounts داخل BuildKit، وترى حجمها بالأمر docker buildx du أو docker system df. ويحذفها الأمر docker builder prune، ولكن انتبه إلى ما يفعله قبل أن تشغله على جهاز مشترك أو سيرفر بناء: فهو يحذف ال Build Cache لكل المشاريع على هذا المحرك وليس لمشروعك وحده، ومعه الخيار --all يحذف حتى ما يستخدم حالياً، وبعده يصبح أول بناء لكل مشروع بناءً بارداً، كما في وثائق docker builder prune. وأخطر منه docker system prune الذي يحذف أيضاً ال Containers المتوقفة والشبكات غير المستخدمة وال Images التي لا يستخدمها Container، ومعه --volumes يحذف البيانات نفسها. لذلك على سيرفر الإنتاج أو جهاز يعمل عليه أكثر من شخص احذف ما أنشأته بالاسم، واترك التنظيف العام لسياسة الحذف التلقائي في BuildKit، وهي التي يضبطها الإعداد builder.gc في ملف daemon.json بحد أقصى للمساحة.

الخلاصة Summary

وصلنا لنهاية الموضوع، وأهم ما فيه:

  • كل تعليمة تغير الملفات تنتج طبقة، وإبطال طبقة يعيد كل ما بعدها، لذلك رتب ال Dockerfile من الأقل تغيراً إلى الأكثر، وانسخ ملفات الحزم وثبتها قبل الكود. هذا وحده نزل البناء بعد تعديل سطر من 4 دقائق و48 ثانية إلى 21 ثانية.
  • البناء متعدد المراحل يترك المترجم وأدوات البناء خارج ال Image، و.dockerignore يمنع أن يدخلها ما على جهازك، ومعهما نزل الحجم من 641 ميجابايت مضغوطة إلى 66، وخرج .env و.git وحزم التطوير من ال Image.
  • ال Cache Mounts تحفظ ذاكرة مدير الحزم والمترجم خارج ال Image، ونزلت بها ترجمة Go بعد تعديل الكود من 110.7 ثانية إلى 5.5، أما npm على اتصال سريع فلم يستفد كثيراً.
  • ARG للبناء وENV للتشغيل، ولا يمر أي سر عبر أي منهما لأنه يظهر في docker history، والطريق الصحيح Secret Mount.
  • CMD بالصيغة exec يجعل تطبيقك PID 1، وتطبيقك يجب أن يعالج SIGTERM أو يعمل خلف --init، وإلا قتل بعد المهلة في كل إيقاف.
  • USER بمستخدم عادي، وHEALTHCHECK خفيف يطبع سبب فشله، وdocker build --check قبل كل Commit.

وفي المقالات التالية من هذه المرحلة بإذن الله نأخذ ال Image الصغيرة التي وصلنا إليها ونقلل ما فيها أكثر ونفحصها ونوقعها، ثم نشغلها مع قاعدة البيانات وال Cache في ملف Compose مرتب.

دليلتقليل حجم ال Docker Images وتأمينها Hardeningكيف تبني Image فيها ما يحتاجه تطبيقك فقط، وتقيس الفرق بين slim وalpine وdistroless وscratch بالحجم والثغرات، ثم تشغلها بمستخدم عادي وتوقعها قبل النشر.دليلأفضل الممارسات Best Practices في ملفات Docker Composeكيف تكتب ملف Compose يبدأ خدماته بالترتيب الصحيح ويحمي كلمات المرور ويضبط الذاكرة ويفصل التطوير عن الإنتاج، مع تجربة أظهرت أين يخدعك كل إعداد افتراضي.

سجل التحديثات Changelog

  • 18 نوفمبر 2026: كتابة المقال، وتنفيذ التجربة على Docker Engine 29.8.0 مع BuildKit وBuildx 0.39.0، وnode:24.22.1-bookworm وnode:24.22.1-alpine وgolang:1.27-alpine (Go 1.27.4)، وExpress 5.2.1 وeslint 10.15.0.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.