Сборка NGINX из исходников на Debian 13, 12, 11: полное руководство

Стандартный пакет NGINX в Debian удобен, но иногда вам может понадобиться более свежая версия, поддержка HTTP/3, специфические модули или полный контроль над конфигурацией. В таких случаях единственный выход — собрать NGINX из исходников.

В этом руководстве я покажу, как собрать NGINX из исходного кода на Debian 13, 12 и 11 с поддержкой современных протоколов (HTTP/2, HTTP/3), модулей (image filter, stream) и правильной интеграцией с systemd.

⚠️ Важное примечание: Сборка из исходников даёт гибкость, но вы не будете получать автоматические обновления через APT. Для обновления нужно будет пересобирать NGINX вручную (в статье есть скрипт-помощник для этого).

---

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

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

• У вас есть доступ к интернету
• Вы имеете права sudo (администратора)
• На сервере остановлен и удалён стандартный пакет NGINX (если он был установлен), чтобы избежать конфликта портов

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

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

sudo whoami

Что делает: sudo — выполняет команду от имени суперпользователя; whoami — показывает имя текущего пользователя.

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

root

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

---

Установка зависимостей для сборки

Для Debian 13 (Trixie)

Debian 13 использует PCRE2 (более новую версию библиотеки регулярных выражений):

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential libpcre2-dev libssl-dev zlib1g-dev libgd-dev curl

Для Debian 12 (Bookworm) и Debian 11 (Bullseye)

Более старые версии Debian используют PCRE3 (классическую версию):

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential libpcre3-dev libssl-dev zlib1g-dev libgd-dev curl

Что делают эти пакеты:

• build-essential — компиляторы (gcc, make)
• libpcre2-dev / libpcre3-dev — библиотека регулярных выражений (нужна для модуля rewrite)
• libssl-dev — библиотеки для HTTPS и HTTP/2/3
• zlib1g-dev — библиотека сжатия gzip
• libgd-dev — библиотека для модуля image_filter (обработка изображений)
• curl — для скачивания исходников

---

Скачивание и распаковка исходного кода NGINX

Шаг 1: Создайте директорию для сборки

mkdir -p "$HOME/nginx-source"
cd "$HOME/nginx-source"

Шаг 2: Определите последнюю стабильную версию

NGINX_TARBALL="$(curl -fsSL https://nginx.org/en/download.html | tr '<' '\n' | sed -n '/h4>Stable version/,/\/table>/p' | grep -Eo 'nginx-[0-9]+\.[0-9]+\.[0-9]+\.tar\.gz' | head -n1)"
printf '%s\n' "$NGINX_TARBALL"

Что делает: Парсит страницу загрузки NGINX и извлекает имя последнего стабильного архива.

✅ Ожидаемый вывод: nginx-1.28.2.tar.gz (или новее).

Шаг 3: Скачайте и распакуйте архив

curl -fLO "https://nginx.org/download/$NGINX_TARBALL"
tar -xzf "$NGINX_TARBALL"
cd "${NGINX_TARBALL%.tar.gz}"

Шаг 4: Проверьте, что исходники готовы

test -f auto/configure && printf 'source tree ready: %s\n' "$PWD"

✅ Ожидаемый вывод: source tree ready: /home/your-user/nginx-source/nginx-1.28.2

---

Конфигурация сборки NGINX

Запустите скрипт ./configure с нужными флагами:

./configure \
  --prefix=/var/www/html \
  --sbin-path=/usr/sbin/nginx \
  --conf-path=/etc/nginx/nginx.conf \
  --http-log-path=/var/log/nginx/access.log \
  --error-log-path=/var/log/nginx/error.log \
  --with-pcre \
  --lock-path=/var/lock/nginx.lock \
  --pid-path=/var/run/nginx.pid \
  --with-http_ssl_module \
  --with-http_image_filter_module=dynamic \
  --modules-path=/etc/nginx/modules \
  --with-http_v2_module \
  --with-http_v3_module \
  --with-stream=dynamic \
  --with-http_addition_module \
  --with-http_mp4_module

Что означают флаги:

