Как разместить Verdaccio самостоятельно в 2026 году: аутентификация npm, хранилище и TLS
Практическое руководство по самостоятельному размещению Verdaccio: Docker, порты, постоянные данные, TLS, безопасность, резервное копирование и проблемы, мешающие использовать сервис в production. Версия 2026 года.
Самостоятельное размещение Verdaccio становится действительно важным после первого redeploy, а не после первого docker run. Если npm-клиенты отправляют данные аутентификации на другой хост или хранилище пакетов доступно только для чтения, Docker всё равно может сообщать, что процесс работает нормально. Описанное ниже развёртывание построено вокруг наблюдаемого поведения: войти через npm, опубликовать scoped-пакет, установить его из чистого проекта и убедиться, что upstream-пакет кэшируется.
Назначение Verdaccio сформулировано однозначно: приватный npm registry для внутренних пакетов. Это описание показывает, что должно оставаться публичным, что следует хранить в приватной зоне и что необходимо восстановить из резервной копии.
Порты, процессы и приватные сервисы
Полезная схема Verdaccio показывает публичный маршрут, приватный порт 4873, границу состояния и все вспомогательные требования. Отметьте, какие стрелки передают учётные данные, а какие обозначают обычный пользовательский трафик. Сетевой контракт Verdaccio включает постоянную конфигурацию, хранилище htpasswd и опциональное object storage. Оставляйте приватные endpoints во внутреннем DNS, разрешайте только необходимые исходящие вызовы и выдайте Verdaccio ограниченные service credentials.
Подтвердите схему одним реальным действием: войдите через npm, опубликуйте scoped-пакет, установите его из чистого проекта и убедитесь, что upstream-пакет кэшируется. Основная нагрузка, вероятно, будет связана с хранением tarball-файлов, операциями с метаданными, параллельными установками и задержкой до настроенных upstream-регистри; наблюдайте именно за этим маршрутом, а не рассматривайте все HTTP-запросы как равноценные.
Превратите локальную команду в наблюдаемый сервис
Используйте команду, в которой явно указаны все важные параметры. Этот базовый вариант привязывает Verdaccio к loopback-интерфейсу хоста, добавляет известные mount points для данных и задаёт первую обязательную настройку. Добавьте проверенные параметры подключения для постоянной конфигурации, хранилища 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. Затем выполните приёмочное действие для Verdaccio; ответ корневой страницы не доказывает, что весь сценарий работает: войдите через npm, опубликуйте scoped-пакет, установите его из чистого проекта и убедитесь, что upstream-пакет кэшируется.
TLS — простая часть; сгенерированные URL — нет
Настройте публичный URL и URL npm registry на один и тот же HTTPS origin. Направьте выбранное имя хоста на порт контейнера 4873, передавайте исходные host и HTTPS scheme и не публикуйте второй прямой origin.
Проверяйте Verdaccio из чистого внешнего клиента. Отделяйте сбой ingress от известной границы приложения — например, когда npm-клиенты отправляют данные аутентификации на другой хост или хранилище пакетов доступно только для чтения. Ошибка сертификата, DNS или 502 относится к маршрутизации; запрос, который дошёл до Verdaccio и завершился ошибкой позже, указывает на состояние приложения, нехватку ресурсов или проблему во вспомогательном компоненте. В руководстве по TLS для собственного домена рассматривается первая группа проблем.
Восстановление Verdaccio на пустом хосте
Для Verdaccio безопасность redeploy начинается с tarball-файлов пакетов, метаданных, конфигурации и файлов аутентификации. Подключите /verdaccio/storage до bootstrap, запишите безвредные тестовые данные и замените контейнер, чтобы доказать фактическую сохранность этого пути. Проверьте путь заменой контейнера, пока тестовые данные существуют: так обнаруживаются mount points, указывающие на каталог на один уровень выше или ниже нужного.
Затем проверьте disaster recovery на чистом хосте. При необходимости используйте согласованный с приложением экспорт базы данных и убедитесь, что приватные tarball-файлы, метаданные, пользователи и конфигурация восстановились, а чистый проект устанавливает пакет с той же integrity. В руководстве по резервному копированию базы данных с проверенным восстановлением задана более строгая цель, чем простая проверка создания файла архива.
Учётные данные, роли и открытые поверхности
Для Verdaccio ценной поверхностью не обязательно является landing page. Главная ошибка — разрешить анонимную публикацию или использовать доступную для записи конфигурацию uplink. Противодействуйте этому намеренно: запретите анонимную публикацию, ограничьте права maintainers и привяжите npm-аутентификацию к точному HTTPS registry host.
VERDACCIO_PUBLIC_URL — это конфигурация, а не секрет; явно задавайте его значение, защищая при этом отдельные credentials, используемые Verdaccio. Используйте непривилегированного пользователя контейнера, если это поддерживается образом, и не подключайте посторонние credentials. Настройте ограничения скорости или размера на ingress-уровне, где недоверенная нагрузка может расходовать хранилище tarball-файлов, выполнять операции с метаданными, создавать параллельные установки и увеличивать задержку до настроенных upstream-регистри.
Проверка отказов в Verdaccio
Тесты производительности должны задействовать хранение tarball-файлов, операции с метаданными, параллельные установки и задержку до настроенных upstream-регистри, а не отправлять повторяющиеся запросы к /. Запустите сценарий «войти через npm, опубликовать scoped-пакет, установить его из чистого проекта и убедиться, что upstream-пакет кэшируется» при реалистичной параллельной нагрузке и зафиксируйте задержку, процент ошибок и рост объёма хранилища.
При планировании обновления необходимо учитывать следующие риски: синтаксис конфигурации, authentication plugins и метаданные пакетов следует проверять для целевой major version Verdaccio. Протестируйте новый релиз на репрезентативных входных данных, затем повторите приёмочную транзакцию и сравните результат. Если npm-клиенты отправляют данные аутентификации на другой хост или хранилище пакетов доступно только для чтения, зафиксируйте неудачную транзакцию и исследуйте первую задействованную границу, вместо того чтобы считать причиной ingress.
Сквозная проверка развёртывания Verdaccio
Не используйте первый пользовательский трафик как приёмочный тест Verdaccio. Подготовьте безвредное тестовое состояние и выполните полное действие: «войти через npm, опубликовать scoped-пакет, установить его из чистого проекта и убедиться, что upstream-пакет кэшируется». Зафиксируйте точный публичный URL, результат, ссылку на image и интервал логирования, связанный с запуском.
Замените контейнер и повторите тест, не пересоздавая данные. Затем восстановите систему на пустом хосте; условие успешного восстановления — возврат приватных tarball-файлов, метаданных, пользователей и конфигурации, после чего чистый проект устанавливает пакет с той же integrity. На каждом проходе наблюдайте за хранением tarball-файлов, операциями с метаданными, параллельными установками и задержкой до настроенных upstream-регистри; настройте alert на ухудшение транзакции, а не на метрики бездействующего контейнера.
Ещё одна проверка должна намеренно завершиться ошибкой: временно запретите тестовой identity доступ к постоянной конфигурации, хранилищу htpasswd и опциональному object storage. Убедитесь, что сообщение Verdaccio указывает на соответствующую границу, а не приводит к удалению данных или бесконечному перезапуску. Восстановите корректное состояние и подтвердите успешное выполнение той же тестовой транзакции. Включите эту короткую проверку в release checklist.
Сохраняйте явную конфигурацию Verdaccio, а маршрутизацию поручите Dockup
Для Verdaccio Dockup может создать маршрут и TLS-сертификат, сохранить mounts, передать secrets и разместить постоянную конфигурацию, хранилище htpasswd и опциональное object storage в приватной сети при развёртывании в Dockup или на подключённых серверах.
Условием выпуска всё равно остаётся конкретная транзакция Verdaccio: войти через npm, опубликовать scoped-пакет, установить его из чистого проекта и убедиться, что upstream-пакет кэшируется. Также проверьте условие восстановления — приватные tarball-файлы, метаданные, пользователи и конфигурация возвращаются, а чистый проект устанавливает пакет с той же integrity. Эти две проверки показывают, работает ли развёртывание и можно ли его восстановить.
Часто задаваемые вопросы
Что нужно Verdaccio для production-развёртывания?
Пропустите контейнер Verdaccio на порту 4873 через один HTTPS origin. Сетевое требование для вспомогательных компонентов — постоянная конфигурация, хранилище htpasswd и опциональное object storage. Не объявляйте Verdaccio готовым, пока не сможете войти через npm, опубликовать scoped-пакет, установить его из чистого проекта и убедиться, что upstream-пакет кэшируется.
Какие данные Verdaccio нужно включать в резервную копию?
Сохраняйте /verdaccio/storage и включайте tarball-файлы пакетов, метаданные, конфигурацию и файлы аутентификации в один recovery manifest. Чистое восстановление Verdaccio считается успешным только тогда, когда возвращены приватные tarball-файлы, метаданные, пользователи и конфигурация, а чистый проект устанавливает пакет с той же integrity.
Требуется ли Verdaccio HTTPS за reverse proxy?
Используйте HTTPS для публичного Verdaccio origin, а порт 4873 оставляйте во внутреннем маршруте. Корректно задайте настройку Verdaccio: публичный URL и URL npm registry должны указывать на один и тот же HTTPS origin. Для Verdaccio HTTPS защищает credentials и пользовательский контент при передаче и обеспечивает согласованное поведение клиентов, зависящее от origin.
Как тестировать обновление Verdaccio?
Восстановите текущее состояние Verdaccio в изолированном развёртывании, установите candidate version и повторите приёмочную транзакцию. Будьте особенно внимательны: синтаксис конфигурации, authentication plugins и метаданные пакетов следует проверять для целевой major version Verdaccio. Сохраняйте предыдущий Verdaccio image, пока не будут понятны границы миграции данных и rollback.