telegram-helper-bot/docs/OPERATIONS.md

# Операционные команды для управления ботом

> **⚠️ ВАЖНО:** Все команды выполняются из корневой директории проекта

## 🔧 Основные команды

### Запуск и остановка
```bash
# Запустить всю инфраструктуру (Prometheus + Бот)
docker-compose up -d

# Запустить только бота
docker-compose up -d telegram-bot

# Запустить только Prometheus
docker-compose up -d prometheus

# Остановить все сервисы
docker-compose down

# Остановить только бота
docker-compose stop telegram-bot

# Остановить только Prometheus
docker-compose stop prometheus
```

### Сборка
```bash
# Собрать все контейнеры
docker-compose build

# Собрать только бота
docker-compose build telegram-bot

# Собрать только Prometheus
docker-compose build prometheus

# Пересобрать и запустить все
docker-compose up -d --build

# Пересобрать и запустить только бота
docker-compose up -d --build telegram-bot
```

## 📊 Мониторинг и логи

### Просмотр логов
```bash
# Логи всех сервисов
docker-compose logs -f

# Логи только бота
docker-compose logs -f telegram-bot

# Логи Prometheus
docker-compose logs -f prometheus

# Логи в реальном времени (последние 100 строк)
docker-compose logs -f --tail=100
```

### Статус и здоровье
```bash
# Статус всех контейнеров
docker-compose ps

# Проверить здоровье всех сервисов
docker-compose ps | grep -E "(unhealthy|starting)"

# Проверить здоровье бота
curl -f http://localhost:8080/health || echo "❌ Бот недоступен"

# Проверить здоровье Prometheus
curl -f http://localhost:9090/-/healthy || echo "❌ Prometheus недоступен"
```

## 🔄 Управление сервисами

### Перезапуск
```bash
# Перезапустить все сервисы
docker-compose restart

# Перезапустить только бота
docker-compose restart telegram-bot

# Перезапустить только Prometheus
docker-compose restart prometheus
```

### Обновление
```bash
# Обновить код и перезапустить
git pull origin main && docker-compose up -d --build

# Обновить только бота
git pull origin main && docker-compose up -d --build telegram-bot

# Обновить только Prometheus
docker-compose pull prometheus && docker-compose up -d prometheus
```

## 🧪 Тестирование

### Запуск тестов
```bash
# Запустить все тесты
docker-compose run --rm telegram-bot sh -c "pip install --no-cache-dir -r requirements-dev.txt && pytest"

# Тесты с покрытием
docker-compose run --rm telegram-bot sh -c "pip install --no-cache-dir -r requirements-dev.txt && pytest --cov=helper_bot --cov-report=term-missing"

# Тесты только бота
docker-compose run --rm telegram-bot sh -c "pip install --no-cache-dir -r requirements-dev.txt && pytest helper_bot/"

# Тесты с HTML отчетом
docker-compose run --rm telegram-bot sh -c "pip install --no-cache-dir -r requirements-dev.txt && pytest --cov=helper_bot --cov-report=html"

# Тесты конкретного модуля
docker-compose run --rm telegram-bot sh -c "pip install --no-cache-dir -r requirements-dev.txt && pytest helper_bot/handlers/admin/"
```

## 🛠️ Разработка

### Отладка
```bash
# Проверить версию Python в контейнере
docker exec bots_telegram_bot python --version

# Открыть shell в контейнере бота
docker exec -it bots_telegram_bot sh

# Проверить установленные пакеты
docker exec bots_telegram_bot pip list

# Проверить переменные окружения
docker exec bots_telegram_bot env | grep TELEGRAM

# Проверить логи бота в реальном времени
docker exec bots_telegram_bot tail -f /app/logs/helper_bot_$(date +%Y-%m-%d).log
```

### База данных
```bash
# Создать backup базы
tar -czf "backup-$(date +%Y%m%d-%H%M%S).tar.gz" database/ logs/ .env

# Восстановить из backup
tar -xzf backup-20241231-120000.tar.gz

# Подключиться к базе данных
docker exec -it bots_telegram_bot sqlite3 /app/database/tg-bot-database.db

# Проверить размер базы данных
docker exec bots_telegram_bot ls -lh /app/database/tg-bot-database.db

# Очистить логи (⚠️ ОСТОРОЖНО!)
docker exec bots_telegram_bot find /app/logs -name "*.log" -mtime +7 -delete
```

## 🚨 Аварийные ситуации

