Установка Harbor (реестр образов) на Ubuntu 22.04 с Docker

TL;DR

Harbor — корпоративный реестр контейнерных образов. В этом пошаговом руководстве показано, как установить Harbor на Ubuntu 22.04 с помощью Docker CE и офлайн-инсталлятора, настроить HTTPS (Let’s Encrypt или вручную), создать пользователей и проекты, подключиться через Docker CLI и загрузить первый образ. Включены чек-листы, сценарии устранения неполадок и рекомендации по безопасности.

Введение

Harbor — это проект с выпуском CNCF, корпоративный реестр образов Docker/OCI для облачных сред. Harbor хранит и распределяет контейнерные образы и предоставляет механизмы безопасности: политики, роль-базированный доступ, сканирование уязвимостей и подписание образов. Варианты развертывания: в Kubernetes (через Helm) или как набор контейнеров с Docker Compose.

В этом руководстве приводится установка Harbor с помощью Docker на сервере Ubuntu 22.04. Мы пройдём установку Docker CE, конфигурацию офлайн-инсталлятора Harbor, настройку HTTPS, базовое администрирование (пользователи, проекты) и демонстрацию push/pull через docker CLI.

Важно: следуйте инструкциям по безопасности перед выносом в продакшн: используйте надежные пароли, TLS-сертификаты из доверенного центра, резервное копирование базы данных и конфигураций.

Основные цели этого руководства

• Установить Docker CE на Ubuntu 22.04
• Скачать и распаковать офлайн-инсталлятор Harbor
• Настроить harbor.yml и включить HTTPS
• Запустить инсталлятор и проверить контейнеры
• Создать пользователя, добавить в проект, выполнить docker login/push

Требования

• Сервер Ubuntu 22.04 (в примерах hostname — “harbor-server”).
• Пользователь с правами sudo (не обязательно root).
• Домен или локальное имя, указывающее на этот сервер (например, registry.example.local).
• TLS-сертификат для домена (Let’s Encrypt или самоподписанный для тестирования).
• Доступ в интернет для загрузки пакетов (или подготовленный офлайн-репозиторий).

Быстрая карта процесса

1. Установить Docker CE и плагин docker compose
2. Скачать офлайн-инсталлятор Harbor и распаковать в /opt/harbor
3. Изменить harbor.yml: hostname, HTTPS-сертификаты, пароль admin, база данных
4. Выполнить sudo ./install.sh
5. Проверить контейнеры: docker compose ps
6. Войти в веб-интерфейс, создать пользователя и проект
7. Выполнить docker login/push

Установка Docker CE (Community Edition)

Harbor может быть развёрнут в разных вариантах; в этом руководстве выбран способ с Docker Engine + офлайн-инсталлятор.

Запустите установку зависимостей:

sudo apt install \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

При появлении запроса подтвердите установку, введя y и нажав ENTER.

Добавьте официальный GPG-ключ и репозиторий Docker:

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Обновите индекс пакетов и установите Docker CE и плагин Docker Compose:

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Проверьте статус службы Docker:

sudo systemctl is-enabled docker
sudo systemctl status docker

Вы должны увидеть, что служба running и enabled — Docker будет автоматически запускаться при старте системы.

Примечание: по безопасности можно добавить своего пользователя в группу docker, чтобы запускать docker без sudo: sudo usermod -aG docker . После этого выйдите и войдите в сеанс снова.

Загрузка офлайн-инсталлятора Harbor

Harbor поставляется в двух вариантах инсталлятора: офлайн (включает образы) и онлайн. В этом руководстве используется офлайн-инсталлятор.

Перейдите в /tmp и загрузите последний релиз (команда получает URL релиза и скачивает tgz):

cd /tmp
curl -s https://api.github.com/repos/goharbor/harbor/releases/latest | grep browser_download_url | cut -d '"' -f 4 | grep '\.tgz$' | wget -i -

