Справочник конфигурации
Параметры конфигурации, значения по умолчанию, аутентификация и безопасное перечитывание.
Конфигурация записывается в YAML. Неизвестные ключи отклоняются: опечатка вызывает ошибку при запуске, а не игнорируется. Файл можно редактировать вручную или через CLI, который проверяет каждое изменение перед сохранением.
Длительности задаются в синтаксисе Go: 500ms, 5s, 1m30s.
Дополнительная конфигурация config.d и объединение
Используйте config.d/ для дополнительных файлов конфигурации (drop-in), чтобы не хранить все настройки в основном файле. При использовании config.yaml служба также загружает видимые файлы *.yaml и *.yml непосредственно из соседнего каталога config.d/. Имя каталога образуется из имени основного файла без расширения с добавлением .d: --config /path/proxy.yml использует /path/proxy.d/. Основной файл обязателен; дополнительный каталог — нет.
Сначала загружается основной файл, затем дополнительные файлы в лексикографическом порядке имён. Исключение — local-overrides.yaml, зарезервированный для переопределения существующих URL и загружаемый последним. Скрытые, временные и резервные файлы, а также подкаталоги игнорируются.
Отображения объединяются рекурсивно; более поздние явно заданные значения заменяют ранние, включая false. Значения по умолчанию применяются после объединения. Источники объединяются по нормализованному URL внутри каждого реестра: первое появление определяет позицию, последующие явно заданные параметры переопределяют настройки того же URL. upstreams: [] не очищает ранее заданные источники. Регистр схемы и хоста, порты по умолчанию и корневой слеш нормализуются; значимые пути остаются различными. Идентификатор источника не требуется.
Повторяющиеся ключи, несколько документов YAML, псевдонимы и ключи объединения YAML, неизвестные поля и неподдерживаемые явно заданные версии отклоняются. Ошибка в любом файле конфигурации отклоняет всё обновление; работающая конфигурация сохраняется.
local-overrides.yaml меняет только URL, предоставленные другими источниками, поэтому локальное отключение сохраняется после обновлений, не возвращая URL, удалённые из всех источников. Файлы подписок и резервные копии описаны в разделе удалённых каталогов.
Верхний уровень
| Ключ | По умолчанию | Описание |
|---|---|---|
version | 1 | Версия схемы. Допускается только 1. |
log_level | info | Необязательный уровень журнала: debug, info, warn или error. Поддерживает перечитывание; явный serve --log-level имеет приоритет. По умолчанию не записывается в создаваемую конфигурацию. |
listen | 127.0.0.1:24817 | Адрес прослушивания API реестра. |
advertise | вычисляется | host:port, по которому dockerd подключается к прокси. На практике необходим, если listen содержит wildcard-адрес. Должен указывать конкретный хост. |
admin.socket | пользовательский путь | Путь сокета управления. По умолчанию $XDG_RUNTIME_DIR/oci-mirror-proxy/admin.sock, а при отсутствии XDG_RUNTIME_DIR — каталог кеша пользователя. |
registries | docker.io | Отображение псевдонимов реестров в их настройки. |
Если указан advertise, dockerd подключается к нему. Иначе используется listen, причём wildcard-хосты (0.0.0.0, ::) заменяются на 127.0.0.1.
Для отладки добавьте log_level: debug на верхнем уровне и выполните oci-mirror-proxy reload. Отладочные записи связывают запросы по request_id и содержат стратегию маршрутизации, кандидатов, задержку и статус попыток, пропуски из-за circuit breaker, запуск дублирующих запросов и выбранный источник. upstream — прежняя метка, если она задана, иначе URL; via — настроенный базовый URL. upstream hit означает успешный ответ, а upstream selected указывает фактического победителя: другие успешные ответы гонки могут быть отброшены. Это не показатель попадания во внутренний кеш зеркала. Задержка измеряется до получения заголовков, а не завершения передачи blob. Попытки возобновления содержат range. Отладочные записи попыток не включают заголовки аутентификации и подписанные URL перенаправлений.
Реестры
Каждый ключ в registries — псевдоним реестра:
docker.ioобслуживается по корневому пути/v2/, который использует dockerd.- Другие псевдонимы, например
ghcr.io, обслуживаются с префиксом/ghcr.io/v2/. Псевдоним должен быть именем хоста без порта.v2зарезервирован.
| Ключ | По умолчанию | Описание |
|---|---|---|
origin | https://registry-1.docker.io для docker.io, иначе https://<alias> | Официальный адрес. dockerd обращается к нему, если прокси не может обслужить запрос. |
race.enabled | true | Включить дублирующие запросы с задержкой для реестра. |
race.delay | 500ms | При включённой гонке запустить следующий источник, если ответ не получен за это время. Значение должно быть положительным. |
race.max_parallel | 3 | Максимальное число одновременных попыток на запрос. При включённой гонке — не менее 2. |
breaker.threshold | 3 | Число последовательных сбоев перед исключением источника. |
breaker.cooldown | 30s | Сколько ждать после исключения источника до одной пробной попытки. |
upstreams | [] | Упорядоченный список источников. Ранние записи проверяются первыми. |
Гонка создаёт дополнительные запросы к источникам. Docker Hub ограничивает частоту загрузок, поэтому по умолчанию число параллельных попыток ограничено тремя. Для отключения задайте race.enabled: false.
Источники
| Ключ | По умолчанию | Описание |
|---|---|---|
id | не задан | Необязательная устаревшая метка, уникальная внутри реестра. От 1 до 63 букв, цифр, - или _. Источник определяется URL; новым конфигурациям ID не нужен. |
url | обязателен | Базовый URL Registry v2. http или https, без строки запроса, фрагмента и учётных данных. Допускается базовый путь, например /hub. |
disabled | false | Сохранить источник в файле, но исключить из обработки запросов. |
timeouts.connect | 10s | Лимит, применяемый отдельно к установке TCP-соединения и TLS-рукопожатию. Увеличьте для медленных соединений или работы через прокси. |
timeouts.first_byte | 5s | Максимальное ожидание заголовков ответа. Определяет задержку при неотвечающем источнике. |
timeouts.overall | 60s | Общий предел для запросов метаданных: манифестов, списков тегов и referrers. Не ограничивает передачу blob. |
auth.type | none | none, basic или token. См. ниже. |
auth.username | Имя пользователя для basic или для token, если его требует сервис токенов. | |
auth.password | Ссылка на секрет, например env:MIRROR_PASSWORD или file:/run/secrets/mirror. Пароли напрямую не допускаются. | |
tls.ca_file | Дополнительный файл CA-сертификатов источника. Добавляется к системным корневым сертификатам. | |
tls.insecure_skip_verify | false | Отключить проверку сертификата для источника. Избегайте этого вне тестов. |
Типы аутентификации
none: запросы отправляются без учётных данных.basic:usernameиpasswordпередаются с каждым запросом через HTTP Basic.token: источник отвечает запросом аутентификацииWWW-Authenticate: Bearer. Прокси получает токен из указанного realm, кеширует его для соответствующего scope до момента незадолго до истечения срока и повторяет запрос один раз. Указывайтеusernameиpasswordтолько если этого требует сервис токенов.
Учётные данные ограничены своим источником и никогда не отправляются другому. Собственный заголовок клиента Authorization не пересылается.
Ссылки на секреты
password принимает ссылку, а не значение:
| Ссылка | Результат |
|---|---|
env:NAME | Значение переменной окружения NAME. Она должна быть задана и не пуста. |
file:/path | Содержимое файла без завершающих переводов строки. |
Ссылки разрешаются при создании источника, поэтому отсутствие переменной обнаруживается при запуске или перечитывании конфигурации, а не при первом запросе.
Влияние тайм-аутов по умолчанию
Если гонка отключена, источник, который установил соединение, но не отправляет заголовки ответа, может добавлять около 5 секунд к каждому запросу до срабатывания circuit breaker. После трёх таких сбоев источник исключается на 30 секунд, затем допускается одна пробная попытка. Установка TCP-соединения и TLS-рукопожатие ограничены 10 секундами каждое. Гонка включена по умолчанию: без пригодного ответа через 500 миллисекунд запускается следующий кандидат, поэтому ждать полного тайм-аута первого не нужно. Общая задержка всё ещё зависит от остальных кандидатов.
Изменение конфигурации
- Через CLI или API управления: изменения проверяются, сохраняются и применяются без перезапуска. При ошибке проверки файлы и работающая конфигурация не меняются. Новые источники записываются в основной файл; включение и отключение — в
local-overrides.yaml. - Вручную: отредактируйте файл и выполните
oci-mirror-proxy reloadлибо отправьте процессуSIGHUP. Некорректный файл отклоняется; прежняя конфигурация продолжает работать. - Адрес прослушивания: изменение
listenзаписывается в журнал и вступает в силу после перезапуска. - Текущие передачи: перечитывание не прерывает существующие HTTP-запросы и не меняет их кандидатов для возобновления. Последующие HTTP-запросы, в том числе в рамках того же
docker pull, используют новую конфигурацию.
Адаптивное переключение blob включено по умолчанию (окно 10 с, минимум 262144 байт/с, тайм-аут проверки 5 с, 3 раунда проверки). Для отключения задайте adaptive.enabled: false. Прерванные загрузки blob возобновляются автоматически. Эти возможности не разбивают blob на параллельные части и не меняют число одновременных загрузок слоёв Docker.