Django check --deploy 활용법: 배포 전 점검 가이드

Django 배포 전 check --deploy는 어떻게 쓸까요? 운영 settings로 실행해 DEBUG, SECRET_KEY, HTTPS, 미디어 경로 경고를 하나씩 해결하는 방법을 정리했습니다.

조회 23
Django check --deploy 활용법: 배포 전 점검 가이드

핵심 요약

  • check --deploy는 반드시 운영 settings를 지정해 실행한다
  • DEBUG, SECRET_KEY, HTTPS 설정은 프록시 구조에 맞게 적용한다
  • 미디어 노출은 명령이 못 잡으니 직접 점검하고 CI에 fail-level을 둔다

manage.py check --deploy는 운영 설정에서 빠뜨리기 쉬운 항목을 경고로 알려 주는 명령입니다. 배포 직전에 한 번 돌리고, 경고가 나온 항목을 하나씩 지우는 방식으로 쓰면 됩니다. Django 배포 체크리스트에 따르면 이 문서의 점검 항목 중 일부를 이 옵션으로 자동화할 수 있습니다. 같은 문서가 짚듯이 반드시 운영 설정 파일을 대상으로 실행해야 합니다.

먼저 운영 설정으로 실행하기

개발 설정으로 돌리면 의미 있는 결과가 나오지 않습니다. 운영용 settings 모듈을 지정해서 실행하세요.

python manage.py check --deploy --settings=config.settings.production

경고를 없애려고 SILENCED_SYSTEM_CHECKS에 넣는 방법도 있지만, 이유를 설명할 수 없다면 쓰지 않는 편이 낫습니다. 문서는 HTTPS 강제처럼 모든 사이트에 맞지는 않는 보안 기능이 있다고 설명합니다. 그런 항목은 경고를 끄기 전에 서비스 구조에 필요한지 먼저 판단해야 합니다.

CI에 넣을 때는 --fail-level WARNING 옵션을 쓰면 경고가 하나라도 있을 때 실패 코드를 반환하게 만들 수 있습니다. 배포 파이프라인 앞단에 두면 점검을 빼먹을 일이 없습니다.

DEBUG와 SECRET_KEY 정리

가장 먼저 볼 항목은 DEBUG입니다. 운영에서 True이면 오류 페이지에 설정값과 내부 정보가 노출됩니다. DEBUG = False로 바꾸면 ALLOWED_HOSTS를 반드시 채워야 하니 도메인도 함께 확인하세요.

SECRET_KEY는 코드에 넣지 않고 환경 변수나 비밀 저장소로 분리하는 것이 권장됩니다. Django 체크리스트는 데이터베이스 비밀번호도 SECRET_KEY와 똑같이 보호하라고 말합니다. 최소한의 형태는 아래와 같습니다.

import os
from django.core.exceptions import ImproperlyConfigured

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY")
if not SECRET_KEY:
    raise ImproperlyConfigured("DJANGO_SECRET_KEY가 설정되지 않았습니다")

DEBUG = os.environ.get("DJANGO_DEBUG", "") == "1"

값이 없으면 기동을 막아 두면 빈 키로 서비스가 뜨는 사고를 막을 수 있습니다. 이미 저장소 히스토리에 키가 올라갔다면 파일에서 지우는 것만으로는 부족합니다. 키를 새로 발급해 교체하세요.

HTTPS 관련 경고 하나씩 해결하기

HTTPS 관련 경고는 보통 아래 설정들을 가리킵니다. 각 설정의 의미는 Django 보안 문서에서 확인할 수 있습니다.

설정 하는 일
SECURE_SSL_REDIRECT HTTP 요청을 HTTPS로 리다이렉트
SESSION_COOKIE_SECURE 세션 쿠키를 HTTPS로만 전송
CSRF_COOKIE_SECURE CSRF 쿠키를 HTTPS로만 전송
SECURE_HSTS_SECONDS 브라우저에 HTTPS 전용 접속을 지시

nginx 같은 프록시 뒤에서 HTTPS를 종료한다면 주의할 점이 있습니다. Django는 프록시가 전달하는 요청을 HTTP로 인식하므로 SECURE_PROXY_SSL_HEADER 설정이 필요합니다. 설정하지 않은 채 SECURE_SSL_REDIRECT만 켜면 무한 리다이렉트에 빠질 수 있습니다.

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

