Выберите продукт

add_header в Nginx без ловушек: always, контексты и наследование

Директива add_header кажется простой, но чаще всего подводит в двух местах: наследование между http/server/location и ответы не 2xx. В разборе — параметр always, редиректы и 304, нюансы error_page, рабочие шаблоны для security и CORS, чеклист и отладка.
add_header в Nginx без ловушек: always, контексты и наследование

Если вы хоть раз настраивали заголовки в Nginx, то почти наверняка сталкивались с «пропадающим» HSTS на редиректе, отсутствующим CORS на 4xx/5xx или неожиданным исчезновением ранее заданных заголовков внутри конкретного location. Виноваты не «глюки», а специфика директивы add_header, ее наследования и параметр always. Ниже — подробный разбор с практическими схемами и шаблонами.

Что именно делает add_header и чего не делает

add_header добавляет заголовок в ответ сервера. По умолчанию заголовок добавляется только к «успешным» ответам, а для ответов-ошибок он не добавляется. В результате security- и CORS-заголовки часто теряются как раз в те моменты, когда они нужны сильнее всего — при ошибках и служебных ответах.

Параметр always говорит Nginx добавлять заголовок ко всем финальным ответам, включая 4xx/5xx и ответы, сформированные через error_page.

Важно не путать add_header с proxy_set_header. Первое — про заголовки ответа клиенту, второе — про заголовки запроса, который Nginx отправляет во внутренний апстрим. Если вы перепутали их назначение, эффект будет нулевым: клиент не увидит нужного заголовка.

Когда нужен параметр always

Почти всегда, когда речь про:

  • HSTS (Strict-Transport-Security) — иначе заголовок теряется на части ответов;
  • CORS (Access-Control-Allow-*) — ошибки тоже должны возвращать корректные CORS-заголовки;
  • Безопасность и приватность: X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, Cross-Origin-*.

Условно, если заголовок влияет на политику безопасности или кэширования со стороны клиента, его отсутствие на ошибках и редиректах — потенциальная брешь.

Контексты: http, server, location и if in location

add_header можно объявлять в контекстах http, server, location, а также внутри if при условии, что это if in location. От контекста зависит, где сработает правило и как оно наследуется.

Тонкая настройка Nginx чаще всего делается на собственной машине. Если вам нужна изоляция, руут-доступ и стабильная производительность, рассмотрите VDS — так проще воспроизводимо держать единый набор заголовков для всех проектов.

Ключевое правило наследования

Директивы add_header наследуются с верхнего уровня только если на текущем уровне нет ни одной собственной директивы add_header. Как только вы объявили хотя бы один add_header в более узком контексте, вы «обрубили» все наследование и должны перечислить все нужные заголовки заново.

Это самый частый источник сюрпризов. Например, вы задали общий набор заголовков в server, а затем в одном из location добавили одиночный add_header для CORS. Результат: в этом location останется только CORS, а все security-заголовки «пропадут», потому что наследование было сброшено фактом наличия локальной директивы.

Проверка себя: мини-чек на наследование

  • Хотите общий набор заголовков на весь виртуальный хост? Объявляйте их на уровне server.
  • Нужно в location добавить один-единственный заголовок? Либо дублируйте весь набор, либо вынесите общий набор в отдельный include и подключайте его везде, где вы добавляете локальные заголовки.
  • Используете if в location? Заголовки там работают, но правило наследования остается прежним.

Наследование заголовков в Nginx между http, server и location

Редиректы, 304 и error_page

Служебные ответы часто рушат ожидания: вы настроили заголовки, но при return 301 или при 304 Not Modified нужного заголовка нет. Почему? По умолчанию add_header действует для «успешных» кодов, а для ошибок и некоторых служебных случаев — нет. Спасти ситуацию призван always.

Особый случай — error_page. Когда вы переопределяете код ответа через error_page, то без always заголовки могут не добавляться к исходным ошибочным ответам. С always они будут добавлены независимо от того, как ответ сформирован и какой исходный код был у запроса.

Типичный безопасный шаблон заголовков

server {
    listen 443 ssl http2;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-Frame-Options "DENY" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Referrer-Policy "no-referrer-when-downgrade" always;
    add_header Permissions-Policy "geolocation=(), microphone=()" always;
    add_header Cross-Origin-Opener-Policy "same-origin" always;
    add_header Cross-Origin-Resource-Policy "same-origin" always;

    # ... остальной конфиг
}

Этот блок лучше держать на уровне server для HTTPS-виртуала (на HTTP он не нужен — например, HSTS игнорируется браузером по не-HTTPS). Если только подключаете HTTPS, заранее оформите SSL-сертификаты. Если ниже в каком-то location понадобятся дополнительные заголовки — не забудьте дублировать весь набор или подключить include с общими заголовками.

