16.3. Build cache в CI

локально                          CI
─────────                         ──
/var/lib/docker сохраняется       машина создаётся заново
слои от прошлой сборки есть       слоёв нет
docker build → секунды            docker build → минуты

cache-from: type=registry,ref=ghcr.io/org/app:buildcache
cache-to: type=registry,ref=ghcr.io/org/app:buildcache,mode=max

FROM python:3.13-slim AS base
COPY requirements.txt .
RUN pip install -r requirements.txt      # ← дорогой слой

FROM base AS production
COPY src/ ./src/                          # ← дешёвый слой

RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

что экспортирует cache-to:     слои образа
что НЕ экспортирует:           содержимое --mount=type=cache

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # отдельный слой
COPY src/ ./src/                                      # меняется чаще

ветка feature/x  ──► своя область ──► видит: свою + область ветки по умолчанию
ветка main       ──► своя область ──► видит: только свою

- uses: docker/build-push-action@v6
  with:
    cache-to: type=gha,mode=max
    # публикация только на main, а сборка — на всех ветках

cache-from: |
  type=gha,scope=${{ github.ref_name }}
  type=gha,scope=main
cache-to: type=gha,mode=max,scope=${{ github.ref_name }}

mkdir -p /tmp/cache && cd /tmp/cache
mkdir -p src

cat > requirements.txt <<'EOF'
click==8.3.0
httpx==0.28.1
pydantic==2.12.4
EOF

cat > src/__init__.py <<'PY'
PY
cat > src/app.py <<'PY'
"""Приложение для измерения кэша сборки."""
from __future__ import annotations


def main() -> int:
    print("работает")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
PY

cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
WORKDIR /app
# Зависимости отдельным слоем: меняются реже кода
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

FROM base AS production
COPY src/ ./src/
ENTRYPOINT ["python", "-m", "src.app"]
EOF

now() { python3 -c 'import time; print(time.monotonic())'; }
took() { python3 -c "print(f'{$2 - $1:.1f}')"; }

echo "═══ холодная сборка (--no-cache) ═══"
t0="$(now)"
docker build -q --no-cache --target production -t cache:cold . > /dev/null
t1="$(now)"
cold="$(took "$t0" "$t1")"
printf '  время: %s с\n' "$cold"

echo "═══ тёплая сборка (локальный кэш) ═══"
t0="$(now)"
docker build -q --target production -t cache:warm . > /dev/null
t1="$(now)"
warm="$(took "$t0" "$t1")"
printf '  время: %s с\n' "$warm"

echo "═══ тёплая сборка после изменения КОДА ═══"
python3 -c "
from pathlib import Path
p = Path('src/app.py')
p.write_text(p.read_text().replace('работает', 'работает (изменено)'))
"
t0="$(now)"
docker build -q --target production -t cache:codechange . > /dev/null
t1="$(now)"
codechange="$(took "$t0" "$t1")"
printf '  время: %s с\n' "$codechange"

echo "═══ тёплая сборка после изменения ЗАВИСИМОСТЕЙ ═══"
echo "rich==14.2.0" >> requirements.txt
t0="$(now)"
docker build -q --target production -t cache:depchange . > /dev/null
t1="$(now)"
depchange="$(took "$t0" "$t1")"
printf '  время: %s с\n' "$depchange"

echo "═══ сводка ═══"
# Значения передаются через окружение: heredoc в кавычках,
# поэтому тело остаётся валидным Python и проверяется статически
COLD="$cold" WARM="$warm" CODE="$codechange" DEPS="$depchange" python3 - <<'PY'
import os

cold = float(os.environ["COLD"])
rows = [
    ("холодная (--no-cache)", cold),
    ("тёплая, ничего не менялось", float(os.environ["WARM"])),
    ("тёплая, изменился код", float(os.environ["CODE"])),
    ("тёплая, изменились зависимости", float(os.environ["DEPS"])),
]
print(f"  {'случай':<34} {'время':>8} {'от холодной':>13}")
print("  " + "─" * 58)
for name, secs in rows:
    print(f"  {name:<34} {secs:>6.1f} с {secs / cold * 100:>11.0f} %")
