Docker 멀티스테이지 빌드 실전 가이드 — 이미지 크기 90% 줄이기

단일 스테이지 Dockerfile (문제가 있는 버전)
FROM node:22

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

EXPOSE 3000
CMD ["node", "dist/index.js"]

이미지 빌드 후 크기 확인
docker build -t my-app:single .
docker images my-app:single

# REPOSITORY   TAG      SIZE
# my-app       single   1.24GB

레이어별 크기 분석
docker history my-app:single

# IMAGE          CREATED        SIZE      COMMENT
# a1b2c3d4e5f6   2 minutes ago  12.8MB    CMD ["node", "dist/index.js"]
# b2c3d4e5f6a1   2 minutes ago  0B        EXPOSE 3000
# c3d4e5f6a1b2   2 minutes ago  85.2MB    RUN npm run build
# d4e5f6a1b2c3   2 minutes ago  4.7MB     COPY . .
# e5f6a1b2c3d4   3 minutes ago  245MB     RUN npm install
# f6a1b2c3d4e5   3 minutes ago  18.5KB    COPY package*.json
# ...           ...            910MB     node:22 base image

2-스테이지 Dockerfile (빌드 + 실행 분리)
# Stage 1: 빌드
FROM node:22 AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: 실행
FROM node:22-slim

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev

EXPOSE 3000
CMD ["node", "dist/index.js"]

멀티스테이지 빌드 후 크기 비교
docker build -t my-app:multi .
docker images my-app

# REPOSITORY   TAG      SIZE
# my-app       single   1.24GB
# my-app       multi    285MB     ← 77% 감소

Alpine 기반 3-스테이지 Dockerfile
# Stage 1: 의존성 설치
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Stage 2: 빌드
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Stage 3: 실행
FROM node:22-alpine AS runner
WORKDIR /app

RUN addgroup --system --gid 1001 nodejs \
    && adduser --system --uid 1001 appuser

COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

최종 이미지 크기 비교
docker images my-app

# REPOSITORY   TAG        SIZE
# my-app       single     1.24GB
# my-app       multi      285MB
# my-app       alpine     127MB    ← 90% 감소

잘못된 순서 vs 올바른 순서
# ❌ 잘못된 순서 — 소스 변경 시 npm install부터 다시 실행
COPY . .
RUN npm ci
RUN npm run build

# ✅ 올바른 순서 — 소스 변경해도 npm install 캐시 유지
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

.dockerignore 권장 설정
node_modules
dist
.git
.github
*.md
.env*
coverage
.nyc_output
.vscode
.idea
Dockerfile
docker-compose*.yml
.dockerignore

보안 강화 Dockerfile 패턴
# 비root 사용자 생성 및 전환
RUN addgroup --system --gid 1001 nodejs \
    && adduser --system --uid 1001 appuser
USER appuser

# 읽기 전용 파일시스템 (docker run 시)
# docker run --read-only --tmpdir /tmp my-app:alpine

# 헬스체크 추가
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD node -e "require('http').get('http://localhost:3000/health', (r) => { process.exit(r.statusCode === 200 ? 0 : 1) })"

# 취약점 스캔
# docker scout cves my-app:alpine
# trivy image my-app:alpine

Next.js standalone 모드 Dockerfile
# Stage 1: 의존성
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Stage 2: 빌드
FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Stage 3: 실행 (standalone output)
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs \
    && adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
CMD ["node", "server.js"]

# next.config.js에 output: "standalone" 설정 필수

Go API 서버 Dockerfile (최종 이미지 ~15MB)
# Stage 1: 빌드
FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o server ./cmd/server

# Stage 2: 실행
FROM scratch
COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
EXPOSE 8080
ENTRYPOINT ["/server"]

Python FastAPI Dockerfile
# Stage 1: 빌드 (wheel 생성)
FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install --no-cache-dir poetry
COPY pyproject.toml poetry.lock ./
RUN poetry export -f requirements.txt -o requirements.txt --without-hashes
RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

# Stage 2: 실행
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /wheels /wheels
RUN pip install --no-cache-dir /wheels/* && rm -rf /wheels
COPY . .

RUN useradd --system appuser
USER appuser
EXPOSE 8000
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

GitHub Actions 워크플로우 (.github/workflows/docker.yml)
name: Build and Push Docker Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Scan for vulnerabilities
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ghcr.io/${{ github.repository }}:${{ github.sha }}
          severity: CRITICAL,HIGH
          exit-code: 1

dive로 이미지 레이어 분석
# dive 설치 (macOS)
brew install dive

# 이미지 분석
dive my-app:alpine

# CI에서 효율성 검사 (낭비된 공간이 임계값 초과 시 실패)
CI=true dive my-app:alpine --ci-config .dive-ci.yml