Распакуйте скачанный архив (название файла в примере — harbor-offline-installer-v2.6.1.tgz; у вас может быть другая версия — используйте фактическое имя):

tar -xzvf harbor-offline-installer-v2.6.1.tgz

Переместите директорию harbor в /opt:

sudo mv harbor /opt/

Важно: сохраняйте инсталлятор и архив, если планируете офлайн-установку на других хостах.

Настройка установки Harbor (harbor.yml)

Перейдите в каталог инсталлятора:

cd /opt/harbor

Скопируйте шаблон конфигурации и отредактируйте его:

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

Основные параметры, которые нужно изменить:

# The IP address or hostname to access admin UI and registry service.
# DO NOT use localhost or 127.0.0.1, because Harbor needs to be accessed by external clients.
hostname: registry.howtoforge.local

....

https:
  # https port for harbor, default is 443
  port: 443
  # The path of cert and key files for nginx
  certificate: /etc/letsencrypt/live/registry.howtoforge.local/fullchain.pem
  private_key: /etc/letsencrypt/live/registry.howtoforge.local/privkey.pem

....

harbor_admin_password: Harbor_Docker_Ubuntu

....

database:
  # The password for the root user of Harbor DB. Change this before any production use.
  password: db_pass_harbor

Разъяснение ключевых полей:

• hostname — доменное имя, по которому будет доступен Harbor (например, registry.example.com). Не используйте localhost.
• https.certificate и https.private_key — пути к TLS-сертификату и приватному ключу. Для Let’s Encrypt это обычно /etc/letsencrypt/live//*.pem.
• harbor_admin_password — начальный пароль администратора (сильный пароль обязательно поменяйте после установки через UI).
• database.password — пароль для базы данных Harbor (рекомендуется изменить на безопасный).

Примечание: если вы используете самоподписанный сертификат только для тестирования, помните, что клиент Docker и браузер потребуют доверия к этому сертификату (добавьте в системный хранилище доверенных сертификатов или используйте настройку daemon.json для docker).

Важно: убедитесь, что DNS-запись домена указывает на IP сервера, или добавьте запись в /etc/hosts для тестовой среды.

Генерация TLS-сертификата (Let’s Encrypt) — кратко

Если хотите использовать бесплатные сертификаты Let’s Encrypt, самый простой путь — использовать certbot. Пример использования с режимом webroot или standalone (сервер должен иметь порт 80/443 доступными):

sudo apt install certbot
sudo certbot certonly --standalone -d registry.howtoforge.local --agree-tos --no-eff-email -m admin@example.com

После успешного выполнения certbot создаст сертификаты в /etc/letsencrypt/live/registry.howtoforge.local/. Укажите эти пути в harbor.yml.

Примечание: certbot в режиме standalone кратковременно запускает собственный HTTP сервер, поэтому убедитесь, что на порту 80 ничего не мешает.

Запуск инсталлятора Harbor

Когда harbor.yml настроен и сертификаты на месте, выполните скрипт установки из каталога /opt/harbor:

sudo ./install.sh

Скрипт проверит зависимость: наличие Docker и docker compose, затем распакует образы и подготовит окружение.

В процессе могут быть показаны этапы: распаковка образов, подготовка конфигураций, генерирование сертификатов и запуск контейнеров.

После завершения установки в выводе вы увидите состояние сервисов.

Проверка запущенных сервисов Harbor

Убедитесь, что вы в каталоге /opt/harbor и выполните:

ls
docker compose ps

Вы должны увидеть ряд контейнеров (nginx, core, registry, jobservice, database и т.д.) в состоянии Up/healthy.

Откройте браузер по адресу https://registry.howtoforge.local/ и попадёте на страницу логина. Введите admin и пароль, который вы указали в harbor.yml.

После входа вы увидите дашборд и дефолтный проект library.

Важно: поменяйте пароль администратора сразу после первой авторизации.

Базовое администрирование: пользователи и проекты

Создание пользователя

