1F-Spa (Frontend)¶
ℹ️ Сервис 1F-SPA является фронтендом приложения "Первая Форма"
Основная функция сервиса — отдача статических ресурсов SPA-приложения (архитектура Single Page Application на базе Angular), включая HTML, JS, CSS и другие статические файлы. Для обеспечения мультиплатформенной работы сервис упакован в Docker-образ и может быть запущен в следующих средах:
-
Docker (локально или на сервере)
-
Docker Compose (в составе комплекса сервисов)
-
Kubernetes (в кластере)
В качестве веб-сервера используется Nginx, который обеспечивает высокопроизводительную раздачу статических файлов и, при необходимости, проксирование запросов к backend-сервисам. Сервис поддерживает два режима работы:
-
Standalone — Nginx обслуживает только статические файлы SPA без проксирования к backend.
-
Reverse Proxy — Nginx отдаёт статику и одновременно проксирует запросы на backend-сервисы согласно заданным маршрутам и переменным окружения.
Запуск в Docker Compose¶
Запуск в K8s¶
Конфигурация¶
Конфигурация работы сервиса 1F-SPA выполняется путем изменения переменных окружения.
При старте контейнера скрипт entrypoints.sh:
1. Определяет значения переменных по умолчанию (если они не заданы).
2. На основе текущих значений переменных окружения генерирует файлы конфигурации Nginx из шаблонов.
3. Запускает Nginx с готовыми конфигурационными файлами.
Таким образом, изменение параметров работы сервиса выполняется без ручного редактирования конфигураций — достаточно задать нужные переменные окружения при запуске контейнера.
Описание переменных окружения¶
Настройки проксирования и интеграции с бекендом
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_STANDALONE | Флаг режима "standalone" (автономный режим фронтенда). Определяет, как Nginx будет обрабатывать запросы. Если значение false, предполагается интеграция SPA с бекендом: все запросы к корню сайта (/) будут проксированы на адрес, заданный переменной SPA_PROXY_CORE_URL (см. ниже). Также в этом режиме в конфигурации Nginx предусмотрена поддержка нескольких специальных маршрутов (например, /notificationHub, /pushHub, /signalr, /denormalizationHub), которые проксируются на тот же бекенд с поддержкой Upgrade (для WebSocket или Server-Sent Events) и отключенной буферизацией. Если же SPA_STANDALONE=true, Nginx не будет проксировать корневые запросы на бекенд - режим предполагает, что фронтенд работает полностью автономно. В stand-alone режиме блок location / из конфигурации будет отсутствовать, и, по сути, Nginx будет отдавать только статические файлы SPA | true / false | true |
| SPA_PROXY_CORE_URL | URL основного бекенд-сервиса (1F-CORE), с которым интегрируется SPA. Это адрес, на который будут проксироваться все запросы к / (корневому пути), если включён режим интеграции (SPA_STANDALONE=false). Здесь указывается внутренний адрес основного веб-приложения или API (например, http://core-app:5000 или полный URL до бекенда). Nginx будет перенаправлять на этот адрес все запросы, URI которых не начинаются с зарезервированных локаций (/spa, /office и т.д.), тем самым объединяя фронтенд и бекенд под одним доменом. Убедитесь, что указанный URL доступен из контейнера Nginx (например, если бекенд запущен в другом контейнере, можно использовать имя сервиса в сети Docker). Если переменная не задана, но SPA_STANDALONE=false, запросы к / не смогут быть проксированы и вернут ошибку - поэтому при интеграции необходимо обязательно указать SPA_PROXY_CORE_URL | url | http://1f-core:8000 |
| SPA_PROXY_ONLYOFFICE_URL | URL сервиса OnlyOffice Document Server, если требуется интеграция редактора документов OnlyOffice. Значение переменной обязательно должно содежать символ правого слеша (/) в конце ссылки. Например: http://dockumentserver/ При указании этого адреса, Nginx создаст локальный префикс /office и будет проксировать все запросы, начинающиеся с /office, на указанный OnlyOffice-сервер | url | nil |
| SPA_PROXY_TC_URL | URL-адрес для обратной совместимости и редиректа в прежний режим администрирования на базе aspx-страниц | url | nil |
Общие параметры Nginx — системный пользователь и число рабочих процессов.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_NGINX_USER | Системный пользователь, от имени которого будут запущены рабочие процессы (worker processes) Nginx внутри контейнера | string | nginx |
| SPA_WORKER_PROCESSES | Количество worker-процессов Nginx. Это напрямую задаётся директивой worker_processes в nginx.conf. Workers — это параллельные процессы Nginx, которые обрабатывают поступающие соединения. Обычно рекомендуемое значение — равное числу ядер CPU на сервере (или auto, чтобы Nginx сам определил) | string | auto |
| SPA_WORKER_CONNECTIONS | Максимальное количество соединений, которое каждый worker Nginx может одновременно обрабатывать. Соответствует директиве worker_connections в блоке events | int | 1024 |
Настройки HTTP/HTTPS и TLS
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_SITE_DOMAIN_NAME | Определяет доменное имя сайта, которое будет использовано в конфигурации Nginx в директиве server_name. Установите здесь основной домен, по которому будет доступен сервис. Если переменная не задана, используется значение _ (wildcard), что означает, что сервер будет обрабатывать запросы на любой домен | string | "_" |
| SPA_ENABLE_HTTPS | Флаг включения HTTPS. Если установлен в true, Nginx будет слушать порт 443 и ожидать SSL/TLS соединения, используя сертификаты, указанные в переменных SPA_SSL_CERT_PATH и SPA_SSL_KEY_PATH | true / false | false |
| SPA_ENABLE_HTTP_REDIRECT | Флаг для перенаправления HTTP на HTTPS. Если выставлено в true (или 1), Nginx не будет обслуживать незащищённый трафик на порту 80, а автоматически отправит HTTP 301 Redirect на аналогичный URL с схемой https:// | true / false | false |
| SPA_SSL_CERT_PATH | Путь к файлу SSL-сертификата | string | /opt/ssl/selfsigned/cert.crt |
| SPA_SSL_KEY_PATH | Путь к файлу приватного ключа SSL-сертификата | string | /opt/ssl/selfsigned/cert.key |
| SPA_ENABLE_HSTS | Флаг включения HSTS (HTTP Strict Transport Security) | true / false | true |
| SPA_HSTS_MAX_AGE | Срок действия политики HSTS в секундах | int | 31536000 |
ℹ️ HSTS включён по умолчанию, но не применяется при отключённом HTTPS. Активируется автоматически при установке
SPA_ENABLE_HTTPS=true.
Настройки буферизации ответов (Proxy) — управляют тем, как Nginx буферизует ответы от бекенд-сервисов перед отправкой клиенту.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_PROXY_BUFFERING | Включает или отключает буферизацию ответов от прокси-бекенда. Возможные значения: "on" (включено) или "off" (выключено). Когда буферизация включена, Nginx будет стараться как можно быстрее принять полный ответ от бекенда, сохраняя его в памяти (в буферах, определённых директивами proxy_buffer_size и proxy_buffers). Если размер ответа превышает размеры доступных буферов, часть данных может быть временно сохранена во временный файл на диск | on / off | on |
| SPA_PROXY_BUFFER_SIZE | Размер одного буфера (в байтах или с указанием единиц k/m) для чтения первой части ответа от проксируемого сервера | int k/m | 16k |
| SPA_PROXY_BUFFERS_NUMBER | Количество основных буферов для чтения ответа от прокси-бекенда | int | 16 |
| SPA_PROXY_BUFFERS_SIZE | Размер основных буферов для чтения ответа от прокси-бекенда. Эти две переменные совместно формируют директиву proxy_buffers | int k/m | 16k |
| SPA_PROXY_BUSY_BUFFERS_SIZE | Лимит размера «занятых» буферов при буферизации. Эта директива (proxy_busy_buffers_size) указывает максимальный суммарный объём данных в буферах, который Nginx может одновременно держать в процессе отправки клиенту, пока остальная часть ответа ещё читается от бекенда | int k/m | 24k |
Настройки обработки тела клиентского запроса — приём данных от клиента (POST-запросы, загрузка файлов): лимиты размера и место хранения при чтении.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_CLIENT_BODY_BUFFER_SIZE | Размер буфера для чтения тела запроса клиента | string | 512M |
| SPA_CLIENT_MAX_BODY_SIZE | Максимальный допустимый размер тела HTTP-запроса от клиента | string | 512M |
Настройки таймаутов — время ожидания Nginx на разных этапах обработки запроса. Значения задаются с суффиксами (s, m и т.д.) или в секундах.
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_CLIENT_HEADER_TIMEOUT | Таймаут чтения заголовков HTTP-запроса от клиента. Nginx начнёт отсчёт времени, когда клиент подключился и начал отправлять запрос, и если полные заголовки (строка запроса и все поля Header) не будут получены за указанный период, Nginx прервёт соединение с ошибкой 408 Request Timeout | string | 600s |
| SPA_CLIENT_BODY_TIMEOUT | Таймаут на получение тела запроса от клиента. Похож на предыдущий, но отсчитывается во время чтения тела HTTP-запроса (например, при загрузке файла) | string | 600s |
| SPA_PROXY_CONNECT_TIMEOUT | Таймаут установления соединения с проксируемым сервером (бекендом). Это время, отведённое на этап подключения (TCP handshake) к адресу, указанному в proxy_pass (например, к SPA_PROXY_CORE_URL или другим) | string | 600s |
| SPA_PROXY_SEND_TIMEOUT | Таймаут передачи запроса (его тела) к прокси-бекенду | string | 600s |
| SPA_PROXY_READ_TIMEOUT | Таймаут ожидания ответа от прокси-бекенда. Это максимальный промежуток времени, в течение которого Nginx ждёт данных от upstream-сервера, между двумя чтениями | string | 600s |
| SPA_SEND_TIMEOUT | Таймаут отправки ответа клиенту | string | 600s |
Отладка и дополнительные настройки окружения
| Имя переменной | Описание | Тип/Значения | Значение по умолчанию |
|---|---|---|---|
| SPA_DEBUG | Флаг режима отладки конфигурации и работы контейнера | true / false | false |
| SPA_CUSTOM_CA_DIR | Путь к каталогу с дополнительными корневыми сертификатами | string | nil |