---
id: devops-docker-layer-cache
title: Docker Layer Cache — 빌드 시간 90% 줄이기
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [devops, docker, build, cache, vibe-coding]
tech_stack: { language: "Dockerfile / BuildKit", applicable_to: ["Backend", "DevOps"] }
applied_in: []
aliases: [multi-stage build, COPY order, BuildKit cache mount]
---

# Docker Layer Cache

> Layer 1개 = 1줄 = 1 cache 단위. **변경 자주 안 되는 layer 위로**, **자주 바뀌는 layer 아래로**. 잘못 정렬하면 매 빌드마다 npm install. multi-stage + cache mount 가 표준.

## 📖 핵심 개념
- 각 RUN/COPY/ADD = 새 layer.
- 이전 layer 가 같으면 cache 재사용.
- 한 layer 가 바뀌면 그 아래 모두 invalidate.

## 💻 코드 패턴

### 잘못된 순서 — 매 빌드 npm install
```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY . .              # ❌ 소스 변경 시 invalidate
RUN npm install
RUN npm run build
CMD ["node", "dist/index.js"]
```

### 올바른 순서
```dockerfile
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci             # package*.json 안 바뀌면 cache hit

FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY package*.json ./
EXPOSE 3000
USER node
CMD ["node", "dist/index.js"]
```

### BuildKit cache mount — 더 빠른 npm/apt cache
```dockerfile
# syntax=docker/dockerfile:1.6
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
```

`/root/.npm` 가 build cache 에 보존 → 다른 빌드에서도 재사용.

### Multi-stage 의 장점
- 최종 이미지 = runtime 만 (build tool 안 들어감).
- node_modules dev deps 안 들어감 (`npm prune --production` 또는 omit).
- 보안 surface 감소.

### .dockerignore 필수
```
node_modules
.git
.env
.env.*
dist
*.log
coverage
__tests__
```
없으면 모든 파일이 build context 로 → COPY .  시 매번 invalidate.

### Distroless / Alpine
```dockerfile
FROM gcr.io/distroless/nodejs20-debian12 AS runtime
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
CMD ["dist/index.js"]
```
shell 없음 — 가장 작고 보안 강함. 단 디버깅 어려움.

### Python 예시
```dockerfile
FROM python:3.12-slim AS deps
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install --user -r requirements.txt

FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=deps /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH
COPY . .
CMD ["python", "main.py"]
```

## 🤔 의사결정 기준
| 의도 | 도구 |
|---|---|
| 빠른 dev rebuild | multi-stage + cache mount |
| 작은 prod 이미지 | distroless / alpine multi-stage |
| GPU / 큰 ML 모델 | nvidia base image |
| 멀티 아키텍처 (arm64 + amd64) | docker buildx |
| 보안 스캔 | trivy / snyk in CI |

## ❌ 안티패턴
- **Source 먼저 COPY**: 매 commit 마다 deps 재설치.
- **`COPY .` 가 .dockerignore 없이**: 거대 build context.
- **모든 것 한 layer (`RUN apt-get update && ...`)**: 잘 쓰는 패턴이지만 layer 분리해야 cache 잘 작동. apt 는 보통 한 RUN.
- **dev deps 가 prod 이미지에**: 크기 + 보안. multi-stage.
- **root 사용자로 CMD**: 보안. USER node.
- **layer 이미지 매번 :latest**: pull 시점에 다른 버전. 명확한 태그.
- **healthcheck 없음**: orchestrator (k8s, ecs) 가 상태 모름.
- **secret 을 image 에 baked**: layer 에 영구 보관. build args + secrets mount (BuildKit).

## 🤖 LLM 활용 힌트
- multi-stage + .dockerignore + cache mount + non-root + healthcheck 5종.
- BuildKit syntax (`# syntax=docker/dockerfile:1.6`).

## 🔗 관련 문서
- [[DevOps_CI_CD_Pipeline_Patterns]]
- [[DevOps_Build_Performance]]