Поделиться через

Руководство по реализации сервера NuGet

В некоторых случаях может потребоваться настроить собственный источник пакетов NuGet. Многие существующие реализации существуют , которые позволяют размещать собственный веб-канал различным образом, но протокол между официальным клиентским программным обеспечением NuGet и веб-каналом пакетов задокументирован, что позволяет создавать собственную реализацию веб-канала с нуля.

Протокол развивается с течением времени, и это руководство предназначено для тех, кто хочет или уже реализовал сервер пакетов NuGet.

С момента первоначального выпуска протокола NuGet версии 3 в 2015 году NuGet развивался, чтобы предоставить разработчикам более богатые возможности, и это требует, чтобы репозитории пакетов выполняли дополнительную работу для обеспечения дополнительной ценности для потребителей пакетов, помимо простого извлечения точных метаданных из размещенных пакетов и их возврата в различных формах. Например, конечные точки поиска и метаданных пакета содержат больше, чем просто метаданные, найденные в файле nuspec пакета nupkg.

Обратите внимание, что это руководство сосредоточено на протоколе NuGet версии 3, поскольку протокол V2, по сути, не задокументирован, и с 2015 года рекомендованным протоколом для взаимодействия клиента и сервера NuGet является протокол V3. Для получения дополнительной информации, прочитайте о версионировании протокола.

Хронология

Чтобы помочь авторам существующих репозиториев NuGet в курсе новейших функций NuGet, ниже приведена хронология соответствующих функций, упомянутых в оставшейся части документа.

Год Функция
2013 В блоге, объясняющем, как управлять владельцами пакетов на nuget.org, указано, что владельцы, отображаемые на веб-сайте, это учетные записи, имеющие разрешение на загрузку новых версий, и поэтому owners метаданные в пакете игнорируются.
2017 Добавлено verified к SearchQueryService ответам.
Поддержка семантического версионирования 2.0.0
2018 Внедренные лицензии
2019 Внедренные значки
Деградация пакета RegistrationBaseUrl (ресурс метаданных пакета)
2020 Сведения об уязвимостях пакета ( RegistrationsBaseUrl ресурс метаданных пакета)
packageTypes Добавлен параметр запроса для SearchQueryService запросов
2021 Встроенный файл Readme
2023 Предварительная аутентификация аутентифицированных запросов
VulnerabilityInfo ресурс
2025 Включить загрузку встроенных файлов README

Поле владельца

Рассмотрим два поля файла манифеста пакета (.nuspec) и <owners>. <authors> Авторы пакетов, которые упаковывают сторонний контент, часто помещают имя третьей стороны в поле <authors>. Поле <owners> предназначено для обозначения того, кто опубликовал пакет в репозитории, и поэтому кто должен обращаться в случае проблем упаковки или вопросов.

Это было объяснено в записи блога за 2013 год, поэтому поле <owners> в файле .nuspec считается устаревшим. Если манифест пакета содержит эти метаданные, его следует игнорировать. Не возвращайте значение поля <owners> файла .nuspec в свойстве owners в JSON ответе ресурса поиска или ресурса метаданных пакета.

Если у репозитория есть права на уровне пакета, рекомендуется указывать учетные записи, имеющие разрешения на публикацию новых версий, в owner метаданных для ответа JSON при поиске и в ресурсах метаданных пакета.

verified Поле ответа поиска

Пользовательский интерфейс диспетчера пакетов Visual Studio отображает синюю галочку рядом с пакетами в результатах службы поиска, когда для нового поля задано verified значение true.

NuGet.org использует это с данными префикса пакета (серверными данными, а не частью API NuGet), поэтому этот флажок отображается только клиентам, когда учетная запись, которая владеет пакетом, загружает пакет. Например, любой пакет с префиксом microsoft.* проверяется только в том случае, если пакет принадлежит учетной записи Майкрософт на nuget.org. Любой пользователь, загружавший пакет с идентификатором, начинающимся с microsoft., до внедрения зарезервированных префиксов, не будет иметь этот значок проверки. NuGet.org также позволяет префиксам не быть эксклюзивными, так что любой пользователь может загрузить пакет под Contoso.ToolWithPlugins.Community.*, но не получит подтвержденный значок.

Поддержка семантического версионирования 2.0.0

NuGet поддерживает гибрид между System.Version и семантической версией, но в 2017 году была добавлена поддержка семантической версии 2.0.0. Поэтому ресурсы API NuGet, возвращающие версии клиентским версиям ниже 3.6.0, не должны возвращать пакеты, использующие функции семантики 2.0.0.0, несовместимые с семантической версией 1.0.0.

