Skip to content

RsNest/Botpy

BranchesTags

Repository files navigation

Telegram бот для мониторинга статуса Bitrix24

Профессиональный Telegram бот на Python для автоматического мониторинга статуса Bitrix24 и отправки уведомлений о сбоях и восстановлении сервиса. Бот использует SQLite для хранения данных, поддерживает асинхронные операции, инлайн-кнопки и расширенный мониторинг компонентов.

🚀 Основные возможности

Автоматический мониторинг

  • ✅ Автоматическая проверка статуса Bitrix24 с настраиваемым интервалом
  • 🔄 Автоматическое обновление сообщений с таймером длительности сбоя
  • 🌍 Поддержка разных регионов (ru, com, eu, by, kz, ua)
  • 🔧 Мониторинг компонентов: CRM, Почта, Задачи, Диск, Календарь, Телефония
  • 📊 Детальная статистика работы бота и метрики производительности

Уведомления

  • 🔔 Автоматические алерты о сбоях в Telegram группу/канал
  • ✅ Уведомления о восстановлении работы сервиса
  • 🛡️ Дедупликация алертов для предотвращения спама одинаковых уведомлений
  • 📱 Инлайн-кнопки для быстрой проверки статуса и просмотра истории
  • 👥 Управление подписчиками для персонализированных уведомлений
  • 📋 Просмотр логов через команду /logs для быстрой диагностики

Надежность

  • 🛡️ Экспоненциальный backoff при сетевых ошибках
  • 🔄 Автоматические повторные попытки при временных сбоях (502, 503)
  • 💾 SQLite база данных для надежного хранения данных
  • 📝 Подробное логирование с ротацией файлов
  • 🎯 Graceful shutdown при получении сигналов

История и аналитика

  • 📈 История всех инцидентов с временными метками
  • ⏱️ Отслеживание длительности сбоев
  • 📊 Метрики производительности (uptime, количество проверок, ошибки)
  • 📤 Экспорт данных в CSV формат

📋 Требования

Для Docker (рекомендуется)

  • Docker 20.10+
  • Docker Compose 2.0+
  • Telegram бот токен (получить у @BotFather)
  • ID группы/канала для отправки алертов

Для локального запуска

  • Python 3.11+
  • Telegram бот токен (получить у @BotFather)
  • ID группы/канала для отправки алертов

🐳 Установка и запуск с Docker (рекомендуется)

Быстрый старт

  1. Клонируйте репозиторий или скачайте файлы

  2. Создайте файл .env на основе .env.example:

    cp .env.example .env

  3. Настройте .env файл:

    BOT_TOKEN=your_bot_token_here
GROUP_ID=-1003313600592
CHECK_INTERVAL=300
# ... остальные настройки

  4. Запустите бота:

    docker-compose up -d

  5. Проверьте логи:

    docker-compose logs -f

Управление контейнером

# Запустить в фоне
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановить
docker-compose down

# Перезапустить
docker-compose restart

# Проверить статус
docker ps

# Просмотр логов контейнера
docker logs bitrix24-bot

# Health check вручную
docker exec bitrix24-bot python -c "import sys; sys.exit(0)"

Обновление кода

# Получить обновления
git pull

# Пересобрать образ
docker-compose build

# Перезапустить с новым образом
docker-compose up -d

Структура данных

При использовании Docker данные сохраняются в локальных директориях:

  • ./data/bot.db - SQLite база данных (подписчики и инциденты)
  • ./data/metrics.json - файл с метриками
  • ./logs/bot.log - файл логов

Эти данные сохраняются между перезапусками контейнера благодаря volumes.

🔧 Локальная установка (без Docker)

  1. Клонируйте репозиторий или скачайте файлы

  2. Установите зависимости:

    pip install -r requirements.txt

  3. Создайте файл .env на основе .env.example:

    cp .env.example .env

  4. Настройте .env файл:

    BOT_TOKEN=your_bot_token_here
GROUP_ID=-1003313600592
CHECK_INTERVAL=300
# ... остальные настройки

  5. Получите ID группы/канала:

    • Добавьте бота в группу/канал
    • Отправьте команду /getid боту
    • Скопируйте ID и вставьте в .env

  6. Запустите бота:

    python bot.py

