Docker 용량 정리, DB 볼륨을 남기고 이미지·캐시 줄이는 법

용량이 큰 항목부터 찾는 네 가지 조회

개발 프로젝트를 여러 번 빌드하면 예전 이미지와 캐시가 쌓인다. 이미지를 다시 받거나 빌드할 경로가 있다면 오래된 이미지·캐시를 정리할 수 있다. DB 볼륨은 컨테이너가 꺼진 동안에도 다음 실행에 쓸 데이터를 보관하므로, 프로젝트를 다시 쓸 예정이라면 남겨 둔다.

조회는 다음 명령으로 시작한다. docker system df -v는 이미지·컨테이너·로컬 볼륨의 자세한 사용량을 보여주고, docker ps -a는 중지된 컨테이너까지 나열한다. 빌드를 자주 한다면 현재 빌더의 캐시도 함께 본다.

docker context ls
docker system df -v
docker ps -a
docker buildx du

context 목록은 명령이 어느 Docker에 연결되는지 확인하는 출발점이다. 원격 서버를 연결해 둔 터미널이라면 로컬 노트북 대신 서버의 데이터를 보고 있을 수 있다. 환경변수 DOCKER_HOST·DOCKER_CONTEXT나 명령의 접속 옵션으로 대상이 바뀔 수 있으므로, 정리할 개발 환경이 맞는 상태에서 아래 절차를 진행한다.

상세 용량 표의 이미지 SIZE는 다른 이미지와 공유하는 SHARED SIZE와 해당 이미지에만 속한 UNIQUE SIZE를 합친 값이다. 예를 들어 두 이미지가 공통 레이어 2GB를 공유하고 각각 100MB를 더 갖는다고 가정하면, 두 행의 SIZE를 단순히 더한 값은 실제 저장한 데이터보다 크다. 한 이미지를 지워도 다른 이미지가 쓰는 공통 부분은 남는다.

이 때문에 목록에서 가장 큰 이미지 하나를 지웠다는 사실만으로 같은 크기의 공간이 돌아오지는 않는다. 이미지가 큰지, 중지된 컨테이너의 쓰기 영역이 큰지, 빌드 캐시가 큰지에 따라 다음에 사용할 명령이 달라진다. 데이터 볼륨이 큰 경우에는 그 안의 자료를 계속 쓸지부터 정한다.

이미지·컨테이너·볼륨을 지우면 각각 사라지는 것

볼륨의 수명은 컨테이너와 다르다. 컨테이너를 제거하면 그 컨테이너의 쓰기 영역은 사라지지만, 마운트한 볼륨의 데이터는 별도로 남을 수 있다. 데이터베이스를 볼륨에 저장한 앱과 컨테이너 안에만 저장한 앱은 같은 삭제 명령을 실행해도 남는 자료가 다르다.

예를 들어 개발용 DB 컨테이너 이름이 app-db라면 다음 조회로 Mounts 부분을 읽는다. 이름은 실제 컨테이너 이름으로 바꾼다. Type이 volume이면 Name과 Destination으로 어떤 볼륨이 어느 경로에 연결됐는지 확인할 수 있다. bind라면 호스트의 특정 경로를 연결한 것이므로 Docker 볼륨 목록만으로 그 파일 사용량을 모두 설명할 수 없다.

docker inspect app-db

마운트 위치를 확인하면 삭제 전에 남길 자료도 구체화된다. DB 데이터 경로가 이름 있는 볼륨에 연결되어 있다면 그 이름을 기록하고, 컨테이너 안의 별도 출력 폴더에 결과물을 쌓았다면 그 파일도 따로 보관한다. 데이터가 어디에 있는지 모르는 상태에서 컨테이너부터 없애면 남은 볼륨을 보고도 어느 프로젝트의 자료였는지 찾기 어려워진다.

이미지와 중지 컨테이너의 정리 범위

기본 이미지 정리는 태그가 없고 컨테이너도 참조하지 않는 dangling 이미지를 지운다. 다음 명령의 결과가 0B라면 그 조건에 맞는 대상이 없었을 수 있다. Docker 전체가 공간을 쓰지 않는다는 뜻은 아니다.

docker image prune

