добавил deployment-guide
This commit is contained in:
410
.cursor/rules/deployment-guide.md
Normal file
410
.cursor/rules/deployment-guide.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# Инструкция по деплою на продакшен
|
||||
|
||||
## Общая информация
|
||||
|
||||
**⚠️ ВАЖНО:** Креды для доступа к серверу (SSH хост, порт, пользователь) предоставляются пользователем в запросе и НЕ должны сохраняться в этой документации!
|
||||
|
||||
**Технологический стек:**
|
||||
- Python: 3.11.9
|
||||
- Docker: Alpine Linux
|
||||
- База данных: SQLite
|
||||
|
||||
**Директория проекта на сервере:** `/home/prod/bots/telegram-helper-bot`
|
||||
**Директория для команд инфраструктуры:** `/home/prod`
|
||||
**База данных:** `/home/prod/bots/telegram-helper-bot/database/tg-bot-database.db`
|
||||
|
||||
---
|
||||
|
||||
## Этап 1: Подготовка на локальной машине
|
||||
|
||||
### 1.1. Проверка состояния репозитория
|
||||
|
||||
```bash
|
||||
git status
|
||||
git log --oneline -10
|
||||
git diff master...HEAD --stat
|
||||
```
|
||||
|
||||
### 1.2. Пуш ветки в репозиторий
|
||||
|
||||
```bash
|
||||
git push -u origin <branch-name>
|
||||
```
|
||||
|
||||
### 1.3. Создание Release Notes
|
||||
|
||||
**ВАЖНО:** Release notes создаются ПОСЛЕ пуша, чтобы не попали в репозиторий!
|
||||
|
||||
1. Использовать шаблон из `.cursor/rules/release-notes-template.md`
|
||||
2. Создать файл `RELEASE_NOTES_DEV-XX.md` в корне проекта
|
||||
3. Собрать информацию о коммитах:
|
||||
```bash
|
||||
git log master..HEAD --pretty=format:"%h - %ai - %s" --reverse
|
||||
```
|
||||
4. Заполнить release notes по шаблону:
|
||||
- Обзор (количество коммитов и основные направления)
|
||||
- Ключевые изменения (каждый значимый коммит)
|
||||
- Основные достижения (чекбоксы с эмодзи ✅)
|
||||
- Временная шкала разработки
|
||||
|
||||
**Примечание:** Release notes используются для Pull Request, затем файл удаляется из рабочей директории.
|
||||
|
||||
### 1.4. Создание дополнительной документации (если требуется)
|
||||
|
||||
**ВАЖНО:** Документацию создавать ПОСЛЕ пуша, чтобы она не попала в репозиторий!
|
||||
|
||||
1. Создать или обновить инструкции по деплою
|
||||
2. Обновить необходимую техническую документацию
|
||||
3. Убедиться, что не добавляются файлы с секретами
|
||||
|
||||
---
|
||||
|
||||
## Этап 2: Деплой на сервер (тестовая ветка)
|
||||
|
||||
**ВАЖНО:** Креды для подключения к серверу должны быть предоставлены пользователем в запросе.
|
||||
|
||||
### 2.1. Подключение к серверу и остановка инфраструктуры
|
||||
|
||||
```bash
|
||||
# Подключиться к серверу через SSH
|
||||
# Перейти в директорию для команд инфраструктуры
|
||||
cd /home/prod
|
||||
make down
|
||||
```
|
||||
|
||||
**Проверка:** Убедиться, что все контейнеры остановлены.
|
||||
|
||||
### 2.2. Создание бэкапа базы данных
|
||||
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot/database
|
||||
cp tg-bot-database.db tg-bot-database_$(date +%Y%m%d_%H%M%S).db
|
||||
ls -lh tg-bot-database*.db
|
||||
```
|
||||
|
||||
**ВАЖНО:** Всегда создавать бэкап с timestamp перед применением миграций!
|
||||
|
||||
### 2.3. Переключение на ветку и подтягивание изменений
|
||||
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot
|
||||
git fetch origin
|
||||
git checkout <branch-name>
|
||||
git pull origin <branch-name>
|
||||
```
|
||||
|
||||
### 2.4. Установка зависимостей (если изменились)
|
||||
|
||||
#### Если виртуальное окружение уже существует:
|
||||
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
#### Если виртуального окружения нет:
|
||||
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install --upgrade pip
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**Примечание:** Виртуальное окружение `.venv` на сервере используется только для применения миграций и утилит. Бот работает в Docker-контейнере.
|
||||
|
||||
### 2.5. Применение миграций базы данных
|
||||
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot
|
||||
.venv/bin/python scripts/apply_migrations.py
|
||||
```
|
||||
|
||||
**ВАЖНО:**
|
||||
- Миграции применяются **ПЕРЕД** запуском контейнеров
|
||||
- База должна быть "спящей" (контейнеры выключены)
|
||||
- Проверить вывод скрипта на наличие ошибок
|
||||
|
||||
**Вывод при успехе:**
|
||||
```
|
||||
📋 Найдено новых миграций: X
|
||||
✅ Все миграции применены успешно (X шт.)
|
||||
```
|
||||
|
||||
### 2.6. Запуск инфраструктуры
|
||||
|
||||
```bash
|
||||
cd /home/prod
|
||||
make up
|
||||
```
|
||||
|
||||
### 2.7. Пересборка контейнера telegram-bot
|
||||
|
||||
Используем команду с гарантией применения изменений:
|
||||
|
||||
```bash
|
||||
cd /home/prod
|
||||
docker-compose up -d --build --force-recreate --no-deps telegram-bot
|
||||
```
|
||||
|
||||
**Что делает команда:**
|
||||
- `--build` - пересобирает образ
|
||||
- `--force-recreate` - принудительно пересоздает контейнер
|
||||
- `--no-deps` - не затрагивает зависимые сервисы
|
||||
- Гарантирует доставку нового кода в контейнер без кэша
|
||||
|
||||
### 2.8. Проверка работоспособности
|
||||
|
||||
```bash
|
||||
# Проверка статуса всех контейнеров
|
||||
docker-compose ps
|
||||
|
||||
# Проверка логов telegram-bot
|
||||
docker-compose logs telegram-bot --tail=50
|
||||
|
||||
# Или напрямую
|
||||
docker logs bots_telegram_bot --tail=50
|
||||
```
|
||||
|
||||
**Что проверять в логах:**
|
||||
- ✅ База данных инициализирована
|
||||
- ✅ Scoring Manager инициализирован (если используется)
|
||||
- ✅ Metrics server запущен на порту 8080
|
||||
- ✅ Нет критических ошибок
|
||||
- ✅ Бот обрабатывает команды
|
||||
|
||||
**На этом этапе:** Ждать подтверждения от владельца о мердже ветки в master.
|
||||
|
||||
---
|
||||
|
||||
## Этап 3: Финальный деплой на master
|
||||
|
||||
**ВАЖНО:** Выполняется только после подтверждения мерджа ветки в master!
|
||||
|
||||
### 3.1. Остановка инфраструктуры
|
||||
|
||||
```bash
|
||||
cd /home/prod
|
||||
make down
|
||||
```
|
||||
|
||||
### 3.2. Переключение на master и получение изменений
|
||||
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot
|
||||
git checkout master
|
||||
git pull origin master
|
||||
```
|
||||
|
||||
**Проверка:** Убедиться, что получен коммит с мерджем.
|
||||
|
||||
### 3.3. Запуск инфраструктуры
|
||||
|
||||
```bash
|
||||
cd /home/prod
|
||||
make up
|
||||
```
|
||||
|
||||
### 3.4. Пересборка контейнера telegram-bot с кодом master
|
||||
|
||||
```bash
|
||||
cd /home/prod
|
||||
docker-compose up -d --build --force-recreate --no-deps telegram-bot
|
||||
```
|
||||
|
||||
### 3.5. Финальная проверка
|
||||
|
||||
```bash
|
||||
# Статус контейнеров
|
||||
docker-compose ps
|
||||
|
||||
# Логи
|
||||
docker logs bots_telegram_bot --tail=50
|
||||
```
|
||||
|
||||
**Проверить:**
|
||||
- ✅ Все контейнеры в состоянии `Up` и `healthy`
|
||||
- ✅ Логи не содержат критических ошибок
|
||||
- ✅ Бот отвечает на команды в Telegram
|
||||
|
||||
### 3.6. Завершение работы
|
||||
|
||||
- Выйти с сервера
|
||||
- Забыть все креды доступа (не сохранять их)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Проблема: Миграции не применяются
|
||||
|
||||
**Решение:**
|
||||
1. Проверить, что контейнеры остановлены
|
||||
2. Проверить права доступа к файлу БД
|
||||
3. Посмотреть логи скрипта apply_migrations.py
|
||||
4. Восстановить БД из бэкапа при необходимости:
|
||||
```bash
|
||||
cd /home/prod/bots/telegram-helper-bot/database
|
||||
cp tg-bot-database_YYYYMMDD_HHMMSS.db tg-bot-database.db
|
||||
```
|
||||
|
||||
### Проблема: Контейнер не запускается
|
||||
|
||||
**Решение:**
|
||||
1. Проверить логи контейнера:
|
||||
```bash
|
||||
docker logs bots_telegram_bot --tail=100
|
||||
```
|
||||
2. Проверить переменные окружения в `.env`
|
||||
3. Проверить healthcheck:
|
||||
```bash
|
||||
docker inspect bots_telegram_bot | grep -A 20 Health
|
||||
```
|
||||
|
||||
### Проблема: Код не обновился в контейнере
|
||||
|
||||
**Решение:**
|
||||
Использовать принудительную пересборку без кэша:
|
||||
```bash
|
||||
docker-compose down telegram-bot
|
||||
docker-compose build --no-cache telegram-bot
|
||||
docker-compose up -d telegram-bot
|
||||
```
|
||||
|
||||
### Проблема: Нет виртуального окружения
|
||||
|
||||
**Решение:**
|
||||
Создать виртуальное окружение:
|
||||
```bash
|
||||
# Установить python3-venv (если нужно)
|
||||
sudo apt install -y python3.11-venv
|
||||
|
||||
# Создать venv
|
||||
cd /home/prod/bots/telegram-helper-bot
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install --upgrade pip
|
||||
.venv/bin/pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Последовательность действий для агента
|
||||
|
||||
### Этап 1: Локальная подготовка
|
||||
|
||||
1. Проверить состояние репозитория (`git status`, `git log`)
|
||||
2. Запушить ветку в репозиторий
|
||||
3. Создать Release Notes по шаблону - **ПОСЛЕ пуша!**
|
||||
4. Создать дополнительную документацию (если требуется) - **ПОСЛЕ пуша!**
|
||||
5. Сообщить пользователю о готовности к деплою
|
||||
|
||||
### Этап 2: Деплой на dev-ветку
|
||||
|
||||
1. Подключиться к серверу (креды из запроса пользователя)
|
||||
2. Остановить инфраструктуру (`make down` из `/home/prod`)
|
||||
3. Создать бэкап БД с timestamp
|
||||
4. Переключиться на dev-ветку и подтянуть изменения
|
||||
5. Установить/обновить зависимости Python (если требуется)
|
||||
6. Применить миграции БД (через `.venv/bin/python scripts/apply_migrations.py`)
|
||||
7. Проверить успешность применения миграций
|
||||
8. Запустить инфраструктуру (`make up`)
|
||||
9. Пересобрать контейнер telegram-bot с `--build --force-recreate --no-deps`
|
||||
10. Проверить статус контейнеров и логи
|
||||
11. Сообщить пользователю о готовности и ждать подтверждения "ОК"
|
||||
|
||||
### Этап 3: Финальный деплой на master
|
||||
|
||||
**Выполняется только после получения "ОК" от пользователя (означает мердж в master)**
|
||||
|
||||
1. Остановить инфраструктуру
|
||||
2. Переключиться на master и подтянуть изменения
|
||||
3. Запустить инфраструктуру
|
||||
4. Пересобрать контейнер telegram-bot с `--build --force-recreate --no-deps`
|
||||
5. Проверить финальный статус и логи
|
||||
6. Сообщить о успешном завершении деплоя
|
||||
7. Завершить SSH-сессию и забыть все креды
|
||||
|
||||
---
|
||||
|
||||
## Важные команды
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# Просмотр всех контейнеров
|
||||
docker-compose ps
|
||||
|
||||
# Логи конкретного сервиса
|
||||
docker-compose logs <service-name> --tail=N
|
||||
|
||||
# Перезапуск конкретного сервиса
|
||||
docker-compose restart <service-name>
|
||||
|
||||
# Остановка всей инфраструктуры
|
||||
docker-compose down
|
||||
|
||||
# Запуск всей инфраструктуры
|
||||
docker-compose up -d
|
||||
|
||||
# Пересборка без кэша
|
||||
docker-compose build --no-cache <service-name>
|
||||
|
||||
# Принудительное пересоздание контейнера
|
||||
docker-compose up -d --build --force-recreate --no-deps <service-name>
|
||||
```
|
||||
|
||||
### Git
|
||||
|
||||
```bash
|
||||
# Проверка состояния
|
||||
git status
|
||||
git branch
|
||||
|
||||
# Переключение веток
|
||||
git checkout <branch-name>
|
||||
|
||||
# Получение изменений
|
||||
git fetch origin
|
||||
git pull origin <branch-name>
|
||||
|
||||
# История коммитов
|
||||
git log --oneline -N
|
||||
git log master..HEAD --pretty=format:"%h - %ai - %s" --reverse
|
||||
```
|
||||
|
||||
### Работа с БД
|
||||
|
||||
```bash
|
||||
# Создание бэкапа с timestamp
|
||||
cp tg-bot-database.db tg-bot-database_$(date +%Y%m%d_%H%M%S).db
|
||||
|
||||
# Просмотр бэкапов
|
||||
ls -lh tg-bot-database*.db
|
||||
|
||||
# Восстановление из бэкапа
|
||||
cp tg-bot-database_BACKUP.db tg-bot-database.db
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Примечания
|
||||
|
||||
1. **Виртуальное окружение на сервере** - используется только для запуска утилит и миграций. Бот работает в Docker-контейнере.
|
||||
|
||||
2. **Бэкапы БД** - создаются перед каждым применением миграций с timestamp в имени файла.
|
||||
|
||||
3. **Пересборка контейнера** - всегда использовать `--force-recreate --no-deps` для гарантии применения изменений.
|
||||
|
||||
4. **Миграции** - применяются только при остановленных контейнерах к "спящей" базе данных.
|
||||
|
||||
5. **Release notes** - создаются ПОСЛЕ пуша, чтобы не попадали в репозиторий. Используются для Pull Request, затем удаляются из рабочей директории.
|
||||
|
||||
6. **Документация после пуша** - вся документация и инструкции создаются ПОСЛЕ пуша в репозиторий, чтобы не попадали в коммиты и удалённый репозиторий.
|
||||
|
||||
7. **Креды доступа** - креды сервера предоставляются пользователем в запросе и НЕ сохраняются в документации. После завершения деплоя - забыть все креды.
|
||||
|
||||
---
|
||||
|
||||
## Контакты
|
||||
|
||||
При возникновении проблем или вопросов обращаться к владельцу проекта.
|
||||
Reference in New Issue
Block a user