> ## 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.

# سجل Docker Images خاص: Registry وHarbor
- URL: https://arabroot.io/articles/سجل-docker-images-خاص-registry-و-harbor/
- Published: 2026-11-18T21:43:41.000Z
- Updated: 2026-11-18T22:50:35.000Z
- Description: نبني سجل Images خاصاً على سيرفرك بـ distribution مع TLS وكلمة مرور ثم بـ Harbor، ونرى ال Digest وجمع المهملات وفحص الثغرات ومنع تغيير ال Tags وذاكرة السحب أمام Docker Hub.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الحاويات Containers وتنسيقها مع Kubernetes, Docker والحاويات, الأمن السيبراني, الاستضافة الذاتية, Docker

كل Image شغلتها في مقالات هذه المرحلة جاءت من Docker Hub: تكتب `docker pull nginx` فيسحبها Docker من سيرفرات شركة أخرى، ثم تبني Image تطبيقك فوقها وتبقيها على جهازك. وهذا يعمل جيداً حتى تحتاج أن تنقل Image تطبيقك إلى سيرفر الإنتاج Production، أو أن يسحبها خط CI/CD Pipeline كل مرة، أو أن يستخدمها زميلك. فإما أن تنشرها في Docker Hub نفسه، وهي عندئذ عامة Public أو في مستودع خاص Private Repository محدود العدد حسب اشتراكك، وإما أن تنقلها يدوياً بـ `docker save` وملف tar، وإما أن يكون لك سجلك الخاص Private Registry على سيرفرك. وهناك سبب ثالث يدفع الفرق إلى السجل الخاص حتى لو كانت Images عامة: حدود السحب Rate Limits في Docker Hub، التي تتوقف عندها خطوط البناء فجأة برسالة `toomanyrequests`.

وفي هذا المقال سوف نبني سجلاً خاصاً على سيرفر حقيقي بطريقتين. الأولى السجل الرسمي البسيط distribution، وهو برنامج واحد صغير نشغله مع شهادة TLS وكلمة مرور، ونفهم من خلاله كيف يخزن السجل ال Images فعلاً، ولماذا لا تختفي المساحة Disk Space عند حذف Image. والثانية Harbor، وهو منصة كاملة فوق نفس البرنامج، تضيف الواجهة الرسومية Web UI والمستخدمين والمشاريع وفحص الثغرات وقواعد منع تغيير ال Tags. وقد ذكرنا في مقال [ما هي ال Containers؟](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/) الفرق بين ال Tag وال Digest، وهنا سوف نرى أثر هذا الفرق في سجل تملكه أنت.

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

- ما هو السجل Registry من الداخل: Blobs وManifests وTags، وواجهة HTTP API التي يتكلم بها.
- تشغيل distribution بشهادة TLS من جهة إصدار شهادات CA خاصة، ومصادقة Authentication بكلمة مرور، والخطأين اللذين ظهرا قبل أن يعمل.
- السحب بال Digest، وماذا يحدث عندما ترفع Image مختلفة بنفس ال Tag.
- الحذف وجمع المهملات Garbage Collection: لماذا لم تنقص المساحة إلا قليلاً.
- ذاكرة السحب Pull-through Cache، وقياس أثرها على حدود Docker Hub بالأرقام.
- Harbor: التثبيت والمتطلبات واستهلاك الذاكرة، والمشاريع، وفحص الثغرات بـ Trivy، ومنع تغيير ال Tags، وذاكرة السحب.
- Gitea Packages كخيار ثالث، والأخطاء الشائعة، وجدول القرار.

## ما هو السجل Registry من الداخل؟

السجل سيرفر HTTP Web Server يخزن ثلاثة أنواع من الأشياء، وتصفها [مواصفة OCI Distribution](https://github.com/opencontainers/distribution-spec/blob/main/spec.md?ref=arabroot.io) التي تتكلم بها كل السجلات اليوم:

- الكتل Blobs: ملفات مضغوطة لكل طبقة Layer في ال Image، وملف الإعداد Config الذي يصف ال Image (المتغيرات والأمر الذي يبدأ به). وكل Blob اسمه هو الهاش SHA-256 Hash لمحتواه، فلا يمكن أن يتغير محتواه دون أن يتغير اسمه.
- البيان Manifest: ملف JSON صغير يقول «هذه ال Image هي هذا ال Config وهذه الطبقات بهذا الترتيب»، وله أيضاً هاش هو ال Digest الذي تراه في `docker pull`. وقد يكون هناك فهرس Image Index فوقه يجمع Manifest لكل معمارية Architecture.
- الوسوم Tags: أسماء مثل `3.24` أو `latest`، وكل Tag مجرد مؤشر Pointer إلى Manifest، ويمكن نقله إلى Manifest آخر في أي لحظة.

والتشبيه Analogy القريب مكتبة Library: الكتل هي فصول الكتب، والبيان هو فهرس الكتاب الذي يقول أي فصول فيه وبأي ترتيب، وال Tag هو البطاقة على الرف التي تقول «الطبعة الحالية»، ويستطيع أمين المكتبة أن يضعها على كتاب آخر غداً. ولأن الفصول مخزنة بهاشها، فإذا اشترك كتابان في نفس الفصل فهو يخزن مرة واحدة، وهذا ما يجعل عشرات ال Images المبنية على `alpine` لا تأخذ مساحة `alpine` إلا مرة واحدة.

![رسم لمحتوى السجل: Tag اسمه 3.24 يشير إلى Manifest بالبصمة 0f49f331، والبيان يشير إلى Config بالبصمة 3ea06e4c وطبقة واحدة 881fc932 بحجم 3853673 بايت، ثم بعد رفع بناء جديد يتحرك ال Tag إلى Manifest fcad6563 الذي يشترك في نفس الطبقة 881fc932 ويضيف طبقة 737cc32c، مع واجهة HTTP /v2/ في الأسفل](https://arabroot.io/content/images/2026/11/container-registry-01-registry-model.webp)

ال Tag مؤشر متحرك، وال Manifest وال Blobs بأسماء من هاش محتواها

## ما هي الخيارات Options؟

قبل أن نبدأ، هذه الخيارات التي سوف تجدها لسجل خاص على سيرفرك، وكلها تتكلم نفس المواصفة، فأي Image تعمل مع أي منها:

| الخيار                                                                                                   | ما هو                                                                                                           | متى يناسب                                             |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [distribution](https://distribution.github.io/distribution/?ref=arabroot.io) (ال Image الرسمية registry) | برنامج واحد بلغة Go يخزن ويقدم ال Images، دون واجهة ودون مستخدمين                                               | سجل لفريق صغير أو لخط CI، وذاكرة سحب أمام Docker Hub  |
| [Harbor](https://goharbor.io/?ref=arabroot.io)                                                           | منصة من مشاريع CNCF المتخرجة Graduated، فوق distribution، مع واجهة ومشاريع وصلاحيات وفحص ثغرات ونسخ Replication | عدة فرق أو مؤسسة تحتاج صلاحيات وتدقيقاً Audit وسياسات |
| [Gitea Packages](https://docs.gitea.com/usage/packages/container?ref=arabroot.io)                        | سجل مدمج في Gitea بجانب المستودعات، بنفس المستخدمين                                                             | إذا كان عندك Gitea أصلاً وتريد ال Images بجانب الكود  |
| سجلات سحابية Cloud Registries                                                                            | GitHub Container Registry وغيره                                                                                 | إذا كنت لا تريد تشغيل أي شيء بنفسك                    |

وسوف نبدأ بـ distribution لأنه الأساس الذي يبني عليه Harbor نفسه، فما نتعلمه عنه يبقى صحيحاً في Harbor، ثم ننتقل إلى Harbor.

## السيرفر Server الذي سوف نعمل عليه

جهاز افتراضي Virtual Machine نظامه Debian 13 بذاكرة Memory مقدارها 6 GB ومعالجين CPU وقرص 8 GB، وعليه Docker Engine 29.10 كما في دليل [تثبيت Docker](https://arabroot.io/articles/%D8%AA%D8%AB%D8%A8%D9%8A%D8%AA-docker-%D8%B9%D9%84%D9%89-ubuntu/). والسجل سوف يكون باسم `reg.lab` وHarbor باسم `harbor.lab`، وكلاهما في ملف `/etc/hosts` على نفس الجهاز، وعلى سيرفرك سوف تستخدم اسم نطاق Domain حقيقياً مثل `registry.example.com`. وتأكد أولاً من إصدار السجل الذي سوف تسحبه:

```bash
docker run --rm registry:3 registry --version
docker run --rm registry:2 registry --version
```

```text
registry github.com/distribution/distribution/v3 3.1.2
registry github.com/docker/distribution 2.8.3
```

ال Tag `registry:2` الذي تجده في أغلب الأدلة القديمة هو السلسلة 2.8 من المستودع القديم `docker/distribution`، أما `registry:3` فهو الإصدار Version 3 من المشروع بعد أن انتقل إلى `distribution/distribution`، وهو ما سوف نستخدمه. والفرق العملي الذي يهمك أن مسار ملف الإعداد Configuration File تغير من `/etc/docker/registry/config.yml` إلى `/etc/distribution/config.yml`، فإذا نسخت أمراً من دليل قديم يذكر المسار القديم فسوف يفشل.

## سجل distribution بشهادة TLS وكلمة مرور Password

لا تقم بتشغيل سجل دون TLS ولو على شبكة داخلية، والسبب مزدوج: كلمة المرور تمر بنص واضح، وDocker نفسه يرفض أي سجل دون HTTPS إلا إذا أضفته يدوياً إلى قائمة `insecure-registries` على كل جهاز، وهذا يعني أن تضعف كل الأجهزة لتريح سيرفراً واحداً. وعلى سيرفر حقيقي باسم نطاق عام فالحل الأنسب شهادة Let's Encrypt عبر Reverse Proxy كما في دليل [Nginx Proxy Manager](https://arabroot.io/articles/nginx-proxy-manager-%D9%86%D8%B7%D8%A7%D9%82%D8%A7%D8%AA-%D9%88%D8%B4%D9%87%D8%A7%D8%AF%D8%A7%D8%AA-tls/)، أما في شبكة داخلية Internal Network فتستطيع أن تنشئ جهة إصدار شهادات خاصة CA كما سوف نفعل.

### الخطوة الأولى: جهة الإصدار CA والشهادة Certificate

```bash
mkdir -p /srv/reg/{certs,auth} && cd /srv/reg/certs
openssl req -x509 -newkey rsa:3072 -nodes -days 365 -subj "/CN=ct3 lab CA" -keyout ca.key -out ca.crt
openssl req -newkey rsa:2048 -nodes -subj "/CN=reg.lab" -keyout reg.key -out reg.csr
openssl x509 -req -in reg.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 90 -out reg.crt \
  -extfile <(printf "subjectAltName=DNS:reg.lab,DNS:harbor.lab\nextendedKeyUsage=serverAuth")
openssl x509 -in reg.crt -noout -subject -issuer -ext subjectAltName
```

```text
subject=CN=reg.lab
issuer=CN=ct3 lab CA
X509v3 Subject Alternative Name:
    DNS:reg.lab, DNS:harbor.lab
```

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

- الأمر الأول ينشئ جهة الإصدار نفسها، وهي شهادة توقع نفسها Self-signed مدتها سنة. ومفتاحها Private Key `ca.key` هو أهم ملف في القصة، فمن يملكه يستطيع أن يصدر شهادة لأي اسم يثق به أجهزتك، فاحفظه خارج السيرفر.
- الحقل المهم في الشهادة هو الأسماء البديلة Subject Alternative Name، لا الحقل `CN`، فبرامج Go ومنها Docker تتجاهل `CN` تماماً منذ سنوات، وشهادة بلا SAN سوف تعطيك خطأ `x509: certificate relies on legacy Common Name field`. ووضعنا الاسمين في شهادة واحدة لأننا سوف نستخدمها لـ Harbor أيضاً.

### الخطوة الثانية: المستخدم User وكلمة المرور Password

distribution يدعم أبسط طريقة مصادقة، ملف htpasswd، ويشترط أن تكون كلمة المرور بخوارزمية bcrypt، ولذلك نستخدم الخيار `-B`:

```bash
htpasswd -Bbn ci 'Lab-Pass-2026' > /srv/reg/auth/htpasswd
cut -c1-12 /srv/reg/auth/htpasswd
```

```text
ci:$2y$05$hy
```

البداية `$2y$` تعني bcrypt، والرقم `05` هو معامل الكلفة Cost، أي عدد جولات الهاش. وإذا نسيت `-B` فسوف يكتب htpasswd هاش MD5 القديم الذي يبدأ بـ `$apr1$`، ويرفضه السجل عند الدخول.

### الخطوة الثالثة: تشغيل السجل Registry

كل إعدادات السجل في ملف YAML، ويمكنك أن تكتب أي مفتاح فيه كمتغير بيئة Environment Variable يبدأ بـ `REGISTRY_` مع شرطة سفلية بين المستويات، كما في [توثيق الإعداد](https://distribution.github.io/distribution/about/configuration/?ref=arabroot.io)، وهذا ما سوف نفعله:

```bash
docker volume create ct3-regdata
docker run -d --name ct3-reg --restart unless-stopped -p 5000:5000 \
  -v ct3-regdata:/var/lib/registry -v /srv/reg/certs:/certs:ro -v /srv/reg/auth:/auth:ro \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/reg.crt -e REGISTRY_HTTP_TLS_KEY=/certs/reg.key \
  -e REGISTRY_AUTH=htpasswd -e REGISTRY_AUTH_HTPASSWD_REALM="ct3 lab" -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -e REGISTRY_STORAGE_DELETE_ENABLED=true registry:3
```

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

- البيانات في Named Volume اسمه `ct3-regdata`، لأن السجل كله ملفات على القرص، وإذا ضاعت ضاعت كل ال Images. وقد شرحنا اختيار مكان البيانات ونسخها في مقال [بيانات ال Containers](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/).
- الشهادات وملف كلمات المرور مركبة للقراءة فقط `:ro`.
- `REGISTRY_STORAGE_DELETE_ENABLED=true`: الحذف معطل افتراضياً، ودون هذا الخيار يرد السجل على أي طلب حذف بالخطأ `405 Method Not Allowed`.

### أول رفع Push: خطآن Errors قبل النجاح

نعطي `alpine:3.24` اسماً في سجلنا، ثم نرفعه:

```bash
docker tag alpine:3.24 reg.lab:5000/team/alpine:3.24
docker push reg.lab:5000/team/alpine:3.24
```

```text
failed to do request: Head "https://reg.lab:5000/v2/team/alpine/blobs/sha256:3ea06e4cb95e726ea6c6cc4377570ac4c4050d78710004cbd631ca809daf7e8e": tls: failed to verify certificate: x509: certificate signed by unknown authority
```

الخطأ الأول متوقع: Docker لا يعرف جهة الإصدار التي أنشأناها. ولا تقم بإضافة السجل إلى `insecure-registries` لتتجاوز الخطأ، فالحل الصحيح أن تضع شهادة جهة الإصدار في مجلد خاص بهذا السجل وحده، وDocker يقرؤه دون إعادة تشغيل، كما في [توثيق الشهادات](https://docs.docker.com/engine/security/certificates/?ref=arabroot.io):

```bash
mkdir -p /etc/docker/certs.d/reg.lab:5000
cp ca.crt /etc/docker/certs.d/reg.lab:5000/ca.crt
docker push reg.lab:5000/team/alpine:3.24
```

```text
push access denied, repository does not exist or may require authorization: authorization failed: no basic auth credentials
```

تجاوزنا TLS ووصلنا إلى الخطأ الثاني، وهو المصادقة Authentication. ولاحظ أن اسم المجلد Directory يجب أن يطابق ما تكتبه في الأمر بالضبط، مع المنفذ Port، فالمجلد `reg.lab` وحده لن ينفع مع `reg.lab:5000`. والآن ندخل:

```bash
echo 'Lab-Pass-2026' | docker login reg.lab:5000 -u ci --password-stdin
jq '.auths' ~/.docker/config.json
echo "Y2k6TGFiLVBhc3MtMjAyNg==" | base64 -d
```

```text
Login Succeeded
{
  "reg.lab:5000": {
    "auth": "Y2k6TGFiLVBhc3MtMjAyNg=="
  }
}
ci:Lab-Pass-2026
```

نجح الدخول، ولكن انظر أين حفظ Docker كلمة المرور: في `~/.docker/config.json` بترميز Base64 فقط، وفك الترميز Decoding بأمر واحد أعطانا كلمة المرور كما هي. فهذا ليس تشفيراً Encryption بأي معنى، وأي شخص يقرأ هذا الملف يملك حساب السجل. لذلك استخدم على الأجهزة المشتركة مساعد بيانات الدخول Credential Helper مثل `docker-credential-pass` أو `secretservice` كما في [توثيق docker login](https://docs.docker.com/reference/cli/docker/login/?ref=arabroot.io)، وفي خط CI أعط كل خط حساباً خاصاً بصلاحية السحب أو الرفع التي يحتاجها فقط، واحذف الملف في آخر المهمة.

والمحاولة الثالثة نجحت:

```text
881fc932939e: Pushed
3.24: digest: sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b size: 1022

 Info -> Not all multiplatform-content is present and only the available single-platform image was pushed
         sha256:f59abe656b692d901e184be3445e084786602108599d2a51d229c0f5a48c71bf -> sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
```

والسطر الأخير مهم وكثيرون لا يقرؤونه. فـ `alpine:3.24` على Docker Hub فهرس Index بالبصمة `f59abe65...` يجمع ثماني معماريات، كما رأينا في مقال ال Containers، ولكن جهازنا سحب منه معمارية amd64 فقط، فرفع Docker ال Manifest الخاص بها وحده، وبصمته `0f49f331...`. أي أن نفس ال Image لها في سجلك بصمة مختلفة عن بصمتها في Docker Hub. فإذا كتبت في ملف Compose البصمة التي نسختها من Docker Hub ثم غيرت السجل إلى سجلك، فلن يجد السحب ما تطلبه. والحل أن تأخذ البصمة من سجلك أنت بعد الرفع، أو أن تنسخ ال Images بكل معمارياتها بأداة مثل `docker buildx imagetools create` أو `skopeo copy --all`.

### ماذا حدث أثناء الرفع؟ الطلبات Requests من الداخل

قد يتساءل البعض: لماذا طبع Docker السطر `881fc932939e: Unavailable` أكثر من عشرين مرة قبل أن يكتب `Pushed`؟ والإجابة في طريقة الرفع نفسها كما تصفها مواصفة التوزيع، فالرفع ليس طلباً واحداً، وإنما سلسلة طلبات لكل طبقة ثم طلب أخير لل Manifest:

1. طلب `HEAD /v2/team/alpine/blobs/sha256:...` لكل طبقة: هل هذه الكتلة موجودة عندك؟ فإذا رد السجل بـ 200 فلا داعي لرفعها، وهذا ما يجعل رفع البناء الثاني سريعاً لأن الطبقة Layer المشتركة موجودة. وكان هذا الطلب نفسه هو الذي فشل في الخطأ الأول بسبب الشهادة، كما ترى في رسالته `Head "https://reg.lab:5000/v2/..."`.
2. طلب `POST /v2/team/alpine/blobs/uploads/` يفتح جلسة رفع، ويرد السجل بعنوان خاص بها، وهو العنوان IP Address الطويل الذي فيه `uploads/73b85c9d-...` في خطأ Harbor الذي سوف نراه.
3. طلب `PATCH` أو أكثر يرسل البيانات، ثم طلب `PUT` يغلق الجلسة ومعه الهاش، فيحسب السجل هاش ما وصله ويقارنه، ويرفض الكتلة إذا اختلفا. ولذلك لا يمكن أن تفسد طبقة أثناء النقل دون أن يعرف السجل.
4. بعد كل الطبقات، طلب `PUT /v2/team/alpine/manifests/3.24` يرفع ال Manifest، وهذه اللحظة وحدها هي التي يتحرك فيها ال Tag.

أما سطور `Unavailable` فهي حالة الطبقة في واجهة Docker أثناء انتظارها، وظهرت كثيراً لأن الجهاز كان بطيئاً والرفع يتقدم ببطء، فلا تعني خطأً إلا إذا انتهت برسالة فشل. والنقطة العملية من هذا الترتيب أن ال Tag لا يتحرك أبداً إلى Image ناقصة: إذا انقطع الرفع في منتصف الطبقات بقي ال Tag على البناء القديم، وبقيت الكتل التي وصلت يتيمة حتى يحذفها جمع المهملات.

### السجل كما تراه واجهة HTTP API

كل ما تفعله أداة `docker` طلبات HTTP عادية إلى المسار `/v2/`، وتستطيع أن تفعلها بـ curl:

```bash
curl -s -u ci:Lab-Pass-2026 --cacert ca.crt https://reg.lab:5000/v2/_catalog
curl -s -u ci:Lab-Pass-2026 --cacert ca.crt https://reg.lab:5000/v2/team/alpine/tags/list
curl -s -o /dev/null -w 'no password: %{http_code}\n' --cacert ca.crt https://reg.lab:5000/v2/_catalog
curl -s -u ci:Lab-Pass-2026 --cacert ca.crt -H 'Accept: application/vnd.oci.image.manifest.v1+json' https://reg.lab:5000/v2/team/alpine/manifests/3.24 | jq -c '{mediaType, config: .config.digest[0:19], layers: [.layers[] | {size, digest: .digest[0:19]}]}'
```

```text
{"repositories":["team/alpine"]}
{"name":"team/alpine","tags":["3.24"]}
no password: 401
{"mediaType":"application/vnd.oci.image.manifest.v1+json","config":"sha256:3ea06e4cb95e","layers":[{"size":3853673,"digest":"sha256:881fc932939e"}]}
```

هذا هو ال Manifest كاملاً تقريباً: ملف إعداد بصمته تبدأ بـ `3ea06e4c`، وطبقة واحدة حجمها 3853673 بايت أي 3.7 MB مضغوطة. وبدون كلمة المرور يرد السجل بـ 401\. ولاحظ الترويسة Header `Accept`، فالسجل يرد بنوع ال Manifest الذي تطلبه، وإذا لم تكتبها فقد يرد بنوع Docker القديم أو بخطأ.

## ال Tag يتحرك، وال Digest لا يتحرك

والآن التجربة التي تفسر نصف مشاكل الإنتاج مع ال Images. بنينا Image مختلفة فيها ملف إضافي، ورفعناها بنفس الاسم `team/alpine:3.24`:

```bash
printf 'FROM alpine:3.24\nRUN echo "build 2" > /build.txt\n' > /root/b/Dockerfile
docker build -t reg.lab:5000/team/alpine:3.24 /root/b
docker push reg.lab:5000/team/alpine:3.24
docker rmi -f reg.lab:5000/team/alpine:3.24
docker run --rm reg.lab:5000/team/alpine@sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b sh -c 'cat /build.txt'
docker run --rm reg.lab:5000/team/alpine:3.24 cat /build.txt
```

```text
3.24: digest: sha256:fcad6563acf333cdb5c31208462b3860c875d8560a1dfc0d7ec27df588c945db size: 744
cat: can't open '/build.txt': No such file or directory
3.24: Pulling from team/alpine
737cc32c3235: Pull complete
881fc932939e: Already exists
Digest: sha256:fcad6563acf333cdb5c31208462b3860c875d8560a1dfc0d7ec27df588c945db
build 2
```

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

- قبل السجل الرفع الجديد دون أي سؤال، ونقل ال Tag `3.24` إلى بصمة جديدة `fcad6563`. فال Tag في distribution قابل للتغيير Mutable دائماً، ولا يوجد خيار لمنع ذلك.
- السحب بالبصمة القديمة أعطانا ال Image القديمة كما هي، بلا الملف `/build.txt`، أي أن البصمة تثبت المحتوى مهما فعل أحد بال Tag.
- السحب بال Tag أعطانا البناء الثاني، وسحب الطبقة الجديدة `737cc32c` فقط، أما الطبقة `881fc932` فقال عنها `Already exists` لأنها مشتركة بين البناءين.

وتصور ما يعنيه هذا على سيرفرين يسحبان `myapp:1.4` في يومين مختلفين، وبينهما أعاد خط CI رفع نفس ال Tag بعد إصلاح صغير: يعمل على السيرفرين إصداران مختلفان بنفس الاسم، ولا يوجد أي أثر لذلك إلا البصمة. ولهذا السبب تمنع السجلات الجادة تغيير ال Tags كما سوف نرى في Harbor، وتكتب الفرق الجادة البصمة في ملفات النشر، كما شرح مقال تقليل حجم ال Images وتأمينها في قسم تثبيت ال Base Image بالبصمة.

## الحذف وجمع المهملات Garbage Collection

الآن لدينا في السجل بناءان، ال Tag يشير إلى الثاني، والأول ما زال موجوداً بالبصمة. فلنحذف الأول ونرى المساحة:

```bash
docker exec ct3-reg du -sh /var/lib/registry/docker/registry/v2/blobs
docker exec ct3-reg sh -c 'find /var/lib/registry/docker/registry/v2/blobs -name data | wc -l'
curl -s -u ci:Lab-Pass-2026 --cacert ca.crt -X DELETE -o /dev/null -w 'DELETE %{http_code}\n' \
  https://reg.lab:5000/v2/team/alpine/manifests/sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
docker exec ct3-reg du -sh /var/lib/registry/docker/registry/v2/blobs
```

```text
3.8M	/var/lib/registry/docker/registry/v2/blobs
6
DELETE 202
3.8M	/var/lib/registry/docker/registry/v2/blobs
```

قبل السجل الحذف برمز 202، ولكن المساحة لم تتغير إطلاقاً. والسبب أن الحذف في السجل يحذف المؤشر إلى ال Manifest فقط، أما الكتل نفسها فتبقى على القرص، لأن السجل لا يعرف في لحظة الحذف هل تستخدمها Image أخرى أم لا. وإيجاد الكتل التي لم يعد يشير إليها أحد عمل منفصل اسمه جمع المهملات Garbage Collection، يشرحه [توثيق GC](https://distribution.github.io/distribution/about/garbage-collection/?ref=arabroot.io)، وهو يعمل بطريقة Mark and Sweep: يمر على كل Manifest موجود ويعلم كل كتلة يشير إليها، ثم يحذف كل كتلة لم تعلم. ونبدأ بتجربة دون حذف `--dry-run`:

```bash
docker exec ct3-reg registry garbage-collect --dry-run /etc/distribution/config.yml
```

```text
team/alpine: marking blob sha256:737cc32c32359b92e4ea9b3690dc8b95d5f663adff88e9a318b2fcfbd0e03695

4 blobs marked, 2 blobs and 0 manifests eligible for deletion
blob eligible for deletion: sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
blob eligible for deletion: sha256:3ea06e4cb95e726ea6c6cc4377570ac4c4050d78710004cbd631ca809daf7e8e
```

من ست كتل علم أربعاً لأن ال Manifest الحالي يشير إليها، واثنتان فقط قابلتان للحذف: ال Manifest القديم `0f49f331` نفسه، وملف الإعداد القديم `3ea06e4c`. أما الطبقة الكبيرة `881fc932` فلن تحذف لأن البناء الثاني يستخدمها. ثم شغلنا الحذف الحقيقي، والسجل متوقف:

```bash
docker stop ct3-reg
docker run --rm -v ct3-regdata:/var/lib/registry registry:3 registry garbage-collect --delete-untagged /etc/distribution/config.yml
docker start ct3-reg
docker exec ct3-reg du -sh /var/lib/registry/docker/registry/v2/blobs
curl -s -u ci:Lab-Pass-2026 --cacert ca.crt -o /dev/null -w 'old digest after gc: %{http_code}\n' https://reg.lab:5000/v2/team/alpine/manifests/sha256:0f49f331d9212aff11b932863be4eb01cdf962969aa86dab7d1ee21ac6f5f52b
```

```text
3.7M	/var/lib/registry/docker/registry/v2/blobs
4
old digest after gc: 404
```

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

- نزلت المساحة من 3.8M إلى 3.7M فقط، ومن ست كتل إلى أربع، لأن ما حذف ملفان صغيران والطبقة الكبيرة مشتركة. وفي سجل حقيقي يعيد فيه CI بناء Images كل يوم بنفس ال Base Image فالمساحة التي يحررها GC هي طبقات التطبيق فقط، لا ال Base Image.
- أوقفنا السجل قبل GC لأن التوثيق يحذر من أن الرفع أثناء GC قد يجعله يحذف كتلة رفعت للتو ولم يكتب لها Manifest بعد، فتفسد ال Image. لذلك شغله في وقت صيانة Maintenance Window أو اجعل السجل للقراءة فقط أثناءه.
- الخيار `--delete-untagged` يحذف أيضاً كل Manifest لا يشير إليه أي Tag. وهذا مفيد للمساحة، ولكن انتبه: لو كان عندك سيرفر يسحب بالبصمة القديمة لصار يحصل على 404 كما رأينا، فلا تستخدمه إذا كانت ملفات النشر تكتب البصمات.

![ثلاث مراحل للتخزين: قبل الحذف ست كتل بحجم 3.8M، وبعد DELETE برمز 202 نفس الكتل الست ونفس الحجم لأن الحذف يزيل المؤشر فقط، وبعد garbage-collect أربع كتل بحجم 3.7M حيث حذف ال Manifest القديم 0f49f331 والإعداد 3ea06e4c وبقيت الطبقة المشتركة 881fc932، والبصمة القديمة ترد 404](https://arabroot.io/content/images/2026/11/container-registry-02-gc.webp)

الحذف يزيل المؤشر، وجمع المهملات وحده يحرر الكتل التي لم يعد يشير إليها أحد

## ذاكرة السحب Pull-through Cache وحدود Docker Hub

تقول [صفحة حدود الاستخدام في Docker Hub](https://docs.docker.com/docker-hub/usage/?ref=arabroot.io)، كما قرأناها في 18 نوفمبر 2026، إن المستخدم دون حساب Unauthenticated له 100 سحبة في كل 6 ساعات لكل عنوان IPv4 أو شبكة IPv6 من الحجم Size `/64`، والحساب الشخصي المجاني Personal له 200، وحسابات Pro وTeam وBusiness دون حد مع سياسة الاستخدام العادل Fair Use. وتشرح [صفحة السحب](https://docs.docker.com/docker-hub/usage/pulls/?ref=arabroot.io) أن كل سحب Manifest يحسب، وأن ال Image متعددة المعماريات تحسب مرة لكل معمارية، وأن طلب HEAD لا يحسب، ولذلك تستطيع أن تعرف ما بقي لك دون أن تستهلك منه:

```bash
TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull" | jq -r .token)
curl -s --head -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest | grep -i ratelimit
```

```text
docker-ratelimit-source: x.x.x.x
ratelimit-limit: 100;w=3600
ratelimit-remaining: 100;w=3600
```

أخفينا عنوان IP. ولاحظ الرقم `w=3600`: هذا طول النافذة Window بالثواني، أي ساعة واحدة، بينما تقول الصفحة 6 ساعات ومثالها في صفحة السحب `w=21600`. فالقيمة التي يرسلها Docker Hub فعلاً لعنواننا في يوم التجربة كانت 100 في الساعة، والدرس أن تقرأ الترويسة من عنوانك أنت قبل أن تخطط، لأن الأرقام تتغير. والمشكلة الحقيقية أن كل السيرفرات خلف نفس عنوان NAT في مكتب أو مركز بيانات Data Center تتقاسم نفس الحد، فعشرة خطوط CI تبني في نفس الساعة تكفي لتصل إلى الحد Limit.

والحل ذاكرة سحب Pull-through Cache: سجل distribution في وضع الوكيل Proxy، يسحب من Docker Hub في المرة الأولى ويحفظ نسخة، ثم يقدمها من عنده في كل مرة بعدها، كما في [توثيق المرآة Mirror](https://distribution.github.io/distribution/recipes/mirror/?ref=arabroot.io):

```bash
docker volume create ct3-cachedata
docker run -d --name ct3-cache --restart unless-stopped -p 127.0.0.1:5001:5000 -v ct3-cachedata:/var/lib/registry \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io -e REGISTRY_PROXY_TTL=168h registry:3
echo '{"registry-mirrors":["http://127.0.0.1:5001"]}' > /etc/docker/daemon.json && systemctl restart docker
docker info --format '{{json .RegistryConfig.Mirrors}}'
```

```text
["http://127.0.0.1:5001/"]
```

الخيار `registry-mirrors` في `daemon.json` يجعل Docker يسأل المرآة أولاً عن أي Image من Docker Hub، وإذا فشلت المرآة يذهب إلى Docker Hub مباشرة. واستخدمنا HTTP دون TLS هنا لأن المرآة على `127.0.0.1` في نفس الجهاز، أما إذا وضعتها على سيرفر يخدم عدة أجهزة فاجعلها خلف TLS كالسجل الأول. والآن القياس الذي يهمك، عدد السحبات المتبقية في Docker Hub قبل وبعد كل سحب:

```text
before:                       ratelimit-remaining: 95;w=3600
after 1st pull via cache:     ratelimit-remaining: 93;w=3600
after 2nd pull via cache:     ratelimit-remaining: 93;w=3600
after 3rd pull via cache:     ratelimit-remaining: 93;w=3600
after a pull with cache down: ratelimit-remaining: 92;w=3600
```

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

- كان الرصيد 95 لأن التجارب السابقة في هذا المقال استهلكت خمساً.
- السحب الأول عبر المرآة لـ `busybox:1.37` استهلك اثنتين، لأن المرآة سحبت الفهرس ثم Manifest المعمارية، والصفحة تقول إن كل Manifest يحسب.
- السحب الثاني والثالث بعد حذف ال Image محلياً لم يستهلكا شيئاً، فالرصيد بقي 93، والمرآة قدمت ال Image من عندها.
- عندما أوقفنا المرآة نجح السحب لأن Docker ذهب إلى Docker Hub مباشرة، ولكنه استهلك واحدة. أي أن توقف المرآة لا يوقف عملك، ولكنه يعيدك إلى الحد دون أن تشعر.

وجربنا أيضاً أن نرفع Image إلى المرآة نفسها فرفضت بـ `unauthorized`، لأن السجل في وضع الوكيل للقراءة فقط، فلا يمكن أن تستخدم نفس السجل مرآة وسجلاً لتطبيقاتك في وقت واحد. والخيار `REGISTRY_PROXY_TTL=168h` يجعل المرآة تحذف النسخ التي لم تستخدم خلال أسبوع، وإذا كتبت `REGISTRY_PROXY_USERNAME` و`REGISTRY_PROXY_PASSWORD` لحساب Docker Hub فسوف تحسب السحبات على حسابك لا على عنوانك.

![رسم لسيرفر يسحب busybox عبر ذاكرة السحب ct3-cache التي تسحب من Docker Hub مرة واحدة، مع عداد السحبات المتبقية: 95 قبل، و93 بعد السحب الأول، و93 بعد الثاني والثالث، و92 بعد سحب مباشر عندما توقفت الذاكرة، وبطاقة تقول إن الحد في الترويسة كان 100 في نافذة 3600 ثانية بينما تقول الصفحة 6 ساعات](https://arabroot.io/content/images/2026/11/container-registry-03-pull-through.webp)

ثلاث سحبات عبر الذاكرة كلفت سحبتين، وسحبة مباشرة واحدة كلفت واحدة

## Harbor: سجل بمشاريع Projects وصلاحيات Permissions وفحص للثغرات Vulnerabilities

ما بنيناه حتى الآن يكفي فريقاً صغيراً، ولكن انظر إلى ما ينقصه: مستخدم واحد في ملف htpasswd يرفع ويسحب كل شيء، ولا يوجد أي فصل بين مشروع وآخر، ولا يوجد أي سجل لمن رفع ماذا، وال Tags قابلة للتغيير دائماً، ولا يعرف أحد ما في ال Images من ثغرات Vulnerabilities. و[Harbor](https://goharbor.io/?ref=arabroot.io) يضيف كل هذا فوق نفس برنامج distribution: المشاريع Projects بصلاحيات لكل مستخدم ومجموعة، والدخول عبر LDAP أو OIDC، وسجل التدقيق Audit Log، وفحص الثغرات Vulnerability Scanning بـ Trivy، وقواعد منع تغيير ال Tags، وقواعد الاحتفاظ Retention، والنسخ Replication بين السجلات، وذاكرة السحب لعدة سجلات خارجية. وهو من المشاريع المتخرجة في [CNCF](https://www.cncf.io/projects/harbor/?ref=arabroot.io).

### التثبيت Installation: المتطلبات Requirements والوقت

تقول [صفحة المتطلبات](https://goharbor.io/docs/latest/install-config/installation-prereqs/?ref=arabroot.io) إن الحد الأدنى معالجان وذاكرة 4 GB وقرص 40 GB، والموصى به 4 معالجات و8 GB و160 GB، مع Docker Engine وCompose. والتثبيت من [صفحة الإصدارات Releases](https://github.com/goharbor/harbor/releases?ref=arabroot.io)، وفيها مثبت دون إنترنت Offline Installer يحمل كل ال Images في ملف واحد كبير، ومثبت عبر الإنترنت Online Installer صغير يسحبها أثناء التثبيت، واستخدمنا الثاني بالإصدار 2.16.0 الصادر في 10 نوفمبر 2026:

```bash
curl -fsSL -o harbor.tgz https://github.com/goharbor/harbor/releases/download/v2.16.0/harbor-online-installer-v2.16.0-amd64.tgz
tar -xzf harbor.tgz && cd harbor && cp harbor.yml.tmpl harbor.yml
# in harbor.yml: hostname, the certificate and key, the admin password, the data folder
sed -i 's/^hostname: .*/hostname: harbor.lab/' harbor.yml
sed -i 's#certificate: /your/certificate/path#certificate: /srv/reg/certs/reg.crt#; s#private_key: /your/private/key/path#private_key: /srv/reg/certs/reg.key#' harbor.yml
sed -i 's/^harbor_admin_password: .*/harbor_admin_password: Lab-Admin-2026/' harbor.yml
sed -i 's#^data_volume: .*#data_volume: /srv/harbor-data#' harbor.yml
./install.sh --with-trivy
```

وواجهنا هنا مشكلة صغيرة قبل البدء: الرابط الذي كتبناه أولاً بالاسم المعتاد `harbor-online-installer-v2.16.0.tgz` أعطى 404، لأن ملفات الإصدار 2.16.0 صارت تحمل المعمارية في اسمها `-amd64` و`-arm64`، بينما الإصدار 2.15.5 ما زال بالاسم القديم. فلا تنسخ رابط التحميل من دليل قديم، وخذه من صفحة الإصدار نفسها. والمخرج سوف يكون كما يلي:

```text
[Step 0]: checking if docker is installed ...
[Step 1]: checking docker-compose is installed ...
[Step 2]: preparing environment ...
[Step 3]: preparing harbor configs ...
[Step 4]: starting Harbor ...
✔ ----Harbor has been installed and started successfully.----
install took 2263 s
```

أخذ التثبيت 38 دقيقة تقريباً، ومعظمها سحب إحدى عشرة Image حجمها على القرص بين 218 MB و679 MB، أكبرها `trivy-adapter-photon`، مع اتصال إنترنت بطيء في المختبر لم يتجاوز 1 MB في الثانية، فارتفع استخدام القرص في الجهاز من 947M إلى 4.4G. وبعد التشغيل مباشرة وجدنا أحد ال Containers يعيد التشغيل:

```text
harbor-core Up About a minute (health: starting)
harbor-db Up 3 minutes (healthy)
harbor-jobservice Restarting (2) 40 seconds ago
```

وهذا ليس عطلاً، فخدمة المهام `jobservice` تحتاج `harbor-core` جاهزاً وتخرج إذا لم تجده، فتعيدها سياسة الإعادة حتى يجهز. وبعد دقائق كانت كل المكونات `healthy` في نقطة الصحة Health Endpoint:

```text
[{"name":"core","status":"healthy"},{"name":"database","status":"healthy"},{"name":"jobservice","status":"healthy"},{"name":"portal","status":"healthy"},{"name":"redis","status":"healthy"},{"name":"registry","status":"healthy"},{"name":"registryctl","status":"healthy"},{"name":"trivy","status":"healthy"}]
```

وهذه عشرة Containers بدلاً من واحد، وهذا استهلاكها من الذاكرة بعد أن عملت عليها كل تجارب هذا القسم:

```text
harbor-jobservice 22.82MiB
nginx 6.309MiB
harbor-core 65.69MiB
trivy-adapter 66.68MiB
harbor-db 94.77MiB
redis 10.06MiB
registry 34.77MiB
harbor-portal 2.887MiB
registryctl 13.15MiB
harbor-log 4.445MiB
harbor total: 322 MiB
```

أي 322 MiB لكل المنصة، مقابل 14 MiB لسجل distribution وحده. والرقم أقل بكثير من 4 GB في المتطلبات، ولكن لا تعتمد عليه، فالفحص يستهلك ذاكرة أكثر بكثير أثناء عمله، وقاعدة البيانات تكبر مع عدد ال Images، والتوصية مكتوبة لسيرفر يخدم فريقاً لا لمختبر فيه Image واحدة.

![رسم لمكونات Harbor العشرة خلف nginx: harbor-core وharbor-portal وharbor-jobservice وregistry وregistryctl وharbor-db وredis وtrivy-adapter وharbor-log، مع ذاكرة كل منها من المختبر والمجموع 322 MiB مقابل 14 MiB لسجل distribution، ومدة التثبيت 2263 ثانية](https://arabroot.io/content/images/2026/11/container-registry-04-harbor-stack.webp)

عشرة Containers و322 MiB بدلاً من Container واحد و14 MiB

### المشاريع Projects والرفع Push

كل Image في Harbor تعيش داخل مشروع، والصلاحيات Permissions تعطى على مستوى المشروع: مدير المشروع Project Admin، والمطور Developer الذي يرفع، والضيف Guest الذي يسحب فقط، وحسابات الروبوت Robot Accounts لخطوط CI بصلاحيات محددة ومدة صلاحية. وكل ما في الواجهة متاح في واجهة Harbor البرمجية بالمسار `/api/v2.0`، فأنشأنا المشروع `team` ثم رفعنا nginx:

```bash
curl -s -u admin:Lab-Admin-2026 --cacert ca.crt -X POST -H 'Content-Type: application/json' \
  -d '{"project_name":"team","public":false}' https://harbor.lab/api/v2.0/projects
mkdir -p /etc/docker/certs.d/harbor.lab && cp ca.crt /etc/docker/certs.d/harbor.lab/ca.crt
echo 'Lab-Admin-2026' | docker login harbor.lab -u admin --password-stdin
docker tag nginx:1.29-alpine harbor.lab/team/nginx:1.29-alpine
docker push harbor.lab/team/nginx:1.29-alpine
```

```text
create project: 201
Login Succeeded
failed commit on ref "layer-sha256:583599bb...": failed to do request: Put "https://harbor.lab/v2/team/nginx/blobs/uploads/73b85c9d-...": net/http: timeout awaiting response headers
```

الرفع الأول فشل بانتهاء المهلة Timeout، وكان السيرفر في تلك اللحظة تحت ضغط Load شديد بمتوسط 7 على معالجين، لأن Harbor كان ما زال يكمل بدء مكوناته. وأعدنا الرفع نفسه بعد دقائق فنجح:

```text
1.29-alpine: digest: sha256:3bcf852aed06467cf075c6105892e4d5a6ebbbafa0ce22d35062db9e90ddef4c size: 2495
```

والدرس أن خط CI يجب أن يعيد المحاولة Retry عند أخطاء الشبكة والمهلة، فالرفع عملية طويلة بطبيعتها، ولا يعني فشلها مرة أن في السجل خطأ. ولاحظ أننا استخدمنا حساب `admin` للتجربة فقط، وفي الإنتاج أنشئ حساب روبوت لكل خط.

### فحص الثغرات Vulnerability Scanning بـ Trivy: المشكلة الثالثة Problem

طلبنا فحص ال Image، وكانت النتيجة بعد تسع دقائق كما يلي:

```text
scan status: Error after ~555 s
```

فقرأنا سجل `trivy-adapter`، وهذه آخر سطوره:

```text
[vulndb] Need to update DB
[vulndb] Downloading vulnerability DB...
[vulndb] Downloading artifact...	repo="ghcr.io/aquasecurity/trivy-db:2"
[vulndb] Artifact successfully downloaded	repo="ghcr.io/aquasecurity/trivy-db:2"
[vuln] Vulnerability scanning is enabled
WARN	Provide a higher timeout value, see https://trivy.dev/docs/v0.76/guide/references/troubleshooting#timeout
FATAL	Fatal error	run error: image scan error: scan error: scan failed: failed analysis: analyze error: pipeline error: context deadline exceeded
```

والقصة واضحة من الأوقات: Trivy لا يحمل قاعدة بيانات الثغرات Vulnerability Database مع ال Image، وإنما يسحبها من `ghcr.io` في أول فحص، وأخذ ذلك عندنا من 20:16:33 إلى 20:25:01 أي ثماني دقائق ونصفاً، فلما بدأ التحليل Analysis نفسه كانت مهلة الفحص قد انتهت تقريباً. أي أن الفحص الأول على أي Harbor جديد قد يفشل لسبب لا علاقة له بال Image. وأعدنا الفحص بعد أن صارت القاعدة عنده:

```text
rescan requested: 202
scan status: Success after 131 s
{"severity":"Critical","total":241,"fixable":241,"summary":{"Critical":1,"High":57,"Low":96,"Medium":85,"Unknown":2},"scanner":"Trivy","version":"v0.76.1","duration":111}
CVE-2026-111497 Critical brotli-libs 1.2.0-r0 -> 1.2.1-r0
CVE-2026-33630 High c-ares 1.34.6-r0 -> 1.34.8-r0
CVE-2026-11352 High curl 8.17.0-r1 -> 8.22.0-r0
CVE-2026-5773 High curl 8.17.0-r1 -> 8.20.0-r0
```

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

- 241 ثغرة في Image واحدة من nginx الرسمية، منها واحدة حرجة Critical و57 عالية High، وكلها في حزم Alpine داخل ال Image مثل `curl` و`brotli-libs`، لا في nginx نفسه.
- الحقل `fixable` يساوي 241، أي أن لكل ثغرة إصداراً مصلحاً موجوداً، والسهم في كل سطر يقول الإصدار الذي يصلحها، مثل `curl 8.17.0-r1 -> 8.22.0-r0`. والسبب أن هذه النسخة المحلية من ال Image سحبت قبل أشهر، وال Tag `1.29-alpine` على Docker Hub انتقل منذ ذلك الوقت إلى بناءات أحدث، فالحل هنا سحب البناء الأحدث، وهذا ما يشرحه مقال تقليل حجم ال Images وتأمينها بالتفصيل.
- نجح الفحص في 131 ثانية بعد أن كانت القاعدة موجودة، منها 111 ثانية للتحليل نفسه.

وفي إعدادات المشروع تستطيع أن تفعل الفحص التلقائي عند كل رفع، وأن تمنع سحب أي Image فيها ثغرة فوق درجة معينة، كما في [توثيق الفحص](https://goharbor.io/docs/latest/administration/vulnerability-scanning/?ref=arabroot.io). وانتبه قبل تفعيل المنع على مشروع يسحب منه الإنتاج: بهذه النتيجة سوف يتوقف سحب nginx فوراً، وقد يكون ذلك أثناء إعادة تشغيل Restart طارئة.

### منع تغيير ال Tags Tag Immutability

هذه هي الميزة Feature التي لا يقدمها distribution، وهي تحل مشكلة ال Tag المتحرك التي رأيناها. أضفنا قاعدة للمشروع تجعل كل Tag في كل مستودع غير قابل للتغيير، كما في [توثيق القاعدة](https://goharbor.io/docs/latest/working-with-projects/working-with-images/create-tag-immutability-rules/?ref=arabroot.io)، ثم حاولنا أن نرفع بناءً مختلفاً بنفس ال Tag:

```bash
curl -s -u admin:Lab-Admin-2026 --cacert ca.crt -X POST -H 'Content-Type: application/json' \
  -d '{"disabled":false,"action":"immutable","template":"immutable_template","tag_selectors":[{"kind":"doublestar","decoration":"matches","pattern":"**"}],"scope_selectors":{"repository":[{"kind":"doublestar","decoration":"repoMatches","pattern":"**"}]}}' \
  https://harbor.lab/api/v2.0/projects/$PROJECT_ID/immutabletagrules
docker build -t harbor.lab/team/nginx:1.29-alpine /root/b2
docker push harbor.lab/team/nginx:1.29-alpine
docker tag harbor.lab/team/nginx:1.29-alpine harbor.lab/team/nginx:1.29-alpine-b2
docker push harbor.lab/team/nginx:1.29-alpine-b2
curl -s -u admin:Lab-Admin-2026 --cacert ca.crt -X DELETE -o /dev/null -w 'delete: %{http_code}\n' https://harbor.lab/api/v2.0/projects/team/repositories/nginx/artifacts/1.29-alpine-b2
```

```text
immutable rule: 201
error from registry: Failed to process request due to 'nginx:1.29-alpine' configured as immutable.
1.29-alpine-b2: digest: sha256:d59ab1816500546daa95ad9fbaca4fabec66d7090f1037725ce6ea23fb88e33a size: 2255
delete: 412
```

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

- رفض Harbor رفع بناء مختلف بنفس ال Tag، وهذا بالضبط ما نريده: `1.29-alpine` في هذا المشروع يعني محتوى واحداً إلى الأبد.
- نجح رفع نفس البناء باسم جديد `1.29-alpine-b2`، فالقاعدة لا تمنع ال Tags الجديدة، وإنما تمنع تغيير الموجودة.
- حذف `1.29-alpine-b2` رفض أيضاً برمز 412، لأن النمط `**` يشمل كل Tag، والقاعدة تمنع الحذف كما تمنع الكتابة فوقه. لذلك لا تقم بكتابة `**` في مشروع يرفع إليه CI بناءً لكل Commit، وإلا لن تستطيع قواعد الاحتفاظ حذف شيء، واكتب نمطاً للإصدارات فقط مثل `v*`.

وطلبنا بعد ذلك جمع المهملات من Harbor بطلب واحد إلى `/api/v2.0/system/gc/schedule`، فانتهى بنجاح ولكن حجم مجلد السجل بقي 31M قبله وبعده، والسبب نفسه: لم نستطع حذف أي Tag في المشروع `team`، فلا توجد كتل يتيمة. وGC في Harbor يعمل بنفس فكرة distribution، ولكن Harbor يجدوله ويشغله دون أن توقف السجل، ويكتب سجلاً لكل تشغيل، كما في [توثيق GC في Harbor](https://goharbor.io/docs/latest/administration/garbage-collection/?ref=arabroot.io).

### قواعد الاحتفاظ Retention: من يحذف بناءات Builds خط CI القديمة؟

خط CI يرفع Image لكل Commit، وبعد شهر يصبح في المشروع مئات ال Tags لا يحتاجها أحد، وكل منها يمسك طبقاته فلا يحررها جمع المهملات. وقواعد الاحتفاظ في Harbor، كما في [توثيق Tag Retention](https://goharbor.io/docs/latest/working-with-projects/working-with-images/create-tag-retention-rules/?ref=arabroot.io)، تحل ذلك بقواعد مثل «احتفظ بآخر عشرة Tags تطابق `main-*`» أو «احتفظ بكل ما سحب خلال 30 يوماً»، وتعمل في جدول زمني، وتستطيع أن تجربها دون حذف Dry Run أولاً لترى ما سوف تحذفه. والترتيب الصحيح أن تعمل قاعدة الاحتفاظ أولاً فتحذف ال Tags، ثم يعمل جمع المهملات بعدها فيحرر الكتل. وتذكر ما رأيناه في قسم منع التغيير: ال Tags المحمية بقاعدة Immutability لا تحذفها قاعدة الاحتفاظ، فاجعل الحماية للإصدارات والاحتفاظ لبناءات الفروع Branches.

وإذا كنت توقع ال Images قبل نشرها كما في مقال [SBOM مع Syft ثم توقيع ال Images مع cosign](https://arabroot.io/articles/sbom-%D9%85%D8%B9-syft-%D8%AB%D9%85-%D8%AA%D9%88%D9%82%D9%8A%D8%B9-%D8%A7%D9%84-images-%D9%85%D8%B9-cosign/)، فإن Harbor يخزن التوقيع وقائمة المكونات SBOM كقطع Artifacts مرتبطة بال Image نفسها في نفس المستودع، ويعرضها بجانبها، ويستطيع أن يمنع سحب أي Image غير موقعة في المشروع. وهذا ما يجعل البصمة والتوقيع ومنع التغيير تعمل معاً: البصمة تثبت المحتوى، والتوقيع يثبت من بناه، ومنع التغيير يثبت أن الاسم لن يشير إلى غيره.

### ذاكرة السحب Proxy Cache في Harbor

وأخيراً أنشأنا نقطة اتصال Endpoint لـ Docker Hub ومشروعاً من نوع ذاكرة السحب اسمه `hub`، كما في [توثيق Proxy Cache](https://goharbor.io/docs/latest/administration/configure-proxy-cache/?ref=arabroot.io)، ثم سحبنا من خلاله:

```bash
docker pull harbor.lab/hub/library/busybox:1.37
```

```text
registry endpoint: 201
proxy project: 201
harbor.lab/hub/library/busybox:1.37
[]
[{"name":"hub/library/busybox","artifact_count":2}]
```

نجح السحب، ولكن قائمة مستودعات المشروع كانت فارغة `[]` مباشرة بعده، وبعد دقائق ظهر المستودع وفيه قطعتان Artifacts: الفهرس وManifest المعمارية. فـ Harbor يقدم ال Image للعميل أولاً ثم يكتبها في مشروعه في الخلفية. والفرق عن ذاكرة distribution أن الاسم هنا صريح `harbor.lab/hub/library/busybox`، فتكتبه في ملفات Compose وفي ال Dockerfile، ويمر تحت نفس الصلاحيات والفحص، وتستطيع أن تضع عدة مشاريع ذاكرة لعدة سجلات خارجية مثل `ghcr.io` و`quay.io`. أما distribution فيعمل كمرآة شفافة لـ Docker Hub وحده عبر `registry-mirrors` دون تغيير الأسماء.

![ثلاث بطاقات من تجارب Harbor: فحص Trivy الأول فشل بانتهاء المهلة بعد ثماني دقائق ونصف في تحميل قاعدة البيانات، والفحص الثاني نجح في 131 ثانية بـ 241 ثغرة منها 1 حرجة و57 عالية وكلها قابلة للإصلاح، وقاعدة منع تغيير ال Tags رفضت الرفع فوق 1.29-alpine ورفضت الحذف برمز 412، ومشروع hub لذاكرة السحب ظهرت فيه busybox بقطعتين بعد دقائق](https://arabroot.io/content/images/2026/11/container-registry-05-harbor-policies.webp)

الفحص، ومنع تغيير ال Tags، وذاكرة السحب، كما ظهرت في المختبر

## النسخ الاحتياطي Backup للسجل

السجل الخاص يتحول بسرعة إلى نقطة يعتمد عليها كل شيء: إذا ضاع فلن يستطيع أي سيرفر أن يعيد تشغيل تطبيقه بعد إعادة التشغيل، لأن ال Images لم تعد موجودة في أي مكان آخر، وقد لا تستطيع إعادة بنائها بنفس البصمة. لذلك عامله كقاعدة بيانات Database لا كذاكرة مؤقتة. وما تنسخه يختلف حسب السجل:

- distribution: كل شيء ملفات في ال Volume `ct3-regdata`، فتنسخه بنفس طريقة tar عبر Container مساعد التي شرحناها في مقال [بيانات ال Containers](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/)، ويفضل والسجل متوقف أو للقراءة فقط بالإعداد `storage.maintenance.readonly` حتى لا تنسخ رفعاً في منتصفه. ولأن الكتل لا تتغير بعد كتابتها، فالنسخ التزايدي Incremental بأدوات مثل restic سريع جداً بعد المرة الأولى.
- Harbor: مجلد البيانات `data_volume` كله، ومعه قاعدة PostgreSQL التي فيها المشاريع والمستخدمون والقواعد ونتائج الفحص، والملف `harbor.yml` والشهادات. وقاعدة البيانات تنسخها بـ `pg_dump` من Container `harbor-db` لا بنسخ ملفاتها وهي تعمل. ونسخة ملفات بلا قاعدة البيانات تعطيك كتلاً لا يعرف Harbor لمن هي.
- جهة الإصدار الخاصة: الملف `ca.key` خارج السيرفر، فإذا ضاع فسوف تحتاج توزيع جهة جديدة على كل الأجهزة.

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

## وماذا عن Gitea Packages؟

إذا كان عندك Gitea كما في دليل [تثبيت Gitea](https://arabroot.io/articles/%D8%AA%D8%AB%D8%A8%D9%8A%D8%AA-gitea-%D9%85%D8%B9-docker-compose/)، فهو يحمل سجل Images مدمجاً بلا أي تثبيت إضافي، كما في [توثيق Container Registry في Gitea](https://docs.gitea.com/usage/packages/container?ref=arabroot.io): تدخل بـ `docker login git.example.com` بنفس حساب Gitea أو بتوكن Token شخصي، وترفع إلى `git.example.com/OWNER/IMAGE:TAG`، وتظهر ال Image في صفحة Packages للمستخدم أو المنظمة Organization بجانب المستودعات Repositories. وأكبر ميزة فيه أن خطوط [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/) تبني وترفع إلى نفس المكان بنفس الصلاحيات. ولكنه لا يقدم فحص ثغرات ولا قواعد منع تغيير ال Tags ولا ذاكرة سحب، ولذلك فهو مناسب لفريق صغير يريد ال Images بجانب الكود، وأما إذا احتجت السياسات فـ Harbor.

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

- تشغيل السجل دون TLS وإضافته إلى `insecure-registries` على كل جهاز، بدلاً من شهادة واحدة في `/etc/docker/certs.d/`.
- شهادة بلا Subject Alternative Name، أو مجلد `certs.d` باسم لا يطابق الاسم والمنفذ في الأمر.
- الظن أن `docker login` يشفر كلمة المرور، وهي Base64 في `~/.docker/config.json`.
- نشر الإنتاج بال Tag وإعادة رفع نفس ال Tag، فيعمل إصداران مختلفان بنفس الاسم.
- نسخ البصمة من Docker Hub واستخدامها مع سجلك، والبصمة تتغير عندما ترفع معمارية واحدة.
- انتظار أن تنقص المساحة بعد الحذف، والحذف دون Garbage Collection لا يحرر شيئاً.
- تشغيل Garbage Collection والسجل يستقبل رفعاً، أو استخدام `--delete-untagged` مع ملفات نشر تكتب البصمات.
- عدم وجود نسخة احتياطية Backup لمجلد السجل، أو لقاعدة بيانات Harbor مع مجلد بياناته.
- الاعتماد على ذاكرة السحب دون مراقبة، فإذا توقفت عاد الجميع إلى حد Docker Hub دون أي رسالة.

## قائمة تحقق Checklist لسجل في الإنتاج Production

1. اسم نطاق وشهادة TLS صالحة، أو جهة إصدار خاصة موزعة على الأجهزة في `certs.d`.
2. حساب لكل خط CI بصلاحية الرفع لمشروعه فقط، وحساب للسيرفرات بصلاحية السحب فقط.
3. قاعدة منع تغيير ال Tags للإصدارات، والنشر بالبصمة.
4. فحص الثغرات عند الرفع، وسياسة واضحة لما تفعله بالنتائج.
5. جمع مهملات مجدول في وقت صيانة، وقاعدة احتفاظ Retention تحذف بناءات CI القديمة.
6. ذاكرة سحب أمام Docker Hub، بحساب Docker Hub لا بعنوان مشترك، مع مراقبة Monitoring.
7. نسخة احتياطية مجربة لمجلد البيانات وقاعدة البيانات، مع مراقبة المساحة.

## جدول القرار Decision Table: أي سجل Registry تختار؟

| الحالة                                                   | الأنسب                                                 | والسبب                                                   |
| -------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| فريق صغير يريد مكاناً لل Images من CI إلى سيرفر أو اثنين | distribution مع TLS وhtpasswd                          | برنامج واحد بذاكرة 14 MB، والإعداد في متغيرات            |
| عندك Gitea وتريد ال Images بجانب الكود                   | Gitea Packages                                         | لا يوجد تثبيت إضافي، ونفس المستخدمين والصلاحيات وActions |
| عدة فرق، وصلاحيات لكل مشروع، وتدقيق، وفحص ثغرات          | Harbor                                                 | المشاريع والأدوار وTrivy ومنع تغيير ال Tags جاهزة        |
| كثير من السحب من Docker Hub من شبكة واحدة                | ذاكرة سحب distribution، أو مشروع Proxy Cache في Harbor | السحبة الأولى فقط تحسب على الحد                          |
| سيرفر بذاكرة 1 أو 2 GB                                   | distribution أو Gitea                                  | Harbor يطلب 4 GB على الأقل كما في متطلباته               |
| لا تريد تشغيل أي شيء                                     | سجل سحابي                                              | تدفع مقابل ألا تدير التخزين والنسخ والتحديث              |

## حذف المختبر Cleanup

```bash
cd /root/harbor && docker compose down -v
docker rm -f ct3-reg ct3-cache
docker volume rm ct3-regdata ct3-cachedata
rm -rf /srv/harbor-data /etc/docker/certs.d/reg.lab:5000 /etc/docker/certs.d/harbor.lab
echo '{}' > /etc/docker/daemon.json && systemctl restart docker
docker logout reg.lab:5000; docker logout harbor.lab
```

⚠️

الأمر `docker compose down -v` في مجلد Harbor لا يحذف بياناته، لأن Harbor يحفظها في المجلد `data_volume` على المضيف Host وهو عندنا `/srv/harbor-data`، ولذلك حذفناه بنفسنا. وفي الإنتاج هذا المجلد مع قاعدة البيانات هو ما تنسخه احتياطياً، وإذا حذفته فقد حذفت كل ال Images.

## الخلاصة Summary

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

- السجل يخزن كتلاً بأسماء من هاش محتواها، وManifests تجمعها، وTags تشير إلى Manifests ويمكن نقلها.
- distribution 3.1.2 يعمل ببرنامج واحد مع TLS وhtpasswd، وظهر خطآن متوقعان قبل الرفع: جهة إصدار غير معروفة، ثم عدم الدخول. و`docker login` يحفظ كلمة المرور Base64 فقط.
- رفع معمارية واحدة يعطي بصمة مختلفة عن بصمة Docker Hub، فخذ البصمة من سجلك.
- إعادة الرفع بنفس ال Tag نقلته إلى بصمة جديدة دون سؤال، والبصمة القديمة بقيت تسحب نفس المحتوى.
- الحذف برمز 202 لم يحرر شيئاً، وجمع المهملات حذف كتلتين من ست لأن الطبقة الكبيرة مشتركة.
- ترويسة Docker Hub قالت 100 في نافذة 3600 ثانية، وثلاث سحبات عبر ذاكرة السحب كلفت سحبتين فقط.
- Harbor 2.16.0 أخذ 38 دقيقة للتثبيت وعشرة Containers و322 MiB، وفشل فحصه الأول بانتهاء المهلة أثناء تحميل قاعدة Trivy، ثم وجد 241 ثغرة قابلة للإصلاح في nginx، ومنعت قاعدته الكتابة فوق ال Tag وحذفه.

وفي المقالات التالية بإذن الله سوف نتحدث عن Podman الذي يسحب من نفس السجلات بأسماء كاملة، ثم عن Docker Swarm الذي تسحب كل عقده من سجلك. وهذه مقالات مرتبطة:

[![](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-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/dockerfile-best-practices-cover-cover.webp)دليلكتابة Dockerfile صحيح: Multi-stage وLayer Cachingخمس نسخ من Dockerfile للتطبيق نفسه نزلت بال Image من 641 ميجابايت إلى 66 وبالبناء بعد تعديل سطر من خمس دقائق إلى أقل من أربع ثوان، مع شرح كل سطر والأرقام المقاسة.](https://arabroot.io/articles/%D9%83%D8%AA%D8%A7%D8%A8%D8%A9-dockerfile-%D8%B5%D8%AD%D9%8A%D8%AD-multi-stage-%D9%88-layer-caching/)[![](https://arabroot.io/content/images/2026/11/container-runtime-security-cover-cover.webp)دليلأمان ال Containers وقت التشغيل: Rootless وCapabilitiesنختبر على سيرفر Debian كل طبقة تحمي السيرفر من ال Container، من Capabilities وseccomp وAppArmor إلى Rootless وحدود العمليات، ونرى ماذا يحدث عندما نزيلها.](https://arabroot.io/articles/%D8%A7%D9%85%D8%A7%D9%86-%D8%A7%D9%84-containers-%D9%88%D9%82%D8%AA-%D8%A7%D9%84%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-rootless-%D9%88-capabilities/)[![](https://arabroot.io/content/images/2026/10/gitea-cover-cover.webp)دليلGitea: خادم Git خاص لفريقك على سيرفرككيف تثبت Gitea على سيرفرك حتى يبقى كود فريقك عندك بتجربة تشبه GitHub، مع النسخ الاحتياطي والتحديث.](https://arabroot.io/articles/%D8%AA%D8%AB%D8%A8%D9%8A%D8%AA-gitea-%D9%85%D8%B9-docker-compose/)[![](https://arabroot.io/content/images/2026/10/gitea-actions-cover-cover-2.webp)دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.](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/)[![](https://arabroot.io/content/images/2026/11/sbom-signing-cover-cover.webp)دليلSBOM مع Syft ثم توقيع ال Images مع Cosign قبل النشرخط إصدار يولد قائمة المكونات ويوقعها مع ال Image بمفتاح لا يخرج من OpenBao، وبوابة نشر تتحقق منهما، ثم سبع تجارب عليها منها توكن مسرب.](https://arabroot.io/articles/sbom-%D9%85%D8%B9-syft-%D8%AB%D9%85-%D8%AA%D9%88%D9%82%D9%8A%D8%B9-%D8%A7%D9%84-images-%D9%85%D8%B9-cosign/)[![](https://arabroot.io/content/images/2026/11/podman-intro-cover-cover.webp)دليلPodman: بديل Docker دون Daemon ودون rootنشغل Podman بمستخدم عادي بجانب Docker على نفس السيرفر، من ال Pods وQuadlet مع systemd إلى أداة docker وCompose عبر مقبسه، ونقيس الفرق في السرعة والذاكرة.](https://arabroot.io/articles/podman-%D8%A8%D8%AF%D9%8A%D9%84-docker-%D8%AF%D9%88%D9%86-daemon-%D9%88%D8%AF%D9%88%D9%86-root/)

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

- 19 نوفمبر 2026: كتابة المقال، وتنفيذ التجارب في جهاز افتراضي Debian 13.7 مع Docker Engine 29.10.0، وdistribution 3.1.2 (registry:3) و2.8.3 (registry:2)، وHarbor 2.16.0 مع Trivy، وقراءة حدود Docker Hub من الترويسات في يوم التجربة.