배포 빌드 개선 · 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 mount | builder 내부 | 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만 추가하면 왜 효과가 없나
- builder와 함께 사라진다: cache mount는 builder 내부에만 저장된다. builder가 매번 새로 생기면 매번 빈 캐시로 시작한다.
- registry 캐시로 내보내지지 않는다:
--cache-to type=registry,mode=max는 레이어 결과만 저장하고 cache mount 내용은 저장하지 않는다(BuildKit 동작). - 이미 걸린 pnpm store mount도 같은 처지다: lockfile이 그대로면 설치 레이어가 registry 캐시로 통째로 재사용돼 mount가 필요 없고, lockfile이 바뀌면 빈 mount로 시작해 도움이 안 된다.
- Socket의 긴 설치 시간은 대상이 아니다: 로컬 runner 첫 빌드 22분의 대부분은 mediasoup 네이티브 컴파일(OpenSSL 포함)이었다. 결과가
node_modules안에 생기므로 pnpm store 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 환경을 별도 이미지로 만든다.
Dockerfile.dependencies가uv sync --frozen, livekit 모델 파일, FireRed VAD 다운로드까지 담은 의존성 이미지를 만든다.- 입력 파일(
Dockerfile.dependencies,pyproject.toml,uv.lock,scripts/download_firered_vad.py,vendor/)의 Git blob 해시와 base image digest로 key를 만든다. - GHCR에
ppi-livekit-agent-deps:deps-<key>가 있으면 재사용하고, 없을 때만 빌드한다. - 앱 이미지(
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. 그 밖의 후보
- runtime 단계
chown -R: Staging Web에서 약 49초.COPY --chown으로 대체 가능한지 실행 권한과 함께 검증한다. - 이미지 export·cache export: 약 115초·98초(일부 겹침). standalone 산출물만 담기,
.next/cache제외로 크기를 줄인다. 캐시 mode를 낮추면 중간 캐시를 잃을 수 있어 크기와 hit를 함께 측정한다. - mediasoup 컴파일: lockfile이 바뀌어 설치 레이어 캐시가 깨지면 Socket·Dev 빌드가 크게 늘어난다(로컬 runner 첫 빌드 22분). prebuilt worker 사용 가능 여부를 별도로 조사한다.
6. 적용 순서 제안
- LiveKit 의존성 key에서 도구 설정 분리: 관측된 20분 재빌드를 직접 막는다. 빌드 결과는 바뀌지 않아 위험이 작다.
- Web runtime 이미지에서
.next/cache제외: builder 유지 없이 Staging·Prod 이미지 크기와 export 시간을 줄인다. 이미지 크기 전후를 기록한다. - 로컬 Dev runner에서 builder 유지 +
.next/cache재사용 실험: 코드만 바꾼 연속 배포 2회의 Next build 시간을 비교한다. - Staging·Prod runner 유지 여부 확인 후 3번 확대 여부 결정.
모든 항목은 아직 적용하지 않았다. 배포 workflow와 Containerfile 변경은 PPI 저장소의 설계 승인 절차를 따른다.
근거와 검증 범위
- PPI
feature/local-build(2026-11-18) 기준apps/web/Containerfile,apps/socket/Containerfile,Dockerfile.dev.web,Dockerfile.dev.socket,apps/livekit-agent/Dockerfile,apps/livekit-agent/Dockerfile.dependencies,apps/livekit-agent/pyproject.toml,.github/workflows/dev.yml,deploy-staging-web.yml,deploy-prod-web.yml,.github/actions/deploy-socket/action.yml,.github/actions/deploy-livekit-agent/action.yml. - LiveKit Agent 시간은 run 로그의
livekit_agent_dependency_seconds,livekit_agent_application_image_seconds값과 step 시작·종료 시각이다. Dev 재빌드 원인은 두 run의 head 커밋 사이 의존성 입력 파일 diff로 확인했다. - Web 구간 시간은 PPI Web 코드 수정 때 빌드가 오래 걸리는 이유와 개선안의 run 44050628896 분석을 인용했다.
- Staging·Prod runner가 실행마다 새로 뜨는지는 확인하지 않았다.
.next/cache크기와 각 방안의 실제 절감 시간은 미측정이다.
관련 PPI 문서
- PPI Web 코드 수정 때 빌드가 오래 걸리는 이유와 개선안: Web 빌드 구간별 시간과
.next/cache제안의 출발점. - Staging · Dev 배포 시간 분석: 배포 단계별 소요 시간.
- 로컬 self-hosted runner로 Dev 배포하기: builder를 유지할 수 있는 로컬 runner와 캐시 유무에 따른 빌드 시간(22분 / 22초).