Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
491 lines (346 loc) · 13.1 KB

SETUP_GUIDE.md

File metadata and controls

491 lines (346 loc) · 13.1 KB
Raw

Руководство по настройке проекта

Это руководство описывает настройку всех улучшений, добавленных в проект.

Содержание

  1. Кеширование
  2. HTTPS
  3. Тестирование Rate Limiting
  4. CI/CD для GitHub
  5. CI/CD для GitLab
  6. Swagger/OpenAPI документация

Кеширование

✅ Уже настроено!

Кеширование уже реализовано в services/VacancyService.php:

  • Список вакансий: кеш на 5 минут
  • Отдельная вакансия: кеш на 10 минут
  • Автоматическая инвалидация: при создании, обновлении или удалении

Производительность

До кеширования:

  • Запрос списка вакансий: ~50-100ms
  • Запрос одной вакансии: ~20-50ms

После кеширования:

  • Запрос из кеша: ~1-5ms
  • Прирост производительности: 10-100x ✨

Настройка

По умолчанию используется FileCache. Для продакшена рекомендуется Redis:

// config/web.php
'cache' => [
    'class' => 'yii\redis\Cache',
    'redis' => [
        'hostname' => 'localhost',
        'port' => 6379,
        'database' => 0,
    ]
],

HTTPS

Файлы настройки

Созданы следующие файлы:

  1. docker/nginx/nginx.conf - конфигурация Nginx с SSL
  2. docker/nginx/Dockerfile - Docker образ для Nginx
  3. docker/apache/apache-ssl.conf - конфигурация Apache с SSL
  4. setup_ssl_certificates.sh - скрипт для генерации сертификатов
  5. HTTPS_SETUP.md - подробная документация

Быстрый старт

Для разработки (самоподписанный сертификат)

# 1. Генерация сертификатов
./setup_ssl_certificates.sh dev

# 2. Обновите docker-compose.yml (добавьте nginx сервис)
# 3. Запуск
docker-compose up -d

