API медиатеки файлов — `/api/v1/files`

Каталог файлов вынесен из ядра в модуль «Медиатека файлов» версии 1.0.0 (пакет cascad360-module-files). Требуется ядро ≥ 1.0.13. Без установленного модуля Files API недоступен — это нормально для облегчённых инсталляций. Установка модуля — отдельный deb или tar.gz.

Персональные данные. Загруженные файлы могут содержать ПДн. Хранение и доступ регулируются политикой оператора инсталляции. См. политику конфиденциальности.

Контракт модуля: OpenAPI модуля после установки; обзор методов — на этой странице. Ядро: Swagger UI, сводный индекс.

На страницах методов — примеры JSON и curl. См. как читать страницу метода.

Доступность API

Профиль	Поведение
Standard (модуль установлен и включён)	`/api/v1/files/*` и раздача `/media/…` работают
Minimal (модуль отключён)	Маршруты каталога не регистрируются — ответ 404

Требования: ядро ≥ 1.0.13, модуль cascad360-module-files 1.0.0, в конфигурации files.enabled: true.

Конфигурация (config.yml)

Модуль использует секции верхнего уровня modules, files и storage в config.yml (или правки через админку → Модули — у пакета есть config_bindings на files / storage). Общий справочник ядра — config-reference; установка — §2.1.2.

modules:
  installed:
    - cascad360-module-files
files:
  enabled: true
  access_profile: standard
storage:
  type: local
  path: /var/lib/cascad360/files

modules — регистрация модуля

Ключ	По умолчанию	Описание
`modules.installed`	`[]`	Список установленных модулей. Для медиатеки добавьте `cascad360-module-files` после установки deb/tar.gz.
`modules.disabled`	—	Имена модулей, принудительно не стартующих после перезапуска (отключение через админку).
`modules.registry_url`	из `app.module_registry_url`	URL реестра модулей; для зеркала укажите свой домен.

Настройки медиатеки не задаются в modules.settings.cascad360-module-files — только через секции files и storage ниже.

storage — хранилище файлов

Ключ	По умолчанию	Описание
`storage.type`	`local`	Backend: `local` (диск) или `s3` (S3-совместимое хранилище).
`storage.path`	`storage`	Каталог для local-хранения (относительный от корня приложения или абсолютный путь). Ключ именно `path`, не `local.path`.
`storage.size_limit`	`10GB`	Квота дискового/S3-хранилища (строка с суффиксом KB/MB/GB).
`storage.organize_by_date`	`true`	Класть файлы в подкаталоги по дате загрузки.
`storage.organize_by_type`	`true`	Дополнительная группировка по MIME/type.
`storage.organize_by_category`	`false`	Группировка по category из метаданных upload.
`storage.upload_categories`	—	Список допустимых category для UI/API (массив строк).
`storage.s3.bucket`	`""`	Имя bucket при `type: s3` (без секретов в git).
`storage.s3.prefix`	`files/`	Префикс ключей объектов в bucket.
`storage.s3.region`	`us-east-1`	Регион S3.
`storage.s3.endpoint_url`	`""`	Кастомный endpoint (MinIO, совместимые API).

S3 credentials задаются только через переменные окружения, не в config.yml: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, опционально AWS_SESSION_TOKEN; альтернативные имена — CASCAD360_S3_ACCESS_KEY, CASCAD360_S3_SECRET_KEY.

files — каталог и API

Ключ	По умолчанию	Описание
`files.enabled`	`true`	`true` — регистрируются маршруты каталога и Files API; `false` — каталог отключён (заглушки, HTTP 503). Без установленного модуля маршруты не регистрируются (HTTP 404).
`files.access_profile`	`standard`	Профиль ACL публичной раздачи: `open`, `standard` или `strict`.
`files.signed_url_ttl_seconds`	`3600`	TTL подписанных ссылок `/s/…` (секунды).
`files.delivery_cache_control`	`public, max-age=3600`	Заголовок `Cache-Control` для ответов `/media/…`.
`files.delivery_frame_ancestors`	—	Whitelist для заголовка `Content-Security-Policy: frame-ancestors` при встраивании в iframe (массив origin).
`files.cors_origins`	—	Разрешённые origin для CORS при внешней загрузке через браузер (массив URL).
`files.rate_limit_upload_per_minute`	`60`	Лимит запросов upload на клиента в минуту.
`files.chunked_enabled`	`true`	Chunked upload для больших файлов.
`files.chunked_threshold_mb`	`10`	Размер файла (MB), выше которого используется chunked.
`files.chunked_part_size_mb`	`5`	Размер одной part при chunked upload (MB).
`files.chunked_session_ttl_minutes`	`60`	Время жизни сессии chunked upload (минуты).
`files.stream_ram_threshold_mb`	`16`	Порог RAM: ниже — streaming delivery без полной буферизации в память.
`files.deduplication`	`off`	Политика дедупликации по хешу содержимого (`off` или значения политики из релиза модуля).
`files.retention_days`	`0`	Автоудаление старых файлов (дни); `0` — без автоматической очистки.
`files.max_file_size`	`100MB`	Максимальный размер одного файла в upload.
`files.max_files_per_request`	`10`	Максимум файлов в одном multipart-запросе upload.
`files.allowed_mime_types`	—	Whitelist MIME; пустой массив `[]` — без ограничения по MIME.
`files.allowed_extensions`	—	Whitelist расширений (если задан — только они).
`files.forbidden_extensions`	—	Blacklist опасных расширений (например `.exe`, `.sh`).
`files.scan.enabled`	`false`	Асинхронный hook проверки файлов после upload; встроенный антивирус в поставку не входит.
`files.scan.mock_async`	`false`	Mock-сканер для dev/staging (не для production).
`files.scan.mock_delay_seconds`	`0.05`	Задержка mock-сканера (секунды).

При files.scan.enabled: true и статусе файла pending публичная раздача может вернуть 403 до завершения проверки (см. delivery).

Аутентификация

Base path: /api/v1/files

Метод	Header	Permissions (API Key)
JWT	`Authorization: Bearer <access_token>`	access token (не refresh)
API Key	`X-API-Key: <key>`	`files:upload`, `files:download`, `files:` или ``

API медиатеки файлов — /api/v1/files