Файловые поля и хранилища в Django: как сделать правильно

Вы завели FileField, загрузили аватарки, всё работает на локальной машине. Потом приложение переехало на два веб-сервера за балансировщиком — и половина картинок отдаёт 404, потому что файл лёг на другую ноду. Это не баг Django, а следствие того, что по умолчанию файлы пишутся в локальную папку MEDIA_ROOT, которая у каждого сервера своя. Разберём, как устроены файловые поля и бэкенды хранилищ в Django 5.x, где именно всё разваливается при масштабировании и как правильно вынести файлы в объектное хранилище.

Как Django хранит файлы на самом деле

Важный момент, который упускают новички: в базе данных Django не хранит сам файл. FileField и ImageField в таблице — это обычная строковая колонка (varchar), в которой лежит путь к файлу относительно корня хранилища. Сам файл живёт в бэкенде хранилища (storage backend).

Связка выглядит так:

• Storage backend — объект, который умеет сохранять, открывать, удалять файлы и строить URL. По умолчанию это FileSystemStorage, пишущий в MEDIA_ROOT.
• FileField — поле модели, которое хранит путь и при обращении отдаёт объект FieldFile, привязанный к своему хранилищу.
• upload_to — правило, по которому строится путь внутри хранилища при сохранении нового файла.

Из-за этого разделения перенос файлов в облако не требует менять модель: меняется только бэкенд хранилища. Но чтобы это работало без сюрпризов, поле нужно завести правильно с самого начала.

upload_to: не хардкодьте одну папку

Частая ошибка — upload_to='uploads/'. Все файлы всех пользователей сваливаются в одну директорию. Через год там сотни тысяч файлов, а ls по такой папке на файловой системе начинает подтормаживать. Правильнее раскладывать по дате или по идентификатору владельца через функцию:

# Django 5.x, models.py
import uuid
from django.db import models


def user_avatar_path(instance, filename):
    # Раскладываем по id пользователя, чтобы не копить всё в одной папке.
    # Имя файла заменяем на uuid: убираем проблемы с кириллицей и коллизиями.
    ext = filename.rsplit('.', 1)[-1].lower()
    return f"avatars/{instance.user_id}/{uuid.uuid4().hex}.{ext}"


class Profile(models.Model):
    user = models.OneToOneField('auth.User', on_delete=models.CASCADE)
    avatar = models.ImageField(upload_to=user_avatar_path, blank=True)

Функция получает объект модели и оригинальное имя файла, а возвращает путь. Замена имени на uuid решает сразу две проблемы: пользователь не может подсунуть путь с ../, и два файла с одинаковым именем не перезаписывают друг друга (по умолчанию Django добавит суффикс, но полагаться на это неудобно).

Где локальное хранилище ломается

Пока сервер один, FileSystemStorage работает. Проблемы начинаются, когда:

• Серверов становится больше одного. Файл, записанный на ноду A, недоступен с ноды B. Балансировщик отправляет запрос на аватарку туда, где её нет.
• Приложение крутится в контейнере. При пересоздании контейнера локальная папка исчезает вместе с загрузками, если не смонтирован том.
• Файлов много. Отдавать статику через Django-процесс дорого: каждый запрос занимает воркер. Для локального хранилища раздачу перекладывают на Nginx, но с несколькими нодами это всё равно не спасает от проблемы синхронизации.

Правило простое: если приложение когда-нибудь может работать больше чем на одной машине, файлы не должны лежать на локальном диске приложения. Переезжать потом больно, закладываться сразу — дёшево.

Настройка хранилищ через STORAGES

В Django 4.2 появился, а в 5.x стал основным способ конфигурировать хранилища — словарь STORAGES в настройках. Он заменил старые одиночные настройки вроде DEFAULT_FILE_STORAGE. В словаре есть два обязательных ключа:

• default — куда пишутся файлы из FileField/ImageField;
• staticfiles — как обслуживается статика (CSS, JS, картинки шаблонов).

