Як розгорнути Verdaccio на власній інфраструктурі у 2026 році: npm Auth, сховище та TLS

Самостійне розгортання Verdaccio стає справді важливим під час першого повторного розгортання, а не після першого docker run. Якщо npm-клієнти надсилають облікові дані на інший хост або сховище пакетів доступне лише для читання, Docker усе одно може повідомляти про повністю справний процес. Наведене нижче розгортання побудоване навколо спостережуваної поведінки: увійти через npm, опублікувати пакет із namespace, встановити його в чистому проєкті та переконатися, що upstream-пакет кешується.

Призначення Verdaccio чітко визначене: приватний npm registry для внутрішніх пакетів. Це визначення показує, що має залишатися публічним, що слід зберігати приватним і що саме має відновлювати резервна копія.

Порти, процеси та приватні сервіси

Корисна схема Verdaccio показує публічний маршрут, приватний порт 4873, межу стану та всі супровідні вимоги. Позначте, які стрілки передають облікові дані, а які відповідають звичайному користувацькому трафіку. Мережевий контракт Verdaccio — це постійна конфігурація, сховище htpasswd та опційне object storage. Тримайте приватні endpoints у внутрішньому DNS, дозволяйте лише необхідні вихідні з’єднання та надайте Verdaccio service credential з обмеженою областю дії.

Підтвердьте схему реальною дією: увійдіть через npm, опублікуйте пакет із namespace, встановіть його в чистому проєкті та переконайтеся, що upstream-пакет кешується. Найімовірніше навантаження створюватимуть сховище tarball-файлів, операції з metadata, паралельні встановлення та затримка до налаштованих upstream registry; моніторте саме цей шлях, а не сприймайте всі HTTP-запити як однакові.

Перетворіть локальну команду на сервіс, який можна перевірити

Використовуйте команду, що явно задає всі важливі параметри. Ця базова конфігурація прив’язує Verdaccio до loopback-інтерфейсу хоста, додає відомі mount-и даних і передає перше необхідне налаштування. Додайте перевірені connection settings для постійної конфігурації, сховища htpasswd та опційного object storage; для приватних сервісів використовуйте приватні імена.

docker run -d \
  --name verdaccio \
  --restart unless-stopped \
  -p 127.0.0.1:4873:4873 \
  -v verdaccio-data:/verdaccio/storage \
  -e VERDACCIO_PUBLIC_URL=https://app.example.com \
  verdaccio/verdaccio:latest

Замініть плаваючі tags на протестовану версію або digest. Після запуску перегляньте docker logs --tail 200 verdaccio і переконайтеся, що процес слухає порт 4873. Потім виконайте acceptance action для Verdaccio; відповідь root page не доводить, що весь сценарій успішний: увійдіть через npm, опублікуйте пакет із namespace, встановіть його в чистому проєкті та переконайтеся, що upstream-пакет кешується.

TLS простий; згенеровані URL — ні

Установіть public URL і npm registry URL на один і той самий HTTPS origin. Спрямовуйте вибране hostname на порт контейнера 4873, передавайте оригінальні host і HTTPS scheme та не публікуйте другий прямий origin.

Перевірте Verdaccio з чистого зовнішнього клієнта. Відокремлюйте помилку ingress від відомої межі застосунку — npm-клієнти надсилають облікові дані на інший хост або сховище пакетів доступне лише для читання. Помилка сертифіката, DNS або 502 належить до маршрутизації; запит, який доходить до Verdaccio і пізніше завершується помилкою, належить до стану застосунку, capacity або його супровідної вимоги. У посібнику з TLS для custom domain описано першу групу проблем.

Відновлення Verdaccio на порожньому хості

Для Verdaccio безпечне повторне розгортання починається з tarball-файлів пакетів, metadata, config та authentication files. Підключіть /verdaccio/storage до bootstrap, запишіть нешкідливі тестові дані та замініть контейнер, щоб довести фактичну постійність цього шляху. Перевірте шлях, замінивши контейнер, поки нешкідливі тестові дані ще існують; це виявляє mount-и, вказані на директорію на один рівень вище або нижче.

Далі перевірте disaster recovery на чистому хості. За потреби використовуйте application-consistent database export і переконайтеся, що приватні tarball-файли, metadata, користувачі та config відновлюються, а чистий проєкт встановлює пакет із тією самою integrity. Посібник із резервного копіювання database із перевіреним відновленням задає надійнішу ціль, ніж проста перевірка факту створення archive file.

Облікові дані, ролі та відкриті поверхні

Для Verdaccio цінною поверхнею не обов’язково є landing page. Основна помилка — дозволити anonymous publish або використовувати writable uplink configuration. Свідомо протидійте цьому: забороніть anonymous publish, обмежте область дії для maintainers і прив’яжіть npm authentication до точного HTTPS registry host.

