Вложения файлов со своего сервера доступа пользователя

This commit is contained in:
AidarKC
2026-10-07 11:42:12 +03:00
parent b1c42efa82
commit 7b8e178723
33 changed files with 1960 additions and 496 deletions
+213
View File
@@ -0,0 +1,213 @@
# 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
### Затем
8. мониторинг
9. проверка целостности файлов
10. garbage collector в audit-only режиме
11. автоматическая очистка только после отдельного решения
---
## Основное архитектурное решение
На текущем этапе отдельный собственный CDN-слой SHiNE не нужен.
**SHiNE server = origin файлов**
**Cloudflare = внешний CDN/cache**
Сервер должен корректно поддерживать стандартный HTTP для больших файлов и частичной выдачи.
Тогда браузеры, загрузчики и Cloudflare смогут нормально работать с файлами без отдельного
протокола SHiNE для скачивания.