👨‍💻 تثبيت Docker Registry + واجهة ويب — سجل صور Docker خاص بك

انشر Docker Registry خاصاً على Ubuntu مع واجهة ويب — ادفع واسحب صور الحاويات الخاصة بك بمصادقة htpasswd، دون الاعتماد على Docker Hub.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت آلي — ينشر registry:2 على المنفذ 5011 مع واجهة ويب على المنفذ 8213 وبيانات اعتماد htpasswd مولّدة تلقائياً.
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/registry/registry-ubuntu.sh
chmod +x registry-ubuntu.sh
sudo bash registry-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/registry/registry-ubuntu.sh

2 منحه صلاحية التنفيذ

chmod +x registry-ubuntu.sh

3 تشغيل المثبّت

يثبّت السكريبت Docker إن لزم، وينشئ ملف htpasswd باسم مستخدم admin وكلمة مرور عشوائية، ثم يشغّل registry:2 على المنفذ 5011 وواجهة joxit/docker-registry-ui على المنفذ 8213.

sudo bash registry-ubuntu.sh

4 تسجيل الدخول ودفع صورة

صادق على السجل ببيانات الاعتماد المولّدة، ثم ضع علامة على صورة وادفعها:

docker login <your-server-ip>:5011
docker tag nginx:latest <your-server-ip>:5011/nginx:latest
docker push <your-server-ip>:5011/nginx:latest

المنافذ المستخدمة

المنفذالغرض
5011Registry API — docker login/push/pull (host → container 5000)
8213Web UI (joxit/docker-registry-ui, host → container 80)

نظرة عامة

Docker Registry (المعروف أيضاً باسم Distribution) هو التطبيق الرسمي مفتوح المصدر لتخزين وتوزيع صور حاويات Docker، ويُوزَّع كصورة registry:2 ويُصان ضمن مشروع distribution/distribution. يوفر واجهة Docker Registry HTTP API v2 التي يتحدث بها Docker CLI مباشرة لعمليات push وpull وlogin، بدون أي صيغة خاصة أو ارتباط بمزود معين. ولأن السجل الأساسي لا يأتي بواجهة رسومية على الإطلاق، يقترن هذا النشر بواجهة joxit/docker-registry-ui مفتوحة المصدر لتتمكن من تصفح المستودعات والوسوم من المتصفح بدلاً من الاعتماد على API فقط.

لماذا تستخدمه

تشغيل سجلك الخاص يعني أن صور الحاويات التي يبنيها فريقك لا تغادر بنيتك التحتية أبداً ولا تخضع لحدود سحب Docker Hub أو تكلفة المستودعات الخاصة في الخطط المدفوعة. كما يمنح خطوط CI/CD هدف push وpull سريعاً ومحلياً على نفس شبكة سيرفرات البناء، وهو أسرع وأكثر اعتمادية من الاعتماد على سجل خارجي في كل عملية نشر. بالنسبة للبيئات المنظمة أو الشبكات المعزولة عن الإنترنت أو الفرق التي تبني برمجيات مملوكة، تمنحك الاستضافة الذاتية للسجل تحكماً كاملاً في تخزين الصور والاحتفاظ بها والوصول إليها.

متى تحتاجه

  • تواجه حدود سحب معدل Docker Hub (rate limits) التي تعطّل بناءات CI/CD
  • تحتاج تخزيناً خاصاً لصور مملوكة دون دفع تكلفة مستودعات Docker Hub الخاصة أو خطة Teams
  • متطلبات تنظيمية أو إقامة بيانات تمنع خروج الصور من بنيتك التحتية
  • تحتاج مصدراً محلياً للصور في بيئة معزولة عن الإنترنت
  • خط CI/CD يحتاج هدف push/pull سريعاً على نفس الشبكة المحلية لسيرفرات البناء
  • عنقود Kubernetes أو Swarm يحتاج سحب الصور من سجل خاص دون اعتماد على الإنترنت الخارجي
  • عدة سيرفرات أو فرق تحتاج مشاركة صور مبنية داخلياً فيما بينها

من يحتاجه

  • مهندسو DevOps الذين يبنون خطوط CI/CD مخصصة ويحتاجون تخزين صور خاص
  • فرق التطوير التي تبني تطبيقات مملوكة لا يمكن نشر صورها على سجل عام
  • هواة الاستضافة الذاتية الذين يشغّلون عناقيد Kubernetes أو Docker Swarm في مختبراتهم المنزلية
  • الشركات الصغيرة التي تريد تجنب تكاليف Docker Hub للمستودعات الخاصة
  • البيئات المنظمة — المالية والصحية والحكومية — التي تتطلب تخزين صور داخلياً
  • الفرق التي تحتاج سجلاً بسيطاً دون الميزات المؤسسية الكاملة لـ Harbor أو Nexus

