Обратный прокси и HTTPS

Обратный прокси принимает HTTPS-запросы из Интернета, завершает HTTPS-соединение и предъявляет браузеру сертификат сайта. Сертификат проверяет браузер. Прокси передаёт разрешённые запросы приложению по внутренней сети, поэтому приложение остаётся недоступным напрямую из Интернета. Соединение от прокси до приложения в этой схеме использует HTTP.

Схема подходит, если вы размещаете приложение на отдельном Docker-хосте и хотите открыть сотрудникам портал по HTTPS. Само приложение умеет принимать HTTPS напрямую; это отдельный вариант, и одновременно настраивать оба способа не требуется.

Браузер --HTTPS--> прокси на VPS --HTTP по частной сети/VPN--> Docker-хост приложения

Прокси на VPS не подключается к сети другого Docker-хоста автоматически. Для удалённого приложения заранее настройте частный маршрут, например через существующий VPN, и правила межсетевого экрана. Ограничьте доступ к порту приложения адресом прокси и предусмотренным частным маршрутом. Отдельно подготовьте приватный HTTPS-доступ администратора к панели: публичный прокси из этой инструкции намеренно открывает только портал сотрудников.

Подготовка

Перед настройкой убедитесь, что у вас есть:

Что подготовить Для чего
Домен портала и сертификат с закрытым ключом для этого домена Для HTTPS на публичной стороне прокси. Сертификат получает и обновляет администратор сервера.
Адрес частного интерфейса Docker-хоста приложения На этот адрес будет привязан порт приложения.
Адрес прокси, который приложение фактически видит как прямого сетевого соседа Этот точный адрес указывается в TRUSTED_PROXIES. После Docker-маршрутизации или NAT он может отличаться от публичного IP VPS.
Частный маршрут между прокси и Docker-хостом Внешняя Docker-сеть соединяет контейнеры только на одном Docker-хосте и сама не соединяет разные хосты.

Все домены и адреса ниже предназначены только для примеров. Замените portal.example.com, 192.0.2.10 и 192.0.2.20/32 реальными адресами закрытой сети вашей установки. Сеть 192.0.2.0/24 зарезервирована для документационных примеров.

Сеть приложения

По умолчанию Compose публикует порт приложения только на 127.0.0.1:8080. Для удалённого прокси укажите частный адрес интерфейса Docker-хоста и отдельный порт, например:

HOST_BIND_IP=192.0.2.10
HOST_PORT=59000
TRUSTED_PROXIES=192.0.2.20/32

Здесь 192.0.2.10 — пример частного адреса хоста приложения, а 192.0.2.20/32 — пример IP отправителя TCP-соединения, который приложение должно видеть у прокси. TRUSTED_PROXIES принимает список CIDR через запятую, например 192.0.2.20/32,192.0.2.30/32. Маска /32 задаёт один IPv4-адрес, а /128 — один IPv6-адрес. Не указывайте 0.0.0.0/0: это доверило бы заголовкам пересылки любого отправителя.

Разрешите входящий TCP-порт 59000 только с предусмотренного адреса прокси или по частному VPN-маршруту. Не публикуйте этот порт на всех интерфейсах и не открывайте его в Интернете. Изменение переменных окружения требует пересоздать контейнер приложения:

docker compose config --quiet
docker compose up -d --force-recreate salary-slip

Выполняйте команды в каталоге Compose-файла приложения. Если сервис в вашем Compose называется иначе, укажите его фактическое имя. Обычный перезапуск из панели не перечитывает переменные окружения контейнера.

Доверенный прокси

TRUSTED_PROXIES — список CIDR-адресов непосредственных прокси, разделённых запятыми. От этих адресов приложение принимает X-Forwarded-For с IP посетителя и X-Forwarded-Proto: https с внешней схемой соединения. Это не список разрешённых посетителей и не сертификатное доверие. При пустом значении ни один прокси не считается доверенным.

Укажите IP-адреса всех непосредственных прокси, которые подключаются к приложению, включая отдельный приватный прокси администрирования, если он используется. Нужный IP — это адрес отправителя TCP-соединения, который приложение видит после маршрутизации и NAT.

