SERVER-API/README.md

Nginx + PHP-FPM (API v1/v2) + PostgreSQL + Memcached

Проект разворачивает два API (v1 и v2) на отдельных контейнерах PHP-FPM, фронтирует их через Nginx и подключает PostgreSQL и Memcached. Конфигурация рассчитана на локальную разработку и может быть адаптирована для staging/production.

Возможности

• Два независимых API: /api/v1/ и /api/v2/.
• Nginx проксирует запросы к соответствующим пулам PHP-FPM.
• Проверки соединений с PostgreSQL и Memcached в каждом API.
• Разделённые логи для Nginx и каждого PHP-FPM.
• Переменные окружения вынесены в .env файлы (безопаснее, чем хранить пароли в compose).

Требования

• Установленный Docker Desktop (Windows/macOS) или Docker Engine (Linux).
• Docker Compose v2 (входит в Docker Desktop).

Быстрый запуск (локально)

1. Открой папку проекта: c:\docker\nginxphp\server\project.
2. Убедись, что созданы и заполнены файлы:
   • .env.v1 — переменные для API v1
   • .env.v2 — переменные для API v2
   • .env.db — переменные для PostgreSQL Пример значений уже положен в репозиторий (локальные пароли можно заменить).
3. Запусти:

   docker compose up -d --build
   

4. Проверь эндпоинты:
   • http://localhost/api/v1/
   • http://localhost/api/v2/ Оба вернут JSON со статусами PostgreSQL и Memcached, версией API и PHP.

Структура

• docker-compose.yml — оркестрация контейнеров.
• nginx/nginx.conf — маршрутизация /api/v1 и /api/v2 к нужным upstream (PHP-FPM v1/v2).
• api-v1/ — Dockerfile, конфиги PHP-FPM (config), код (index.php).
• api-v2/ — Dockerfile, конфиги PHP-FPM (config), код (index.php).
• database/init/01_init.sql — создаёт БД api_v1 и api_v2, выдаёт права api_user.
• logs/nginx, logs/php-v1, logs/php-v2 — каталоги для логов.
• .env.v1, .env.v2, .env.db — переменные окружения для сервисов.
• .gitignore — исключает .env* и logs/ из VCS.

Развёртывание: подробная инструкция

Локальная среда

• Заполни .env.v1, .env.v2, .env.db корректными значениями (БД, пользователи, пароли).
• Запусти: docker compose up -d --build.
• Просмотри логи при необходимости:
  • docker compose logs -f nginx
  • docker compose logs -f php-fpm-v1
  • docker compose logs -f php-fpm-v2
  • docker compose logs -f postgres
• Остановить и очистить:

  docker compose down -v
  

  Команда удалит контейнеры и именованный том postgres_data.

Staging/Production рекомендации

• Секреты: не хранить пароли в .env на диске. Используй Docker Swarm/Kubernetes secrets, HashiCorp Vault или инъекцию env через CI/CD.
• SSL/HTTP2: поставь обратный прокси с TLS (например, Nginx/Traefik) и включи HSTS/CSP/безопасные заголовки.
• Бэкапы: настроить регулярные бэкапы postgres_data.
• Доступы БД: разнести пользователей по API (отдельные DB_USER/пароли и права на свои базы).
• Обновления: регулярно обновлять базовые образы и пакеты в Dockerfile.
• Мониторинг: добавить healthchecks, метрики и алёрты.

Что было исправлено и почему

• Nginx: убраны вложенные location и добавлены независимые блоки для /api/v1 и /api/v2.
• SCRIPT_FILENAME: передаётся абсолютный путь /var/www/html/index.php (код не монтируется в Nginx).
• PHP-FPM: clear_env = no, чтобы PHP видел переменные из .env/compose.
• Dockerfile: удалены лишние пакеты; оставлены PHP 8.2 и нужные расширения. Исправлено отсутствие php8.2-json (встроено в ядро).
• Права: вместо 777 используются более строгие 755/775 и корректный владелец www.
• БД: добавлен скрипт инициализации, создающий api_v1 и api_v2.

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

• Секреты вынесены в .env файлы и исключены из VCS (.gitignore).
• Для продакшна — использовать secrets-менеджер вместо .env.
• Выключен display_errors в FPM; включать только на dev.
• Разграничение прав БД и ротация паролей.

Диагностика проблем

• Ошибка FPM "failed to open error_log": убедись, что логи монтируются в /var/log/php-fpm (уже настроено в compose).
• Ошибка пакета php8.2-json: не устанавливается отдельно (часть ядра). Удалено из Dockerfile.
• Полный сброс окружения:

  docker compose down -v
  docker compose up -d --build
  

📚 Документация

Подробная документация находится в каталоге docs/:

• Навигация и быстрый старт: docs/README.md
• Обзор и требования: docs/overview.md
• Запуск и деплой: docs/deployment.md
• Мониторинг (метрики и алёрты): docs/monitoring.md
• Примеры .env: docs/env-examples.md
• Публикация в Gitea: docs/gitea.md
• Диагностика: docs/troubleshooting.md

📚 Раздел: Secrets Management

Секреты вынесены из docker-compose.yml в отдельные env-файлы, игнорируемые системой контроля версий.

• Файлы: .env.v1, .env.v2, .env.db (локальные секреты).
• Пример содержимого и рекомендации см. в docs/env-examples.md.

Почему так безопаснее

• Нет паролей в docker-compose.yml — меньше риск утечки в VCS.
• Разделение по сервисам — проще ротация и изоляция.
• В продакшене рекомендуем использовать Swarm/K8s Secrets, Vault, SSM Parameter Store.