حالات الاستخدام الشائعة

  • تخزين وتوزيع صور التطبيقات المخصصة عبر عنقود Docker Swarm أو Kubernetes
  • تخزين مؤقت (mirror) لصور Docker Hub العامة محلياً لتفادي حدود المعدل أثناء بناءات CI
  • استضافة الصور الأساسية لبنية الخدمات المصغرة (microservices) الداخلية
  • العمل كهدف push لخطوط CI/CD مثل GitLab CI أو GitHub Actions أو Jenkins
  • توفير مصدر صور دون اتصال بالإنترنت للشبكات المعزولة
  • توزيع الصور على عدة سيرفرات طرفية دون الاعتماد على إنترنت خارجي

الميزات الرئيسية

  • تطبيق كامل لواجهة Docker Registry HTTP API v2 — متوافق مع docker push وpull وlogin
  • دعم مصادقة أساسية عبر htpasswd مدمج مباشرة دون الحاجة لسيرفر مصادقة خارجي
  • أدعمة تخزين قابلة للتوصيل: نظام ملفات محلي، أو Amazon S3 أو Azure Blob أو Google Cloud Storage للتخزين السحابي
  • دعم حذف الصور مع جامع قمامة (garbage collector) لاستعادة مساحة القرص
  • دعم TLS أصلي، أو يمكن وضعه خلف وكيل عكسي لإنهاء HTTPS
  • تخزين بالطبقات معنون بالمحتوى (content-addressable) يزيل تكرار الطبقات المشتركة لتوفير المساحة
  • واجهة ويب اختيارية من طرف ثالث (joxit/docker-registry-ui) لتصفح المستودعات والوسوم بصرياً
  • يعمل مع أي عميل متوافق مع OCI وليس Docker CLI فقط — بما في ذلك Podman وcontainerd

كيفية الاستخدام بعد التثبيت

  • احفظ كلمة مرور المسؤول المولّدة الظاهرة في نهاية سكريبت التثبيت — لن تظهر مجدداً إلا بإعادة توليد ملف htpasswd
  • شغّل docker login <server-ip>:5011 ببيانات الاعتماد المولّدة للمصادقة
  • ضع علامة على صورة محلية ببادئة السجل: docker tag myapp:latest <server-ip>:5011/myapp:latest
  • ادفع الصورة الموسومة: docker push <server-ip>:5011/myapp:latest
  • تصفح الصور والوسوم المدفوعة بصرياً على http://<server-ip>:8213 عبر واجهة الويب
  • اسحب الصورة من جهاز آخر بعد تسجيل الدخول: docker pull <server-ip>:5011/myapp:latest
  • أضف عنوان السجل ضمن insecure-registries في /etc/docker/daemon.json على أي عميل يحتاج push أو pull عبر HTTP عادي
  • ادمج رابط السجل في خطوط CI/CD كهدف push للصور المبنية

أفضل ممارسات الأمان

  • لا تكشف المنفذين 5011 أو 8213 مباشرة للإنترنت دون TLS — بيانات الاعتماد وطبقات الصور تنتقل بدون تشفير عبر HTTP عادي افتراضياً
  • ضع كلاً من API وواجهة الويب خلف وكيل عكسي (Nginx Proxy Manager) بشهادة TLS صالحة قبل السماح بالوصول الخارجي
  • قيّد الوصول على عناوين IP موثوقة أو VPN — واجهة الويب لا تملك مصادقة خاصة بها بخلاف ما يُضبط على السجل
  • دوّر بيانات اعتماد htpasswd دورياً واستخدم كلمة مرور قوية، فهي البوابة الوحيدة للتحكم بصلاحية الدفع
  • فعّل REGISTRY_STORAGE_DELETE_ENABLED فقط إذا كنت تحتاج فعلياً حذف الصور — تركه مفعّلاً يوسّع نطاق الضرر عند اختراق بيانات الاعتماد
  • حافظ على تحديث صورتي registry:2 وjoxit/docker-registry-ui للحصول على تصحيحات الأمان
  • عند الكشف للعامة، فكّر باستخدام مصادقة قائمة على التوكن (سيرفر مصادقة مخصص) بدلاً من htpasswd الثابت لصلاحيات أدق لكل مستودع
  • احجب منافذ السجل بجدار الحماية واسمح فقط بالاتصال الوارد من سيرفرات البناء وعُقد Kubernetes/Swarm والمسؤولين الذين يحتاجون فعلياً push/pull

