Janitor для Payload CMS: находим потерянные файлы и неиспользуемые документы

В проектах на Payload CMS со временем накапливается мусор. Изображение удалили из статьи, старую запись переписали, импорт несколько раз перезапускали — а файлы и документы могли остаться в системе.

Для поиска таких проблем появился плагин @seshuk/payload-plugin-janitor. Первая версия вышла 14 октября 2026 года, исходный код открыт под лицензией MIT.

Репозиторий проекта:

Что ищет Janitor

Плагин сравнивает хранилище файлов с базой Payload и разделяет проблемы на три типа.

orphaned files — файл физически существует в хранилище, например в S3-совместимом бакете, но соответствующего документа в Payload уже нет.

missing files — обратная ситуация. Запись о загруженном файле существует в базе Payload, но самого файла в хранилище больше нет.

unused documents — документы существуют, но другие документы Payload на них больше не ссылаются.

Последний вариант применим не только к изображениям. Так можно искать, например, забытые категории или теги — любые сущности, которые раньше использовались в проекте, а теперь остались без ссылок.

Плагин понимает структуру Payload

Самая интересная часть Janitor — поиск ссылок.

Просто проверить поля relationship и upload было бы недостаточно: ссылки на документы могут находиться глубоко внутри структуры страницы.

Поэтому Janitor строит обратный индекс по обычным полям, блокам, Rich Text, JSON, глобальным настройкам и версиям документов.

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

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

Ничего не удаляется автоматически

Для такого инструмента это принципиально.

Janitor сначала выполняет сканирование и только записывает найденные проблемы. Администратор помечает каждую находку как «удалить» или «оставить» и лишь затем запускает очистку.

Перед самой операцией плагин повторно проверяет состояние объекта: если файл появился в хранилище заново или на документ снова кто-то сослался, удаление не выполняется.

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

Отдельный случай — missing files: документы, у которых файл отсутствует в хранилище, плагин сам не удаляет никогда. Восстановить файл или удалить запись решает администратор.

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

Поэтому перед массовой очисткой резервная копия по-прежнему обязательна.

Поддерживаемые базы и хранилища

Для поиска неиспользуемых документов нужен один из адаптеров базы: PostgreSQL, SQLite или MongoDB.

С хранилищами файлов плагин работает через адаптеры: локальный диск, S3 и S3-совместимые сервисы (R2, Bunny), а также Vercel Blob, Azure и Google Cloud Storage.

Устанавливается плагин обычным способом:

# Payload 4 beta
pnpm add @seshuk/payload-plugin-janitor@beta

# Payload 3
pnpm add @seshuk/payload-plugin-janitor@0

Минимальная конфигурация для медиатеки на S3:

import { janitor } from '@seshuk/payload-plugin-janitor'
import { s3Adapter } from '@seshuk/payload-plugin-janitor/s3'

export default buildConfig({
  // ...
  plugins: [
    janitor({
      collections: { media: true },
      storage: s3Adapter({
        bucket: 'assets',
        config: { region: 'eu-central-1' },
      }),
    }),
  ],
})

После подключения в админке появляются две коллекции — Janitor findings и Janitor runs, а также виджет на панели управления: что нашла последняя проверка и сколько места можно освободить.

Плагин поддерживает Payload CMS 3.83 и новее; для Payload 4 beta существует соответствующая бета-версия.

Когда пригодится

В первую очередь Janitor интересен давно работающим проектам с большим количеством медиафайлов.

Если сайт несколько лет наполнялся редакторами, пережил миграции, массовые импорты или изменение структуры контента, проверить хранилище на мусор вполне разумно.

Причём Janitor полезен не только как «уборщик». Возможность увидеть обратные связи документа — где и кем он используется — сама по себе закрывает довольно распространённую задачу при сопровождении Payload-проектов.

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

Источники