hubmc-datagw/DEPLOYMENT.md

# Развертывание HubGW

Инструкции по развертыванию FastAPI-шлюза HubGW.

## Требования

- Python 3.11+
- PostgreSQL 12+
- Poetry (для управления зависимостями)

## Установка

1. Клонируйте репозиторий:
```bash
git clone <repository-url>
cd hubmc-datagw
```

2. Установите зависимости:
```bash
poetry install
```

3. Создайте файл `.env` на основе `.env.example`:
```bash
cp .env.example .env
```

4. Настройте переменные окружения в `.env`:
```env
APP_ENV=prod
APP_HOST=0.0.0.0
APP_PORT=8080
APP_LOG_LEVEL=INFO

DB_DSN=postgresql+asyncpg://user:password@localhost:5432/hubgw
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=10

API_KEY=your-secure-api-key-here
RATE_LIMIT_PER_MIN=1000
```

## Настройка базы данных

1. Создайте базу данных PostgreSQL:
```sql
CREATE DATABASE hubgw;
CREATE USER hubgw_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE hubgw TO hubgw_user;
```

2. Создайте таблицы (в будущем будет добавлена миграция):
```sql
-- Таблицы будут созданы автоматически при первом запуске
-- или можно использовать Alembic для миграций
```

## Запуск

### Разработка
```bash
poetry run hubgw
```

### Продакшн с Gunicorn
```bash
poetry run gunicorn hubgw.main:create_app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8080
```

### Продакшн с Docker
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Установка Poetry
RUN pip install poetry

# Копирование файлов
COPY pyproject.toml poetry.lock ./
COPY src/ ./src/

# Установка зависимостей
RUN poetry config virtualenvs.create false
RUN poetry install --no-dev

# Запуск приложения
CMD ["poetry", "run", "hubgw"]
```

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

### Логи
Логи сохраняются в директории `logs/` в продакшне:
- `logs/hubgw.log` - основные логи приложения
- Ротация каждый день
- Хранение 30 дней
- Сжатие старых логов

### Health Check
```bash
curl http://localhost:8080/api/v1/health/
```

## Безопасность

1. **API Key**: Используйте сильный, случайный API ключ
2. **HTTPS**: Настройте SSL/TLS в продакшне
3. **Firewall**: Ограничьте доступ к порту 8080
4. **База данных**: Используйте отдельного пользователя БД с минимальными правами

## Масштабирование

### Горизонтальное масштабирование
- Используйте load balancer (nginx, HAProxy)
- Настройте sticky sessions если необходимо
- Используйте внешний Redis для сессий

### Вертикальное масштабирование
- Увеличьте `DB_POOL_SIZE` и `DB_MAX_OVERFLOW`
- Настройте `RATE_LIMIT_PER_MIN` под нагрузку
- Мониторьте использование памяти и CPU

## Резервное копирование

1. **База данных**: Регулярные бэкапы PostgreSQL
2. **Конфигурация**: Сохраните файл `.env` в безопасном месте
3. **Логи**: Архивируйте важные логи

## Обновление

1. Остановите приложение
2. Создайте бэкап базы данных
3. Обновите код
4. Установите новые зависимости: `poetry install`
5. Примените миграции (если есть)
6. Запустите приложение
7. Проверьте работоспособность

## Устранение неполадок

### Проблемы с подключением к БД
- Проверьте строку подключения в `DB_DSN`
- Убедитесь, что PostgreSQL запущен
- Проверьте права пользователя БД

### Проблемы с API
- Проверьте правильность API ключа
- Убедитесь, что заголовок `X-API-Key` передается
- Проверьте логи приложения

### Проблемы с производительностью
- Увеличьте размер пула БД
- Проверьте индексы в базе данных
- Мониторьте использование ресурсов