From ff81cf165b635dc42682f8dc081db250a8ca80ce Mon Sep 17 00:00:00 2001 From: valitovgaziz Date: Wed, 3 Dec 2025 06:51:05 +0500 Subject: [PATCH] new file: main_dc/nginx/documentation/docs.md add nignx documetation --- main_dc/nginx/documentation/docs.md | 249 ++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 main_dc/nginx/documentation/docs.md diff --git a/main_dc/nginx/documentation/docs.md b/main_dc/nginx/documentation/docs.md new file mode 100644 index 0000000..86bee3c --- /dev/null +++ b/main_dc/nginx/documentation/docs.md @@ -0,0 +1,249 @@ +# Документация: Nginx Reverse Proxy & SSL Manager + +*Дата создания: 03 декабря 2025 года* +*Версия: 1.0* + +## Обзор + +Данный контейнер Nginx выполняет функции: +1. **Reverse Proxy** для нескольких веб-приложений и API-сервисов +2. **Менеджера SSL/TLS сертификатов** с автоматическим переключением между HTTP и HTTPS режимами +3. **Балансировщика нагрузки** и единой точки входа для всех доменов + +## Содержание + +- [Архитектура](#архитектура) +- [Конфигурационные файлы](#конфигурационные-файлы) +- [Домены и сервисы](#домены-и-сервисы) +- [SSL/TLS управление](#ssltls-управление) +- [Переменные окружения](#переменные-окружения) +- [Здоровье сервисов](#здоровье-сервисов) +- [Волумы](#волумы) +- [Сети](#сети) +- [Скрипты и автоматизация](#скрипты-и-автоматизация) +- [Развертывание и обновление](#развертывание-и-обновление) + +## Архитектура + +``` +┌─────────────────────────────────────────────────────────┐ +│ Nginx Container │ +├─────────────────────────────────────────────────────────┤ +│ • HTTP/HTTPS терминация │ +│ • Автопереключение SSL │ +│ • Маршрутизация по доменам │ +│ • Проксирование к backend-сервисам │ +└─────────────────────────────────┬───────────────────────┘ + │ + ┌──────────────────────┴──────────────────────┐ + │ Docker Services │ + ├─────────────────────────────────────────────┤ + │ • certbot - SSL сертификаты │ + │ • analytics - Статистика (Node.js) │ + │ • api_tp - API yalarba.ru (Go) │ + │ • api_es - API easysite102.ru (Go) │ + │ • api_bb - API Бегущий Башкир (Go) │ + │ • easysite - SPA (Nuxt.js) │ + │ • db - PostgreSQL (yalarba/easy) │ + │ • db_bb - PostgreSQL (Бегущий Баш.) │ + └─────────────────────────────────────────────┘ +``` + +## Конфигурационные файлы + +### Основные конфиги Nginx + +1. **nginx-http.conf** - HTTP-режим (используется при отсутствии SSL сертификатов) + - Порт 80: статический контент из `/usr/share/nginx/stub/html` + - Порт 443: редирект HTTPS → HTTP с dummy сертификатами + +2. **nginx-ssl.conf** - HTTPS-режим (активируется при наличии всех сертификатов) + - Порт 80: редирект HTTP → HTTPS + ACME challenges + - Порт 443: SSL терминация с Let's Encrypt сертификатами + +### Скрипты + +- **switch-config.sh** - Автоматическое переключение между HTTP/HTTPS конфигурациями +- **Dockerfile** - Сборка образа с генерацией dummy сертификатов + +## Домены и сервисы + +### Основные домены + +| Домен | Тип | Backend сервис | Путь на диске | +|-------|-----|----------------|---------------| +| `yalarba.ru` | SPA (Vue) | `api_tp:8080` | `/usr/share/nginx/yalarba/html` | +| `valitovgaziz.ru` | Статический сайт | - | `/usr/share/nginx/valitovgaziz/html` | +| `easysite102.ru` | SPA (Nuxt.js) | `easysite:3000` + `api_es:8088` | Прокси | +| `begushiybashkir.ru` | SPA (Vue) | `api_bb:8080` | `/usr/share/nginx/begushiybashkir/html` | +| `xn--80abahjtcfl5d0a8di.xn--p1ai` | Альтернативный домен для Бегущий Башкир | `api_bb:8080` | `/usr/share/nginx/begushiybashkir/html` | + +### Специальные поддомены + +| Поддомен | Назначение | +|----------|------------| +| `auth.yalarba.ru` | Аутентификация (HTTP режим) | + +## SSL/TLS управление + +### Автоматическое переключение + +Система проверяет наличие сертификатов для всех доменов: +```bash +/etc/letsencrypt/live/yalarba.ru/fullchain.pem +/etc/letsencrypt/live/easysite102.ru/fullchain.pem +/etc/letsencrypt/live/valitovgaziz.ru/fullchain.pem +/etc/letsencrypt/live/begushiybashkir.ru/fullchain.pem +/etc/letsencrypt/live/xn--80abahjtcfl5d0a8di.xn--p1ai/fullchain.pem +``` + +**Логика переключения:** +1. Если ВСЕ сертификаты присутствуют → активируется `nginx-ssl.conf` +2. Если хотя бы один сертификат отсутствует → активируется `nginx-http.conf` + +### Сертификаты + +1. **Let's Encrypt** (производственные): + - Хранятся в волуме `certbot_data` + - Обновляются автоматически через certbot контейнер + +2. **Dummy сертификаты** (резервные): + - Генерируются при сборке образа + - Используются для запуска Nginx при отсутствии Let's Encrypt сертификатов + - Путь: `/etc/nginx/ssl/dummy.{crt,key}` + +## Переменные окружения + +### Основные (.env файл) +``` +EMAIL=admin@example.com # Для Let's Encrypt +ALL_DOMAINS=yalarba.ru,valitovgaziz.ru... # Все домены для SSL +API_ES_APP_PORT=8088 # Порт API easysite +``` + +### Сервисные +``` +# API сервисы +DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME +APP_PORT, NODE_ENV, PORT, LOG_LEVEL + +# Certbot +STAGING=0 # 1 для тестового режима Let's Encrypt +``` + +## Здоровье сервисов + +### Health checks + +| Сервис | Проверка | Порт | Интервал | +|--------|----------|------|----------| +| nginx | `http://localhost/health` | 80 | 30s | +| certbot | Проверка файла сертификата | - | 30s | +| analytics | `http://localhost:3000/health` | 3000 | 30s | +| api_tp | `http://localhost:8080/health` | 8080 | 30s | +| api_es | `http://localhost:8088/health` | 8088 | 30s | +| api_bb | `http://localhost:8080/api/health` | 8080 | 30s | +| easysite | `http://localhost:3000/api/health` | 3000 | 30s | +| db, db_bb | `pg_isready -U postgres` | 5432 | 30s | + +### Зависимости запуска +Nginx запускается только после подтверждения здоровья: +- `easysite`, `api_es`, `certbot`, `api_tp`, `api_bb`, `analytics` + +## Волумы + +| Название | Назначение | Используется сервисами | +|----------|------------|------------------------| +| `certbot_data` | SSL сертификаты Let's Encrypt | certbot, nginx | +| `certbot_www` | ACME challenge файлы | certbot, nginx | +| `db_tp_data` | База данных yalarba.ru/easysite | db | +| `db_bb_data` | База данных Бегущий Башкир | db_bb | +| `api_bb_uploads` | Загружаемые файлы | api_bb | +| `analytics_logs` | Логи аналитики | analytics | +| `analytics_data` | Данные аналитики | analytics | + +### Монтирование статических файлов +``` +./stubSite → /usr/share/nginx/stub/html +./yalarba/serv_spa/spa/vue/dist → /usr/share/nginx/yalarba/html +./valitovgaziz/html → /usr/share/nginx/valitovgaziz/html +./BB/bbvue/dist → /usr/share/nginx/begushiybashkir/html +``` + +## Сети + +| Сеть | Назначение | Драйвер | +|------|------------|---------| +| `web-network` | Доступ из интернета | bridge | +| `internal` | Внутренняя коммуникация | bridge | +| `app-network` | Сервисы yalarba/easysite | bridge | +| `bb-network` | Сервисы Бегущий Башкир | bridge | + +## Скрипты и автоматизация + +### switch-config.sh +```bash +#!/bin/bash +# Проверяет наличие всех SSL сертификатов +# Переключает конфигурацию nginx +# Выполняет nginx -t для проверки синтаксиса +``` + +### ACME Challenge +Путь для проверок доменов: `/.well-known/acme-challenge/` +Корневая директория: `/var/www/certbot` + +## Развертывание и обновление + +### Первый запуск +1. Настроить `.env` файл с доменами и email +2. Запустить: `docker-compose up -d` +3. Система запустится в HTTP режиме (т.к. нет SSL сертификатов) +4. Certbot автоматически получит сертификаты +5. Nginx переключится на HTTPS режим после получения всех сертификатов + +### Добавление нового сайта +1. Добавить домен в: + - Переменную `ALL_DOMAINS` в `.env` + - `nginx-http.conf` (оба server блока) + - `nginx-ssl.conf` (server блоки портов 80 и 443) + - `switch-config.sh` (проверка сертификата) + +2. Добавить volume для статических файлов (если нужно) + +3. Настроить location блоки для маршрутизации + +### Обновление сертификатов +- Certbot автоматически обновляет сертификаты +- При обновлении Nginx автоматически перезагружает конфигурацию + +### Мониторинг +1. Проверить режим работы: + ```bash + docker exec nginx ls -la /etc/nginx/conf.d/default.conf + ``` + +2. Проверить наличие сертификатов: + ```bash + docker exec certbot certbot certificates + ``` + +3. Проверить логи: + ```bash + docker logs nginx + docker logs certbot + ``` + +--- + +## Примечания для будущих расширений + +1. **Новые домены** должны добавляться во ВСЕ конфигурационные файлы +2. **Новые сертификаты** должны проверяться в `switch-config.sh` +3. **Health checks** для новых сервисов должны быть настроены перед запуском nginx +4. **Сети** должны быть правильно сконфигурированы для изоляции сервисов + +--- + +*Документация будет обновляться при добавлении новых сервисов и доменов.* +*Последнее обновление: 03 декабря 2025 года* \ No newline at end of file