🎮 Использование

Запуск бота

С Docker:

docker-compose up -d

Локально:

python bot.py

Команды бота

Главное меню

  • /start - Начать работу с ботом и показать главное меню

    • Автоматически добавляет пользователя в список подписчиков
    • Показывает красивое меню с кнопками для навигации
    • Все функции доступны через интуитивные кнопки

  • /menu - Показать главное меню

    • Открывает главное меню с разделами:
      • 📊 Мониторинг & Статус
      • 🔔 Управление подписками
      • 📈 Аналитика & Метрики
      • ⚙️ Администрирование (только для админов)
      • ❓ Справка

  • /help - Показать справку (открывает меню)

Основные команды (доступны через меню и текстом)

  • /status - Проверить текущий статус Bitrix24
    • Выполняет немедленную проверку статуса страницы
    • Показывает текущее состояние сервиса
    • Включает быстрые кнопки для навигации

Управление подписками

  • /subscribe - Подписаться на уведомления

    • Добавляет пользователя в базу данных подписчиков
    • Пользователь будет получать все уведомления о сбоях и восстановлении

  • /unsubscribe - Отписаться от уведомлений

    • Удаляет пользователя из базы данных подписчиков
    • Пользователь перестанет получать уведомления

Статистика и информация

  • /stats - Показать базовую статистику бота

    • Количество подписчиков
    • Интервал проверки статуса
    • Ссылка на страницу статуса

  • /metrics - Показать подробные метрики работы бота

    • Время работы (uptime)
    • Количество отправленных алертов
    • Количество уведомлений о восстановлении
    • Общее количество проверок статуса
    • Количество успешных/неуспешных проверок
    • Среднее время парсинга
    • Количество ошибок за последний час
    • Время последней проверки

  • /getid - Получить ID текущего чата/группы

    • Показывает ID чата, тип (личный/группа/супергруппа) и название
    • Полезно для настройки GROUP_ID в .env
    • Предупреждает, если группа была преобразована в супергруппу

История инцидентов

  • /incidents - Показать активные и недавние инциденты

    • Отображает активные инциденты (если есть)
    • Показывает последние завершенные инциденты
    • Включает информацию о времени начала, окончания и длительности

  • /history - Показать последние 5 завершенных инцидентов

    • Отображает только завершенные инциденты
    • Показывает время начала, окончания и общую длительность сбоя
    • Форматированный вывод для удобного чтения

Экспорт и управление

  • /export - Экспортировать данные в CSV формат

    • Экспортирует все инциденты из базы данных
    • Формат: Дата, Время начала, Время конца, Длительность, Регион, Компоненты, Описание
    • Удобно для анализа в Excel или других инструментах

  • /health - Проверить состояние здоровья бота

    • Проверяет подключение к Telegram API
    • Проверяет доступность URL статуса Bitrix24
    • Показывает время последней успешной проверки
    • Отображает количество ошибок за последний час
    • Показывает количество последовательных ошибок
    • Статус мониторинга (включен/выключен)

  • /monitoring - Включить/выключить мониторинг

    • Позволяет временно отключить автоматический мониторинг
    • Полезно для обслуживания или отладки
    • Команды бота продолжают работать

  • /logs - Показать последние 15 строк логов

    • Отображает последние 15 строк из файла логов бота
    • Полезно для быстрой диагностики проблем
    • Автоматически обрезает длинные сообщения для соответствия лимитам Telegram
    • Экранирует специальные символы для корректного отображения

Навигация через меню

Бот поддерживает удобную навигацию через интерактивные меню:

Главное меню (/start или /menu):

  • 📊 Мониторинг & Статус - проверка статуса, история инцидентов, здоровье бота
  • 🔔 Управление подписками - подписка/отписка на уведомления
  • 📈 Аналитика & Метрики - статистика, метрики, экспорт данных, история
  • ⚙️ Администрирование - логи, информация о БД, проверка подключений (только для админов)
  • ❓ Справка - инструкции и информация о боте

