Налаштування приватного Maven-репозиторію (Nexus) для Java-проєктів

Чому ламаються збірки без приватного Maven-репозиторію

Збірка проходить на машині розробника і падає в CI з помилкою розв’язання залежностей — бо приватна бібліотека залишилася лише в локальному кеші ~/.m2.

Локальний кеш не версіонується, не переноситься між агентами і не є джерелом істини: щойно код потрапляє на чисту машину, артефакту там просто немає, і розбір починається з’ясуванням, у кого збірка «працює».

Другий клас відмов — недоступність зовнішнього джерела. Публічний репозиторій відповідає таймаутом або помилкою, і зупиняється не одне завдання, а весь конвеєр: кожен агент заново тягне залежності з мережі.

Той самий коміт у різний час збирається по-різному, а час збірки коливається в рази — від стану чужої інфраструктури, на яку ми не впливаємо.

Третій — розбіжні версії бібліотек. Поки залежності резолвляться напряму, діапазони й транзитивні зв’язки розв’язуються на різних машинах неоднаково. Тест «блимає», реліз відтворюється не повністю, і розбір займає години: порівнювати доводиться не код, а графи залежностей.

Повторюваність збірки — властивість інфраструктури, а не дисципліни розробника.

Поки приватні бібліотеки та внутрішні модулі збираються «на місці», їхні версії ніде не зафіксовані, кеш залежностей у кожного свій, а результат збірки на чистій машині залежить від того, що встигло завантажитися раніше.

Звідси ж і довгі збірки: без спільного кешу ті самі артефакти завантажуються повторно на кожному агенті.

Розбираємо, як це закривається: приватний Maven-репозиторій стає єдиною точкою отримання артефактів — з проксіюванням зовнішніх джерел, політикою зберігання версій і передбачуваною збіркою на будь-якій чистій машині.

Що змінюється в збірці та постачанні після впровадження

Поки залежності тягнуться напряму з публічних джерел, збірка поводиться непередбачувано: частина бібліотек відповідає повільно, частина недоступна, окремі версії підміняються без попередження.

Приватний Maven репозиторій на Nexus замикає ланцюг постачання на себе — артефакти надходять із внутрішнього сховища, а зовнішні джерела використовуються лише для первинного наповнення кешу. Нижче — що саме змінюється і за якими метриками це видно.

• Час чистої збірки. Перший прогін на новій машині або в чистому контейнері скорочується в рази: завантаження йде внутрішньою мережею з прогрітого кешу проксіювання, а не паралельно із зовнішніх джерел із різною швидкістю віддачі.
• Частка відмов збірки. Відмови через недоступність зовнішнього джерела, обрив з’єднання та пошкоджений артефакт перестають бути окремим класом збоїв — збірка перестає залежати від чужого аптайму.
• Фіксація версій. Діапазони та плаваючі мітки замінюються точними версіями в батьківському описі, снапшоти внутрішніх бібліотек переходять в окреме сховище з політикою зберігання — збірка відтворюється на будь-якій машині.
• Підключення нового розробника. Налаштування зводиться до локального конфігу та облікових даних: шаблон роздається з репозиторію, час до першої успішної збірки скорочується до десятків хвилин без обходу колег із флешкою.

Ці чотири пункти зручно брати як приймання: до впровадження фіксуються поточні значення, після — порівнюються за журналами збірок. Якщо хоча б час чистої збірки та частка відмов не рухаються, отже кеш проксіювання налаштовано неправильно або частина залежностей обходить сховище.

Проксі, хостинг і група репозиторіїв: що вибрати

Три режими сховища вирішують різні завдання, і плутати їх — головне джерело проблем на старті. Проксі-режим закриває зовнішні залежності: він кешує те, що реально завантажується збіркою, і прогін перестає залежати від доступності публічного джерела.

Хостинг власних артефактів зберігає те, що ви випускаєте самі, — внутрішні бібліотеки, утиліти, зібрані модулі. Група репозиторіїв не зберігає нічого: це єдина точка входу, з якої збирач забирає все одразу.

Робоча схема — поєднання: проксі закриває зовнішній контур, хостинг тримає власні випуски, група віддає їх однією адресою. Права видаються за призначенням: на проксі лише читання, на хостинг — запис для складальних агентів.

Окремо варто розділення за контурами: складальний контур не повинен бачити релізні артефакти, інакше тестова збірка непомітно підтягне те, що ще не пройшло перевірку.

Етапи впровадження: від аудиту залежностей до передачі