Для продакшена (Let's Encrypt)

# 1. Установите certbot
sudo apt-get install certbot python3-certbot-nginx

# 2. Получите сертификат
./setup_ssl_certificates.sh production

# 3. Настройте автообновление
sudo crontab -e
# Добавьте: 0 0 * * * certbot renew --quiet

Проверка SSL

# Тест подключения
openssl s_client -connect localhost:443

# Проверка качества (для продакшена)
# Откройте: https://www.ssllabs.com/ssltest/

Тестирование Rate Limiting

Созданные тесты

  1. tests/api/RateLimitingCest.php - API тесты
  2. tests/unit/services/RateLimitingUnitTest.php - Unit тесты

Запуск тестов

# Все тесты rate limiting
vendor/bin/codecept run api RateLimitingCest
vendor/bin/codecept run unit services/RateLimitingUnitTest

# Конкретный тест
vendor/bin/codecept run api RateLimitingCest:testRateLimitingEnforced

# С подробным выводом
vendor/bin/codecept run api RateLimitingCest --debug

Что тестируется

  • ✅ Блокировка при превышении лимита (429 код)
  • ✅ Независимость лимитов для разных IP
  • ✅ Алгоритм расчета allowance
  • ✅ Работа кеша для rate limiting
  • ✅ Производительность механизма

Настройка лимитов для тестов

Создайте .env.test:

RATE_LIMIT_REQUESTS=10
RATE_LIMIT_WINDOW=5

Это ускорит тесты (вместо 100 запросов в час - 10 за 5 секунд).

CI/CD для GitHub

Созданные файлы

  1. .github/workflows/ci.yml - основной CI/CD pipeline
  2. .github/workflows/release.yml - релизы

Что включено

CI Pipeline (при push/PR):

  • ✅ Запуск unit, functional и API тестов
  • ✅ Проверка качества кода (PHP syntax, PHPCS)
  • ✅ Проверка безопасности (composer audit)
  • ✅ Покрытие кода (Codecov)
  • ✅ Сборка Docker образа
  • ✅ Автодеплой на продакшн (только main)

Настройка GitHub Secrets

Перейдите в Settings → Secrets and variables → Actions и добавьте:

# Docker Hub
DOCKER_USERNAME=ваш_логин
DOCKER_PASSWORD=ваш_токен

# Деплой
DEPLOY_HOST=ваш_сервер.com
DEPLOY_USER=deploy_user
DEPLOY_SSH_KEY=приватный_ssh_ключ

Генерация SSH ключа для деплоя

# На локальной машине
ssh-keygen -t rsa -b 4096 -C "github-deploy" -f ~/.ssh/github_deploy
cat ~/.ssh/github_deploy # Скопируйте приватный ключ в DEPLOY_SSH_KEY

# На сервере
cat ~/.ssh/github_deploy.pub >> ~/.ssh/authorized_keys

Использование

# Push активирует автоматически CI
git push origin main

# Создание релиза
git tag v1.0.0
git push origin v1.0.0
# Запустит release.yml workflow

CI/CD для GitLab

Созданный файл

.gitlab-ci.yml - полный CI/CD pipeline для GitLab

Что включено

Stages:

  1. build - установка зависимостей, сборка Docker
  2. test - unit, functional, API тесты
  3. code-quality - проверка синтаксиса, PHPCS, PHPStan
  4. security - проверка безопасности
  5. deploy - деплой на staging/production

Настройка GitLab CI/CD Variables

Перейдите в Settings → CI/CD → Variables и добавьте:

# Staging
STAGING_SSH_PRIVATE_KEY=приватный_ключ
STAGING_HOST=staging.example.com
STAGING_USER=deploy

# Production
PRODUCTION_SSH_PRIVATE_KEY=приватный_ключ
PRODUCTION_HOST=api.example.com
PRODUCTION_USER=deploy

# Docker Registry (если используете GitLab Registry)
CI_REGISTRY_USER=$CI_REGISTRY_USER (автоматически)
CI_REGISTRY_PASSWORD=$CI_REGISTRY_PASSWORD (автоматически)

Использование

# Push активирует pipeline
git push origin develop # Запустит тесты

# Деплой на staging (вручную)
# Откройте GitLab → CI/CD → Pipelines → Manual Jobs → deploy:staging

# Деплой на production
git tag v1.0.0
git push origin v1.0.0
# В pipeline появится кнопка deploy:production

Просмотр результатов

  • Pipeline: CI/CD → Pipelines
  • Coverage: CI/CD → Pipelines → Coverage Report
  • Artifacts: CI/CD → Jobs → Download Artifacts

Swagger/OpenAPI документация

Созданные файлы

  1. web/openapi.yaml - спецификация OpenAPI 3.0
  2. web/swagger-ui.html - интерактивная документация
  3. web/redoc.html - красивая документация для чтения
  4. API_DOCUMENTATION.md - руководство по использованию

Доступ к документации

После запуска приложения:

  1. Swagger UI: http://localhost:8080/swagger-ui.html

    • Интерактивное тестирование API
    • Отправка запросов прямо из браузера

  2. ReDoc: http://localhost:8080/redoc.html

    • Красивая документация для чтения
    • Удобная навигация

  3. OpenAPI YAML: http://localhost:8080/openapi.yaml

    • Прямой доступ к спецификации
    • Для импорта в Postman/Insomnia

Импорт в Postman

# Способ 1: через URL
1. Откройте Postman
2. File → Import → Link
3. Вставьте: http://localhost:8080/openapi.yaml

# Способ 2: через файл
1. File → Import → Upload Files
2. Выберите: web/openapi.yaml

Генерация клиентов

# TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i http://localhost:8080/openapi.yaml \
  -g typescript-fetch \
  -o ./client

# Python
pip install openapi-generator-cli
openapi-generator-cli generate \
  -i http://localhost:8080/openapi.yaml \
  -g python \
  -o ./python-client

Обновление документации

При изменении API редактируйте web/openapi.yaml:

# Добавить новый эндпоинт
paths:
  /vacancy/search:
    get:
      summary: Поиск вакансий
      # ...

Быстрая проверка всех функций

1. Проверка кеширования

# Первый запрос (без кеша)
time curl http://localhost:8080/vacancy

# Второй запрос (из кеша) - должен быть намного быстрее
time curl http://localhost:8080/vacancy

2. Проверка HTTPS

# Локально
curl https://localhost:443 -k

# На сервере
curl https://api.example.com

3. Проверка Rate Limiting

# Скрипт для быстрой проверки
for i in {1..110}; do
  curl -w "%{http_code}\n" -o /dev/null -s http://localhost:8080/vacancy
done
# Должен появиться код 429 после ~100 запросов

4. Проверка тестов

vendor/bin/codecept run

5. Проверка документации

# Откройте в браузере
open http://localhost:8080/swagger-ui.html

Производственное развертывание

Чеклист перед деплоем

  • Настроены переменные окружения (.env)
  • HTTPS сертификаты установлены
  • База данных мигрирована
  • Composer dependencies установлены (--no-dev)
  • Настроен rate limiting
  • CORS настроен на правильные домены
  • CI/CD secrets настроены
  • Backup стратегия определена
  • Мониторинг настроен
  • Логи настроены

Рекомендуемая конфигурация

# .env для продакшена
YII_ENV=prod
YII_DEBUG=false

DB_DSN=pgsql:host=db.example.com;dbname=vacancy_prod
DB_USERNAME=vacancy_user
DB_PASSWORD=strong_password

RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=3600

CORS_ORIGIN=https://yourdomain.com

Поддержка

Логи

# Приложение
tail -f runtime/logs/app.log

# Nginx
tail -f /var/log/nginx/error.log

# Docker
docker-compose logs -f

Типичные проблемы

Проблема: Тесты падают с ошибкой БД Решение: Проверьте подключение к тестовой БД

Проблема: HTTPS не работает Решение: Проверьте сертификаты в docker/nginx/ssl/

Проблема: CI/CD не деплоится Решение: Проверьте SSH ключи в Secrets

Полезные команды

# Очистка кеша
php yii cache/flush-all

# Запуск миграций
php yii migrate

# Запуск всех тестов
vendor/bin/codecept run

# Проверка безопасности
composer audit

# Просмотр логов
tail -f runtime/logs/app.log

# Перезапуск Docker
docker-compose restart

# Проверка стиля кода
vendor/bin/phpcs

Что дальше?

Рекомендуемые улучшения:

  1. Мониторинг: Добавить Prometheus + Grafana
  2. Логирование: Интеграция с ELK stack
  3. Аутентификация: JWT или OAuth2
  4. Websockets: Для real-time обновлений
  5. GraphQL: Альтернатива REST
  6. Rate Limiting: Redis вместо FileCache
  7. CDN: Для статических файлов

Итоги

✅ Кеширование - увеличение производительности в 10-100 раз ✅ HTTPS - безопасное соединение ✅ Rate Limiting Tests - проверка защиты от злоупотреблений ✅ GitHub Actions CI/CD - автоматизация тестирования и деплоя ✅ GitLab CI/CD - альтернативная CI/CD платформа ✅ Swagger/OpenAPI - полная документация API

Проект готов к продакшену! 🚀