print()
print("  Изменение кода дёшево: слой с зависимостями взят из кэша.")
print("  Изменение зависимостей дорого: ломается ранний слой,")
print("  и всё, что после него, собирается заново.")
PY

# Возвращаем исходное состояние
git checkout requirements.txt 2>/dev/null || python3 -c "
from pathlib import Path
p = Path('requirements.txt')
p.write_text(''.join(l for l in p.read_text().splitlines(keepends=True)
                     if 'rich' not in l))
"
docker rmi -f cache:cold cache:warm cache:codechange cache:depchange > /dev/null 2>&1

═══ холодная сборка (--no-cache) ═══
  время: 24.3 с
═══ тёплая сборка (локальный кэш) ═══
  время: 0.4 с
═══ тёплая сборка после изменения КОДА ═══
  время: 0.9 с
═══ тёплая сборка после изменения ЗАВИСИМОСТЕЙ ═══
  время: 21.7 с
═══ сводка ═══
  случай                                время   от холодной
  ──────────────────────────────────────────────────────────
  холодная (--no-cache)                  24.3 с         100 %
  тёплая, ничего не менялось              0.4 с           2 %
  тёплая, изменился код                   0.9 с           4 %
  тёплая, изменились зависимости         21.7 с          89 %
  ...

cd /tmp/cache
echo "═══ поднимаем registry для кэша ═══"
docker run -d --name cachereg -p 5000:5000 registry:2 > /dev/null 2>&1
sleep 4
curl -s -o /dev/null -w '  registry: HTTP %{http_code}\n' http://localhost:5000/v2/

echo "═══ сборка с сохранением кэша в registry ═══"
docker buildx create --name cachebuilder --use --driver docker-container \
    --driver-opt network=host > /dev/null 2>&1 || docker buildx use cachebuilder

t0="$(now)"
docker buildx build --target production \
    --cache-to "type=registry,ref=localhost:5000/app:buildcache,mode=max" \
    --tag localhost:5000/app:1 \
    --load . > build1.log 2>&1
t1="$(now)"
printf '  первая сборка: %s с\n' "$(took "$t0" "$t1")"

echo "═══ имитация нового исполнителя: чистый сборщик ═══"
docker buildx rm cachebuilder > /dev/null 2>&1
docker buildx create --name cachebuilder2 --use --driver docker-container \
    --driver-opt network=host > /dev/null 2>&1

echo "═══ сборка на чистом сборщике БЕЗ внешнего кэша ═══"
t0="$(now)"
docker buildx build --target production \
    --tag localhost:5000/app:2 --load . > build2.log 2>&1
t1="$(now)"
nocache="$(took "$t0" "$t1")"
printf '  время: %s с\n' "$nocache"
printf '  строк CACHED: %s\n' "$(grep -c 'CACHED' build2.log || echo 0)"

echo "═══ сборка на чистом сборщике С внешним кэшем ═══"
docker buildx rm cachebuilder2 > /dev/null 2>&1
docker buildx create --name cachebuilder3 --use --driver docker-container \
    --driver-opt network=host > /dev/null 2>&1
t0="$(now)"
docker buildx build --target production \
    --cache-from "type=registry,ref=localhost:5000/app:buildcache" \
    --tag localhost:5000/app:3 --load . > build3.log 2>&1
t1="$(now)"
withcache="$(took "$t0" "$t1")"
printf '  время: %s с\n' "$withcache"
printf '  строк CACHED: %s\n' "$(grep -c 'CACHED' build3.log || echo 0)"

echo "═══ вывод ═══"
NOCACHE="$nocache" WITHCACHE="$withcache" python3 - <<'PY'
import os

