kerrad/prod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge dev-4 into main #4

Merged
KerradKerridi merged 5 commits from dev-4 into main 2026-01-25 16:58:22 +00:00
Conversation 0 Commits 5 Files Changed 5 +533 -219
4 changed files with 533 additions and 219 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 8e595bf7f2 - Show all commits

409
.cursor/rules/my-custom-rule.mdc Normal file
View File

@@ -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 <repo>
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 и на сервере

124
.cursor/rules/release-notes-template.md Normal file
View File

@@ -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)
- **НЕ перечисляй** все файлы, которые были изменены
- **НЕ указывай** статистику строк кода
- **Фокусируйся** на функциональных изменениях, а не на технических деталях реализации
- Используй **реальные даты** из коммитов, а не предполагаемые

92
FIX_PROMLEMS.md
View File

@@ -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 должен показывать статус всех сервисов и их доступность.

127
MONITORING_AUTH.md
View File

@@ -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 файлы для безопасного хранения паролей