Быстрые кнопки (в результатах команд):

  • 🔄 Статус - быстрая проверка статуса
  • 📊 Метрики - просмотр метрик
  • 📋 История - просмотр истории инцидентов
  • 🏠 Меню - возврат в главное меню

Все команды доступны как через меню, так и через текстовые команды (например, /help, /status, /menu).

Инлайн-кнопки

Бот автоматически добавляет инлайн-кнопки к сообщениям:

  • "🔄 Проверить статус сейчас" - Выполняет немедленную проверку статуса

    • Доступна в обычных сообщениях и алертах
    • Показывает актуальный статус без необходимости вводить команду

  • "📊 История инцидентов" - Показывает историю инцидентов

    • Доступна только в сообщениях об алертах
    • Быстрый доступ к информации о прошлых сбоях

📁 Структура проекта

botpythonbitrix24/
├── bot.py                      # Главный файл запуска
├── Dockerfile                  # Docker образ (многостадийная сборка)
├── docker-compose.yml          # Docker Compose конфигурация
├── .dockerignore               # Исключения для Docker
├── config/                     # Конфигурация
│   ├── __init__.py
│   └── config.py               # Класс конфигурации с валидацией
├── handlers/                   # Обработчики команд
│   ├── __init__.py
│   └── command_handlers.py     # Обработчики команд Telegram и callbacks
├── services/                   # Бизнес-логика
│   ├── __init__.py
│   ├── database.py            # Управление SQLite базой данных
│   ├── bitrix_parser.py       # Парсер статуса Bitrix24 с exponential backoff
│   ├── subscriber_manager.py  # Управление подписчиками (SQLite)
│   ├── incident_tracker.py    # Отслеживание истории инцидентов (SQLite)
│   ├── metrics_collector.py   # Сбор и хранение метрик
│   └── status_monitor.py      # Мониторинг статуса и отправка уведомлений
├── utils/                      # Утилиты
│   ├── __init__.py
│   ├── logger_config.py       # Настройка логирования с ротацией
│   ├── message_formatter.py   # Форматирование сообщений и инлайн-кнопки
│   └── time_utils.py          # Утилиты для работы со временем (МСК)
├── .env                        # Конфигурация (создать на основе .env.example)
├── .env.example               # Пример конфигурации
├── requirements.txt           # Зависимости Python (точные версии)
├── README.md                  # Документация
├── CHANGELOG.md               # История изменений
├── data/                      # Данные (создается автоматически)
│   ├── bot.db                 # SQLite база данных
│   └── metrics.json           # Файл с метриками
└── logs/                      # Логи (создается автоматически)
    └── bot.log                # Файл логов с ротацией

⚙️ Конфигурация

Все настройки бота находятся в файле .env:

Параметр Описание По умолчанию Обязательный
BOT_TOKEN Токен Telegram бота от @BotFather - ✅ Да
URL URL страницы статуса Bitrix24 https://status.bitrix24.ru/ Нет
GROUP_ID ID группы/канала для алертов - ✅ Да*
GROUP_IDS Список ID групп (через запятую) - Нет*
CHECK_INTERVAL Интервал проверки статуса (секунды) 300 Нет
LOG_LEVEL Уровень логирования (DEBUG/INFO/WARNING/ERROR) INFO Нет
LOG_FILE Путь к файлу логов logs/bot.log Нет
REQUEST_TIMEOUT Таймаут HTTP запросов (секунды) 10 Нет
RETRY_ATTEMPTS Количество попыток при ошибке 3 Нет
RETRY_DELAY Начальная задержка между попытками (секунды) 5 Нет
CACHE_TTL Время жизни кэша парсинга (секунды) 30 Нет
ALERT_ON_ISSUES Отправлять алерты о проблемах (true/false) true Нет
ALERT_ON_RECOVERY Отправлять уведомления о восстановлении (true/false) true Нет
ADMIN_CHAT_ID ID чата для административных уведомлений - Нет
HEALTH_CHECK_INTERVAL Интервал проверки здоровья (секунды) 3600 Нет
DEDUP_WINDOW Окно дедупликации алертов (секунды) 300 Нет
GROUP_INTERVAL Интервал группировки компонентов (секунды) 30 Нет