# Django 5.x, settings.py — конфигурация по умолчанию
STORAGES = {
    "default": {
        "BACKEND": "django.core.files.storage.FileSystemStorage",
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}

Разделение важное: пользовательские загрузки и статика приложения — это разные потоки с разными правами и жизненным циклом. Не смешивайте их в одном бакете и в одной папке.

Переезд на S3-совместимое хранилище

Для объектных хранилищ (AWS S3, MinIO, Yandex Object Storage, любое S3-совместимое) стандартное решение — пакет django-storages вместе с boto3. Проверяйте актуальную версию и список поддерживаемых бэкендов в документации django-storages, потому что имена классов и набор опций между версиями менялись.

Установка:

pip install django-storages boto3

Подключение S3-бэкенда как хранилища по умолчанию:

# Django 5.x, settings.py
import os

STORAGES = {
    "default": {
        "BACKEND": "storages.backends.s3.S3Storage",
        "OPTIONS": {
            "bucket_name": os.environ["S3_BUCKET"],
            "region_name": os.environ.get("S3_REGION", ""),
            "endpoint_url": os.environ["S3_ENDPOINT"],  # для не-AWS хранилищ
            # Ключи берём из окружения, в код не пишем никогда
            "access_key": os.environ["S3_ACCESS_KEY"],
            "secret_key": os.environ["S3_SECRET_KEY"],
        },
    },
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}

Точное имя класса бэкенда (storages.backends.s3.S3Storage) и набор ключей в OPTIONS сверьте с документацией вашей версии django-storages: в более старых релизах класс назывался иначе, а часть параметров задавалась глобальными настройками с префиксом AWS_. После этой замены код моделей и вызовы instance.avatar.url менять не нужно — Django построит URL уже в бакете.

Приватные файлы: не отдавайте публичный URL

Если файлы содержат персональные данные — сканы документов, договоры — их нельзя класть в публичный бакет. Тогда бэкенд настраивают на приватный доступ, а .url возвращает подписанную ссылку с ограниченным сроком жизни (presigned URL). Опция, отвечающая за это поведение, и её имя зависят от версии django-storages — не полагайтесь на память, откройте документацию раздела про S3 и приватный доступ.

Сравнение вариантов хранения

Что ломается на практике

• Удаление объекта модели не удаляет файл. Django намеренно не трогает файлы при удалении записи начиная с версии 1.3 — это не баг. Файлы-сироты накапливаются. Чистку организуют отдельно: сигналом post_delete или периодической задачей, которая сверяет бакет с базой.
• Кириллица в именах файлов. При переносе на S3 неэкранированные имена ломают URL. Отсюда совет выше — заменять имя на uuid в upload_to.
• Валидация типа файла по расширению. Расширение подделывается. Проверяйте содержимое: ImageField при наличии Pillow проверяет, что это действительно изображение, но для остальных типов нужна своя валидация MIME.
• Файлы в тестах уезжают в боевой бакет. Для тестов переопределяйте STORAGES на локальную временную папку или используйте override_settings, иначе тестовые загрузки попадут в продовое хранилище.

Что делать дальше

Если вы только заводите проект — сразу опишите upload_to функцией с раскладкой по владельцу и заменой имени на uuid, даже пока файлы лежат локально. Это единственная часть, которую больно менять задним числом. Бэкенд хранилища подключайте через STORAGES, а ключи держите в переменных окружения.

Когда дойдёте до масштабирования: перенесите существующие файлы в бакет отдельным скриптом (пути в базе уже относительные, менять их не придётся), переключите default на S3-бэкенд и заведите задачу на чистку файлов-сирот. Инвалидация CDN-кеша при перезаливке файлов — отдельная тема, здесь её не разбираем. Смотрите в проде на долю запросов, которые всё ещё проходят через Django-воркер за файлами: если она заметна, раздачу нужно уводить на CDN.