Медиатека

Медиатека хранит изображения и файлы сайта. У каждого сайта своя медиатека. Файлы другого сайта никогда не показываются и не сопоставляются.

Открыть медиатеку

Откройте Медиатека в боковом меню для управления файлами. При выборе файла та же библиотека открывается в диалоге Медиатека:

медиаполе записи: Медиатека;
форматированный текст: Вставить изображение → Медиатека или Загрузить новое, чтобы загрузить файл прямо в текст;
слот изображения в секции страницы в редакторе страниц.

Если медиатека не загрузилась, нажмите Повторить. Закрывать окно не нужно.

Выберите один или несколько файлов и нажмите Использовать выбранные: N. Медиаполе принимает только те виды файлов, которые разрешает его модель, и не больше установленного для поля количества. См. строку media в разделе типы полей.

Чтение медиатеки подчиняется праву чтения медиа. Разным действиям соответствуют три отдельных права:

Право	Разрешает
`media:upload`	Добавлять файлы: загрузки, файлы, сохранённые из ИИ-генерации, файлы, которые приносят импорт или плагин, файлы, скопированные из внешнего источника, и приватные загрузки.
`media:update`	Менять alt-текст и описания, точки фокуса, режим загрузки и приоритет запроса файла, заменять сам файл, управлять папками, тегами и публичным или приватным режимом доступа.
`media:delete`	Удалять файл. Удаление используемого файла всё равно отклоняется.

Встроенные роли admin и editor имеют все три права. Роль author имеет только media:upload: автор может добавлять файлы, но не может менять или удалять их. У роли viewer нет ни одного из этих прав. Пользовательская роль имеет ровно то, что перечислено в разделе Настройки → Роли. Если для действия не хватает прав, соответствующий элемент управления отключён; рядом указано нужное право.

Загрузить файлы

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

Виды и форматы файлов

Каждый сайт выбирает, что принимает его медиатека, в разделе Настройки → Сайт → Медиафайлы. Выключение вида не удаляет уже загруженные файлы.

Вид	Форматы	По умолчанию
Изображения	PNG, JPEG, WebP, AVIF, GIF, SVG	Включены всегда
Документы	PDF, Word, Excel, PowerPoint; также текст, таблица и презентация ODF, RTF, Text, CSV	Включены: PDF и форматы Office
Аудио	MP3, M4A, Ogg, WAV; также FLAC, AAC	Выключено
Видео	MP4, WebM; также QuickTime, Ogg video	Выключено
Другие файлы	Любой другой безопасный файл	Выключено

Программы, скрипты и веб-страницы не принимаются никогда, при любой настройке.
Формат проверяется по байтам файла, а не только по имени.
SVG — изображение: его можно выбрать в поле изображения, просмотреть и вывести через <img>, сохранив векторный формат. Поддерживаются статичные фигуры, текст, градиенты и внутренние ссылки #id; размер — до 1 MiB. Скрипты, обработчики событий, таблицы стилей, внешние ресурсы, анимация, сущности XML и небезопасная разметка отклоняются. SVG хранится в R2 даже при использовании Cloudflare Images для растровых изображений. Для публичных SVG нужны IMAGES_BUCKET и R2_PUBLIC_DOMAIN.
Установка без публичного хранилища файлов принимает только изображения.

Лимиты размера

У каждого вида свой лимит размера в той же настройке. Для каждого вида исходный лимит — 32 MiB.

Изображения: не больше 32 MiB.
Документы, аудио, видео и другие файлы, загружаемые здесь: лимит можно поднять до предела загрузки установки. Этот предел — 100 MB, если оператор не указал больший лимит тарифа Cloudflare в MEDIA_REQUEST_BODY_LIMIT_BYTES, максимум 5 GB.
Форматы, которые проверяются целиком (Word, Excel, PowerPoint, ODF, Text, CSV): не больше 32 MiB.
Обычный импорт, плагины и загрузка через API управления: не больше 32 MiB на файл. При переносе в формате .deewan файлы копируются частями; действуют ограничения принимающей установки по типу и размеру — до 5 GB, если это разрешено. См. Импорт и перенос данных.

Дубликаты

Если такой файл уже есть в медиатеке, ничего не загружается. Диалог сообщает Уже есть в медиатеке и предлагает:

Использовать существующий: использовать уже имеющийся файл. Его описание и теги сохраняются.
Загрузить отдельную копию: сохранить вторую копию.

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

Найти файлы