* Требуется указать хотя бы GROUP_ID или GROUP_IDS

Пример конфигурации .env:

# Обязательные параметры
BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
GROUP_ID=-1003313600592

# Опциональные параметры
CHECK_INTERVAL=300
LOG_LEVEL=INFO
REQUEST_TIMEOUT=10
RETRY_ATTEMPTS=3
RETRY_DELAY=5
CACHE_TTL=30

# Фильтры алертов
ALERT_ON_ISSUES=true
ALERT_ON_RECOVERY=true

# Административные настройки
ADMIN_CHAT_ID=123456789

🔍 Подробное описание функционала

Дедупликация алертов (Smart Alerts)

Бот использует систему дедупликации для предотвращения спама одинаковых алертов:

  • Окно дедупликации: Не отправляет идентичные алерты чаще, чем раз в DEDUP_WINDOW секунд (по умолчанию 300 секунд = 5 минут)
  • Идентификация алертов: Сравнивает регион + статус + отсортированные компоненты
  • Восстановление: Уведомления о восстановлении всегда отправляются (не дедуплицируются)
  • Логирование: Все пропущенные дубликаты логируются с уровнем INFO
  • Автоматическая очистка: Старые записи автоматически удаляются из памяти

Автоматический мониторинг

Бот автоматически проверяет статус Bitrix24 с заданным интервалом (CHECK_INTERVAL). При обнаружении изменений:

  1. Обнаружение сбоя:

    • Создается новый инцидент в базе данных
    • Отправляется алерт во все настроенные группы
    • Сообщение обновляется каждые CHECK_INTERVAL секунд с актуальной длительностью сбоя

  2. Восстановление сервиса:

    • Активный инцидент завершается
    • Рассчитывается общая длительность сбоя
    • Отправляется уведомление о восстановлении

  3. Поведение при запуске:

    • При первом запуске бот сразу проверяет статус
    • Если обнаружен сбой - отправляется алерт
    • Если есть активный инцидент в БД - используется его время начала
    • Если сервис восстановлен, но инцидент был активен - отправляется уведомление о восстановлении
    • Если был недавний инцидент (менее 24 часов) - отправляется уведомление о восстановлении

Парсинг статуса

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

  1. Основной метод:

    • Поиск текста "ВРЕМЕННЫЙ СБОЙ" на странице
    • Поиск текста "ВСЕ ОТЛИЧНО РАБОТАЕТ"

  2. Backup методы:

    • Поиск по CSS классам (error, warning, alert, down)
    • Поиск по заголовкам (h1-h6) с ключевыми словами

  3. Парсинг компонентов:

    • Автоматическое определение затронутых компонентов:
      • CRM
      • Почта
      • Задачи
      • Диск
      • Календарь
      • Телефония

  4. Извлечение дополнительной информации:

    • Регион (из URL или текста)
    • Временная метка сбоя
    • Описание проблемы

Экспоненциальный backoff

При сетевых ошибках бот использует экспоненциальный backoff:

  • Формула: delay = base_delay * (2 ^ (attempt - 1)) + jitter
  • Jitter: случайная добавка до 10% от задержки (избежание thundering herd)
  • Повторные попытки: до RETRY_ATTEMPTS раз
  • Специальная обработка: для статусов 502 и 503 (временная недоступность сервера)

База данных SQLite

Бот использует SQLite для надежного хранения данных:

Таблица subscribers:

  • chat_id (INTEGER PRIMARY KEY) - ID чата подписчика
  • subscribed_at (TEXT) - Время подписки

Таблица incidents:

  • id (INTEGER PRIMARY KEY AUTOINCREMENT) - ID инцидента
  • start_time (TEXT) - Время начала сбоя (ISO format)
  • end_time (TEXT) - Время окончания сбоя
  • duration (TEXT) - Длительность сбоя (форматированная)
  • description (TEXT) - Описание проблемы
  • region (TEXT) - Регион где произошел сбой
  • status (TEXT) - Статус: 'active' или 'resolved'
  • components (TEXT) - Затронутые компоненты (через запятую)
  • created_at (TEXT) - Время создания записи

