Update docker-compose and README for Telegram bot integration; add environment file reference and clarify port usage in documentation.

2025-08-31 23:32:56 +03:00
parent 7378179d98
commit 6733043a61
17 changed files with 2499 additions and 12 deletions
--- a/README.md
+++ b/README.md
@@ -19,6 +19,10 @@ prod/

 ## 🚀 Быстрый запуск

+### ⚠️ Важное замечание
+**Убедитесь, что вы удалили файл `docker-compose.yml` из папки `bots/telegram-helper-bot/`** 
+для избежания конфликтов портов. Используйте только корневой `docker-compose.yml`.
+
 ### 1. Настройка переменных окружения

 Скопируйте шаблон и настройте переменные:
@@ -65,14 +69,65 @@ docker-compose ps
 - **Grafana** (порт 3000) - дашборды
 - **Server Monitor** - мониторинг системы + Telegram уведомления

-## 🌐 Доступные адреса
+## 🌐 Доступные адреса и порты

-| Сервис | Адрес | Описание |
-|--------|-------|----------|
-| **Grafana** | http://localhost:3000 | Дашборды мониторинга (admin/admin) |
-| **Prometheus** | http://localhost:9090 | API метрик и веб-интерфейс |
-| **Метрики сервера** | http://localhost:9091/metrics | Endpoint для Prometheus |
-| **Health check** | http://localhost:9091/health | Проверка состояния мониторинга |
+### 📊 Основные сервисы мониторинга
+
+| Сервис | Порт | Адрес | Описание |
+|--------|------|-------|----------|
+| **Grafana** | 3000 | http://localhost:3000 | Дашборды мониторинга (admin/admin) |
+| **Prometheus** | 9090 | http://localhost:9090 | API метрик и веб-интерфейс |
+| **Server Monitor** | 9091 | http://localhost:9091/health | Проверка состояния мониторинга |
+| **Server Monitor Metrics** | 9091 | http://localhost:9091/metrics | Endpoint для Prometheus |
+
+### 🤖 Telegram Bot сервисы
+
+| Сервис | Порт | Адрес | Описание |
+|--------|------|-------|----------|
+| **Telegram Bot Health** | 8080 | http://localhost:8080/health | Health check бота |
+| **Telegram Bot Metrics** | 8080 | http://localhost:8080/metrics | Метрики бота (если включены) |
+
+### 🔍 Детальная информация о портах
+
+#### **Порт 3000 - Grafana**
+- **Контейнер**: `bots_grafana`
+- **Назначение**: Веб-интерфейс для просмотра дашбордов мониторинга
+- **Доступ**: Публичный (проброс из контейнера)
+- **Аутентификация**: admin/admin (по умолчанию)
+
+#### **Порт 9090 - Prometheus**
+- **Контейнер**: `bots_prometheus`
+- **Назначение**: Сбор и хранение метрик, API для запросов
+- **Доступ**: Публичный (проброс из контейнера)
+- **Функции**: 
+  - Сбор метрик с server_monitor (порт 9091)
+  - Сбор метрик с telegram-bot (порт 8080)
+  - Хранение исторических данных
+
+#### **Порт 9091 - Server Monitor**
+- **Контейнер**: `bots_server_monitor`
+- **Назначение**: Мониторинг системных ресурсов сервера
+- **Доступ**: Внутренний (только внутри Docker сети)
+- **Функции**:
+  - Сбор CPU, RAM, Disk метрик
+  - Отправка алертов в Telegram
+  - Предоставление метрик для Prometheus
+
+#### **Порт 8080 - Telegram Bot**
+- **Контейнер**: `bots_telegram_bot`
+- **Назначение**: Основной функционал Telegram бота
+- **Доступ**: Публичный (проброс из контейнера)
+- **Функции**:
+  - Health check endpoint
+  - Метрики производительности (если включены)
+  - API для управления ботом
+
+### 🌐 Сетевые настройки
+
+- **Основная сеть**: `bots_network` (192.168.100.0/24)
+- **Все сервисы**: Работают в одной Docker сети для взаимодействия
+- **Внешний доступ**: Только порты 3000, 8080, 9090
+- **Внутренние порты**: 9091 доступен только внутри Docker сети

 ## 🔧 Модуль мониторинга

@@ -131,3 +186,121 @@ curl http://localhost:3000/api/health
 ```bash
 docker-compose down
 ```