При первичной настройке, пока TRUSTED_PROXIES пуст, откройте через прокси страницу /login. На Docker-хосте приложения найдите в JSON-журнале запись http_access и поле client_ip; например, выполните docker compose logs --since 1m salary-slip. Это поле показывает адрес прямого отправителя. Проверки /health и /ready в журнал не записываются. Подробнее — технический журнал узла. Не подставляйте автоматически публичный адрес VPS. Уже настроенную работающую установку не нужно временно менять для этой проверки.

Приложение разбирает цепочку X-Forwarded-For справа налево до первого недоверенного адреса. Если цепочка некорректна, оно использует адрес отправителя прямого соединения. Значение X-Forwarded-Proto: https принимается только от доверенного отправителя.

ADMIN_ALLOWED_CIDRS — отдельное ограничение сетей, из которых разрешена административная панель. Оно не заменяется настройкой TRUSTED_PROXIES. До сохранения публичного HTTPS-адреса подготовьте отдельный приватный HTTPS-доступ к администрированию. При Публичный URL со схемой https:// cookie входа становится защищённой и не отправляется браузером при обычном HTTP-входе из LAN.

Настройки приложения

После подготовки сети откройте в панели Настройки → Транспорт и задайте параметры:

Поле Значение
Публичный URL Внешний HTTPS-адрес портала, например https://portal.example.com. Если внешний порт отличается от 443, укажите его в URL, например https://portal.example.com:49443.
Режим работы сервиса HTTP, потому что HTTPS завершается на прокси.
TLS-сертификат и закрытый ключ Для этого сценария Go-приложению сертификат не нужен. Не загружайте сертификат прокси в настройки TLS приложения.
CORS origins (по одному на строку) Оставьте пустым, если страница портала и приложение доступны с одного внешнего адреса.

Сохраните настройки и примените их явной командой Перезапустить сервис. Подробнее — настройки транспорта и перезапуск выбранных узлов. Настройки Публичный URL, Режим работы сервиса и CORS хранятся в базе данных; одноимённое значение в .env не заменяет их.

Вариант с reproxy

В репозитории есть отдельный Compose-файл deploy/reproxy/compose.yaml. Он запускает umputun/reproxy:v1.7.1, принимает HTTPS на порту 443 и направляет только точные пути портала сотрудников. Это самостоятельная альтернатива nginx, а не дополнительный слой перед nginx. Сохраните приведённый ниже compose.yaml и файл .env в одном каталоге на VPS; команды запуска выполняйте из этого каталога.

Создайте .env рядом с Compose-файлом, скопировав deploy/reproxy/.env.example, затем замените примеры:

PUBLIC_DOMAIN=portal.example.com
BACKEND_URL=http://192.0.2.10:59000
TLS_CERTS_ROOT=/etc/letsencrypt
SSL_CERT_PATH=/certs/live/portal.example.com/fullchain.pem
SSL_KEY_PATH=/certs/live/portal.example.com/privkey.pem

BACKEND_URL должен быть доступен из внешней Docker-сети container_network и не должен оканчиваться /. Каталог сертификатов подключается только для чтения; укажите корень, в котором доступны и live/, и archive/, поскольку сертификаты могут ссылаться из одной папки в другую. Убедитесь, что сертификат и ключ соответствуют домену и доступны контейнеру.

В отдельном каталоге проекта reproxy используйте следующий Compose-файл. Сохраните его вместе с .env выше, заменив все примеры на значения своей сети:

services:
  reproxy:
    image: umputun/reproxy:v1.7.1
    restart: unless-stopped
    environment:
      STATIC_ENABLED: "true"
      STATIC_RULES: >-
        ${PUBLIC_DOMAIN:?Set PUBLIC_DOMAIN to the exact public portal domain},^(/|/login|/link|/payslips|/assets/[A-Za-z0-9_-][A-Za-z0-9._-]*|/api/v1/branding/logo|/api/v1/auth/login|/api/v1/auth/invitations/requirements|/api/v1/auth/invitations/exchange|/api/v1/auth/password/reset|/api/v1/auth/password/change|/api/v1/auth/totp/setup|/api/v1/auth/totp|/api/v1/auth/session|/api/v1/auth/logout|/api/v1/payslips|/api/v1/payslips/settings|/api/v1/payslips/pdf|/api/v1/payslips/pdf-intents|/api/v1/payslips/pdf-jobs|/api/v1/payslips/pdf-jobs/[0-9A-Fa-f-]{36}|/api/v1/payslips/pdf-jobs/[0-9A-Fa-f-]{36}/file)$,${BACKEND_URL:?Set BACKEND_URL to the internal service URL}$$1
      SSL_TYPE: static
      SSL_CERT: ${SSL_CERT_PATH:-/certs/live/portal.example.com/fullchain.pem}
      SSL_KEY: ${SSL_KEY_PATH:-/certs/live/portal.example.com/privkey.pem}
      SSL_NO_REDIRECT: "true"
      KEEP_HOST: "true"
      DROP_HEADERS: X-Forwarded-For,X-Real-IP,X-Forwarded-Proto,X-Forwarded-Port,X-Forwarded-Host,X-Forwarded-URL,Forwarded
      REMOTE_LOOKUP_HEADERS: "false"
      LOGGER_ENABLED: "false"
      TIMEOUT_WRITE: 120s
      TIMEOUT_RESP_HEADER: 120s
    ports:
      - "443:8443"
    networks:
      - container_network
    volumes:
      - type: bind
        source: ${TLS_CERTS_ROOT:?Set TLS_CERTS_ROOT to the host certificate root directory}
        target: /certs
        read_only: true
        bind:
          create_host_path: false

networks:
  container_network:
    external: true

STATIC_RULES ограничивает маршруты сотрудническим порталом. Не расширяйте шаблон до общих префиксов /api/ или /assets/: неизвестные и будущие маршруты должны оставаться закрытыми.

KEEP_HOST: "true" сохраняет домен и порт из браузерного адреса при передаче запроса приложению. DROP_HEADERS удаляет переданные клиентом заголовки пересылки до установки доверенных значений самим прокси. REMOTE_LOOKUP_HEADERS: "false" запрещает reproxy определять адрес посетителя для собственных проверок из переданных клиентом заголовков.

Сеть container_network должна уже существовать на Docker-хосте VPS. Она соединяет контейнер reproxy с другими контейнерами на том же хосте, но не настраивает маршрут к удалённому Docker-хосту. Для удалённого адреса приложения заранее настройте VPN-маршрут и правила межсетевого экрана.

Проверьте Compose-конфигурацию, запустите reproxy и проверьте состояние контейнера:

docker compose config --quiet
docker compose up -d
docker compose ps

Для проверки ответа приложения используйте /health на внутреннем адресе приложения из BACKEND_URL. Собственные /health и /ping reproxy не проверяют приложение. Не выводите в терминал конфигурацию с секретами и не публикуйте её вывод.

Правило reproxy разрешает только следующие точные пути:

  • страницы сотрудников: /, /login, /link, /payslips;
  • один плоский файл /assets/<имя> с буквами, цифрами, _, - и .;
  • /api/v1/branding/logo;
  • вход и восстановление: /api/v1/auth/login, /api/v1/auth/invitations/requirements, /api/v1/auth/invitations/exchange, /api/v1/auth/password/reset, /api/v1/auth/password/change, /api/v1/auth/totp/setup, /api/v1/auth/totp, /api/v1/auth/session, /api/v1/auth/logout;
  • расчётные листки: /api/v1/payslips, /api/v1/payslips/settings, /api/v1/payslips/pdf, /api/v1/payslips/pdf-intents, /api/v1/payslips/pdf-jobs, /api/v1/payslips/pdf-jobs/<UUID> и /api/v1/payslips/pdf-jobs/<UUID>/file.

