Эксплуатация
Команды, интеграция с Docker, управление службами и устранение неполадок.
Команды
Просмотрите удалённый каталог без подписки командой remote show [--url U] [--region cn]. Управление каталогами зеркал: remote list, remote update [--url U] --region cn, remote update --all и remote remove --url U. Обновление и удаление поддерживают --dry-run и резервирование предыдущего результата; см. удалённые каталоги. Источники можно добавлять без --id; enable/disable/remove принимают --url вместо устаревшей метки. Перечитывание не прерывает текущие HTTP-передачи.
| Команда | Назначение |
|---|---|
init [--config F] [--force] | Создать конфигурацию по умолчанию. |
serve [--config F] [--admin-socket S] [--log-level L] | Запустить прокси на переднем плане. |
status [--admin-socket S] | Показать состояние circuit breaker, число запросов и сбоев и последнюю задержку каждого источника. |
reload [--admin-socket S] | Перечитать конфигурацию работающего прокси. |
upstream list [--registry R] | Список источников. |
upstream add --url U [--id I --registry R --auth T --username N --password-ref REF --first-byte D --overall D --ca-file F --insecure-skip-verify --disabled] | Добавить источник; устаревшая метка ID необязательна. |
upstream enable|disable|remove --url U [--registry R] | Изменить источник; вместо --url U можно использовать --id I. |
server info [--admin-socket S] [--json] | Показать версии клиента и сервера и сведения службы без секретов. |
dockerd plan [flags] | Показать файлы, которые запишет apply. Ничего не записывает. |
dockerd apply [flags] [--no-reload] | Объединить настройки Docker. В Linux при необходимости отправить сигнал dockerd; перезапускать Docker Desktop только с --restart. |
dockerd revert [flags] [--no-reload] | Удалить выбранный прокси из текущей конфигурации. |
doctor [flags] | Проверки без изменений: доступность прокси и dockerd, наличие конфигурации. Код выхода 1 при любой ошибке. |
version, help | Версия и справка. |
Коды выхода: 0 — успех, 1 — ошибка выполнения, 2 — ошибка использования.
Клиентским командам нужна работающая служба; конфигурацию они получают через её API управления. Нестандартный адрес выбирается через --admin-socket. serve и init поддерживают выбор файла конфигурации. Команды интеграции с Docker также принимают --server-info F, чтобы читать экспортированный снимок server info --json без подключения к API управления; см. развёртывание в контейнере. Устаревший параметр --config для клиентских команд игнорируется.
Частный API управления также поддерживает GET /v1/config/fragments и GET, PUT, DELETE /v1/config/fragments/{name} только для YAML-файлов непосредственно в каталоге дополнительной конфигурации config.d службы. Ответ файла содержит name, data в base64 и ревизию содержимого revision; список не содержит содержимого файлов. Для записи нужны JSON-поля revision (пустое при создании) и data в base64; для удаления — revision. Устаревшая ревизия возвращает 412. Предел файла — 1 МиБ. Сохранение не вызывает перечитывание; для применения используйте POST /v1/reload.
Параметры dockerd
| Параметр | По умолчанию (системная установка) | По умолчанию (rootless) |
|---|---|---|
--store auto|containerd|legacy | auto | auto |
--rootless | выключен | включён: пользовательские пути |
--certs-dir | /etc/docker/certs.d | $XDG_CONFIG_HOME/docker/certs.d |
--daemon-json | /etc/docker/daemon.json | $XDG_CONFIG_HOME/docker/daemon.json |
--docker-socket | /var/run/docker.sock | $XDG_RUNTIME_DIR/docker.sock |
--pid-file | /var/run/docker.pid | $XDG_RUNTIME_DIR/docker.pid |
--store auto запрашивает у работающего dockerd используемое хранилище образов. Если dockerd не запущен, задайте --store containerd или --store legacy.
Настройка dockerd
Windows и Docker Desktop
Установщик Windows запускает прокси как автоматически запускаемую службу. Запросы состояния и локальный API управления доступны из обычного PowerShell; для изменения защищённых файлов службы и запуска/остановки служб Windows нужны повышенные права:
$proxy = "$env:ProgramFiles\oci-mirror-proxy\bin\oci-mirror-proxy.exe"
$config = "$env:ProgramData\oci-mirror-proxy\config.yaml"
Get-Service oci-mirror-proxy
& $proxy status --admin-socket '\\.\pipe\oci-mirror-proxy-admin'
& $proxy remote update --admin-socket '\\.\pipe\oci-mirror-proxy-admin' --region cn
# После редактирования config.yaml:
& $proxy reload --admin-socket '\\.\pipe\oci-mirror-proxy-admin'
# После изменения listen:
Restart-Service oci-mirror-proxy
# Остановить / запустить прокси:
Stop-Service oci-mirror-proxy
Start-Service oci-mirror-proxyКонфигурация службы находится в %ProgramData%\oci-mirror-proxy\config.yaml, журналы — в %ProgramData%\oci-mirror-proxy\logs. Для нестандартного имени службы замените в командах имя службы и канала. Для удаления запустите .\install.ps1 uninstall от пользователя Docker и подтвердите UAC. Перед остановкой службы установщик удаляет прокси из текущих настроек Docker; при сбое очистки установка сохраняется. -SkipDocker явно пропускает очистку. Docker не перезапускается; конфигурация и журналы сохраняются. Не останавливайте прокси до очистки: dockerd revert получает адрес из работающей службы.
Локальные пользователи могут как просматривать, так и менять системную службу через API управления. Частные экземпляры на переднем плане доступны только своей учётной записи; удалённые подключения к каналу отклоняются. Для применения изменённого ACL канала установите обновлённый исполняемый файл и один раз перезапустите службу.
Каждый запуск установщика Windows выводит путь постоянного журнала сеанса. Журналы пользовательского этапа находятся в %LOCALAPPDATA%\oci-mirror-proxy-installer\<run-id>\install.log; этапа с повышенными правами — в %ProgramData%\oci-mirror-proxy-installer\<run-id>\install.log и требуют прав администратора. Исходное окно выводит код завершения и путь журнала привилегированного этапа, даже если его окно закрылось. Индикатор загрузки скрыт; предупреждения внешних программ выводятся обычным текстом и сами по себе не означают сбой.
Системный исполняемый файл доступен и без повышения прав. Используйте полный путь $proxy выше либо откройте новый терминал и запускайте oci-mirror-proxy напрямую: установщик добавляет программу в PATH. Для собственной конфигурации выполняйте init и serve из обычного PowerShell; не указывайте --config системной службы или её канал управления. Если служба уже заняла порт 24817, перед запуском второго экземпляра измените listen и advertise в пользовательской конфигурации. Она хранится в %APPDATA%\oci-mirror-proxy\config.yaml. PowerShell администратора нужен только для администрирования службы.
Для автоматической интеграции с Docker Desktop выберите локальный контекст контейнеров Linux и не задавайте --store. dockerd plan/apply/revert объединяет %USERPROFILE%\.docker\daemon.json, сохраняет посторонние настройки и хранит резервные копии в %APPDATA%\oci-mirror-proxy\backups. Применение не перезапускает Docker без явного --restart; настройки также можно активировать через Docker Desktop. Удалённые движки, нестандартные DOCKER_HOST или DOCKER_CONFIG и движки Desktop с контейнерами Windows отклоняются при автоматическом изменении локальных файлов.
& $proxy dockerd plan
& $proxy dockerd apply
# Перезапустите Docker Desktop вручную или разрешите перезапуск через apply --restart.
& $proxy doctor
# Отменить изменение конфигурации:
& $proxy dockerd revertЯвные сценарии с --store без работающего движка используют пути в %ProgramData%\docker и требуют ручной активации. --rootless и --pid-file для движков Windows не поддерживаются.
Docker Engine в Linux
- Убедитесь, что прокси работает и доступен по адресу, который будет использовать dockerd. Это проверяет
doctor. - Выполните
dockerd planи изучите показанные файлы. Пока ничего не записывается. - Выполните
dockerd apply. Файлы записываются атомарно; существующие резервируются в каталоге приложения текущего пользователя, вbackups/. Конфигурация объединяется; запись об установке или владении не требуется. - Для классического хранилища при необходимости dockerd получает
SIGHUP. Хранилище containerd читаетhosts.tomlпри каждом разрешении, поэтому сигнал не нужен. - Выполните
doctor. Все проверки должны пройти.
Какие файлы записываются
Хранилище containerd: по одному файлу на реестр, <certs-dir>/<alias>/hosts.toml:
server = "https://registry-1.docker.io"
[host."http://127.0.0.1:24817"]
capabilities = ["pull", "resolve", "referrers"]containerd сначала пробует записи [host], затем server, поэтому официальный реестр остаётся резервным. Для реестра с префиксом, например ghcr.io, создаётся [host."http://127.0.0.1:24817/ghcr.io"].
Классическое хранилище: прокси добавляется первой записью registry-mirrors в daemon.json. Остальные записи остаются резервными, все прочие ключи сохраняются. Классическое хранилище поддерживает зеркала только для docker.io. plan, apply и doctor предупреждают о других реестрах и пропускают настройку их зеркал в dockerd; маршруты самого прокси не меняются. Настройка Docker Hub продолжается. Если поддерживаемых реестров нет, plan и apply завершаются успешно без записи файлов и отправки сигнала dockerd.
Резервные копии используют каталог приложения текущего пользователя (~/Library/Application Support/oci-mirror-proxy в macOS, $XDG_CONFIG_HOME/oci-mirror-proxy или ~/.config/oci-mirror-proxy в Linux и %APPDATA%\oci-mirror-proxy в Windows). Обновление установщиком выполняет такое же безопасное объединение, как первая настройка.
Отмена изменений
dockerd revert удаляет только записи выбранного прокси из текущих файлов, сохраняя остальные настройки и последующие изменения. Команда не восстанавливает исторический снимок и не удаляет каталоги конфигурации. Адрес прокси получается от выбранной работающей службы или из переданного снимка --server-info. При удалении из containerd также проверяются каталоги реестров, которых больше нет в подписках. Резервные копии предназначены для явного ручного восстановления, а не обнаружения конфигурации.
Перечитывание и перезапуск
| Изменение | Результат |
|---|---|
| Источники, гонка, circuit breaker, тайм-ауты, аутентификация (через CLI, API управления или файл + reload) | Применяется сразу. Неизменённые источники сохраняют состояние circuit breaker и счётчики. |
listen | Записывается в журнал; вступает в силу после перезапуска. |
Конфигурация Docker (dockerd apply) | Хранилище containerd в Linux: сразу для новых загрузок. Классическое хранилище в Linux: сигнал dockerd при необходимости. Docker Desktop: может потребоваться перезапуск; инструмент выполняет его только с --restart. |
Если проверка при перечитывании не прошла, прежняя конфигурация продолжает работать, а причина записывается в журнал.
Rootless dockerd
Прокси привязывается к адресу listen. Rootless dockerd работает в собственном сетевом пространстве имён, а RootlessKit по умолчанию блокирует подключения к loopback хоста (DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK, см. contrib/dockerd-rootless.sh в дереве moby). Проект не обходит это ограничение. Выберите вариант:
- Сохраните стандартное поведение, задайте в
advertiseадрес, доступный rootless dockerd, и убедитесь, чтоlistenпривязан к нему. - Задайте
DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK=falseв переопределении службы dockerd. Это открывает rootless dockerd доступ к loopback-службам хоста и требует осознанного принятия риска безопасности.
Стандартные rootless-пути: $XDG_CONFIG_HOME/docker/daemon.json и $XDG_RUNTIME_DIR/docker.pid. Если используются другие пути, задайте --daemon-json или --pid-file.
Журналы
Журналы выводятся в stderr в формате logfmt. Уровни:
DEBUG: каждый обслуженный запрос со статусом и длительностью.INFO: запуск, перечитывание конфигурации, завершение и отсутствие содержимого (content not found on any upstream). Это нормально: dockerd обращается к официальному реестру.WARN: сбои запросов, которые источники не смогли обслужить.ERROR: ошибки перечитывания и отката.
Устранение неполадок
| Симптом | Вероятная причина и действия |
|---|---|
dockerd не подключается к прокси | Выполните doctor. Проверьте advertise, адрес listen и межсетевой экран. Rootless dockerd по умолчанию не имеет доступа к loopback хоста. |
| Каждая загрузка задерживается примерно на 5 секунд | При отключённой гонке первым может проверяться источник, не отправляющий заголовки ответа. Проверьте status и race.enabled. После повторных сбоев circuit breaker временно пропускает источник; при необходимости уменьшите timeouts.first_byte или снова включите гонку. |
| Источник пропускается | Его circuit breaker разомкнут. status показывает состояние. Повторная проверка произойдёт через breaker.cooldown. |
| Загрузки переходят на Docker Hub | Прокси ответил 404 или 502. Проверьте status и строки WARN. Для отсутствующих образов резервный путь нормален. |
reload failed в журнале | Конфигурация не прошла проверку. Сообщение указывает причину. Работающая конфигурация не изменилась. |
secret ... not set or empty | Переменная окружения, на которую ссылается password, отсутствует в окружении прокси. |
cannot detect the image store | dockerd недоступен через --docker-socket. Запустите его или задайте --store. |