Proxy-репозиторий — кеширующее зеркало внешнего реестра: клиенты всегда обращаются к Galleon, а Galleon по мере необходимости скачивает артефакты из внешнего реестра и сохраняет их локально.
Как обрабатывается запрос
Запрос к proxy-репозиторию обрабатывается так:
- артефакт есть в кеше и срок его хранения не истёк — Galleon отдаёт его из кеша, внешний реестр не участвует;
- срок истёк — Galleon спрашивает внешний реестр, изменился ли артефакт. Не изменился — клиент получает копию из кеша, а срок хранения отсчитывается заново; изменился — Galleon скачивает новую версию, заменяет ею кеш и отдаёт клиенту;
- артефакта в кеше нет — Galleon скачивает его из внешнего реестра, сохраняет и отдаёт клиенту.
Если внешний реестр недоступен
Пока в кеше есть копия, клиенты её получают — даже если срок хранения истёк и проверить актуальность не удалось. Ошибкой завершаются только запросы к тому, чего в кеше нет.
Если сбои повторяются, а в настройках репозитория включена автоматическая блокировка, Galleon перестаёт обращаться к реестру и периодически проверяет, не восстановился ли он; всё это время кеш продолжает отдаваться. Обращения можно приостановить и вручную — тогда репозиторий работает только на кеше.
Текущее состояние связи видно в колонке «Источник» списка репозиториев; значения этой колонки описаны в разделе Репозитории руководства администратора.
Сроки хранения
Кеш различает два вида данных:
- Контент — сами артефакты: архивы пакетов, слои образов. Содержимое таких файлов для конкретной версии обычно не меняется.
- Метаданные — списки версий, индексы и дескрипторы пакетов, которые внешний реестр обновляет по мере выхода новых версий.
Сроки задаются в настройках репозитория двумя параметрами:
contentMaxAge — для контента, metadataMaxAge — для метаданных.
Оба принимают три вида значений:
- Положительное число — срок хранения в минутах. По умолчанию 1440, то есть сутки: в течение этого времени запросы обслуживаются из кеша, после — Galleon проверяет у внешнего реестра, не изменился ли артефакт.
0— проверять внешний реестр при каждом запросе. Содержимое берётся из кеша, если реестр отвечает «не изменилось», но каждый запрос ждёт ответа внешнего реестра.-1— кешировать бессрочно, к внешнему реестру больше не обращаться. Подходит для неизменяемого содержимого и для закрытого контура.
Какие файлы к какому классу относятся:
| Формат | Метаданные (metadataMaxAge) | Контент (contentMaxAge) |
|---|---|---|
| Docker (OCI) | Теги: какой образ стоит за тегом, список тегов | — (манифесты и слои неизменяемы, объяснение ниже) |
| Maven | maven-metadata.xml и его контрольные суммы | Артефакты сборки (.jar, .pom) и их контрольные суммы |
| Go | Список версий и запрос последней версии | — (файлы версий неизменяемы, объяснение ниже) |
| npm | Дескриптор пакета | Архивы версий |
| PyPI | Страница проекта в индексе | Файлы дистрибутивов |
| RubyGems | Индексы Compact Index (списки версий и имён) | Файлы гемов |
| Cargo | Индекс крейта | Файлы крейтов |
| raw | — | Все файлы |
Файлы, которые запрашиваются по контрольной сумме, кешируются бессрочно
независимо от обеих настроек: их содержимое не может измениться.
Это файлы версий Go-модулей, слои и манифесты образов контейнеров.
Для образов срок metadataMaxAge задаёт, как часто Galleon проверяет
у внешнего реестра, не указывает ли тег на другой образ.
У Maven-репозиториев с политикой версий RELEASE контент по умолчанию кешируется бессрочно: релизные версии не переиздаются.
По истечении срока артефакт не удаляется из кеша: Galleon лишь проверяет его актуальность при следующем запросе. Вытеснить закешированное можно политикой очистки — она удаляет компоненты по возрасту, давности скачивания и пути (Политики очистки).
Сбросить кеш можно и не дожидаясь истечения сроков — кнопкой «Сбросить кеш»
в настройках любого proxy-репозитория.
Содержимое при этом не удаляется, а помечается устаревшим:
каждый следующий запрос сначала сверяется с внешним реестром и только потом отдаётся.
Заодно очищается кеш отказов.
Пометка действует при любом сроке хранения, включая -1;
содержимое, запрошенное по контрольной сумме, она не затрагивает.
Кеширование отказов
Ответы «не найдено» от внешнего реестра тоже кешируются — по умолчанию на 15 минут. Это защищает внешний реестр от потока повторных запросов к несуществующим путям.
Если пакет только что опубликован во внешнем реестре, а Galleon отвечает, что его нет, вероятно, действует кеш отказов: он истекает сам, по умолчанию через 15 минут, а сбросить его сразу можно кнопкой «Сбросить кеш» в настройках репозитория.
Обращения к внешнему реестру
Временные ошибки внешнего реестра (перегрузка, сетевые сбои) обрабатываются повторными попытками с нарастающей задержкой; число попыток задаётся в настройках репозитория.
Если внешний реестр требует аутентификации, например приватный реестр контейнеров, учётные данные задаются там же, в настройках proxy-репозитория.