Как настроить модерацию комнат Matrix с помощью бота Mjolnir

Mjolnir — это бот для модерации от Matrix, который может применять общие политики блокировки, редактировать сообщения, отслеживать защищенные комнаты и помогать модераторам действовать без использования личных учетных записей. Безопасная настройка зависит от трех решений: где работает бот, кто может отдавать ему команды и какие права доступа он получает в каждой защищенной комнате. Держите комнату управления закрытой, защищайте только те комнаты, которые вы хотите защитить, и проверяйте права доступа, прежде чем полагаться на бота во время инцидента.

Данное руководство соответствует документации по настройке и модерации Mjolnir из исходного кода и рекомендациям по модерации сообщества Matrix, проверенным 6 октября 2026 года. На странице релизов проекта указана версия 1.12.1 как последняя на момент проверки. При установке еще раз проверьте страницу релизов исходного кода и пример конфигурации, поскольку теги контейнеров и поддерживаемые параметры могут измениться.

Подходит ли Mjolnir для вашего сообщества в Matrix?

Используйте Mjolnir, когда модераторам необходимо обмениваться правилами модерации между несколькими комнатами, подписываться на общие списки рассылки или последовательно применять повторяющиеся действия. Разрешения комнат в Matrix по-прежнему определяют, что может делать бот; Mjolnir не получает права доступа просто потому, что присоединился к комнате. Для обычной модерации небольших комнат может быть достаточно встроенных инструментов для работы с комнатами. Mjolnir наиболее полезен, когда одно и то же сообщество управляет несколькими комнатами или нуждается в контролируемом, совместно используемом рабочем процессе.

Модерация комнат и администрирование домашнего сервера — это разные области ответственности. Mjolnir может управлять блокировками и редактированием сообщений на уровне комнат при наличии соответствующих разрешений для комнат. Более сложные команды, затрагивающие весь сервер, такие как деактивация пользователей, перемещение псевдонимов или закрытие комнат, требуют от Mjolnir прав администратора сервера Synapse. Не предоставляйте доступ к администрированию домашнего сервера, если у модераторов нет особой необходимости в этих операциях.

Что нужно подготовить перед установкой?

• Для бота может потребоваться учетная запись на домашнем сервере Matrix, например, такая @mjolnir:example.org.
• Закрытая комната управления, где авторизованные модераторы могут отдавать команды и получать сообщения о состоянии дел.
• Постоянный каталог или том для хранения конфигурации и состояния Mjolnir.
• План для зашифрованных комнат. Текущая конфигурация Mjolnir поддерживает встроенное шифрование; в конфигурации также указан Pantalaimon как отдельная, устаревшая опция. Не включайте оба пути одновременно.
• Тестовая комната, где вы можете подтвердить приглашения, права доступа и поведение списка пользователей, прежде чем защищать загруженные производственные помещения.

Как установить Мьёльнир?

В документации проекта описана установка Docker и самостоятельная сборка. Для большинства администраторов, уже использующих контейнеры, Docker Compose удобен, поскольку позволяет перезапускать бота и отображать логи без необходимости держать открытым интерактивный терминал. Следуйте инструкциям проекта по настройке Docker и закрепите проверенный релиз в продакшене, вместо того чтобы бесконечно полагаться на плавающий latestтег. Официальный образ: matrixdotorg/mjolnir.

Подготовьте конфигурацию перед запуском контейнера. В руководстве Docker от разработчиков предполагается, что конфигурация находится в каталоге постоянных данных по адресу config/production.yaml. Этот каталог должен быть доступен для чтения только администраторам и службам, которым он необходим. Файл может содержать токен доступа или другие учетные данные для входа; не добавляйте его в общедоступный репозиторий, не вставляйте в комнату поддержки и не включайте в логи.

Используйте текущую конфигурацию проекта по умолчанию с комментариями в качестве источника достоверной информации для названий параметров. Как минимум, задайте URL-адрес домашнего сервера и комнаты управления, затем настройте аутентификацию и шифрование для выбранного вами развертывания. Если вы используете настройку на основе токенов, рассматривайте токен как пароль. В руководстве по настройке от разработчика описывается получение токена путем входа в систему в качестве бота из отдельного профиля браузера в Element и открытия разделов «Настройки», «Справка» и «О программе», а также раздела «Токен доступа». В нем предупреждается, что после этого не следует выходить из системы, поскольку это может аннулировать токен; вместо этого закройте этот профиль браузера. Для зашифрованной комнаты управления включите и протестируйте поддержку шифрования Mjolnir, прежде чем полагаться на команды в ней.

# Illustrative values only; use the exact keys and authentication method
# from the current upstream configuration sample. Never share real secrets.
homeserverUrl: https://matrix.example.org
managementRoom: '!privateRoomId:example.org'
accessToken: '[STORE A SECRET HERE, NOT IN PUBLIC]'

Этот небольшой фрагмент не является полной конфигурацией. В частности, настройки шифрования и входа в систему зависят от того, используете ли вы собственное шифрование или дополнительный путь Pantalaimon. Обратитесь к текущему примеру, а не копируйте старый файл блога или compose. В руководстве по настройке Mjolnir также рекомендуется размещать бота как можно ближе к домашнему серверу по сети, чтобы уменьшить задержку ответа.

