S3-совместимое объектное хранилище: bucket, key и URL

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

S3 хранит файлы как объекты внутри bucket. Приложение находит объект по
key. Это не путь локальной файловой системы, хотя ключ может выглядеть как
covers/uuid.webp. Bucket отвечает на вопрос «где коллекция», а key — «какой объект».

Храни отдельно:

• key — стабильный идентификатор для чтения и удаления;
• URL — способ доступа, который может быть временным;
• метаданные — размер, обнаруженный тип и владелец.

Не извлекай key обратно из URL: домен, кодирование и подпись могут измениться.

Путь одного файла

1. Приложение проверяет загрузку.
2. Сервер создаёт непредсказуемый key.
3. Storage adapter сохраняет байты.
4. База хранит key и метаданные, но не временную подпись URL.
5. Для чтения приложение строит URL, а для удаления использует сохранённый key.

Минимальный adapter

from typing import Protocol

class Storage(Protocol):
    def save(self, key: str, data: bytes, content_type: str) -> str: ...
    def delete(self, key: str) -> None: ...

Один контракт позволяет использовать локальную реализацию в разработке и тестах,
а S3 — в production. Маршрут FastAPI не должен знать детали boto3.

Так учебный проект работает локально без облачных ключей, а подключение S3 позже не
требует переписывать маршруты.

Безопасность

• создавай непредсказуемые ключи на сервере;
• выдавай IAM-пользователю только нужные bucket и операции;
• не коммить access key и secret key;
• указывай корректный ContentType;
• не делай bucket публичным ради одного файла;
• для приватного доступа создавай короткоживущий presigned URL.

Presigned URL даёт ограниченный по времени доступ с полномочиями создавшей его
учётной записи. Он не заменяет авторизацию приложения и не является стабильным
значением для базы данных. Сначала пользователь проходит авторизацию в приложении,
и только затем сервер решает, можно ли выдать ссылку. Истечение presigned URL не
удаляет объект — оно прекращает доступ только по этой подписи.

Официальная документация

• AWS: presigned URLs