태그가 붙은 예전 빌드까지 정리하려면 docker image prune -a를 쓴다. 이때도 기존 컨테이너가 사용하는 이미지는 남는다. 중지된 컨테이너 역시 이미지의 참조가 될 수 있으므로, docker ps -a에 남은 과거 작업을 함께 보는 이유가 여기에 있다.

예전 테스트 컨테이너 하나만 제거하려면, 이미 중지됐고 그 안의 필요한 파일을 보관한 상태에서 해당 이름을 지정한다. 아래 old-test는 설명용 이름이다. -f 없이 실행하면 실행 중인 컨테이너를 강제로 없애는 경로를 피할 수 있다.

docker rm old-test

중지 컨테이너 전체를 정리하는 docker container prune도 있지만, 잠시 꺼 둔 작업과 버려도 되는 실험을 함께 가지고 있다면 이름을 지정하는 방식이 범위를 좁히기 쉽다. 컨테이너를 없앤 뒤 이미지를 다시 조회하면 해당 참조가 사라진 상태를 확인할 수 있다.

docker system prune은 중지 컨테이너, 미사용 네트워크, dangling 이미지, 미사용 빌드 캐시를 한꺼번에 정리한다. 기본값은 볼륨을 포함하지 않는다. -a는 이미지 범위를 넓히며, --volumes는 미사용 익명 볼륨을 추가한다. 따라서 -a를 붙여도 그것만으로 볼륨이 삭제되지는 않는다. 반대로 DB를 익명 볼륨에 저장했다면 --volumes의 삭제 대상이 될 수 있다.

명령의 확인 질문에는 기본값으로 아니요가 선택되어 있다. 삭제 범위가 예상과 다르면 그 자리에서 취소하고 개별 명령으로 돌아갈 수 있다. 여러 프로젝트가 함께 있는 개발 환경에서는 이 확인을 생략하는 -f를 습관적으로 붙일 이유가 없다.

빌드 캐시는 빌더를 맞춰 정리한다

이미지를 자주 다시 만드는 환경에서는 캐시가 더 큰 부분을 차지할 수 있다. docker buildx du는 현재 선택된 빌더의 캐시 사용량을 보여준다. 별도 빌더를 쓰는 프로젝트라면 그 이름을 지정해야 같은 캐시를 조회하고 정리할 수 있다.

빌더 이름을 모르면 docker buildx ls로 목록을 연다. NAME/NODE 열에서 별표가 붙은 이름이 현재 선택된 빌더다. 그 아래 노드와 DRIVER/ENDPOINT를 보면 빌더가 어느 연결을 사용하는지도 알 수 있다. 원격 빌더의 캐시를 지워도 노트북의 저장 공간이 그만큼 늘어나는 것은 아니므로 조회 결과와 정리 대상을 맞춘다.

docker buildx du --builder mybuilder
docker buildx prune --builder mybuilder --filter "until=168h"

mybuilder는 실제 사용하는 빌더 이름으로 바꾼다. 두 번째 줄은 삭제 명령이며, 첫 조회 결과에서 그 빌더의 오래된 캐시를 정리하기로 결정했을 때 실행한다. buildx의 until 필터에서 168시간은 최근 7일 동안 사용한 기록을 남기는 조건이다. 이미지 생성일을 기준으로 하는 다른 prune 필터와 같은 의미로 옮겨 읽지 않는다.

캐시를 지우면 다음 빌드에서 재사용할 단계가 줄어든다. 매번 다시 받거나 계산하는 시간을 줄이는 것과 디스크를 비우는 것 사이에 선택이 생기는 셈이다. 방금 작업한 프로젝트를 계속 빌드할 예정이라면 최근 캐시를 남기고 오래된 기록부터 정리하는 방식이 맞는다.

캐시의 Shared 표시도 회수량에 영향을 준다. 이미지와 실제 저장 레이어를 공유하는 기록을 정리하면 캐시 메타데이터는 사라져도 이미지가 필요한 레이어는 남을 수 있다. RECLAIMABLE이 false인 기록은 빌더가 사용 중인 것이므로 삭제 대상을 넓혔다고 모두 없어지는 것도 아니다.

DB 볼륨과 Compose의 down 옵션

