Docker SSL 인증서 오류 (배경, 원인분석, Dockerfile 수정)

Docker 경량 이미지를 쓰다 보면 로컬에서는 멀쩡히 돌아가던 게 배포 환경에서 갑자기 HTTPS 요청에 실패하는 경우가 있습니다. 저도 그걸 직접 겪었습니다. Synology NAS에 Next.js 프로젝트를 배포했더니 웹사이트는 잘 열리는데 자막 API만 500 에러를 뱉는 상황이었습니다. 원인은 생각보다 단순했지만, 찾아가는 과정은 전혀 단순하지 않았습니다.

웹사이트는 되는데 API만 죽는 상황의 배경

처음 증상을 보고 제가 제일 먼저 의심한 건 Apache 역방향 프록시(Reverse Proxy) 설정이었습니다. 역방향 프록시란 외부에서 들어오는 요청을 받아서 내부 서버로 전달해 주는 중간 서버를 말합니다. 이 구성에서 뭔가 잘못됐으면 웹사이트도 같이 안 열렸을 텐데, 페이지는 정상이고 API만 죽어있으니 그게 아닌 건 금방 알 수 있었습니다.

그래서 NAS에서 직접 컨테이너에 접속해 봤습니다. curl http://172.30.1.95:3002 명령을 실행했더니 HTML이 멀쩡하게 돌아왔습니다. 포트 매핑(Port Mapping), 즉 NAS의 3002번 포트와 컨테이너 내부 3000번 포트를 연결하는 설정도 정상이라는 뜻이었습니다. 그렇다면 문제는 컨테이너 내부의 실행 환경에 있을 가능성이 높았습니다.

브라우저에서 API 응답을 직접 열어 봤을 때 단서가 나왔습니다. 상태 코드만 보여주는 게 아니라 서버에서 실행한 명령어와 에러 로그까지 그대로 반환되고 있었습니다. 핵심 메시지는 이것이었습니다.

certificate verify failed: unable to get local issuer certificate

yt-dlp가 YouTube에 HTTPS로 접속하는 과정에서 SSL 인증서(SSL Certificate) 검증에 실패한 것입니다. SSL 인증서란 서버가 “나는 신뢰할 수 있는 곳입니다”라고 증명하는 디지털 문서로, 이걸 검증하지 못하면 HTTPS 연결 자체가 성립하지 않습니다. 웹사이트 렌더링은 브라우저가 직접 처리하지만, yt-dlp의 YouTube 요청은 컨테이너 내부에서 실행됩니다. 그래서 웹사이트는 열리고 API만 죽는 기묘한 현상이 만들어졌던 겁니다.

SSL 인증서 검증 실패의 구조적 원인 분석

HTTPS 연결이 성립하려면 인증서 체인(Certificate Chain)이라는 신뢰 구조가 필요합니다. 인증서 체인이란 서버 인증서에서 출발해서 중간 인증기관(Intermediate CA)을 거쳐 최상위 루트 인증기관(Root CA)까지 이어지는 신뢰의 연결고리를 말합니다. 브라우저나 시스템은 이 루트 CA가 자신의 신뢰 목록에 있는지 확인하고, 있으면 연결을 허용합니다.

이 프로젝트에서는 node:20-slim 이미지를 베이스로 사용했습니다. slim 이미지는 이름처럼 불필요한 패키지를 최대한 줄인 경량 이미지입니다. 용량을 아끼는 대신 시스템 패키지를 직접 챙겨야 한다는 게 전제입니다. 그런데 저는 python3, ffmpeg, curl 같은 실행에 필요한 패키지는 챙겼지만, CA 인증서 번들(CA Certificate Bundle)은 빠뜨렸습니다. CA 인증서 번들이란 시스템이 신뢰하는 루트 인증기관 목록을 담은 파일 묶음으로, 이게 없거나 오래된 버전이면 최신 HTTPS 사이트 접속에서 검증 실패가 발생할 수 있습니다.