Поиск по имени файла или alt-тексту — поиск по имени файла или alt-тексту.
Тип файла: Все, Изображения, Документы, Аудио или Видео.
Папка, либо Все медиа ({count}) и Без папки.
Фильтр по тегам. Без тегов показывает изображения без тегов.

Папки

Папки упорядочивают медиатеку. Они никогда не перемещают и не переименовывают сохранённый файл и не меняют его адрес.

Каждый файл лежит в одной папке или в категории Без папки.
Новая папка создаёт папку внутри открытой. Вложенность — не больше 5 уровней.
На сайте не больше 500 папок. Имя — от 1 до 80 символов, уникально внутри родительской папки без учёта регистра.
Меню Параметры папки содержит Переименовать, Переместить папку в и Удалить папку.
Выберите файлы и используйте Переместить выбранные (N) в, чтобы переместить до 200 файлов за раз.
Удалить папку удаляет папку и её подпапки после одного подтверждения. Файлы не удаляются. Они переходят в категорию Без папки.

Выберите изображения.
В блоке Теги · выбрано: N введите имя в Добавить тег и нажмите Добавить тег. Чтобы снять тег с выбранных изображений, нажмите кнопку удаления рядом с ним.

Имя тега — от 1 до 64 символов, уникально на сайте без учёта регистра.
Управлять тегами переименовывает и удаляет теги. Удаление тега никогда не удаляет изображение. Для используемого тега спрашивается подтверждение с числом изображений, на которых он стоит.
Теги видны только в админке. Публичный API их не отдаёт.

Alt-текст и описания

Выберите файлы и нажмите Изменить выбранные. У каждого языка сайта своя вкладка.

Изображению нужен Альтернативный текст на каждом языке сайта, от 1 до 125 символов. Сохранить отклоняется, пока alt-текст не заполнен для всех языков: Перед сохранением нужен альтернативный текст на каждом языке. Вкладка без него помечена нет альтернативного текста.
У других файлов есть необязательное Описание на каждом языке.
Версия записи хранит один alt-текст на изображение, скопированный из медиатеки при сохранении записи. При обычном сохранении это alt-текст на языке сайта по умолчанию. Публичный API отдаёт это сохранённое значение как alt. Изменение в медиатеке попадёт в публичный API после того, как запись снова сохранят и опубликуют.

Кадрирование изображения в контенте

Кадрирование определяет, какая часть изображения видна. Файл при этом не меняется.

В медиаполе записи задайте Точка фокуса: нажмите на часть, которая должна оставаться видимой, затем Использовать эту точку.
Если для поля задано соотношение сторон, кадр подстраивается под него.
Кадрирование относится к одному использованию. То же изображение в другом месте сохраняет своё кадрирование.
Фокус по умолчанию в Изменить выбранные задаёт точку для новых использований изображения. Существующие использования сохраняют свою точку фокуса и кадр.
Кадрировать можно только изображения.

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

Загрузка изображений

В окне Изменить выбранные параметр Приоритет загрузки задаёт подсказку браузеру: Высокий, Низкий или Авто. Параметр Загрузка выбирает Сразу для немедленной загрузки или Лениво, чтобы дождаться момента, когда изображение понадобится. Оставляйте приоритет Авто, если изображению не нужен особый приоритет. Эти настройки не меняют сам файл.

Редактировать изображение

Создать обрезанную или повёрнутую копию

Выберите изображение, нажмите Изменить выбранные, затем Обрезать и повернуть.
Поворачивайте кнопками Повернуть влево и Повернуть вправо. Перетаскивайте рамку или её углы. С клавиатуры: стрелки двигают рамку, Alt со стрелками меняет размер, R поворачивает.
Нажмите Сохранить как копию или Enter.

Копия — отдельный файл со своими размерами и ссылками из контента. Она получает alt-текст, папку и теги оригинала и помечена Создано из {name}. Оригинал и все места, где он используется, не меняются. Если в медиатеке уже есть точно такой результат, вместо копии выбирается этот файл.

Заменить оригинал

Другие действия → Заменить оригинал записывает правку поверх оригинального файла.

Сначала показываются записи, которые используют изображение. Их опубликованные страницы покажут изменённое изображение.
Также считаются использования там, куда у вас нет доступа.
Если у нового файла другое соотношение сторон, показывается, сколько записей кадрируют изображение обрезкой или точкой фокуса, чтобы вы их проверили.

Файл, подключённый по ссылке из внешнего источника, нельзя заменить или отредактировать.

Замена через скрипт: POST /api/manage/v1/media/{id}/replace, multipart file и ключ идемпотентности. Идентификатор и ссылки из контента сохраняются; адрес доставки может измениться. Используйте url из ответа. Опубликованные версии, закрепившие прежний объект, сохраняют его байты. См. API управления.

