في الحادية عشرة ليلًا من ليلة إطلاق، أعطى اثنان من الـ Pods التابعة للخدمة نفسها إجابتين مختلفتين عن الطلب نفسه. كلاهما كان يشغّل api:latest. أحدهم أعاد دفع latest بعد الظهر، فسحب أحد الـ nodes الـ image الجديدة بينما بقي الآخر يستخدم نسخته المخزّنة. قضينا ساعة نثبت أن الكود سليم قبل أن ينظر أحد إلى الـ image. الأسماء جزء من عملية النشر، فاجعلها دقيقة.
ghcr.io/skylane/notes-api:1.4.0@sha256:3f1c9e…\n└──┬──┘ └──┬──┘ └───┬───┘ └─┬─┘ └─────┬─────┘\nregistry namespace repo tag digestghcr.io)، وAmazon ECR، وGoogle Artifact Registry، وغيرها.الـ image notes-api:latest ليست مميّزة. latest مجرد الـ tag الذي يستخدمه Docker حين لا تحدّد واحدًا. لا يعني «الأحدث»، ولا شيء يحدّثه ما لم يدفعه أحد.
لكل بناء قد يُنشر، ادفع اثنين من الـ tags للـ image نفسها:
\n1.4.0.sha-9f2c1ab.حين يُبلغ أحدهم عن خلل في «1.4.0»، يأخذك الـ tag الخاص بالـ SHA مباشرة إلى الكود. والقاعدة التي تمنع حادث ليلة الإطلاق: لا تدفع أبدًا محتوى مختلفًا تحت tag منشور فعلًا. إن أصلحت شيئًا، فهذا 1.4.1. كثير من الـ registries تستطيع فرض ذلك؛ فلـ Amazon ECR مثلًا إعداد لثبات الـ tags يرفض أي دفع إلى tag موجود.
ابنِ مرة واحدة، ثم رقِّ (promote) الـ image نفسها من بيئة إلى أخرى مرات عديدة. الـ image التي تجتاز staging يجب أن تكون بالضبط الـ image التي تصل إلى الإنتاج، ويعرّفها الـ digest نفسه. لا تُعد البناء من الـ commit نفسه للإنتاج «احتياطًا»: إعادة البناء قد تسحب base image أحدث أو اعتمادية غير مباشرة مختلفة، وعندها يشغّل الإنتاج شيئًا لم يختبره أحد. الترقية تغيير في الـ digest الذي يشير إليه الـ manifest الخاص بكل بيئة، لا بناء جديد.
\nحافظ على ترتيب الـ registry أيضًا. قواعد الاحتفاظ التي تحذف الـ images بلا tags وtags الـ SHA القديمة بعد بضعة أشهر تخفّض تكاليف التخزين، لكن استثنِ منها كل ما زال manifest يشير إليه، وإلا فسيفشل التراجع التالي بسبب image مفقودة.
\necho \"$GHCR_TOKEN\" | docker login ghcr.io -u amara-skylane --password-stdin\n\nGIT_SHA=$(git rev-parse --short HEAD)\ndocker buildx build \\\n --platform linux/amd64,linux/arm64 \\\n -t ghcr.io/skylane/notes-api:1.4.0 \\\n -t ghcr.io/skylane/notes-api:sha-$GIT_SHA \\\n --push .\n\ndocker buildx imagetools inspect ghcr.io/skylane/notes-api:1.4.0الخيار --password-stdin يُبقي الـ token خارج سجلّ الأوامر في الـ shell. وفي الـ CI، استخدم الـ token قصير العمر الذي توفّره المنصّة بدلًا من token شخصي. والأمر الأخير يطبع الـ digest الخاص بالـ image والمنصّات التي تحتويها.
قد يكون حاسوبك arm64 (Apple Silicon) بينما الـ nodes في الـ cluster من نوع amd64، أو العكس. الـ image المبنية لمعمارية معالج معيّنة تفشل على الأخرى برسالة مقتضبة: exec format error. البناء متعدّد المنصّات يحلّ ذلك: --platform linux/amd64,linux/arm64 يبني النسختين ويدفع image index (فهرس الـ image)، وهو قائمة صغيرة تربط كل منصّة بالـ manifest الخاص بها. حين يسحب node الـ image notes-api:1.4.0، يختار الـ runtime الـ manifest المناسب لمعماريّته.
البناء لمعمارية غير معمارية جهازك يعمل تحت المحاكاة، وقد يكون بطيئًا مع خطوات npm ci الثقيلة. الـ runners في الـ CI التي تملك أجهزة arm64 وamd64 أصلية أسرع حين يكبر البناء. ولكي تحتفظ بالـ images متعدّدة المنصّات محليًا، يحتاج Docker إلى مخزن الـ images الخاص بـ containerd (containerd image store)، وهو الإعداد الافتراضي في تثبيتات Docker Desktop الجديدة؛ أما في الإعدادات الأقدم فتأكّد من أنه مفعّل.
الـ digest يضمن أن كل node يشغّل بايتات متطابقة، مهما حدث للـ tag لاحقًا. تستطيع النشر بالاثنين معًا، والـ digest هو الذي يفوز:
\nimage: ghcr.io/skylane/notes-api:1.4.0@sha256:3f1c9e…يبقى الـ tag في المرجع من أجل البشر؛ والـ runtime يسحب بالـ digest. افعل الشيء نفسه مع الـ base images في الـ Dockerfile، حتى لا تلتقط إعادة البناء في الشهر القادم نسخة مختلفة من node:24-slim بصمت:
FROM node:24-slim@sha256:<digest-from-imagetools-inspect> AS buildالتثبيت يقايض الترقيعات التلقائية بإمكانية التنبّؤ، لذا اقرنه بأداة آلية مثل Dependabot أو Renovate تفتح pull request حين يُنشر digest جديد للـ base. فتحصل على التحديثات مراجَعة ومختبَرة، بدلًا من المفاجآت.
\n\nالـ image لديك الآن مسمّاة، وذات رقم إصدار، ومرفوعة إلى الـ registry. وقبل أن ينشرها أحد، يجب أن تعرف ما بداخلها، وهذا موضوع الدرس التالي.
\n","toc":[{"id":"sec-1","text":"تشريح مرجع الـ image","level":2},{"id":"sec-2","text":"مخطّط tags يصمد","level":2},{"id":"sec-3","text":"رفع الـ image إلى registry","level":2},{"id":"sec-4","text":"الـ images متعدّدة المنصّات","level":2},{"id":"sec-5","text":"التثبيت بالـ digest","level":2}],"takeaways":["مرجع الـ image هوregistry/namespace/repository:tag@digest؛ الـ tag لافتة قابلة للنقل، والـ digest بصمة المحتوى.","الـ tag latest مجرد اسم الـ tag الافتراضي، لا أحدث بناء؛ انشر إصدارات صريحة مثل 1.4.0 أو SHA من Git.","لا تدفع أبدًا محتوى مختلفًا تحت tag منشور فعلًا؛ وفعّل ثبات الـ tags (tag immutability) حيث يدعمه الـ registry لديك.","التثبيت بالـ digest (@sha256:…) يضمن أن كل node يشغّل البايتات نفسها، لتطبيقك وللـ base images.","ابنِ images متعدّدة المنصّات بـ docker buildx build --platform linux/amd64,linux/arm64 حين يستخدم المطوّرون والخوادم معالجات مختلفة."],"further":[{"title":"docker image tag","url":"https://docs.docker.com/reference/cli/docker/image/tag/"},{"title":"Multi-platform builds","url":"https://docs.docker.com/build/building/multi-platform/"},{"title":"Images in Kubernetes","url":"https://kubernetes.io/docs/concepts/containers/images/"}],"quiz":[{"q":"اثنان من الـ Pods في الـ Deployment نفسه، وكلاهما يستخدم notes-api:latest، يتصرّفان بشكل مختلف. ما التفسير الأرجح؟
latest يُحلّ دائمًا إلى أحدث image مع كل بدء للـ container.","why":"يُحلّ إلى ما يشير إليه الـ tag حين يسحب الـ node. والـ node الذي لديه نسخة مخزّنة قد لا يسحب مرة أخرى أبدًا."},{"text":"أُعيد دفع الـ tag بمحتوى جديد، وسحبه كلٌّ من الـ nodes الاثنين في وقت مختلف.","why":"صحيح. الـ tags قابلة للتغيير، فالاسم نفسه دلّ على بايتات مختلفة على nodes مختلفة. استخدم tags ذات إصدارات أو digests."},{"text":"أحد الـ Pods يشغّل image تالفة.","why":"الـ registries تتحقّق من الـ layers بالـ digest، فالتلف يُفشل السحب بدلًا من أن يعمل بصمت."}],"answer":2},{"q":"ماذا يحدّد digest مثل sha256:3f1c…؟
يبني مطوّرٌ image notes-api على حاسوب Apple Silicon ويدفعها. على الـ cluster ذي معمارية amd64 يكتب الـ Pod في سجلّه exec format error. ما الحل؟
EXPOSE لمعمارية الـ cluster.","why":"التعليمة EXPOSE توثّق المنافذ؛ ولا تستطيع تغيير معمارية المعالج للملفات التنفيذية."},{"text":"غيّر الـ base image إلى Alpine.","why":"images Alpine تأتي أيضًا لكل معمارية على حدة. والـ image المبنية على الحاسوب ما زالت arm64."},{"text":"اضبط imagePullPolicy على Always في الـ Deployment.","why":"السحب من جديد يجلب الـ image نفسها التي لا تدعم إلا arm64."},{"text":"ابنِ بـ docker buildx build --platform linux/amd64,linux/arm64 (ويفضَّل في الـ CI) حتى يحتوي فهرس الـ image على المعماريّتين.","why":"صحيح. الحاسوب بنى arm64 فقط. البناء متعدّد المنصّات يدفع tag واحدًا يشير فهرسه إلى manifest لكل معمارية."}],"answer":3},{"q":"أي مخطّط للـ tags يعطي أفضل قابلية للتتبّع لإصدارات notes-api؟
","options":[{"text":"إصدار دلالي مع tag من SHA الخاص بـ Git، مثل1.4.0 وsha-9f2c1ab، يُدفعان للبناء نفسه.","why":"صحيح. الإصدار هو ما يتحدّث عنه الناس؛ والـ SHA يخبرك بالضبط أي commit تقرأ حين ينكسر شيء."},{"text":"الـ tag latest فقط، يُعاد دفعه مع كل merge إلى main.","why":"تفقد أي وسيلة لمعرفة أي بناء يعمل، أو للتراجع إلى بناء محدّد باسمه."},{"text":"تاريخ البناء، مثل 2026-10-05.","why":"بناءان في يوم واحد يتصادمان، والتاريخ لا يشير إلى الكود الذي أنتجه."},{"text":"اسم المطوّر، مثل amara-test.","why":"يصلح لتجربة عابرة، ولا فائدة منه لمعرفة ما يعمل في الإنتاج."}],"answer":0}],"exercise":{"kind":"order","items":["build","test","push","digest","manifest","apply","verify"],"title":"اشحن الإصدار 1.4.0","prompt":"رتّب خطوات إطلاق notes-api 1.4.0، من الكود المصدري إلى نشر متحقَّق منه يشغّل فيه كل node البايتات نفسها تمامًا.
\n","hints":["لا تستطيع اختبار image غير موجودة، ولا تستطيع قراءة digest لم يره الـ registry بعد.","يجب أن يشير الـ manifest إلى الـ digest، لذا يجب أن تعرف الـ digest قبل تعديله.","التحقّق يأتي في النهاية، بعد أن يحصل الـ cluster على المواصفات الجديدة."],"explanation":"ابنِ الـ image، واختبرها، وادفعها مع tag الإصدار وtag الـ SHA، واقرأ الـ digest الذي عيّنه الـ registry، واكتب هذا الـ digest في الـ manifest الخاص بالـ Deployment، وطبّقه، ثم تحقّق من الـ rollout. الاختبار قبل الدفع يُبقي البناءات المعطوبة خارج الـ registry، والنشر بالـ digest يعني أن ما اختبرته هو بالضبط ما يعمل.
\n","checkLabels":{},"itemText":{"build":"docker buildx build --platform linux/amd64,linux/arm64 -t ghcr.io/skylane/notes-api:1.4.0 -t ghcr.io/skylane/notes-api:sha-9f2c1ab .","test":"شغّل مجموعة الاختبارات وفحصًا أمنيًا على الـ image المبنية","push":"ادفع كلا الـ tags إلى ghcr.io","digest":"الأمر docker buildx imagetools inspect ghcr.io/skylane/notes-api:1.4.0 لقراءة الـ digest","manifest":"اضبط image: ghcr.io/skylane/notes-api:1.4.0@sha256:… في الـ manifest الخاص بالـ Deployment","apply":"kubectl apply -f k8s/","verify":"kubectl rollout status deployment/notes-api"}},"words":737,"readMinutes":4}