볼륨 정리의 ‘미사용’은 어떤 컨테이너도 참조하지 않는 상태를 말한다. 다음 주 다시 켤 프로젝트의 DB도 컨테이너를 제거한 직후에는 이 조건에 해당할 수 있다. 데이터의 업무상 가치까지 Docker가 판단한 결과는 아니다.

현재 docker volume prune의 기본 대상은 미사용 익명 볼륨이고, --all 또는 -a를 붙이면 이름 있는 미사용 볼륨도 포함된다. 이 옵션은 Docker API 1.42 이상을 지원하는 환경에서 사용할 수 있다. 따라서 ‘볼륨이 남았다’는 결과만 보고 정리가 실패했다고 생각해 옵션을 넓히면 보관하려던 DB까지 지울 수 있다. 계속 쓸 DB 볼륨은 정리 목록에서 남기고, 데이터 자체를 줄여야 한다면 해당 DB의 보관 정책과 백업 절차로 처리한다.

Compose의 기본 down은 프로젝트 컨테이너와 네트워크를 제거하지만 볼륨은 기본적으로 제거하지 않는다. 이름 있는 볼륨을 다음 실행에도 다시 쓰려는 개발 작업에서는 이 차이가 유용하다. 여기에 -v를 붙이면 Compose 파일에 선언한 이름 있는 볼륨과 연결된 익명 볼륨까지 제거한다. external로 선언한 볼륨은 이 삭제 대상에서 제외된다.

익명 볼륨이 남았다는 사실과 다음 up에서 자동으로 다시 연결된다는 것은 다르다. Compose는 익명 볼륨에 안정적인 이름이 없어 다음 실행에서 자동으로 같은 것을 마운트하지 않는다고 설명한다. 재사용할 데이터에는 이름 있는 볼륨이나 명시적인 bind 경로를 사용하면 어느 자료를 다시 연결할지 표현할 수 있다.

Mac의 Docker.raw 크기와 실제 디스크 회수

한 맥 사용자는 Docker.raw가 494GB로 보였다며 용량 한도를 낮춘 경험을 공유했다. 댓글에서는 파일의 최대 크기와 실제 점유량이 다를 수 있다는 지적이 이어졌다. 이 사례에서 바로 따라 할 부분은 숫자만 보고 한도를 내리는 행동이 아니라, Docker가 표시하는 실제 사용량을 찾아보는 절차다.

Docker Desktop의 Mac 안내에 따르면 Linux 컨테이너와 이미지는 맥의 큰 디스크 이미지 파일 안에 저장된다. Settings→Resources→Advanced에서 파일 위치, 최대 크기, 실제 사용 공간을 확인한다. 다른 파일 도구가 보여주는 큰 숫자는 최대 크기일 수 있다.

정리 뒤 호스트의 공간 회수에는 몇 분이 걸릴 수 있다. 실행 중인 컨테이너 안에서 파일만 지운 경우에는 자동 회수가 되지 않을 수 있으며, 공식 안내는 다음 회수 명령을 제공한다. 이 명령은 Docker Desktop for Mac의 회수 절차에 해당한다.

docker run --privileged --pid=host docker/desktop-reclaim-space

--privileged와 --pid=host를 사용하는 명령이므로, 앞에서 확인한 로컬 Desktop 연결에서 실행한다. 원격 운영 Docker의 일반 정리 명령으로 옮겨 쓰지 않는다. 실행 뒤에는 Desktop의 실제 점유량과 호스트 여유 공간을 다시 비교한다.

디스크 한도 슬라이더를 낮추는 것은 이 회수 작업과 다르다. Docker는 한도를 줄일 때 현재 디스크 이미지 파일을 삭제하고 컨테이너와 이미지를 잃는다고 설명한다. 단지 큰 표시값을 줄이기 위해 사용하는 정리 버튼이 아니다. 용량을 더 확보하려고 저장 위치를 옮길 때도 Finder에서 파일을 직접 이동하는 대신 Desktop의 Disk image location 설정을 사용한다.

마지막으로 처음 조회했던 같은 Docker 대상에서 docker system df -v를 다시 실행한다. 프로젝트를 재개하면 DB가 원래 볼륨에 연결되는지, 캐시를 지운 빌드가 새로 완료되는지 확인한다.