Как настроить бота для работы с матрицами с помощью Python и библиотеки Simple-Matrix-Bot-Lib

Что именно вы выбираете, создавая таким образом бота для Matrix?

Simple-Matrix-Bot-Lib — это удобный слой поверх matrix-nioклиентской библиотеки Python. Это делает его привлекательным, когда вам нужен небольшой бот для управления командами, бот для уведомлений или помощник для комнат, без необходимости самостоятельно писать полный цикл синхронизации и обработки событий Matrix. Компромисс заключается в том, что вы принимаете абстракции и шаблоны аутентификации, предоставляемые оберткой, вместо того, чтобы напрямую контролировать каждую деталь клиента Matrix.

По состоянию на 6 октября 2026 года в PyPI указана версия simplematrixbotlib2.13.1, выпущенная 29 марта 2026 года и требующая Python 3.9 или более поздней версии, но более ранней, чем Python 4. На сайте проекта Read the Docs в настоящее время предупреждается, что документация не поддерживается и может быть устаревшей, поэтому в данном руководстве в качестве основных источников используются PyPI и текущая спецификация Matrix, а более старая документация рассматривается как руководство по реализации, а не как доказательство текущего поведения.

Сам пакет можно найти в проекте simplematrixbotlib на PyPI . Для описания работы протокола используйте текущую спецификацию API Matrix Client-Server .

Simple-Matrix-Bot-Lib, matrix-nio или сервис приложений?

Если ваша цель — «отвечать на команды в комнатах как один бот», то Simple-Matrix-Bot-Lib обычно является кратчайшим путем. Если вы уже знаете, что вам нужна пользовательская аутентификация, необычное поведение синхронизации, подробная проверка устройства или низкоуровневое управление шифрованием, то, начав с matrix-nio , вы сможете избежать борьбы с оболочкой в ​​дальнейшем. Для мостов или интеграций, требующих маршрутизации на уровне домашнего сервера, изучите API Matrix Application Service , а не используйте обычный бот в качестве замены.

Шаг 1: Выберите домашний сервер и подтвердите способ входа бота в систему.

Для работы бота Matrix необходима учетная запись пользователя Matrix на домашнем сервере. Вы можете использовать общедоступный домашний сервер, на котором разрешено создание учетных записей, или учетную запись на домашнем сервере, которым вы управляете. Держите бота отдельно от вашей личной учетной записи Matrix, чтобы права доступа, членство в комнатах и ​​учетные данные можно было управлять независимо.

Важное решение — это аутентификация. Текущая спецификация Matrix поддерживает как устаревший API аутентификации, так и OAuth 2.0. Домашний сервер может предоставлять один или оба варианта. В опубликованных примерах быстрого запуска Simple-Matrix-Bot-Lib используются URL-адрес домашнего сервера, имя пользователя и пароль, поэтому в этом руководстве предполагается, что ваш сервер по-прежнему предлагает совместимый процесс входа по паролю.

Прежде чем писать код, проверьте методы авторизации, предоставляемые вашим домашним сервером:

curl https://matrix.example.com/_matrix/client/v3/login

Если ответ включает в себя вход по паролю, приведенный ниже пример с использованием учетных данных вполне подойдет. Если сервер использует только SSO или OAuth, не следует принудительно включать пароль в пример. В этом случае подтвердите поддержку аутентификации в текущей версии библиотеки или используйте клиент более низкого уровня, поддерживающий необходимый вам поток. Спецификация Matrix объясняет обнаружение входа и обработку токенов в разделе входа в систему API клиент-сервер .

Шаг 2: Создайте изолированную среду Python и установите библиотеку.

Используйте виртуальную среду, чтобы зависимости бота были отделены от системного Python и от несвязанных проектов. Текущие метаданные PyPI требуют Python 3.9 или более поздней версии.

mkdir matrix-bot
cd matrix-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install simplematrixbotlib

В Windows PowerShell активируйте среду с помощью следующей команды:

.venv\Scripts\Activate.ps1

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

python -m pip show simplematrixbotlib

Проверка версии важна, потому что на общедоступных страницах «Читать документацию» по-прежнему отображается более старая документация, и там явно предупреждается о том, что она может быть устаревшей. Если пример с этих страниц конфликтует с установленным пакетом, проверьте метаданные релиза и текущий репозиторий, прежде чем изменять свой код в соответствии со старой версией.

Вам необходимо сквозное шифрование?

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

В документации Simple-Matrix-Bot-Lib и текущей документации matrix-nio указано, что сквозное шифрование (E2EE) зависит от поддержки шифрования matrix-nio и библиотеки libolm. В Debian или Ubuntu в документации matrix-nio описана установка, libolm-devа затем и дополнительный модуль E2EE:

sudo apt-get install libolm-dev
python -m pip install "matrix-nio[e2e]"

Не включайте сквозное шифрование (E2EE) только потому, что Matrix его поддерживает. Используйте его, когда комнаты требуют шифрования, и вы готовы сохранять данные бота и обрабатывать доверие к устройствам. В документации matrix-nio отмечается, что состояние шифрования, ключи и доверие к устройствам хранятся локально при включенном E2EE.

Шаг 3: Создайте учетную запись бота и не размещайте учетные данные в исходном коде.

Создайте выделенную учетную запись Matrix, используя клиент или процесс управления учетными записями, предоставляемый вашим домашним сервером. Точный интерфейс регистрации может различаться в зависимости от провайдера, поэтому данное руководство не предполагает использования конкретного экрана Element и не утверждает, что открытая регистрация доступна повсюду.

Для разработки экспортируйте три переменные среды:

export MATRIX_HOMESERVER="https://matrix.example.com"
export MATRIX_USERNAME="botname"
export MATRIX_PASSWORD="replace-with-a-secret"

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

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

Шаг 4: Напишите, запустите и протестируйте минимального бота для управления командами.

Создание bot.pyс помощью небольшой !pingкоманды. Приведенная ниже структура соответствует примеру общедоступного пакета: создать Creds, создать Bot, добавить асинхронный обработчик сообщений, использовать MessageMatchи отправить текстовое сообщение через bot.api.

import os
import simplematrixbotlib as botlib

HOMESERVER = os.environ["MATRIX_HOMESERVER"]
USERNAME = os.environ["MATRIX_USERNAME"]
PASSWORD = os.environ["MATRIX_PASSWORD"]
PREFIX = "!"

creds = botlib.Creds(HOMESERVER, USERNAME, PASSWORD)
bot = botlib.Bot(creds)

@bot.listener.on_message_event
async def ping(room, message):
    match = botlib.MessageMatch(room, message, bot, PREFIX)

    if (
        match.is_not_from_this_bot()
        and match.prefix()
        and match.command("ping")
    ):
        await bot.api.send_text_message(room.room_id, "Pong!")

bot.run()

Запустите его из активированной виртуальной среды:

python bot.py

В тестовой комнате отправьте:

!ping

Успешный результат прост: бот остается подключенным, видит событие в комнате и отвечает Pong!. Также убедитесь, что он не отвечает на собственный ответ. Эта is_not_from_this_bot()проверка важна, потому что наивный бот, работающий по принципу эхо-ответа, в противном случае может создавать петли обратной связи.

Когда следует добавлять список разрешенных лиц?

Добавьте еще один параметр, прежде чем бот сможет активировать что-либо конфиденциальное. Команда, которая возвращает только «Pong!», имеет мало влияния, но команда, которая запускает задания развертывания, запрашивает данные из внутренних систем или публикует конфиденциальную информацию, не должна выполняться для каждого пользователя в каждой подключенной комнате.

Библиотека Simple-Matrix-Bot-Lib позиционирует управление доступом пользователей и настройку списков разрешений/блокировок как свои функции. Для бота, используемого в производственной среде, авторизацию следует рассматривать как логику приложения, а не как необязательный этап доработки. Ограничивайте доступ по идентификатору пользователя, идентификатору комнаты или обоим параметрам, а разрешения на стороне сервера следует хранить в нижестоящих системах в качестве второй линии защиты.