المنافذ وإعدادات جدار الحماية

يربط هذا النشر المنفذ المضيف 5011 بمنفذ حاوية API الخاص بالسجل رقم 5000، والمنفذ المضيف 8213 بمنفذ حاوية واجهة الويب joxit رقم 80. كلاهما يعمل عبر HTTP عادي افتراضياً — بينما يتوقع Docker نفسه HTTPS للتواصل مع السجل، لذا يجب على أي عميل يدفع أو يسحب الصور إضافة عنوان السجل ضمن insecure-registries في /etc/docker/daemon.json، أو يمكنك وضع السجل خلف وكيل عكسي مثل Nginx Proxy Manager لإنهاء TLS على المنفذ 443. لا تكشف المنفذين 5011 أو 8213 مباشرة للإنترنت العام — احجبهما بجدار الحماية واسمح فقط بالاتصالات الواردة من سيرفرات البناء وعُقد Kubernetes/Swarm والمسؤولين، ويُفضّل عبر VPN أو نطاقات IP داخلية محصورة.

النسخ الاحتياطي والصيانة

  • انسخ احتياطياً دليل ./data الذي يحتوي كل طبقات الصور والبيانات الوصفية والـ blobs — وهو محتوى سجلك بالكامل
  • انسخ احتياطياً دليل ./auth الذي يحتوي ملف htpasswd ببيانات تسجيل الدخول
  • انسخ docker-compose.yml احتياطياً لتتمكن من إعادة إنشاء نفس الإعداد بالضبط — المنافذ ومتغيرات البيئة والأحجام — على مضيف جديد
  • شغّل registry garbage-collect دورياً على ملف الإعداد لاستعادة مساحة القرص من طبقات الصور المحذوفة
  • خزّن النسخ الاحتياطية بعيداً عن نفس القرص أو السيرفر — يجب أن تنجو نسخة السجل الاحتياطية من فقدان المضيف نفسه
  • اختبر استعادة دليل ./data على مثيل منفصل وتحقق من عمل docker pull ضد النسخة المستعادة
  • راقب استخدام القرص على حجم البيانات — السجلات تنمو بلا حدود دون جامع القمامة ويمكن أن تملأ القرص

الأخطاء الشائعة

  • كشف السجل مباشرة للإنترنت على المنفذين 5011 أو 8213 دون وكيل عكسي وTLS
  • نسيان إضافة عنوان السجل ضمن insecure-registries في daemon.json الخاص بـ Docker، مما يسبب خطأ "server gave HTTP response to HTTPS client"
  • فقدان كلمة مرور المسؤول المولّدة دون حفظها، ثم عدم القدرة على تسجيل الدخول إلا بإعادة توليد htpasswd
  • افتراض أن حذف وسم أو صورة يحرر مساحة القرص فوراً — الطبقات الفعلية تبقى حتى تشغيل جامع القمامة
  • عدم فصل حجم ./data عن نظام ملفات الحاوية، مما يعرّض البيانات لخطر الفقدان عند إعادة إنشاء الحاوية
  • التشغيل بدون أي مصادقة على الإطلاق، مما يسمح لأي شخص بدفع الصور والكتابة فوقها
  • عدم نسخ دليل ./data احتياطياً أبداً، والتعامل مع السجل كأنه قابل للاستغناء عنه

استكشاف الأخطاء وإصلاحها

  • "server gave HTTP response to HTTPS client" — أضف عنوان السجل ضمن insecure-registries في /etc/docker/daemon.json وأعد تشغيل Docker
  • فشل docker login بخطأ 401 unauthorized — تحقق أن اسم المستخدم وكلمة المرور تطابقان ملف htpasswd بالضبط، وتأكد من تركيب حجم ./auth بشكل صحيح
  • فشل الدفع بخطأ "blob upload unknown" — عادة بسبب انقطاع أو مهلة اتصال مع صورة كبيرة؛ أعد محاولة الدفع
  • واجهة الويب لا تُظهر أي مستودعات رغم نجاح عمليات الدفع — تأكد أن متغير البيئة REGISTRY_URL في الواجهة يشير لعنوان ومنفذ API الصحيحين
  • القرص يمتلئ حتى بعد حذف الصور — الحذف يزيل المراجع فقط؛ شغّل أمر registry garbage-collect داخل الحاوية لتحرير المساحة فعلياً
  • تعذر سحب الصور من سيرفر آخر على الشبكة — تحقق من قواعد جدار الحماية للمنفذ 5011 وتأكد أن ذلك السيرفر أيضاً لديه إدخال insecure-registries مضبوط
  • فشل تشغيل حاوية السجل — تحقق من تعارض المنافذ 5011 أو 8213 وراجع سجلات docker logs لحاوية السجل

