MOD_PROXY_HTML_ERR Linux / DevOps

Траблшутинг ошибок mod_proxy_html в Apache: коррекция URL в обратном прокси

Обновлено: 21.08.2026

При проксировании бэкенда в подкаталог (/app/) ссылки в HTML, картинки и скрипты ведут в корень / и отдают 404.
Логи Apache содержат ошибки ProxyHTMLURLMap: no map defined или Cannot parse HTML.
Контент страниц ломается из-за некорректной обработки сжатых (gzip/brotli) ответов бэкенда.

1. Включение необходимых модулей Apache

a2enmod proxy proxy_http proxy_html xml2enc headers deflate filter
systemctl restart apache2

2. Настройка виртуального хоста с трансляцией путей HTML

Отредактируйте конфигурацию VirtualHost:

<VirtualHost *:80>
    ServerName proxy.itstm.ru

    ProxyRequests Off
    ProxyPreserveHost Off

    <Location /app/>
        ProxyPass http://internal-backend:8080/
        ProxyPassReverse http://internal-backend:8080/

        # Включение парсера HTML
        ProxyHTMLEnable On
        ProxyHTMLExtended On
        
        # Отключение сжатия с бэкенда для возможности парсинга HTML на лету
        RequestHeader unset Accept-Encoding

        # Правила подмены внутренних ссылок на внешние
        ProxyHTMLURLMap http://internal-backend:8080/ /app/
        ProxyHTMLURLMap / /app/

        # Замена путей внутри CSS и JavaScript
        ProxyHTMLURLMap "/assets/" "/app/assets/" V
        
        # Коррекция заголовков редиректа Location
        ProxyPassReverseCookiePath / /app/
    </Location>
</VirtualHost>

3. Валидация конфигурации

apachectl configtest && systemctl reload apache2

💡 Практика специалистов: По возможности избегайте переписывания HTML на лету через веб-сервер, так как это создает существенную нагрузку на CPU. Правильнее настраивать параметр baseUrl/AppRoot непосредственно в самом приложении.

Частые вопросы (FAQ)

Зачем отключать Accept-Encoding через RequestHeader unset?

Если бэкенд сожмет HTML ответ алгоритмом gzip, модуль mod_proxy_html не сможет прочитать бинарный поток и выполнить строковую замену ссылок в документе.

Что означает флаг 'V' в директиве ProxyHTMLURLMap?

Флаг 'V' (Verbose/Extended) активирует парсинг и замену ссылок внутри тегов <script> и inline CSS-стилей, а не только в стандартных HTML-атрибутах href и src.