nocache = float(os.environ["NOCACHE"])
withcache = float(os.environ["WITHCACHE"])
print(f"  без внешнего кэша: {nocache:.1f} с")
print(f"  с внешним кэшем:   {withcache:.1f} с")
if nocache > 0:
    print(f"  сокращение:        {(1 - withcache / nocache) * 100:.0f} %")
print()
print("  Чистый сборщик — это и есть модель нового исполнителя CI.")
print("  Локальный кэш там отсутствует всегда; помогает только внешний.")
PY

═══ поднимаем registry для кэша ═══
  registry: HTTP 200
═══ сборка с сохранением кэша в registry ═══
  первая сборка: 26.8 с
═══ имитация нового исполнителя: чистый сборщик ═══
═══ сборка на чистом сборщике БЕЗ внешнего кэша ═══
  время: 25.1 с
  строк CACHED: 0
═══ сборка на чистом сборщике С внешним кэшем ═══
  время: 4.2 с
  строк CACHED: 6
═══ вывод ═══
  без внешнего кэша: 25.1 с
  с внешним кэшем:   4.2 с
  сокращение:        83 %
  ...

cd /tmp/cache
fresh_builder() {
    docker buildx rm "$1" > /dev/null 2>&1
    docker buildx create --name "$1" --use --driver docker-container \
        --driver-opt network=host > /dev/null 2>&1
}

echo "═══ сохраняем кэш в режиме min ═══"
fresh_builder b-min
docker buildx build --target production \
    --cache-to "type=registry,ref=localhost:5000/app:cache-min,mode=min" \
    --tag localhost:5000/app:m1 --load . > /dev/null 2>&1

echo "═══ сохраняем кэш в режиме max ═══"
fresh_builder b-max
docker buildx build --target production \
    --cache-to "type=registry,ref=localhost:5000/app:cache-max,mode=max" \
    --tag localhost:5000/app:m2 --load . > /dev/null 2>&1

echo "═══ меняем КОД и собираем на чистых сборщиках ═══"
python3 -c "
from pathlib import Path
p = Path('src/app.py')
p.write_text(p.read_text().replace('работает', 'работает v2'))
"

for mode in min max; do
    fresh_builder "use-$mode"
    t0="$(now)"
    docker buildx build --target production \
        --cache-from "type=registry,ref=localhost:5000/app:cache-$mode" \
        --tag "localhost:5000/app:r-$mode" --load . > "use-$mode.log" 2>&1
    t1="$(now)"
    secs="$(took "$t0" "$t1")"
    cached="$(grep -c 'CACHED' "use-$mode.log" || echo 0)"
    pip_run="$(grep -c 'pip install' "use-$mode.log" || echo 0)"
    printf '  mode=%-4s время %6s с  CACHED %-3s  строк с pip install: %s\n' \
        "$mode" "$secs" "$cached" "$pip_run"
done

echo "═══ вывод ═══"
cat <<'TXT'
  mode=min экспортирует слои только КОНЕЧНОЙ стадии.
  Стадия base с установкой зависимостей в кэш не попадает —
  и при следующей сборке pip install выполняется заново.

  mode=max экспортирует слои ВСЕХ стадий, включая base.

  Для multi-stage сборок всегда mode=max. По умолчанию — min,
  и это самая частая причина «кэш настроен, а сборка медленная».

  Цена mode=max: кэш больше по размеру и дольше передаётся.
TXT

═══ сохраняем кэш в режиме min ═══
═══ сохраняем кэш в режиме max ═══
═══ меняем КОД и собираем на чистых сборщиках ═══
  mode=min  время   23.4 с  CACHED 1    строк с pip install: 3
  mode=max  время    3.8 с  CACHED 6    строк с pip install: 0
═══ вывод ═══
  mode=min экспортирует слои только КОНЕЧНОЙ стадии.
  Стадия base с установкой зависимостей в кэш не попадает —
  и при следующей сборке pip install выполняется заново.
  ...

