Docker 캐시 문제 (레이어 캐시, no-cache, yt-dlp 업데이트)
솔직히 저는 Docker의 레이어 캐시가 이렇게 골치 아픈 문제를 만들어낼 줄 몰랐습니다. 단순히 “빌드를 빠르게 해주는 기능”이라고만 생각했는데, Synology NAS에 서비스를 배포하면서 yt-dlp가 캐시에 묶여 업데이트가 안 되는 상황을 직접 겪고 나서야 비로소 캐시 전략이 얼마나 중요한지 깨달았습니다. 이 글은 그 삽질의 기록입니다.
Docker 레이어 캐시, 알고 보니 양날의 검이었습니다
Docker의 레이어 캐시(Layer Cache)란 Dockerfile의 각 명령어(RUN, COPY 등)가 실행될 때마다 생성되는 중간 결과물을 저장해두는 기능을 뜻합니다. 쉽게 말해 “이미 만들어둔 부분은 다시 만들지 않겠다”는 방식입니다. 덕분에 빌드 시간이 크게 줄어드는 건 사실입니다.
그런데 제가 직접 써봤는데, 이 캐시가 은근히 배신을 칩니다. 처음에 저는 Dockerfile 안에 다음과 같이 작성했습니다.
RUN pip3 install –no-cache-dir –upgrade yt-dlp
–upgrade 옵션을 붙였으니 당연히 빌드할 때마다 최신 버전을 받겠거니 했습니다. 그런데 빌드 로그를 확인해보니 “Using cache”라는 메시지가 떡하니 찍혀 있었습니다. Docker 입장에서는 해당 RUN 명령어 앞의 레이어가 변경되지 않았으니 이 단계를 다시 실행할 이유가 없었던 겁니다. –upgrade는 pip 자체의 옵션일 뿐, Docker 캐시를 무효화해주지는 않습니다.
일반적으로 –no-cache 옵션을 docker build에 붙이면 해결된다고 알려져 있습니다. 실제로 docker build –no-cache를 사용하면 모든 레이어를 처음부터 다시 빌드합니다. –no-cache란 Docker가 이전에 저장해둔 모든 캐시를 무시하고 Dockerfile의 각 명령어를 처음부터 실행하도록 강제하는 옵션입니다. 하지만 제 경험상 이건 근본적인 해결책이 아니었습니다. apt 패키지 재설치, npm ci 재실행, Next.js 전체 빌드까지 전부 새로 돌아가니 시간도 시간이거니와 효율 면에서도 너무 아까웠습니다. yt-dlp 하나 때문에 나머지 전체를 다시 굽는 건 말이 안 됐습니다.
no-cache를 쓰면 된다는 말, 반은 맞고 반은 틀립니다
docker build –no-cache가 해결책처럼 소개되는 경우가 많은데, 저는 이게 상황에 따라 다르다고 생각합니다. 디버깅이나 CI/CD 파이프라인의 nightly build처럼 재현성이 중요한 상황에서는 분명히 유용합니다. 하지만 개발 중 반복 배포 상황이나, 저처럼 특정 패키지 하나만 자주 갱신해야 하는 경우에는 오히려 역효과입니다.
제가 운영하는 서비스에서 각 컴포넌트의 업데이트 주기를 정리해보면 이렇습니다.
- Next.js 앱 코드 — 제가 직접 수정하고 Git에 push할 때만 변경됩니다.
- npm 패키지 — package-lock.json이 바뀔 때, 즉 의존성을 추가하거나 업그레이드할 때 변경됩니다.
- yt-dlp — YouTube의 구조 변화에 대응하기 위해 수시로 업데이트가 필요합니다. 제 코드와는 무관합니다.
이 세 가지를 하나의 빌드 사이클에 묶어버리면, 결국 어느 하나를 바꿀 때마다 나머지도 전부 다시 실행해야 하는 구조가 됩니다. –no-cache는 이 문제를 “전부 다시 하면 되잖아”로 풀어버리는 방식인데, 솔직히 이건 해결책이 아니라 회피에 가깝습니다.
멀티 스테이지 빌드(Multi-Stage Build)도 검토했습니다. 멀티 스테이지 빌드란 하나의 Dockerfile 안에서 빌드 단계와 실행 단계를 분리해, 최종 이미지에는 실행에 필요한 파일만 포함시키는 기법입니다. 이미 이 방식을 사용하고 있었지만, yt-dlp 업데이트 주기 문제는 별개였습니다. 빌드 단계가 분리되어 있어도 캐시가 살아 있는 한 yt-dlp 설치 단계는 다시 실행되지 않았습니다.
결국 Synology 작업 스케줄러로 분리했습니다
처음에는 yt-dlp 전용 컨테이너를 따로 띄우고 Next.js 컨테이너에서 HTTP로 요청하는 구조를 고민했습니다. 구조 자체는 깔끔하지만, 현재 서비스 규모에서 컨테이너를 하나 더 운영하는 건 과한 것 같았습니다. 관리해야 할 요소가 늘어나는 것도 부담이었고요.
그래서 선택한 방법이 Synology NAS의 작업 스케줄러입니다. 이미 NAS 위에서 Docker를 돌리고 있으니, 굳이 컨테이너 내부에 cron을 넣지 않고 외부에서 docker exec 명령으로 컨테이너 안의 yt-dlp를 업데이트하면 된다는 발상이었습니다. docker exec란 실행 중인 컨테이너 내부에서 명령어를 직접 실행할 수 있게 해주는 Docker 명령입니다.
그런데 여기서 또 하나의 벽을 만났습니다. Synology에서 다음 명령을 실행했더니 예상치 못한 오류가 발생했습니다.
docker exec tubestudynote pip3 install –no-cache-dir –upgrade yt-dlp
오류 메시지는 “error: externally-managed-environment”였습니다. 이것은 PEP 668과 관련된 Debian 계열 Python 환경의 보호 정책입니다. PEP 668이란 시스템 Python 환경에 pip로 패키지를 임의 설치하지 못하도록 막는 규격으로, 주로 Debian 12(Bookworm) 이후 배포판에서 적용됩니다. 처음에는 pip가 제대로 설치되지 않은 줄 알고 한참을 헤맸는데, 알고 보니 의도된 제한이었습니다. 해결 방법은 –break-system-packages 옵션을 추가하는 것이었습니다. 이 옵션은 시스템 Python 환경의 보호를 우회해서 패키지를 설치하도록 허용합니다.
최종적으로 Synology 작업 스케줄러에 등록한 명령은 이렇습니다.
docker exec tubestudynote pip3 install –no-cache-dir –upgrade –break-system-packages yt-dlp
이렇게 하면 Docker 이미지를 새로 빌드하지 않고도, 실행 중인 컨테이너 안의 yt-dlp만 주기적으로 최신 버전으로 갱신할 수 있습니다. 그리고 이 방식을 쓰려면 런타임 이미지에 python3-pip도 설치되어 있어야 합니다. 저는 처음에 실행 단계에서 python3-pip를 제외했다가 나중에 다시 추가했습니다. 작은 실수였지만 덕분에 Dockerfile을 한 번 더 점검하는 계기가 됐습니다.
Docker 공식 문서(출처: Docker 공식 빌드 캐시 문서)에서도 레이어 캐시의 동작 방식과 무효화 조건을 상세히 설명하고 있습니다. 캐시가 어떤 조건에서 깨지는지 이해하면 Dockerfile을 훨씬 효율적으로 설계할 수 있습니다.
역할 분리가 핵심이었습니다
이번 작업을 마치고 나서 구조를 정리해보니, 결국 핵심은 각 컴포넌트의 업데이트 주기와 책임을 명확히 분리하는 것이었습니다. 모든 것을 Docker 빌드 한 방에 해결하려고 했던 게 문제의 출발점이었습니다.
현재 최종 구조는 이렇습니다. GitHub Actions가 Git push를 감지해서 Docker 이미지를 빌드하고 Next.js 서비스를 배포합니다. 그리고 별도로 Synology 작업 스케줄러가 주기적으로 docker exec를 실행해서 컨테이너 내부의 yt-dlp만 업데이트합니다. 두 흐름이 완전히 독립적으로 돌아갑니다.
이 방식이 모든 상황에 맞는 건 아닙니다. 대규모 프로덕션 환경이라면 컨테이너 외부에서 내부 상태를 직접 변경하는 방식보다는 전용 컨테이너나 별도의 배포 파이프라인이 맞을 수 있습니다. 하지만 Synology NAS에서 개인 프로젝트를 운영하는 현재 규모에서는, 이 정도 단순함이 오히려 장점이라고 판단했습니다. 복잡도를 낮게 유지하는 것도 중요한 설계 결정입니다.
또한 yt-dlp의 업데이트 현황과 릴리즈 노트는 yt-dlp 공식 GitHub 릴리즈 페이지에서 확인할 수 있습니다. 업데이트 빈도가 꽤 잦기 때문에, 자동 갱신 설정 없이 Docker 캐시에만 의존하면 어느 순간 YouTube에서 자막이 제대로 안 받아지는 상황이 생길 수 있습니다. 제가 직접 겪어봤습니다.
자주 묻는 질문
Q. docker build –no-cache를 쓰면 항상 최신 yt-dlp가 설치되지 않나요?
A. 기술적으로는 맞습니다. –no-cache를 사용하면 모든 레이어가 처음부터 다시 실행되니 그 시점의 최신 yt-dlp가 설치됩니다. 하지만 제 경험상 이건 yt-dlp 하나 때문에 apt 패키지 설치, npm ci, Next.js 빌드까지 전부 다시 돌리는 셈이라 시간과 자원 낭비가 큽니다. 코드 변경 없이 yt-dlp만 갱신하고 싶을 때는 비효율적인 방법입니다.
Q. PEP 668 오류는 왜 발생하고, –break-system-packages 말고 다른 해결책은 없나요?
A. PEP 668은 Debian 12 이후 Python 환경에서 시스템 패키지 매니저 외의 방법으로 패키지를 설치하지 못하도록 보호하는 정책입니다. 대안으로는 가상 환경(venv)을 생성해서 그 안에 yt-dlp를 설치하는 방법이 있습니다. 다만 Docker 컨테이너처럼 이미 격리된 환경에서는 –break-system-packages로 단순하게 처리하는 것이 현실적으로 더 간편합니다.
Q. Synology 작업 스케줄러 말고 컨테이너 내부 cron으로 처리하면 안 되나요?
A. 가능합니다. 컨테이너 안에 cron을 설치하고 주기적으로 pip upgrade를 실행하도록 설정할 수 있습니다. 하지만 그렇게 하면 컨테이너가 단일 프로세스를 실행하는 Docker의 철학에서 벗어나고, 컨테이너 이미지가 무거워집니다. 이미 Synology NAS라는 호스트 환경이 있다면 그 환경의 스케줄러를 활용하는 편이 구조적으로 더 깔끔합니다.
Q. docker exec로 변경한 내용은 컨테이너 재시작 후에도 유지되나요?
A. 이 부분이 핵심입니다. docker exec로 컨테이너 내부를 변경해도, 컨테이너가 삭제되고 이미지로부터 새로 생성되면 변경 내용이 사라집니다. 따라서 이 방식은 컨테이너가 재생성되지 않고 계속 실행 중인 환경에서만 유효합니다. 저는 Synology에서 재시작 시 기존 컨테이너를 그대로 재개하는 방식을 사용하고 있어 문제가 없었습니다.
Docker를 처음 쓸 때는 캐시를 “그냥 빠르게 해주는 것” 정도로만 생각했는데, 이번 경험으로 캐시 전략 자체가 하나의 설계 결정이라는 걸 다시 느꼈습니다. 업데이트 주기가 다른 컴포넌트를 하나의 Dockerfile에 욱여넣기 전에, 각각의 갱신 주기와 책임을 먼저 정의하는 것이 훨씬 중요합니다. 비슷한 고민을 하고 있다면, 먼저 어떤 컴포넌트가 어떤 이유로 얼마나 자주 바뀌는지를 정리해보는 것에서 시작해보시길 권합니다.
—
참고: https://www.cloudbees.com/blog/docker-build-without-cache
https://docs.docker.com/build/cache/
https://github.com/yt-dlp/yt-dlp/releases