Сменить формат изображения

Нажмите Изменить выбранные. В блоке Формат изображения можно выбрать WebP или AVIF либо сохранить исходный формат. Конвертация выполняется в вашем браузере. Сохранение заменяет оригинал, поэтому сначала показывается та же проверка использования.

Где используется файл

Перед заменой или удалением диалог показывает, где используется файл: На него ничего не ссылается. или Ещё используется ссылками в содержимом (N): …..

Использование в контенте, который вы не можете читать, учитывается в числе, но не называется.
Старые версии, которые запись ещё хранит, тоже считаются использованиями. См. сколько версий хранится.

Удалить файл

Нажмите Удалить изображение (или Удалить файл) на файле.

Удаление требует media:delete. Удаление приватного файла убирает его из приватного хранилища.
Используемый файл удалить нельзя: Изображение используется. Сначала измените контент, который его использует. Сохранённые версии могут мешать удалению файла до сокращения истории версий.
Файл, который начали использовать во время удаления, сохраняется.
Удаление требует подтверждения и не отменяется.

Приватные файлы

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

Нужно приватное хранилище. Оператор привязывает приватный бакет R2 как PRIVATE_MEDIA_BUCKET (см. backend/wrangler.example.jsonc). Это должен быть отдельный бакет без публичного домена и публичного доступа: бакет медиа публичный, и приватный файл в нём был бы опубликован. Без него Делать новые файлы приватными не предлагается, а Сделать приватным отключён с сообщением В этой установке нет приватного хранилища файлов. Setup не создаёт этот бакет и не проверяет, что он приватный.
Загрузка приватных файлов. Отметьте Делать новые файлы приватными до выбора файлов. Это действует на следующие загрузки, включая большие файлы, загружаемые потоком. Файлы, которые добавляет плагин или внешний источник, всегда публичные. При импорте копии сайта или файла истории приватные файлы сохраняют свой режим доступа.
Обозначение приватных файлов. Приватный файл показывает значок Приватный в библиотеке и в своих сведениях.
Открыть или скачать. Нажмите Открыть или Скачать в сведениях приватного файла. При каждом нажатии сервер создаёт ссылку только на выбранный файл этого сайта сроком на 5 минут. Такие же ссылки используются для предпросмотра в медиатеке и в плеерах аудио и видео. Её может запросить любой участник, который читает медиатеку. Другими способами файл недоступен: по публичному адресу медиа его нет, а сервис преобразования изображений не имеет к нему доступа. Если предпросмотр приватного аудио или видео не загрузился, нажмите Повторить. Если не сработала кнопка Открыть или Скачать, кнопка Повторить повторяет это действие, сохраняя ваши правки.
Приватные превью изображений. При загрузке приватного растрового изображения браузер создаёт миниатюру WebP до 320 пикселей и превью до 1280 пикселей. Каждый файл — не больше 2 MiB; оба хранятся в том же приватном бакете. Доступ проверяется через исходный файл и его временную ссылку. Публичных адресов нет. Для старых изображений и при неудачной конвертации показывается оригинал. Кнопка Обновить приватные превью в сведениях файла повторяет создание; нужно право media:update. SVG показывается в исходном векторном формате. Копия сайта и перенос в сгенерированное приложение несут готовые превью с контрольными суммами. При удалении или замене неиспользуемого приватного объекта удаляются и его превью.
Приватные файлы в форматированном тексте. В приватной модели можно вставлять приватные изображения, галереи и файлы для скачивания в поля форматированного текста, в том числе в текстовые поля внутри блоков плагина. Редактор открывает их через защищённую выдачу медиатеки. Публичные модели, секции страниц, сниппеты, изображения для соцсетей и оформление сайта по-прежнему отклоняют приватные файлы (media_private). Чтение приватной модели требует токена API. Сделать модель публичной нельзя, пока хотя бы одна сохранённая версия ссылается на приватный файл (model_holds_private_media). Ответ API содержит идентификаторы файлов, но не адреса в хранилище. Сгенерированное приложение выдаёт файл только после проверки доступа к содержащей его записи; см. следующий пункт.
Копии сайта сохраняют приватность файлов. Копия сайта и файл истории несут каждый приватный файл с байтами, контрольной суммой, сведениями и видимостью. Импорт кладёт каждый в приватное хранилище назначения под приватным провайдером и никогда в публичный бакет; отмена убирает его оттуда. Приватная модель приходит приватной. Если на этой установке нет приватного хранилища файлов, проверка блокирует с private_storage_unavailable до любой записи. Для сборки файла нужны доступ на чтение к медиатеке (тот же, что открывает приватный файл) и data:export, если на сайте есть хоть один приватный файл (export_private_media_forbidden); media:update не нужен. Доступ проверяется заново при каждом скачивании. Экспорт только содержимого (CSV, JSON, XLSX) никогда не зависит от приватных файлов медиатеки. Если приватное хранилище не привязано, экспорт копии сайта или файла истории отклоняется с указанием проблемного файла и ничего не создаёт (export_private_storage_unavailable). Ни учётные данные хранилища, ни имена бакетов не переносятся.
Сгенерированное приложение отдаёт свои приватные файлы само. При переносе проекта с приватными файлами в собственный репозиторий файлы копируются в ваш приватный бакет (никогда не в публичный), а в столбце адреса строки лежит метка private-file:, а не URL. Приложение отдаёт файл по GET /api/<model>/files/<field>/<row id> только тому, кто может читать эту строку по правилам доступа самой модели: ваши сессии аккаунтов, сервисные учётные данные или токены чтения. Доступ к медиатеке CMS сам по себе не даёт доступа к этим файлам в сгенерированном приложении. Каждый запрос проверяется заново; временные ссылки не выпускаются, и срока действия у такого доступа нет. Worker читает байты из своего бакета PRIVATE_FILES; Node-сервер — из каталога в PRIVATE_FILES_DIRECTORY, а без того и другого отвечает 503 private_files_unavailable. См. Справочник автономного бэкенда.
Дубликаты. Проверка дубликатов сравнивает все файлы медиатеки, публичные и приватные.