cd /tmp/cache
cat > Dockerfile.mount <<'EOF'
# syntax=docker/dockerfile:1
FROM python:3.13-slim AS base
ENV PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt .
# Cache mount: ускоряет ЛОКАЛЬНЫЕ повторные сборки
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

FROM base AS production
COPY src/ ./src/
ENTRYPOINT ["python", "-m", "src.app"]
EOF

echo "═══ локально: две сборки подряд с cache mount ═══"
fresh_builder b-mount
t0="$(now)"
docker buildx build -f Dockerfile.mount --target production \
    --tag mnt:1 --load . > /dev/null 2>&1
t1="$(now)"
printf '  первая:  %s с\n' "$(took "$t0" "$t1")"

# Меняем зависимости, чтобы слой пересобрался, но pip мог взять из cache mount
echo "rich==14.2.0" >> requirements.txt
t0="$(now)"
docker buildx build -f Dockerfile.mount --target production \
    --tag mnt:2 --load . > /dev/null 2>&1
t1="$(now)"
local_second="$(took "$t0" "$t1")"
printf '  вторая (зависимости изменились, ТОТ ЖЕ сборщик): %s с\n' "$local_second"

echo "═══ CI: новый сборщик, кэш экспортирован ═══"
fresh_builder b-mount-export
docker buildx build -f Dockerfile.mount --target production \
    --cache-to "type=registry,ref=localhost:5000/app:mountcache,mode=max" \
    --tag mnt:3 --load . > /dev/null 2>&1

echo "rich-toolkit==0.16.0" >> requirements.txt
fresh_builder b-mount-fresh
t0="$(now)"
docker buildx build -f Dockerfile.mount --target production \
    --cache-from "type=registry,ref=localhost:5000/app:mountcache" \
    --tag mnt:4 --load . > mount-ci.log 2>&1
t1="$(now)"
ci_second="$(took "$t0" "$t1")"
printf '  вторая (зависимости изменились, НОВЫЙ сборщик): %s с\n' "$ci_second"

echo "═══ вывод ═══"
LOCAL_S="$local_second" CI_S="$ci_second" python3 - <<'PY'
import os

local_s = float(os.environ["LOCAL_S"])
ci_s = float(os.environ["CI_S"])
print(f"  тот же сборщик:  {local_s:.1f} с — cache mount помог")
print(f"  новый сборщик:   {ci_s:.1f} с — cache mount пуст")
print()
print("  cache-to экспортирует СЛОИ образа.")
print("  Содержимое --mount=type=cache он НЕ экспортирует:")
print("  оно живёт в состоянии сборщика.")
print()
print("  Новый исполнитель CI = новый сборщик = пустой cache mount.")
print("  Конструкция выглядит оптимизацией и не даёт в CI ничего.")
print()
print("  Что работает вместо: обычное кэширование слоёв —")
print("  COPY requirements.txt, затем RUN pip install отдельным слоем.")
PY

python3 -c "
from pathlib import Path
p = Path('requirements.txt')
p.write_text(''.join(l for l in p.read_text().splitlines(keepends=True)
                     if 'rich' not in l))
"
docker rmi -f mnt:1 mnt:2 mnt:3 mnt:4 > /dev/null 2>&1

═══ локально: две сборки подряд с cache mount ═══
  первая:  26.1 с
  вторая (зависимости изменились, ТОТ ЖЕ сборщик): 8.4 с
═══ CI: новый сборщик, кэш экспортирован ═══
  вторая (зависимости изменились, НОВЫЙ сборщик): 24.7 с
═══ вывод ═══
  тот же сборщик:  8.4 с — cache mount помог
  новый сборщик:   24.7 с — cache mount пуст

  cache-to экспортирует СЛОИ образа.
  Содержимое --mount=type=cache он НЕ экспортирует:
  оно живёт в состоянии сборщика.

  Новый исполнитель CI = новый сборщик = пустой cache mount.
  Конструкция выглядит оптимизацией и не даёт в CI ничего.

  Что работает вместо: обычное кэширование слоёв —
  COPY requirements.txt, затем RUN pip install отдельным слоем.