### Диагностика
```bash
# Проверить использование ресурсов
docker stats --no-stream

# Проверить сетевые соединения
docker network ls
docker network inspect prod_bots_network

# Проверить логи ошибок
docker-compose logs | grep -i error

# Проверить использование диска
docker system df

# Проверить свободное место
docker exec bots_telegram_bot df -h
```

### Восстановление
```bash
# Принудительная перезагрузка всех сервисов
docker-compose down && docker-compose up -d

# Очистка всех контейнеров и образов
docker-compose down -v --rmi all
docker system prune -f

# Восстановление из последнего backup
ls -t backup-*.tar.gz | head -1 | xargs -I {} tar -xzf {}

# Принудительная перезагрузка только бота
docker-compose stop telegram-bot
docker-compose rm -f telegram-bot
docker-compose up -d --build telegram-bot
```

## 📱 Доступ к сервисам

### Веб-интерфейсы
- **Prometheus**: http://localhost:9090
- **Бот Health**: http://localhost:8080/health
- **Бот Metrics**: http://localhost:8080/metrics

### Полезные команды
```bash
# Открыть Prometheus в браузере
open http://localhost:9090

# Открыть метрики бота в браузере
open http://localhost:8080/metrics

# Открыть health check бота в браузере
open http://localhost:8080/health

# Проверить доступность сервисов
curl -s http://localhost:8080/health | jq . || echo "Бот недоступен"
curl -s http://localhost:9090/-/healthy || echo "Prometheus недоступен"
```

## 🔍 Отладка проблем

### Частые проблемы
```bash
# Бот не отвечает
docker-compose restart telegram-bot && docker-compose logs -f telegram-bot

# Prometheus недоступен
docker-compose restart prometheus && curl -f http://localhost:9090/-/healthy

# Проблемы с базой данных
docker exec bots_telegram_bot sqlite3 /app/database/tg-bot-database.db ".tables"

# Проблемы с сетью
docker network inspect prod_bots_network

# Проблемы с правами доступа
docker exec bots_telegram_bot ls -la /app/database/
docker exec bots_telegram_bot ls -la /app/logs/
```

### Полезные alias'ы для .bashrc/.zshrc
```bash
# Добавить в ~/.bashrc или ~/.zshrc
alias bot='cd /Users/andrejkatyhin/PycharmProjects/prod && docker-compose'
alias bot-logs='cd /Users/andrejkatyhin/PycharmProjects/prod && docker-compose logs -f telegram-bot'
alias bot-restart='cd /Users/andrejkatyhin/PycharmProjects/prod && docker-compose restart telegram-bot'
alias bot-status='cd /Users/andrejkatyhin/PycharmProjects/prod && docker-compose ps'
alias bot-shell='cd /Users/andrejkatyhin/PycharmProjects/prod && docker exec -it bots_telegram_bot sh'
alias prometheus='cd /Users/andrejkatyhin/PycharmProjects/prod && docker-compose logs -f prometheus'
```

## 📝 Примеры использования

### Типичный workflow разработки
```bash
# 1. Внести изменения в код
cd /Users/andrejkatyhin/PycharmProjects/prod/bots/telegram-helper-bot
# ... редактируем код ...

# 2. Пересобрать и перезапустить бота
cd /Users/andrejkatyhin/PycharmProjects/prod
docker-compose up -d --build telegram-bot

# 3. Проверить логи
docker-compose logs -f telegram-bot

# 4. Запустить тесты
docker-compose run --rm telegram-bot sh -c "pip install --no-cache-dir -r requirements-dev.txt && pytest helper_bot/"
```

### Мониторинг в продакшене
```bash
# Проверить здоровье всех сервисов
docker-compose ps | grep -E "(unhealthy|starting)"

# Посмотреть статус
docker-compose ps

# Проверить логи ошибок
docker-compose logs | grep -i error

# Создать backup
tar -czf "backup-$(date +%Y%m%d-%H%M%S).tar.gz" database/ logs/ .env

# Проверить метрики
curl -s http://localhost:8080/metrics | head -20
```

### Отладка проблем
```bash
# Бот не запускается
docker-compose logs telegram-bot

# Проверить конфигурацию
docker exec bots_telegram_bot cat /app/.env

# Проверить права доступа к файлам
docker exec bots_telegram_bot ls -la /app/

# Проверить сетевые соединения
docker exec bots_telegram_bot netstat -tulpn

# Проверить процессы
docker exec bots_telegram_bot ps aux
```