Наиболее важными различиями между двумя версиями являются метки предварительного выпуска и строка метаданных. Спецификация семантического версионирования 1.0.0 предоставляет [0-9A-Za-z-] в качестве примера строку регулярных выражений для символов, разрешенных в качестве части метки предрелизной версии, и не поддерживает строки метаданных. Спецификация «Семантическое версионирование 2.0.0» позволяет разделять идентификаторы предварительных выпусков с помощью символов . (и запрещает числовым идентификаторам иметь начальный ноль), а также позволяет добавлять метаданные сборки после символа +.

В ресурсе метаданных пакета (RegistrationsBaseUrl), версии ресурсов ниже 3.6.0 должны возвращать только пакеты, которые соответствуют требованиям .NET или Семантического версионирования 1.0.0. Это означает, что пакеты, версии которых соответствуют только семантической версии версии 2.0.0, невидимы для этих клиентских версий.

Аналогичным образом , служба запросов поиска (SearchQueryService) и служба автозавершения (SearchAutocompleteService) добавили &semVerLevel={version} параметры запроса. Если semVerLevel отсутствует, предположим значение 1.0.0. Как и ресурс метаданных пакета, пакеты, версия которых совместима только с семантической версией 2.0.0.0, не должны быть возвращены, если semVerLevel значение ниже 2.0.0.

Внедренные файлы

Файлы значков, лицензий и readme могут быть встроены в пакет, и это рекомендуется. Эти файлы нуждаются в конечной точке URL-адреса: либо извлеченной и размещенной на статическом файловом сервере, либо URL-адреса, который динамически извлекает файлы из .nupkg по запросу, чтобы их можно было просматривать без загрузки всего nupkg. Если репозиторий пакетов предоставляет сведения о пакете и просмотр сведений о пакете, вы можете использовать URL-адреса, чтобы показать клиентам внедренное содержимое на веб-сайте.

Наконец, ресурс метаданных пакета и ресурс поиска должны содержать размещенный URL-адрес в свойствах iconUrl, licenseUrl, и/или readmeUrl ответа JSON. Пакеты (.nupkg файлы) не должны подвергаться изменению, так как клиентские компоненты (файлы блокировки и подписанные пакеты) будут расценивать эти изменения как вмешательство в пакет.

Обратите внимание, что лицензия может быть выражением SPDX или внедренным файлом (но не обоими). Пакеты, использующие выражение лицензии, когда они представлены в результатах поиска и метаданных пакета, могут иметь licenseUrl, установленное на выражение лицензии, закодированное в формате URL и добавленное в конец https://licenses.nuget.org/. Например: https://licenses.nuget.org/Apache-2.0. Команда сервера NuGet.org предоставляет дополнительную документацию на licenses.nuget.org.

Известные данные об уязвимостях и устаревших данных

Ресурс метаданных пакета (RegistrationsBaseUrl)

Ресурс метаданных пакета может содержать сведения об устаревании и уязвимостях. Это позволяет клиентам просматривать пакеты в пользовательском интерфейсе диспетчера пакетов Visual Studio или эквивалентном в других средах разработки, получать уведомления о важных проблемах безопасности или обслуживания.

Если ваш репозиторий пакетов заимствует пакеты из другого репозитория для их зеркального отображения в собственном потоке, мы рекомендуем периодически проверять исходный источник на наличие устаревших данных или данных об уязвимостях и дублировать эти метаданные в вашем собственном репозитории. Если репозиторий пакетов получает данные из nuget.org, сохраняя текущее состояние последней проверки (в виде "курсора"), вы можете использовать ресурсCatalog, чтобы эффективно проверять наличие обновлений для пакетов, которые вы зеркалируете, не загружая большое количество JSON-файлов метаданных из вышестоящего потока. Существует руководство по использованию ресурса каталога с примером кода, который поможет вам приступить к работе.

База данных известных уязвимостей (VulnerabilityInfo)

Чтобы обеспечить высокопроизводительную проверку уязвимостей во время восстановления пакета, NuGet скачивает полный список известных уязвимостей из VulnerabilityInfo ресурса. Nuget.org предоставляет данные об уязвимостях для всех проверенных рекомендаций из базы данных GitHub Advisories, которая включает пакеты, не хранящиеся на nuget.org.

