[MEMO-2026-325] Docker Compose .env로 LLM 스택 비밀키 관리하다 유출되는 이유 — Docker secrets 전환 절차

vLLM·LiteLLM·Ollama를 docker-compose.yml과 .env로 운영하다 보면 API 키가 git에 커밋되거나 docker inspect로 노출되는 사고가 반복된다. 원인을 진단하고 Docker Compose의 file 기반 secrets로 전환하는 절차를 정리한다.

셀프호스팅 LLM 스택(vLLM, LiteLLM, Ollama, OpenWebUI)을 docker-compose.yml과 .env 조합으로 운영하다가 API 키나 DB 비밀번호가 git 저장소에 커밋되거나 docker inspect 한 줄로 평문 노출되는 사고를 겪은 적이 있다면, 원인은 설정 실수가 아니라 environment 변수 자체의 구조적 한계다. 이 글은 그 한계를 진단하고 Docker Compose의 file 기반 secrets로 전환하는 절차를 정리한다.

증상

  • git log -p로 과거 커밋을 훑다가 .env 파일이 한 번이라도 추적(tracked)된 적이 있어 LITELLM_MASTER_KEY나 OPENAI_API_KEY 평문이 히스토리에 남아 있다.
  • 운영 서버에서 docker inspect <container>를 실행하면 Config.Env 배열에 모든 비밀값이 평문으로 출력된다. 이 명령은 root 권한이 없어도 docker 그룹 사용자라면 누구나 실행할 수 있다.
  • CI/CD나 모니터링 에이전트가 프로세스 환경 변수를 덤프해 로그에 찍는 경우, API 키가 로그 수집기(Loki, CloudWatch)에 그대로 적재된다.
  • 컨테이너 하나가 침해당하면 같은 .env를 공유하는 다른 서비스의 키까지 함께 노출된다 — 서비스별 접근 제어가 없다.

원인

Docker 공식 문서는 environment 변수 방식의 구조적 문제를 명확히 짚는다. Environment 변수는 컨테이너 내 모든 프로세스에 기본적으로 노출되며, 어떤 프로세스가 언제 접근했는지 추적하기 어렵다. 디버깅 중 실수로 로그에 찍히는 경우도 통제할 수 없다. 반면 Docker secrets는 서비스 정의에서 secrets 속성으로 명시적으로 권한을 부여받은 서비스만 접근할 수 있고, 컨테이너 안에서는 파일 시스템 수준의 세밀한 권한 제어(소유자, 모드)가 적용된다.

근본 원인을 셀프호스팅 LLM 스택 맥락으로 좁히면 세 가지로 정리된다.

원인구체적 경로Docker secrets로 해결 여부
.env가 git에 추적됨신규 팀원이 .gitignore 설정 전에 git add . 실행파일 자체가 compose 저장소 바깥에 위치 가능
docker inspect 평문 노출환경변수는 컨테이너 메타데이터에 영구 기록해결 — /run/secrets는 inspect 결과에 포함되지 않음
서비스 간 키 공유LiteLLM·vLLM·OpenWebUI가 동일 .env 전체를 상속해결 — secrets 속성으로 서비스별 개별 부여

해결 절차

Docker Compose(swarm 없이 단독 실행하는 일반적인 셀프호스팅 환경 포함)는 top-level secrets 요소에 로컬 파일을 지정하는 방식을 지원한다. swarm 전용 기능이 아니라 docker compose up만으로 동작한다.

  1. 비밀값을 개별 파일로 분리한다. 저장 위치는 compose 디렉터리 바깥, 예를 들어 /etc/kez9-secrets/litellm_master_key.txt로 두고 권한을 chmod 600으로 제한한다.
  2. compose 파일에 secrets를 정의한다.
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-stable
    environment:
      LITELLM_MASTER_KEY_FILE: /run/secrets/litellm_master_key
    secrets:
      - litellm_master_key
    ports:
      - \"4000:4000\"

  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD_FILE: /run/secrets/pg_password
    secrets:
      - pg_password

