Удалённые каталоги зеркал

Подпишитесь на JSON-каталог, чтобы выбирать зеркала по региону и сохранять их в файлы каталога конфигурации config.d работающей службы. Перед подпиской запустите службу.

# При работающей службе прокси:
oci-mirror-proxy remote update --url https://ocimp.zmide.com/subscriptions/mirrors.json --region cn
oci-mirror-proxy remote list
oci-mirror-proxy remote update --url https://example.com/mirrors.json --region cn,apac
oci-mirror-proxy remote update --all --dry-run
oci-mirror-proxy remote update --all
oci-mirror-proxy remote remove --url https://example.com/mirrors.json

update добавляет источник при первом использовании. Команда выше использует опубликованный каталог:

https://ocimp.zmide.com/subscriptions/mirrors.json

Для выбора каталога используйте --url; без --url и --all выбирается встроенный каталог CLI по умолчанию. Опубликованный URL задаётся явно и не меняет значение по умолчанию в CLI.

Без --region выбираются все регионы каталога; с этим параметром применяется фильтр. Регионы — точные метки; несколько меток выбирают их объединение. global не включается автоматически. --all обновляет настроенные источники с их сохранённым выбором и не может сочетаться с --url или --region.

List/update/remove принимают --admin-socket для выбора службы. Update/remove поддерживают --dry-run и --no-reload. Пробный запуск показывает изменения без сохранения. Пустой выбор отклоняется, если явно не указан update --allow-empty. Для remove всегда нужен --url. Фонового обновления нет.

Просмотр каталогаКопировать ссылку на заголовок

remote list показывает источники, настроенные в выбранной службе. Используйте remote show, чтобы скачать каталог и просмотреть зеркала без подписки и создания локальных файлов:

oci-mirror-proxy remote show
oci-mirror-proxy remote show --url https://example.com/mirrors.json
oci-mirror-proxy remote show --url https://example.com/mirrors.json --region cn,apac

Без --url используется встроенный каталог по умолчанию. Для каждого адреса выводится строка с именем зеркала, полным набором региональных меток, реестром, URL адреса и сайтом (-, если сайта нет). Сохраняется порядок зеркал и адресов в каталоге; одинаковые адреса разных зеркал остаются видимыми. Строки запроса URL сайтов скрываются.

Без --region или с пустым значением показываются все зеркала. Несколько регионов выбирают объединение; для подходящего зеркала выводятся все его адреса. Неизвестные региональные метки вызывают ошибку со списком допустимых меток. При пустом результате выводится no matching mirrors, и команда завершается успешно.

show принимает только --url, --region и параметры справки. Ей не нужны локальная конфигурация или работающий прокси; она не записывает конфигурацию и не перечитывает её в службе. Команда показывает содержимое каталога, а не локальное включение или состояние адресов; к зеркалам и сайтам запросы не выполняются. Правила загрузки и проверки каталога совпадают с правилами обновления.

Файлы, атомарная замена и резервные копииКопировать ссылку на заголовок

При основном файле /etc/oci-mirror-proxy/config.yaml каждому источнику принадлежит файл в config.d/:

config.d/example.com@0123456789abcdef.yaml
config.d/example.com@0123456789abcdef.yaml.bak

Каждый источник имеет отдельный файл, даже если два URL используют один хост. Сохраняйте заголовочные комментарии с URL источника и регионами: по ним CLI распознаёт подписку.

Защищайте эти файлы, если URL содержит частный токен в строке запроса. CLI скрывает строки запроса; создаваемые файлы и резервные копии имеют права 0600.

Файлы сохраняются атомарно; перечитывание проверяет полную конфигурацию перед применением. Некорректные сохранённые файлы можно исправить или удалить через CLI. Предыдущий файл резервируется как .yaml.bak; при сбое резервирования текущий файл не меняется. При первом создании предыдущей копии нет; обновление без изменений не перезаписывает ни текущий файл, ни копию. Удаление источника также создаёт резервную копию. Резервные копии не загружаются как конфигурация. Для ручного восстановления скопируйте .bak в исходный путь .yaml и выполните reload.

При --all успешные обновления сохраняются, даже если другой источник завершился с ошибкой; любой сбой даёт код выхода 1. После обработки источников выполняется попытка перечитывания. Для файловых операций служба должна работать. --no-reload сохраняет без применения; файлы вступят в силу после успешного перечитывания или перезапуска. Если перечитывание отклонено или истёк тайм-аут, CLI сообщает, что файлы сохранены, но применение во время работы не подтверждено, и возвращает 1. Файлы сохраняются; выполните oci-mirror-proxy reload или повторите обновление для новой попытки.

Перечитывание не прерывает текущие HTTP-передачи и не меняет кандидатов для их возобновления. Последующие HTTP-запросы, в том числе в рамках того же docker pull, используют новую конфигурацию.

Локальные настройкиКопировать ссылку на заголовок

Источники объединяются по нормализованному URL внутри каждого реестра. Удаление одного удалённого каталога не удаляет адрес, всё ещё предоставляемый другим источником. См. объединение конфигурации.

oci-mirror-proxy upstream disable --url https://docker.example.com
oci-mirror-proxy upstream enable --url https://docker.example.com

Эти настройки сохраняются в config.d/local-overrides.yaml, загружаемом последним и применяемом только к существующим URL. Они переживают обновления, не возвращая URL, последний источник которых исчез. Здесь же можно задать собственные параметры тайм-аутов, аутентификации и TLS. Не редактируйте поля сгенерированного источника: следующее обновление заменит их. upstream remove --url удаляет текущие определения, но обновление каталога может вернуть URL; для устойчивого локального выбора отключите его.

Формат каталога и довериеКопировать ссылку на заголовок

Опубликованные каталог и JSON Schema определяют версию 1. У зеркал есть отображаемое имя, несколько региональных меток и явно заданные URL для каждого реестра. ID зеркала не нужен. Неизвестные поля, повторяющиеся JSON-ключи, неподдерживаемые версии, некорректные регионы и URL отклоняются. Создаваемые адреса используют анонимный auth: {type: token} для поддержки Bearer-аутентификации без секретов.

Загрузка имеет тайм-аут 30 секунд, предел декодированного тела 4 МиБ и ограниченное число перенаправлений. HTTPS-сертификаты проверяются; перенаправления HTTPS→HTTP запрещены. Явно заданный HTTP-источник вызывает предупреждение. Поддерживаются стандартные переменные окружения прокси. Каталоги не могут задавать учётные данные, локальные пути, обход TLS или глобальные настройки прокси.

Каталог — источник данных, которому вы доверяете: проверка дайджеста защищает адресуемое содержимое, но не подлинность и актуальность разрешения изменяемых тегов. Региональные метки не гарантируют доступность. Перед использованием публичного зеркала изучите подробности каталога, ограничения провайдера и доступность из вашей сети.