Как обеспечить безопасность комнаты управления?

Создайте комнату для доверенных модераторов, пригласите учетную запись бота и сделайте комнату приватной для команды модераторов. Идентификатор или псевдоним комнаты указывается в файле managementRoom. Текущая конфигурация описывает эту комнату как источник команд и предупреждает, что любой, кто может отправлять туда команды, может управлять Mjolnir; она не предоставляет более детального уровня контроля доступа для каждой команды. Это делает проверку членства крайне важной. Незамедлительно удаляйте бывших модераторов и не используйте комнату управления ботом в качестве общего чата сообщества.

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

Какие разрешения должен получить Мьёльнир?

Пригласите бота в каждую комнату, которую он должен защищать, и предоставьте ему достаточно мощности для выполнения ожидаемых действий модерации. Matrix использует уровни мощности комнаты для таких операций, как блокировка, исключение, редактирование событий других пользователей и изменение состояния комнаты. Требуемое значение определяется событием уровня мощности комнаты; значения по умолчанию для блокировки, исключения и редактирования в Matrix обычно равны 50, если они не указаны, но отдельные комнаты могут их изменять.

В рекомендациях сообщества Matrix уровень мощности 100 описывается как распространенная настройка Mjolnir, позволяющая обеспечивать выполнение решений модерации. Однако этот уровень является существенным: любой, кто может контролировать учетную запись Mjolnir, фактически обладает такими полномочиями в защищенных комнатах, и бот может стать их фактическим владельцем. Просмотрите уровни мощности каждой комнаты и выберите уровень, который разрешает необходимые действия бота, ограничивая при этом ненужные полномочия. Не предоставляйте ему статус администратора домашнего сервера для обычной модерации комнат.

В Element вы можете пригласить бота из панели участников комнаты или ввести команду приглашения, например /invite @mjolnir:example.org, . После того, как он присоединится, измените его роль в списке участников комнаты. Повторите для каждой комнаты, которую вы хотите защитить. Mjolnir не может защищать комнаты, в которые он не присоединился, что следует из децентрализованной модели разрешений Matrix, устанавливаемой для каждой комнаты отдельно.

Как создать список забаненных пользователей и добавить защищенные комнаты?

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

!mjolnir list create COC code-of-conduct-ban-list
!mjolnir default COC
!mjolnir rooms add #community:example.org
!mjolnir verify
!mjolnir status

Первая команда создает комнату из списка заблокированных пользователей с помощью короткого кода COC; создавший ее пользователь получает приглашение, чтобы управлять ее видимостью. Вторая команда выбирает этот список в качестве списка по умолчанию для последующих команд модерации. Третья команда добавляет комнату в набор защищенных комнат Mjolnir. Команда проверки проверяет, имеет ли бот необходимые разрешения во всех защищенных комнатах, а команда статуса помогает подтвердить, что он работает должным образом. Используйте команду, !mjolnir helpчтобы увидеть синтаксис команд, доступный в вашей установленной версии.

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

Что следует проверить перед использованием в реальных условиях?

• Убедитесь, что бот отправляет сообщения о запуске и состоянии в настроенную комнату управления.
• Запустите программу !mjolnir verifyпосле приглашения в тестовую комнату и предоставления ей выбранной роли.
• Запустите программу !mjolnir roomsи убедитесь, что нужная комната отображается, и в ней нет посторонних комнат.
• Просматривайте !mjolnir protectionsи включайте только те средства защиты, которые вам понятны; автоматическая защита может повлиять на законных пользователей.
• Используйте тестовый аккаунт и временное помещение, чтобы проверить процедуру блокировки, разблокировки и редактирования, разработанную командой, прежде чем применять её к реальным участникам.
• Проверьте журналы контейнера и сообщения из комнаты управления Mjolnir, если бот пропускает команды или сообщает об отсутствии разрешений.

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

Какие распространённые ошибки при настройке?

• Предоставление бот-серверу прав администратора для удобства: для модерации на уровне комнаты обычно требуется доступ к настройкам комнаты, а не права администратора Synapse.
• Обеспечение широкого доступа к комнате управления: каждому участнику, имеющему право отдавать команды, доверяются функции модерации бота.
• Забыли про разрешения для защищенных комнат: бот может находиться в сети и при этом не забанить или не удалить сообщение, если его уровень доступа слишком низок.
• Использование зашифрованных комнат без настройки шифрования: одного членства недостаточно для того, чтобы бот мог читать зашифрованные команды.
• Копирование старого рецепта настройки: поддержка конфигурации и шифрования в Mjolnir развивается; используйте текущий пример по умолчанию и документацию по настройке.
• Предположим, что удаление одного списка отменяет все блокировки: другой отслеживаемый список может по-прежнему применять то же правило.

Где можно проверить актуальную информацию?

Начните с руководства по настройке Mjolnir , руководства для модераторов и истории релизов , указанных в исходном коде . Для получения информации о правах доступа в комнатах обратитесь к руководству по модерации сообщества Matrix и спецификации Matrix для уровней мощности комнат . Точные команды установки и настройки шифрования зависят от вашего домашнего сервера, конфигурации контейнера и релиза Mjolnir; если инструкции в исходном коде изменятся, приоритет следует отдавать указанным выше источникам.