Порядок кроків тут не формальність: якщо почати з розгортання й прав, а склад залежностей з’ясовувати в кінці, половину конфігурації доведеться переробляти — групи зберігання та правила доступу будуються під реальний трафік, а не навпаки.

1. Інвентаризація залежностей. Проходимо по всіх модулях і збираємо фактичний список артефактів: що тягнеться із зовнішніх джерел, що публікується власною збіркою, які версії закріплені в батьківських файлах. На виході — перелік груп із частотою звернень, за ним рахується обсяг сховища та потреба в дзеркалах.
2. Схема розміщення. Визначаємо, скільки сховищ потрібно: проксі для зовнішніх джерел, внутрішнє для власних артефактів, окремі лінії для проміжних і релізних збірок. Прописуємо порядок пошуку, щоб збірка не йшла в зовнішню мережу за тим, що вже лежить локально.
3. Налаштування прав доступу. Розводимо ролі: облікові записи складального конвеєра отримують читання й запис лише у свої групи, розробники — читання та публікацію у відведені каталоги, адміністратори — керування. Публікація йде під окремим обліковим записом, прив’язаним до конкретного проєкту, а не під загальним.
4. Перевірка на реальних проєктах. Спершу наповнюємо проксі-сховища, потім збираємо два-три проєкти з повністю очищеним локальним кешем. Так видно, що жодна залежність не тягнеться в обхід, а збірка проходить на чистій машині.
5. Передача в експлуатацію. Віддаємо описані правила доступу, регламент резервного копіювання, спостереження за вільним місцем і порядок ескалації. Команда замовника повторює типові операції сама — публікацію, відкликання версії, додавання проєкту.

Після передачі сховище живе без нашої участі: налаштування зафіксовані в документації, а не в листуванні, і будь-яка зміна відтворювана.

Комплект передачі: конфігурації, схеми, регламенти

Разом із робочою конфігурацією команда замовника отримує повний комплект передачі — усе лежить у репозиторії поряд із кодом, а не в листуванні та головах. Такий набір дозволяє змінювати склад модулів, підключати нові команди й відновлювати сховище без звернення до нас.

• settings.xml і профілі збірки для локальних станцій і агентів: дзеркала, порядок звернення до джерел, прив’язка до облікових даних.
• Конфігурація сховища: розкладка локальних, проксіювальних і групових репозиторіїв, прив’язка форматів артефактів, правила кешування зовнішніх залежностей.
• Схема потоків артефактів: від збірки до публікації, хто пише і хто лише читає, де закріплено правило незмінності релізної версії.
• Політики доступу: ролі сервісних облікових записів, права на публікацію та видалення, строки ротації, зв’язок із корпоративним каталогом користувачів.
• Регламент оновлення: порядок виведення версій сховища, вікна робіт, перевірка сумісності зі складальними конвеєрами, план відкату.
• Резервне копіювання: склад копій, розклад, винесення за межі основного майданчика, регулярна перевірка відновлення на тестовому контурі.
• Інструкції черговому: сценарії відновлення, дії при відмові вузла, видача доступу новій команді, діагностика збою публікації.
• Перелік приймання: звірка прав, збірка проєкту з нуля, відновлення з копії, перевірка очищення застарілих артефактів.

Кейс: переведення збірок із публічного джерела на власне

До: збірка залежала від чужого вузла

Двадцять вісім Java-проєктів збиралися напряму з публічного джерела, кеш залежностей лежав на машинах розробників і складальних агентах. Поки зовнішній вузол відповідав, проблем не було; при затримці або обриві з’єднання конвеєр зупинявся на етапі розв’язання залежностей.

За квартал накопичилося близько сорока таких зупинок, кожна — ручний перезапуск і простій команди. Повний прохід збірки займав 12–14 хвилин, і помітна частина часу йшла на повторне завантаження тих самих бібліотек.

Що зробили

Наші інженери розгорнули приватний Maven репозиторій на Nexus і ввели єдину точку входу для всіх команд: зовнішні джерела проксіюються, внутрішні артефакти публікуються в локальний хостинг, а групову адресу прописано в налаштуваннях збірки.

Кеш переїхав на сервер і перестав залежати від конкретної машини — повторний запит бібліотеки закривається всередині мережі. Окремо описали політики зберігання та правила для снапшотів, щоб каталог не розростався безконтрольно.

Результат