Для файла в форматированном тексте используйте GET /api/<model>/files/<field>/<row id>?media=<media id>. Параметр &variant=thumb или &variant=preview выбирает защищённое превью. Функция privateRichText(html, endpoint, rowId) из сгенерированного src/private-files.ts заменяет внутренние метки на эти адреса в домене приложения перед выводом текста. Маршрут при каждом запросе заново проверяет доступ к записи, содержащей файл.

Сделать файл приватным или публичным

Выберите файл, нажмите Изменить выбранные и используйте Видимость. Нужно media:update.

Смена видимости никогда не просто переключает флаг. Сервер копирует файл в другое хранилище под новым ключом, проверяет, что копия имеет ту же длину и SHA-256, что записанный оригинал, и только потом переключает файл. После этого он удаляет старую копию. Пока идёт работа, элемент показывает Копирование и проверка файла…, затем говорит, что произошло:

Файл теперь приватный. Публичная копия удалена. (или наоборот для публичного).
Изменение сохранено. Старая копия оставлена, потому что её всё ещё упоминает сохранённая история., когда сохранённая история всё ещё её называет.
Изменение сохранено, но удаление старой копии подтвердить не удалось. Она может оставаться доступной по старому адресу, пока её не удалят из хранилища. Копии, которые уже держит браузер или кеш, вне досягаемости медиатеки.
Файл не перемещён., когда копирование не удалось или копия не совпала: ничего не изменилось, незавершённая копия удалена. Если её не удалось удалить, сообщение говорит об этом.

Перевод файла в приватный режим отклоняется, пока его использует любой контент или сохранённая версия (media_in_use); сначала обновите этот контент. Файл, который хранит внешний источник медиа, нельзя сделать приватным.

Внешние источники медиа

Плагин может предоставлять источники медиа. Тогда в диалоге рядом с Библиотека появляется Источники.

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

Сведения, теги, папка и кадрирование файла по ссылке редактируются как у любого файла. Его байты нельзя заменить или отредактировать. Удаление убирает только запись в медиатеке. Если плагин выключен или удалён, существующий контент сохраняет записанный адрес, в сведениях написано Источник сейчас недоступен., а новые ссылки из него отклоняются.

Указание авторства скопированного файла сохраняется вместе с записью и отдаётся публичным API как credit. Показывайте его под изображением.

Сгенерировать изображение с помощью ИИ

Нажмите Сгенерировать в медиатеке.

Опишите изображение. Выберите Модель и Соотношение сторон (9:16, 1:1 или 16:9) в разделе Настройки.
Нажмите Сгенерировать. Сгенерировать снова и Создать новое пробуют снова. Пока ничего не сохранено.
Нажмите Сохранить, чтобы добавить изображение в медиатеку, в открытую папку. Проверка дубликатов действует.

