# Документация: 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 года*