# Руководство по развертыванию 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. Клонирование репозитория ```bash git clone cd sfera ``` ### 2. Установка зависимостей ```bash # Установка Node.js зависимостей npm install # Генерация Prisma клиента npx prisma generate ``` ### 3. Настройка окружения Создайте файл `.env.local`: ```env # База данных 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. Настройка базы данных ```bash # Применение миграций npx prisma migrate dev # Заполнение начальными данными (опционально) npx prisma db seed ``` ### 5. Запуск приложения ```bash # Режим разработки npm run dev # Приложение будет доступно на http://localhost:3000 ``` ## 🐳 Docker развертывание ### Структура Docker файлов ``` sfera/ ├── Dockerfile # Основной образ приложения ├── docker-compose.yml # Локальная оркестрация ├── docker-compose.prod.yml # Production конфигурация ├── .env # Переменные окружения └── stack.env # Production переменные ``` ### Локальный Docker запуск ```bash # Сборка и запуск всех сервисов docker-compose up --build # Запуск в фоновом режиме docker-compose up -d # Просмотр логов docker-compose logs -f app # Остановка сервисов docker-compose down ``` ### Production Docker развертывание #### 1. Подготовка окружения ```bash # Создание production переменных cp .env stack.env # Редактирование production конфигурации nano stack.env ``` #### 2. Production переменные окружения ```env # 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 сборка ```bash # Сборка 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 ```dockerfile FROM node:18-alpine AS base ``` - Базовый образ с Node.js 18 Alpine - Минимальный размер для оптимизации #### 2. Dependencies Stage ```dockerfile FROM base AS deps WORKDIR /app COPY package.json package-lock.json* ./ RUN npm ci ``` - Установка только production зависимостей - Кэширование слоя зависимостей #### 3. Builder Stage ```dockerfile 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 ```dockerfile FROM base AS runner ENV NODE_ENV production USER nextjs COPY --from=builder /app/.next/standalone ./ ``` - Минимальный runtime образ - Непривилегированный пользователь - Только необходимые файлы ## 🔧 Конфигурация Next.js для Production ### next.config.ts оптимизации ```typescript 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 # В Dockerfile RUN apk add --no-cache wget ``` ```yaml # В 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`: ```typescript 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** ```bash # Анализ размера бандла 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 оптимизации ```typescript // Lazy loading компонентов const HeavyComponent = dynamic(() => import('./HeavyComponent'), { loading: () =>

Загрузка...

, }) // Мемоизация дорогих вычислений const expensiveValue = useMemo(() => { return heavyCalculation(data) }, [data]) // React.memo для предотвращения лишних рендеров const OptimizedComponent = memo(({ data }) => { return
{data}
}) ``` ## 🔐 Безопасность развертывания ### 1. Переменные окружения ```bash # Генерация безопасного JWT секрета openssl rand -hex 32 # Использование Docker secrets echo "my-secret" | docker secret create jwt_secret - ``` ### 2. Пользователи и права ```dockerfile # Создание непривилегированного пользователя RUN addgroup --system --gid 1001 nodejs RUN adduser --system --uid 1001 nextjs USER nextjs ``` ### 3. Network security ```yaml # docker-compose.yml networks: app-network: driver: bridge internal: true ``` ## 🗄 База данных ### Производственная настройка PostgreSQL ```bash # Создание пользователя и базы данных 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 ```bash # Проверка статуса миграций npx prisma migrate status # Применение миграций npx prisma migrate deploy # Создание администратора (если нужно) node scripts/create-admin.mjs ``` ### Backup стратегия ```bash # Ежедневный 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 пример ```yaml 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 ```bash # Проверка подключения к БД npx prisma db execute --preview-feature --stdin <<< "SELECT 1;" # Перегенерация Prisma клиента npx prisma generate ``` #### 2. Permission denied ```bash # Проверка прав на файлы ls -la .next/standalone/server.js # Исправление прав chmod +x .next/standalone/server.js ``` #### 3. Memory issues ```bash # Увеличение 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 ```bash # Очистка кэша rm -rf .next node_modules npm install npm run build # Проверка TypeScript ошибок npm run typecheck ``` ### Логирование ```typescript // Структурированное логирование 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, }), ) }, } ``` ## 📈 Масштабирование ### Горизонтальное масштабирование ```yaml # 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) ```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 в любом окружении.