Правило не открывает /admin, /api/v1/admin/*, аудит, восстановление и проверки сервиса приложения. Неразрешённые пути получают ответ reproxy с кодом 502. HTTP-метод, вход в систему и права доступа по-прежнему проверяет приложение. Сохраните без изменений параметры запроса URL и заголовки браузера, включая Host, Cookie, Origin, X-Requested-With и Idempotency-Key. Не подменяйте Origin, X-Requested-With или данные авторизации.

Шаблон публикует внешний порт 443. Если он занят и вы меняете отображение порта, например на 49443:8443, укажите тот же порт во внешнем Публичный URL. После обновления файлов сертификата выполните docker compose restart reproxy, чтобы контейнер перечитал их. Compose-файл не включает HTTP-порт, Docker socket, панель управления или перенаправление с HTTP.

Отдельный вариант с nginx

Используйте этот вариант, если nginx установлен как публичный HTTPS-сервер на VPS. Не подключайте nginx перед reproxy из предыдущего раздела. Ниже приведён самостоятельный серверный блок. Замените домен, backend-адрес и пути сертификата на значения вашей установки.

server {
    listen 443 ssl;
    server_name portal.example.com;

    ssl_certificate /etc/letsencrypt/live/portal.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/portal.example.com/privkey.pem;

    if ($host != portal.example.com) { return 404; }

    proxy_http_version 1.1;
    proxy_read_timeout 120s;
    proxy_send_timeout 120s;
    proxy_connect_timeout 10s;
    proxy_cache off;
    proxy_buffering off;

    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-Host $http_host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header Forwarded "";
    proxy_set_header X-Forwarded-URL "";

    location = / { proxy_pass http://192.0.2.10:59000; }
    location = /login { proxy_pass http://192.0.2.10:59000; }
    location = /link { proxy_pass http://192.0.2.10:59000; }
    location = /payslips { proxy_pass http://192.0.2.10:59000; }
    location ~ ^/assets/[A-Za-z0-9_-][A-Za-z0-9._-]*$ { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/branding/logo { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/login { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/invitations/requirements { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/invitations/exchange { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/password/reset { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/password/change { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/totp/setup { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/totp { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/session { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/auth/logout { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/payslips { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/payslips/settings { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/payslips/pdf { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/payslips/pdf-intents { proxy_pass http://192.0.2.10:59000; }
    location = /api/v1/payslips/pdf-jobs { proxy_pass http://192.0.2.10:59000; }
    location ~ "^/api/v1/payslips/pdf-jobs/[0-9A-Fa-f-]{36}(/file)?$" { proxy_pass http://192.0.2.10:59000; }

    location / { return 404; }
}

proxy_pass указан без URI и завершающего /, чтобы nginx передавал исходный путь и параметры запроса URL. Nginx перезаписывает Host, X-Forwarded-Host, X-Forwarded-For, X-Real-IP, X-Forwarded-Proto и X-Forwarded-Port, а заголовки Forwarded и X-Forwarded-URL удаляет. Браузерные Cookie, Origin, X-Requested-With и Idempotency-Key остаются без изменений.

proxy_buffering off и proxy_cache off отключают буферизацию ответов и кэширование. Для долгих ответов ожидание чтения и отправки ограничено 120 секундами. Ожидание соединения с внутренним адресом приложения составляет 10 секунд; при необходимости согласуйте его с вашей сетью. Если nginx слушает внешний порт 49443, измените listen и укажите этот порт в Публичный URL.

Если nginx установлен как системная служба Linux, проверьте конфигурацию командой sudo nginx -t, затем перечитайте её командой sudo nginx -s reload. Сертификаты и их продление остаются ответственностью администратора хоста. После замены сертификата или ключа nginx должен перечитать файлы.

Проверка HTTPS

Откройте внешний адрес портала в браузере и убедитесь, что браузер показывает защищённое соединение. Войдите тестовой учётной записью сотрудника и проверьте доступность страницы расчётных листков. Убедитесь, что административные маршруты через публичный прокси недоступны.

Предупреждения TLS в панели приложения относятся к сертификату, который использует сам Go-сервис. Они не проверяют сертификат внешнего прокси. Следите за сроком сертификата на прокси отдельно и после обновления проверьте, что прокси перечитал новые файлы.

Источники