hubmc-datagw/DEPLOYMENT.md

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

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

Требования

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

Установка

1. Клонируйте репозиторий:

git clone <repository-url>
cd hubmc-datagw

2. Установите зависимости:

poetry install

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

cp .env.example .env

4. Настройте переменные окружения в .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:

CREATE DATABASE hubgw;
CREATE USER hubgw_user WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE hubgw TO hubgw_user;

2. Создайте таблицы (в будущем будет добавлена миграция):

-- Таблицы будут созданы автоматически при первом запуске
-- или можно использовать Alembic для миграций

Запуск

Разработка

poetry run hubgw

Продакшн с Gunicorn

poetry run gunicorn hubgw.main:create_app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8080

Продакшн с Docker

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

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 передается
• Проверьте логи приложения

Проблемы с производительностью

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