Инженерная документация

Назначение

unRedirector (unRed) — обратный прокси на Go. Он направляет запросы к бэкендам по имени хоста и пути URL, распределяет нагрузку между серверами и раздаёт локальные файлы. В нём настраиваются TLS, аутентификация, кэширование и контроль доступности бэкендов.

Сборка и запуск

Для запуска нужен бинарник с действующей лицензией. Исходники находятся в source/; скрипты сборки в корне проекта добавляют версию и лицензионные параметры. Обычный go build без этих параметров создаёт бинарник, который при запуске без -sstini завершится с ошибкой лицензии.

Подготовьте config.json, доступный бэкенд и входящий TLS-сертификат. Команда ниже запускает готовый бинарник из текущего каталога.

./unred.lin -config ./config.json -debug 2

Основные флаги

Конфигурация

При загрузке JSON unRed обновляет маршруты, веса бэкендов и настройки модулей. SIGHUP перечитывает конфигурацию без перезапуска. Если новый файл содержит ошибку, она записывается в журнал, а процесс продолжает работать с предыдущей конфигурацией.

Основные параметры

Маршрутизация и проксирование

Правило связывает имя хоста и, при необходимости, префикс пути URL с бэкендом. Среди совпавших префиксов выбирается самый длинный. Общие rulesURL сопоставляются с путём точно, а configs.<host>.rulesURL — по префиксу.

Значения правил

{
  "rules": {
    "portal.example.com": "http://127.0.0.1:3000",
    "portal.example.com/static": "file://",
    "portal.example.com/api": "api-pool"
  },
  "balancer-weight": {
    "api-pool": {
      "primary": {
        "http://10.0.0.11:8080": 80,
        "http://10.0.0.12:8080": 20
      },
      "backup": {
        "http://10.0.0.21:8080": 100
      }
    }
  }
}

Ответы бэкенда

Для 3xx передаются исходные заголовки и допустимое тело; у 304 тела нет. Заголовки, относящиеся к отдельному соединению, удаляются. Завершающие заголовки сохраняются для gRPC. Для WebDAV режим convert-200 меняет финальный статус на 200, если запрос не совпал с passthrough_errors. Правила WebDAV.

Expect: 100-continue

По умолчанию заголовок Expect удаляется перед отправкой бэкенду. Чтобы передавать Expect: 100-continue и ожидать предварительный ответ бэкенда, установите одновременно stripExpect: false и proxyExpect: true.

Балансировка и доступность бэкендов

balancer-weight задаёт веса бэкендов общим списком или в группах primary и backup. Проверка доступности по умолчанию выключена. При включённом balancerHealth запросы направляются на доступные бэкенды.

Если недоступными отмечены все бэкенды, unRed выбирает сервер из полного списка по весам и пытается отправить запрос. Состояние проверок хранится отдельно в каждом процессе.

TLS и аутентификация

Входящие TLS-соединения

Сертификат выбирается по имени сервера, переданному клиентом через SNI. Файлы задаются в секции certs или загружаются из certs/<host>.crt и certs/<host>.key. В режиме -sstini используется сертификат SST.

Аутентификация

Аутентификация настраивается в configs.<host>.auth. Доступны проверка токена bearer и проверка Basic-данных через внешнюю программу (basic-binary), управляемую службу (basic-binary-port-controlled) или удалённый сервис (remote-hostport).

HTTP/3 и QUIC

unRed принимает HTTP/3-соединения по UDP. HTTP/1.1 и HTTP/2 продолжают работать по TCP. Для HTTP/3 действуют те же маршруты, аутентификация, ограничения запросов и режимы WebDAV. С бэкендами прокси соединяется по HTTP/1.1 или HTTP/2.

HTTP/3 использует TLS 1.3, сертификаты HTTPS, SNI, OCSP и настройки клиентских сертификатов clientTLS. Ранние данные 0-RTT выключены: запросы обрабатываются после завершения TLS-согласования.

Порты и сеть

Разрешите UDP на основном и дополнительных HTTPS-портах, включая порты из правил. Например, адрес :9443 использует TCP 9443 и UDP 9443. Порты listen-http и правила с http:// обслуживают только TCP.

Alt-Svc объявляется только после открытия UDP-порта и указывает его фактический номер. При NAT внешний UDP-порт должен совпадать с объявленным. Если UDP недоступен или номера портов отличаются, оставьте advertiseAltSvc: false.

Перечитывание и диагностика

Изменение блока http3 требует перезапуска. UDP-порты из правил добавляются и удаляются при перечитывании маршрутов; перевод порта с HTTPS на обычный HTTP закрывает UDP. Ошибка открытия UDP при старте завершает процесс. При обновлении правил такая ошибка записывается в журнал, а остальные порты продолжают работать.

В /unRed/Listeners HTTP/3-адреса имеют proto: "http3". При SIGINT или SIGTERM HTTP/3 и основной HTTPS-сервер получают до 10 секунд на завершение запросов.

Для маршрутов с inspect: true и запросов CONNECT через HTTP/3 возвращается 501; используйте для них прежние HTTP-протоколы. WebSocket работает через TCP. Перенаправление произвольных UDP-пакетов — отдельная функция.

Пример HTTP/3 с сертификатом и бэкендом.

Кэширование

Кэш снимков включается через cache.enabled и применяется к URI, содержащим shot. Для кэширования HTTP-ответов с учётом заголовков бэкенда дополнительно включите cache.respectUpstreamCacheControl: true.

Протоколы

WebDAV: правила применения

DAV распознаётся по методу (например, PROPFIND или LOCK), по заголовку DAV в ответе этого бэкенда за последние пять минут или в текущем ответе. Первый OPTIONS с заголовком DAV уже обрабатывается выбранным режимом. Обычный GET без этих признаков не становится DAV автоматически.

Оба параметра задаются в корне и в configs.<host>. Для passthroughDAV отсутствие или null означает наследование, явное false отключает детектор. Для webdavResponseMode пустая строка наследует общее значение. При выборе хоста порт отбрасывается; поддерживаются имена с шаблонами, например *.example.com. Режим без включённого детектора не действует. Неизвестное значение режима вызывает ошибку загрузки; при ошибке перечитывания остаётся прежняя конфигурация.

На хостах с включённым DAV-детектором и при совпадении passthrough_errors оба кэша HTTP-ответов обходятся. Прокси передаёт редиректы бэкенда клиенту, не следуя им самостоятельно. В сохраняемых ответах исходный Content-Type не переопределяется по содержимому тела. Заголовки ответа передаются клиенту, кроме тех, которые относятся к отдельному соединению. Статусы, заголовки и содержимое тела сохраняются на уровне HTTP; разбиение на TCP-пакеты и HTTP-фрагменты может меняться.

Политика работает в обычной HTTP-ветке при inspect: false. Локальные отказы аутентификации, ограничения запросов и ошибки соединения сохраняют свои коды. Эта политика не применяется к inspect, отдельным TCP-туннелям и WebSocket. Примеры transparent и convert-200.

Мониторинг и диагностика

Встроенные страницы и счётчики доступны через HTTPS. Начальная страница /unRed содержит ссылки на модули диагностики.

Ограничьте доступ к служебным адресам сетевыми правилами или внешним прокси с аутентификацией. Настройка configs.<host>.auth защищает маршруты приложений и не распространяется на эти адреса.

В разработке

Планируемые возможности.