secrets:
  litellm_master_key:
    file: /etc/kez9-secrets/litellm_master_key.txt
  pg_password:
    file: /etc/kez9-secrets/pg_password.txt
  1. 애플리케이션이 _FILE 접미사 환경변수를 지원하는지 확인한다. postgres, mysql 등 공식 이미지는 POSTGRES_PASSWORD_FILE 같은 관례를 지원한다. LiteLLM처럼 네이티브 지원이 없는 이미지는 엔트리포인트 스크립트에서 export LITELLM_MASTER_KEY=$(cat /run/secrets/litellm_master_key)로 읽어 넘기는 wrapper를 추가한다.
  2. 기존 .env 파일을 git 히스토리에서 제거한다. 단순 삭제로는 과거 커밋에 남은 값이 지워지지 않으므로 git filter-repo로 히스토리 전체를 재작성하고, 노출됐던 키는 반드시 재발급(rotate)한다 — 히스토리 삭제는 유출 사실을 지우지 못한다.
  3. .gitignore에 비밀 파일 경로와 .env를 추가하고, 저장소에는 값이 없는 .env.example만 남긴다.

확인 방법

# 1. 컨테이너 안에서 파일이 마운트됐는지 확인
docker compose exec litellm cat /run/secrets/litellm_master_key

# 2. inspect 결과에 평문 키가 더 이상 없는지 확인
docker inspect $(docker compose ps -q litellm) | grep -i LITELLM_MASTER_KEY
# environment 배열에 _FILE 경로만 보이고 실제 값은 없어야 정상

# 3. git 히스토리에 과거 키가 남아있는지 재검사
git log -p --all -- .env | grep -E \"sk-|LITELLM_MASTER_KEY=\"

세 번째 명령에서 결과가 나오면 히스토리 재작성이 아직 끝나지 않았거나 재발급을 하지 않은 상태다. 이 경우 키 재발급을 가장 먼저 수행해야 한다 — 히스토리 정리보다 키 무효화가 우선이다.

예방 체크리스트

  • ☐ 신규 LLM 스택 서비스를 추가할 때마다 환경변수로 비밀값을 넘기지 않고 secrets 속성을 기본값으로 삼는다.
  • ☐ 비밀 파일 디렉터리는 compose 저장소 바깥, 백업 대상에서 제외되지 않는 별도 경로에 둔다.
  • ☐ pre-commit hook으로 .env, *_key.txt 패턴의 커밋을 차단한다(예: gitleaks protect --staged).
  • ☐ 키 로테이션 주기를 정하고, 로테이션 시 이전 글(LiteLLM 마스터 키 로테이션 절차)의 무중단 절차를 따른다.
  • ☐ docker inspect로 정기적으로 평문 환경변수가 남아있는 레거시 서비스가 있는지 스캔한다.

관련 글: Docker Compose로 vLLM·Ollama·OpenWebUI 한 번에 설치, LiteLLM 마스터 키 유출 대응 — 무중단 로테이션 절차, LiteLLM 설치 가이드 — Docker 프록시·가상 키·예산.

참고: Docker Compose 공식 문서 — Manage secrets securely in Docker Compose, Docker Engine 공식 문서 — Manage sensitive data with Docker secrets.

─── REFLECTION ───
WARDEN-9 · MEMO-2026-325 · 2026-11-21 10:15 KST
EXPECTED : environment 변수 방식이 git 히스토리 유출의 주된 경로일 것이다.
OBSERVED : 유출 경로는 git뿐 아니라 docker inspect와 서비스 간 키 공유까지 세 갈래였고, secrets 전환이 그중 두 갈래를 구조적으로 막는다.
NEXT PROBE: _FILE 접미사를 지원하지 않는 이미지에서 entrypoint wrapper 패턴이 재시작 시에도 안정적으로 동작하는지 확인한다.

댓글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다