Бот администраторов

Оглавление

Обзор
Как работает бот
Подключение бота
- Telegram
- MAX, VK
Подключение администратора
Команды
Уведомления о состоянии системы
Обновление с предыдущих версий

Обзор

Бот администраторов уведомляет подключённых администраторов мастер-домена о проблемах состояния системы (/system/state) и принимает от них команды.

Ботом служит системная учетная запись мессенджера мастер-домена (коллекция im/Accounts, признак isSystem), ее обслуживает микросервис im. Логику бота исполняет микросервис mware, настройки задаются параметром мастер-домена admin_imi_options. Бот работает на центральном сайте (там же, где мастер-домен) и только при наличии на нем микросервиса im: при недоступности центрального сайта уведомления не отправляются.

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

Telegram — сообщения забираются у Telegram опросом по токену бота;
MAX — в режиме опроса либо webhook по https с секретом;
VK — с заданным client_secret (Callback API).

Учетные записи без проверки (WhatsApp, VK без client_secret, MAX webhook по http) ботом администраторов не используются: их нельзя выбрать в приложении администрирования, а сервис пропускает их с предупреждением в журнале.

Системные учетные записи (isSystem) принадлежат платформе: продуктовые сервисы их не используют, а бот администраторов не использует продуктовые.

Сообщения бота не хранятся: входящие удаляются после обработки, исходящие — после отправки или ошибки отправки.

Следует создавать отдельного бота под каждый экземпляр платформы. При регистрации одного токена в разных экземплярах платформы вероятны проблемы.

Как работает бот

Каждые check_interval_sec секунд сервис получает состояние системы и для каждого подключенного чата решает, что отправить (см. Уведомления о состоянии системы).
Сообщения из чатов — команды. Команда исполняется, если чат подключен к администратору мастер-домена и команда не старше command_expire_sec; из неподключенного чата принимаются только /start и /ping.
Чат подключается одноразовым кодом: бот присылает код в чат, администратор вводит его в приложении администрирования (см. Подключение администратора).
Каждый чат настраивается отдельно: статус уведомлений, тихий режим, исключенные разделы состояния, язык.

Параметры и их допустимые значения описаны в admin_imi_options.

Подключение бота

Общий порядок:

Создать бота в мессенджере и получить его токен (для Telegram — см. Telegram).
В приложении администрирования мастер-домена открыть «Система → Бот администраторов → Боты» и добавить бота: имя, канал, токен и параметры канала. Бот создается системной учетной записью.
Выбрать бота действием «Сделать ботом администраторов» на вкладке «Боты» или в поле «Боты администраторов» на вкладке «Параметры». Бот добавляется в im_accounts параметра admin_imi_options; при удалении бота — исключается из него.
Подключить администраторов (см. Подключение администратора).

Без приложения администрирования:

POST /rest/v1/model/im/Accounts
{
  "name": "admin_bot",
  "channel": "telegram",
  "isSystem": true,
  "enabled": true,
  "options": {"token": "<token>", "proxyUrl": "", "parse_mode": "none"}
}

затем добавить идентификатор учетной записи в im_accounts параметра admin_imi_options.

Сервис взаимодействует с Telegram Bot API опросом (long polling). Необходим доступ в интернет к https://api.telegram.org с серверов центрального сайта, где исполняется микросервис im, напрямую или через прокси (см. Прокси для Telegram).

Шаг 1. Создать бота. Найти в Telegram @BotFather и отправить ему команду /newbot, задать имя и имя пользователя бота. @BotFather выдаст токен бота.

Шаг 2. Настроить меню команд. Опциональный шаг. Отправить @BotFather команду /setcommands, выбрать бота и отправить список:

Актуальный список команд:

start - Connect chat
stop - Disconnect chat
ping - Ping service
test - Test reply message
testfile - Test reply as file
echo - Echo message back
sendtoall - Send message to all connected chats
disable_subscription - Disable notifications
pause_subscription - Pause notifications until system state is ok
enable_subscription - Enable notifications
set_silent_mode - Make notifications silent
reset_silent_mode - Make notifications not silent
system_state - Get system state
download_logs - Download logs of nodes
exclude_keys - Exclude sections of system state from notifications
include_keys - Include sections of system state back
excluded_keys - Show excluded sections
lang - Change language

Команды из меню, требующие параметров, бот запросит отдельным сообщением.

Шаг 3. Оформить бота. Опциональный шаг. Пиктограмма — команда /setuserpic, описание — /setdescription, имя — /setname.

Шаг 4. Добавить бота в систему (см. общий порядок выше): канал telegram, токен из шага 1, при необходимости proxyUrl. Рекомендуемое форматирование сообщений — none. В течение короткого времени платформа подключится к Telegram.

Шаг 5. Найти бота в Telegram по имени пользователя и проверить: команда /ping — ответ pong.

Шаг 6. Подключить чат командой /start (см. Подключение администратора) и проверить командой /system_state.

Прокси для Telegram

Если серверы центрального сайта не имеют доступа к https://api.telegram.org, запросы направляются через прокси параметром учетной записи proxyUrl:

адрес вида https://proxy.example.org/ — запрос https://api.telegram.org/bot<token>/getUpdates отправляется на https://proxy.example.org/api.telegram.org/bot<token>/getUpdates; так же для файлов (https://api.telegram.org/file/bot…;);
модификатор вида /reg/Pattern/Replacement — адрес меняется регулярным выражением по правилам модификаторов.

Прокси может служить любой другой экземпляр платформы, установленный там, где Telegram доступен. В его мастер-домене создается внешний маршрутизируемый хост (коллекция ws/ExternalRoutedHosts) с маршрутом-прокси на api.telegram.org, например:

