میرور ابربیت؛ راهنمای استفاده برای Docker، Composer و npm

دریافت ایمیج‌ها و بسته‌های نرم‌افزاری، بخشی از کار روزانهٔ توسعه‌دهندگان است. اجرای یک پروژه روی سیستم جدید یا ساخت آن در CI/CD معمولاً به دانلود وابستگی‌ها نیاز دارد. میرور ابربیت یک مسیر مشخص برای دریافت این منابع در اختیار شما قرار می‌دهد.

در این راهنما، آدرس سرویس‌ها و روش استفاده از آن‌ها در داکر، Composer و npm را مرور می‌کنیم. تنظیمات را می‌توانید در فایل‌های پروژه نگه دارید تا اعضای تیم و محیط ساخت از مسیر یکسانی استفاده کنند.

آدرس میرورهای ابربیت

در دستورهای داکر، نام ایمیج بدون پیشوند https:// نوشته می‌شود. برای Composer و npm، آدرس کامل HTTPS را وارد کنید.

میرور و کش چه کاری انجام می‌دهند؟

میرور واسطه‌ای برای دریافت منابع از مخزن اصلی است. در یک مخزن پروکسی، بسته یا لایهٔ ایمیج هنگام درخواست از منبع اصلی دریافت و در کش نگهداری می‌شود. درخواست‌های بعدی، در صورت وجود نسخهٔ معتبر در کش، می‌توانند از همان داده استفاده کنند.

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

استفاده در داکر

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

docker pull mirror.abrbit-apps.ir/docker/nginx:alpine

برای ایمیج‌های متعلق به یک سازمان یا کاربر، فضای نام همان ناشر را حفظ کنید. ساختار کلی نام چنین است:

mirror.abrbit-apps.ir/docker/<namespace>/<image>:<tag>

داکر دریافت ایمیج با نام رجیستری، مسیر، برچسب یا digest را پشتیبانی می‌کند. جزئیات در مستندات رسمی دریافت ایمیج آمده است.

تنظیم فایل Dockerfile

همین آدرس را در دستور پایهٔ ایمیج بنویسید:

FROM mirror.abrbit-apps.ir/docker/nginx:alpine

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

تنظیم فایل Docker Compose

در فایل Compose، آدرس میرور در مقدار تصویر قرار می‌گیرد:

services:
  web:
    image: mirror.abrbit-apps.ir/docker/nginx:alpine
    ports:
      - "8080:80"

سپس ایمیج را دریافت کنید:

docker compose pull

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

استفاده در Composer

برای معرفی میرور به کامپوزر، بخش زیر را به ریشهٔ فایل composer.json اضافه کنید. اگر پروژه از قبل مخزن خصوصی دارد، تنظیمات آن را نیز حفظ کنید:

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://mirror.abrbit-apps.ir/repository/composer/"
    },
    {
      "packagist.org": false
    }
  ]
}

در این نمونه، مخزن پیش‌فرض Packagist غیرفعال شده تا جست‌وجوی بسته‌ها از مخزن معرفی‌شده انجام شود. برای جزئیات، مستندات رسمی مخزن‌های کامپوزر را ببینید.

برای بررسی تنظیمات و نصب وابستگی‌های قفل‌شده اجرا کنید:

composer validate
composer install

فایل composer.lock علاوه بر نسخه‌ها، اطلاعات دریافت بسته‌ها را هم نگه می‌دارد. بنابراین فقط تعریف مخزن، تضمین نمی‌کند تمام دانلودهای یک فایل قفل موجود از میرور انجام شوند؛ آدرس‌های dist.url را نیز بررسی کنید.

در محیط CI/CD، فایل قفل را در مخزن کد نگه دارید و برای نصب نسخه‌های تعیین‌شده از دستور نصب استفاده کنید. به‌روزرسانی نسخهٔ وابستگی‌ها را به‌عنوان کاری جداگانه انجام دهید.

استفاده در npm

برای تنظیم میرور در سطح پروژه، کنار فایل package.json یک فایل .npmrc بسازید:

registry=https://mirror.abrbit-apps.ir/repository/npm/

این روش تنظیم را همراه پروژه نگه می‌دارد. فایل تنظیمات پروژه در ریشهٔ همان پروژه خوانده می‌شود. جزئیات در مستندات رسمی تنظیمات npm آمده است.

آدرس فعال و دسترسی به اطلاعات یک بسته را بررسی کنید:

npm config get registry
npm view is-number@7.0.0 version

برای نصب وابستگی‌ها در محیط توسعه اجرا کنید:

npm install

در محیط CI، اگر فایل package-lock.json با تعریف بسته‌های پروژه هماهنگ است، از دستور زیر استفاده کنید:

npm ci

مقادیر resolved در فایل قفل را هم بررسی کنید؛ ممکن است لینک دریافت بعضی بسته‌ها صریحاً در آن ثبت شده باشد. برای بسته‌های scoped نیز تنظیمات اختصاصی رجیستری را بررسی کنید.

بررسی نهایی در پروژه و CI/CD

پیش از اتکا به تنظیمات در محیط ساخت، این موارد را بررسی کنید:

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

با ثبت این تنظیمات در پروژه، مسیر دریافت منابع برای توسعهٔ محلی و CI/CD روشن و قابل بررسی خواهد بود. اگر می‌خواهید برای تیم خود مخزن مستقلی بسازید، آموزش ساخت میرور اختصاصی داکر با نکسوس را نیز بخوانید.