البدائل

Harbor هو مشروع CNCF المتخرج ويقدّم ميزات مؤسسية كاملة — تحكم بالأدوار (RBAC)، فحص ثغرات بواسطة Trivy، توقيع الصور، وتكرار (replication) بين السجلات، مع واجهة ويب متكاملة، مقابل نشر أثقل يضم عدة حاويات وPostgres وRedis. Nexus Repository OSS يدعم Docker إلى جانب Maven وnpm وPyPI وصيغ أخرى في مستودع قِطَع (artifact) واحد شامل. GitLab Container Registry يأتي مدمجاً مع GitLab المستضاف ذاتياً ويتكامل بإحكام مع خطوط GitLab CI. الخيارات المُدارة سحابياً مثل Amazon ECR وGoogle Artifact Registry وAzure Container Registry تزيل كل عبء الصيانة لكن بتكلفة حسب الاستخدام وارتباط بالمزود. Verdaccio سجل خفيف الوزن أيضاً لكنه مصمم خصيصاً لحزم npm وليس صور Docker. لسجل خاص بسيط وذاتي الاستضافة ومجاني دون العبء التشغيلي لـ Harbor، فإن صورة registry:2 الأساسية مقترنة بواجهة ويب — كما في هذا النشر — هي الخيار الأبسط.

متى لا تستخدمه

إذا احتجت تحكماً بالأدوار (RBAC) أو فحص ثغرات أو توقيع صور أو تكراراً بين عدة سجلات، فإعداد registry:2 الأساسي هذا يفتقر لكل ذلك — استخدم Harbor بدلاً منه. إذا كان فريقك يدير أنواع قِطَع أخرى بالفعل مثل Maven وnpm وPyPI ويريد مدير مستودعات موحداً، فإن Nexus أو Artifactory خيار أنسب. إذا كنت لا تريد تشغيل أي بنية تحتية بنفسك وتقبل بالتسعير حسب الاستخدام، فإن سجلاً سحابياً مُداراً مثل ECR أو GCR أو ACR يزيل كل عبء الصيانة. وإذا كنت تحتاج فقط بضع صور خاصة بين الحين والآخر، فإن خطة Docker Hub المجانية تتضمن بالفعل مستودعاً خاصاً واحداً، وقد يكون أبسط من تشغيل سيرفرك الخاص.

هل تحتاج مساعدة احترافية؟

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

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما بيانات الاعتماد الافتراضية؟

اسم المستخدم هو admin وكلمة المرور نص عشوائي من 20 حرفاً يُولَّد أثناء التثبيت ويُطبع في النهاية. تُخزَّن كتجزئة bcrypt في ملف htpasswd ضمن دليل ./auth. احفظ كلمة المرور — فهي التي تتحكم بصلاحية دفع صورك.

ما المنافذ التي يستخدمها هذا النشر؟

منفذان: 5011 لواجهة API الخاصة بالسجل (منفذ الحاوية 5000)، وهو ما يستخدمه docker login وpush وpull، و8213 لواجهة joxit للويب (منفذ الحاوية 80). قيّد كليهما — فواجهة الويب يمكنها حذف الصور وAPI يتحكم بتخزين صورك.

لماذا يرفض Docker الدفع إلى سجلي؟

لأن السجل يعمل عبر HTTP عادي وDocker يتوقع HTTPS. سترى رسالة "server gave HTTP response to HTTPS client". أضف عنوان السجل إلى قائمة insecure-registries في /etc/docker/daemon.json على كل جهاز يحتاج الدفع أو السحب ثم أعد تشغيل Docker — أو الأفضل، ضع السجل خلف وكيل عكسي بشهادة TLS صالحة.

كيف أدفع صورة إلى سجلي؟

سجّل الدخول بـ docker login your-server-ip:5011، ضع علامة على الصورة ببادئة سجلك (docker tag nginx:latest your-server-ip:5011/nginx:latest)، ثم docker push your-server-ip:5011/nginx:latest. بادئة الوسم هي ما يخبر Docker بأي سجل يدفع إليه.

لماذا لا تتحرر مساحة القرص بعد حذف الصور؟

حذف وسم يزيل المرجع فقط — الطبقات الأساسية تبقى على القرص حتى يعمل جامع قمامة السجل. الحذف مفعّل هنا عبر REGISTRY_STORAGE_DELETE_ENABLED، لكن يجب تشغيل جامع القمامة بشكل منفصل لاستعادة المساحة فعلياً في ./data.