Индексы:

  • idx_incidents_start_time - для быстрого поиска по времени
  • idx_incidents_status - для быстрого поиска активных инцидентов

Метрики

Бот собирает подробные метрики работы:

  • Время работы (uptime): с момента последнего запуска
  • Алерты: количество отправленных алертов о проблемах
  • Восстановления: количество уведомлений о восстановлении
  • Проверки: общее количество, успешные, неуспешные
  • Производительность: среднее время парсинга, время последней проверки
  • Ошибки: количество ошибок за последний час, время последней ошибки

Метрики сохраняются в файл data/metrics.json и обновляются в реальном времени.

Логирование

Бот ведет подробные логи:

  • Файл логов: logs/bot.log (или указанный в LOG_FILE)
  • Ротация: автоматическая при достижении 10 МБ (сохраняется 5 резервных копий)
  • Уровни: DEBUG, INFO, WARNING, ERROR, CRITICAL
  • Формат: YYYY-MM-DD HH:MM:SS - module - LEVEL - message
  • Вывод: одновременно в файл и консоль (для Docker)

При использовании Docker: логи доступны в ./logs/bot.log на хосте.

🔒 Безопасность

⚠️ Важно:

  • Никогда не публикуйте файл .env с реальными токенами
  • Добавьте .env в .gitignore
  • Храните токены в безопасном месте
  • Не делитесь токеном бота публично
  • Используйте переменные окружения в production

🛠️ Разработка

Запуск в режиме разработки

# Установите зависимости для разработки
pip install -r requirements.txt

# Установите LOG_LEVEL=DEBUG в .env для подробных логов
LOG_LEVEL=DEBUG

# Запустите бота
python bot.py

Тестирование

Для тестирования бота:

  1. Создайте тестовую группу в Telegram
  2. Добавьте бота в группу
  3. Используйте команду /getid для получения ID группы
  4. Установите GROUP_ID в .env
  5. Запустите бота и проверьте работу команд

Архитектура

Бот построен с использованием следующих принципов:

  • Асинхронность: все сетевые и БД операции асинхронны (aiohttp, aiosqlite)
  • Модульность: четкое разделение ответственности между модулями
  • Dependency Injection: зависимости передаются через конструкторы
  • Обработка ошибок: конкретные исключения вместо общих Exception
  • Type hints: полная типизация для лучшей читаемости
  • Константы: магические числа вынесены в константы
  • Production-ready: код соответствует best practices

🐛 Обработка ошибок

Бот включает в себя:

  • Автоматические повторные попытки при сетевых ошибках с exponential backoff
  • Graceful shutdown при получении сигналов SIGINT/SIGTERM
  • Валидацию конфигурации при запуске
  • Обработку исключений во всех критических местах с конкретными типами
  • Подробное логирование ошибок с traceback
  • Восстановление активных инцидентов из БД при перезапуске
  • Специальная обработка ошибок Telegram API (миграция групп в супергруппы)

📊 Метрики и мониторинг

Бот отслеживает:

  • Время работы (uptime) - с момента последнего запуска
  • Количество отправленных алертов - о проблемах
  • Количество восстановлений - уведомлений о восстановлении
  • Количество проверок статуса - общее, успешные, неуспешные
  • Производительность - среднее время парсинга, время последней проверки
  • Ошибки - количество за последний час, время последней ошибки
  • Количество подписчиков - активных пользователей

Все метрики доступны через команду /metrics и сохраняются в data/metrics.json.

🤝 Вклад

Если вы хотите улучшить бота:

  1. Создайте форк проекта
  2. Внесите изменения
  3. Убедитесь, что код соответствует стандартам (PEP 8, type hints, обработка ошибок)
  4. Создайте Pull Request

📄 Лицензия

Этот проект распространяется свободно. Используйте на свой страх и риск.

⚠️ Отказ от ответственности

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

📞 Поддержка и Troubleshooting

Проверка работы

С Docker:

# Проверить статус контейнера
docker ps

# Просмотр логов
docker-compose logs -f

# Проверить health check
docker exec bitrix24-bot python -c "import sys; sys.exit(0)"

