docker history ومن مخرجات البناء، وأبقِ الـ cache دافئًا بالـ cache mounts وتصدير الـ cache في الـ CI.","html":"سألني فريق في Skylane مرة لماذا ارتفع زمن البناء في الـ CI لديهم تدريجيًا من أربعين ثانية إلى ثماني دقائق. كان الـ Dockerfile عندهم يشبه الذي كتبته في الدرس السابق: COPY . . ثم npm ci. وبما أن كل commit يغيّر ملفًا ما، كان كل بناء يعيد تثبيت 900 حزمة من الإنترنت. وإعادة ترتيب واحدة أعادته إلى أربعين ثانية.
كل FROM وCOPY وADD وRUN تنتج layer (طبقة). حين تعيد البناء، يمرّ BuildKit على الـ Dockerfile من الأعلى إلى الأسفل ويسأل عن كل خطوة: «هل نفّذت هذا بالضبط من قبل، وبهذه المُدخلات بالضبط؟»
RUN، المفتاح هو نصّ الأمر مع الـ layer التي يعمل فوقها.COPY وADD، يتضمّن المفتاح checksum للملفات المنسوخة.أول خطوة لا يطابق مفتاحها هي إخفاق الـ cache (cache miss)، ومن بعدها تُعاد كل خطوة لاحقة، لأن كل واحدة منها تعمل فوق layer صارت مختلفة الآن. لذا فإصابات الـ cache (cache hits) لا تقع إلا في جزء متّصل من بداية الملف. الترتيب هو كل شيء.
\nالاعتماديات تتغيّر أسبوعيًا؛ والكود يتغيّر مع كل commit. لذا انسخ ملفات تعريف الاعتماديات وحدها، ثم ثبّتها، وبعد ذلك فقط انسخ الباقي:
\n# syntax=docker/dockerfile:1\nFROM node:24-slim\nWORKDIR /app\n\n# Changes rarely: only when dependencies change\nCOPY package.json package-lock.json ./\nRUN npm ci\n\n# Changes on every commit\nCOPY . .\nRUN npm run build\n\nEXPOSE 3000\nCMD [\"node\", \"dist/server.js\"]عدّل src/server.ts وأعِد البناء. المخرجات تُظهر الخطوات التي أُعيد استخدامها:
=> CACHED [2/6] WORKDIR /app\n => CACHED [3/6] COPY package.json package-lock.json ./\n => CACHED [4/6] RUN npm ci\n => [5/6] COPY . .\n => [6/6] RUN npm run buildالقاعدة العامة: رتّب التعليمات من الأقل تغيّرًا إلى الأكثر تغيّرًا. حزم النظام، ثم اعتماديات اللغة، ثم كودك، ثم كل ما يُشتقّ من كودك.
\nالأمر docker history notes-api:dev يعرض الـ layers مع حجم كل منها والتعليمة التي أنشأتها. استخدمه حين تكون الـ image أكبر مما تتوقّع؛ فالمتّهم عادةً layer واحدة متضخّمة.
والقاعدة نفسها تنطبق على معاملات البناء. سطر مثل ARG GIT_SHA في أعلى الملف، يُستخدم لاحقًا في RUN أو LABEL، يعطي كل خطوة RUN تحته مُدخلًا جديدًا مع كل commit، لأن معاملات البناء تكون مرئية لكل RUN لاحقة على هيئة متغيّرات بيئة. لذا أخّر تعريف مثل هذه القيم قدر الإمكان، وضعه مباشرة قبل الخطوة الوحيدة التي تستخدمها.
مفتاح COPY مبنيّ على محتوى الملفات لا على تواريخ تعديلها، لذا فإن git clone جديدًا على خادم بناء يصيب الـ cache نفسه الذي على جهازك ما دامت البايتات متطابقة. ولهذا أيضًا يهمّ أن يكون package-lock.json محدّثًا ومحفوظًا في المستودع: فهو المُدخل الذي يقرّر هل يُعاد استخدام التثبيت المكلف أم لا.
إن احتجت إلى حزم نظام التشغيل، فثبّتها في RUN واحدة:
RUN apt-get update \\\n && apt-get install -y --no-install-recommends ca-certificates \\\n && rm -rf /var/lib/apt/lists/*الخيار --no-install-recommends يتخطّى الإضافات الاختيارية، وحذف قوائم الحزم في الخطوة نفسها يُبقيها خارج الـ layer. حذفها في RUN لاحقة لا يقلّص شيئًا: الـ layer السابقة ما زالت تحتويها.
أحيانًا يجب أن يُعاد التثبيت لأنك أضفت اعتمادية. الـ cache mount يحتفظ بذاكرة تنزيلات npm داخل أداة البناء بين عمليات البناء، دون أن يضعها في الـ image:
\nCOPY package.json package-lock.json ./\nRUN --mount=type=cache,target=/root/.npm npm ciما زال npm ci يحذف node_modules ويعيد إنشاءه، لكن الملفات المضغوطة تأتي من القرص المحلي بدلًا من الـ registry. في notes-api يحوّل هذا إعادة تثبيت تستغرق 70 ثانية إلى نحو 15 ثانية.
جهازك يحتفظ بالـ cache بين عمليات البناء. أما معظم الـ runners في الـ CI فتبدأ فارغة، فيبدأ كل بناء باردًا مهما أحسنت ترتيب الملف. صدّر الـ cache إلى مكان دائم واستورده في التشغيل التالي:
\ndocker buildx build \\\n --cache-from type=registry,ref=ghcr.io/skylane/notes-api:buildcache \\\n --cache-to type=registry,ref=ghcr.io/skylane/notes-api:buildcache,mode=max \\\n -t ghcr.io/skylane/notes-api:dev .الخيار mode=max يخزّن الـ layers الوسيطة أيضًا، وهذا مهمّ حين تصبح لديك عدّة build stages. ومستخدمو GitHub Actions يستطيعون استخدام type=gha بدلًا من registry.
البناء سريع الآن. في الدرس التالي ستألف جانب التشغيل: المنافذ، ومتغيّرات البيئة، والسجلات، وما الذي يحدث فعلًا حين يتوقّف الـ container.
\n","toc":[{"id":"sec-1","text":"الـ Layers ومفاتيح الـ cache","level":2},{"id":"sec-2","text":"أعِد الترتيب لصالح الـ cache","level":2},{"id":"sec-3","text":"حزم النظام: RUN واحدة مع التنظيف","level":2},{"id":"sec-4","text":"الـ Cache mounts: إخفاقات أسرع","level":2},{"id":"sec-5","text":"الـ Cache في الـ CI","level":2}],"takeaways":["مفتاح الـ cache لكل تعليمة يعتمد على التعليمة نفسها، وفي حالةCOPY على checksum الملفات المنسوخة؛ وإخفاق واحد يعيد بناء كل الخطوات التالية.","انسخ package.json وpackage-lock.json أولًا، وشغّل npm ci، ثم انسخ الكود المصدري، حتى لا تعيد تعديلات الكود تثبيت الاعتماديات.","ضع التعليمات التي نادرًا ما تتغيّر في الأعلى، والتعليمات التي تتغيّر مع كل commit في الأسفل.","شغّل apt-get update وapt-get install داخل RUN واحدة حتى لا يكون فهرس الحزم قديمًا أبدًا.","الـ cache mount (RUN --mount=type=cache) يحتفظ بذاكرة تنزيلات npm بين عمليات البناء، حتى حين يجب إعادة بناء الـ layer نفسها."],"further":[{"title":"Docker build cache","url":"https://docs.docker.com/build/cache/"},{"title":"Optimize cache usage in builds","url":"https://docs.docker.com/build/cache/optimize/"},{"title":"Cache storage backends","url":"https://docs.docker.com/build/cache/backends/"}],"quiz":[{"q":"في هذا الـ Dockerfile تعدّل الملف src/routes.ts فقط ثم تعيد البناء. أي الخطوات تُنفَّذ من جديد؟
FROM node:24-slim\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN npm ci\nCOPY . .\nRUN npm run buildRUN npm run build، لأنها الخطوة التي تترجم TypeScript.","why":"التعليمة COPY . . تنسخ src/routes.ts، فيتغيّر الـ checksum الخاص بها وتكون هي أول إخفاق؛ ثم تُعاد خطوة البناء لأنها تأتي بعد إخفاق."},{"text":"الخطوة RUN npm ci وكل ما بعدها.","why":"الأمر npm ci يأتي بعد COPY لملفَّي الحزم فقط، وهما لم يتغيّرا، فيبقى في الـ cache."},{"text":"الخطوتان COPY . . وRUN npm run build؛ ويبقى تثبيت الاعتماديات في الـ cache.","why":"صحيح. أول مُدخل تغيّر هو عند COPY . .، فتُعاد هي وكل خطوة بعدها. والتثبيت المكلف فوقها يُعاد استخدامه."}],"answer":3},{"q":"لماذا يسبّب وضع RUN apt-get update في سطر مستقل، يليه RUN apt-get install -y curl، مشاكل بعد أشهر؟
apt-get في الـ cache.","why":"يخزّن Docker خطوات RUN في الـ cache حسب نصّها، سواء كانت apt أم لا. وهذه بالضبط هي المشكلة هنا."},{"text":"لأن الـ layer الخاصة بـ update تبقى في الـ cache بفهرس حزم قديم، فأي تغيير لاحق في سطر التثبيت يجلب إصدارات قديمة أو مفقودة.","why":"صحيح. مفتاح الـ cache هو نصّ الأمر، وهو لا يتغيّر أبدًا، فيكون الفهرس من يوم إنشاء الـ cache. اجمعهما في RUN واحدة."},{"text":"لأن تعليمتَي RUN تضاعفان حجم الـ image.","why":"الـ layers الإضافية تضيف قليلًا من البيانات الوصفية، ولا تضاعف الحجم. المشكلة الحقيقية فهرس قديم في الـ cache."},{"text":"لأن apt-get update يحتاج إلى root بينما تُسقط الـ RUN الثانية الصلاحيات.","why":"كلتاهما تعملان بالمستخدم نفسه ما لم تأتِ تعليمة USER بينهما."}],"answer":1},{"q":"الـ runner في الـ CI يبدأ بـ cache فارغ لـ Docker في كل مهمة، فكل بناء يبدأ باردًا. ما الذي يساعد أكثر؟
","options":[{"text":"إضافة المزيد من تعليماتRUN حتى توجد layers أكثر للتخزين.","why":"الـ layers الإضافية لا تفيد حين لا يوجد cache تقرأ منه أصلًا."},{"text":"التحويل من npm ci إلى npm install لأنه أسرع.","why":"قد يعيد npm install كتابة الـ lockfile، ولا يحلّ مشكلة الـ cache الفارغ. أبقِ npm ci من أجل قابلية التكرار."},{"text":"تصدير الـ build cache واستيراده، مثلًا باستخدام --cache-to و--cache-from موجّهَين إلى registry.","why":"صحيح. واجهات تخزين الـ cache تسمح للـ runners الجديدة بإعادة استخدام الـ layers التي بنتها مهام سابقة."},{"text":"استخدام docker build --no-cache حتى تكون النتيجة متوقّعة.","why":"هذا يتخلّص من الـ cache كليًا، وهو عكس ما تريده من أجل السرعة."}],"answer":2},{"q":"ما الذي يعطيك إياه RUN --mount=type=cache,target=/root/.npm npm ci ولا يعطيك إياه الـ layer cache؟
node_modules من جهازك داخل الـ image.","why":"الـ cache mounts تعيش داخل أداة البناء، لا على جهازك، وتخزّن مستودع تنزيلات npm، لا node_modules."},{"text":"تُستبعد الحزم المثبّتة من الـ image النهائية لتوفير المساحة.","why":"المجلد node_modules ما زال يُكتب داخل الـ layer. وحده المجلد المُركَّب /root/.npm يبقى خارج الـ image."},{"text":"لا تُعاد الخطوة أبدًا، حتى لو تغيّر الـ lockfile.","why":"تُعاد الخطوة كلما تغيّرت مُدخلاتها. الـ mount يجعل الإعادة أسرع فقط."}],"answer":0}],"exercise":{"kind":"spot-bug","language":"dockerfile","code":"# syntax=docker/dockerfile:1\nFROM node:24-slim\nRUN apt-get update\nRUN apt-get install -y --no-install-recommends ca-certificates\nWORKDIR /app\nCOPY . .\nRUN npm ci\nRUN npm run build\nEXPOSE 3000\nCMD [\"node\", \"dist/server.js\"]","bugLines":[3,6],"title":"اعثر على قاتلَي الـ cache","prompt":"البناء في الـ CI لهذا الـ Dockerfile يستغرق ثماني دقائق حتى حين يغيّر الـ commit سطرًا واحدًا من TypeScript، وفي الأسبوع الماضي فشلت إضافة حزمة نظام ثانية برسالة Unable to locate package. اختر السطرين الاثنين المسؤولين.
RUN تُخزَّن في الـ cache حسب نصّها وحده، فقد يكون عمر نتيجتها أشهرًا؟"],"explanation":"السطر 6 ينسخ الـ context كاملًا قبل npm ci، فأي تغيير في الكود يُخفق في الـ cache هناك ويعيد تثبيت كل الاعتماديات. انسخ ملفات التعريف وحدها أولًا، ثم ثبّت الاعتماديات، ثم انسخ الباقي.
السطر 3 يخزّن apt-get update وحده في الـ cache؛ فحين يتغيّر سطر التثبيت، يعمل اعتمادًا على فهرس من يوم إنشاء الـ cache. اجمع التحديث والتثبيت في RUN واحدة:
RUN apt-get update \\\n && apt-get install -y --no-install-recommends ca-certificates \\\n && rm -rf /var/lib/apt/lists/*\nWORKDIR /app\nCOPY package.json package-lock.json ./\nRUN npm ci\nCOPY . .\nRUN npm run build