Для генерации нужно ai:generate. Для сохранения нужно media:upload. Сгенерированное изображение всегда публичное. Для установки должен быть настроен провайдер ИИ. Генерация расходует почасовой лимит ИИ сайта.

Следующий шаг

Используйте файлы в контенте и на страницах.

Alt-текст и подписи с ИИ

В свойствах изображения выберите язык и модель с поддержкой изображений. Запросите предложения, проверьте и отредактируйте их. Применение сохраняет alt-текст и подпись выбранного языка. Отмена сохраняет авторский текст. Изображение отправляется настроенному ИИ-провайдеру; приватный файл не становится публичным. Если данные тем временем изменились, сохранение отклоняется. После загрузки можно открыть проверку описаний. Поддерживаются JPEG, PNG и WebP до 10 МиБ.

Поля файлов и история

Раздел Медиатека в боковом меню позволяет управлять файлами без выбора файла для записи. Диалоги выбора используют ту же библиотеку.

В разделе Поля файлов администратор сайта может добавить до 24 полей: текст, число, логическое значение, выбор, дата, медиа или связь. Флажок По языкам включает отдельные значения для каждого языка; остальные значения общие. Новые поля закрыты для публичного доступа. Включайте Публичное только для данных, которые должен получать сайт. Настройка полей требует site:settings, изменение значений — media:update.

Откройте Данные файла, выберите язык и заполните поля. Кнопка Сохранить внизу редактора сохраняет данные вместе с описаниями и параметрами выбранных файлов. Отдельной кнопки сохранения данных нет. В разделе История данных можно восстановить сохранённую версию. Хранятся до 50 версий в пределах 512 КиБ на текущие данные вместе с историей. При превышении лимита удаляются целые старые версии; текущие значения не обрезаются. После изменения типа, настроек, языкового режима или публичности поля старые значения не выдаются публично и не восстанавливаются автоматически: их нужно ввести заново для текущего определения.

Связи учитывают права на модель, запись и язык в текущем сайте. Публичные значения могут ссылаться только на публичные файлы и опубликованные публичные записи. Закрытые данные и история не попадают в обычные ответы медиатеки и публичный контент. Объявленные публичные значения находятся в mediaMetadata по ID файла. Они соответствуют текущей версии данных файла, даже если файл используется в нескольких записях. Сгенерированный сайт сохраняет данные на момент генерации; для обновления нужна повторная генерация. Закреплённые в версиях записи байты, кадрирование и описания файла работают по прежним правилам.

Копия сайта переносит поля, значения и историю с переназначением ссылок на перенесённые файлы и записи. Данные уже существующего файла назначения не перезаписываются. При отмене импорта изменённый или используемый файл сохраняется вместе с данными, а зависимое удаление отклоняется; это относится и к ссылкам из истории и циклическим связям. Используемые определения полей также сохраняются. Если публичный кеш не удалось очистить после сохранения, появится сообщение.

Если данные файла не удалось сохранить, редактор остаётся открытым с вашими изменениями, а раздел Данные файла раскрывается и показывает ошибку. Исправьте значения и снова нажмите Сохранить внизу редактора. Если поля или значения изменились у другого пользователя, нажмите Перезагрузить, чтобы отбросить свои изменения данных файла и загрузить актуальную версию. Затем внесите изменения и повторите сохранение.

Оригиналы по языкам

Откройте Медиа → Изменить выбранные → Оригиналы по языкам. Выберите Язык, затем Заменить файл. Удалить оригинал возвращает язык к резервному файлу. Нужно разрешение media:update. ID медиа, ссылки и описания по языкам сохраняются.

Порядок: выбранный язык, настроенные резервные языки, основной оригинал. Опубликованная версия сохраняет точный файл. Замена и удаление оригинала не удаляют файлы сохранённых версий. Для приватных оригиналов действуют обычные правила доступа к приватным файлам. Копия сайта и перенос полной истории сохраняют язык оригинала и старые файлы.

Операции API управления: listMediaOriginals, replaceMediaOriginal, removeMediaOriginal. Замена: multipart file и expected_object_id; пустая строка означает отсутствие оригинала этого языка. Удаление требует текущий expected_object_id. Конфликт возвращает 409 media_changed. Для основного оригинала остаётся прежняя операция замены.

Стабильная версия ещё не выпущена (pre-MVP)
Коммит исходного кода: fe23db481c422b40e317b92fc98116b4c0c26a87 (с локальными изменениями)
Дата сборки (UTC): 2026-10-18T09:22:34.630Z
Коммит для обновления: не определён: в рабочей копии есть изменения. Примечания к выпуску