آموزش کش میرور داکر نکسوس با Nginx Cache در ابربیت

اگر میرور داکر شما روی نکسوس کار می‌کند، می‌توانید یک برنامهٔ Nginx Cache جلوی آن بسازید تا فایل‌های پرتکرار از دیسک کش تحویل داده شوند. کلاینت به آدرس کش وصل می‌شود و برنامهٔ کش، نکسوس همان پروژه را به‌عنوان مقصد می‌شناسد. تنظیمات nginx از قالب آماده تولید می‌شوند؛ برای شروع، نیازی به نوشتن کانفیگ ندارید.

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

تفاوت کش نکسوس و کش جلوی آن

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

در حالت Docker، حتی برای فایل موجود در کش، مجوز دانلود با یک درخواست سبک HEAD به نکسوس بررسی می‌شود. بنابراین هدف، کاهش انتقال و خواندن تکراری محتوای لایه‌ها از نکسوس است؛ تعداد درخواست‌های آن صفر نمی‌شود. مقدار بهبود به اندازهٔ فایل‌ها، تکرار دانلود و شرایط سرویس بستگی دارد و عدد ثابتی برای آن تضمین نمی‌شود.

مرحلهٔ اول: ساخت برنامهٔ کش

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

1. ابتدا در کنسول ابربیت، پروژهٔ نکسوس را انتخاب کنید و از بخش پلتفرم، صفحهٔ ساخت برنامهٔ جدید را باز کنید.
2. سپس از برنامه‌های آماده، گزینهٔ Nginx Cache را انتخاب کنید و نامی مانند nexus-cache برای برنامه بگذارید.
3. در بخش «اپ مقصد در همین پروژه»، برنامهٔ نکسوس را انتخاب کنید؛ نام مقصد ممکن است در پروژهٔ شما مثلاً nexus یا docker باشد.
4. گزینهٔ «کش Docker» را روشن نگه دارید؛ این گزینه برای نصب جدید به‌صورت پیش‌فرض روشن است.
5. برای شروع آموزش، یک نسخه و دیسک ۲۰ گیگابایتی انتخاب کنید. پردازنده و حافظهٔ هر نسخه را متناسب با نیاز و برآورد هزینه تعیین کنید؛ این مثال، توصیهٔ ظرفیت برای بار عملیاتی شما نیست.
6. در پایان، خلاصهٔ سفارش را بررسی و برنامه را ایجاد کنید. پس از آماده‌شدن، آدرس HTTPS آن را از صفحهٔ برنامه بردارید.

در نصب قدیمی، روشن‌شدن کش Docker را فرض نکنید؛ وضعیت آن را در صفحهٔ برنامه ببینید و در صورت نیاز از گزینهٔ «تنظیم کش Docker» فعال کنید. تغییر تنظیم می‌تواند باعث راه‌اندازی مجدد گردشی و وقفهٔ موقت شود؛ دیسک‌های کش حفظ می‌شوند.

انتخاب مقصد فقط از برنامه‌های آمادهٔ همان پروژه ممکن است؛ آدرس اینترنتی دلخواه یا یک برنامهٔ کش دیگر را نمی‌توانید مقصد کنید. اتصال به نکسوس از مسیر داخلی پروژه انجام می‌شود و آدرس مستقیم نکسوس با ساخت کش تغییر نمی‌کند.

مرحلهٔ دوم: دریافت ایمیج از آدرس کش

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

اگر مخزن نیاز به ورود دارد، با همان حساب خواندن نکسوس، این بار به میزبان کش وارد شوید و رمز را در اعلان تعاملی بنویسید:

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

در دستور ورود، بخش https:// و مسیر مخزن را ننویسید. ورود قبلی به میزبان نکسوس لزوماً برای میزبان تازهٔ کش استفاده نمی‌شود. اگر Docker را با sudo اجرا می‌کنید، برای ورود و دریافت هر دو همان روش را به کار ببرید.

حالا یک ایمیج کوچک عمومی را از مخزن پروکسی خود دریافت کنید:

docker pull cache.example.com/docker/hello-world:latest

برای استفاده در ساخت برنامه هم آدرس ایمیج پایه را تغییر دهید؛ این مثال از همان نام‌گذاری مقالهٔ نکسوس پیروی می‌کند و برای ایمیج رسمی نیازی به افزودن library/ ندارد:

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

این روش، تنظیم خودکار registry-mirrors موتور داکر نیست؛ دستور docker pull alpine همچنان از تنظیمات معمول خودش پیروی می‌کند. برای ساخت تکرارپذیر، پس از انتخاب ایمیج مناسب از digest مشخص استفاده کنید؛ برچسب‌هایی مثل latest ممکن است تغییر کنند.

مرحلهٔ سوم: اثبات کش با لاگ و درخواست تکراری

موفقیت دستور دریافت، عبور مسیر را نشان می‌دهد؛ برای اثبات کش، وضعیت پاسخ همان فایل را بررسی کنید. پیام Already exists مربوط به کش محلی Docker است و به‌تنهایی برخورد کش سرور را ثابت نمی‌کند. نیازی به حذف همهٔ ایمیج‌های سیستم یا اجرای پاک‌سازی سراسری ندارید.