nginx 쪽에는 proxy_set_header X-Forwarded-Proto $scheme;를 넣어야 합니다. 이 헤더를 클라이언트가 위조해서 보낼 수 없도록 프록시가 항상 덮어쓰는 구조여야 합니다. 그렇지 않으면 이 설정이 오히려 위험해집니다.

HSTS는 한 번 켜면 브라우저가 기억하므로 처음에는 짧은 값으로 시작하세요. 서브도메인까지 영향을 주는 옵션은 모든 서브도메인이 HTTPS를 지원한다는 확신이 있을 때만 켜야 합니다.

미디어와 정적 파일 노출 점검

check --deploy가 모든 것을 잡아 주지는 않습니다. 사용자 업로드 파일이 저장되는 MEDIA_ROOT는 특히 직접 점검해야 합니다. 체크리스트 문서가 정적 파일과 미디어를 별도 항목으로 다루는 만큼, 두 경로를 분리해서 확인하는 것이 좋습니다.

  • 업로드 경로가 소스 코드나 설정 파일이 있는 디렉터리와 겹치지 않는지 확인합니다.
  • nginx에서 미디어 디렉터리의 스크립트 실행을 허용하지 않습니다.
  • 비공개 파일은 MEDIA_URL로 바로 노출하지 말고 인증을 거치는 뷰로 내려 줍니다.
  • 업로드 확장자와 크기를 검증하고, 서버 쪽에서 요청 크기 제한도 둡니다.

운영에서는 Django 개발 서버가 정적·미디어 파일을 서빙하게 두지 않고 nginx나 오브젝트 스토리지에서 처리하세요. 또한 collectstatic 결과물이 어디에 쌓이는지, 그 안에 의도치 않은 파일이 섞이지 않았는지도 한 번 열어 보세요.

실천 가이드

배포 전에 아래 순서로 점검해 보세요.

  1. 운영 settings로 check --deploy를 실행하고 경고 목록을 확보합니다.
  2. DEBUG, ALLOWED_HOSTS, SECRET_KEY를 환경 변수 기반으로 바꿉니다.
  3. 프록시 구조에 맞게 SECURE_PROXY_SSL_HEADER와 쿠키 보안 설정을 적용합니다.
  4. HSTS는 짧은 기간으로 시작해 점차 늘립니다.
  5. 미디어 경로와 업로드 정책을 수동으로 점검합니다.
  6. 경고가 0건이 된 것을 확인하고, CI에 --fail-level WARNING을 추가합니다.

마지막으로 기억할 점은, 경고가 없다고 안전한 것은 아니라는 사실입니다. 이 명령은 설정 수준의 위험만 보여 주므로, 비밀 관리와 파일 노출 같은 운영 습관은 체크리스트로 따로 챙겨야 합니다. 그 기준은 Django 보안 문서와 배포 체크리스트를 기본으로 삼으면 됩니다.

자주 묻는 질문

Q. check --deploy는 어떤 설정 파일로 실행해야 하나요?

반드시 운영 설정 파일을 대상으로 실행해야 합니다. 개발 설정으로 돌리면 의미 있는 결과가 나오지 않으므로 --settings 옵션으로 운영용 settings 모듈을 지정하세요.

Q. nginx 같은 프록시 뒤에서 SECURE_SSL_REDIRECT를 켜면 왜 문제가 되나요?

Django는 프록시가 전달한 요청을 HTTP로 인식하기 때문입니다. SECURE_PROXY_SSL_HEADER를 설정하지 않고 리다이렉트만 켜면 무한 리다이렉트에 빠질 수 있습니다. 프록시가 해당 헤더를 항상 덮어쓰는 구조여야 안전합니다.

Q. 경고가 0건이면 배포해도 안전한가요?

그렇지 않습니다. 이 명령은 설정 수준의 위험만 보여 주며 미디어 파일 노출이나 비밀 관리 같은 운영 습관은 잡아 주지 않습니다. 이런 항목은 체크리스트로 따로 점검해야 합니다.

참고 자료

이 글은 웹 검색으로 확인한 위 출처를 바탕으로 AI(claude-sonnet-5-5)가 작성했습니다. 수치·가격은 출처 원문에서 다시 확인하세요.

#check --deploy#CI#Django#HSTS#HTTPS#SECRET_KEY#배포#보안