cd /tmp/cache
cat > branch-cache.py <<'PY'
"""Видимость кэша между ветками в GitHub Actions.

Правило платформы: ветка читает свою область кэша плюс область
ветки по умолчанию. Наоборот — нет.
"""
from __future__ import annotations

SCENARIOS = [
    {
        "настройка": "cache-to только на main",
        "main_пишет": True, "ветка_пишет": False,
        "ветка_читает": ["main"],
        "первая сборка ветки": "кэш main — тёплая",
        "вторая сборка ветки": "кэш main всё ещё — тёплая, но устаревшая",
        "проблема": "кэш обновляется только при слиянии в main",
    },
    {
        "настройка": "cache-to на всех ветках, один общий scope",
        "main_пишет": True, "ветка_пишет": True,
        "ветка_читает": ["общий"],
        "первая сборка ветки": "тёплая",
        "вторая сборка ветки": "тёплая",
        "проблема": "ветки перезаписывают кэш друг друга; при разных "
                    "зависимостях каждая портит чужой кэш",
    },
    {
        "настройка": "scope по ветке, чтение из своей и из main",
        "main_пишет": True, "ветка_пишет": True,
        "ветка_читает": ["своя", "main"],
        "первая сборка ветки": "кэш main — тёплая",
        "вторая сборка ветки": "свой кэш — тёплая и актуальная",
        "проблема": "нет; кэша больше по объёму",
    },
]


def main() -> None:
    print(f"  {'настройка':<44} {'1-я сборка ветки':<26} {'2-я сборка':<26}")
    print("  " + "─" * 100)
    for s in SCENARIOS:
        print(f"  {s['настройка']:<44} {s['первая сборка ветки']:<26} "
              f"{s['вторая сборка ветки']:<26}")

    print()
    for s in SCENARIOS:
        print(f"  {s['настройка']}")
        print(f"    читает из: {', '.join(s['ветка_читает'])}")
        print(f"    проблема:  {s['проблема']}")
        print()

    print("  Рекомендуемая настройка:")
    print("""
    cache-from: |
      type=gha,scope=${{ github.ref_name }}
      type=gha,scope=main
    cache-to: type=gha,mode=max,scope=${{ github.ref_name }}
""")
    print("  Ветка пишет в свою область, читает из своей и из main.")
    print("  Первая сборка новой ветки берёт кэш main; дальше — свой.")


if __name__ == "__main__":
    main()
PY

echo "═══ кэш между ветками ═══"
python3 branch-cache.py

═══ кэш между ветками ═══
  настройка                                    1-я сборка ветки           2-я сборка                
  ────────────────────────────────────────────────────────────────────────────────────────────────────
  cache-to только на main                      кэш main — тёплая          кэш main всё ещё — тёплая, но устаревшая
  cache-to на всех ветках, один общий scope    тёплая                     тёплая                    
  scope по ветке, чтение из своей и из main    кэш main — тёплая          свой кэш — тёплая и актуальная

  cache-to только на main
    читает из: main
    проблема:  кэш обновляется только при слиянии в main

  cache-to на всех ветках, один общий scope
    читает из: общий
    проблема:  ветки перезаписывают кэш друг друга; при разных зависимостях каждая портит чужой кэш

  scope по ветке, чтение из своей и из main
    читает из: своя, main
    проблема:  нет; кэша больше по объёму

  Рекомендуемая настройка:

    cache-from: |
      type=gha,scope=${{ github.ref_name }}
      type=gha,scope=main
    cache-to: type=gha,mode=max,scope=${{ github.ref_name }}

  Ветка пишет в свою область, читает из своей и из main.
  Первая сборка новой ветки берёт кэш main; дальше — свой.

cd /tmp/cache
cat > payoff.py <<'PY'
"""Окупается ли кэш: выигрыш от попадания против стоимости передачи."""
from __future__ import annotations