در صفحهٔ برنامهٔ کش، لاگ را باز کنید. وضعیت کش در هدر پاسخ با نام X-Cache-Status و در لاگ با مقدارهایی مانند نمونهٔ زیر مشخص می‌شود؛ این خروجی نمونه است، نه گزارش اندازه‌گیری سرویس شما:

EDGE GET 200 MISS
EDGE GET 200 HIT

• وضعیت MISS یعنی فایل در کش قابل استفاده نبوده و درخواست به مقصد رفته است؛ پاسخ واجد شرایط می‌تواند در کش ذخیره شود.
• وضعیت HIT یعنی محتوا از کش همین نسخه تحویل داده شده است؛ بررسی مجوز Docker همچنان انجام می‌شود.
• وضعیت BYPASS یعنی درخواست از کش کنار گذاشته شده است؛ مثلاً به‌دلیل کوکی، سیاست خصوصی یا مسیر توکن و manifest.

برای مخزن خصوصی، پس از ورود مجاز، دریافت را از کلاینتی انجام دهید که لایه را محلی ندارد؛ مثلاً یک Runner آزمایشی مستقل. سپس لاگ برنامه را برای درخواست‌های دانلود ببینید. مشاهدهٔ مسیر یا توکن در لاگ لازم نیست؛ لاگ مشتری فقط روش، کد پاسخ و وضعیت کش را نشان می‌دهد. در نصب چندنسخه‌ای، نمایش لاگ فعلی همهٔ نسخه‌ها را تجمیع نمی‌کند؛ برای آزمایش اولیه یک نسخه ساده‌تر است.

نمونهٔ قابل‌کپی برای blob عمومی

اگر همین مخزن از قبل دریافت عمومی بدون احراز هویت را مجاز می‌داند، می‌توانید در Bash با ابزارهای curl و jq، مسیر واقعی یک لایهٔ ایمیج را استخراج و چهار بار دریافت کنید. برای اجرای این نمونه، دسترسی مخزن خصوصی را عمومی نکنید؛ در پاسخ ۴۰۱ یا ۴۰۳، از روش ورود و لاگ بخش قبل استفاده کنید.

set -euo pipefail
base='https://cache.example.com'
repo='docker/hello-world'
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT

curl --fail --silent --show-error --max-time 60 \
  -H 'Accept: application/vnd.oci.image.index.v1+json, application/vnd.docker.distribution.manifest.list.v2+json' \
  "$base/v2/$repo/manifests/latest" -o "$tmp/index.json"

manifest=$(jq -er '.manifests[] | select(.platform.os == "linux" and .platform.architecture == "amd64") | .digest' "$tmp/index.json")
curl --fail --silent --show-error --max-time 60 \
  -H 'Accept: application/vnd.oci.image.manifest.v1+json, application/vnd.docker.distribution.manifest.v2+json' \
  "$base/v2/$repo/manifests/$manifest" -o "$tmp/manifest.json"
layer=$(jq -er '.layers[0].digest' "$tmp/manifest.json")

for attempt in 1 2 3 4; do
  curl --fail --silent --show-error --max-time 60 \
    -D "$tmp/headers" -o /dev/null "$base/v2/$repo/blobs/$layer"
  sed -n '/^HTTP\//p; /^[Xx]-[Cc]ache-[Ss]tatus:/p' "$tmp/headers"
done

این نمونه، لایهٔ نسخهٔ لینوکس با معماری amd64 را می‌خواند و آن را روی دیسک کلاینت نگه نمی‌دارد؛ حتی روی میزبان با معماری دیگر هم صرفاً آزمون دانلود است و کانتینری اجرا نمی‌کند. در یک نسخه با کش سرد، انتظار معمول، MISS و سپس HIT است. اگر فایل از قبل گرم باشد، اولین پاسخ هم می‌تواند HIT باشد؛ اگر پاسخ مبدأ اجازهٔ کش ندهد، انتظار برخورد کش نداشته باشید.

مجوز دانلود و پاسخ‌های خصوصی چگونه حفظ می‌شوند؟

گزینهٔ Docker فقط لایه‌های دارای digest از نوع sha256 در مسیر استاندارد رجیستری را پوشش می‌دهد. پیش از هر دریافت، حتی برخورد کش، مقصد با همان اطلاعات احراز هویت بررسی می‌شود. توکن و پاسخ ورود ذخیره نمی‌شوند؛ manifest و درخواست‌های نوشتن هم بدون کش عبور می‌کنند. مجوز push را همچنان نوع مخزن و دسترسی‌های نکسوس تعیین می‌کنند.

پاسخ‌های دارای private، no-store، no-cache یا Set-Cookie مانع استفاده از کش Docker می‌شوند و درخواست کوکی‌دار از کش عبور می‌کند. نکسوس همچنان مرجع مجوز است؛ رد دسترسی یا خطای بررسی مجوز با تحویل نسخهٔ کش‌شده دور زده نمی‌شود. بنابراین خاموش‌بودن نکسوس به معنای امکان دانلود مستقل و همیشگی از کش نیست.

