배포 빌드 개선 · 2026-11-18

PPI 배포 빌드 시간 단축 방법

마지막 업데이트 2026-11-18

대상: Dev·Staging·Prod 배포가 오래 걸리는 원인과 줄일 방법을 정하려는 개발자

cache mount를 더 추가하는 것만으로는 거의 줄지 않는다. 모든 배포가 실행마다 새 Buildx builder를 만들고 지우기 때문에 cache mount 내용은 다음 배포로 이어지지 않는다. 실행 사이에 남는 캐시는 GHCR registry 레이어 캐시뿐이다.

효과가 확실한 순서는 ① LiveKit Agent 의존성 이미지의 불필요한 재빌드 방지, ② Web runtime 이미지에서 .next/cache 제외, ③ builder를 유지하는 runner에서 .next/cache 재사용이다. 이 문서의 절감 시간은 관측 로그 기준 추정이며 적용 후 측정이 필요하다.

1. 지금 배포 빌드가 캐시를 쓰는 방식

캐시 종류저장 위치다음 배포에 남는가현재 사용
registry 레이어 캐시GHCR …:buildcache남는다Web·Socket·Agent 모두 --cache-from/--cache-to type=registry
BuildKit cache mountbuilder 내부builder가 남아야만pnpm store·npm 캐시에 이미 적용(apps/web/Containerfile:14,18, apps/socket/Containerfile:17,21, Dockerfile.dev.web:20,25, Dockerfile.dev.socket:20,25)
미리 만든 의존성 이미지GHCR ppi-livekit-agent-deps:deps-<key>남는다LiveKit Agent만 적용

Dev(dev.yml), Staging·Prod Web, Socket action, LiveKit Agent action 모두 docker/setup-buildx-action@v3을 기본 설정으로 쓴다. 실행마다 새 이름의 docker-container builder를 만들고 job 종료 시 지운다.

2. cache mount만 추가하면 왜 효과가 없나

cache mount가 효과를 내려면 같은 builder가 실행 사이에 남아 있어야 한다. 고정 name과 cleanup: false로 builder를 유지하고, runner 머신 자체도 유지돼야 한다. deploy-staging-web.yml의 주석에는 "임시 Amazon Linux runner"라는 표현이 있어 Staging·Prod runner가 매번 새로 뜨는지 먼저 확인해야 한다.

3. .next/cache 재사용

지금 동작

Web 빌드는 의존성 설치 뒤 앱 소스를 복사하고 pnpm run build를 실행한다(apps/web/Containerfile:22-40, Dockerfile.dev.web:29-44). 코드가 한 줄이라도 바뀌면 이 레이어부터 다시 계산되고, Next.js 컴파일 캐시(apps/web/.next/cache)는 이전 결과 없이 처음부터 만든다. 2026-11-17 Staging run 44050628896에서 Next build는 약 154초였다.

방법 A: runtime 이미지에서 .next/cache 제외 (builder 유지 불필요)

Staging·Prod용 apps/web/Containerfile의 runner 단계는 COPY --from=builder /app/apps/web/.next ./.next로 .next 전체를 복사한다. 실행에 필요 없는 컴파일 캐시까지 이미지에 들어가 레이어 export(약 115초)와 push가 커진다. 빌드 단계에서 .next/cache를 cache mount 경로로 두면 이미지에서 빠진다. Dev(Dockerfile.dev.web)는 standalone 산출물만 복사해 해당하지 않는다.

RUN --mount=type=cache,target=/app/apps/web/.next/cache,sharing=locked \
    --mount=type=secret,id=next_server_actions_key \
    … pnpm run build

이미지에서 빠지는 용량은 실제 빌드에서 .next/cache 크기를 재서 확인한다.

방법 B: builder를 유지해 컴파일 캐시 재사용

방법 A의 mount가 다음 배포까지 남으면 Next.js가 이전 컴파일 결과를 재사용한다. 코드만 바뀐 연속 배포에서 154초 구간이 줄어들 수 있다. 조건은 2절과 같다.