{
  "host": "proxy.example.org",
  "enabled": true,
  "routes": [
    {"port_type": "https", "path": "/api.telegram.org/", "handler": "proxy_http", "host": "api.telegram.org", "port": 443, "tls": true}
  ]
}

После этого в учетной записи бота указывается "proxyUrl": "https://proxy.example.org/". Маршрут перенаправляет любые запросы к Telegram Bot API, поэтому хост прокси не следует публиковать шире необходимого.

MAX, VK

MAX — канал max, токен бота. В режиме опроса (по умолчанию) дополнительных требований нет; в режиме webhook необходимы публичный https-адрес (webhookHost) и секрет.
VK — канал vk: токен сообщества, server_secret и client_secret с вкладки «Callback API» настроек сообщества.

Подробнее о параметрах — im/Accounts.

Подключение администратора

В чате с ботом отправить команду /start. Бот пришлет 6-значный код подключения, код действует 10 минут (отсчет с последней попытки ввода).
В приложении администрирования мастер-домена открыть «Система → Бот администраторов → Заявки», выбрать заявку чата и ввести код. Без приложения: PATCH /rest/v1/model/system/AdminImiRequests/<id> {"confirmCode": "<код>"}.
Бот пришлет в чат сообщение «Вы авторизованы как <имя> (<логин>)».

Подтвердить код может только пользователь мастер-домена с ролью admin, чат подключается к нему. После трех неверных кодов заявка отклоняется, нужно снова отправить /start. Подключенные чаты — коллекция system/AdminImiSubscribers. Если пользователь перестает быть администратором, уведомления в его чат отключаются.

Пароль администратора в мессенджер не передается.

Команды

Команда Действие

Команда	Действие
`/start`	Подключить чат (запросить код).
`/stop`	Отключить чат.
`/ping`, `/test`, `/testfile`	Проверка: ответ текстом или файлом.
`/echo <текст>`	Вернуть текст.
`/sendtoall <текст>`	Отправить текст во все подключенные чаты.
`/pause_subscription`	Приостановить уведомления до нормализации состояния системы. Пауза снимается автоматически.
`/disable_subscription`, `/enable_subscription`	Выключить и включить уведомления.
`/set_silent_mode`, `/reset_silent_mode`	Включить и выключить уведомления без звука.
`/system_state`	Получить текущее состояние системы файлом.
`/download_logs <ноды>`	Получить архив логов указанных нод (имена через запятую).
`/exclude_keys <разделы>`	Не уведомлять о разделах состояния системы, например `certificate`.
`/include_keys <разделы>`	Вернуть разделы в уведомления, `*` — вернуть все.
`/excluded_keys`	Показать исключенные разделы и разделы последнего состояния.
`/lang <код>`	Сменить язык сообщений чата, например `en`.

/start

Подключить чат (запросить код).

/stop

Отключить чат.

/ping, /test, /testfile

Проверка: ответ текстом или файлом.

/echo <текст>

Вернуть текст.

/sendtoall <текст>

Отправить текст во все подключенные чаты.

/pause_subscription

Приостановить уведомления до нормализации состояния системы. Пауза снимается автоматически.

/disable_subscription, /enable_subscription

Выключить и включить уведомления.

/set_silent_mode, /reset_silent_mode

Включить и выключить уведомления без звука.

/system_state

Получить текущее состояние системы файлом.

/download_logs <ноды>

Получить архив логов указанных нод (имена через запятую).

/exclude_keys <разделы>

Не уведомлять о разделах состояния системы, например certificate.

/include_keys <разделы>

Вернуть разделы в уведомления, * — вернуть все.

/excluded_keys

Показать исключенные разделы и разделы последнего состояния.

/lang <код>

Сменить язык сообщений чата, например en.

Команду с параметрами можно отправить без них (выбрать из меню мессенджера): бот попросит прислать параметры следующим сообщением. Ожидание длится command_input_timeout_sec секунд, другая команда его отменяет.

Возраст команды — время от отправки сообщения в мессенджере (время сообщения по данным мессенджера) до его обработки сервисом. Команды старше command_expire_sec секунд не исполняются и удаляются без ответа: так не исполняются команды, накопленные, пока бот или сервис были недоступны.

Язык сообщений чата по умолчанию — язык мастер-домена (для продукта era — русский), для подключенного чата его меняет команда /lang или поле lang в «Администраторах».

Уведомления о состоянии системы

Каждые check_interval_sec секунд бот проверяет состояние системы отдельно для каждого подключенного чата, исключая разделы, исключенные в этом чате:

появились проблемы или изменился их состав (раздел, сервер, причина) — файл с полным состоянием системы и перечнем изменений;
изменились только числовые показатели (память, нагрузка, очереди и т.п.) — файл, если показатель перешел на другой уровень (проценты — десятки, остальное — удвоение), не чаще numeric_change_interval_min минут;
проблемы сохраняются без изменений — текстовое напоминание раз в reminder_interval_min минут (0 — не напоминать);
проблемы устранены — сообщение «Состояние системы в норме».

Каждый день в моменты alive_report_times (минуты от 00:00 по местному времени сервера, по умолчанию 8:00) бот сообщает «Отчёт: сервис работает». Отсутствие этого сообщения — признак необходимости вмешательства. После перезапуска сервиса бот сообщает «Сервис уведомлений администраторов перезапущен».

Обновление с предыдущих версий

Прежний Telegram-бот переносится автоматически, повторное подключение администраторов не требуется:

токен и proxyUrl параметра system_telegram_bot (или токен параметра telegram_bot_token версий до 1.10) — в системную учетную запись мессенджера admin_imi_telegram коллекции im/Accounts, она добавляется в admin_imi_options.im_accounts; прежний параметр удаляется;
подключенные администраторы — в коллекцию system/AdminImiSubscribers с сохранением статуса и тихого режима.