Флаг	Назначение
--prefix=/var/www/html	Корневая директория для файлов сайта
--sbin-path=/usr/sbin/nginx	Путь к исполняемому файлу NGINX
--conf-path=/etc/nginx/nginx.conf	Путь к основному конфигурационному файлу
--with-http_ssl_module	Поддержка HTTPS
--with-http_v2_module	Поддержка HTTP/2
--with-http_v3_module	Поддержка HTTP/3 (QUIC)
--with-http_image_filter_module=dynamic	Динамический модуль обработки изображений
--with-stream=dynamic	Динамический модуль для TCP/UDP проксирования

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

Configuration summary
  + using system PCRE2 library (или PCRE library)
  + using system OpenSSL library
  + using system zlib library

  nginx binary file: "/usr/sbin/nginx"
  nginx configuration file: "/etc/nginx/nginx.conf"
  ...

---

Компиляция и установка

make -j"$(nproc)"
sudo make install

Что делает:

• make -j"$(nproc)" — компиляция с использованием всех ядер процессора (ускоряет сборку)
• sudo make install — установка файлов в систему

Проверьте, что бинарный файл установлен:

/usr/sbin/nginx -v

✅ Ожидаемый вывод: nginx version: nginx/1.28.2

---

Настройка конфигурации NGINX для Debian

Стандартная конфигурация из исходников не очень удобна. Заменим её на более привычную для Debian (с поддержкой conf.d и правильными временными директориями).

Шаг 1: Создайте необходимые директории

sudo install -d -m 0755 /etc/nginx/conf.d /var/cache/nginx /var/log/nginx /var/www/html

Шаг 2: Создайте основной конфигурационный файл /etc/nginx/nginx.conf

sudo tee /etc/nginx/nginx.conf > /dev/null <<'EOF'
user www-data;
worker_processes auto;

error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    sendfile on;
    tcp_nopush on;
    keepalive_timeout 65;
    server_tokens off;

    client_body_temp_path /var/cache/nginx/client_temp;
    proxy_temp_path /var/cache/nginx/proxy_temp;
    fastcgi_temp_path /var/cache/nginx/fastcgi_temp;
    uwsgi_temp_path /var/cache/nginx/uwsgi_temp;
    scgi_temp_path /var/cache/nginx/scgi_temp;

    include /etc/nginx/conf.d/*.conf;
}
EOF

Шаг 3: Создайте тестовый виртуальный хост

sudo tee /etc/nginx/conf.d/default.conf > /dev/null <<'EOF'
server {
    listen 80;
    listen [::]:80;
    server_name _;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
EOF

Шаг 4: Создайте тестовую страницу

printf '%s\n' '<!doctype html><html><body><h1>NGINX source build on Debian</h1></body></html>' | sudo tee /var/www/html/index.html > /dev/null

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

sudo /usr/sbin/nginx -t

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

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

---

Создание systemd-сервиса (для автозапуска)

printf '%s\n' \
  '[Unit]' \
  'Description=The NGINX HTTP and reverse proxy server' \
  'After=syslog.target network-online.target remote-fs.target nss-lookup.target' \
  'Wants=network-online.target' \
  '' \
  '[Service]' \
  'Type=forking' \
  'PIDFile=/var/run/nginx.pid' \
  'ExecStartPre=/usr/sbin/nginx -t' \
  'ExecStart=/usr/sbin/nginx' \
  'ExecReload=/usr/sbin/nginx -s reload' \
  'ExecStop=/bin/kill -s QUIT $MAINPID' \
  'PrivateTmp=true' \
  '' \
  '[Install]' \
  'WantedBy=multi-user.target' | sudo tee /etc/systemd/system/nginx.service > /dev/null

sudo systemctl daemon-reload

---

Запуск NGINX

sudo systemctl enable nginx
sudo systemctl start nginx

Проверьте статус:

systemctl status nginx --no-pager

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

Проверьте, что страница отдаётся:

curl -I http://127.0.0.1

✅ Ожидаемый вывод: HTTP/1.1 200 OK

---

Скрипт для обновления NGINX (помощник)

Так как исходная сборка не обновляется через APT, я подготовил скрипт, который автоматически скачивает последнюю стабильную версию и пересобирает NGINX.

Установите скрипт:

sudo install -m 0755 /dev/stdin /usr/local/bin/update-nginx-source <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

BUILD_DIR="/usr/local/src/nginx-build"
DOWNLOAD_PAGE="https://nginx.org/en/download.html"
BASE_URL="https://nginx.org/download"

CURRENT_VERSION="$([ -x /usr/sbin/nginx ] && /usr/sbin/nginx -v 2>&1 | sed 's#.*nginx/##' || true)"
TARBALL="$(curl -fsSL "$DOWNLOAD_PAGE" | tr '<' '\n' | sed -n '/h4>Stable version/,/\/table>/p' | grep -Eo 'nginx-[0-9]+\.[0-9]+\.[0-9]+\.tar\.gz' | head -n1)"
TARGET_VERSION="$(printf '%s\n' "$TARBALL" | sed 's/^nginx-//; s/\.tar\.gz$//')"

if [ -z "$TARBALL" ] || [ -z "$TARGET_VERSION" ]; then
  echo "Could not determine the current stable NGINX tarball." >&2
  exit 1
fi

if [ -n "$CURRENT_VERSION" ] && [ "$CURRENT_VERSION" = "$TARGET_VERSION" ]; then
  echo "NGINX is already at the current stable release: $CURRENT_VERSION"
  exit 0
fi

echo "Preparing build directory: $BUILD_DIR"
sudo install -d -m 0755 "$BUILD_DIR"
cd "$BUILD_DIR"
sudo rm -rf "nginx-$TARGET_VERSION" "$TARBALL"

echo "Downloading $TARBALL"
sudo curl -fLO "$BASE_URL/$TARBALL"
sudo tar -xzf "$TARBALL"
cd "nginx-$TARGET_VERSION"

echo "Configuring NGINX $TARGET_VERSION"
sudo ./configure \
  --prefix=/var/www/html \
  --sbin-path=/usr/sbin/nginx \
  --conf-path=/etc/nginx/nginx.conf \
  --http-log-path=/var/log/nginx/access.log \
  --error-log-path=/var/log/nginx/error.log \
  --with-pcre \
  --lock-path=/var/lock/nginx.lock \
  --pid-path=/var/run/nginx.pid \
  --with-http_ssl_module \
  --with-http_image_filter_module=dynamic \
  --modules-path=/etc/nginx/modules \
  --with-http_v2_module \
  --with-http_v3_module \
  --with-stream=dynamic \
  --with-http_addition_module \
  --with-http_mp4_module

echo "Compiling NGINX $TARGET_VERSION"
sudo make -j"$(nproc)"

echo "Stopping nginx"
sudo systemctl stop nginx

echo "Installing NGINX $TARGET_VERSION"
sudo make install

echo "Starting nginx"
sudo systemctl start nginx

echo "Update complete"
/usr/sbin/nginx -v
EOF

Запуск обновления:

sudo update-nginx-source

---

Решение типичных проблем

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

Симптом: После установки команда nginx -v не работает.

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

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

Используйте полный путь:

/usr/sbin/nginx -v

или запускайте с sudo:

sudo nginx -v

---

8.2 Ошибка: Port 80 already in use

Симптом: NGINX не запускается, systemctl status nginx показывает ошибку:

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

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

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

Шаг 1: Определите, какой процесс занял порт:

sudo ss -tlnp | grep ':80'

Пример вывода: users:(("apache2",pid=1234,fd=4))

Шаг 2: Остановите конфликтующий сервис:

sudo systemctl stop apache2
sudo systemctl disable apache2

Шаг 3: Запустите NGINX:

sudo systemctl start nginx

---

8.3 Ошибка: HTTP/3 не работает (OpenSSL QUIC support not found)

Симптом: В процессе ./configure появляется сообщение checking for OpenSSL QUIC support ... not found.

Причина: HTTP/3 требует OpenSSL 3.5.1+ — это есть только в Debian 13. На Debian 12 и 11 будет использоваться встроенная совместимость NGINX (базовый HTTP/3 без 0-RTT).

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

Это не ошибка. На Debian 12/11 HTTP/3 будет работать в ограниченном режиме. Если вам нужен полный HTTP/3 на Debian 12, придётся собирать NGINX с BoringSSL или QuicTLS — это выходит за рамки данного руководства.

---

8.4 Ошибка: Много «not found» в выводе configure

Симптом: В выводе ./configure много строк вида:

checking for kqueue ... not found
checking for crypt() ... not found
checking for SO_ACCEPTFILTER ... not found

Причина: Это нормальное поведение. NGINX проверяет функции, специфичные для разных ОС (BSD, macOS, Solaris). На Linux они отсутствуют, но это не мешает сборке.

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

Ничего не делайте. Это не ошибка, а информационные сообщения.
Основные проверки (epoll, sendfile, timerfd) завершатся успешно, и сборка продолжится.

Примечание: Почему crypt() отмечен как «not found» и безопасно ли это?

Строка checking for crypt() ... not found означает, что скрипт configure не нашёл функцию crypt() в стандартной библиотеке C. Она используется модулем ngx_http_auth_basic_module для хэширования паролей
(например, при базовой HTTP-аутентификации).

Почему это происходит:
На некоторых системах (включая Debian/Ubuntu с GLibC) функция crypt() находится не в libc, а в отдельной библиотеке libcrypt.
Поскольку ./configure проверяет только libc, он выдаёт «not found», даже если функция технически доступна через -lcrypt.

Влияет ли это на работу NGINX?
❌ Нет. При фактической сборке NGINX используется auto/libcrypt/conf, которая правильно обнаруживает libcrypt и подключает её к линковке. Модуль auth_basic будет работать без каких-либо проблем. Это «ложное срабатывание» диагностики, которое не влияет на финальный бинарный файл.

---

8.5 Ошибка: Unit nginx.service could not be found

Симптом: systemctl status nginx говорит, что сервис не найден.

Причина: Вы не создали systemd-юнит или не перезагрузили systemd после его создания.

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

Шаг 1: Убедитесь, что файл юнита существует:

ls -la /etc/systemd/system/nginx.service

Шаг 2: Если файла нет — создайте его (см. раздел «Создание systemd-сервиса»).

Шаг 3: Перезагрузите systemd и запустите сервис:

sudo systemctl daemon-reload
sudo systemctl enable nginx
sudo systemctl start nginx

---

Чек-лист: что проверить после установки

• [ ] NGINX собран и установлен: /usr/sbin/nginx -v показывает версию
• [ ] Конфигурация корректна: sudo /usr/sbin/nginx -t → syntax is ok
• [ ] systemd-сервис создан: systemctl status nginx → Active: active (running)
• [ ] Порт 80 слушается: sudo ss -tlnp | grep ':80' показывает nginx
• [ ] Тестовая страница открывается: curl -I http://127.0.0.1 → 200 OK
• [ ] Скрипт обновления установлен: command -v update-nginx-source

---

Удаление собранного NGINX

Шаг 1: Остановите и отключите сервис

sudo systemctl stop nginx
sudo systemctl disable nginx

Шаг 2: Удалите systemd-юнит

sudo rm -f /etc/systemd/system/nginx.service
sudo systemctl daemon-reload

Шаг 3: Удалите бинарные файлы и конфигурацию

sudo rm -f /usr/sbin/nginx
sudo rm -rf /etc/nginx
sudo rm -rf /var/log/nginx
sudo rm -rf /var/cache/nginx

Шаг 4: Удалите исходники (опционально)

sudo rm -rf "$HOME/nginx-source"
sudo rm -rf /usr/local/src/nginx-build

Шаг 5: Проверьте удаление

test ! -x /usr/sbin/nginx && echo "nginx binary removed"
test ! -e /etc/systemd/system/nginx.service && echo "systemd unit removed"

---

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

Вопрос: Зачем собирать NGINX из исходников, если есть готовый пакет?
Ответ: Когда вам нужна поддержка HTTP/3, специфические модули или более свежая версия, чем в репозиториях Debian.

Вопрос: Нужно ли удалять стандартный пакет NGINX перед сборкой?
Ответ: Да, иначе будет конфликт портов и systemd-юнитов.

Вопрос: Как обновлять NGINX после сборки?
Ответ: Используйте скрипт update-nginx-source (создан в разделе «Скрипт для обновления»).

Вопрос: Будут ли работать динамические модули (например, --with-http_image_filter_module=dynamic)?
Ответ: Да, они собираются как .so файлы и устанавливаются в /etc/nginx/modules/.

Вопрос: Почему в выводе ./configure так много «not found»?
Ответ: Это нормально — скрипт проверяет функции, специфичные для других ОС. На Linux они отсутствуют, но это не мешает сборке.

---

Заключение

Теперь NGINX собран из исходников и работает на вашем Debian с поддержкой HTTP/2, HTTP/3, динамических модулей и корректной интеграцией с systemd.

Что дальше?

• Настройте виртуальные хосты в /etc/nginx/conf.d/
• Защитите NGINX с помощью Let’s Encrypt
• Настройте балансировку нагрузки