참고로 비슷한 문제가 node:16-alpine 이미지에서도 보고된 바 있습니다. 이쪽은 서드파티 API가 Sectigo R46 루트를 쓰는 새 인증서 체인으로 갱신했는데, Alpine 이미지의 CA 번들이 오래돼서 R46을 모르는 상태였습니다. 결과적으로 서버가 R36 → R46 체인을 내밀어도 컨테이너가 R46을 신뢰 목록에서 찾지 못해서 연결이 끊긴 겁니다. 제 상황도 구조는 동일했습니다. 컨테이너가 YouTube의 인증서 체인 상단에 있는 루트 CA를 알아보지 못한 것입니다.

이런 SSL 검증 실패가 발생할 수 있는 주요 상황을 정리하면 다음과 같습니다.

  1. 경량 Docker 이미지에 ca-certificates 패키지가 아예 설치되지 않은 경우
  2. CA 번들이 오래돼서 최근에 추가된 루트 인증기관을 포함하지 않는 경우
  3. 기업 네트워크나 특정 프록시 환경에서 중간 인증서를 가로채서 교체하는 경우
  4. 멀티 스테이지 빌드(Multi-stage Build)에서 빌드 단계에만 패키지를 설치하고 런타임 단계에는 빠뜨린 경우

제 경우는 첫 번째였습니다. 솔직히 이건 예상 밖이었습니다. HTTPS 접속 자체가 막힌 게 아니라 인증서를 검증할 참고 자료가 없어서 실패하는 상황이라는 걸 처음에는 바로 파악하지 못했습니다. Docker 공식 빌드 가이드라인에서도 경량 이미지 사용 시 필요한 시스템 패키지를 명시적으로 설치할 것을 권고하고 있는데, CA 인증서가 바로 그런 항목 중 하나입니다.

Dockerfile 한 줄 수정으로 해결한 과정

원인을 파악하고 나니 수정 자체는 간단했습니다. Dockerfile의 런타임 이미지 패키지 설치 명령에 ca-certificates 하나를 추가했습니다.

기존 설치 명령은 이렇게 돼 있었습니다. python3, ffmpeg, curl, bash를 설치하고 apt 캐시를 지우는 구조였습니다. 여기에 ca-certificates를 끼워 넣었고, 이것 하나로 컨테이너가 신뢰할 수 있는 루트 인증기관 목록을 갖추게 됩니다.

수정 시 한 가지 주의할 점이 있었습니다. 이 프로젝트는 빌드 단계와 런타임 단계를 분리한 멀티 스테이지 빌드(Multi-stage Build) 구조를 사용하고 있었습니다. 멀티 스테이지 빌드란 하나의 Dockerfile 안에서 여러 단계를 나눠 빌드 시에만 필요한 도구는 최종 이미지에서 제외하는 방식입니다. 이 구조에서는 빌드 단계에 패키지를 설치해도 런타임 단계에 자동으로 넘어오지 않습니다. 제가 직접 써봤는데, 이걸 간과하면 빌드는 성공해도 실행 환경에서 또 같은 오류가 납니다. ca-certificates는 반드시 yt-dlp가 실제로 실행되는 런타임 이미지에 설치해야 합니다.

한편 이 과정에서 또 다른 오류와도 마주쳤습니다. Debian 계열 이미지에서 pip로 yt-dlp를 설치하려 하면 PEP 668 정책에 따라 externally-managed-environment 오류가 발생합니다. externally-managed-environment란 시스템 Python 환경을 pip가 직접 수정하지 못하도록 막는 Debian의 패키지 관리 정책입니다. 이 오류와 SSL 검증 실패는 완전히 별개의 문제라서 각각 따로 처리해야 합니다. 두 오류를 뭉뚱그려서 하나의 해결책을 찾으려 하면 오히려 시간을 더 씁니다. 제 경험상 이건 좀 다릅니다.

수정한 이미지를 다시 빌드하고 배포했습니다. docker-compose down 후 docker-compose up -d –build 로 이미지를 새로 만들고, docker logs -f 로 컨테이너 로그를 확인했습니다. 컨테이너가 정상 기동됐고, API를 다시 테스트했을 때 yt-dlp가 YouTube에 정상적으로 접속해서 자막 정보를 가져왔습니다. OpenSSL 공식 문서에서도 인증서 체인 검증에 로컬 CA 번들이 필수임을 설명하고 있는데, 이번 경험으로 그 의미를 실감했습니다.

