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 года*