CORS: почему без always нельзя

Запросы из браузера ждут корректные CORS-заголовки независимо от того, успешно ли выполнен запрос. Предположим, вы отдаете Access-Control-Allow-Origin только на 2xx. При 401/403/404 клиентская логика может «сломаться», потому что браузер заблокирует доступ к телу ответа без CORS. Поэтому CORS почти всегда настраивают с always, а также добавляют Vary, если политика зависит от Origin. Дополнительные приемы собраны в статье «CORS-заголовки: Nginx и Apache» — посмотрите материал в разделе подробный разбор CORS.

location /api/ {
    # Общие security-заголовки стоит включить через include;
    # Здесь — чисто CORS.

    add_header Access-Control-Allow-Origin "*" always;
    add_header Access-Control-Allow-Methods "GET, POST, OPTIONS" always;
    add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
    add_header Vary "Origin" always;

    if ($request_method = OPTIONS) {
        add_header Content-Length 0 always;
        add_header Content-Type text/plain always;
        return 204;
    }

    # proxy_pass ...
}

Если вам нужна точная выборка по источникам, вместо * используйте $http_origin с проверкой в map (и обязательно не забывайте Vary: Origin).

FastFox VDS
Облачный VDS-сервер
Виртуальные серверы с быстрым запуском и гибкой конфигурацией от 390₽ / мес
Доступные локации
Россия Нидерланды Финляндия

Как не потерять заголовки при «точечных» переопределениях

Два рабочих подхода:

  1. Дублировать весь набор заголовков в каждом location, где вы используете add_header. Надежно, но громоздко.
  2. Вынести общие заголовки в файл и подключать через include. Тогда даже в «частных» location вы начинаете с общего набора и добавляете точечные.
# common/security_headers.conf
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
add_header X-Frame-Options "DENY" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "no-referrer-when-downgrade" always;
add_header Permissions-Policy "geolocation=(), microphone=()" always;

# server {...}
server {
    listen 443 ssl http2;
    include common/security_headers.conf;

    location /static/ {
        include common/security_headers.conf; # Чтобы не срезать наследование
        add_header Cache-Control "public, max-age=31536000, immutable" always;
    }
}

Подключение include в каждом location, где есть собственные заголовки, — самый практичный способ не наступать на грабли.

Противоречия и дубликаты: как Nginx склеивает заголовки

Nginx не «перезаписывает» одинаковые заголовки, а добавляет второй экземпляр. Браузер может объединять их по правилам конкретного заголовка (например, Cache-Control может конфликтовать). Если вы получаете заголовок и от апстрима, и от Nginx, решайте конфликт явным образом:

  • Для ответов из апстрима: proxy_hide_header убирает конкретный заголовок из ответа апстрима.
  • Для заголовков, поставленных ранее в Nginx, штатного удаления нет; можно «переформатировать» поведение конфигурацией или использовать сторонние модули, если это допустимо вашей политикой.
location /api/ {
    proxy_hide_header Server;
    proxy_hide_header X-Powered-By;
    # ...
}

Избыточные или конфликтующие заголовки — частая причина неожиданных кэшей, смешения политик безопасности и проблем с CORS.

Отладка заголовков: curl -I и кастомный формат access-лога

Редиректы и HSTS: частые ошибки

Классика: на HTTPS-виртуале задан Strict-Transport-Security, но при редиректе внутри сайта он отсутствует. Причины две: либо заголовок объявлен в location, где редирект уходит раньше, либо отсутствует always. Решение — объявлять HSTS на уровне server с always и не занижать область действия излишне узким location. Подробная инструкция по выпуску HTTPS и включению HSTS — в материале HTTPS, Certbot и HSTS.

server {
    listen 443 ssl http2;

    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

    return 301 https://example.org$request_uri;
}
FastFox SSL
Надежные SSL-сертификаты
Мы предлагаем широкий спектр SSL-сертификатов от GlobalSign по самым низким ценам. Поможем с покупкой и установкой SSL бесплатно!

304 Not Modified и кэш

304 — особенный ответ без тела. Клиент может использовать заголовки, кешированные ранее, или те, что пришли с 304. Если без always нужные заголовки не попадают в 304, клиентская сторона может вести себя неконсистентно: например, считать, что у ответа нет Cache-Control или политики безопасности. Чтобы избежать сюрпризов с валидаторами и браузерами, задавайте важные заголовки с always и держите кэш-заголовки согласованными между 200 и 304.

error_page и внутренние локации

