Docker 사용후 이상하게 용량이 많아 진다? - Docker Build Cache 관리방법

 

 

Docker 이미지를 빌드하면 각 레이어가 캐시로 저장되어 다음 빌드 시 재사용된다.

편리하지만 관리하지 않으면 디스크를 수십 GB씩 잡아먹는 주범이 된다.

---

1. Build Cache란?

Docker는 Dockerfile의 각 명령어(RUN, COPY 등)를 레이어 단위로 캐시한다.

FROM node:20          ← 베이스 이미지 레이어
COPY package.json .   ← 캐시 레이어 1
RUN npm install       ← 캐시 레이어 2 (package.json 변경 없으면 재사용)
COPY . .              ← 캐시 레이어 3
RUN npm run build     ← 캐시 레이어 4

• 이전 빌드와 동일한 명령 + 동일한 입력이면 캐시 히트 → 빌드 시간 단축
• 변경이 감지되면 해당 레이어부터 이후 모든 레이어를 재빌드

BuildKit 캐시 vs Legacy 캐시

항목	Legacy (overlay2)	BuildKit
활성화	Docker 기본	DOCKER_BUILDKIT=1 또는 Docker 23.0+ 기본
캐시 위치	/var/lib/docker/overlay2/	/var/lib/docker/buildkit/
관리 명령	docker system prune	docker builder prune
캐시 효율	레이어 단위	레이어 + 마운트 캐시 지원

---

2. 캐시 확인 명령어

전체 Docker 디스크 사용량 요약

docker system df

출력 예시:

TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          3         3         1.281GB   0B (0%)
Containers      3         3         0B        0B
Local Volumes   2         2         579.6MB   0B (0%)
Build Cache     149       0         4.09GB    4.09GB (100%)

• ACTIVE: 현재 사용 중인 항목 수
• RECLAIMABLE: 삭제 가능한 크기
• Build Cache의 ACTIVE가 0이면 전부 삭제 가능

상세 사용량 (-v 옵션)

docker system df -v

이미지, 컨테이너, 볼륨별 개별 크기까지 상세히 표시한다.

빌드 캐시 상세 목록

docker builder du

출력 예시:

ID                         RECLAIMABLE  SIZE        LAST ACCESSED
abc123def456               true         256MB       3 weeks ago
def789ghi012               true         512MB       2 months ago
...

• 각 캐시 엔트리의 ID, 크기, 마지막 사용 시점을 확인 가능
• RECLAIMABLE이 true면 삭제 가능

---

3. 캐시 정리 명령어

빌드 캐시만 정리

# 미사용 빌드 캐시 전부 삭제
docker builder prune -f

# 확인 프롬프트 포함
docker builder prune

# 특정 기간 이상 된 캐시만 삭제 (예: 7일 이상)
docker builder prune --filter "until=168h" -f

# 모든 빌드 캐시 강제 삭제 (사용 중인 것 포함)
docker builder prune --all -f

Docker 전체 정리 (주의)

# 미사용 이미지 + 컨테이너 + 네트워크 + 캐시 정리
docker system prune -f

# 위 + 미사용 볼륨까지 포함 (데이터 손실 주의!)
docker system prune --volumes -f

# 위 + 모든 미사용 이미지 (dangling이 아닌 것도 포함)
docker system prune -a -f

정리 명령어 비교

 

명령어	삭제 대상	위험도
docker builder prune	빌드 캐시만	낮음 (빌드 속도만 영향)
docker image prune	dangling 이미지	낮음
docker system prune	컨테이너+이미지+네트워크+캐시	중간
docker system prune -a --volumes	위 + 모든 미사용 이미지 + 볼륨	높음

---

4. 컨테이너 로그 관리

빌드 캐시와 함께 디스크를 잡아먹는 또 다른 주범이 컨테이너 로그다.

로그 크기 확인

# 특정 컨테이너 로그 크기
docker inspect <container_id> --format='{{.LogPath}}' | xargs sudo du -sh

# 전체 컨테이너 로그 크기 한눈에 보기
sudo du -sh /var/lib/docker/containers/*/*-json.log | sort -rh

로그 즉시 비우기 (컨테이너 재시작 없음)

sudo truncate -s 0 $(docker inspect <container_id> --format='{{.LogPath}}')

로그 사이즈 제한 설정 (재발 방지)

/etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

• max-size: 로그 파일 1개의 최대 크기
• max-file: 로테이션 파일 수 (3개 × 100MB = 최대 300MB)

# 적용 (Docker 재시작 필요 - 서비스 중단 발생)
sudo systemctl restart docker

주의: daemon.json 설정은 새로 생성되는 컨테이너부터 적용된다. 기존 컨테이너에 적용하려면 컨테이너를 재생성해야 한다. docker-compose를 사용한다면 docker compose down && docker compose up -d로 재생성한다.

docker-compose에서 개별 서비스 로그 제한

services:
  app:
    image: myapp:latest
    logging:
      driver: json-file
      options:
        max-size: "50m"
        max-file: "3"

---

5. 자동화: Cron으로 주기적 정리

빌드 캐시 주간 정리

# crontab -e
0 3 * * 0 docker builder prune --filter "until=168h" -f >> /var/log/docker-cleanup.log 2>&1

매주 일요일 새벽 3시에 7일 이상 된 빌드 캐시를 자동 삭제한다.

전체 정리 스크립트

#!/bin/bash
# /usr/local/bin/docker-cleanup.sh

echo "=== Docker Cleanup $(date) ==="

# 1. 중지된 컨테이너 제거
docker container prune -f

# 2. dangling 이미지 제거
docker image prune -f

# 3. 7일 이상 된 빌드 캐시 제거
docker builder prune --filter "until=168h" -f

# 4. 사용량 리포트
docker system df

echo "=== Cleanup Complete ==="

chmod +x /usr/local/bin/docker-cleanup.sh

# 매주 일요일 새벽 3시 실행
echo "0 3 * * 0 /usr/local/bin/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1" | crontab -

---

6. Dockerfile 최적화로 캐시 효율 높이기

변경 빈도 낮은 레이어를 위로

# 좋은 예 - 의존성 설치를 먼저 (잘 안 바뀜)
FROM node:20-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production
COPY . .
RUN npm run build

# 나쁜 예 - 소스 변경마다 npm install 재실행
FROM node:20-slim
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build

.dockerignore 활용

node_modules
.git
*.log
dist
.env

불필요한 파일이 COPY 컨텍스트에 포함되면 캐시 무효화가 더 자주 발생한다.

Multi-stage 빌드로 최종 이미지 경량화

# Build stage
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/main.js"]

빌드 도구(devDependencies 등)가 최종 이미지에 포함되지 않아 이미지 크기가 줄어든다.

---

7. 빠른 참조 (Quick Reference)

# 디스크 사용량 확인
docker system df              # 요약
docker system df -v           # 상세
docker builder du             # 빌드 캐시 상세

# 빌드 캐시 정리
docker builder prune -f            # 미사용 캐시 삭제
docker builder prune --all -f      # 전체 캐시 삭제
docker builder prune --filter "until=168h" -f  # 7일 이상 된 것만

# 컨테이너 로그
docker logs <container> --tail 100  # 최근 100줄 확인
sudo truncate -s 0 $(docker inspect <id> --format='{{.LogPath}}')  # 로그 비우기

# 전체 정리
docker system prune -f              # 미사용 리소스 정리
docker system prune -a --volumes -f # 전부 정리 (주의!)

---

참고

• Docker 공식 문서 - Builder cache
• Docker 공식 문서 - Logging
• Docker 공식 문서 - Prune unused objects