Для безопасного удаления старых данных Matrix Synapse рассматривайте историю комнат и медиафайлы как отдельные задачи. Используйте API администратора для очистки истории комнат для старых событий в комнатах, API удаления медиафайлов для локальных медиафайлов и API удаленного кэша медиафайлов для загруженных файлов с других домашних серверов. Для регулярной очистки настройте политики хранения сообщений и медиафайлов. Очистка строк базы данных не всегда приводит к немедленному уменьшению размера файла базы данных на диске.
Выберите тот вид уборки, который соответствует вашей цели.
| Что занимает место? | Использовать | Важное ограничение |
| Старые сообщения и другие события в комнате | API администрирования для очистки истории сообщений или автоматическое сохранение сообщений. | Удаление истории сообщений происходит только в пределах одной комнаты. Состояние комнаты сохраняется; Synapse хранит как минимум одно сообщение в каждой комнате. |
| Медиафайлы, хранящиеся на вашем домашнем сервере | Удалить API локальных медиафайлов или сохранить локальные медиафайлы. | Медиафайлы, используемые в профилях и аватарах комнат, по умолчанию защищены конечной точкой даты/размера. |
| Медиафайлы кэшированы с других домашних серверов. | Очистка API удаленных медиафайлов или сохранение удаленных медиафайлов | При повторном запросе Synapse снова получит данные с исходного сервера. |
Эти параметры управления влияют на собственную базу данных Synapse и хранилище медиафайлов. Если вы используете внешнее хранилище медиафайлов, например Matrix Media Repository, локальная конечная точка удаления медиафайлов Synapse не удаляет файлы, хранящиеся в нем. Перед удалением данных ознакомьтесь с документацией и политикой резервного копирования этого хранилища.
Подготовьтесь перед тем, как проводить уборку.
- Уточните, какой экземпляр Synapse обрабатывает медиафайлы. В развертывании с использованием рабочих процессов очистка медиафайлов выполняется на рабочем процессе с помощью команды `npm run server`
enable_media_repo: true; это может быть основной процесс. Перед диагностикой проблемы с очисткой, которая, по-видимому, не выполняется, подтвердите маршрутизацию и конфигурацию.
- Создайте резервную копию базы данных и хранилища носителей. Перед необратимым удалением сделайте актуальную, восстанавливаемую резервную копию. Запишите идентификатор комнаты и время окончания сеанса, используя токен доступа администратора сервера. Не копируйте токен в историю общей оболочки и не публикуйте его в журналах.
- Тщательно спланируйте пороговое значение. Конечные точки очистки принимают метки времени в миллисекундах Unix. Используйте пороговое значение, полученное из UTC, и проверьте число перед отправкой запроса. Пороговое значение не является предварительным просмотром: оно может навсегда удалить подходящие данные.
В приведенных ниже примерах замените https://matrix.example.comна базовый URL-адрес вашего домашнего сервера, доступный для клиента, укажите действительный идентификатор комнаты и экспортируйте токен администратора в файле ADMIN_TOKEN. Храните токен bearer в закрытом доступе.
Удалите старую историю сообщений из одной комнаты.
API очистки истории удаляет из базы данных Synapse события старше указанного момента. Он не удаляет сообщения для других серверов и не является тем же самым, что удаление комнаты. По умолчанию Synapse удаляет события, отправленные удаленными пользователями, но сохраняет события локальных пользователей; установите delete_local_eventsэтот параметр trueтолько в том случае, если вы собираетесь удалить и их. Состояние комнаты, такое как членство и тема, сохраняется.
Например, чтобы установить крайний срок в 180 дней до текущего времени на хосте Linux, вычислите метку времени в миллисекундах, проверьте её, а затем отправьте запрос на бронирование отдельного номера:
export SYNAPSE_URL='https://matrix.example.com'
export ROOM_ID='!roomid:example.com'
export ADMIN_TOKEN='replace-with-a-server-admin-token'
PURGE_BEFORE_MS=$(python3 -c 'import time; print(int((time.time() - 180*86400) * 1000))')
printf 'Cutoff (Unix milliseconds): %s\n' "$PURGE_BEFORE_MS"
curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/purge_history/$ROOM_ID" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d "{\"purge_up_to_ts\":$PURGE_BEFORE_MS,\"delete_local_events\":true}"
Опустите это значение delete_local_eventsили установите его, falseесли хотите использовать поведение Synapse по умолчанию. Если API возвращает значение purge_id, очистка началась; она не обязательно завершилась. Опрашивайте конечную точку статуса, пока она не сообщит об ошибке, completeили исследуйте ее, errorесли статус равен failed:
curl -sS "$SYNAPSE_URL/_synapse/admin/v1/purge_history_status/$PURGE_ID" \
-H "Authorization: Bearer $ADMIN_TOKEN"
Масштабные очистки могут занять несколько минут или больше. Во время операции пользователи могут быть не в состоянии прокручивать страницу назад по этой комнате после точки очистки. Synapse хранит как минимум одно сообщение в комнате, поэтому этот API не сделает ленту комнаты полностью пустой.
Удалите старые медиафайлы и кэшированные удаленные файлы.
Для однократной очистки локальных медиафайлов, использованных перед ограничением, используйте текущую конечную точку локальных медиафайлов. Это before_tsметка времени Unix в миллисекундах, и она также может принимать size_gtфайлы, превышающие пороговое значение в байтах. По умолчанию сохраняются медиафайлы, использованные для изображений профиля или аватаров комнат; не изменяйте этот параметр, keep_profiles=falseесли вы намеренно не хотите удалить эти файлы.
curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/media/delete?before_ts=$PURGE_BEFORE_MS" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{}'
Проверьте идентификаторы ответов totalи удаленных медиафайлов. Конечная точка удаляет локальные оригиналы и эскизы. Избегайте старого пути, содержащего /media/<server_name>/delete; в документации Synapse этот маршрут помечен как устаревший начиная с версии 1.78.0. Текущая конечная точка для локальных медиафайлов не работает с отдельным внешним хранилищем медиафайлов.
Кэшированные удаленные медиафайлы — это отдельная категория. Чтобы удалить из кэша удаленные медиафайлы, к которым последний раз обращались до указанного времени, используйте:
curl -sS -X POST "$SYNAPSE_URL/_synapse/admin/v1/purge_media_cache?before_ts=$PURGE_BEFORE_MS" \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'Content-Type: application/json' \
-d '{}'
В ответе сообщается, сколько кэшированных элементов было удалено. Если пользователи запросят эти файлы позже, Synapse может загрузить их снова со своего исходного сервера, поэтому эта операция обменивает использование локального диска на возможный сетевой трафик и задержку при получении данных.
Установите периодическое сохранение данных вместо повторной ручной очистки.
Сохранение сообщений в Synapse по умолчанию отключено. Чтобы установить значение по умолчанию для всех комнат, не имеющих собственного состояния сохранения, добавьте политику в конфигурацию и включите её. В этом примере устанавливается максимальный срок в один год:
retention:
enabled: true
default_policy:
max_lifetime: 1y
Используйте единицы измерения продолжительности, поддерживаемые Synapse, например, dдни и yгоды. Администраторы и модераторы комнат также могут устанавливать состояние события комнаты m.room.retention, а администраторы серверов могут ограничивать максимально допустимое время жизни с помощью параметров allowed_lifetime_minи allowed_lifetime_max. Перед включением этой функции ознакомьтесь с полной политикой: подходящие события удаляются навсегда фоновыми заданиями очистки. Synapse скрывает просроченные события от клиентов сразу после их истечения, но очистка базы данных выполняется периодически, поэтому строки могут оставаться до тех пор, пока не будет выполнено задание. События состояния не подпадают под действие политики хранения сообщений.
Для медиафайлов добавьте media_retention, например, время жизни:
media_retention:
local_media_lifetime: 90d
remote_media_lifetime: 14d
Эти периоды времени — это периоды бездействия, а не просто ограничение по времени загрузки: когда к файлу обращались, Synapse использует время последнего обращения; для медиафайлов, к которым никогда не обращались, используется время их создания. Оригинальные файлы и эскизы удаляются. Медиафайлы, помещенные в карантин, и локальные медиафайлы, защищенные от карантина, не удаляются в ходе этой очистки. Настройте сохранение медиафайлов в процессе, который размещает хранилище медиафайлов, а затем проверьте этот параметр в соответствии с руководством по настройке для используемой вами версии Synapse.
Перед внесением изменений ознакомьтесь с официальными документами по API очистки истории , API администрирования носителей , руководством по настройке Synapse и политикой хранения сообщений . Описанное здесь поведение API соответствует официальной документации, проверенной 10 октября 2026 года; проверьте конечные точки и конфигурацию в соответствии с установленной у вас версией.
Убедитесь, что хранилище освобождено.
- Отслеживайте статус очистки истории до тех пор, пока он не изменится на
complete; сохраните идентификатор очистки и ответ для журнала обслуживания.
- Проверьте локальные медиафайлы и ответы удаленного кэша на предмет количества удаленных файлов, затем изучите журналы Synapse и использование файловой системы после очистки.
- Не следует предполагать, что меньшее количество строк в базе данных сразу означает меньший размер файла базы данных. В документации Synapse отмечается, что PostgreSQL может повторно использовать освобожденное пространство, не возвращая его операционной системе. Для PostgreSQL
VACUUM FULLможно освободить дисковое пространство, но для этого требуется эксклюзивная блокировка; планируйте операцию с учетом времени простоя/влияния на систему и следуйте документации по команде VACUUM в PostgreSQL . Для SQLite документация Synapse по хранению данных определяет VACUUMсоответствующую операцию.
- Перед закрытием задачи обслуживания убедитесь, что ожидаемые файлы или более старые события больше не обрабатываются, и проверьте, что ваша резервная копия по-прежнему доступна.