배포방법 B 적용 가능성
Dev(로컬 Mac runner)높다. 항상 같은 PC라 builder를 유지할 수 있다. 로컬 runner Dev 배포 가이드 참고
Dev·Staging·Prod(기존 runner)runner가 유지되는지 확인 후 결정. 매번 새로 뜨면 cache mount를 GitHub Actions 캐시로 옮기는 별도 단계가 필요하고 그 전송 시간만큼 이득이 줄어든다

4. LiveKit Agent uv 의존성 이미지 재사용

이미 적용되어 있다

2026-09-10 PR #1080(PPI-1289)부터 .github/actions/deploy-livekit-agent/action.yml이 uv 환경을 별도 이미지로 만든다.

  1. Dockerfile.dependencies가 uv sync --frozen, livekit 모델 파일, FireRed VAD 다운로드까지 담은 의존성 이미지를 만든다.
  2. 입력 파일(Dockerfile.dependencies, pyproject.toml, uv.lock, scripts/download_firered_vad.py, vendor/)의 Git blob 해시와 base image digest로 key를 만든다.
  3. GHCR에 ppi-livekit-agent-deps:deps-<key>가 있으면 재사용하고, 없을 때만 빌드한다.
  4. 앱 이미지(Dockerfile)는 의존성 이미지 위에 소스만 복사한다.
run의존성 이미지앱 이미지배포 step 전체
Staging 44050628896 (2026-11-17)reused, 3초13초252초
Staging 43001678119 (2026-11-11)reused, 3초89초314초
Dev 44068470775 (2026-11-17, PPI-1437)built, 1,201초13초1,447초

남은 문제: 의존성과 무관한 변경도 20분 재빌드를 일으킨다

Dev run 44068470775의 재빌드 원인은 pyproject.toml 변경이었다. 직전 Dev 배포(42605353406)와 비교하면 바뀐 내용은 [tool.mutmut]의 source_paths·only_mutate에 파일 3개를 추가한 것뿐이다. mutation 테스트 설정이라 uv 환경에는 영향이 없지만 key가 바뀌어 의존성 이미지를 처음부터 다시 만들었다(배포 step의 83%).

또 base image를 태그(ghcr.io/astral-sh/uv:python3.11-bookworm-slim)로 지정하고 매번 digest를 조회하므로, upstream이 태그를 갱신하면 코드 변경 없이도 key가 바뀌어 재빌드된다.

개선 방안

방안효과주의
도구 설정을 pyproject.toml 밖으로 이동(예: mutmut 설정 파일 분리)테스트 대상 추가 같은 잦은 변경이 key를 바꾸지 않는다mutmut이 별도 설정 파일을 읽는지 버전별 확인 필요
key 계산 시 pyproject.toml의 [tool.*] 중 uv와 무관한 섹션 제외설정 파일 위치를 바꾸지 않고 같은 효과빌드에 넣는 pyproject.toml도 같은 기준으로 정규화해야 key와 내용이 어긋나지 않는다. [tool.uv.sources]는 의존성에 영향을 주므로 남긴다
base image를 digest로 고정하고 갱신은 별도 PR로upstream 태그 갱신으로 인한 예기치 않은 재빌드 방지보안 패치 반영을 위해 주기적 갱신 절차 필요
배포 전에 의존성 이미지를 미리 빌드(예: uv.lock 변경 PR에서 사전 빌드)배포 시점에는 항상 reused사전 빌드용 workflow와 GHCR 정리 정책 추가

5. 그 밖의 후보

6. 적용 순서 제안

  1. LiveKit 의존성 key에서 도구 설정 분리: 관측된 20분 재빌드를 직접 막는다. 빌드 결과는 바뀌지 않아 위험이 작다.
  2. Web runtime 이미지에서 .next/cache 제외: builder 유지 없이 Staging·Prod 이미지 크기와 export 시간을 줄인다. 이미지 크기 전후를 기록한다.
  3. 로컬 Dev runner에서 builder 유지 + .next/cache 재사용 실험: 코드만 바꾼 연속 배포 2회의 Next build 시간을 비교한다.
  4. Staging·Prod runner 유지 여부 확인 후 3번 확대 여부 결정.

모든 항목은 아직 적용하지 않았다. 배포 workflow와 Containerfile 변경은 PPI 저장소의 설계 승인 절차를 따른다.

근거와 검증 범위

관련 PPI 문서