sfera-new/docs/infrastructure/DEPLOYMENT_GUIDE.md

Руководство по развертыванию SFERA

🚀 Обзор

Это комплексное руководство по развертыванию платформы SFERA в различных окружениях - от локальной разработки до production развертывания с использованием Docker и оркестрации контейнеров.

📋 Требования к системе

Минимальные требования

• CPU: 2 ядра (4 рекомендуется для production)
• RAM: 4GB (8GB рекомендуется для production)
• Диск: 20GB свободного места (SSD рекомендуется)
• OS: Linux Ubuntu 20.04+, CentOS 8+, или macOS 11+

Программное обеспечение

• Node.js: 18.17.0+ (LTS рекомендуется)
• npm: 9.0.0+
• Docker: 24.0.0+
• Docker Compose: 2.20.0+
• PostgreSQL: 14+ (для прямого подключения)
• Git: 2.30.0+

🛠 Локальная разработка

1. Клонирование репозитория

git clone <repository-url>
cd sfera

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

# Установка Node.js зависимостей
npm install

# Генерация Prisma клиента
npx prisma generate

3. Настройка окружения

Создайте файл .env.local:

# База данных
DATABASE_URL="postgresql://user:password@localhost:5432/sfera_dev"

# SMS сервис (разработка)
SMS_AERO_EMAIL="test@example.com"
SMS_AERO_API_KEY="test-key"
SMS_AERO_API_URL="https://gate.smsaero.ru/v2"
SMS_DEV_MODE="true"

# DaData API
DADATA_API_KEY="your-dadata-key"
DADATA_API_URL="https://suggestions.dadata.ru/suggestions/api/4_1/rs"

# Marketplace APIs
WILDBERRIES_API_URL="https://common-api.wildberries.ru"
OZON_API_URL="https://api-seller.ozon.ru"

# JWT секрет
JWT_SECRET="your-super-secret-jwt-key-for-development"

# Next.js
NEXT_TELEMETRY_DISABLED=1

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

# Применение миграций
npx prisma migrate dev

# Заполнение начальными данными (опционально)
npx prisma db seed

5. Запуск приложения

# Режим разработки
npm run dev

# Приложение будет доступно на http://localhost:3000

🐳 Docker развертывание

Структура Docker файлов

sfera/
├── Dockerfile                 # Основной образ приложения
├── docker-compose.yml        # Локальная оркестрация
├── docker-compose.prod.yml   # Production конфигурация
├── .env                      # Переменные окружения
└── stack.env                # Production переменные

Локальный Docker запуск

# Сборка и запуск всех сервисов
docker-compose up --build

# Запуск в фоновом режиме
docker-compose up -d

# Просмотр логов
docker-compose logs -f app

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

Production Docker развертывание

1. Подготовка окружения

# Создание production переменных
cp .env stack.env

# Редактирование production конфигурации
nano stack.env

2. Production переменные окружения

# DATABASE
DATABASE_URL="postgresql://sfera_user:secure_password@db_host:5432/sfera_prod"

# Security
JWT_SECRET="super-secure-production-jwt-secret-256-bit"

# SMS сервис
SMS_AERO_EMAIL="production@company.com"
SMS_AERO_API_KEY="production-sms-key"
SMS_DEV_MODE="false"

# API ключи
DADATA_API_KEY="production-dadata-key"
WILDBERRIES_API_URL="https://common-api.wildberries.ru"
OZON_API_URL="https://api-seller.ozon.ru"

# System
NODE_ENV="production"
NEXT_TELEMETRY_DISABLED=1

3. Production сборка

# Сборка production образа
docker build -t sfera:latest \
  --build-arg DATABASE_URL="${DATABASE_URL}" \
  --build-arg JWT_SECRET="${JWT_SECRET}" \
  --build-arg SMS_AERO_EMAIL="${SMS_AERO_EMAIL}" \
  --build-arg SMS_AERO_API_KEY="${SMS_AERO_API_KEY}" \
  --build-arg DADATA_API_KEY="${DADATA_API_KEY}" \
  .

# Запуск production контейнера
docker run -d \
  --name sfera-app \
  --env-file stack.env \
  -p 3017:3000 \
  --restart unless-stopped \
  sfera:latest

🏗 Multi-stage Docker архитектура

Описание этапов сборки

1. Base Stage

FROM node:18-alpine AS base

• Базовый образ с Node.js 18 Alpine
• Минимальный размер для оптимизации

2. Dependencies Stage

FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json* ./
RUN npm ci

• Установка только production зависимостей
• Кэширование слоя зависимостей

3. Builder Stage

FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npx prisma generate
RUN npm run build

• Генерация Prisma клиента
• Сборка Next.js приложения
• TypeScript компиляция

4. Runner Stage

FROM base AS runner
ENV NODE_ENV production
USER nextjs
COPY --from=builder /app/.next/standalone ./

• Минимальный runtime образ
• Непривилегированный пользователь
• Только необходимые файлы

🔧 Конфигурация Next.js для Production

next.config.ts оптимизации

const nextConfig: NextConfig = {
  // Standalone режим для Docker
  output: 'standalone',

  // Production проверки
  eslint: {
    ignoreDuringBuilds: false,
    dirs: ['src'],
  },
  typescript: {
    ignoreBuildErrors: false,
  },

  // Оптимизация изображений
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.twcstorage.ru',
        port: '',
        pathname: '/**',
      },
    ],
  },

  // Экспериментальные оптимизации
  experimental: {
    optimizePackageImports: ['lucide-react'],
  },
}

🎯 Healthcheck и мониторинг

Docker Healthcheck

# В Dockerfile
RUN apk add --no-cache wget

