Andrey
8e595bf7f2
- Deleted FIX_PROMLEMS.md and MONITORING_AUTH.md as they contained obsolete information regarding Prometheus and Alertmanager configurations. - This cleanup helps streamline the documentation and focuses on current setup practices.
410 lines
17 KiB
Plaintext
410 lines
17 KiB
Plaintext
---
|
||
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 и на сервере
|