При обработке ошибок через error_page вы фактически запускаете внутренний запрос в другой location. Без always итоговый набор заголовков может зависеть от того, какой код вернулся на выходе. С always вы исключаете «просадки» заголовков на ошибочных цепочках.

error_page 404 = @fallback;

location @fallback {
    add_header Cache-Control "no-store" always;
    return 200 "{}";
}

Если вы используете общий набор security-заголовков, помните про правило наследования и не забывайте подключать include в таких внутренних локациях.

Отладка заголовков: как быстро понять, что пошло не так

Самое простое — смотреть «сырой» ответ:

curl -I https://example.org
curl -I -H "Origin: https://foo.example" https://example.org/api/

Чтобы ловить «дрейф» заголовков прямо в логах, добавьте в формат access-лога интересующие $sent_http_* переменные. Например, так:

log_format hdr '$remote_addr - $request "$status" '
               'sts=$sent_http_strict_transport_security '
               'xfo=$sent_http_x_frame_options '
               'csp=$sent_http_content_security_policy '
               'cors=$sent_http_access_control_allow_origin';

access_log /var/log/nginx/access.log hdr;

Теперь вы будете видеть, какие значения реально уехали клиенту. Это удобный способ выявить сброшенное наследование или конфликт с заголовками апстрима. Если параллельно решаете миграцию с редиректами 301, обратите внимание на разбор «Переезд домена, 301, HSTS и SSL» — см. чеклист переезда домена.

Content-Security-Policy: минимально безопасный старт

Полная CSP сложна и требует инвентаризации фронтенда. Но даже базовая политика уже помогает. В Nginx ее обычно задают одной строкой:

add_header Content-Security-Policy "default-src 'self'; object-src 'none'; base-uri 'self'" always;

Планомерно расширяйте политику, включая источники по мере необходимости, и обязательно тестируйте в режиме Content-Security-Policy-Report-Only на ранних этапах. Для режима report-only добавьте отдельный заголовок с тем же набором правил, но без эффектов блокировки. Не забывайте правило наследования: если вы в каком-то location добавили чисто CORS, придется повторить и CSP.

Версии Nginx и совместимость

Параметр always поддерживается в современных стабильных версиях давно. Если у вас древний Nginx, обновитесь: отсутствие always усложняет конфигурацию, а безопасность страдает. При миграции проверяйте, не «ломает» ли новое поведение ваши редиректы и кэш-цепочки (особенно 304), и валидируйте заголовки инструментами командной строки и автотестами.

Чеклист перед продом

  • Где объявлены базовые security-заголовки? На уровне server для HTTPS.
  • Включен ли always для HSTS, CORS и базовой безопасности? Должен быть.
  • Есть ли локации с собственными add_header? Если да, общий набор подключен через include или продублирован?
  • Проверены ли ответы на 301/302, 304, 401/403/404, 5xx? Заголовки на месте?
  • Нет ли конфликтов с заголовками апстрима? При необходимости используйте proxy_hide_header.
  • Логи содержат ключевые $sent_http_* для наблюдаемости? Это помогает ловить регрессии.

Итоги

add_header в Nginx прост, пока вы не столкнетесь с наследованием и «нестандартными» кодами ответа. Две главные идеи, которые экономят часы отладки: используйте always для политик безопасности и CORS, а общий набор заголовков держите на уровне server и/или в подключаемом include, который повторяете в каждом «частном» контексте, где есть собственные add_header. Добавьте наблюдаемость через $sent_http_*, регулярно проверяйте 3xx/4xx/5xx/304 и не забывайте про конфликты с заголовками апстрима. Тогда заголовки будут предсказуемыми, а безопасность — консистентной.

Поделиться статьей

Вам будет интересно

Как безопасно выполнить bootstrap MariaDB Galera после полного останова

Как безопасно выполнить bootstrap MariaDB Galera после полного останова

После одновременной остановки всех узлов Galera обычного запуска MariaDB недостаточно. Сначала найдите сервер с последней транзакц ...
CoreDNS в Kubernetes: исправляем CrashLoopBackOff, SERVFAIL и DNS-петлю

CoreDNS в Kubernetes: исправляем CrashLoopBackOff, SERVFAIL и DNS-петлю

Разберём, почему CoreDNS перезапускается или отвечает SERVFAIL, как обнаружить замкнутую пересылку DNS-запросов, проверить доступн ...
Apache Kafka KRaft на VDS: отдельные controller и broker

Apache Kafka KRaft на VDS: отдельные controller и broker

Соберём новый Kafka-кластер без ZooKeeper на шести Linux VDS: три узла controller образуют отказоустойчивый metadata quorum, а три ...