> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# كتابة Dockerfile صحيح: Multi-stage وLayer Caching
- URL: https://arabroot.io/articles/كتابة-dockerfile-صحيح-multi-stage-و-layer-caching/
- Published: 2026-11-18T16:26:32.000Z
- Updated: 2026-11-18T17:27:27.000Z
- Description: خمس نسخ من Dockerfile للتطبيق نفسه نزلت بال Image من 641 ميجابايت إلى 66 وبالبناء بعد تعديل سطر من خمس دقائق إلى أقل من أربع ثوان، مع شرح كل سطر والأرقام المقاسة.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الحاويات Containers وتنسيقها مع Kubernetes, Docker والحاويات, الاستضافة الذاتية, Docker, DevOps وCI/CD

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

وكل هذه المشكلات تأتي من الملف نفسه، وكل واحدة منها لها سبب واضح في طريقة عمل البناء. وقد شرحنا في [تثبيت Docker على Ubuntu](https://arabroot.io/articles/%D8%AA%D8%AB%D8%A8%D9%8A%D8%AA-docker-%D8%B9%D9%84%D9%89-ubuntu/) كيف تجهز المحرك، وفي [شبكات Docker](https://arabroot.io/articles/%D8%B4%D8%A8%D9%83%D8%A7%D8%AA-docker-%D9%88%D8%A3%D9%81%D8%B6%D9%84-%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA/) كيف تتصل ال Containers ببعضها، واستخدمنا Dockerfile متعدد المراحل في خدمة Go الحقيقية و[خدمة Node.js الحقيقية](https://arabroot.io/articles/%D8%AE%D8%AF%D9%85%D8%A9-%D8%B7%D9%84%D8%A8%D8%A7%D8%AA-%D8%AD%D9%82%D9%8A%D9%82%D9%8A%D8%A9-node-js-fastify-postgresql/) دون أن نقف عند كل سطر فيه. وفي هذا المقال سوف نقف عند كل سطر، فنأخذ تطبيقاً صغيراً واحداً، ونكتب له خمس نسخ من ال 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.

[![](https://arabroot.io/content/images/2026/11/containers-basics-cover-cover.webp)دليلما هي ال Containers؟ الفرق بينها وبين الأجهزة الافتراضيةنفتح Container حقيقياً من الخارج ثم نبني واحداً بأيدينا بـ unshare وchroot وcgroup v2، لنفهم ما الذي يعزله فعلاً وأين تقف حدوده أمام الجهاز الافتراضي.](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%8A-%D8%A7%D9%84-containers-%D9%88%D8%A7%D9%84%D9%81%D8%B1%D9%82-%D8%A8%D9%8A%D9%86%D9%87%D8%A7-%D9%88%D8%A8%D9%8A%D9%86-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9-%D8%A7%D9%84%D8%A7%D9%81%D8%AA%D8%B1%D8%A7%D8%B6%D9%8A%D8%A9/)[![](https://arabroot.io/content/images/2026/11/docker-commands-cover-cover.webp)دليلأوامر Docker الأساسية: التشغيل والسجلات والإيقافنشغل خدمة صغيرة ونتابعها بأوامر Docker اليومية، ثم نفهم لماذا ينتظر docker stop ثم يقتل، وماذا تعني رموز الخروج 0 و1 و127 و137 و143.](https://arabroot.io/articles/%D8%A7%D9%88%D8%A7%D9%85%D8%B1-docker-%D8%A7%D9%84%D8%A7%D8%B3%D8%A7%D8%B3%D9%8A%D8%A9-%D8%A7%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D9%88%D8%A7%D9%84%D8%B3%D8%AC%D9%84%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%A7%D9%8A%D9%82%D8%A7%D9%81/)

## كيف يبني 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](https://docs.docker.com/build/buildkit/?ref=arabroot.io). وقبل أن ينفذ BuildKit أي تعليمة يسأل: هل نفذت هذه التعليمة من قبل فوق الطبقة نفسها وبالمدخلات نفسها؟ فإذا كان الجواب نعم أخذ النتيجة من ال Build Cache وكتب في المخرج `CACHED`، وإلا نفذها من جديد. والمدخلات تختلف بحسب نوع التعليمة، كما تشرح [صفحة إبطال ال Cache](https://docs.docker.com/build/cache/invalidation/?ref=arabroot.io):

- **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` هو الذي يحدد ما يستثنى من هذا السياق، كما في [وثائق سياق البناء](https://docs.docker.com/build/concepts/context/?ref=arabroot.io)، فإذا لم يكن موجوداً أرسل المجلد كاملاً بما فيه `.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` فيه كلمات مرور التطوير:

```text
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 ونشغل التطبيق:

```dockerfile
# 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 ثانية، وهذه أهم الأسطر من مخرجه مع وقت كل خطوة:

```text
#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 الكبيرة بطيئة في البناء أيضاً وليس في السحب فقط.

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

```bash
docker images ct2-d-orders:v1
docker history ct2-d-orders:v1 --format 'table {{.CreatedBy}}\t{{.Size}}'
```

```text
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 نفسها:

```bash
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'
```

```text
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 ثانية:

```text
#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](https://arabroot.io/content/images/2026/11/dockerfile-best-practices-01-layers-cache.webp)

الترتيب يحدد ما يعاد: تغيير في طبقة يعيد كل ما فوقها، فضع ما يتغير مع كل Commit في الأعلى

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

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

```dockerfile
# 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` فكان كما يلي:

```text
#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](https://docs.docker.com/build/building/best-practices/?ref=arabroot.io) هذه المشكلة بالاسم، والحل أن يكون التحديث والتثبيت في أمر واحد، فإذا تغير أي منهما أعيد الاثنان معاً.

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

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

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

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

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

الفكرة بسيطة: ال Dockerfile الواحد يمكن أن يحتوي عدة تعليمات `FROM`، وكل واحدة تبدأ مرحلة Stage جديدة لها اسم، والمرحلة الأخيرة هي ال Image الناتجة، وتنسخ من المراحل السابقة ما تحتاجه فقط بالتعليمة `COPY --from`، وكل ما بقي في تلك المراحل لا يصل إلى ال Image، كما في [وثائق البناء متعدد المراحل](https://docs.docker.com/build/building/multi-stage/?ref=arabroot.io):

```dockerfile
# 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:** شرحنا كل واحدة منها في قسم مستقل بعد النتائج.

```text
#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](https://arabroot.io/content/images/2026/11/dockerfile-best-practices-03-multi-stage.webp)

المترجم وذاكرة npm يبقيان في مراحل البناء، وما يصل إلى السيرفر هو ما تنسخه COPY --from فقط

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

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

```bash
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\"]}))"'
```

```text
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 . .`. وهذا ملف التجربة:

```text
# 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 لأغراض مختلفة، كما في [وثائق سياق البناء](https://docs.docker.com/build/concepts/context/?ref=arabroot.io).

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

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

```text
# 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 ميجابايت ومعه بضعة كيلوبايتات](https://arabroot.io/content/images/2026/11/dockerfile-best-practices-02-build-context.webp)

ملف .dockerignore يعمل قبل الإرسال، فما يستثنيه لا يصل إلى BuildKit ولا يمكن لأي COPY أن ينسخه

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

```text
$ 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](https://docs.docker.com/build/cache/optimize/?ref=arabroot.io):

```dockerfile
# 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`، أي تغييراً في الاعتماديات وتغييراً في الكود المترجم معاً، ثم بنينا النسختين الرابعة والخامسة بعد أن بنيت كل منهما من قبل:

```text
== 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 معها](https://arabroot.io/content/images/2026/11/dockerfile-best-practices-06-cache-mount.webp)

ال Cache Mount يعيش في BuildKit وليس في ال Image، فتعاد الخطوة ولكن دون أن تبدأ من الصفر، والفائدة الكبيرة هنا كانت في ترجمة Go

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

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

```bash
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](https://docs.docker.com/build/cache/backends/?ref=arabroot.io). ولاحظ أن ال Cache Mounts لا تدخل في هذا التصدير، كما تذكر [وثائق ال Cache في GitHub Actions](https://docs.docker.com/build/ci/github-actions/cache/?ref=arabroot.io) التي تقترح حلاً التفافياً لذلك، فهي مصممة لسيرفر البناء الثابت، ولذلك يبقى ترتيب الطبقات وفصل المراحل هو الأهم في خط CI. وقد شرحنا بناء ال Images ورفعها من خط CI على سيرفرك في [Gitea Actions](https://arabroot.io/articles/gitea-actions-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-ci-cd-%D8%B9%D9%84%D9%89-%D8%AE%D8%A7%D8%AF%D9%85%D9%83/).

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

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

| النسخة              | CONTENT SIZE | DISK USAGE | الطبقات | بناء بارد | بعد تعديل سطر |
| ------------------- | ------------ | ---------- | ------- | --------- | ------------- |
| v1 البسيطة          | 641MB        | 2.51GB     | 14      | 8m 26s    | 4m 48s        |
| v2 ترتيب الطبقات    | 632MB        | 2.51GB     | 15      | 6m 24s    | 21s           |
| v3 متعدد المراحل    | 152MB        | 460MB      | 8       | 2m 11s    | 23s           |
| v4 مع .dockerignore | 66MB         | 261MB      | 8       | 1m 36s    | 3.7s          |
| v5 مع Cache Mounts  | 66MB         | 261MB      | 8       | 1m 56s    | 6.9s          |

![ثلاثة رسوم أعمدة للنسخ الخمس: الحجم المضغوط 641 و632 و152 و66 و66 ميجابايت، والبناء البارد 506 و384 و132 و96 و116 ثانية، والبناء بعد تعديل سطر 288 و21 و23 و3.7 و6.9 ثانية](https://arabroot.io/content/images/2026/11/dockerfile-best-practices-04-results.webp)

الحجم نزل من 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، كما في [وثائق متغيرات البناء](https://docs.docker.com/build/building/variables/?ref=arabroot.io). والاستخدام الشائع أن تجمع بينهما: ARG ليأخذ القيمة من خط CI، وENV ليحفظها في ال Image، مثل رقم الإصدار:

```dockerfile
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 يعمل بها:

```text
#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](https://docs.docker.com/reference/cli/docker/image/history/?ref=arabroot.io):

```bash
docker history --no-trunc --format "{{.CreatedBy}}" ct2-d-argdemo | head -4
```

```text
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](https://docs.docker.com/reference/build-checks/secrets-used-in-arg-or-env/?ref=arabroot.io)، فقد ظهر هذا التحذير عند البناء: `Do not use ARG or ENV instructions for sensitive data (ARG "NPM_TOKEN")`، ولكنه تحذير وليس خطأ، فلا يوقف البناء.

والطريقة الصحيحة هي ال Secret Mount، حيث يعطي BuildKit السر لخطوة RUN واحدة كملف أو متغير بيئة أثناء تنفيذها فقط، ولا يكتبه في أي طبقة ولا في التاريخ، كما في [وثائق Build Secrets](https://docs.docker.com/build/building/secrets/?ref=arabroot.io):

```dockerfile
# 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
```

```bash
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
```

```text
#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 فلا يدخل. وقد شرحنا في [اكتشاف الأسرار المسربة](https://arabroot.io/articles/%D8%A7%D9%83%D8%AA%D8%B4%D8%A7%D9%81-%D8%A7%D9%84%D8%A7%D8%B3%D8%B1%D8%A7%D8%B1-%D8%A7%D9%84%D9%85%D8%B3%D8%B1%D8%A8%D8%A9-%D9%85%D8%B9-gitleaks-%D9%88-trufflehog/) كيف تبحث عن الأسرار التي وصلت إلى طبقات Images قديمة، وماذا تفعل إذا وجدتها.

🔑

في أبريل 2021 أعلنت شركة Codecov أن مهاجماً عدل سكربت Bash Uploader الذي يشغله آلاف العملاء داخل خطوط CI، فصار يرسل متغيرات البيئة في هذه الخطوط، بما فيها من Tokens ومفاتيح، إلى سيرفر المهاجم لمدة شهرين تقريباً. وذكرت الشركة في [بيانها عن الحادثة](https://about.codecov.io/security-update/?ref=arabroot.io) أن المهاجم وصل إلى ذلك بسبب خطأ في طريقة إنشاء ال 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](https://docs.docker.com/reference/dockerfile/?ref=arabroot.io):

- **الصيغة 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](https://docs.docker.com/reference/cli/docker/container/stop/?ref=arabroot.io). والمهلة الافتراضية 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`:

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

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

```text
  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 -c  | 12.0 ثانية، وSIGKILL بعد 10.1 | 137        |
| \["npm", "start"\] (exec)         | npm start   | 2.8 ثانية                     | 1          |
| \["node", "server.js"\] دون معالج | node        | 12.9 ثانية، وSIGKILL          | 137        |
| \["node", "server.js"\] مع معالج  | node        | 1.9 ثانية                     | 0          |
| docker run --init دون معالج       | docker-init | 1.7 ثانية                     | 143        |

![أربع حالات لإيقاف ال Container: الصيغة shell حيث PID 1 هو sh ولا تصل الإشارة إلى node فيقتل بعد المهلة، والصيغة exec دون معالج حيث node هو PID 1 ويتجاهل الإشارة، والصيغة exec مع معالج حيث يغلق التطبيق ويخرج بالرمز 0، وdocker run --init حيث يمرر tini الإشارة إلى node فيخرج بالرمز 143](https://arabroot.io/content/images/2026/11/dockerfile-best-practices-05-signals.webp)

الإشارة تصل إلى 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](https://arabroot.io/articles/%D9%82%D8%A7%D8%A6%D9%85%D8%A9-%D8%AA%D8%AD%D9%82%D9%82-%D8%A7%D9%84%D9%85%D8%B7%D9%88%D8%B1-%D9%82%D8%A8%D9%84-%D9%86%D8%B4%D8%B1-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D9%87/#graceful-shutdown).
- **الخيار `--init`:** وضع Docker عملية init صغيرة مبنية على [tini](https://github.com/krallin/tini?ref=arabroot.io) في مكان 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](https://docs.docker.com/reference/build-checks/json-args-recommended/?ref=arabroot.io) كما سنرى بعد قليل.

## 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`، وهذا جيد للكود، لأن التطبيق يقرؤه ولا يحتاج أن يغيره، فإذا استطاع مخترق أن ينفذ أوامر بصلاحيات التطبيق فلن يستطيع أن يعدل الكود نفسه. وهذا ما ظهر عندما حاولنا الكتابة داخل النسخة الرابعة:

```text
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، تجدها في المقالات التالية من هذه المرحلة.

[![](https://arabroot.io/content/images/2026/11/docker-image-hardening-cover-cover.webp)دليلتقليل حجم ال Docker Images وتأمينها Hardeningكيف تبني Image فيها ما يحتاجه تطبيقك فقط، وتقيس الفرق بين slim وalpine وdistroless وscratch بالحجم والثغرات، ثم تشغلها بمستخدم عادي وتوقعها قبل النشر.](https://arabroot.io/articles/%D8%AA%D9%82%D9%84%D9%8A%D9%84-%D8%AD%D8%AC%D9%85-docker-images-%D9%88%D8%AA%D8%A7%D9%85%D9%8A%D9%86%D9%87%D8%A7/)[![](https://arabroot.io/content/images/2026/11/docker-volumes-cover-cover.webp)دليلبيانات ال Containers: Volumes وBind Mounts والنسخ الاحتياطيأين تذهب ملفات ال Container وما الذي يحذفها، مع قياس حقيقي لسرعة مسارات Windows وLinux ونسخة احتياطية مستعادة لملفات Volume وقاعدة PostgreSQL.](https://arabroot.io/articles/%D8%A8%D9%8A%D8%A7%D9%86%D8%A7%D8%AA-%D8%A7%D9%84-containers-volumes-%D9%88-bind-mounts-%D9%88%D8%A7%D9%84%D9%86%D8%B3%D8%AE-%D8%A7%D9%84%D8%A7%D8%AD%D8%AA%D9%8A%D8%A7%D8%B7%D9%8A/)

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

عندما يبدأ ال Container يعتبره Docker «يعمل» ما دامت العملية الأولى حية، حتى لو كان التطبيق داخلها عالقاً أو لا يستمع على المنفذ الصحيح أو فقد اتصاله بقاعدة البيانات. والتعليمة `HEALTHCHECK` تضيف سؤالاً دورياً: أمر يشغله Docker داخل ال Container كل فترة، فإذا خرج بالرمز 0 فال Container سليم healthy، وإذا فشل عدة مرات متتالية أصبح unhealthy، كما في [مرجع Dockerfile](https://docs.docker.com/reference/dockerfile/?ref=arabroot.io) في قسم 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:

```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 ولا يتغير الفحص معه:

```bash
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}}'
```

```text
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](https://docs.docker.com/build/checks/?ref=arabroot.io). وعندما شغلناه على النسخة الأولى كان المخرج كما يلي:

```text
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](https://arabroot.io/articles/%D9%81%D8%AD%D8%B5-%D8%A7%D9%84%D8%AD%D8%A7%D9%88%D9%8A%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%A8%D9%86%D9%8A%D8%A9-%D9%83%D9%83%D9%88%D8%AF-%D9%85%D8%B9-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](https://docs.npmjs.com/cli/v11/commands/npm-ci?ref=arabroot.io).
- **مكتبات التطوير في الإنتاج:** نسيان `--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 بأمان](https://arabroot.io/articles/%D8%AA%D8%AD%D8%AF%D9%8A%D8%AB-%D8%A7%D9%84-containers-%D8%A8%D8%A7%D9%85%D8%A7%D9%86-watchtower-%D8%A7%D9%85-diun-%D8%A7%D9%85-renovate/).

## قائمة تحقق 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                                   |
| التطبيق يعالج SIGTERM                                          | docker stop ينتهي في أقل من ثانيتين برمز 0                                            |
| التعليمة USER بمستخدم عادي                                     | docker run --rm image id لا يطبع uid=0                                                |
| HEALTHCHECK خفيف بالصيغة exec، ويطبع سبب الفشل                 | docker ps يبين healthy، والحقل Output مفيد عند الفشل                                  |
| لا توجد تحذيرات من الفحص                                       | docker build --check .                                                                |

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

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

```bash
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](https://docs.docker.com/reference/cli/docker/builder/prune/?ref=arabroot.io). وأخطر منه `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 مرتب.

[![](https://arabroot.io/content/images/2026/11/docker-image-hardening-cover-cover.webp)دليلتقليل حجم ال Docker Images وتأمينها Hardeningكيف تبني Image فيها ما يحتاجه تطبيقك فقط، وتقيس الفرق بين slim وalpine وdistroless وscratch بالحجم والثغرات، ثم تشغلها بمستخدم عادي وتوقعها قبل النشر.](https://arabroot.io/articles/%D8%AA%D9%82%D9%84%D9%8A%D9%84-%D8%AD%D8%AC%D9%85-docker-images-%D9%88%D8%AA%D8%A7%D9%85%D9%8A%D9%86%D9%87%D8%A7/)[![](https://arabroot.io/content/images/2026/11/compose-best-practices-cover-cover.webp)دليلأفضل الممارسات Best Practices في ملفات Docker Composeكيف تكتب ملف Compose يبدأ خدماته بالترتيب الصحيح ويحمي كلمات المرور ويضبط الذاكرة ويفصل التطوير عن الإنتاج، مع تجربة أظهرت أين يخدعك كل إعداد افتراضي.](https://arabroot.io/articles/%D8%A7%D9%81%D8%B6%D9%84-%D8%A7%D9%84%D9%85%D9%85%D8%A7%D8%B1%D8%B3%D8%A7%D8%AA-%D9%81%D9%8A-%D9%85%D9%84%D9%81%D8%A7%D8%AA-docker-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.