Docker 용량 부족 해결: 로그·캐시 정리와 볼륨 보존 방법

AI Editter

Docker 서버에서 용량이 부족할 때 docker system prune -a --volumes부터 실행하면, 되돌릴 때 필요한 이미지나 사용하지 않는 것으로 분류된 데이터까지 정리할 수 있습니다. 먼저 이미지·빌드 캐시·컨테이너 로그·볼륨 중 무엇이 늘었는지 나눠 봐야 합니다. 특히 데이터베이스 볼륨의 크기를 이미지 정리로 줄일 수는 없습니다.

이 글은 Linux의 Docker Engine을 기준으로 합니다. Docker Desktop을 쓰면 아래 명령으로 Docker 내부 사용량을 먼저 확인하되, Windows의 가상 디스크 파일 크기는 별도 문제로 봐야 합니다. 아래 컨테이너 이름 app은 실제 서비스 이름으로 바꾸세요.

1. 디스크 부족과 Docker 사용량을 같은 기준으로 비교하기

df -h
df -i
docker info --format '{{.DockerRootDir}}'
docker system df -v
docker ps -a --size
docker buildx ls
docker buildx du

df -h에서 Docker 데이터 디렉터리가 속한 파일시스템을 찾습니다. 루트 디스크가 찼는데 별도 디스크에 있는 Docker 이미지를 지워도 루트 공간은 늘지 않습니다. df -i가 100%라면 작은 파일이 너무 많아 inode가 고갈된 경우입니다.

docker system df -v의 이미지 크기는 공유 레이어를 포함할 수 있습니다. 목록의 SIZE를 모두 더해 회수 가능 용량으로 잡지 마세요. 컨테이너의 writable layer와 별도로 연결한 볼륨, 로그도 구분해야 합니다. 빌드 캐시는 선택된 builder에 따라 보이는 범위가 달라지므로 여러 builder를 쓴다면 각각 확인합니다. Docker 사용량 명령 설명과 정리 대상의 공식 정의를 함께 보면 결과를 해석하기 쉽습니다.

크게 보이는 항목	다음에 확인할 것	첫 조치
Build cache	현재 builder와 최근 빌드	오래된 캐시만 정리
Images	배포·롤백에 쓰는 태그	필요 없는 이미지 ID를 개별 삭제
Local Volumes	마운트한 서비스와 백업	애플리케이션 안에서 보존 정책 점검
Docker 합계보다 df 사용량이 큼	로그, 다른 디렉터리, 삭제 후 열린 파일	파일시스템 쪽 원인도 조사

2. 로그가 원인인지 확인하는 가장 짧은 경로

docker inspect --format '{{json .HostConfig.LogConfig}}' app
docker inspect --format '{{.LogPath}}' app
docker logs --tail 100 app

로그 드라이버가 json-file이고 회전 제한이 없다면 같은 오류가 반복될 때 파일이 계속 커질 수 있습니다. LogPath가 비어 있거나 다른 드라이버를 쓰면 json 로그 파일이 있다는 전제로 조사하지 않습니다. 확인한 경로는 관리 권한으로 파일 크기를 조회하되, Docker가 쓰는 파일을 임의로 삭제하거나 내용을 잘라내는 방식은 피하세요.

Compose 서비스에 아래처럼 제한을 설정할 수 있습니다. 기존 services.app 설정에 합치는 예시이며, 볼륨·포트 등 나머지 서비스 정의는 유지합니다.

services:
  app:
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

설정 파일을 저장한 것만으로 기존 컨테이너의 로그 설정이 바뀌지는 않습니다. docker compose config -q로 구문을 검사하고, 배포 절차에 따라 해당 서비스의 컨테이너를 재생성한 다음 docker inspect로 적용 여부를 확인합니다. 재생성은 서비스 중단을 일으킬 수 있습니다. Docker 로그 설정 문서도 기존 컨테이너에는 새 기본값이 자동 적용되지 않는다고 설명합니다.

3. prune 명령마다 지우는 대상이 다르다

개발용 서버라면 오래된 빌드 캐시부터 검토하기 좋습니다. 예를 들어 다음 명령은 7일보다 오래된 캐시를 대상으로 하며 실행 전 확인 질문을 표시합니다. 다음 빌드가 느려질 수 있으므로 배포 직전에는 작업 시간을 따져 보세요.

docker builder prune --filter 'until=168h'

docker image prune의 기본 대상은 dangling 이미지입니다. -a를 붙이면 컨테이너가 참조하지 않는 이미지까지 넓어집니다. 지금 실행 중인 컨테이너가 없더라도 이전 버전 이미지가 롤백에 필요할 수 있습니다. 레지스트리에서 다시 받을 수 있는지, 태그가 같은 내용으로 유지되는지 확인한 뒤 정리합니다.

현재 Docker 문서에서 docker volume prune은 기본적으로 사용하지 않는 익명 볼륨을 정리하며, --all은 이름 있는 볼륨까지 포함합니다. 컨테이너를 지운 뒤 남은 DB 볼륨은 “unused”여도 중요한 데이터입니다. 사용 여부와 업무상 필요 여부는 다릅니다.

4. 볼륨을 지우기 전에 확인할 세 가지

docker inspect --format '{{json .Mounts}}' app
docker volume ls
docker volume inspect example_data

Compose 파일의 볼륨 이름과 실제 마운트 대상을 대조합니다. bind mount라면 호스트 경로가 데이터 위치입니다.
데이터베이스는 실행 중인 파일을 복사하는 것만으로 백업이 완성되지 않습니다. DB가 지원하는 백업 방식과 복원 검증을 사용합니다.
삭제하려는 볼륨에서 필요한 파일을 복원할 수 있는지 확인한 뒤, 승인된 대상 하나만 정리합니다. 전체 볼륨 일괄 삭제는 점검 절차를 대신하지 못합니다.

공간이 늘었는데 다음 날 다시 찬다면

정리 전후의 df -h, docker system df, 주요 로그 파일 크기를 기록하고 하루 뒤 같은 항목을 비교하세요. 이미지가 늘면 배포 보존 수를, 캐시가 늘면 빌드 정책을, 로그가 늘면 반복 오류와 회전 설정을 고칩니다. DB 볼륨이 늘면 테이블 보존 정책과 DB 내부 정리가 필요합니다. /var/lib/docker/overlay2를 직접 지우면 Docker의 관리 정보와 실제 파일이 어긋날 수 있습니다.

Docker 수치만으로 설명되지 않는 공간은 리눅스 디스크·inode 진단과 연결해 확인하세요. 정리의 완료 기준은 명령 성공 메시지가 아니라, 필요한 데이터가 남고 서비스가 정상 동작하면서 증가 원인까지 통제되는 것입니다.