Протокол pull/push реестра: манифесты, блобы и контент-адресуемая дистрибуция

Два вида объектов, одно адресное пространство

Прежде чем отлаживать сбой pull или рассуждать о сборке мусора, нужна ментальная модель того, что реестр реально хранит — потому что это не то, что подсказывает слово «реестр». Всё в реестре — одно из двух: манифест (маленький JSON, описывающий образ — его config плюс упорядоченный список слоёв) или блоб (непрозрачный контент-адресуемый объект: tar-слой или config JSON). Оба живут под /v2/ API, единым неймспейс-деревом OCI distribution spec:

GET /v2/<name>/manifests/<reference>   # reference = тег (v2.4.1) ИЛИ дайджест (sha256:ab…)
GET /v2/<name>/blobs/<digest>          # дайджест ВСЕГДА sha256:<hex>, никогда не тег
HEAD /v2/<name>/blobs/<digest>         # этот слой уже есть здесь? (перед push)

Это разделение и есть весь дизайн. Адрес блоба — его содержимое: sha256:9b2a… и есть SHA-256 байтов, поэтому блоб неизменяем по определению — измени один байт, и это другой объект с другим именем. Reference манифеста может быть тегом, а тег — лишь изменяемый указатель, который реестр хранит в индексе. Так что myrepo:latest и myrepo@sha256:9b2a… категорически разные: дайджест навсегда называет точный бит-в-бит образ; тег называет “то, что было запушено под этой меткой последним”. Когда тянешь тег, клиент делает GET .../manifests/v2.4.1, читает возвращённый Content-Type, чтобы узнать media type манифеста (например, application/vnd.oci.image.manifest.v1+json для одноархитектурного образа или ...image.index.v1+json для multi-arch индекса, перечисляющего per-platform манифесты), затем тянет блоб config и каждый блоб layers[].digest — дедуплицируя любой слой, уже имеющийся в локальном хранилище.

Push: блобы первыми, манифест последним

В каком порядке клиент загружает вещи при push? Если перепутать, реестр отклонит манифест — и понимание правильного порядка объясняет, как работают cross-repo mount (монтирование блоба между репозиториями) и возобновляемая чанковая загрузка. Push — зеркало pull, и порядок несущий. Нельзя PUT-нуть манифест, ссылающийся на блоб, которого у реестра ещё нет, поэтому клиент грузит блобы первыми, манифест последним:

POST /v2/<name>/blobs/uploads/          # начать загрузку, получить session URL (Location:)
PATCH <session-url>                      # чанк: послать диапазон байтов, повторить
PUT <session-url>?digest=sha256:<hex>    # финал: реестр проверяет, что байты хешатся в <digest>
PUT /v2/<name>/manifests/<tag>           # только когда все ссылаемые блобы на месте

Здесь живут две senior-оптимизации. Cross-repository blob mount: перед загрузкой слоя клиент делает HEAD; если реестр уже держит этот sha256: (в любом репо, доступном креденшелу), клиент шлёт POST .../blobs/uploads/?mount=<digest>&from=<other-repo>, и слой линкуется без передачи единого байта — причина, по которой push нового тега приложения с общим базовым образом двигает лишь изменённые слои, часто пару МБ вместо сотен. Chunked vs monolithic: мелкие блобы идут одним PUT с inline-телом; большие стримятся PATCH-диапазонами, чтобы оборванное соединение возобновилось с последнего подтверждённого офсета, а не перезапускало 400-МБ слой. Финализирующий PUT ...?digest= — место, где реестр проверяет: пересчитывает хеш и отклоняет загрузку с 400 DIGEST_INVALID, если байты не совпали, так что испорченная передача не закоммитится под валидным именем.

Почему протокол формирует операции

Три операционных факта прямо следуют из дизайна — и когда ты встречаешь эти проблемы в проде, понимание дизайнерского решения сразу показывает, где искать фикс. Первое: pull — это fan-out (веерный запрос): один GET манифеста порождает N+1 GET блобов (N слоёв плюс config), поэтому 12-слойный образ это ~13 запросов на узел, а раскатка на 200 узлов — тысячи GET блобов; ровно поэтому существуют pull-through кэши и rate limits (публичный реестр вроде Docker Hub ограничивает анонимные pull до 100 за 6 часов и аутентифицированные бесплатные до 200 за 6 часов, считая по pull манифеста, троттля раскатки флота, которые пере-тянут). Второе: сборка мусора — двухфазный mark-and-sweep (пометить используемое, смести остальное) по хранилищу блобов: она обходит каждый манифест, помечая ссылаемые дайджесты, затем удаляет непомеченные блобы — и push, гоняющийся с фазой mark, может оставить ссылаемый блоб непомеченным и сметённым, тот самый сбой из Hook. Запускай GC с реестром в read-only ради корректности. Третье: дайджесты — единственный безопасный deploy-reference: пиннинг Deployment на app@sha256:… значит, что байты не изменятся под тобой, тогда как app:latest можно пере-запушить на другой манифест между pull двух узлов, и одна раскатка прогонит два разных образа.