# В docker-compose.yml
healthcheck:
  test: ['CMD', 'wget', '--no-verbose', '--tries=1', '--spider', 'http://localhost:3000/api/health']
  timeout: 10s
  interval: 30s
  retries: 3
  start_period: 40s

API Endpoint для проверки состояния

Создание /app/api/health/route.ts:

import { NextResponse } from 'next/server'
import { PrismaClient } from '@prisma/client'

export async function GET() {
  try {
    const prisma = new PrismaClient()

    // Проверка подключения к базе данных
    await prisma.$queryRaw`SELECT 1`

    return NextResponse.json({
      status: 'healthy',
      timestamp: new Date().toISOString(),
      services: {
        database: 'connected',
        application: 'running',
      },
    })
  } catch (error) {
    return NextResponse.json(
      {
        status: 'unhealthy',
        timestamp: new Date().toISOString(),
        error: error.message,
      },
      { status: 500 },
    )
  }
}

📊 Производительность и оптимизация

Сборка оптимизации

1. Bundle Analysis

# Анализ размера бандла
npm run analyze

# С помощью @next/bundle-analyzer
ANALYZE=true npm run build

2. Image Optimization

• Использование Next.js Image компонента
• Поддержка WebP/AVIF форматов
• Lazy loading по умолчанию

3. Code Splitting

• Автоматическое разделение по страницам
• Dynamic imports для больших компонентов
• Lazy loading библиотек

Runtime оптимизации

// Lazy loading компонентов
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
  loading: () => <p>Загрузка...</p>,
})

// Мемоизация дорогих вычислений
const expensiveValue = useMemo(() => {
  return heavyCalculation(data)
}, [data])

// React.memo для предотвращения лишних рендеров
const OptimizedComponent = memo(({ data }) => {
  return <div>{data}</div>
})

🔐 Безопасность развертывания

1. Переменные окружения

# Генерация безопасного JWT секрета
openssl rand -hex 32

# Использование Docker secrets
echo "my-secret" | docker secret create jwt_secret -

2. Пользователи и права

# Создание непривилегированного пользователя
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
USER nextjs

3. Network security

# docker-compose.yml
networks:
  app-network:
    driver: bridge
    internal: true

🗄 База данных

Производственная настройка PostgreSQL

# Создание пользователя и базы данных
sudo -u postgres psql
CREATE USER sfera_user WITH PASSWORD 'secure_password';
CREATE DATABASE sfera_prod OWNER sfera_user;
GRANT ALL PRIVILEGES ON DATABASE sfera_prod TO sfera_user;

Миграции в Production

# Проверка статуса миграций
npx prisma migrate status

# Применение миграций
npx prisma migrate deploy

# Создание администратора (если нужно)
node scripts/create-admin.mjs

Backup стратегия

# Ежедневный backup
pg_dump -h localhost -U sfera_user -d sfera_prod > backup_$(date +%Y%m%d).sql

# Автоматический backup через cron
0 2 * * * pg_dump -h localhost -U sfera_user -d sfera_prod > /backups/sfera_$(date +\%Y\%m\%d).sql

🔄 CI/CD Pipeline

GitHub Actions пример

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Type check
        run: npm run typecheck

      - name: Lint
        run: npm run lint

      - name: Build Docker image
        run: |
          docker build -t sfera:${{ github.sha }} .
          docker tag sfera:${{ github.sha }} sfera:latest

      - name: Deploy to production
        run: |
          docker-compose -f docker-compose.prod.yml down
          docker-compose -f docker-compose.prod.yml up -d

🚨 Troubleshooting

Частые проблемы

1. Database connection errors

# Проверка подключения к БД
npx prisma db execute --preview-feature --stdin <<< "SELECT 1;"

# Перегенерация Prisma клиента
npx prisma generate

2. Permission denied

# Проверка прав на файлы
ls -la .next/standalone/server.js

# Исправление прав
chmod +x .next/standalone/server.js

3. Memory issues

# Увеличение Node.js heap size
NODE_OPTIONS="--max-old-space-size=4096" npm run build

# В Docker
ENV NODE_OPTIONS="--max-old-space-size=2048"

4. Build failures

# Очистка кэша
rm -rf .next node_modules
npm install
npm run build

# Проверка TypeScript ошибок
npm run typecheck

Логирование

// Структурированное логирование
const logger = {
  info: (message: string, meta?: object) => {
    console.log(
      JSON.stringify({
        level: 'info',
        message,
        timestamp: new Date().toISOString(),
        ...meta,
      }),
    )
  },
  error: (message: string, error?: Error, meta?: object) => {
    console.error(
      JSON.stringify({
        level: 'error',
        message,
        error: error?.stack,
        timestamp: new Date().toISOString(),
        ...meta,
      }),
    )
  },
}

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

Горизонтальное масштабирование

# docker-compose.prod.yml
version: '3.8'
services:
  app:
    image: sfera:latest
    deploy:
      replicas: 3
      restart_policy:
        condition: on-failure
    ports:
      - '3017-3019:3000'

Load Balancer конфигурация (Nginx)

upstream sfera_backend {
    server localhost:3017;
    server localhost:3018;
    server localhost:3019;
}

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://sfera_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

🎯 Заключение

Это руководство покрывает полный цикл развертывания SFERA от локальной разработки до production окружения. Ключевые принципы:

1. Безопасность: Использование секретов, непривилегированных пользователей
2. Производительность: Multi-stage сборка, оптимизация образов
3. Надежность: Healthchecks, автоматический restart, backup
4. Масштабируемость: Готовность к горизонтальному масштабированию
5. Мониторинг: Структурированные логи, метрики производительности

Следуйте этому руководству для надежного и безопасного развертывания платформы SFERA в любом окружении.