Установка Nginx Mainline на Debian 13, 12, 11: подробное руководство

Nginx Mainline — это основная ветка разработки официального репозитория nginx.org. Она содержит самые свежие функции, поддержку новых протоколов TLS и исправления, которые появляются раньше, чем в стандартных репозиториях Debian. Если вам нужен HTTP/3, современный TLS или новые возможности reverse-прокси, а версия из Debian слишком старая — Nginx Mainline то, что нужно.

💡 В этом руководстве мы добавим официальный репозиторий nginx.org, настроим APT-приоритет (pinning) выше, чем у Debian, установим Mainline-версию, настроим автозапуск и проверим работоспособность. Все команды одинаково работают на Debian 13, 12 и 11.

В этой статье вы узнаете:

• Как добавить официальный репозиторий nginx.org
• Как настроить APT pinning, чтобы приоритет был выше, чем у Debian
• Как установить Nginx Mainline
• Как управлять сервисом (запуск, перезагрузка, статус)
• Как обновлять Nginx через APT
• Как удалить Nginx Mainline и вернуться к стандартному пакету Debian
• Как решить типичные проблемы с пошаговыми инструкциями

Для кого: веб-разработчики, администраторы серверов, пользователи, которым нужны свежие версии Nginx, пользователи Debian 11, 12 и 13.

1. 🔧 Предварительные требования

Перед установкой убедитесь, что:

• У вас установлена Debian 11, 12 или 13 (любая редакция)
• Подключение к интернету стабильно
• Порт 80 (HTTP) и 443 (HTTPS) свободны (если вы планируете использовать веб-сервер)

⚠️ ВАЖНО: Проверьте права sudo перед установкой

Если вы не уверены, есть ли у вашего пользователя права администратора, выполните в терминале:

sudo whoami

✅ Если выводит root — всё в порядке, можете продолжать.

❌ Если выводит is not in the sudoers file — сначала пройдите наше руководство по настройке sudo

1.1 Обновление системы

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

sudo apt update && sudo apt upgrade -y

Что делает:

• sudo — права суперпользователя
• apt update — обновляет список доступных пакетов
• && — выполняет следующую команду только если предыдущая успешна
• apt upgrade -y — обновляет все установленные пакеты, -y автоматически подтверждает

Зачем: Это стандартная практика безопасности перед установкой нового ПО.

1.2 Установка вспомогательных пакетов

sudo apt install ca-certificates curl gpg -y

Что делает:

• ca-certificates — пакет с корневыми сертификатами для проверки HTTPS
• curl — утилита для скачивания файлов
• gpg — инструмент для работы с цифровыми подписями

Зачем: Эти пакеты нужны для безопасного добавления репозитория nginx.org. Без них команды скачивания ключа и настройки репозитория не сработают.

2. 📦 Установка Nginx Mainline

2.1 Импорт GPG-ключа nginx.org

curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

Что делает:

• curl -fsSL — скачивает GPG-ключ с официального сайта nginx.org
• | — передаёт скачанный ключ следующей команде
• sudo gpg --dearmor — преобразует ключ из текстового формата в бинарный (такой формат понимает APT)
• -o /usr/share/keyrings/nginx-archive-keyring.gpg — сохраняет ключ в стандартную директорию для сторонних ключей

Зачем: GPG-ключ нужен, чтобы APT мог проверить, что пакеты действительно от nginx.org, а не от кого-то постороннего.

2.2 Проверка GPG-ключа (чтобы убедиться, что он загрузился правильно)

gpg --dry-run --quiet --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg

Что делает: Показывает содержимое ключа, не импортируя его в связку ключей.

✅ Ожидаемый вывод в терминале:

pub   rsa4096 2024-05-29 [SC]
      8540A6F18833A80E9C1653A42FD21310B49F6B46
uid                      nginx signing key <signing-key-2@nginx.com>

pub   rsa2048 2011-08-19 [SC] [expires: 2027-05-24]
      573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
uid                      nginx signing key <signing-key@nginx.com>

Зачем: Если вы видите такой вывод — ключ загружен корректно. Если вывод пустой или содержит ошибку — ключ не загрузился, и нужно проверить интернет-соединение или повторить команду.

2.3 Создание конфигурации репозитория

CODENAME=$(. /etc/os-release && echo "$VERSION_CODENAME")
ARCH=$(dpkg --print-architecture)

