tp/main_dc/nginx/documentation/docs.md

Документация: Nginx Reverse Proxy & SSL Manager

Дата создания: 03 декабря 2025 года
Версия: 1.0

Обзор

Данный контейнер Nginx выполняет функции:

1. Reverse Proxy для нескольких веб-приложений и API-сервисов
2. Менеджера SSL/TLS сертификатов с автоматическим переключением между HTTP и HTTPS режимами
3. Балансировщика нагрузки и единой точки входа для всех доменов

Содержание

• Архитектура
• Конфигурационные файлы
• Домены и сервисы
• SSL/TLS управление
• Переменные окружения
• Здоровье сервисов
• Волумы
• Сети
• Скрипты и автоматизация
• Развертывание и обновление

Архитектура

┌─────────────────────────────────────────────────────────┐
│                    Nginx Container                       │
├─────────────────────────────────────────────────────────┤
│  • HTTP/HTTPS терминация                                 │
│  • Автопереключение SSL                                  │
│  • Маршрутизация по доменам                              │
│  • Проксирование к backend-сервисам                      │
└─────────────────────────────────┬───────────────────────┘
                                  │
           ┌──────────────────────┴──────────────────────┐
           │              Docker Services                 │
           ├─────────────────────────────────────────────┤
           │  • certbot     - SSL сертификаты            │
           │  • analytics   - Статистика (Node.js)       │
           │  • api_tp      - API yalarba.ru (Go)        │
            │  • api_yal      - 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_yal:8787	Прокси
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 управление

Автоматическое переключение

Система проверяет наличие сертификатов для всех доменов:

/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 убран, используется api_yal:8787

Сервисные

# 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_yal	http://localhost:8787/health	8787	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_yal, 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

#!/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. Проверить режим работы:

   docker exec nginx ls -la /etc/nginx/conf.d/default.conf
   

2. Проверить наличие сертификатов:

   docker exec certbot certbot certificates
   

3. Проверить логи:

   docker logs nginx
   docker logs certbot
   

---

Примечания для будущих расширений

1. Новые домены должны добавляться во ВСЕ конфигурационные файлы
2. Новые сертификаты должны проверяться в switch-config.sh
3. Health checks для новых сервисов должны быть настроены перед запуском nginx
4. Сети должны быть правильно сконфигурированы для изоляции сервисов

---

Документация будет обновляться при добавлении новых сервисов и доменов.
Последнее обновление: 03 декабря 2025 года