Перейдите в раздел Администрирование → Пользователи и нажмите НОВЫЙ ПОЛЬЗОВАТЕЛЬ. Заполните поля (например, alice) и подтвердите.

Заполните данные пользователя и нажмите OK.

Пользователь появится в списке.

Добавление пользователя в проект

Перейдите в Projects → выберите проект library → Members. Нажмите кнопку ДОБАВИТЬ ПОЛЬЗОВАТЕЛЯ, выберите alice и назначьте роль, например Project Admin, после чего подтвердите.

После этого alice появится в списке участников проекта.

Работа с Docker CLI: вход, push и pull

Вход в реестр

На машине клиента выполните:

docker login https://registry.howtoforge.local/

Введите имя пользователя и пароль (alice). При успешном входе Docker выдаст Login Succeeded.

Отправка (push) образа в Harbor

Пример: скачиваем nginx:alpine, переименовываем тег и пушим в проект library.

docker pull nginx:alpine

docker images

docker tag nginx:alpine registry.howtoforge.local/library/nginx:alpine

docker push registry.howtoforge.local/library/nginx:alpine

После успешного push образ появится в разделе Projects → library → Repositories.

Контроль доступа и роли — кратко

Harbor поддерживает RBAC: роли на уровне проекта (Project Admin, Developer, Guest). Управляйте правами доступа через Members → назначение ролей.

Совет: создавайте сервисные аккаунты (robot accounts) для CI/CD и ограничивайте их права по минимуму.

Безопасность и hardening (рекомендации)

• Используйте TLS от публичного CA в продакшне; исключение — тестовые стенды.
• Храните приватные ключи и сертификаты в защищённом хранилище (Vault, KMS).
• Включите сканирование уязвимостей (Vulnerability Scanning) и настройте политики.
• Ограничьте доступ к панели администрирования только из доверенных сетей (через firewall/NGINX).
• Настройте резервное копирование базы данных и конфигураций (см. раздел «Резервное копирование»).
• Разграничивайте роли: используйте robot accounts для CI/CD, не используйте admin в автоматизации.

Резервное копирование и восстановление

Harbor использует СУБД (обычно PostgreSQL в контейнере). Для простого бэкапа:

• Сделайте дамп базы данных PostgreSQL внутри контейнера или с хоста.
• Сохраните каталог с данными (для встроенного storage) и TLS-сертификаты.

Пример создания дампа (если используется контейнер database):

# Получить имя контейнера database
docker ps | grep harbor-database

# Выполнить pg_dump внутри контейнера
docker exec -it  pg_dump -U postgres > harbor_db_dump.sql

Восстановление зависит от схемы: разверните новый Harbor и импортируйте дамп в его БД, либо восстановите тома/файлы контейнеров.

Важно планировать регулярные бэкапы и тестировать восстановление.

Обновление Harbor

• Перед обновлением прочтите release notes конкретной версии Harbor.
• Создайте резервную копию базы и конфигурации.
• Для обновления скачайте новый офлайн-инсталлятор и выполните ./install.sh — инсталлятор обновит сервисы.
• В тестовой среде всегда сначала прогоняйте обновление и проверяйте работоспособность.

Альтернативные подходы

• Kubernetes + Helm: если у вас кластер Kubernetes, рекомендуем установку Harbor через официальный Helm-чарт — это упрощает масштабирование и интеграцию с CSI/Ingress.
• Облачные реестры (ECR/GCR/Azure ACR): если ваша инфраструктура целиком в облаке, рассмотрите облачный реестр с управляемыми функциями.
• Управление контейнерами через GitOps: robot accounts + CI для автоматического push образов.

Когда установка Harbor с Docker не подходит

• Если требуется высокая доступность и масштабирование уровня кластера, предпочтителен развёртывание в Kubernetes.
• Для управления миллионами образов и интеграций с облачной платформой может быть выгоднее использовать облачный реестр.

Чек-листы и роли (кто что делает)