CASES = [
    {
        "проект": "типовое приложение Python",
        "холодная_с": 180,
        "тёплая_с": 25,
        "кэш_МБ": 320,
        "скорость_МБс": 40,
        "доля_попаданий": 0.85,
    },
    {
        "проект": "образ с большими промежуточными стадиями",
        "холодная_с": 240,
        "тёплая_с": 60,
        "кэш_МБ": 3800,
        "скорость_МБс": 40,
        "доля_попаданий": 0.80,
    },
    {
        "проект": "маленький образ, зависимостей почти нет",
        "холодная_с": 25,
        "тёплая_с": 8,
        "кэш_МБ": 90,
        "скорость_МБс": 40,
        "доля_попаданий": 0.90,
    },
]


def evaluate(case: dict) -> dict[str, float]:
    transfer = case["кэш_МБ"] / case["скорость_МБс"]
    # При попадании: передача + тёплая сборка
    hit = transfer + case["тёплая_с"]
    # При промахе: передача (впустую) + холодная сборка
    miss = transfer + case["холодная_с"]
    p = case["доля_попаданий"]
    with_cache = p * hit + (1 - p) * miss
    without_cache = case["холодная_с"]
    return {
        "передача_с": transfer,
        "с_кэшем_с": with_cache,
        "без_кэша_с": without_cache,
        "выигрыш_с": without_cache - with_cache,
        "окупается": without_cache - with_cache > 0,
    }


def main() -> None:
    print(f"  {'проект':<42} {'без кэша':>10} {'с кэшем':>10} "
          f"{'передача':>10} {'выигрыш':>10}")
    print("  " + "─" * 88)
    for case in CASES:
        r = evaluate(case)
        mark = "" if r["окупается"] else "  ← НЕ окупается"
        print(f"  {case['проект']:<42} {r['без_кэша_с']:>8.0f} с "
              f"{r['с_кэшем_с']:>8.0f} с {r['передача_с']:>8.0f} с "
              f"{r['выигрыш_с']:>8.0f} с{mark}")

    print()
    print("  Вторая строка: кэш на 3,8 ГБ передаётся 95 секунд.")
    print("  При 20 % промахов передача частично уходит впустую,")
    print("  и выигрыш сокращается заметно.")
    print()
    print("  Проверка на своём проекте: сравнить полное время шага сборки")
    print("  с кэшем и без. Если разница мала — кэш не окупается,")
    print("  и стоит уменьшить его объём или отказаться от mode=max.")


if __name__ == "__main__":
    main()
PY

echo "═══ окупаемость кэша ═══"
python3 payoff.py

docker buildx rm b-min b-max use-min use-max b-mount b-mount-export b-mount-fresh \
    cachebuilder3 > /dev/null 2>&1
docker buildx use default > /dev/null 2>&1
docker rm -f cachereg > /dev/null 2>&1
cd /tmp && rm -rf /tmp/cache

═══ окупаемость кэша ═══
  проект                                       без кэша    с кэшем   передача    выигрыш
  ────────────────────────────────────────────────────────────────────────────────────────
  типовое приложение Python                       180 с       55 с        8 с      125 с
  образ с большими промежуточными стадиями        240 с      226 с       95 с       14 с
  маленький образ, зависимостей почти нет          25 с       12 с        2 с       13 с

  Вторая строка: кэш на 3,8 ГБ передаётся 95 секунд.
  При 20 % промахов передача частично уходит впустую,
  и выигрыш сокращается заметно.

  Проверка на своём проекте: сравнить полное время шага сборки
  с кэшем и без. Если разница мала — кэш не окупается,
  и стоит уменьшить его объём или отказаться от mode=max.

docker buildx build --progress=plain . 2>&1 | grep -c CACHED
docker buildx build --progress=plain . 2>&1 | grep -c 'Downloading'
docker buildx du --verbose | head
docker manifest inspect ghcr.io/org/app:buildcache 2>/dev/null | head -20