Локально:

  • Проверьте логи в файле logs/bot.log
  • Убедитесь, что процесс Python запущен

Решение проблем

  1. Бот не запускается:

    • Проверьте логи: docker-compose logs или logs/bot.log
    • Убедитесь, что все настройки в .env корректны
    • Проверьте, что BOT_TOKEN и GROUP_ID установлены
    • Убедитесь, что формат токена правильный (должен содержать двоеточие)

  2. Бот не отправляет сообщения:

    • Убедитесь, что бот добавлен в группу
    • Проверьте, что бот имеет права на отправку сообщений
    • Проверьте GROUP_ID командой /getid
    • Если группа была преобразована в супергруппу, используйте новый ID

  3. Ошибки при парсинге:

    • Проверьте интернет-соединение
    • Убедитесь, что URL https://status.bitrix24.ru/ доступен
    • Проверьте логи на наличие ошибок запросов
    • Увеличьте REQUEST_TIMEOUT если запросы долго выполняются

  4. Данные не сохраняются (Docker):

    • Убедитесь, что volumes настроены в docker-compose.yml
    • Проверьте права доступа к директориям ./data и ./logs
    • Убедитесь, что контейнер не пересоздается без volumes

  5. Контейнер падает:

    • Проверьте логи: docker-compose logs
    • Убедитесь, что все переменные окружения установлены
    • Проверьте health check: docker exec bitrix24-bot python -c "import sys; sys.exit(0)"
    • Проверьте, что база данных не повреждена

  6. Дублирование логов:

    • Это нормальное поведение в Docker (логи идут и в файл, и в stdout)
    • Убедитесь, что setup_logging вызывается только один раз
    • Проверьте, что в файле логов нет реальных дубликатов

  7. Бот не отправляет алерты при запуске:

    • Проверьте логи на наличие сообщений о первой проверке
    • Убедитесь, что ALERT_ON_ISSUES=true в .env
    • Проверьте, что бот действительно обнаруживает сбой (команда /status)

Полезные команды для отладки

# Просмотр последних 50 строк логов
docker-compose logs --tail=50

# Просмотр логов в реальном времени
docker-compose logs -f

# Проверка базы данных
docker exec bitrix24-bot sqlite3 /app/data/bot.db "SELECT * FROM incidents ORDER BY start_time DESC LIMIT 5;"

# Проверка подписчиков
docker exec bitrix24-bot sqlite3 /app/data/bot.db "SELECT * FROM subscribers;"

# Проверка метрик
docker exec bitrix24-bot cat /app/data/metrics.json

🧪 Тестирование

Проект включает полный набор тестов для проверки функциональности:

⚡ Быстрый старт: См. QUICK_START.md для быстрой настройки

Запуск тестов

# Установить зависимости для тестирования
# Linux/WSL:
python3 -m pip install -r requirements.txt

# Windows:
pip install -r requirements.txt

# Запустить все тесты
# Linux/WSL:
python3 -m pytest tests/ -v

# Windows:
pytest tests/ -v

# Запустить с покрытием кода
pytest tests/ --cov=services --cov=handlers --cov=config

# Запустить только unit тесты
pytest tests/test_database.py -v

# Запустить только integration тесты
pytest tests/test_integration.py -v

# Пропустить медленные тесты
pytest tests/ -m "not slow"

Структура тестов

  • tests/test_database.py - Unit тесты для БД и сервисов
  • tests/test_integration.py - Integration тесты для критичных потоков
  • tests/test_stress.py - Stress тесты для проверки производительности

Health Check

Для проверки здоровья бота используйте скрипт:

# Linux/WSL:
python3 debug/check_bot.py

# Windows:
python debug/check_bot.py

Скрипт проверит:

  • Конфигурацию
  • Базу данных
  • Доступность Bitrix24
  • Telegram API
  • Логи и метрики
  • Права доступа к файлам

Ручное тестирование

Подробное руководство по ручному тестированию см. в TESTING_GUIDE.md

Создано с ❤️ для мониторинга Bitrix24

Версия: 2.0 (с SQLite, инлайн-кнопками и расширенным мониторингом)

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages