Как да хоствате Verdaccio самостоятелно през 2026 г.: npm удостоверяване, хранилище и TLS

Самостоятелното хостване на Verdaccio става важно при първото повторно внедряване, а не при първото docker run. Ако npm клиентите изпращат удостоверяване към друг хост или хранилището за пакети е само за четене, Docker пак може да отчита напълно здрав процес. Внедряването по-долу е организирано около наблюдаемо поведение: влизане с npm, публикуване на scoped пакет, инсталиране от чист проект и потвърждение, че upstream пакет е кеширан.

Предназначението на Verdaccio е ясно: частен npm registry за вътрешни пакети. Това описание показва какво трябва да остане публично, какво трябва да е частно и какво трябва да може да възстанови едно резервно копие.

Портове, процеси и частни услуги

Полезната диаграма на Verdaccio показва публичния маршрут, частния порт 4873, границата на състоянието и всички поддържащи изисквания. Отбележете кои стрелки пренасят идентификационни данни и кои представляват обикновен потребителски трафик. Мрежовият договор за Verdaccio включва постоянна конфигурация, htpasswd хранилище и незадължително object storage. Дръжте частните endpoints във вътрешен DNS, разрешете само необходимите изходящи връзки и предоставете на Verdaccio service credential с ограничен обхват.

Докажете диаграмата с едно реално действие: влезте с npm, публикувайте scoped пакет, инсталирайте го от чист проект и потвърдете, че upstream пакет е кеширан. Натоварването вероятно ще идва от съхранението на tarball файлове, операциите с metadata, едновременните инсталации и latency до конфигурираните upstream registries; наблюдавайте този път, вместо да третирате всички HTTP заявки като равностойни.

Превърнете локалната команда в услуга, която може да се инспектира

Използвайте команда, която показва всяка важна настройка. Тази базова конфигурация свързва Verdaccio с loopback интерфейса на хоста, добавя известните data mounts и задава първата необходима настройка. Добавете проверените 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 действието за Verdaccio; отговорът от root страницата не може да докаже, че целият сценарий работи успешно: влезте с npm, публикувайте scoped пакет, инсталирайте го от чист проект и потвърдете, че upstream пакет е кеширан.

TLS е лесен; генерираните URL адреси — не

Задайте публичния URL и registry URL адреса за npm към един и същ HTTPS origin. Насочете избрания hostname към container port 4873, препратете оригиналните host и HTTPS scheme и не публикувайте втори директен origin.

Тествайте Verdaccio от чист външен клиент. Разделяйте проблемите при ingress от известната граница на приложението — npm клиентите изпращат удостоверяване към друг хост или хранилището за пакети е само за четене. Грешка със сертификат, DNS или 502 принадлежи на routing слоя; заявка, която достига до Verdaccio и се проваля по-късно, е свързана със състоянието на приложението, капацитета или неговото поддържащо изискване. Ръководството за TLS с персонализиран домейн разглежда първата група проблеми.

Възстановете Verdaccio на празен хост

При Verdaccio сигурността при повторно внедряване започва с tarball файловете на пакетите, metadata, конфигурацията и authentication файловете. Монтирайте /verdaccio/storage преди bootstrap, запишете безвредни примерни данни и заменете контейнера, за да докажете, че този път наистина е постоянен. Тествайте пътя, като замените контейнера, докато безвредните примерни данни са налични; така ще откриете mount-ове, насочени с една директория прекалено нагоре или надолу.

След това тествайте disaster recovery на празен хост. Където е необходимо, използвайте export на базата данни, съгласуван със състоянието на приложението, и проверете дали частните tarball файлове, metadata, потребителите и конфигурацията се възстановяват, а чистият проект инсталира пакет със същата integrity стойност. Ръководството за резервни копия на бази данни, които сте възстановили задава по-висока цел от простата проверка дали е създаден архивен файл.

Идентификационни данни, роли и изложени повърхности

При Verdaccio ценната повърхност не е непременно landing страницата. Основната грешка е да разрешите anonymous publish или да използвате writable uplink конфигурация. Противодействайте ѝ умишлено: забранете anonymous publish, ограничете обхвата на maintainers и поддържайте npm authentication свързано с точния HTTPS registry host.

VERDACCIO_PUBLIC_URL е конфигурация, а не secret; оставете стойността му изрично зададена, като защитите отделните credentials, използвани от Verdaccio. Използвайте непривилегирован container user, когато image-ът го поддържа, и не монтирайте несвързани credentials. Прилагайте ограничения за rate или size на ingress ниво, където недоверени операции могат да изчерпят tarball storage, metadata операциите, едновременните инсталации и latency до конфигурираните upstream registries.

Тестове за отказ на Verdaccio

Тестовете за капацитет трябва да упражняват tarball storage, metadata операциите, едновременните инсталации и latency до конфигурираните upstream registries, а не повтаряща се заявка към /. Изпълнете сценария „влезте с npm, публикувайте scoped пакет, инсталирайте го от чист проект и потвърдете, че upstream пакет е кеширан“ при реалистична конкурентност и запишете latency, error rate и ръста на storage.

Планирането на upgrade трябва да отчита следния риск: config syntax, authentication plugins и package metadata трябва да бъдат тествани спрямо целевата major версия на Verdaccio. Тествайте новия release с представителни входни данни, след което повторете acceptance транзакцията и сравнете резултата. Ако npm клиентите изпращат удостоверяване към друг хост или хранилището за пакети е само за четене, запишете неуспешната транзакция и проверете първата засегната граница, вместо да приемате, че ingress е причината.

Докажете внедряването на Verdaccio от край до край

Не използвайте трафика от първия потребител като acceptance тест за Verdaccio. Подгответе безвредно примерно състояние и изпълнете цялото действие „влезте с npm, публикувайте scoped пакет, инсталирайте го от чист проект и потвърдете, че upstream пакет е кеширан“. Запишете точния публичен URL, резултата, image reference и интервала в log-овете, свързан с изпълнението.

Заменете контейнера и повторете теста, без да създавате данните отново. След това възстановете системата на празен хост; условието за успешно възстановяване е частните tarball файлове, metadata, потребителите и конфигурацията да се върнат, а чистият проект да инсталира пакет със същата integrity стойност. Наблюдавайте tarball storage, metadata операциите, едновременните инсталации и latency до конфигурираните upstream registries при всяко изпълнение и задайте alert при влошаване на транзакцията, а не при idle показатели на контейнера.

Една последна проверка трябва умишлено да се провали: временно забранете на тестовата identity достъпа до persistent configuration, htpasswd storage и optional object storage. Потвърдете, че полученото съобщение от Verdaccio идентифицира съответната граница, вместо да задейства изтриване на данни или безкраен restart. Възстановете валидното условие и потвърдете, че същата примерна транзакция отново преминава успешно. Включете този кратък тест в release checklist-а.

Поддържайте Verdaccio изрично конфигуриран, докато Dockup управлява routing-а

За Verdaccio Dockup може да създаде route и TLS сертификат, да запази mounts, да достави secrets и да постави persistent configuration, htpasswd storage и optional object storage в частна мрежа, докато внедрява към Dockup или свързани сървъри.

Критерият за release все още е конкретната транзакция на Verdaccio: влезте с npm, публикувайте scoped пакет, инсталирайте го от чист проект и потвърдете, че upstream пакет е кеширан. Проверете и условието за възстановяване — частните tarball файлове, metadata, потребителите и конфигурацията трябва да се върнат, а чистият проект да инсталира пакет със същата integrity стойност. Тези две проверки показват дали внедряването работи и дали може да бъде възстановено.

Често задавани въпроси

Какво е необходимо на Verdaccio за production внедряване?

Насочете контейнера на Verdaccio през порт 4873 към един HTTPS origin. Мрежовото поддържащо изискване включва persistent configuration, htpasswd storage и optional object storage. Не приемайте Verdaccio за готов, докато не можете да влезете с npm, да публикувате scoped пакет, да го инсталирате от чист проект и да потвърдите, че upstream пакет е кеширан.

Кои данни на Verdaccio трябва да бъдат включени в резервно копие?

Запазете /verdaccio/storage и включете tarball файловете на пакетите, metadata, конфигурацията и authentication файловете в един и същ recovery manifest. Чистото възстановяване на Verdaccio е успешно само когато частните tarball файлове, metadata, потребителите и конфигурацията се върнат, а чистият проект инсталира пакет със същата integrity стойност.

Необходим ли е HTTPS за Verdaccio зад reverse proxy?

Използвайте HTTPS за публичния Verdaccio origin и оставете порт 4873 във вътрешния route. Приложете правилно настройката на Verdaccio: задайте публичния URL и registry URL адреса за npm към един и същ HTTPS origin. При Verdaccio HTTPS защитава credentials или потребителското съдържание при пренос и поддържа последователно поведението на клиента, зависещо от origin.

Как трябва да се тества upgrade на Verdaccio?

Възстановете текущото състояние на Verdaccio в изолирано внедряване, приложете кандидат-версията и повторете acceptance транзакцията. Обърнете особено внимание, защото config syntax, authentication plugins и package metadata трябва да бъдат тествани спрямо целевата major версия на Verdaccio. Запазете предишния Verdaccio image, докато не изясните границите на миграцията на данните и rollback-а.