Вход по паролю против использования токенов доступа: в чем практический компромисс?

Вход по паролю прост для понимания и соответствует опубликованному минимальному примеру пакета. Недостаток заключается в том, что для длительной работы бота необходим пароль учетной записи, а в некоторых современных развертываниях Matrix могут предпочитать потоки SSO или OAuth.

Токены доступа уменьшают необходимость повторного использования паролей, но правила жизненного цикла токенов зависят от системы аутентификации. Спецификация Matrix гласит, что токены доступа следует рассматривать как непрозрачные учетные данные и отправлять с использованием Authorization: Bearerсхемы HTTP. Текущие версии Matrix также поддерживают токены доступа с истекающим сроком действия и токены обновления в некоторых сценариях. Не следует предполагать, что пример, написанный для учетных данных паролей, автоматически обрабатывает обновление, отзыв или OAuth.

Если для вашей системы центральное место занимают жизненный цикл токенов, единый вход (SSO), OAuth или аутентификация в стиле учетных записей служб, проверьте наличие этой возможности именно в той версии Simple-Matrix-Bot-Lib, которую вы устанавливаете. Если оболочка не предоставляет достаточного контроля, использование matrix-nio напрямую — более экологичный инженерный вариант.

На каком устройстве следует запускать бота: на ноутбуке, VPS, в контейнере или Kubernetes?

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

Типичные ошибки при настройке и что они обычно означают.

• Вход в систему не удается немедленно: подтвердите URL-адрес домашнего сервера и проверьте его /_matrix/client/v3/login. Сервер, который не сообщает о возможности входа по паролю, может не работать с быстрым запуском на основе пароля.
• Бот запускается, но не видит сообщений: убедитесь, что учетная запись бота действительно подключена к комнате и что вы тестируете с помощью обычного текстового события.
• Бот отвечает неоднократно: убедитесь, что обработчик игнорирует события, отправленные самим ботом.
• Зашифрованные комнаты нечитаемы: установки базового пакета недостаточно. Добавьте зависимости matrix-nio E2EE, включите шифрование в соответствии с конфигурацией библиотеки и сохраните криптографическое хранилище.
• В одном из старых примеров возникает ошибка API: проверьте версию установленного пакета. В документации Simple-Matrix-Bot-Lib в настоящее время указано, что поддержка библиотеки прекращена, поэтому примеры могут отставать от релиза в PyPI.

Какой путь вам следует выбрать?

Выбирайте Simple-Matrix-Bot-Lib, если ваш бот использует только одного пользователя Matrix, ваши команды просты и вы цените лаконичный код на Python больше, чем низкоуровневое управление протоколами. Он особенно подходит для прототипов, ботов для оповещений, утилит для переговорных комнат и небольших внутренних автоматизаций.

Выбирайте matrix-nio напрямую, если шифрование, проверка устройств, пользовательская аутентификация, типы событий, поведение синхронизации или управление токенами являются ключевыми требованиями. Вам придётся написать больше кода, но граница абстракции будет ниже, и будет проще разобраться в сложных задачах Matrix.

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

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

Основные источники

• Библиотека Simple-Matrix-Bot-Lib на PyPI — текущие метаданные пакета, требования к Python, история релизов и базовый пример.
• Документация Simple-Matrix-Bot-Lib — полезный справочник по историческому использованию; на данный момент сайт предупреждает о возможном устарелости.
• Документация matrix-nio — базовая клиентская библиотека, зависимости E2EE, хранилище и примеры.
• Клиент-серверный API Matrix — текущее поведение протоколов аутентификации, входа в систему, токенов, комнат и событий.
• API-интерфейс Matrix Application Service — интегрированная с сервером альтернатива для создания мостов и более масштабных интеграций.