+
+## 🛠️ Управление через Makefile
+
+В корневой директории доступен Makefile с удобными командами для управления инфраструктурой:
+
+### 🚀 Основные команды
+```bash
+make help          # Показать справку по всем командам
+make start         # Собрать и запустить все сервисы
+make stop          # Остановить все сервисы
+make restart       # Перезапустить все сервисы
+make status        # Показать статус контейнеров
+make health        # Проверить здоровье всех сервисов
+```
+
+### 📊 Мониторинг и логи
+```bash
+make logs          # Логи всех сервисов
+make logs-monitor  # Логи только мониторинга
+make logs-bot      # Логи Telegram бота
+make logs-errors   # Только ошибки из логов
+make monitoring    # Открыть Grafana в браузере
+make prometheus    # Открыть Prometheus в браузере
+```
+
+### 🔧 Управление отдельными сервисами
+```bash
+make restart-monitor    # Перезапустить только мониторинг
+make restart-grafana    # Перезапустить только Grafana
+make restart-prometheus # Перезапустить только Prometheus
+make restart-bot        # Перезапустить только Telegram бота
+```
+
+### 🧹 Обслуживание
+```bash
+make backup            # Создать backup конфигурации
+make restore FILE=...  # Восстановить из backup
+make clean             # Очистить все контейнеры и образы
+make clean-monitoring  # Очистить только данные мониторинга
+make check-ports       # Проверить занятые порты
+```
+
+### 🔍 Диагностика
+```bash
+make metrics           # Показать текущие метрики
+make check-grafana     # Проверить состояние Grafana
+make test              # Запустить все тесты в проекте (инфраструктура + бот)
+make test-infra        # Запустить тесты инфраструктуры (мониторинг)
+make test-bot          # Запустить тесты Telegram бота (201 тест)
+make test-coverage     # Запустить все тесты с отчетом о покрытии
+make test-clean        # Очистить все файлы тестирования и отчеты
+make reload-prometheus # Перезагрузить конфигурацию Prometheus
+make reload-grafana    # Перезагрузить конфигурацию Grafana
+
+## 🧪 Тестирование
+
+Проект включает в себя комплексную систему тестирования для всех компонентов:
+
+### 📁 Структура тестов
+
+``` text
+tests/
+├── __init__.py                    # Инициализация корневой директории тестов
+├── pytest.ini                    # Конфигурация pytest для всего проекта
+├── test_pytest_config.py         # Тест конфигурации pytest
+└── infra/                        # Тесты инфраструктуры
+    ├── __init__.py
+    └── test_infra.py            # Тесты модулей мониторинга
+```
+
+### 📊 Тесты инфраструктуры (`make test-infra`)
+- **Расположение**: `tests/infra/test_infra.py`
+- **Количество тестов**: 7 тестов
+- **Покрытие**: Основные модули мониторинга
+- **Проверяет**:
+  - Импорт всех модулей
+  - Создание экземпляров классов
+  - Структуру системной информации
+  - Структуру метрик
+
+### 🤖 Тесты Telegram бота (`make test-bot`)
+- **Расположение**: `bots/telegram-helper-bot/tests/` (отдельная директория)
+- **Количество тестов**: 201 тест
+- **Покрытие**: Все основные компоненты бота
+- **Проверяет**:
+  - База данных и операции с ней
+  - Обработчики сообщений (admin, group, private)
+  - Клавиатуры и фильтры
+  - Утилиты и вспомогательные функции
+  - Автоматическое разбанивание пользователей
+  - Интеграционные тесты
+
+### 🚀 Запуск всех тестов (`make test`)
+Команда `make test` последовательно запускает:
+1. Тесты инфраструктуры
+2. Тесты Telegram бота
+3. Выводит общую статистику
+
+### 📊 Анализ покрытия тестами (`make test-coverage`)
+Команда `make test-coverage` запускает все тесты с детальным анализом покрытия:
+1. **Тесты инфраструктуры** с покрытием модулей мониторинга
+2. **Тесты Telegram бота** с покрытием всех компонентов
+3. **HTML отчеты** сохраняются в `htmlcov/` для детального анализа
+
+### 🧹 Очистка тестовых файлов (`make test-clean`)
+Команда `make test-clean` удаляет все файлы, созданные в процессе тестирования:
+- Кэш pytest (`.pytest_cache/`)
+- Отчеты о покрытии (`htmlcov/`, `.coverage`)
+- Скомпилированные Python файлы (`*.pyc`, `__pycache__`)
+- Временные файлы тестирования
+
+### ⚙️ Конфигурация pytest
+
+Проект использует централизованную конфигурацию pytest (`pytest.ini`):
+- **Автоматическое обнаружение**: тесты в директории `tests/`
+- **Настройки asyncio**: автоматический режим для асинхронных тестов
+- **Маркеры**: `slow`, `integration`, `unit` для категоризации тестов
+- **Форматирование**: краткий вывод ошибок, отключение предупреждений