Середній прохід збірки скоротився з 12–14 до 6–7 хвилин, а кількість зупинок через зовнішню доступність упала до поодиноких випадків за квартал. На єдину точку входу переведено всі 28 проєктів, включно зі старими модулями з власними налаштуваннями.

Клас відмов «зовнішнє джерело недоступне» перестав впливати на випуск: збірка йде з внутрішнього кешу, а зовнішній вузол використовується лише для його поповнення.

Що робити, якщо вже розгорнуто власний сервер артефактів?

Розгорнутий Nexus — не привід переїжджати «з нуля». Розумний порядок зворотний: аудит поточного сховища, перенесення артефактів, потім включення в єдину схему доступу. За такого порядку команди продовжують збирати й випускати релізи, поки ми працюємо зі сховищем.

Аудит починається з карти репозиторіїв: які з них власні, які проксіюють зовнішні джерела, що реально лежить у спільних групах і хто публікує артефакти під кожним обліковим записом.

Окремо фіксуємо, де не чистилися снапшоти й які збірки жорстко прив’язані до старих адрес — ці посилання доведеться змінювати в конфігурації проєктів, і знати про них краще заздалегідь.

Перенесення йде не копіюванням каталогів, а зі збереженням історії версій: переносяться випущені релізи, метадані та контрольні суми, щоб старі збірки залишалися відтворюваними, а відкат на попередню версію працював так само, як раніше. Застаріле можна не тягнути — обсяг сховища скорочується, а потрібна історія залишається.

Останній крок — включення в загальну схему доступу: групи з корпоративного каталогу, роздільні ролі на читання й публікацію, окремі облікові записи для систем збірки, єдині правила зберігання снапшотів.

Після цього сховище живе за загальними правилами й не потребує ручного втручання при кожному релізі.

Розбір сумнівів: оновлення, доступ, відмовостійкість

Перед стартом зазвичай виринає п’ять питань: ізоляція контурів, доступи підрядників, поведінка при недоступності сховища, обсяг зберігання та правки у файлах збірки. Нижче — короткі відповіді щодо кожного.

Як видати доступ підряднику, не відкриваючи весь репозиторій?

Роль із читанням конкретного набору артефактів і окремий обліковий запис без права публікації. Доступ обмежений строком і відкликається однією операцією, коли роботи завершено.

Що буде, якщо сховище недоступне?

Локальний кеш залежностей на машині збірки закриває повторну збірку, але нові версії не підтягнуться. Ставимо дзеркало й описуємо порядок перемикання — конвеєр не зупиняється на час збою.

Як швидко зростає обсяг зберігання?

Зростання дає переважно кеш сторонніх бібліотек і снапшоти збірок. Політика зберігання тримає останні збірки на версію й чистить решту за розкладом — обсяг перестає зростати лінійно, відкат залишається можливим.

Чи доведеться змінювати файли збірки?

Так, але мінімально: адреса Nexus і доступи виносяться в налаштування оточення, а не в код проєкту. Розробнику достатньо правки в особистому профілі, командна збірка бере параметри з оточення.

Обговорімо задачу та повернімося з оцінкою й планом

Щоб розмова була предметною, а не оглядовою, нам вистачить кількох ввідних про ваш контур. Спеціально нічого готувати не потрібно — достатньо того, що вже є в команди: опис проєктів, конфігурації збірки та вимоги служби безпеки. Корисно надіслати:

• склад Java-проєктів: скільки модулів, що публікується як артефакт, а що лише споживається, хто з команд залежить від спільних бібліотек;
• поточні джерела залежностей: публічні зовнішні репозиторії, локальні дзеркала, артефакти, що лежать просто в системі контролю версій;
• вимоги до ізоляції контурів: які середовища не повинні бачити артефакти одне одного і з якого боку потрібна перевірка;
• модель доступу: хто публікує, за якими обліковими даними, чи потрібна інтеграція з корпоративним каталогом користувачів і рольова схема;
• політика зберігання та проксіювання: що розумно тримати постійно, що віддавати з проміжного сховища і яка глибина зберігання потрібна для відкатів;
• обмеження майданчика: де розміщується сервіс, вимоги до резервного копіювання, відновлення та моніторингу;
• сценарій переходу: як переводимо проєкти на приватний репозиторій, щоб збірки не зупинялися на жодному етапі.

За підсумками розбору повернемося з планом впровадження та оцінкою строків: етапи, зони відповідальності, точки перевірки, порядок відкату. Опишіть задачу — і ми прийдемо з конкретною пропозицією, а не із загальними питаннями.