آموزش راه‌اندازی Harbor به‌عنوان Registry خصوصی سازمانی (همراه با Proxy Cache برای Docker Hub)

Harbor یک Registry متن‌باز و سازمانی برای ایمیج‌های کانتینر است که زیر چتر CNCF توسعه داده می‌شود. اگر Docker Registry ساده فقط «جای نگه‌داری ایمیج» است، Harbor یک سامانه‌ی کامل است: پروژه‌ها و سطح دسترسی، حساب‌های Robot برای CI/CD، اسکن آسیب‌پذیری با Trivy، Proxy Cache برای Registryهای عمومی، Replication بین Registryها و سیاست‌های نگه‌داری.

برای تیم‌های ایرانی، Harbor یک مزیت دیگر هم دارد: با قابلیت Proxy Cache، مشکل دسترسی به Docker Hub را به‌شکلی پایدار و قابل کنترل حل می‌کند. در این آموزش Harbor را روی Ubuntu 24.04 نصب می‌کنیم.

پیش‌نیازها

  • یک سرور Ubuntu 24.04. مستندات Harbor حداقل ۲ هسته CPU، ۴ گیگابایت RAM و ۴۰ گیگابایت دیسک را ذکر می‌کند؛ برای استفاده‌ی واقعی تیمی، ۴ هسته، ۸ گیگابایت RAM و دیسک بزرگ‌تر (بسته به حجم ایمیج‌ها) مناسب‌تر است.
  • Docker Engine و پلاگین Docker Compose. نسخه‌های حداقل لازم را در صفحه‌ی پیش‌نیازهای مستندات رسمی Harbor بررسی کنید.
  • یک دامنه، مثلاً harbor.example.com، و گواهی SSL معتبر.
  • پورت‌های 443 (و در صورت نیاز 80 برای ریدایرکت) روی فایروال باز.

Harbor را کجا نصب کنیم؟

اگر هدف اصلی شما Proxy Cache برای Docker Hub است، خود سرور Harbor باید به Docker Hub دسترسی پایدار داشته باشد. دو الگوی رایج: Harbor روی یک سرور مجازی خارج از ایران، یا Harbor داخل ایران (نزدیک سرورهای Production) که ایمیج‌ها را از یک Harbor یا Registry خارج از ایران Replicate می‌کند. مقایسه‌ی کامل راه‌حل‌ها را در دسترسی به Docker Hub از ایران نوشته‌ایم.

قدم ۱: نصب Docker

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
docker compose version

اگر مخزن Docker از سرور شما در دسترس نیست، از یک مخزن واسط مثل Nexus استفاده کنید (آموزش راه‌اندازی Nexus).

قدم ۲: دانلود Installer (آنلاین یا آفلاین)

Harbor دو نوع Installer دارد که هر دو در صفحه‌ی Releases مخزن goharbor/harbor در GitHub منتشر می‌شوند:

  • Online Installer: فایل کوچک است و ایمیج‌های Harbor را هنگام نصب از Docker Hub دریافت می‌کند. روی سرورهای داخل ایران معمولاً با خطای 403 Docker Hub شکست می‌خورد.
  • Offline Installer: همه‌ی ایمیج‌ها داخل فایل است. برای سرورهای ایران این گزینه را انتخاب کنید.

اگر دسترسی سرور به GitHub کند یا ناپایدار است، فایل را روی سیستم دیگری دانلود کنید و با scp منتقل کنید. شماره‌ی آخرین نسخه‌ی پایدار را از صفحه‌ی Releases بردارید؛ در دستورات زیر آن را در متغیر VER گذاشته‌ایم:

VER=v2.x.y   # آخرین نسخه‌ی پایدار را از صفحه‌ی Releases جایگزین کنید
wget https://github.com/goharbor/harbor/releases/download/${VER}/harbor-offline-installer-${VER}.tgz
wget https://github.com/goharbor/harbor/releases/download/${VER}/harbor-offline-installer-${VER}.tgz.asc
sudo tar xzvf harbor-offline-installer-${VER}.tgz -C /opt
cd /opt/harbor

فایل .asc برای بررسی امضای Installer است؛ روش تأیید آن در مستندات Harbor آمده است.

قدم ۳: گواهی SSL

Harbor را بدون HTTPS راه‌اندازی نکنید؛ Docker هم به‌طور پیش‌فرض با Registry بدون TLS کار نمی‌کند. ساده‌ترین روش برای دامنه‌ی عمومی، Let’s Encrypt است:

