Панель управления сломала конфиг nginx: разбор конфликта

MAATRIX

Вчера всё работало, сегодня сайт не открывается — а вы точно помните, что не трогали конфиг руками. Или трогали, но давно, и с тех пор всё было в порядке. Первый подозреваемый в такой ситуации — панель управления хостингом: ISPmanager, HestiaCP, aaPanel и им подобные умеют молча переписать файлы конфигурации nginx поверх правок, сделанных напрямую через SSH. Это не баг панели и не случайность, а закономерный результат смешения двух способов управления одним и тем же файлом. Разберём, почему так происходит, как это диагностировать и как настроить сервер так, чтобы конфликт больше не повторялся.

Почему панель и ручные правки конфликтуют

Панель управления хостингом не редактирует конфиг nginx — она его генерирует заново. Внутри у неё лежит база (или набор файлов настроек) с параметрами каждого сайта: домен, корневая директория, версия PHP, включён ли SSL, redirect-правила из формы «Домены» и так далее. Когда вы через веб-интерфейс меняете хоть один параметр — например, переключаете версию PHP или добавляете алиас домена — панель берёт свой шаблон vhost-конфига, подставляет туда актуальные значения из базы и перезаписывает итоговый файл в /etc/nginx/... целиком. Не патчит построчно, а генерирует заново.

Если между двумя такими генерациями кто-то зашёл по SSH и дописал в этот же файл руками пару директив — client_max_body_size, кастомный location для проксирования API, proxy_read_timeout для долгих запросов — эти строки нигде не сохранены, кроме самого файла. Панель о них не знает: они не попали в её базу настроек. При следующей генерации панель перезапишет файл по своему шаблону, и ручные строки исчезнут, как будто их и не было.

Триггером для перегенерации бывает не только явное изменение через форму. Частые сценарии:

• обновление самой панели или пакета шаблонов nginx (у многих панелей это происходит по расписанию, автоматически, без запроса подтверждения);
• нажатие кнопки «Пересоздать конфигурацию сайта» или аналога после диагностики панелью какой-то другой проблемы;
• смена SSL-сертификата через встроенный Let's Encrypt в панели — это почти всегда приводит к перегенерации всего vhost-блока, а не только SSL-директив;
• восстановление сайта из бэкапа средствами панели.

Ключевая идея, которую стоит держать в голове: панель считает себя единственным источником правды для конфигурации. Всё, что не описано в её собственных настройках, для неё не существует и будет стёрто при первой же перегенерации.

Как обнаружить, что панель переписала конфиг

Первый шаг всегда одинаковый — проверка синтаксиса:

nginx -t

Здесь возможны два разных сценария, и важно не путать их.

Синтаксическая ошибка. Встречается реже, чем кажется: сгенерированные панелью шаблоны обычно валидны сами по себе. Но если панель попыталась «умно» сохранить часть ваших правок (некоторые современные панели пытаются это делать) и не до конца поняла синтаксис, результат может оказаться битым — nginx -t покажет unexpected "}" или unknown directive с конкретной строкой. Это самый простой случай: видно, где именно панель напортачила.

Конфиг синтаксически верный, но не тот. Гораздо более частый и коварный случай: nginx -t бодро рапортует syntax is ok и test is successful, nginx перезапускается без единой ошибки — а сайт всё равно ведёт себя не так, как настраивали вручную. Типичные симптомы такого «тихого» отката к шаблону:

• загрузка файлов стала падать с 413 Request Entity Too Large — значит, ваш client_max_body_size 50M заменился панельным значением по умолчанию (обычно 1M);
• долгие запросы к API рвутся по 504 Gateway Timeout — исчез кастомный proxy_read_timeout;
• перестал работать редирект или rewrite-правило для конкретного пути — панель не знала о вашем location, и его не стало;
• отвалились security-заголовки (X-Frame-Options, Content-Security-Policy), которые вы добавляли вручную;
• кеширование статики перестало работать — исчезли директивы expires и add_header Cache-Control, которые вы добавляли в блок для статики.

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

journalctl -u nginx --since "2 hours ago"

и проверить время изменения файла:

stat -c '%y %n' /etc/nginx/vhosts/example.com.conf

Если mtime файла свежее, чем ваша последняя SSH-сессия — конфиг точно менялся не руками, а через панель (её процесс, а не интерактивный шелл).

Диагностика: сравниваем текущий конфиг с тем, что было

Дальше нужно понять не только «что сломалось», а «что именно изменилось» — построчно.

Если конфиги под git. Это лучший вариант, и если вы уже практикуете деплой через git (см. статью про автодеплой из git), сравнение — дело одной команды:

git diff HEAD~5 -- /etc/nginx/vhosts/example.com.conf
git log -p --follow /etc/nginx/vhosts/example.com.conf

Вы сразу увидите, какие строки исчезли и в какой момент — по времени коммита можно сопоставить это с действием в панели.

Если git не настроен. Тогда ищем любые другие следы прежней версии:

• бэкапы файловой системы, если они настроены (borgbackup, restic или любой другой инструмент, который у вас работает на сервере) — ищите там снапшот /etc/nginx за нужную дату;
• собственные бэкап-файлы панели: многие панели перед перегенерацией сохраняют предыдущую версию файла рядом, с суффиксом вроде .conf.bak или .conf~ — стоит явно поискать:

  find /etc/nginx -name "*.bak" -o -name "*~" -mtime -7

• логи самой панели. У ISPmanager это обычно каталог /usr/local/mgr5/var/, у HestiaCP — /usr/local/hestia/log/, у aaPanel — /www/server/panel/logs/. В них можно найти запись о том, когда и по какой причине панель пересоздавала конфигурацию конкретного сайта;
• лог обновлений пакетов, если подозреваете автообновление самой панели или её nginx-шаблонов:

  grep -i nginx /var/log/apt/history.log
  # или для систем на dnf/yum
  grep -i nginx /var/log/dnf.rpm.log

Если старой версии конфига нигде не осталось, а помните только «что было настроено» — воссоздайте её по памяти и сразу зафиксируйте в git, чтобы в следующий раз сравнение заняло полминуты, а не полчаса археологии.

Где панели чаще всего затирают ручные правки

Три самых частых панели на VPS ведут себя по-разному, но логика одна и та же — «GUI = единственный источник, всё остальное будет стёрто»:

Если у вас другая панель (FastPanel, CyberPanel, CloudPanel) — принцип идентичен, отличается только название директории для «безопасных» дополнений. Первое, что стоит сделать при знакомстве с новой панелью — найти в её документации раздел про custom nginx directives или additional config, прежде чем один раз вручную отредактировать генерируемый файл.

Правильная практика: один способ управления конфигом

Правило простое и жёсткое: выбирайте один способ конфигурирования и не смешивайте его со вторым. Есть два рабочих варианта.

Вариант А — всё только через панель. Если у вас нет специфичных nginx-директив, которые панель не поддерживает через GUI, — не заходите в конфиги руками вообще. Даже «быстро поправить одну строчку и всё» — плохая идея: правка проживёт ровно до следующей перегенерации.

Вариант Б — используйте предусмотренный панелью include-механизм. Почти все панели знают, что пользователям иногда нужны кастомные директивы, и оставляют для этого отдельные файлы или директории, которые не пересоздаются автоматически:

# Пример для ISPmanager: /etc/nginx/vhosts-includes/example.com.conf
# Этот файл панель НЕ трогает при перегенерации основного vhost-конфига
client_max_body_size 50M;

location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_read_timeout 300s;
}

Для HestiaCP вместо правки /home/user/conf/web/domain/nginx.conf создаётся собственный шаблон:

cp /usr/local/hestia/data/templates/web/nginx/default.tpl \
   /usr/local/hestia/data/templates/web/nginx/mytemplate.tpl
# правим mytemplate.tpl
# затем в панели: Web → Edit Domain → Template → mytemplate

Это не быстрее, чем открыть vim и дописать строчку, зато переживёт следующее обновление панели. Разница в подходе окупается один раз — при первом же автообновлении шаблонов.

Что делать, если правки уже потеряны

Если конфиг уже переписан и нужно вернуть работоспособность прямо сейчас:

1. Восстановите утраченные директивы по результатам диагностики из предыдущих разделов — из git-истории, бэкапа или по памяти.
2. Добавьте их не напрямую в генерируемый файл, а через include-механизм своей панели (см. выше) — иначе через день-два история повторится.
3. Проверьте синтаксис и примените изменения без даунтайма:

   nginx -t && systemctl reload nginx

1. Явно проверьте симптом, из-за которого всё началось: сделайте тестовую загрузку файла, если чинили client_max_body_size, или тестовый долгий запрос, если дело было в таймауте.
2. Зафиксируйте текущее состояние в git (даже простой git init в /etc/nginx и один коммит — уже страховка на будущее):

   cd /etc/nginx && git init && git add -A && git commit -m "snapshot after incident"

Дальше остаётся только следить, что новые ручные правки идут исключительно в включаемый файл, а не в генерируемый — тогда следующее обновление панели пройдёт незаметно.

Частые вопросы