자주 묻는 질문

Q. node:20-slim 말고 node:20-alpine 이미지에서도 같은 방법이 통하나요?

A. Alpine 이미지에서는 apt-get 대신 apk 패키지 관리자를 사용합니다. 명령어 형태가 달라서 apk –no-cache add ca-certificates 로 설치하면 됩니다. 설치 후 update-ca-certificates를 실행해서 CA 번들을 갱신하는 단계도 함께 넣는 것이 좋습니다. 근본적인 원리는 동일합니다.

Q. NODE_EXTRA_CA_CERTS 환경변수는 꼭 설정해야 하나요?

A. NODE_EXTRA_CA_CERTS란 Node.js가 시스템 CA 번들 외에 추가로 참조할 인증서 파일 경로를 지정하는 환경변수입니다. yt-dlp처럼 Node.js가 아닌 Python 프로세스가 HTTPS 요청을 보내는 경우라면 이 환경변수는 효과가 없습니다. Python은 자체적으로 certifi 패키지나 시스템 CA 번들을 참조하기 때문입니다. ca-certificates 패키지를 설치해서 시스템 번들 자체를 최신화하는 방법이 Node.js와 Python 모두에 적용되는 근본 해결책입니다.

Q. 로컬 개발 환경에서는 왜 오류가 없었나요?

A. 로컬 macOS나 Windows 환경에서는 운영체제가 관리하는 CA 번들이 자동으로 업데이트됩니다. 반면 Docker 컨테이너는 이미지를 빌드할 당시의 패키지 상태를 그대로 유지합니다. 이미지를 오래 쓸수록 CA 번들이 오래돼서 최신 인증서 체인을 모를 가능성이 높아집니다. 주기적으로 베이스 이미지를 최신 버전으로 업데이트하는 것이 예방책입니다.

Q. 멀티 스테이지 빌드에서 ca-certificates를 어느 단계에 설치해야 하나요?

A. 외부 HTTPS 요청이 실제로 발생하는 단계, 즉 런타임(실행) 단계의 이미지에 설치해야 합니다. 빌드 단계에서 설치한 패키지는 COPY –from 명령으로 명시적으로 가져오지 않는 한 런타임 이미지에 포함되지 않습니다. 이 부분을 놓치면 빌드는 성공해도 배포 후 동일한 SSL 오류가 재발합니다.

Q. ca-certificates를 설치하면 보안상 문제는 없나요?

A. ca-certificates 패키지는 공식 배포판이 관리하는 신뢰할 수 있는 루트 인증기관 목록을 설치하는 것입니다. 이 자체로 보안 취약점이 생기지는 않습니다. 오히려 HTTPS 검증을 우회하는 NODE_TLS_REJECT_UNAUTHORIZED=0 설정이나 –no-check-certificate 옵션이 훨씬 위험합니다. 임시방편으로 TLS 검증을 끄는 방법을 쓰다가 그대로 운영에 배포하는 경우가 종종 있는데, ca-certificates를 제대로 설치하는 것이 맞는 방향입니다.

Docker 경량 이미지는 분명히 편리한 도구입니다. 그런데 slim이나 alpine이라는 이름이 붙는 순간 “가볍다”는 것의 의미를 정확히 이해하고 써야 합니다. CA 인증서처럼 당연히 있을 거라고 여기던 것들이 빠져 있을 수 있습니다. 배포 환경에서 이상 증상이 생기면 웹 서버와 포트 설정만 볼 게 아니라, 컨테이너 내부의 시스템 패키지 상태까지 점검 범위에 넣는 것이 시간을 아끼는 방법입니다. 같은 오류를 만났다면 Dockerfile에 ca-certificates 한 줄 추가하는 것부터 시도해 보시길 권합니다.

—
참고: https://medium.com/@sathish.msthamby/resolving-unable-to-get-local-issuer-certificate-error-in-node-js-docker-alpine-7792339ec9d3

Similar Posts