printf '%s\n' \
'Types: deb' \
'URIs: https://nginx.org/packages/mainline/debian' \
"Suites: ${CODENAME}" \
'Components: nginx' \
"Architectures: ${ARCH}" \
'Signed-By: /usr/share/keyrings/nginx-archive-keyring.gpg' | sudo tee /etc/apt/sources.list.d/nginx.sources > /dev/null

Что делает:

• CODENAME= — определяет кодовое имя вашей версии Debian (trixie, bookworm или bullseye)
• ARCH= — определяет архитектуру процессора (amd64, arm64 и т.д.)
• printf ... | sudo tee — создаёт файл репозитория с автоматически подставленными значениями

Зачем: Файл репозитория говорит APT, откуда брать пакеты Nginx.

2.4 Обновление списка пакетов

sudo apt update

Что делает: Заставляет APT прочитать новые файлы репозиториев и получить список доступных пакетов.

✅ Ожидаемый вывод в терминале: Должны появиться строки с https://nginx.org/packages/mainline/debian. Если их нет — репозиторий не добавился.

2.5 Проверка Origin репозитория (перед настройкой приоритета)

grep -h '^Origin:' /var/lib/apt/lists/*nginx*_InRelease

Что делает: Ищет в скачанных метаданных репозитория строку Origin:.

✅ Ожидаемый вывод: Origin: nginx

Зачем: Это значение понадобится для настройки приоритета APT. Если вывод пустой — репозиторий не добавился или метаданные не скачались.

2.6 Настройка APT pinning (чтобы приоритет nginx.org был выше, чем у Debian)

printf '%s\n' 'Package: *' 'Pin: release o=nginx' 'Pin-Priority: 900' | sudo tee /etc/apt/preferences.d/99nginx > /dev/null

Что делает:

• Package: * — правило применяется ко всем пакетам
• Pin: release o=nginx — правило применяется к пакетам из репозитория с Origin nginx
• Pin-Priority: 900 — приоритет выше, чем у Debian (у Debian обычно 500)

Зачем: Без этого файла APT мог бы установить версию Nginx из Debian, а не Mainline. Приоритет 900 говорит APT: «сначала смотри в nginx.org».

2.7 Проверка, что APT выбирает nginx.org

apt-cache policy nginx

Что делает: Показывает, какая версия Nginx будет установлена по умолчанию (Candidate) и откуда она берётся.

✅ Ожидаемый вывод в терминале (Debian 13):

nginx:
  Installed: (none)
  Candidate: 1.29.6-1~trixie
  Version table:
     1.29.6-1~trixie 900
        900 https://nginx.org/packages/mainline/debian trixie/nginx amd64 Packages
     1.26.3-3+deb13u2 500
        500 http://security.debian.org/debian-security trixie-security/main amd64 Packages

Что важно: Цифра 900 рядом с версией из nginx.org означает, что APT выберет её. Цифра 500 — у версии из Debian. Если у вас версия из nginx.org имеет приоритет 500 или ниже — проверьте, правильно ли создан файл /etc/apt/preferences.d/99nginx.

2.8 Установка Nginx

sudo apt install nginx -y

Что делает: Устанавливает Nginx из репозитория nginx.org (благодаря pinning).

2.9 Проверка версии

sudo nginx -v

Что делает: Показывает установленную версию Nginx.

✅ Ожидаемый вывод в терминале:

nginx version: nginx/1.29.6

(Версия может отличаться — это актуальная версия Mainline на момент установки)

Важно: Команда nginx -v без sudo может не работать, потому что бинарный файл находится в /usr/sbin/nginx, который не всегда в PATH обычного пользователя.

2.10 Включение и запуск сервиса

sudo systemctl enable nginx
sudo systemctl start nginx

Что делает:

• enable — добавляет Nginx в автозагрузку (при каждом включении компьютера Nginx будет запускаться автоматически)
• start — запускает сервис сейчас, без перезагрузки

2.11 Проверка статуса сервиса

systemctl status nginx --no-pager

Что делает: Показывает текущий статус Nginx.

✅ Ожидаемый вывод: Active: active (running)

Если статус inactive (dead) или failed — перейдите к разделу 8 «Решение типичных проблем».

2.12 Проверка конфигурации

sudo nginx -t

Что делает: Проверяет конфигурационные файлы Nginx на синтаксические ошибки.

✅ Ожидаемый вывод:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Зачем: Всегда выполняйте эту команду перед перезагрузкой или перезапуском Nginx. Если в конфигурации ошибка, Nginx не запустится или перестанет работать.

2.13 Проверка HTTP-ответа

curl -I http://127.0.0.1

Что делает: Отправляет HTTP-запрос к локальному серверу и показывает только заголовки ответа.

✅ Ожидаемый вывод:

HTTP/1.1 200 OK
Server: nginx/1.29.6

Если ответа нет — перейдите к разделу 8 «Решение типичных проблем».

3. 📂 Структура каталогов Nginx из nginx.org

Пакеты из официального репозитория nginx.org используют другую структуру, чем пакеты Debian. Вот основные отличия:

Файл/каталог	Назначение	Примечание
/etc/nginx/nginx.conf	Главный конфигурационный файл	Основной файл настроек
/etc/nginx/conf.d/	Директория для сайтов (server blocks)	По умолчанию включает все *.conf
/usr/share/nginx/html/	Корневая директория по умолчанию	Здесь лежит приветственная страница
/var/log/nginx/access.log	Лог запросов	Каждый запрос к серверу пишется сюда
/var/log/nginx/error.log	Лог ошибок	Ошибки Nginx пишутся сюда

⚠️ Важно: В отличие от пакета Debian, здесь нет каталогов sites-available и sites-enabled. Все конфигурации сайтов складываются прямо в /etc/nginx/conf.d/.

Как добавить свой сайт:

1. Создайте файл /etc/nginx/conf.d/mysite.conf
2. Напишите в нём server block
3. Выполните sudo nginx -t для проверки
4. Выполните sudo systemctl reload nginx для применения

4. 📊 Сравнение версий Nginx

Источник	Версия (на март 2026)	Скорость обновлений	Для кого
nginx.org Mainline	1.29.6	Самая быстрая	Кому нужны новые функции (HTTP/3, новые протоколы)
nginx.org Stable	1.28.2	Медленнее Mainline	Кто хочет upstream- пакеты, но консервативнее
Debian 13 (стандартный)	1.26.3	Обновления безопасности	Стабильность, минимальные изменения
Debian 12 (стандартный)	1.22.1	Обновления безопасности	Стабильность, минимальные изменения
Debian 11 (стандартный)	1.18.0	Обновления безопасности	Стабильность, минимальные изменения

💡 Рекомендация: Если вам нужны новые функции и вы готовы к более частым обновлениям — выбирайте Mainline. Если хотите upstream-пакеты, но более консервативные — используйте Stable (замените mainline на packages в URL репозитория).

5. 🛠️ Управление Nginx

5.1 Проверка конфигурации (всегда делайте перед перезагрузкой!)

sudo nginx -t

Зачем: Если в конфигурации ошибка, Nginx не перезагрузится. Эта команда позволяет найти ошибку до того, как сервер перестанет работать.

5.2 Перезагрузка конфигурации (без потери соединений)

sudo systemctl reload nginx

Что делает: Применяет изменения конфигурации, не разрывая активные соединения.

Когда использовать: После изменения файлов в /etc/nginx/conf.d/ или /etc/nginx/nginx.conf.

5.3 Перезапуск сервиса

sudo systemctl restart nginx

Когда использовать: После обновления бинарного файла (например, после apt upgrade) или если reload не помог.

5.4 Остановка сервиса

sudo systemctl stop nginx

5.5 Просмотр статуса

systemctl status nginx

5.6 Просмотр логов в реальном времени

sudo tail -f /var/log/nginx/error.log

Что делает: Показывает новые строки лога ошибок по мере их появления. Нажмите Ctrl+C для выхода.

6. 🔄 Обновление Nginx

Поскольку мы настроили pinning, обновления будут приходить из репозитория nginx.org.

Обновить только Nginx:

sudo apt update
sudo apt install --only-upgrade nginx -y
sudo systemctl reload nginx

Обновить всё (включая Nginx):

sudo apt update && sudo apt upgrade -y

7. ❌ Удаление Nginx Mainline

7.1 Остановка и отключение сервиса

sudo systemctl stop nginx
sudo systemctl disable nginx

7.2 Удаление пакетов

sudo apt remove --purge nginx nginx-common -y
sudo apt autoremove -y

Что делает: Удаляет Nginx, его конфигурационные файлы и неиспользуемые зависимости.

7.3 Удаление репозитория и pinning

sudo rm -f /etc/apt/sources.list.d/nginx.sources
sudo rm -f /etc/apt/preferences.d/99nginx
sudo rm -f /usr/share/keyrings/nginx-archive-keyring.gpg
sudo apt update

7.4 Проверка, что пакет теперь из Debian

apt-cache policy nginx

✅ Ожидаемый вывод: Должны остаться только строки с deb.debian.org или security.debian.org. Строк с nginx.org быть не должно.

8. ⚠️ Решение типичных проблем (пошаговые инструкции)

8.1 Ошибка: nginx: command not found

Симптом: При выполнении nginx -v появляется bash: nginx: command not found.

Причина: Бинарный файл Nginx находится в /usr/sbin/nginx, который не всегда входит в PATH обычного пользователя. Это нормально, не ошибка установки.

Решение: Используйте sudo или полный путь:

sudo nginx -v

или

/usr/sbin/nginx -v

8.2 Ошибка: nginx.service is not active, cannot reload

Симптом: При попытке выполнить sudo systemctl reload nginx появляется сообщение:

nginx.service is not active, cannot reload.

Причина: Сервис Nginx не запущен. Это может быть из-за того, что он никогда не запускался, или запустился и упал с ошибкой.

Пошаговое решение:

Шаг 1: Проверьте статус сервиса:

systemctl status nginx

Шаг 2: Если статус inactive (dead) — попробуйте запустить:

sudo systemctl start nginx

Шаг 3: Если запуск не удался (статус failed), посмотрите логи:

sudo journalctl -u nginx -n 30 --no-pager

Ищите строки с error или emerg. Они подскажут причину (например, порт 80 уже занят или ошибка в конфигурации).

Шаг 4: Проверьте конфигурацию:

sudo nginx -t

Если конфигурация содержит ошибки — исправьте их и повторите шаг 2.

8.3 Ошибка: bind() to 0.0.0.0:80 failed (98: Address already in use)

Симптом: Nginx не может запуститься, а в логах (journalctl -u nginx) есть строка:

bind() to 0.0.0.0:80 failed (98: Address already in use)

Причина: Другой веб-сервер (Apache, другой экземпляр Nginx) или приложение уже слушает порт 80.

Пошаговое решение:

Шаг 1: Узнайте, какой процесс занимает порт 80:

sudo ss -ltnp | grep ':80 '

Пример вывода:

LISTEN 0      5            0.0.0.0:80        0.0.0.0:*    users:(("python3",pid=3925,fd=3))

В этом примере порт 80 занят процессом python3 с PID 3925.

Шаг 2: Определите, что это за процесс:

ps aux | grep 3925

Шаг 3: Варианты решения:

• Если это Apache, который вы не используете:

  sudo systemctl stop apache2
  sudo systemctl disable apache2

• Если это другой экземпляр Nginx (например, из Debian):

  sudo systemctl stop nginx
  # затем удалите старый пакет, если он конфликтует

• Если это ваше приложение (например, Python-сервер), и оно вам нужно: измените его порт в конфигурации на другой (например, 8080).

Шаг 4: После освобождения порта проверьте, что порт свободен:

sudo ss -ltnp | grep ':80 '

Вывод должен быть пустым.

Шаг 5: Запустите Nginx:

sudo systemctl start nginx

8.4 Ошибка: curl: (7) Failed to connect to 127.0.0.1 port 80

Симптом: curl -I http://127.0.0.1 не получает ответа, выводит:

curl: (7) Failed to connect to 127.0.0.1 port 80: Connection refused

Причина: Nginx не запущен или не слушает порт 80.

Пошаговое решение:

Шаг 1: Проверьте статус сервиса:

systemctl status nginx

Шаг 2: Если сервис не запущен, запустите:

sudo systemctl start nginx

Шаг 3: Если запуск не удался, посмотрите логи ошибок:

sudo journalctl -u nginx -n 30 --no-pager

Ищите строки с error или emerg.

Шаг 4: Проверьте конфигурацию:

sudo nginx -t

Если конфигурация содержит ошибки, исправьте их. Ошибки обычно указывают на конкретный файл и строку.

Шаг 5: Проверьте, что Nginx слушает порт 80 (после успешного запуска):

sudo ss -ltnp | grep ':80 '

В выводе должна быть строка с nginx.

8.5 Ошибка 403 Forbidden на приветственной странице

Симптом: curl -I http://127.0.0.1 возвращает 403 Forbidden.

Причина: Проблемы с правами доступа к директории /usr/share/nginx/html/. Nginx работает от пользователя www-data, и если у этого пользователя нет прав на чтение файлов или выполнение (переход) в директории, возникает 403.

Пошаговая диагностика и решение:

Шаг 1: Проверьте, какие права установлены на директорию и файлы:

ls -la /usr/share/nginx/html/

✅ Нормальный вывод должен выглядеть так:

total 12
drwxr-xr-x 2 root root 4096 ... .
drwxr-xr-x 3 root root 4096 ... ..
-rw-r--r-- 1 root root  896 ... index.html

Что означают права:

• drwxr-xr-x — директория (d), владелец (root) может читать/писать/переходить, группа и остальные — только читать и переходить.
• -rw-r--r-- — файл, владелец (root) может читать/писать, группа и остальные — только читать.

Шаг 2: Проверьте, от какого пользователя работает Nginx:

ps aux | grep nginx | grep worker

Вывод покажет строку с www-data. Это нормально.

Шаг 3: Если права отличаются от примера выше, исправьте их:

# Устанавливаем владельца root (владельцем должен быть root, не www-data)
sudo chown -R root:root /usr/share/nginx/html/

# Устанавливаем права на директории: 755 = rwxr-xr-x
sudo find /usr/share/nginx/html/ -type d -exec chmod 755 {} \;

# Устанавливаем права на файлы: 644 = rw-r--r--
sudo find /usr/share/nginx/html/ -type f -exec chmod 644 {} \;

Что делает каждая команда:

• chown -R root:root — меняет владельца и группу на root (рекурсивно, для всех файлов и поддиректорий)
• find -type d -exec chmod 755 {} \; — находит все поддиректории и даёт права 755 (владелец может всё, остальные — читать и переходить)
• find -type f -exec chmod 644 {} \; — находит все файлы и даёт права 644 (владелец может читать/писать, остальные — только читать)

Шаг 4: После исправления прав перезагрузите Nginx:

sudo systemctl reload nginx

Шаг 5: Снова проверьте страницу:

curl -I http://127.0.0.1

✅ Если всё исправлено, должен вернуться 200 OK.

8.6 APT не видит пакет из nginx.org (Candidate из Debian)

Симптом: apt-cache policy nginx показывает Candidate из Debian, а не из nginx.org.

Причина: APT pinning не настроен или настроен неправильно.

Пошаговое решение:

Шаг 1: Проверьте, что файл репозитория существует и содержит правильный URL:

cat /etc/apt/sources.list.d/nginx.sources

Должен быть вывод с URIs: https://nginx.org/packages/mainline/debian.

Шаг 2: Проверьте, что файл pinning существует:

cat /etc/apt/preferences.d/99nginx

Должен быть вывод:

Package: *
Pin: release o=nginx
Pin-Priority: 900

Шаг 3: Если файла нет — создайте его заново (см. шаг 2.6).

Шаг 4: Обновите список пакетов и проверьте снова:

sudo apt update
apt-cache policy nginx

9. 📝 Чек-лист: всё готово к работе

• [ ] Репозиторий nginx.org добавлен: cat /etc/apt/sources.list.d/nginx.sources показывает правильный URL
• [ ] APT pinning настроен: cat /etc/apt/preferences.d/99nginx показывает Pin-Priority: 900
• [ ] apt-cache policy nginx показывает версию из nginx.org с приоритетом 900
• [ ] Nginx установлен: sudo nginx -v показывает версию Mainline
• [ ] Сервис активен: systemctl status nginx показывает active (running)
• [ ] Приветственная страница открывается: curl -I http://127.0.0.1 возвращает 200 OK

Заключение

Вы успешно установили Nginx Mainline на Debian из официального репозитория nginx.org. Благодаря APT pinning, обновления будут приходить из nginx.org, а не из Debian. Это даёт доступ к самым свежим функциям и исправлениям. Старое ядро Debian осталось в системе — вы всегда можете удалить Nginx Mainline и вернуться к стандартному пакету.

Что дальше:

• Настройте виртуальные хосты (server blocks) в /etc/nginx/conf.d/
• Настройте SSL-сертификаты Let’s Encrypt
• Настройте reverse-proxy для ваших приложений
• Включите gzip-сжатие для ускорения загрузки страниц
• Защитите сервер с помощью Fail2Ban