Централизованная система reverse proxy на базе Nginx для управления доступом к Docker-контейнерам через HTTPS с автоматическим управлением SSL-сертификатами Let's Encrypt
Balancer упрощает подключение любых сервисов (API, фронтенды, базы данных) к интернету через единую точку входа с автоматическим SSL. Система разработана для максимальной автоматизации операций и минимального времени развертывания новых сервисов.
- Автоматическое управление SSL - Let's Encrypt сертификаты с автообновлением каждые 12 часов
- 4 типа подключения - Backend API, Static Frontend, SSR Frontend, Database TCP
- Direct Mount оптимизация - прямое монтирование статики: -50% RAM, -60% latency
- Bash-автоматизация - добавление сервиса за < 5 минут через интерактивные скрипты
- Версионирование деплоев - история версий с мгновенным откатом
- Health monitoring - проверка каждые 5 минут с Telegram алертами
- IP-фильтрация - защита внутренних сервисов (базы данных)
- Graceful reload - изменение конфигураций без downtime
- Целевой uptime > 99.5%
| Тип | Использование | Путь данных | Примеры |
|---|---|---|---|
| Backend API | REST API сервисы | Client → Nginx → Backend Container | FastAPI, Django, Node.js |
| Frontend Static | Статические сборки | Client → Nginx → Static Files (Volume) | React, Vue, Angular |
| Frontend Container | SSR приложения | Client → Nginx → Frontend Container | Next.js, Nuxt.js |
| Database TCP | Базы данных | Client → Nginx TCP → Database Container | PostgreSQL, MySQL |
Frontend Static (рекомендуется для SPA)
- ✅ Приложение генерирует статический билд (
npm run build) - ✅ Не требуется Server-Side Rendering
- ✅ Нужна максимальная производительность
Frontend Container (для SSR)
- ✅ Приложение использует SSR (Next.js, Nuxt.js)
- ✅ Требуется кастомная конфигурация Nginx
# 1. Клонировать репозиторий
git clone <repository-url>
cd balancer
# 2. Инициализировать систему
sudo bash scripts/init-balancer.sh
# 3. Добавить первый сервис (интерактивно)
sudo bash scripts/add-service.sh
# 4. Проверить статус
docker compose ps/opt/balancer/
├── docker-compose.yml # Основной compose файл
├── nginx/ # Конфигурации Nginx
│ ├── conf.d/
│ │ ├── proxy/ # Backend API конфиги
│ │ ├── static/ # Static Frontend конфиги (Direct Mount)
│ │ ├── external/ # Proxy Frontend конфиги (SSR)
│ │ └── streams.conf # TCP Database конфиги
│ └── snippets/ # Переиспользуемые блоки (ssl, security, proxy)
├── static/ # Статический контент для direct mount
├── scripts/ # Bash-скрипты управления
│ ├── init-balancer.sh # Инициализация системы
│ ├── add-service.sh # Добавление сервиса
│ ├── remove-service.sh # Удаление сервиса
│ ├── deploy-frontend.sh # Деплой статического фронтенда
│ ├── rollback-frontend.sh # Откат версии фронтенда
│ ├── health-check.sh # Мониторинг здоровья
│ └── telegram-alert.sh # Telegram уведомления
├── templates/ # Шаблоны конфигураций
├── deployments/ # История деплоев (версионирование)
├── logs/ # Логи Nginx
└── docs/ # Документация проекта
# На сервере: добавить сервис
sudo bash scripts/add-service.sh
# Выбрать: 2 (Frontend Static)
# Имя: myapp, Поддомен: app, Домен: example.ru
# Локально: собрать приложение
cd my-react-app
npm run build
# Деплой на сервер
rsync -av --delete dist/ user@server:/opt/balancer/static/myapp/
# Откат при необходимости
bash /opt/balancer/scripts/rollback-frontend.sh myapp previous# Запустить FastAPI контейнер в сети proxy_network
docker network connect proxy_network fastapi-app
# Добавить сервис
sudo bash scripts/add-service.sh
# Выбрать: 1 (Backend API) → 1 (FastAPI)
# Контейнер: fastapi-app, Порт: 8000# Добавить TCP Stream
sudo bash scripts/add-service.sh
# Выбрать: 4 (Database TCP) → 1 (PostgreSQL)
# Настроить IP-фильтрацию
sudo ufw allow from 192.168.1.0/24 to any port 5432 proto tcp# Статус сервисов
docker compose ps
# Просмотр логов
docker compose logs -f nginx
# Graceful reload Nginx
docker exec nginx-proxy nginx -t && docker exec nginx-proxy nginx -s reload
# Health check
bash scripts/health-check.sh
# Проверка SSL сертификатов
docker compose run --rm certbot certificatesПолная документация проекта находится в директории docs/prd/:
- INDEX.md - главный навигационный индекс со ссылками на все разделы
- README.md - руководство по работе с документацией
- CHEATSHEET.md - шпаргалка по типам подключения
- 001_index.md - титульная страница и содержание
- 002_executive-summary.md - обзор проекта и цели
- 003_architecture.md - архитектура системы
- 004_technical-requirements.md - технические требования
- 005_project-structure.md - структура проекта
- 008_deployment.md - инструкции по развертыванию
- 009_operations.md - руководство по эксплуатации
sudo bash scripts/add-service.shСкрипт интерактивно проведет через процесс добавления. Весь процесс занимает < 5 минут.
docker compose run --rm certbot renew
docker exec nginx-proxy nginx -s reloadАвтоматическое обновление происходит каждые 12 часов.
bash /opt/balancer/scripts/rollback-frontend.sh myapp previousДоступны откаты на любую сохраненную версию из /opt/balancer/deployments/{app-name}/.
Отредактируйте переменные в scripts/telegram-alert.sh:
TELEGRAM_BOT_TOKEN="your_bot_token"
TELEGRAM_CHAT_ID="your_chat_id"# Проверить, запущен ли контейнер бэкенда
docker ps | grep backend-name
# Проверить, в правильной ли сети
docker network inspect proxy_network
# Проверить конфигурацию Nginx
docker exec nginx-proxy nginx -tsudo bash scripts/remove-service.shСкрипт удалит конфигурацию Nginx и SSL сертификаты.
- 80 (HTTP) - для редиректа на HTTPS
- 443 (HTTPS) - основной трафик
- 5432, 5984 (опционально) - для баз данных с IP-фильтрацией
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp- Ubuntu 22.04+ / Debian 10+
- 2 CPU cores
- 2 GB RAM
- 20 GB disk
- Docker 20.10+
- Docker Compose 2.0+
- Ubuntu 24.04 LTS
- 4 CPU cores
- 4 GB RAM
- 50 GB SSD
- Docker 24.0+
- Docker Compose 2.20+
Система использует две изолированные сети:
- proxy_network (172.20.0.0/16) - для nginx-proxy, certbot, healthcheck и публичных сервисов
- internal_network (172.22.0.0/16) - для изоляции баз данных (internal only)
Данный проект лицензирован под Apache License 2.0.
Copyright 2025
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Версия: 2.1 Последнее обновление: 2025-11-06