برای دانلودهای عمومی دیگر، مانند فایل بسته‌ها از مخزن npm نکسوس، کش عمومی پاسخ موفق درخواست‌های خواندنی قابل استفاده است؛ اما درخواست دارای Authorization یا Cookie در این مسیرها کنار گذاشته می‌شود. روشن‌کردن کش Docker این استثنا را برای همهٔ بسته‌ها ایجاد نمی‌کند و محدودیت‌هایی مانند پشتیبانی‌نشدن npm audit در پروکسی سادهٔ npm را برطرف نمی‌کند.

نسخه‌ها، دیسک و هزینه را چطور انتخاب کنیم؟

هر نسخهٔ کش یک دیسک پایدار مستقل دارد. برای مثال، سه نسخه با دیسک ۲۰ گیگابایتی یعنی سه دیسک و مجموعاً ۶۰ گیگابایت فضای رزروشده؛ این فضا یک کش مشترک ۶۰ گیگابایتی نیست و ممکن است هر سه دیسک فایل‌های یکسانی را نگه دارند. درخواست‌های متوالی ممکن است به نسخه‌های متفاوت برسند و هر نسخه ابتدا کش سرد خودش را داشته باشد.

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

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

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

بخش اختیاری: انتقال آدرس قبلی میرور به کش

اگر کلاینت‌ها از آدرس قبلی نکسوس استفاده می‌کنند، می‌توانید پس از تأیید کش، انتقال همان ساب‌دامین به برنامهٔ کش را هماهنگ کنید تا آدرس کلاینت‌ها ثابت بماند. این بخش مربوط به آدرس‌های مدیریت‌شدهٔ برنامه‌ها در ابربیت است؛ برای دامنهٔ بیرونی خودتان، تنظیم DNS و TLS را جداگانه بررسی کنید.

1. ابتدا با آدرس تازهٔ کش، ورود، دریافت ایمیج و برخورد کش را آزمایش کنید و آدرس‌ها و تنظیمات قبلی نکسوس را برای بازگشت ثبت کنید؛ رمز و توکن را در گزارش ننویسید.
2. سپس برای انتقال آدرس، یک بازهٔ مناسب با احتمال وقفه در نظر بگیرید. نام قبلی پس از تغییر برای برنامهٔ نکسوس رزرو می‌ماند؛ برای آزادسازی و انتقال آن به کش با پشتیبانی هماهنگ کنید. صرف تغییر ساب‌دامین نکسوس، قابل‌انتخاب‌شدن فوری نام برای کش را تضمین نمی‌کند.
3. پس از آزادشدن نام، آن را برای برنامهٔ کش انتخاب کنید و تا آماده‌شدن آدرس HTTPS صبر کنید. نکسوس را حذف نکنید؛ مقصد داخلی انتخاب‌شدهٔ کش باید همان برنامه باقی بماند.
4. در پایان، ورود و دریافت را با آدرس قبلی کلاینت‌ها دوباره بررسی کنید؛ نشانی سرویس احراز هویت و تنظیمات آدرس پایهٔ نکسوس هم باید با مسیر جدید سازگار باشند.

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

رفع خطاهای رایج و محدودیت‌ها

• برای نبود HIT، روشن‌بودن کش Docker، دانلود واقعی همان blob، وجود کوکی و سیاست پاسخ نکسوس را بررسی کنید؛ درخواست manifest معیار برخورد کش لایه نیست. در چند نسخه، گرم‌شدن هر دیسک مستقل است.
• برای پاسخ 401 یا 403، ورود به میزبان درست، فعال‌بودن Docker Bearer Token Realm و مجوزهای حساب نکسوس را بررسی کنید؛ کش به شما مجوز جدید نمی‌دهد.
• برای پاسخ 404، نام مخزن، نام ایمیج، digest و تنظیم مسیریابی مسیرمحور را بررسی کنید؛ در دستور pull این روش، مسیر /repository/ نمی‌آید.
• برای پاسخ 502، سلامت و دسترسی مقصد و امکان بررسی مجوز را بررسی کنید؛ انتظار تحویل فایل بدون تأیید نکسوس نداشته باشید. خطای TLS را با غیرفعال‌کردن بررسی گواهی دور نزنید.
• برای رشد دیسک یا افت کارایی، ظرفیت تخصیص‌یافته، بار و رفتار مبدأ را بررسی کنید؛ راه‌اندازی مجدد، پاک‌سازی انتخابی کش نیست و دیسک پایدار را حذف نمی‌کند.

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

برای جزئیات پروتکل، مرجع رسمی رجیستری Docker و برای رفتار کش و بررسی مجوز، مرجع پروکسی و کش nginx و مرجع بررسی مجوز nginx را ببینید؛ تنظیمات برنامهٔ ابربیت از قالب مدیریت‌شده تولید می‌شوند.

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

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