From e87f4af82f29774f97a8de696702eaade24ab60e Mon Sep 17 00:00:00 2001 From: Andrey Date: Wed, 28 Jan 2026 01:47:04 +0300 Subject: [PATCH] =?UTF-8?q?=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=B8=D0=BB=20de?= =?UTF-8?q?ployment-guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/rules/deployment-guide.md | 410 ++++++++++++++++++++++++++++++ 1 file changed, 410 insertions(+) create mode 100644 .cursor/rules/deployment-guide.md diff --git a/.cursor/rules/deployment-guide.md b/.cursor/rules/deployment-guide.md new file mode 100644 index 0000000..dd4d641 --- /dev/null +++ b/.cursor/rules/deployment-guide.md @@ -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 +``` + +### 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 +git pull origin +``` + +### 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 --tail=N + +# Перезапуск конкретного сервиса +docker-compose restart + +# Остановка всей инфраструктуры +docker-compose down + +# Запуск всей инфраструктуры +docker-compose up -d + +# Пересборка без кэша +docker-compose build --no-cache + +# Принудительное пересоздание контейнера +docker-compose up -d --build --force-recreate --no-deps +``` + +### Git + +```bash +# Проверка состояния +git status +git branch + +# Переключение веток +git checkout + +# Получение изменений +git fetch origin +git pull origin + +# История коммитов +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. **Креды доступа** - креды сервера предоставляются пользователем в запросе и НЕ сохраняются в документации. После завершения деплоя - забыть все креды. + +--- + +## Контакты + +При возникновении проблем или вопросов обращаться к владельцу проекта.