diff --git a/.cursor/rules/my-custom-rule.mdc b/.cursor/rules/my-custom-rule.mdc new file mode 100644 index 0000000..555b9e8 --- /dev/null +++ b/.cursor/rules/my-custom-rule.mdc @@ -0,0 +1,409 @@ +--- +name: prod-project-rules +description: Правила работы с проектом prod - инфраструктура, боты, CI/CD +--- + +# Правила работы с проектом prod + +## 📋 Обзор проекта + +**prod** — проект для управления Telegram ботами и мониторинга инфраструктуры в продакшене. + +### Основные компоненты: +- **Инфраструктура мониторинга**: Prometheus, Grafana, Alertmanager, Uptime Kuma +- **Telegram боты**: telegram-helper-bot, AnonBot (в отдельных поддиректориях) +- **CI/CD**: GitHub Actions с автоматическим тестированием, созданием PR и деплоем +- **Контейнеризация**: Docker Compose для оркестрации сервисов + +--- + +## 🌿 Работа с ветками и Git + +### Структура веток: +- **`main`** — продакшен ветка, защищена, только через PR +- **`develop`** — ветка разработки (опционально) +- **`dev-*`** — ветки для разработки (например, `dev-4`) +- **`feature/**`** — ветки для новых фич + +### Workflow разработки: + +1. **Создание ветки для разработки:** + ```bash + git checkout -b dev-4 # или feature/my-feature + ``` + +2. **Перед коммитом - проверка качества кода:** + ```bash + make code-quality # Проверяет форматирование, импорты, линтинг + # Или автоматически исправить: + make format # Исправить форматирование + make import-fix # Исправить сортировку импортов + ``` + +3. **Коммит и пуш:** + ```bash + git add . + git commit -m "feat: описание изменений" + git push -u origin dev-4 + ``` + +4. **Автоматические действия после push:** + - ✅ Запускаются тесты (Black, isort, flake8, pytest) + - ✅ При успешных тестах автоматически создается/обновляется PR в `main` + - ✅ Отправляется уведомление в Telegram + +5. **После мержа PR в `main`:** + - ✅ Автоматически запускается деплой в продакшен (`deploy.yml`) + - ✅ Проверяются токены ботов + - ✅ Выполняется деплой на сервер + - ✅ Запускаются health checks и smoke tests + - ✅ При падении smoke tests — автоматический rollback + +--- + +## 🎨 Стандарты кода + +### Форматирование (Black): +- **Обязательно**: Все Python файлы должны быть отформатированы через Black +- **Проверка**: `make format-check` или `black --check .` +- **Исправление**: `make format` или `black .` +- **Правила**: + - Двойные кавычки `"` вместо одинарных `'` + - 2 пустые строки между импортами и определениями функций/классов + - Автоматический перенос длинных строк + +### Сортировка импортов (isort): +- **Обязательно**: Импорты должны быть отсортированы +- **Проверка**: `make import-check` или `isort --check-only .` +- **Исправление**: `make import-fix` или `isort .` +- **Порядок**: стандартная библиотека → сторонние → локальные + +### Линтинг (flake8): +- **Критические ошибки** (E9, F63, F7, F82) — блокируют пайплайн +- **Предупреждения** (F821, F822, F824) — игнорируются в CI +- **Проверка**: `make lint-check` +- **Исключения**: `.venv`, `venv`, `__pycache__`, `.git` + +### Перед коммитом: +```bash +make code-quality # Проверяет всё сразу +``` + +--- + +## 🧪 Тестирование + +### Структура тестов: +- **`tests/`** — тесты инфраструктуры проекта +- **`bots/*/tests/`** — тесты ботов (в их репозиториях) + +### Запуск тестов: +```bash +make test # Все тесты +make test-infra # Только тесты инфраструктуры +make test-coverage # С отчетом о покрытии +make test-clean # Очистить кэш и отчеты +``` + +### Конфигурация pytest: +- Файл: `pytest.ini` в корне проекта +- Автоматическое обнаружение тестов в `tests/` +- Маркеры: `slow`, `integration`, `unit` +- Asyncio режим: автоматический + +### Правила написания тестов: +- Используй описательные имена: `test_prometheus_config_is_valid` +- Группируй связанные тесты в классы +- Используй фикстуры для общих setup/teardown +- Тесты должны быть независимыми и идемпотентными + +--- + +## 🐳 Docker и контейнеризация + +### Структура: +- **`docker-compose.yml`** — основной файл оркестрации +- **`Dockerfile`** — базовый образ (если нужен) +- **`bots/*/Dockerfile`** — Dockerfile для каждого бота + +### Сервисы в docker-compose: +- `prometheus` — сбор метрик (порт 9090) +- `grafana` — дашборды (порт 3000) +- `alertmanager` — управление алертами (порт 9093) +- `uptime-kuma` — мониторинг доступности (порт 3001) +- `telegram-bot` — Telegram Helper Bot (порт 8080) +- `anon-bot` — AnonBot (порт 8081) + +### Команды: +```bash +make build # Собрать все контейнеры +make up # Запустить все сервисы +make down # Остановить все сервисы +make restart # Перезапустить все сервисы +make logs # Логи всех сервисов +make logs-bot # Логи Telegram бота +``` + +### Важные правила: +- **Токены ботов**: Используются из GitHub Secrets через переменные окружения +- **Формат**: `TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-${BOT_TOKEN}}` (Secrets имеют приоритет) +- **Build**: Используй `docker-compose build --pull` (не `--no-cache`) для оптимизации +- **Graceful shutdown**: `docker-compose down -t 30` для корректного завершения + +--- + +## 🔐 Безопасность и секреты + +### GitHub Secrets (обязательные): +- `TELEGRAM_BOT_TOKEN` — токен Telegram Helper Bot +- `TELEGRAM_TEST_BOT_TOKEN` — токен тестового бота (опционально) +- `ANON_BOT_TOKEN` — токен AnonBot +- `SSH_PRIVATE_KEY` — приватный ключ для SSH доступа к серверу +- `SERVER_HOST`, `SERVER_USER`, `SSH_PORT` — данные сервера +- `TELEGRAM_CHAT_ID` — ID чата для уведомлений + +### Локальная разработка: +- Используй `.env` файлы для локальных переменных +- `.env` файлы в `.gitignore` — никогда не коммить! +- Токены из Secrets имеют приоритет над `.env` в продакшене + +### Правила: +- ❌ **НЕ коммить** токены, пароли, секреты +- ❌ **НЕ коммить** `.env` файлы +- ✅ Используй `env.template` как шаблон +- ✅ Все секреты храни в GitHub Secrets + +--- + +## 🚀 CI/CD Pipeline + +### Два основных workflow: + +#### 1. `pipeline.yml` (CI): +- **Триггер**: Push в `main`, `develop`, `dev-*`, `feature/**` +- **Jobs**: + - `test` — проверка качества кода и тесты + - `create-pr` — автоматическое создание/обновление PR (только для `dev-*` и `feature/**`) + - `rollback` — ручной откат через `workflow_dispatch` + +#### 2. `deploy.yml` (CD): +- **Триггер**: Мерж PR в `main` +- **Jobs**: + - `deploy` — деплой на сервер + - `smoke-tests` — проверка работоспособности ботов + - `auto-rollback` — автоматический откат при падении smoke tests + +### Правила работы с пайплайном: + +1. **Перед push** — всегда запускай `make code-quality` локально +2. **После успешных тестов** — PR создастся/обновится автоматически +3. **После мержа PR** — деплой запустится автоматически +4. **При проблемах** — используй manual rollback через Actions → Run workflow + +--- + +## 📁 Структура проекта + +``` +prod/ +├── .github/workflows/ # CI/CD пайплайны +│ ├── pipeline.yml # CI: тесты, создание PR +│ └── deploy.yml # CD: деплой, smoke tests, rollback +├── bots/ # Директория для ботов (submodules) +│ ├── telegram-helper-bot/ # Telegram Helper Bot +│ └── AnonBot/ # AnonBot +├── infra/ # Инфраструктура +│ ├── prometheus/ # Конфигурация Prometheus +│ ├── grafana/ # Дашборды и provisioning Grafana +│ ├── alertmanager/ # Конфигурация Alertmanager +│ ├── nginx/ # Nginx конфигурация +│ └── ansible/ # Ansible playbooks +├── scripts/ # Скрипты развертывания +├── tests/ # Тесты инфраструктуры +│ └── infra/ # Тесты инфраструктуры +├── docker-compose.yml # Docker Compose конфигурация +├── Makefile # Команды для управления проектом +├── pytest.ini # Конфигурация pytest +└── README.md # Документация проекта +``` + +### Важные файлы: +- **`docker-compose.yml`** — основная конфигурация сервисов +- **`Makefile`** — команды для разработки и управления +- **`pytest.ini`** — конфигурация тестов +- **`.gitignore`** — исключает `.env`, `.venv`, логи, кэш + +--- + +## 🔧 Разработка + +### Локальная настройка: + +1. **Клонирование и настройка:** + ```bash + git clone + cd prod + cp env.template .env + # Отредактируй .env с локальными значениями + ``` + +2. **Установка зависимостей:** + ```bash + python3 -m venv .venv + source .venv/bin/activate + pip install black isort flake8 pytest + ``` + +3. **Проверка перед коммитом:** + ```bash + make code-quality + ``` + +### Работа с ботами: + +- Боты находятся в `bots/` как отдельные репозитории (submodules или клоны) +- Каждый бот имеет свой Dockerfile +- Токены ботов передаются через environment variables в docker-compose + +--- + +## 📝 Коммиты и PR + +### Формат коммитов: +Используй понятные сообщения: +``` +feat: добавлена функция X +fix: исправлена ошибка Y +chore: обновлены зависимости +docs: обновлена документация +refactor: рефакторинг модуля Z +``` + +### Pull Request: +- **Автоматическое создание**: Для веток `dev-*` и `feature/**` после успешных тестов +- **Обновление**: PR автоматически обновляется при новых коммитах в той же ветке +- **Мерж**: После мержа в `main` запускается автоматический деплой + +--- + +## 🚨 Деплой и Rollback + +### Автоматический деплой: +1. Мерж PR в `main` → запуск `deploy.yml` +2. Валидация токенов ботов +3. Деплой на сервер (SSH) +4. Пересборка контейнеров с `--pull` +5. Health checks с экспоненциальным retry +6. Smoke tests (отправка сообщений в Telegram) +7. При успехе — обновление истории деплоев + +### Автоматический rollback: +- Срабатывает при падении smoke tests +- Откатывается к последнему успешному коммиту из истории +- Пересобираются контейнеры +- Проверяются health checks + +### Ручной rollback: +- Actions → CI & CD pipeline → Run workflow +- Выбери `rollback` и опционально укажи commit hash +- Если commit не указан — используется последний успешный деплой + +--- + +## 🛠️ Полезные команды Makefile + +### Качество кода: +```bash +make code-quality # Все проверки (Black, isort, flake8) +make format # Автоисправление форматирования +make import-fix # Автоисправление импортов +make format-diff # Показать что будет изменено +``` + +### Docker: +```bash +make build # Собрать контейнеры +make up # Запустить сервисы +make down # Остановить сервисы +make restart # Перезапустить +make logs # Логи всех сервисов +make logs-bot # Логи бота +``` + +### Тестирование: +```bash +make test # Все тесты +make test-infra # Тесты инфраструктуры +make test-coverage # С покрытием +make test-clean # Очистить кэш +``` + +### Мониторинг: +```bash +make monitoring # Открыть Grafana +make prometheus # Открыть Prometheus +make status # Статус контейнеров +make health # Health checks +``` + +--- + +## ⚠️ Важные замечания + +### НЕ делай: +- ❌ Коммить `.env` файлы с секретами +- ❌ Коммить токены ботов в код +- ❌ Использовать `docker-compose build --no-cache` без необходимости +- ❌ Пуш в `main` напрямую (только через PR) +- ❌ Игнорировать ошибки форматирования перед коммитом + +### Всегда делай: +- ✅ Запускай `make code-quality` перед коммитом +- ✅ Используй ветки `dev-*` или `feature/**` для разработки +- ✅ Проверяй, что тесты проходят локально +- ✅ Используй GitHub Secrets для токенов в продакшене +- ✅ Проверяй логи после деплоя + +--- + +## 📚 Дополнительные ресурсы + +- **README.md** — основная документация проекта +- **`.cursor/rules/release-notes-template.md`** — шаблон для Release Notes +- **`pytest.ini`** — конфигурация тестов +- **`Makefile`** — все доступные команды (`make help`) + +--- + +## 🔄 Workflow схема + +``` +1. Создание ветки (dev-* или feature/**) + ↓ +2. Разработка + локальные тесты (make code-quality) + ↓ +3. Git commit + push + ↓ +4. GitHub Actions: автоматические тесты + ↓ +5. При успехе: автоматическое создание/обновление PR + ↓ +6. Ручной review и мерж PR в main + ↓ +7. GitHub Actions: автоматический деплой + ↓ +8. Health checks + Smoke tests + ↓ +9. При успехе: ✅ Деплой завершен + При падении: 🔄 Автоматический rollback +``` + +--- + +## 💡 Советы + +1. **Используй Makefile** — все команды там, не запоминай длинные команды +2. **Проверяй локально** — запускай `make code-quality` перед каждым коммитом +3. **Следи за уведомлениями** — Telegram уведомления показывают статус деплоя +4. **Используй правильные ветки** — `dev-*` для автоматического создания PR +5. **Читай логи** — при проблемах смотри логи в GitHub Actions и на сервере diff --git a/.cursor/rules/release-notes-template.md b/.cursor/rules/release-notes-template.md new file mode 100644 index 0000000..ebde57e --- /dev/null +++ b/.cursor/rules/release-notes-template.md @@ -0,0 +1,124 @@ +# Инструкция по оформлению Release Notes + +## Назначение +Этот документ описывает структуру и формат для создания файлов Release Notes (например, `docs/RELEASE_NOTES_DEV-XX.md`). + +## Структура документа + +### 1. Заголовок +```markdown +# Release Notes: [название-ветки] +``` + +### 2. Обзор +Краткий абзац (1-2 предложения), описывающий: +- Количество коммитов в ветке +- Основные направления изменений + +**Формат:** +```markdown +## Обзор +Ветка [название] содержит [N] коммитов с ключевыми улучшениями: [краткое перечисление основных изменений]. +``` + +### 3. Ключевые изменения +Основной раздел с пронумерованными подразделами для каждого значимого изменения. + +**Структура каждого подраздела:** +```markdown +### [Номер]. [Название изменения] + +**Коммит:** `[hash]` + +**Что сделано:** +- [Краткое описание изменения 1] +- [Краткое описание изменения 2] +- [Краткое описание изменения 3] +``` + +**Правила:** +- Каждое изменение = отдельный подраздел +- Название должно быть кратким и понятным +- В разделе "Что сделано" используй маркированные списки +- НЕ перечисляй затронутые файлы +- НЕ указывай статистику строк кода +- Фокусируйся на сути изменений, а не на технических деталях +- Разделяй подразделы горизонтальной линией `---` + +### 4. Основные достижения +Раздел с чекбоксами, подводящий итоги релиза. + +**Формат:** +```markdown +## 🎯 Основные достижения + +✅ [Достижение 1] +✅ [Достижение 2] +✅ [Достижение 3] +``` + +**Правила:** +- Используй эмодзи ✅ для каждого достижения +- Каждое достижение на отдельной строке +- Краткие формулировки (3-5 слов) +- Фокусируйся на ключевых фичах и улучшениях + +### 5. Временная шкала разработки +Раздел с информацией о сроках разработки. + +**Формат:** +```markdown +## 📅 Временная шкала разработки + +**Последние изменения:** [дата] +**Основная разработка:** [период] +**Предыдущие улучшения:** [контекст предыдущих веток/изменений] + +**Хронология коммитов:** +- `[hash]` - [дата и время] - [краткое описание] +- `[hash]` - [дата и время] - [краткое описание] +``` + +**Правила:** +- Используй реальные даты из коммитов +- Формат даты: "DD месяц YYYY" (например, "25 января 2026") +- Для времени используй формат "HH:MM" +- Хронология должна быть в хронологическом порядке (от старых к новым) + +## Стиль написания + +### Общие правила: +- **Краткость**: Фокусируйся на сути, избегай избыточных деталей +- **Ясность**: Используй простые и понятные формулировки +- **Структурированность**: Информация должна быть легко читаемой и сканируемой +- **Без технических деталей**: Не перечисляй файлы, классы, методы (только если это ключевая фича) +- **Без статистики**: Не указывай количество строк кода, файлов и т.д. + +### Язык: +- Используй прошедшее время для описания изменений ("Добавлена", "Реализована", "Обновлена") +- Избегай технического жаргона, если это не необходимо +- Используй активный залог + +### Эмодзи: +- 🔥 для раздела "Ключевые изменения" +- 🎯 для раздела "Основные достижения" +- 📅 для раздела "Временная шкала разработки" +- ✅ для чекбоксов достижений + +## Пример использования + +При создании Release Notes для новой ветки: + +1. Получи список коммитов: `git log [base-branch]..[target-branch] --oneline` +2. Для каждого значимого коммита создай подраздел в "Ключевые изменения" +3. Собери основные достижения в раздел "Основные достижения" +4. Добавь временную шкалу с реальными датами коммитов +5. Проверь, что документ следует структуре и стилю + +## Важные замечания + +- **НЕ включай** информацию о коммитах, которые уже были в базовой ветке (master/main) +- **НЕ перечисляй** все файлы, которые были изменены +- **НЕ указывай** статистику строк кода +- **Фокусируйся** на функциональных изменениях, а не на технических деталях реализации +- Используй **реальные даты** из коммитов, а не предполагаемые diff --git a/FIX_PROMLEMS.md b/FIX_PROMLEMS.md deleted file mode 100644 index 1e11e0a..0000000 --- a/FIX_PROMLEMS.md +++ /dev/null @@ -1,92 +0,0 @@ -# FIX_PROBLEMS.md - -## Текущий статус Prometheus - -### ✅ Что работает: -- Prometheus доступен по `https://188.68.223.37/prometheus/` -- Nginx проксирование настроено правильно -- Другие таргеты работают (Node Exporter, боты) -- Grafana работает по `https://188.68.223.37/grafana/` - -### ❌ Что не работает: - -#### 1. Самомониторинг Prometheus -- **Статус:** `"health":"down"` с ошибкой 404 -- **Проблема:** Prometheus не может получить доступ к своим метрикам по `/metrics` -- **Ошибка:** `"server returned HTTP status 404 Not Found"` -- **Причина:** Prometheus не экспортирует метрики по эндпоинту `/metrics` внутри контейнера - -#### 2. Редирект в Prometheus -- **Проблема:** Редирект с `https://188.68.223.37/prometheus/` на `https://188.68.223.37/prometheus/prometheus/query` -- **Причина:** Неправильная конфигурация Nginx proxy_pass -- **Статус:** ТРЕБУЕТ ИСПРАВЛЕНИЯ - -### 🔧 Быстрые исправления: - -#### Исправление редиректа Prometheus: -Проблема в конфигурации Nginx - нужно убрать слэш в `proxy_pass`: -```nginx -# Было: -proxy_pass http://prometheus_backend/; - -# Должно быть: -proxy_pass http://prometheus_backend; -``` - -#### Исправление самомониторинга: -Проблема в том, что Prometheus не экспортирует метрики. Возможные решения: -1. Убрать job 'prometheus' из конфигурации -2. Добавить параметры для экспорта метрик -3. Использовать другой подход для самомониторинга - -### 📋 Следующие шаги: -1. ✅ Исправить редирект Prometheus -2. ❌ Решить проблему с самомониторингом (пропущено) -3. ✅ Исправить главную страницу -4. ✅ Исправить Alertmanager -5. 🔄 Настроить безопасность -6. 🔄 Настроить Uptime Kuma - ---- - -## Этап 5: Настройка безопасности - -### План действий: -1. **Добавить базовую аутентификацию для Prometheus** - - Создать файл с логином/паролем - - Настроить Nginx для запроса аутентификации - - Проверить, что теперь требуется логин/пароль - -2. **Добавить базовую аутентификацию для Alertmanager** - - Создать файл с логином/паролем - - Настроить Nginx для запроса аутентификации - - Проверить, что теперь требуется логин/пароль - -3. **Перезагрузить Nginx** - - Применить новые настройки безопасности - -4. **Проверить, что теперь требуется логин/пароль** - - Убедиться, что Prometheus и Alertmanager защищены - -**Цель:** Сейчас Prometheus и Alertmanager доступны без аутентификации, что небезопасно. Нужно добавить базовую HTTP аутентификацию. - ---- - -## Этап 6: Настройка Uptime Kuma - -### План действий: -1. **Проверить статус Uptime Kuma** - - Убедиться, что контейнер запущен - - Проверить логи на наличие ошибок - -2. **Настроить мониторинг основных сервисов** - - Добавить мониторинг Grafana - - Добавить мониторинг Prometheus - - Добавить мониторинг Alertmanager - - Добавить мониторинг ботов - -3. **Проверить доступность `/status/`** - - Убедиться, что страница работает - - Проверить отображение статуса сервисов - -**Цель:** Uptime Kuma должен показывать статус всех сервисов и их доступность. diff --git a/MONITORING_AUTH.md b/MONITORING_AUTH.md deleted file mode 100644 index 4810e49..0000000 --- a/MONITORING_AUTH.md +++ /dev/null @@ -1,127 +0,0 @@ -# 🔐 Авторизация для мониторинга - -## Что было добавлено - -Добавлена HTTP Basic Authentication для следующих сервисов мониторинга: - -- **Prometheus** (`/prometheus/`) - метрики и мониторинг -- **Alertmanager** (`/alerts/` и `/api/v1/`) - управление алертами - -## Быстрый старт - -### 1. Автоматическая настройка через Ansible - -```bash -# Развертывание с паролями по умолчанию -ansible-playbook -i infra/ansible/inventory.ini infra/ansible/playbook.yml - -# Развертывание с кастомными паролями -ansible-playbook -i infra/ansible/inventory.ini infra/ansible/playbook.yml \ - -e monitoring_username=myuser \ - -e monitoring_password=mypassword -``` - -### 2. Ручная настройка - -```bash -# Настроить авторизацию -make auth-setup - -# Добавить пользователя -make auth-add-user USER=admin - -# Добавить еще одного пользователя -make auth-add-user USER=operator -``` - -## Управление пользователями - -### Добавление пользователя -```bash -make auth-add-user USER=username -``` - -### Сброс пароля -```bash -make auth-reset USER=username -``` - -### Просмотр пользователей -```bash -make auth-list -``` - -## Доступ к сервисам - -После настройки авторизации: - -- **Prometheus**: `https://your-server/prometheus/` -- **Alertmanager**: `https://your-server/alerts/` -- **Alertmanager API**: `https://your-server/api/v1/` - -При первом обращении браузер запросит логин и пароль. - -## Health Check endpoints - -Следующие endpoints остаются доступными без авторизации: - -- `https://your-server/prometheus/-/healthy` - проверка состояния Prometheus -- `https://your-server/nginx-health` - проверка состояния nginx - -## Файлы конфигурации - -### Nginx конфигурации -- `infra/nginx/conf.d/prometheus.conf` - авторизация для Prometheus -- `infra/nginx/conf.d/alertmanager.conf` - авторизация для Alertmanager - -### Ansible -- `infra/ansible/playbook.yml` - автоматическая настройка авторизации -- `infra/ansible/group_vars/all.yml` - переменные по умолчанию - -### Скрипты -- `scripts/generate_auth_passwords.sh` - генерация паролей -- `infra/nginx/AUTH_SETUP.md` - подробная документация - -## Безопасность - -- Пароли хранятся в зашифрованном виде в `/etc/nginx/passwords/monitoring.htpasswd` -- Файл доступен только для чтения пользователю root и группе www-data -- Используется HTTPS для всех соединений -- Настроена защита от брутфорса через fail2ban - -## Устранение проблем - -### Проверка конфигурации nginx -```bash -sudo nginx -t -``` - -### Проверка файла паролей -```bash -make auth-list -``` - -### Проверка логов -```bash -sudo tail -f /var/log/nginx/error.log -sudo tail -f /var/log/nginx/access.log -``` - -### Перезапуск nginx -```bash -sudo systemctl reload nginx -``` - -## Переменные Ansible - -В файле `infra/ansible/group_vars/all.yml`: - -```yaml -monitoring_username: "admin" # Имя пользователя по умолчанию -monitoring_password: "admin123" # Пароль по умолчанию -``` - -Можно переопределить через: -- Переменные окружения -- `--extra-vars` в ansible-playbook -- Vault файлы для безопасного хранения паролей