Если ваш репозиторий пакетов размещает собственные пакеты, и вы хотите предоставить информацию об уязвимостях клиентам, используя свой собственный канал распространения пакетов, но у вас еще нет раскрытых уязвимостей пакетов, вам следует предоставить индекс уязвимостей с одной или несколькими страницами уязвимостей, содержимое которых представляет собой пустой массив JSON ([]).

Если репозиторий пакетов предназначен для использования приложениями в качестве репозитория по умолчанию (вместо nuget.org), можно использовать данные об уязвимостях nuget.org. Один из вариантов — использовать URL-адрес индекса уязвимостей nuget.org в индексе службы. Другой вариант — периодически проверять индекс nuget.org VulnerabilityInfo и скачивать все измененные страницы для отображения локально.

packageTypes поисковый запрос

Интерфейс командной dotnet tool search строки .NET позволяет выполнять поиск пакетов инструментов .NET с помощью команды. Это реализуется добавлением &packageTypes={value} параметра к ресурсу поискового запроса, который считывает значения из поля <packageTypes> файла .nuspec пакета.

Структура URL-адресов для проверенных веб-каналов

Как описано в обзоре API NuGet, начальный URL-адрес для всех подключений к серверу NuGet является индексом службы. Этот документ содержит URL-адреса для всех остальных ресурсов, которые клиенты NuGet запрашивают. Начиная с NuGet 6.7 (Visual Studio и MSBuild 17.7 и пакета SDK для .NET 7.0.400), NuGet использует .NET, который избегает анонимных HTTP-запросов, если последующие URL-адреса находятся в том же виртуальном каталоге или подкаталоге URL-адреса, который ранее прошел проверку подлинности. Это значительно уменьшит количество неавторизованных HTTP-запросов, отправленных на сервер, и, следовательно, уменьшит рабочую нагрузку сервера.

Ниже приведены некоторые примеры.

URL-адрес Будет ли предварительная аутентификация?
https://pkgs.contoso.com/nuget/v3/feed/index.json N/A— это индекс службы.
https://pkgs.contoso.com/nuget/v3/search Нет, не в том же или вложенном каталоге, как индекс службы.
https://search.pkgs.contoso.com/nuget/v3/feed/ Нет, не на том же имени узла, что и индекс услуги.
https://pkgs.contoso.com/nuget/v3/feed/search Да, в том же каталоге, что и индекс службы.
https://pkgs.contoso.com/nuget/v3/registration/ Нет, не в подкаталоге индекса службы.
https://pkgs.contoso.com/nuget/v3/feed/registration/ Да, в подкаталоге индекса службы.
https://pkgs.contoso.com/nuget/v3/{guid}/registration/ См. ниже

В последнем примере сервер может иметь каноническое (в этом примере guid) имя и иметь один или несколько псевдонимов. Если запрос индекса службы был аутентифицирован на неканоническом URL-адресе (понятное имя, в нашем примере feed), то нет, никакие запросы к ресурсам по каноническому URL-адресу не будут соответствовать правилам HttpClientHandler для PreAuthenticate. Однако если не канонический URL-адрес является перенаправлением HTTP на канонический URL-адрес, https://pkgs.contoso.com/nuget/v3/{guid}/index.jsonэтот URL-адрес будет использоваться в HttpClientHandlerкэше учетных данных. В этом случае каждый запрос к индексу службы будет иметь дополнительную задержку из-за перенаправления.

Хотя API NuGet версии 3 был разработан для работы на статичном файловом сервере, ресурс поиска является исключением, которое всегда требует динамической веб-службы для обработки запросов. Если вы хотите разместить поиск, а также любой другой ресурс API NuGet на разных серверах, чтобы воспользоваться преимуществами HttpClientHandler и PreAuthenticate, необходимо использовать обратный прокси-сервер, чтобы убедиться, что все клиентские URL-адреса в индексе службы удовлетворяют правилу "тот же или подкаталог".

Включить загрузку встроенных файлов README

Новый ресурс был задокументирован для создания URL-адреса, который можно использовать для скачивания README для данного пакета. Это позволит клиенту, например пользовательскому интерфейсу управления пакетами в VS, отобразить внедренный README для пакетов, которые ранее не были установлены пользователем. Клиент создаст этот URL-адрес и попытается скачать README, используя ответ на запрос, чтобы определить, доступен ли README. Это означает, что серверы должны ожидать несколько запросов к созданной конечной точке, так как пользователи перемещаются по пользовательскому интерфейсу PM.