VERDACCIO_PUBLIC_URL — це configuration, а не secret; зберігайте його значення явним, водночас захищаючи окремі credentials, які використовує Verdaccio. Використовуйте unprivileged container user, якщо image це підтримує, і не монтуйте сторонні credentials. Застосовуйте rate або size limits на ingress там, де ненадійні операції можуть споживати сховище tarball-файлів, операції з metadata, паралельні встановлення та затримку до налаштованих upstream registry.

Перевірки відмовостійкості для Verdaccio

Capacity tests мають перевіряти сховище tarball-файлів, операції з metadata, паралельні встановлення та затримку до налаштованих upstream registry, а не повторний запит до /. Запускайте сценарій «увійти через npm, опублікувати пакет із namespace, встановити його в чистому проєкті та переконатися, що upstream-пакет кешується» за реалістичної concurrency і фіксуйте latency, error rate та зростання storage.

Планування upgrade має враховувати цей ризик: config syntax, authentication plugins і package metadata потрібно тестувати з цільовою major version Verdaccio. Перевірте новий release на representative input, потім повторіть acceptance transaction і порівняйте результат. Якщо npm-клієнти надсилають облікові дані на інший хост або сховище пакетів доступне лише для читання, зафіксуйте failing transaction і перевірте першу задіяну boundary замість припущення, що відповідальність лежить на ingress.

Перевірте розгортання Verdaccio наскрізь

Не використовуйте трафік першого користувача як acceptance test для Verdaccio. Підготуйте нешкідливий sample state і виконайте повну дію «увійти через npm, опублікувати пакет із namespace, встановити його в чистому проєкті та переконатися, що upstream-пакет кешується». Зафіксуйте точний public URL, результат, image reference і log interval, пов’язані із запуском.

Замініть контейнер і повторіть перевірку без повторного створення даних. Далі відновіть систему на порожньому хості; умова успішного відновлення — приватні tarball-файли, metadata, користувачі та config повернулися, а чистий проєкт встановлює пакет із тією самою integrity. На кожному етапі спостерігайте за сховищем tarball-файлів, операціями з metadata, паралельними встановленнями та затримкою до налаштованих upstream registry і визначте alert на основі деградації transaction, а не idle container metrics.

Одна фінальна перевірка має навмисно завершитися помилкою: тимчасово забороніть test identity доступ до постійної конфігурації, сховища htpasswd та опційного object storage. Переконайтеся, що повідомлення Verdaccio вказує на відповідну boundary, а не спричиняє видалення даних або нескінченний restart. Відновіть коректну умову та переконайтеся, що та сама sample transaction знову виконується успішно. Додайте цю коротку перевірку до release checklist.

Зберігайте Verdaccio явним, а маршрутизацію передайте Dockup

Для Verdaccio Dockup може створити route і TLS certificate, зберегти mount-и, доставити secrets і розмістити постійну конфігурацію, сховище htpasswd та опційне object storage у приватній мережі під час розгортання в Dockup або на підключених серверах.

Release gate все одно має ґрунтуватися на конкретній Verdaccio transaction: увійти через npm, опублікувати пакет із namespace, встановити його в чистому проєкті та переконатися, що upstream-пакет кешується. Також перевірте умову відновлення — приватні tarball-файли, metadata, користувачі та config повертаються, а чистий проєкт встановлює пакет із тією самою integrity. Ці дві перевірки показують, чи працює розгортання і чи можна його відновити.

Поширені запитання

Що потрібно Verdaccio для production deployment?

Спрямуйте контейнер Verdaccio на порту 4873 через один HTTPS origin. Мережева супровідна вимога — постійна конфігурація, сховище htpasswd та опційне object storage. Не вважайте Verdaccio готовим, доки не зможете увійти через npm, опублікувати пакет із namespace, встановити його в чистому проєкті та переконатися, що upstream-пакет кешується.

Які дані Verdaccio потрібно включати до резервної копії?

Збережіть /verdaccio/storage і додайте tarball-файли пакетів, metadata, config та authentication files до одного recovery manifest. Відновлення чистого Verdaccio успішне лише тоді, коли приватні tarball-файли, metadata, користувачі та config повертаються, а чистий проєкт встановлює пакет із тією самою integrity.

Чи потрібен Verdaccio HTTPS за reverse proxy?

Використовуйте HTTPS для публічного Verdaccio origin і залиште порт 4873 у внутрішньому маршруті. Правильно застосуйте налаштування Verdaccio: установіть public URL і npm registry URL на один і той самий HTTPS origin. Для Verdaccio HTTPS захищає credentials або user content під час передавання та забезпечує узгоджену поведінку клієнта, чутливу до origin.

Як тестувати upgrade Verdaccio?

Відновіть поточний стан Verdaccio в ізольованому deployment, застосуйте candidate version і повторіть acceptance transaction. Будьте особливо уважні: config syntax, authentication plugins і package metadata потрібно тестувати з цільовою major version Verdaccio. Зберігайте попередній Verdaccio image, доки не буде зрозумілою межа міграції даних і rollback.