valitovgaziz
5d22544df1
Updated the domains table to reflect that yalarba.ru is now Nuxt 4 SSR (not static Vue SPA), and the old static path /usr/share/nginx/yalarba/html no longer exists.
249 lines
12 KiB
Markdown
249 lines
12 KiB
Markdown
# Документация: 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_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` | Nuxt 4 SSR | `yalarba:3000` + `api_yal:8787` | Прокси |
|
||
| `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 управление
|
||
|
||
### Автоматическое переключение
|
||
|
||
Система проверяет наличие сертификатов для всех доменов:
|
||
```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 убран, используется 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
|
||
# удалено: serv_spa больше не используется, yalarba работает через Nuxt SSR (yalarba-nuxt)
|
||
./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 года* |