Медиабиблиотека

Медиабиблиотека хранит изображения и их описания в CMS. Сами файлы лежат в Garage. Папка помогает редактору найти изображение; она не меняет адрес файла и не создаёт копию в S3. Одно изображение можно использовать в нескольких материалах.

Как устроены папки

Материалы распределены по назначению:

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

Названия и описания

В карточке файла есть несколько разных полей:

• Название — понятная редактору метка, например «Кулачный бой — 166.jpg». Число помогает различать фотографии с похожими названиями.
• Альтернативный текст — короткое описание изображения для читателя, который его не видит: «Участники кулачного боя в защитном снаряжении». Описывайте видимое; имена и обстоятельства указывайте, когда они известны.
• Подпись — пояснение, авторство или контекст использования. Служебный список связанных записей сюда не помещают: сайт показывает подпись читателю.

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

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

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

Повторяемая реорганизация

Скрипт scripts/media-library.py работает через административный API CMS. Нужен Python 3; сторонние Python-пакеты не требуются. Адрес CMS передаётся явно. Учётные данные можно задать переменными STRAPI_ADMIN_EMAIL и STRAPI_ADMIN_PASSWORD либо прочитать из локального файла. Файл с паролем, план и журнал должны оставаться вне Git.

Сначала подготовьте план, подставив адрес своей CMS:

python3 scripts/media-library.py \
  --cms https://cms.example.org \
  --credentials .local/production-access.txt \
  --plan .local/media-library-plan.json

Без --apply скрипт только читает медиабиблиотеку и сохраняет JSON-план. Просмотрите его: раздел before содержит исходное состояние, folder — путь папки, after — новые название, альтернативный текст, подпись и точку фокуса. Существующие папки сохраняются; классификация применяется к файлам в корне. Уточните папки и описания по самим изображениям. Автоматическая классификация использует связанные записи, поэтому не заменяет редакторскую проверку. Генерация нового плана перезаписывает его файл — сохраняйте уже проверенный план под отдельным именем, если он ещё нужен.

Затем примените проверенный план:

python3 scripts/media-library.py \
  --cms https://cms.example.org \
  --credentials .local/production-access.txt \
  --plan .local/media-library-plan.json \
  --journal .local/media-library-journal.json \
  --apply

До записи скрипт проверяет состав библиотеки и конфликты с исходным состоянием. Журнал сохраняет снимок файлов, созданные папки и выполненные изменения. Он связан с адресом CMS и SHA-256 проверенного плана; чужой журнал отвергается до записи. Изменив план, используйте новый журнал. Старые журналы без идентификатора не подходят для продолжения, но остаются пригодны как ручные резервные снимки. Запись выполняется атомарной заменой файла с правами 0600: предыдущий снимок не усечётся при ошибке записи. После каждой записи проверяются новые поля, URL, параметры изображения, миниатюры и связи с контентом. При конфликте выполнение останавливается. Не запускайте параллельно импорт или другое массовое изменение медиабиблиотеки. Проверка перед записью не является блокировкой от одновременной редакторской правки.

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

Журнал помогает восстановить исходные поля вручную через CMS; это не автоматический откат и не замена резервной копии базы данных и S3.

Проверки сохранения редакторских полей, конфликтов и продолжения работы:

python3 -m unittest discover -s scripts/tests -p 'test_media_library.py'

Изменение медиа отправляет webhook media.update; его обработчик инвалидирует кеш сайта без публикации записей. В настройках webhook включите события медиа create/update/delete вместе с событиями записей. Встроенные Blocks остаются снимками данных изображения: webhook обновляет кеш, но не переписывает их поля.