new file: main_dc/nginx/documentation/docs.md

add nignx documetation
2025-12-03 06:51:05 +05:00
parent 0a8e51a349
commit ff81cf165b
1 changed files with 249 additions and 0 deletions
@@ -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 года*