sub_filter
Тема дорожной карты · Nginx
Директива sub_filter в Nginx позволяет веб-серверу или обратному прокси выполнять текстовые подстановки в теле ответа перед доставкой контента клиенту, обеспечивая перезапись HTML, JavaScript или любого текстового контента на лету без изменения вышестоящего приложения. Типичный сценарий использования — перезапись абсолютных URL в ответах, полученных через обратный прокси: sub_filter 'http://internal-host' 'https://public-host' заменяет все вхождения в ответе при использовании совместно с sub_filter_all on, включающей глобальную замену вместо только первого совпадения. Модуль sub_filter требует включённой буферизации ответов (proxy_buffering on), поскольку Nginx должен буферизовать полное тело ответа для выполнения подстановки, а Content-Type ответа должен входить в список, управляемый sub_filter_types (по умолчанию text/html). Директива sub_filter_last_modified on сохраняет заголовок Last-Modified ответа после подстановки, чтобы клиентское кэширование оставалось функциональным. При использовании sub_filter в высокопроизводительном развёртывании Nginx учитывайте увеличенное потребление памяти из-за буферизации ответов для больших страниц и рассматривайте ограничение его применения конкретными блоками location, а не глобальным использованием.
Как это работает
sub_filter имеет встроенную HTTP Basic auth (auth_basic + auth_basic_user_file с htpasswd), верификацию client TLS-сертов (ssl_client_certificate + ssl_verify_client on) и auth_request для делегированной auth (subrequest к auth-сервису — идеально для OAuth-flow, SSO, JWT-верификации через sidecar). Для SSO + OIDC — модуль lua-resty-openidc (с OpenResty/Lua) или vouch-proxy как sidecar.
Когда применять
HTTP Basic — для непубличных admin / internal dashboards: быстро настроить, достаточно поверх HTTPS. auth_request — для делегирования к OAuth-прокси (oauth2-proxy, vouch-proxy) когда нужен реальный SSO. Client TLS-серты — для very-high-assurance B2B API или замены VPN. Не пишите свою JWT-верификацию в nginx — OpenResty/Lua или sidecar.
Типичные ошибки
Ловушки sub_filter: HTTP Basic поверх HTTP (credentials в открытом виде — всегда HTTPS); htpasswd-файлы в git ("internal only"); JWT-верификация через regex в nginx (пожалуйста, нет); неверно защищены /.well-known/ пути (admin-эндпойнты утекают).