Files
SHiNE-server/TODO/PUBLIC_ATTACHMENTS_TODO.md
T

7.6 KiB
Raw Blame History

TODO — публичные вложенные файлы

Цель

Довести публичную раздачу вложений до production-схемы: сервер SHiNE остаётся origin-хранилищем файлов, а Cloudflare используется перед ним для HTTPS, кэширования и CDN.

Отдельный CDN-сервис на данном этапе не требуется, если Cloudflare нормально кэширует ответы серверного file endpoint.


1. Настроить Cloudflare

  • Подключить домен/поддомен для публичных вложений.
  • Проксировать file endpoint через Cloudflare.
  • Проверить HTTPS.
  • Настроить Cache Rules для публичных неизменяемых файлов.
  • По возможности использовать длинный TTL для файлов, адресуемых по хэшу/ID.
  • Проверить корректную работу Range-запросов и ответов 206 Partial Content.
  • Не кэшировать служебные API-ответы и ошибки, которые кэшировать не нужно.

Предпочтительная схема

Client → Cloudflare → SHiNE server file endpoint → локальное файловое хранилище сервера

То есть отдельную CDN-реализацию внутри SHiNE делать не обязательно: сервер должен корректно отдавать файлы, а Cloudflare занимается внешним кэшем/CDN.


2. Полноценная HTTP-отдача файлов

Для публичного file endpoint реализовать/проверить:

GET

  • Полная отдача файла.
  • Правильный Content-Type.
  • Правильный Content-Length.
  • Content-Disposition, где это необходимо.
  • Стабильное имя/ID файла в URL.
  • Корректный 404, если файла нет.

HEAD

  • Те же HTTP-заголовки, что и для GET, но без тела файла.
  • Нужен для проверки размера, типа и существования файла.
  • Не должен читать весь файл в память.

Range requests

Поддержать:

Range: bytes=start-end

и ответ:

206 Partial Content

с корректными:

  • Accept-Ranges: bytes
  • Content-Range
  • Content-Length

Также обработать:

  • bytes=N-
  • при необходимости bytes=-N
  • некорректный диапазон → 416 Range Not Satisfiable

Важно: сервер не должен загружать весь большой файл в RAM ради выдачи небольшого диапазона.


3. Докачка файлов

Клиент должен иметь возможность продолжить загрузку после обрыва.

Сценарий:

  1. Клиент уже скачал первые N байт.
  2. Повторный запрос отправляется с: Range: bytes=N-
  3. Сервер возвращает остаток через 206 Partial Content.

Желательно дополнительно использовать:

  • ETag
  • Last-Modified
  • If-Range

Это позволит убедиться, что докачивается та же версия файла.


4. Кэширование

Для неизменяемых публичных файлов желательно:

  • адресовать файл стабильным ID/хэшем;
  • после публикации не изменять содержимое под тем же ID;
  • отдавать подходящий Cache-Control;
  • использовать ETag.

Если содержимое изменилось — лучше создавать новый объект/ID, а не менять содержимое старого URL.


5. Безопасность и корректность

Проверить:

  • защиту от ../ и path traversal;
  • невозможность запросить произвольный файл сервера;
  • ограничения допустимых директорий;
  • корректность MIME-type;
  • лимиты размера;
  • отсутствие передачи внутренних filesystem-path клиенту;
  • логирование подозрительных и битых запросов.

6. Garbage Collector / проверка файлов — позже

Добавить фоновый или периодический сборщик мусора.

Он должен уметь:

Проверять физические файлы

  • существует ли файл;
  • соответствует ли размер;
  • соответствует ли SHA-256/ожидаемый hash;
  • не повреждён ли файл;
  • есть ли для него запись в БД.

Проверять БД

  • есть ли физический файл для каждой актуальной записи;
  • нет ли записей, указывающих на отсутствующие файлы.

Находить orphan-файлы

Файлы, которые лежат на диске, но больше ни на что не ссылаются.

На первом этапе безопаснее:

  • только находить;
  • писать отчёт;
  • ничего автоматически не удалять.

Позже можно добавить grace period: orphan найден → помечен → повторно проверен через несколько дней → только потом допускается удаление.

Никогда сразу не удалять

До появления уверенной reference-модели GC должен работать в режиме аудита.


7. Метрики и обслуживание — желательно позже

Добавить базовые метрики:

  • объём файлов на диске;
  • количество файлов;
  • число GET / HEAD / Range запросов;
  • объём исходящего трафика;
  • доля 206;
  • 404 / 416;
  • ошибки чтения файлов;
  • количество orphan/corrupted файлов по результатам GC.

Приоритет реализации

Сначала

  1. GET
  2. HEAD
  3. Range / 206 Partial Content
  4. нормальная докачка
  5. ETag / If-Range
  6. Cloudflare перед file endpoint
  7. Cache Rules

Затем

  1. мониторинг
  2. проверка целостности файлов
  3. garbage collector в audit-only режиме
  4. автоматическая очистка только после отдельного решения

Основное архитектурное решение

На текущем этапе отдельный собственный CDN-слой SHiNE не нужен.

SHiNE server = origin файлов

Cloudflare = внешний CDN/cache

Сервер должен корректно поддерживать стандартный HTTP для больших файлов и частичной выдачи. Тогда браузеры, загрузчики и Cloudflare смогут нормально работать с файлами без отдельного протокола SHiNE для скачивания.