Initial commit: Message Gateway project

- FastAPI приложение для отправки мониторинговых алертов в мессенджеры - Поддержка Telegram и MAX/VK - Интеграция с Grafana, Zabbix, AlertManager - Автоматическое создание тикетов в Jira - Управление группами мессенджеров через API - Декораторы для авторизации и скрытия эндпоинтов - Подробная документация в папке docs/ Автор: Сергей Антропов Сайт: https://devops.org.ru
2025-11-12 20:25:11 +03:00
commit b90def35ed
72 changed files with 10609 additions and 0 deletions
--- a/docs/api/message.md
+++ b/docs/api/message.md
@@ -0,0 +1,188 @@
+# API для отправки сообщений
+
+**Важно:** Все эндпоинты для отправки сообщений требуют API ключ в заголовке `X-API-Key`.
+
+## Аутентификация
+
+Все эндпоинты требуют API ключ в заголовке запроса:
+
+```bash
+X-API-Key: your_api_key_here
+```
+
+API ключ настраивается в переменной окружения `API_KEY` в файле `.env`.
+
+## Отправка текстового сообщения
+
+```bash
+POST /api/v1/message/text
+Content-Type: application/json
+X-API-Key: your_api_key_here
+
+{
+  "tg_group": "monitoring",
+  "tg_thread_id": 0,
+  "text": "<b>Критическое уведомление</b>\n\nСистема недоступна!\n\n<i>Время: 2024-02-08 16:49:44</i>",
+  "parse_mode": "HTML",
+  "disable_web_page_preview": false
+}
+```
+
+**Пример ответа:**
+```json
+{
+  "status": "ok",
+  "message": "Сообщение отправлено в чат monitoring, тред 0"
+}
+```
+
+**Поддерживаемые режимы парсинга:**
+- `HTML` - HTML форматирование (рекомендуется)
+- `Markdown` - Markdown форматирование
+- `MarkdownV2` - Markdown V2 форматирование
+
+**Примеры форматирования:**
+- HTML: `<b>жирный</b>`, `<i>курсив</i>`, `<code>код</code>`
+- Markdown: `**жирный**`, `*курсив*`, `` `код` ``
+
+## Отправка фото
+
+```bash
+POST /api/v1/message/photo
+Content-Type: application/json
+X-API-Key: your_api_key_here
+
+{
+  "tg_group": "monitoring",
+  "tg_thread_id": 0,
+  "photo": "https://grafana.example.com/render/dashboard-solo?panelId=1&width=1000&height=500",
+  "caption": "<b>График CPU</b>\n\n<i>Время: 2024-02-08 16:49:44</i>",
+  "parse_mode": "HTML"
+}
+```
+
+**Пример ответа:**
+```json
+{
+  "status": "ok",
+  "message": "Фото отправлено в чат monitoring, тред 0"
+}
+```
+
+**Примечания:**
+- Фото может быть передано через URL (автоматически загрузится) или как файл
+- Поддерживаются форматы: JPG, PNG, GIF, WebP
+- Максимальный размер файла: 10 МБ (Telegram), зависит от мессенджера
+- Для отправки графиков из Grafana используйте URL рендеринга дашбордов
+
+## Отправка видео
+
+```bash
+POST /api/v1/message/video
+Content-Type: application/json
+X-API-Key: your_api_key_here
+
+{
+  "tg_group": "monitoring",
+  "tg_thread_id": 0,
+  "video": "https://example.com/recording.webm",
+  "caption": "<b>Запись работы системы</b>\n\n<i>Длительность: 60 сек</i>",
+  "parse_mode": "HTML",
+  "duration": 60,
+  "width": 1920,
+  "height": 1080
+}
+```
+
+**Пример ответа:**
+```json
+{
+  "status": "ok",
+  "message": "Видео отправлено в чат monitoring, тред 0"
+}
+```
+
+**Примечания:**
+- Видео может быть передано через URL (автоматически загрузится) или как файл
+- Поддерживаются форматы: MP4, WebM, MOV (зависит от мессенджера)
+- Максимальный размер файла: 50 МБ (Telegram), зависит от мессенджера
+- Длительность, ширина и высота опциональны, но рекомендуются для лучшего отображения
+
+## Отправка аудио
+
+```bash
+POST /api/v1/message/audio
+Content-Type: application/json
+X-API-Key: your_api_key_here
+
+{
+  "tg_group": "monitoring",
+  "tg_thread_id": 0,
+  "audio": "https://example.com/notification.ogg",
+  "caption": "<b>Аудио уведомление</b>\n\n<i>Система работает нормально</i>",
+  "parse_mode": "HTML",
+  "duration": 30,
+  "performer": "System Notification",
+  "title": "Alert Notification"
+}
+```
+
+**Пример ответа:**
+```json
+{
+  "status": "ok",
+  "message": "Аудио отправлено в чат monitoring, тред 0"
+}
+```
+
+**Примечания:**
+- Аудио может быть передано через URL (автоматически загрузится) или как файл
+- Поддерживаются форматы: MP3, OGG, WAV, M4A (зависит от мессенджера)
+- Максимальный размер файла: 50 МБ (Telegram), зависит от мессенджера
+- Исполнитель и название опциональны, но улучшают отображение в Telegram
+
+## Отправка документа
+
+```bash
+POST /api/v1/message/document
+Content-Type: application/json
+X-API-Key: your_api_key_here
+
+{
+  "tg_group": "monitoring",
+  "tg_thread_id": 0,
+  "document": "https://example.com/report.xlsx",
+  "caption": "<b>Отчет за неделю</b>\n\n<i>Дата: 2024-02-08</i>",
+  "parse_mode": "HTML",
+  "filename": "report_2024-02-08.xlsx"
+}
+```
+
+**Пример ответа:**
+```json
+{
+  "status": "ok",
+  "message": "Документ отправлен в чат monitoring, тред 0"
+}
+```
+
+**Примечания:**
+- Документ может быть передан через URL (автоматически загрузится) или как файл
+- Поддерживаются все форматы файлов (PDF, DOCX, XLSX, TXT, и т.д.)
+- Максимальный размер файла: 50 МБ (Telegram), зависит от мессенджера
+- Имя файла опционально, если не указано - используется имя из URL
+- Для отправки отчетов используйте прямые ссылки на файлы
+
+## Параметры запроса
+
+Все endpoints поддерживают параметр `messenger` (опционально):
+- `?messenger=telegram` - использовать Telegram
+- `?messenger=max` - использовать MAX/VK
+- Если не указан, используется мессенджер из конфигурации группы
+
+## Общие параметры
+
+- `tg_group` - имя группы из конфигурации (config/groups.json)
+- `tg_thread_id` - ID треда в группе (0 для основной группы, поддерживается только для Telegram)
+- `messenger` - тип мессенджера (опционально, `telegram`, `max`, по умолчанию используется из конфигурации группы)
+