آموزش ساخت میرور داکر با Nexus روی PaaS ابربیت

برای ساخت میرور داکر لازم نیست کل Docker Hub را کپی کنید. می‌توانید یک مخزن پروکسی در Nexus Repository بسازید تا ایمیج‌های درخواستی تیم را از داکرهاب دریافت و کش کند. در این آموزش، نکسوس را با سرویس برنامه‌های ابری ابربیت راه‌اندازی می‌کنیم و تا اولین دریافت ایمیج از آدرس اختصاصی پیش می‌رویم.

مسیر اصلی با دیسک ماندگار برنامه کار می‌کند. اگر به ذخیرهٔ لایه‌ها در فضای شیءگرا نیاز دارید، بخش اختیاری اتصال به فضای ذخیره‌سازی S3 ابربیت را هم بخوانید. این راهنما برای ساخت میرور خودتان است و یک رجیستری عمومی آماده معرفی نمی‌کند.

نحوهٔ کار میرور داکر با نکسوس

وقتی کلاینت یک ایمیج را از مخزن پروکسی می‌خواهد، نکسوس محتوای موجود در کش و وضعیت مبدأ را بررسی می‌کند و اجزای لازم را از داکرهاب می‌گیرد. لایه‌های ذخیره‌شده برای درخواست‌های بعدی قابل استفاده‌اند؛ اما بررسی تازگی برچسب‌ها و دریافت محتوای کش‌نشده همچنان می‌تواند به ارتباط با مبدأ نیاز داشته باشد. کش، دسترسی همیشگی بدون اینترنت یا رفع محدودیت‌های داکرهاب را تضمین نمی‌کند.

• مخزن proxy برای دریافت و کش‌کردن محتوای یک رجیستری دیگر است؛ موضوع اصلی این مقاله همین نوع مخزن است.
• مخزن hosted برای نگهداری ایمیج‌های ساخته‌شدهٔ خود تیم و دریافت دستور docker push است.
• مخزن group چند مخزن سازگار را پشت یک آدرس دریافت جمع می‌کند؛ برای شروع این آموزش لازم نیست.

برای جزئیات رفتار مخزن، راهنمای رسمی پروکسی داکر را ببینید.

مرحلهٔ اول: راه‌اندازی نکسوس روی PaaS ابربیت

پیش از شروع، یک پروژه در کنسول ابربیت، مجوز ساخت برنامه در آن پروژه و یک سیستم با Docker نصب‌شده لازم دارید. نکسوس باید بتواند به رجیستری و سرویس احراز هویت Docker Hub متصل شود. سرویس برنامه‌های ابری در مرحلهٔ آزمایشی است؛ ظرفیت و هزینهٔ نمایش‌داده‌شده در کنسول را پیش از ساخت بررسی کنید.

1. ابتدا وارد کنسول شوید، پروژه را انتخاب کنید و در بخش برنامه‌های ابری، قالب آمادهٔ Nexus Repository را بسازید.
2. سپس تا آماده‌شدن برنامه صبر کنید و آدرس HTTPS نمایش‌داده‌شده برای همان برنامه را باز کنید.
3. بعد اطلاعات ورود اولیه را از گزینهٔ مربوط به رمز نکسوس در فهرست برنامه‌ها بگیرید؛ دریافت رمز به مجوز مدیر پروژه نیاز دارد.
4. حالا با کاربر admin وارد شوید، رمز اولیه را تغییر دهید و برای این آموزش دسترسی ناشناس را غیرفعال نگه دارید.

قالب برنامه، نصب نکسوس را فراهم می‌کند؛ مخزن‌ها، کاربران و تنظیم کش را در خود نکسوس می‌سازید. برای آشنایی با سایر قالب‌ها، معرفی نکسوس، متابیس و آپ‌تایم کوما در ابربیت را بخوانید.

در همهٔ مثال‌ها، دامنهٔ nexus.example.com یک جای‌نگهدار است؛ آن را با همان آدرس واقعی HTTPS برنامهٔ خودتان عوض کنید. برای انجام آموزش نیازی به ساخت دامنهٔ شخصی نیست.

مرحلهٔ دوم: ساخت مخزن پروکسی Docker Hub

در رابط کلاسیک نکسوس، مسیر Administration → Repository → Repositories → Create repository را باز کنید و نوع docker (proxy) را انتخاب کنید. در رابط‌های جدیدتر، این بخش زیر تنظیمات مخزن‌ها قرار دارد. مقدارهای اصلی به این صورت‌اند:

• برای نام مخزن، مقدار docker را وارد کنید.
• برای روش انتشار، گزینهٔ Path-based routing را فعال کنید؛ پورت اتصال اضافی نسازید.
• برای آدرس مبدأ یا Remote storage، مقدار https://registry-1.docker.io را بگذارید.
• برای شاخص یا Docker Index، گزینهٔ Use Docker Hub را انتخاب کنید.
• برای فضای ذخیره یا Blob store، فعلاً مقدار default را انتخاب کنید؛ این فضا روی دیسک ماندگار نکسوس است.
• برای دسترسی، گزینهٔ دریافت ناشناس این مخزن را غیرفعال نگه دارید و تنظیمات را ذخیره کنید.

روش مسیرمحور از نکسوس نسخهٔ 3.83.0 اضافه شده و نسخهٔ 3.91.0 قالب بررسی‌شده آن را دارد. به این ترتیب، همان دامنهٔ HTTPS برنامه برای رابط وب و درخواست‌های رجیستری استفاده می‌شود. آدرس کلاینت داکر نام مخزن را در مسیر می‌آورد و شامل بخش /repository/ نیست. جزئیات در راهنمای رسمی مسیریابی رجیستری آمده است.

اگر برای دسترسی نکسوس به مبدأ، حساب Docker Hub تعریف می‌کنید، اطلاعات آن را در تنظیمات احراز هویت HTTP همین مخزن وارد کنید. این حساب با کاربری که اعضای تیم برای ورود به نکسوس استفاده می‌کنند متفاوت است؛ سهمیه و محدودیت‌های مبدأ همچنان اعمال می‌شوند.

مرحلهٔ سوم: فعال‌کردن ورود داکر و دسترسی خواندن

1. ابتدا در مسیر Security → Realms، گزینهٔ Docker Bearer Token Realm را به فهرست فعال منتقل و ذخیره کنید.
2. سپس در بخش Security → Roles یک نقش مخصوص دریافت ایمیج بسازید و فقط مجوزهای nx-repository-view-docker-docker-read و nx-repository-view-docker-docker-browse را به آن بدهید.
3. بعد در بخش کاربران، کاربری مثل mirror-reader بسازید و همین نقش را به او اختصاص دهید.

در نام این مجوزها، بخش دوم docker نام مخزنی است که در مرحلهٔ قبل ساختید. برای تیم و CI از حساب مدیر استفاده نکنید؛ مجوز خواندن و مرور برای دریافت کافی است. الزام فعال‌بودن Realm در راهنمای رسمی احراز هویت داکر توضیح داده شده است.

حالا در ترمینال، بدون افزودن نام مخزن یا https:// به دستور ورود، اجرا کنید و رمز را در اعلان تعاملی وارد کنید:

docker login nexus.example.com --username mirror-reader

اگر روی سیستم شما اجرای داکر به sudo نیاز دارد، برای ورود و دریافت هر دو از همان شیوه استفاده کنید؛ اطلاعات ورود کاربر عادی و کاربر ریشه در یک محل ذخیره نمی‌شوند. رمز را داخل دستور، فایل مقاله یا مخزن کد ننویسید.

مرحلهٔ چهارم: دریافت ایمیج از میرور اختصاصی

پس از ورود موفق، این دو ایمیج عمومی را از مسیر نکسوس دریافت کنید:

docker pull nexus.example.com/docker/alpine:3.21
docker pull nexus.example.com/docker/nginx:alpine

در این آدرس‌ها، دامنه مقصد نکسوس و بخش docker نام مخزن پروکسی است. برای ایمیج‌های رسمی داکرهاب می‌توانید بخش library را صریح بنویسید یا حذف کنید؛ برای نمونه، این شکل هم معتبر است:

docker pull nexus.example.com/docker/library/alpine:3.21

برای ایمیج‌های یک سازمان، نام سازمان باید باقی بماند؛ در نمونهٔ زیر، نام سازمان، ایمیج و نسخه را با مقادیر واقعی جایگزین کنید:

docker pull nexus.example.com/docker/your-org/your-image:your-tag

برای استفاده در فایل Dockerfile نیز کافی است مبدأ ایمیج پایه را به مسیر میرور تغییر دهید:

FROM nexus.example.com/docker/alpine:3.21

برای ساخت‌های تکرارپذیر، پس از انتخاب ایمیج سازگار از digest مشخص استفاده کنید؛ برچسبی مثل latest و حتی برچسب نسخه می‌تواند در مبدأ به محتوای دیگری اشاره کند. راهنمای دریافت ایمیج در نکسوس نمونه‌های بیشتری دارد.

این روش، میرور خودکار موتور داکر نیست. دستور docker pull alpine همچنان از تنظیمات عادی کلاینت پیروی می‌کند؛ برای استفاده از این مخزن باید آدرس نکسوس را صریح بنویسید. آدرس مسیرمحور را به‌عنوان راهکار آماده در تنظیم registry-mirrors قرار ندهید؛ آن روش به endpoint مناسب و تنظیم جداگانه نیاز دارد.

مرحلهٔ پنجم: بررسی کش داکرهاب و ماندگاری داده

1. ابتدا یک ایمیج را کامل دریافت کنید و در بخش Browse نکسوس، مخزن docker و محتوای آن را ببینید.
2. سپس همان ایمیج را از یک ماشین یا محیط آزمایشی دیگر با کش محلی خالی دریافت کنید؛ دستورهای پاک‌سازی سراسری روی سیستم کاری لازم نیستند.
3. برای بررسی دریافت مستقل از مبدأ، در یک مخزن آزمایشی و زمان کنترل‌شده، گزینهٔ Blocked همان مخزن پروکسی را موقتاً فعال کنید تا درخواست به مبدأ متوقف شود؛ گزینهٔ Online را فعال نگه دارید. بعد ایمیج کاملِ قبلاً دریافت‌شده را از کلاینت با کش خالی بخواهید و سپس گزینه را به حالت قبلی برگردانید. رفتار این گزینه در راهنمای تنظیمات مخزن آمده است. این آزمایش را روی مخزن مشترک تیم اجرا نکنید.
4. برای بررسی ماندگاری، در زمان مناسب برنامه را راه‌اندازی مجدد کنید و باقی‌ماندن کاربران، مخزن و امکان دریافت ایمیج را دوباره بررسی کنید.

پیام Already exists به وجود لایه در کش محلی کلاینت اشاره دارد و به‌تنهایی اثبات نمی‌کند که نکسوس آن را از فضای ذخیره‌سازی خوانده است. همچنین دریافت روی یک معماری، لزوماً همهٔ لایه‌های معماری‌های دیگر همان ایمیج را کش نمی‌کند.

ظرفیت دیسک و رشد مخزن را پایش کنید و برای محتوای بلااستفاده، سیاست پاک‌سازی متناسب با نیاز تیم بسازید. فایل‌های Blob Store یا اشیای باکت را دستی حذف نکنید؛ پاک‌سازی و آزادسازی فضا باید با سازوکار نکسوس هماهنگ باشد. پیش از حذف برنامه، نسخهٔ پشتیبان لازم را تهیه کنید؛ حذف برنامه در پلتفرم دیسک همراهش را هم حذف می‌کند.

بخش اختیاری: اتصال نکسوس به فضای S3 ابربیت

برای شروع میرور، فضای default کافی است. اگر می‌خواهید محتوای مخزن در باکت قرار بگیرد، پیش از ایجاد مخزن اصلی یک Blob Store جدا بسازید. دیسک ماندگار برنامه حتی با S3 برای دیتابیس و تنظیمات نکسوس لازم است؛ باکت جایگزین پشتیبان آن‌ها نیست.

وضعیت پشتیبانی S3 را در نسخه و مجوز نصب خودتان بررسی کنید: ماتریس رسمی امکانات، قابلیت AWS S3 Blob Stores را برای Community نشان می‌دهد، اما جدول دیگر نسخه‌ها برای ذخیره‌سازی ابری محدودیت متفاوتی دارد. بنابراین از روی نام نسخهٔ رایگان یا تجاری به‌تنهایی تصمیم نگیرید؛ وجود گزینهٔ S3 و امکان ساخت و استفاده از آن در نصب خودتان را پیش از انتقال داده بررسی کنید.

1. ابتدا در سرویس ذخیره‌سازی ابربیت، یک باکت خصوصی مخصوص نکسوس بسازید و از تب کلیدها، کلید دسترسی جداگانهٔ همان باکت را تهیه کنید؛ نکسوس به عملیات خواندن، نوشتن، فهرست‌کردن و حذف محتوا نیاز دارد.
2. سپس در مسیر Repository → Blob Stores → Create blob store نوع S3 را انتخاب کنید و نامی مثل abrbit-cache بدهید.
3. برای نام باکت، مقدار دقیق باکت را وارد کنید؛ برای Endpoint URL مقدار اصلی Endpoint در پنل باکت را بدون افزودن نام باکت بگذارید. دامنهٔ اختصاصی دانلود باکت برای این اتصال مناسب نیست.
4. برای منطقه، مقدار us-east-1 مطابق راهنمای اتصال فعلی پنل را بگذارید، کلیدها را فقط در بخش اعتبارنامهٔ نکسوس وارد و گزینهٔ Use path-style access را فعال کنید.
5. پس از ساخت موفق، در زمان ایجاد مخزن جدید داکر همین Blob Store را انتخاب کنید. تغییر مقصد یک مخزن پر از داده، مهاجرت جداگانه است؛ صرفاً عوض‌کردن یک گزینه را معادل انتقال داده ندانید.

اگر خطای مالکیت باکت گرفتید، ابتدا صحت باکت و کلیدها را بررسی کنید. برای سرویس‌های سازگار با S3، راهنمای رسمی Sonatype تنظیم زیر را در فایل /nexus-data/etc/nexus.properties پیشنهاد می‌کند؛ اعمال تغییر ممکن است به راه‌اندازی مجدد نیاز داشته باشد:

nexus.blobstore.s3.ownership.check.disabled=true

این تنظیم، مجوز دسترسی به باکت ایجاد نمی‌کند. اگر نسخهٔ قالب مستقر این مقدار را از قبل اعمال کرده باشد، نیازی به تکرار آن نیست؛ در نبود دسترسی مدیریتی به فایل، موضوع را از پشتیبانی پیگیری کنید. پس از اتصال، با دریافت ایمیج آزمایشی و بررسی ایجاد اشیا در باکت، مسیر ذخیره را تأیید کنید. جزئیات تنظیمات در راهنمای رسمی S3 نکسوس آمده است.

برای باکت نکسوس، قانون حذف خودکار اشیا نگذارید و پیش از اعمال Object Lock یا محدودیت حذف، سازگاری آن را با عملیات نکسوس بررسی کنید. پشتیبان‌گیری باید دیتابیس، تنظیمات و Blob Store را به‌شکل هماهنگ پوشش دهد.

رفع خطاهای رایج میرور داکر

• برای خطای unauthorized یا denied، فعال‌بودن Realm، مجوزهای خواندن و مرور، نام کاربر و یکسان‌بودن اجرای معمولی یا sudo در ورود و دریافت را بررسی کنید.
• برای خطای 404 یا manifest unknown، نام مخزن، فعال‌بودن مسیریابی مسیرمحور، نام سازمان و وجود برچسب در مبدأ را بررسی کنید؛ بخش /repository/ در دستور دریافت مسیرمحور جایی ندارد.
• برای خطای 429، محدودیت دریافت در مبدأ و حساب اتصال نکسوس به داکرهاب را بررسی کنید؛ کش سهمیهٔ مبدأ را حذف نمی‌کند.
• برای خطای 502 یا timeout، دسترسی خود نکسوس به مبدأ، وضعیت مخزن، فضای آزاد و گزارش‌های مدیریتی را بررسی کنید؛ گواهی TLS را برای رفع خطا غیرفعال نکنید.
• برای خطای مالکیت باکت یا AccessDenied در S3، باکت، endpoint، کلید، مجوزها و تنظیم سازگاری مالکیت را بررسی کنید؛ این دو خطا لزوماً علت یکسان ندارند.

پرسش‌های متداول دربارهٔ ساخت میرور داکر

آیا با ساخت پروکسی، کل داکرهاب دانلود می‌شود؟

خیر؛ نکسوس محتوای درخواستی را دریافت و کش می‌کند. برای ایمیج یا معماری جدید، دسترسی به مبدأ ممکن است لازم باشد.

آیا می‌توان نام مخزن را از آدرس حذف کرد؟

در روش مسیرمحور این آموزش، بخش docker باید بماند؛ حذف آن نیازمند روش انتشار و تنظیم جداگانه است. برای نام کوتاه‌تر می‌توانید از ابتدا نام کوتاه‌تری برای مخزن انتخاب کنید.

آیا می‌توان ایمیج‌های خودمان را به همین مخزن ارسال کرد؟

خیر؛ برای ارسال ایمیج‌های تیم، یک مخزن docker (hosted) و دسترسی نوشتن محدود بسازید. مخزن پروکسی برای کش‌کردن محتوای مبدأ است.

آیا این مخزن، ایمیج‌های GHCR و Quay را هم کش می‌کند؟

خیر؛ مخزن این آموزش به Docker Hub متصل است. برای مبدأهای دیگر، مخزن پروکسی مستقل با تنظیمات همان رجیستری لازم است.

آیا اتصال S3 دیسک برنامه را بی‌نیاز می‌کند؟

خیر؛ دیتابیس و تنظیمات نکسوس همچنان به ذخیره‌سازی ماندگار نیاز دارند. اتصال باکت به‌تنهایی راهکار پشتیبان‌گیری کامل نیست.

شروع ساخت میرور اختصاصی در ابربیت

برای شروع، یک نکسوس با دیسک ماندگار بسازید، مخزن پروکسی و حساب خواندن را تنظیم کنید و دریافت یک ایمیج را از کلاینت مستقل بررسی کنید. پس از آن، نگه‌داری کش و در صورت نیاز اتصال S3 را با نیاز واقعی تیم هماهنگ کنید.

ساخت نکسوس در کنسول ابربیت