Годами перезагрузка конфига nginx выглядела одинаково: правишь файл, nginx -t, шлёшь сигнал, а потом идёшь читать логи, чтобы узнать, сработало ли оно на самом деле. nginx 1.31.5 (mainline, выпущен 2 сентября 2026) меняет вторую половину этого ритуала. Он приносит Control API в open-source nginx, так что перезагрузка конфига теперь - это HTTP-запрос, который отвечает в JSON, а не сигнал, результат которого приходится выискивать в error.log.

Вот что это такое, как этим пользоваться и что оно меняет - и не меняет - в эксплуатации reverse proxy.

Старый способ: перезагрузил и пошёл читать логи

nginx -s reload - сигнальная форма перезагрузки. Он шлёт SIGHUP мастер-процессу, который заново читает и переоценивает конфигурацию и поднимает новые воркеры.[6] Для человека в шелле - нормально. Для автоматизации - плохо.

Проблема в том, чего команда не сообщает. Код возврата 0 означает только, что сигнал доставлен - но не то, что конфиг распарсился, не то, что воркеры стартовали, не то, что новая директива listen смогла забиндиться. Если в конфиге опечатка, путь к сокету, который воркер не может открыть, или директива, которая не применяется, - nginx пишет ошибку в лог и продолжает отдавать последний рабочий конфиг. И цикл оператора такой: перезагрузить, а потом хвостом смотреть error.log и сопоставлять увиденное с тем, что ты только что поменял.

Именно этот цикл Control API и заменяет.

Что такое Control API

Control API - это небольшой REST-интерфейс, который живёт в мастер-процессе nginx и занимается runtime-контролем и инспекцией. Изначально это была фича NGINX Plus - она вышла впервые в релизе Plus R37.0 long-term support - а 1.31.5 открывает её в ядре.[2][3]

Он отдаёт три эндпоинта:[2]

  • /1/control/processes - информация о воркерах: имя, PID, состояние выхода.
  • /1/control/config - конфигурация nginx в памяти. GET - посмотреть, PATCH - запустить перезагрузку.
  • /1/nginx - версия и сборка.

Вот и вся суть. Вместо того чтобы послать сигнал и гадать о результате, ты делаешь HTTP-запрос и читаешь JSON-ответ.

Требование к версии: mainline 1.31.5+

Control API пришёл в ветку mainline. Open-source nginx должен быть версии 1.31.5 или новее, чтобы отдать его.[1][3] Ветка stable - это отдельный трек (1.30.x)[7] и она отстаёт. Так что если ваш дистрибутив собирает nginx из ветки stable, фичи вы не увидите, пока не перейдёте на mainline.

Это и есть практическое ограничение, которое стоит держать в голове: для большинства «просто работает» VPS-установок nginx из дистрибутива - это ветка stable. Переход на mainline - отдельное решение (то же тестирование, что и при любой смене ветки), и это цена доступа к Control API. Релиз доступен в виде исходников и бинарных пакетов для основных Linux-дистрибутивов, так что компилировать не придётся.[3]

Включить

Control API выключен по умолчанию.[2] Вы включаете его при старте флагом -l, указав Unix-domain сокет или TCP-порт:[2]

sudo nginx -l unix:/tmp/nginx.sock

Используйте Unix-сокет, а не порт. API - это неаутентифицированный интерфейс к внутренностям nginx; и admin guide, и пост о релизе советуют биндить его на Unix-сокет по пути, доступному только привилегированным пользователям, и никогда не выставлять в публичный интернет.[2][3] Права файла сокета - это и есть весь контроль доступа, поэтому сокет должен лежать в каталоге, куда обычные пользователи не могут писать.

Перезагрузка через PATCH

Когда API запущен, перезагрузка конфига - это один запрос к /1/control/config:

curl --unix-socket /tmp/nginx.sock -X PATCH http://localhost/1/control/config

Меняется не сама перезагрузка - PATCH перезагружает примерно так же, как и nginx -s reload. Меняется результат: статус перезагрузки приходит в виде JSON в том же HTTP-ответе.[3]

Вот и вся разница:

# старый
nginx -s reload
# exit 0. Сработало? Иди читай /var/log/nginx/error.log.

# новый
curl --unix-socket /tmp/nginx.sock -X PATCH http://localhost/1/control/config
# exit 0 И JSON-тело, которое говорит, прошла ли перезагрузка.

Скрипт деплоя, который запускает nginx -s reload, не может отличить удачную перезагрузку от неудачной без разбора лога. Скрипт, который шлёт PATCH в Control API, ветвится по ответу.

Посмотреть, что реально запущено

Перезагрузка - это заголовок, но остальные два эндпоинта и есть то, что делает API полезным в ежедневной работе. Это GET-запросы, так что они read-only и безопасны, пока течёт трафик:

curl --unix-socket /tmp/nginx.sock http://localhost/1/control/processes
curl --unix-socket /tmp/nginx.sock http://localhost/1/nginx

/1/control/processes возвращает информацию о воркерах - имя, PID, состояние выхода - без разбора ps. /1/nginx отдаёт версию и сборку, что удобно, когда ты на mainline и хочешь точно подтвердить, что у тебя запущено, прежде чем заводить баг или решать об апгрейде.[2]

А вот эндпоинт конфига - тот, вокруг которого реально стоит строить рабочий процесс. GET /1/control/config возвращает снимок загруженной конфигурации из памяти; PATCH запускает перезагрузку.[2] Так что API не только про изменение конфига - он ещё и про то, чтобы спросить у работающего процесса, что он на самом деле делает, что полезно, когда конфиг на диске и конфиг в памяти разошлись.

Что это меняет в вашем op-workflow

У старого цикла было две болячки: ошибки перезагрузки всплывали в лог-файле, а сопоставлять их приходилось с конкретным деплоем. Control API схлопывает обе в пару запрос/ответ.

Для машины, которую вы перезагружаете руками, выигрыш небольшой. Выигрыш - для всего, что перезагружает nginx программно. Три места, куда это встраивается:

  • Пайплайны деплоя. После git pull и изменения конфига вызовите Control API и валите шаг при не-успешном ответе вместо tail + grep по emerg.
  • Infrastructure-as-code и конфиг-менеджеры. Триггерите и проверяйте перезагрузку в одном шаге, а JSON-результат кладите в лог запуска.
  • Canary / тестовые конфиги. Закатите кандидат, перезагрузите, прочитайте вердикт и откатитесь при ошибке - без человека, следящего за лог-хвостом.

Две вещи, которые стоит держать в голове, прежде чем полагаться на это:

  • Это не замена nginx -t. Проверяйте кандидат конфиг до применения. Control API даёт чистый машиночитаемый сигнал о самой перезагрузке; он не отменяет необходимость тестировать.
  • Неудачная перезагрузка всё равно сохраняет последний рабочий конфиг. При ошибке конфига nginx проверяет синтаксис, затем откатывается и продолжает отдавать старую конфигурацию, логируя проблему, - та же внутренняя механика, что и у сигнальной перезагрузки.[6] Так что Control API - не зелёный свет заливать непроверенное; это более быстрый и ясный способ узнать, что оно упало.

И поскольку он неаутентифицированный, сокет - это ваша граница. Держите его root-овским, недоступным другим пользователям и никогда не биндьте на публичный порт.

Тот же релиз задел и роутинг

Control API - заголовок, но 1.31.5 привёз ещё три вещи, которые важны, если вы маршрутизируете трафик на прокси. Не тема этой статьи, но знать стоит:

  • Predicate locations - location теперь может принимать переменную, вычисляемую в момент запроса; он совпадает, когда переменная не пустая и не равна "0".[5] То есть location $is_ai_scraper { ... } маршрутизирует по чему-то другому, кроме пути URI.
  • Раннее чтение тела (client_body_early_read) - nginx может буферизовать и распарсить тело запроса до выбора location, так что роутинг может зависеть от полезной нагрузки, а не только от пути.[5]
  • Нативный парсинг JSON (ngx_http_json_module) - заполняйте переменные из JSON-документа, например json_set $method $request_body "method".[4] Это отдельный модуль, не собираемый по умолчанию; включите его через --with-http_json_module, а json_max_depth по умолчанию равен 32.[4]

Эти фичи работают в связке с Control API: если вы собираетесь перезагружать и маршрутизировать гибче, площадь конфига растёт, и перезагрузка, которая отвечает, - это эксплуатационная сторона этого процесса.

Перед апгрейдом

Если вы уже гоняете nginx как reverse proxy, изменение небольшое: проверьте кандидат конфиг, стартуйте nginx с сокетом и поменяйте шаг перезагрузки с nginx -s reload на PATCH по сокету. Остальной конфиг не меняется.

Ещё одно, что стоит сделать в любом случае: в этом релизе есть фикс memory-safety, связанный с proxy_buffering on по HTTP/2. При ошибке body filter и медленном клиенте прокси, буферизующий HTTP/2-ответы, мог отдать клиенту содержимое освобождённой heap-памяти. Если вы проксируете HTTP/2 с включённым буферингом - это повод быть на 1.31.5 независимо от Control API.[3]

Если вы ещё только поднимаете свой прокси - начните с полного конфига из нашего гайда по reverse proxy, а Control API добавьте как механизм перезагрузки, когда трафик уже идёт.

Короткая версия

Control API - это REST-поверхность в мастер-процессе nginx: три эндпоинта, включается через -l, перезагружается через PATCH. Его ценность не в более быстрой перезагрузке - а в синхронном машиночитаемом ответе на вопрос «применился ли конфиг?». Вместо перезагрузки и чтения error.log вы делаете один запрос и читаете JSON. Чтобы им пользоваться, нужен mainline 1.31.5+. Держите сокет вне сети и оставьте nginx -t в своём рабочем процессе.

Источники

  1. nginx news: 2026 - релиз nginx-1.31.5 mainline (control API, predicate locations, ngx_http_json_module), 2 сен 2026. https://nginx.org/2026.html - проверено 2026-09-27
  2. NGINX documentation - Control NGINX Processes at Runtime (эндпоинты Control API, включение через -l, соображения безопасности). https://docs.nginx.com/nginx/admin-guide/basic-functionality/runtime-control - проверено 2026-09-27
  3. NGINX Community Blog - NGINX 1.31.5: Control API, predicate locations, early body inspection, and more. https://blog.nginx.org/blog/nginx-1-31-5-control-api-predicate-locations-early-body-inspection-and-more - проверено 2026-09-27
  4. nginx - Module ngx_http_json_module (json_set, json_max_depth по умолчанию 32, --with-http_json_module). https://nginx.org/en/docs/http/ngx_http_json_module.html - проверено 2026-09-27
  5. nginx - Module ngx_http_core_module (location predicate, client_body_early_read, порядок совпадения). https://nginx.org/en/docs/http/ngx_http_core_module.html#location - проверено 2026-09-27
  6. nginx - Controlling nginx (сигналы; семантика перезагрузки по HUP; откат к старой конфигурации при ошибке). https://nginx.org/en/docs/control.html - проверено 2026-09-27
  7. nginx - download (ветка stable 1.30.x, mainline 1.31.x). https://nginx.org/en/download.html - проверено 2026-09-27