sudo apt install -y certbot
sudo certbot certonly --standalone -d harbor.example.com

اگر سرور از اینترنت در دسترس نیست، از گواهی CA داخلی سازمان استفاده کنید و گواهی CA را روی کلاینت‌ها در مسیر /etc/docker/certs.d/harbor.example.com/ca.crt قرار دهید.

قدم ۴: تنظیم harbor.yml

sudo cp harbor.yml.tmpl harbor.yml
sudo nano harbor.yml

مهم‌ترین بخش‌ها:

hostname: harbor.example.com

http:
  port: 80

https:
  port: 443
  certificate: /etc/letsencrypt/live/harbor.example.com/fullchain.pem
  private_key: /etc/letsencrypt/live/harbor.example.com/privkey.pem

harbor_admin_password: A-Strong-Password-Here

database:
  password: Another-Strong-Password

data_volume: /data
  • hostname باید دقیقاً همان دامنه‌ای باشد که کلاینت‌ها استفاده می‌کنند، نه localhost یا IP.
  • harbor_admin_password فقط برای اولین راه‌اندازی است؛ بعد از ورود آن را از پنل عوض کنید.
  • data_volume جایی است که ایمیج‌ها و دیتابیس ذخیره می‌شوند. آن را روی دیسک بزرگ و جداگانه بگذارید. Harbor می‌تواند ایمیج‌ها را در Object Storage سازگار با S3 هم نگه دارد (بخش storage_service).

قدم ۵: نصب همراه با Trivy

نصب پیش‌فرض Harbor سرویس اسکن Trivy را شامل نمی‌شود. برای فعال کردن آن، فلگ --with-trivy را بدهید:

sudo ./install.sh --with-trivy

اسکریپت فایل‌های Compose را می‌سازد، ایمیج‌ها را Load می‌کند و سرویس‌ها را بالا می‌آورد. وضعیت را بررسی کنید:

sudo docker compose ps

همه‌ی سرویس‌ها باید healthy باشند. حالا https://harbor.example.com را باز کنید و با کاربر admin وارد شوید. هر بار harbor.yml را تغییر دادید، باید sudo ./prepare --with-trivy و سپس docker compose down و docker compose up -d را اجرا کنید.

توجه: Trivy برای به‌روزرسانی پایگاه آسیب‌پذیری‌ها به اینترنت نیاز دارد. روی سرورهای ایران ممکن است این به‌روزرسانی شکست بخورد؛ مستندات Harbor روش حالت آفلاین Trivy را توضیح داده است.

قدم ۶: پروژه‌ها و Push اولین ایمیج

در Harbor هر ایمیج داخل یک Project قرار می‌گیرد. از منوی Projects یک پروژه‌ی خصوصی، مثلاً myteam، بسازید. در تنظیمات پروژه این گزینه‌ها را فعال کنید:

  • Automatically scan images on push: هر ایمیج جدید بلافاصله اسکن شود.
  • Prevent vulnerable images from running: جلوی Pull ایمیج‌هایی با آسیب‌پذیری بالاتر از سطح تعیین‌شده گرفته شود.
docker login harbor.example.com
docker tag myapp:1.0 harbor.example.com/myteam/myapp:1.0
docker push harbor.example.com/myteam/myapp:1.0

برای جلوگیری از بازنویسی نسخه‌های Release، در بخش Policy پروژه یک قانون Tag Immutability (مثلاً برای الگوی v*) تعریف کنید.

قدم ۷: Robot Account برای CI/CD

هرگز رمز کاربر admin یا کاربر شخصی را در CI قرار ندهید. از بخش Robot Accounts پروژه یک حساب Robot بسازید، فقط دسترسی Push و Pull روی همان پروژه را بدهید و تاریخ انقضا تعیین کنید. نام کاربری (با پیشوند robot$) و توکن را در متغیرهای مخفی CI ذخیره کنید:

echo "$HARBOR_TOKEN" | docker login harbor.example.com -u 'robot$myteam+ci' --password-stdin

برای سرورهای Production یک Robot جداگانه با دسترسی فقط Pull بسازید. نمونه‌ی کامل Pipeline را در راه‌اندازی CI/CD با GitLab و Docker ببینید.

قدم ۸: Proxy Cache برای Docker Hub

این بخش برای تیم‌های ایرانی ارزشمندترین قابلیت است:

  1. از Administration ← Registries یک Endpoint جدید از نوع Docker Hub بسازید. نام کاربری و Access Token یک حساب Docker Hub را وارد کنید تا سقف Pull بالاتر برود، و با Test Connection بررسی کنید.
  2. از Projects ← New Project یک پروژه، مثلاً dockerhub، بسازید، گزینه‌ی Proxy Cache را فعال کنید و Endpoint بالا را انتخاب کنید.

از این به بعد، ایمیج‌های Docker Hub را با پیشوند پروژه دریافت کنید. ایمیج‌های رسمی Docker Hub زیر library هستند:

docker pull harbor.example.com/dockerhub/library/nginx:alpine
docker pull harbor.example.com/dockerhub/bitnami/redis:latest

در Dockerfileها و فایل‌های Compose هم همین آدرس را بنویسید. می‌توانید برای GitHub Container Registry یا Quay هم Endpoint و پروژه‌ی Proxy Cache جداگانه بسازید.

قدم ۹: Replication

با Administration ← Replications می‌توانید ایمیج‌ها را بین دو Registry به‌صورت Push یا Pull همگام کنید، با فیلتر بر اساس نام و Tag و اجرای دستی، زمان‌بندی‌شده یا بلافاصله بعد از Push. یک الگوی کاربردی: CI روی سرور خارج از ایران ایمیج را می‌سازد و در Harbor خارج Push می‌کند و Replication آن را به Harbor داخل ایران، نزدیک سرورهای Production، منتقل می‌کند.

قدم ۱۰: پاک‌سازی و Garbage Collection

حذف یک ایمیج از پنل فقط ارجاع به آن را حذف می‌کند و لایه‌ها روی دیسک می‌مانند. دو کار لازم است:

  • Tag Retention در تنظیمات هر پروژه: مثلاً نگه‌داشتن ۱۰ نسخه‌ی آخر هر Repository یا نسخه‌هایی که در ۳۰ روز اخیر Pull شده‌اند.
  • Garbage Collection از Administration ← Clean Up: زمان‌بندی هفتگی در ساعات کم‌ترافیک. ابتدا با Dry Run ببینید چه حجمی آزاد می‌شود.

قدم ۱۱: بکاپ

Harbor دو بخش داده دارد که هر دو باید بکاپ گرفته شوند: دیتابیس PostgreSQL (کاربران، پروژه‌ها، تنظیمات) و ایمیج‌ها در data_volume. ساده‌ترین روش سازگار، توقف کوتاه سرویس است:

cd /opt/harbor
sudo docker compose down
sudo tar czf /backup/harbor-$(date +%F).tar.gz /data /opt/harbor/harbor.yml
sudo docker compose up -d

اگر توقف ممکن نیست، از دیتابیس با pg_dump داخل کانتینر harbor-db بکاپ بگیرید و پوشه‌ی ایمیج‌ها را جداگانه کپی کنید، یا ایمیج‌ها را در Object Storage نگه دارید. بکاپ را به سروری دیگر منتقل کنید (بکاپ با Restic روی Object Storage) و بازیابی را حداقل یک بار روی سرور تست امتحان کنید.

نکات Production

  • قبل از ارتقای نسخه‌ی Harbor، یادداشت‌های انتشار و راهنمای Upgrade را بخوانید و بکاپ بگیرید؛ ارتقا معمولاً شامل Migration دیتابیس است.
  • ثبت‌نام آزاد کاربران (Self-registration) را خاموش کنید و در صورت امکان Harbor را به LDAP یا OIDC سازمان وصل کنید.
  • فضای دیسک data_volume را مانیتور کنید؛ Registry پر یعنی Build و Deploy متوقف.

جمع‌بندی

Harbor با چند ساعت کار، یک Registry خصوصی امن، Proxy Cache پایدار برای Docker Hub و اسکن خودکار آسیب‌پذیری به تیم شما می‌دهد. نگه‌داری آن، یعنی Garbage Collection، بکاپ و ارتقا، کاری است که باید از روز اول برنامه‌ریزی شود.

نمی‌خواهید این کار را خودتان انجام دهید؟ تیم مروانت Harbor یا Nexus را روی زیرساخت شما یا سرورهای مروانت راه‌اندازی، به CI/CD وصل و نگه‌داری می‌کند. صفحه‌ی برون‌سپاری پروژه‌های Docker را ببینید.

دیدگاهتان را بنویسید

جستجو

فهرست مطالب