• Системный администратор:
  • Подготовить сервер и DNS, установить Docker
  • Настроить firewall и резервное копирование
  • Установить и обновлять Harbor
• DevOps-инженер:
  • Генерировать robot accounts для CI
  • Настроить автоматические сканирования и политики
  • Интегрировать реестр в CI/CD
• Разработчик:
  • Пушить образы с помощью docker tag/push
  • Использовать проектные роли и следовать политикам безопасности

SOP: быстрый playbook установки (конспект)

1. Установить зависимости и добавить репозиторий Docker.
2. Установить Docker CE и docker compose plugin.
3. Скачать офлайн-инсталлятор Harbor и распаковать в /opt/harbor.
4. Скопировать harbor.yml.tmpl → harbor.yml и отредактировать hostname, HTTPS, пароли.
5. Убедиться, что сертификаты доступны в указанных путях.
6. Выполнить sudo ./install.sh и дождаться статуса Up для контейнеров.
7. Выполнить docker compose ps и перейти в UI по https:///.
8. Сменить пароль admin, создать пользователей и проекты.
9. Настроить robot accounts для CI и политику сканирования.

Тесты и критерии приёмки

• UI доступен по HTTPS и проходит проверку сертификата браузером.
• Веб-страница логина отображается и вы можете войти под admin.
• docker login проходит успешно для созданного пользователя.
• docker push/pull образов для проекта проходит без ошибок.
• Все контейнеры Harbor в состоянии Up/healthy после установки.

Типичные проблемы и их устранение

• “Cannot connect to registry” — проверьте DNS и firewall, убедитесь, что порты 443/80 открыты.
• “x509: certificate signed by unknown authority” — клиент не доверяет сертификату; добавьте CA в доверенные или используйте сертификат публичного CA.
• Ошибки при install.sh — проверьте лог скрипта и наличие свободного места на диске (docker образа могут занимать гигабайты).
• Контейнеры не запускаются/падают — смотрите логи через docker compose logs .

Пример просмотра логов:

docker compose logs -f nginx

Советы по производительности

• Размещайте каталоги с данными Harbor (volumes) на быстром диске (SSD).
• Настройте retention политики для артефактов, чтобы не хранить старые ненужные образы.
• В больших установках рассмотрите внешнюю СУБД и объектное хранилище (S3-совместимое) для хранения слоёв образов.

Краткая терминология

• Harbor — реестр образов (registry) с UI и безопасностью.
• Project — логическая пространство имен для репозиториев и прав.
• Robot account — сервисный аккаунт для CI/CD.
• Image/Repository — контейнерные образы и их репозитории.

Резюме

Вы успешно установили Harbor на Ubuntu 22.04 используя Docker CE и офлайн-инсталлятор. Установлен TLS, создан администратор и пользователь, выполнён push образа. В руководстве приведены рекомендации по безопасности, бэкапам, обновлению и устранению проблем.

Важно: перед использованием в продакшне настройте резервные копии, мониторинг и политики безопасности, а также протестируйте процедуру восстановления.

Полезные команды (чизшит)

# Проверки
sudo systemctl status docker
docker compose ps

# Логи
docker compose logs -f 

# Docker CLI
docker login https://registry.example.com
docker pull nginx:alpine
docker tag nginx:alpine registry.example.com/library/nginx:alpine
docker push registry.example.com/library/nginx:alpine

# Backup базы (пример)
docker exec -it  pg_dump -U postgres > harbor_db_dump.sql

Краткая подборка сценариев: когда использовать Helm, когда — Docker

• Используйте Docker-инсталляцию, если у вас одиночный хост и вы хотите простую установку.
• Используйте Helm в Kubernetes, если нужна высокая доступность, масштабирование и интеграция с кластером.

Вывод: Harbor предоставляет мощный и безопасный реестр образов. Правильная конфигурация TLS, резервных копий и ролей обеспечит надёжную работу в командах разработки и в CI/CD процессах.