feat: 미디어 파일 저장소 설정을 위한 환경 변수 및 .gitignore 업데이트

Author: MU-Software

.gitignore

@@ -249,6 +249,10 @@ django_extensions/*
 static
 static/*
 
+# Django media (self-hosted FileSystemStorage uploads)
+media
+media/*
+
 # Jupyter Notebook
 .ipynb_checkpoints
 .ipynb_checkpoints/*

app/core/settings.py

@@ -7,6 +7,7 @@
 import environ
 import sentry_sdk
 import sentry_sdk.integrations.django
+from django.core.exceptions import ImproperlyConfigured
 
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = pathlib.Path(__file__).resolve().parent.parent
@@ -283,46 +284,66 @@
 # Static files (CSS, JavaScript, Images)
 # https://docs.djangoproject.com/en/5.2/howto/static-files/
 STATIC_ROOT = BASE_DIR / "static"
-MEDIA_ROOT = BASE_DIR / "media"
+# env 로 덮어쓰더라도 항상 pathlib.Path 로 유지한다. (env() 는 값이 설정되면 str 을 반환)
+MEDIA_ROOT = pathlib.Path(env("DJANGO_MEDIA_ROOT", default=BASE_DIR / "media"))
 
 DATA_UPLOAD_MAX_MEMORY_SIZE = 30 * 1024 * 1024  # 30 MB
 FILE_UPLOAD_MAX_MEMORY_SIZE = 30 * 1024 * 1024  # 30 MB
 
-DEFAULT_STORAGE_BACKEND = env("DJANGO_DEFAULT_STORAGE_BACKEND", default="storages.backends.s3.S3Storage")
-STATIC_STORAGE_BACKEND = env("DJANGO_STATIC_STORAGE_BACKEND", default="storages.backends.s3.S3Storage")
+S3_STORAGE_BACKEND = "storages.backends.s3.S3Storage"
+
+DEFAULT_STORAGE_BACKEND = env("DJANGO_DEFAULT_STORAGE_BACKEND", default=S3_STORAGE_BACKEND)
+STATIC_STORAGE_BACKEND = env("DJANGO_STATIC_STORAGE_BACKEND", default=S3_STORAGE_BACKEND)
+
+# AWS S3 모드일 때만 S3 전용 설정을 적용한다. (env 가 S3 백엔드를 가리키면 기존 동작을 그대로 유지)
+# 그 외(FileSystemStorage = 자체 호스팅) 모드에서는 로컬 파일시스템에 맞는 설정만 넣는다.
+USING_S3 = DEFAULT_STORAGE_BACKEND == S3_STORAGE_BACKEND
+
+# default(media/public)와 static 백엔드는 함께 S3 이거나 함께 자체 호스팅이어야 한다.
+# 한쪽만 S3 로 두면 STORAGES["staticfiles"] 가 버킷 없이 구성되어 조용히 깨지므로 시작 시 막는다.
+if USING_S3 != (STATIC_STORAGE_BACKEND == S3_STORAGE_BACKEND):
+    raise ImproperlyConfigured(
+        "DJANGO_DEFAULT_STORAGE_BACKEND 와 DJANGO_STATIC_STORAGE_BACKEND 는 "
+        "둘 다 S3 이거나 둘 다 비-S3(자체 호스팅) 여야 합니다. "
+        f"(default={DEFAULT_STORAGE_BACKEND!r}, static={STATIC_STORAGE_BACKEND!r})"
+    )
 
 PRIVATE_STORAGE_BUCKET_NAME = f"pyconkr-backend-{API_STAGE}"
 PUBLIC_STORAGE_BUCKET_NAME = f"pyconkr-backend-{API_STAGE}-public"
 
-STATIC_URL = (
-    f"https://s3.ap-northeast-2.amazonaws.com/{PRIVATE_STORAGE_BUCKET_NAME}/"
-    if STATIC_STORAGE_BACKEND == "storages.backends.s3.S3Storage"
-    else "static/"
-)
-MEDIA_URL = (
-    f"https://s3.ap-northeast-2.amazonaws.com/{PUBLIC_STORAGE_BUCKET_NAME}/"
-    if DEFAULT_STORAGE_BACKEND == "storages.backends.s3.S3Storage"
-    else "media/"
-)
+if USING_S3:
+    STATIC_URL = f"https://s3.ap-northeast-2.amazonaws.com/{PRIVATE_STORAGE_BUCKET_NAME}/"
+    MEDIA_URL = f"https://s3.ap-northeast-2.amazonaws.com/{PUBLIC_STORAGE_BUCKET_NAME}/"
 
-STATIC_STORAGE_OPTIONS = (
-    {
+    STATIC_STORAGE_OPTIONS = {
         "bucket_name": PRIVATE_STORAGE_BUCKET_NAME,
         "file_overwrite": False,
         "addressing_style": "path",
     }
-    if DEFAULT_STORAGE_BACKEND == "storages.backends.s3.S3Storage"
-    else {}
-)
-PUBLIC_STORAGE_OPTIONS = (
-    {
+    PUBLIC_STORAGE_OPTIONS = {
         "bucket_name": PUBLIC_STORAGE_BUCKET_NAME,
         "file_overwrite": False,
         "addressing_style": "path",
     }
-    if DEFAULT_STORAGE_BACKEND == "storages.backends.s3.S3Storage"
-    else {}
-)
+else:
+    # 자체 호스팅(FileSystemStorage): static·미디어 모두 nginx 가 서빙한다.
+    #  - static: collectstatic -> STATIC_ROOT, nginx 가 STATIC_URL 로 서빙.
+    #  - 미디어(public 업로드): PublicFile 은 upload_to="public/" 이므로 디스크 경로는 MEDIA_ROOT/public/<name>,
+    #    URL 은 MEDIA_URL + "public/<name>" 로 떨어진다. (location/base_url 기본값 = MEDIA_ROOT/MEDIA_URL)
+    STATIC_URL = env("DJANGO_STATIC_URL", default="static/")
+    MEDIA_URL = env("DJANGO_MEDIA_URL", default="media/")
+
+    # URL 뒤에 파일 경로가 그대로 이어붙으므로 끝 슬래시를 보장한다. (예: MEDIA_URL + "public/<name>")
+    if not STATIC_URL.endswith("/"):
+        STATIC_URL += "/"
+    if not MEDIA_URL.endswith("/"):
+        MEDIA_URL += "/"
+
+    # FileSystemStorage 등 로컬 백엔드에는 S3 전용 kwargs(bucket_name 등)를 넘기지 않는다.
+    STATIC_STORAGE_OPTIONS = {}
+    PUBLIC_STORAGE_OPTIONS = {}
+
+# STORAGES 구조는 두 모드 공통이며, OPTIONS 만 위 분기에서 모드별로 채워진다.
 STORAGES = {
     "default": {"BACKEND": DEFAULT_STORAGE_BACKEND, "OPTIONS": STATIC_STORAGE_OPTIONS},
     "staticfiles": {"BACKEND": STATIC_STORAGE_BACKEND, "OPTIONS": STATIC_STORAGE_OPTIONS},

envfile/.env.docker

@@ -1,3 +1,22 @@
 DATABASE_HOST=host.docker.internal
 CELERY_BROKER_URL=redis://host.docker.internal:46379/0
 CELERY_RESULT_BACKEND=redis://host.docker.internal:46379/1
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Object storage
+# ──────────────────────────────────────────────────────────────────────────────
+# 기본값(아래 변수를 모두 비워두면): AWS S3 (storages.backends.s3.S3Storage). 기존 동작 그대로.
+#
+# 자체 호스팅(로컬 파일시스템 + nginx)으로 전환하려면 아래 주석을 해제한다.
+#  - 미디어(public 업로드)는 nginx 가 MEDIA_URL 로 서빙한다.
+#       디스크 경로: MEDIA_ROOT/public/<name>  <->  URL: MEDIA_URL + "public/<name>"
+#       nginx: location /media/ { alias <MEDIA_ROOT>/; }  ->  /media/public/<name> -> <MEDIA_ROOT>/public/<name>
+#  - static(admin/DRF CSS,JS)도 nginx 가 STATIC_URL 로 서빙한다.
+#       배포 시 `python manage.py collectstatic --noinput` 필수. (결과물: STATIC_ROOT = <BASE_DIR>/static)
+#       nginx: location /static/ { alias <STATIC_ROOT>/; }
+#
+# DJANGO_DEFAULT_STORAGE_BACKEND=django.core.files.storage.FileSystemStorage
+# DJANGO_STATIC_STORAGE_BACKEND=django.contrib.staticfiles.storage.StaticFilesStorage
+# DJANGO_MEDIA_ROOT=/app/media
+# DJANGO_MEDIA_URL=https://rest-api.pycon.kr/media/         # dev: https://rest-api-dev.pycon.kr/media/
+# DJANGO_STATIC_URL=https://rest-api.pycon.kr/static/       # dev: https://rest-api-dev.pycon.kr/static/