Веб-стек / Ступень 2 из 9 · шаг 6 из 8

Настроить reverse proxy на nginx

~25 мин

Не запущена Запускается обычно ~20 с

Ситуация

На сервере работает бэкенд inventory-api. Он слушает только 127.0.0.1:3000, и с других машин к нему не попасть. Опубликовать его поручили через nginx, который уже стоит на сервере: запросы на порт 80 должны уходить на бэкенд, а клиенту — возвращаться его ответ.

Задача

Конфигурация nginx проходит nginx -t, служба nginx работает.
nginx принимает запросы на порту 80 на всех адресах машины.
Любой запрос к http://localhost/ nginx передаёт бэкенду и возвращает его ответ.

Интернета на машине нет, всё нужное уже установлено. Команды администратора запускай через sudo.

Цели лабы

0 из 4

Конфигурация nginx проходит проверку — ещё не проверялась
Служба nginx активна — ещё не проверялась
nginx слушает порт 80 на всех адресах машины — ещё не проверялась
На запросы к http://localhost/ отвечает бэкенд inventory-api — ещё не проверялась

Подсказки

открыто 0 из 3 · открываются по одной

Подсказка 1

Показать решение после 3 неудачных проверок

Для запуска машины нужен вход

Машина запускается на твой аккаунт, там же хранится прогресс. Читать можно без входа.

После входа вернёшься на эту лабу.

Службы и systemd · подобрано по лабе

nginx — веб-сервер и обратный прокси

Шпаргалка

$_ — вставить в терминал

sudo nginx -t проверить конфиг (только с sudo)
sudo systemctl reload nginx применить без обрыва соединений
sudo nginx -T | grep -n server_name какие сайты видит nginx
ls -l /etc/nginx/sites-enabled/ включённые сайты
curl -i -H 'Host: docs.lab.test' http://127.0.0.1/ кто ответит
sudo tail -n 5 /var/log/nginx/error.log почему 404, 403, 502
sudo tail -n 5 /var/log/nginx/access.log что спрашивали и код
sudo ss -tlnp | grep nginx на каких портах слушает

Раскладка Debian и Ubuntu:

/etc/nginx/nginx.conf — общие настройки, внизу include сайтов;
/etc/nginx/sites-available/ — файлы сайтов;
/etc/nginx/sites-enabled/ — ссылки на включённые сайты; nginx читает только их;
/var/log/nginx/access.log и error.log — журналы.

Включить сайт

bash

sudo ln -s /etc/nginx/sites-available/docs /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Файл в sites-available без ссылки в sites-enabled nginx не видит. Выключить сайт — удалить ссылку, файл остаётся.

nginx -t проверяет весь конфиг и называет файл и строку ошибки. reload перечитывает конфиг без обрыва соединений; с ошибкой в конфиге nginx оставляет старый. Команда systemctl reload возвращается сразу, а новые рабочие процессы берут соединения чуть позже: curl в той же строке может увидеть старое.

Журналы

access.log — строка на каждый запрос, error.log — почему запрос не удался и что сломалось при старте. Формат access.log по умолчанию — combined:

text

127.0.0.1 - - [20/Oct/2026:10:03:58 +0000] "POST / HTTP/1.1" 405 166 "-"

По полям: $remote_addr (адрес клиента), -, $remote_user, [$time_local], "$request" (метод, путь, версия), $status (код), $body_bytes_sent (размер тела), "$http_referer", "$http_user_agent" — в примере user-agent "curl/8.5.0" не поместился. Свой формат задаёт log_format — в файле сайта вне блока server:

nginx

log_format timed '$remote_addr [$time_local] "$request" '
                 '$status $body_bytes_sent $request_time';
access_log /var/log/nginx/app.log timed;

$request_time — сколько секунд nginx обрабатывал запрос. Файлы с .1 и .2.gz рядом с журналом — прошлые, их по расписанию отодвигает и сжимает logrotate (/etc/logrotate.d/nginx).

Прокси: путь и заголовки

Есть ли URI после адреса в proxy_pass, решает, какой путь получит приложение:

`location /api/` и `proxy_pass`	Запрос `/api/x` уходит как
`http://127.0.0.1:3003`	`/api/x` — путь без изменений
`http://127.0.0.1:3003/`	`/x` — `/api/` заменено на `/`

По умолчанию приложение видит Host: 127.0.0.1:3003 — адрес из proxy_pass. Имя сайта и адрес клиента передают заголовками:

nginx

proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

HTTPS и перенаправление с HTTP

nginx

server {
    listen 443 ssl;
    server_name shop.lab.test;
    ssl_certificate     /etc/nginx/tls/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/shop.key;
    root /var/www/shop;
}
server {
    listen 80;
    server_name shop.lab.test;
    return 301 https://$host$request_uri;
}

ssl_certificate — файл цепочки: сначала сертификат сайта, за ним промежуточный. $request_uri — путь вместе с запросом после ?: http://shop.lab.test/x?y=1 уводит на https://shop.lab.test/x?y=1. Сертификаты и их проверка — openssl-tls.

Кто ответит на имя

bash

curl -i -H 'Host: docs.lab.test' http://127.0.0.1/
sudo nginx -T | grep -n 'server_name\|listen'

Первая команда — ответ глазами клиента, вторая — какие listen и server_name nginx на самом деле прочитал, в порядке файлов.

Найти, где сломан прокси

bash

curl -s -o /dev/null -w '%{http_code}\n' http://app.lab.test/
sudo tail -n 1 /var/log/nginx/error.log
curl -i http://127.0.0.1:3000/        # приложение напрямую

Строка error.log называет upstream — куда nginx шёл. Приложение напрямую отвечает — дело в proxy_pass или правах; не отвечает — в приложении.

Отвечает чужой сайт

Host запроса не совпал ни с одним server_name — ответил сервер по умолчанию. Проверь имя в server_name и что ссылка на сайт есть в sites-enabled: sudo nginx -T | grep server_name.

404 Not Found

В error.log — путь, который собрал nginx: open() "/var/www/portal/nope.html" failed (2: No such file or directory). Сравни его с настоящим путём файла: обычно ошибка в root или alias.

403 Forbidden

(13: Permission denied) — www-data не может прочитать файл или войти в каталог по пути; права по всему пути покажет namei -l. directory index of "…" is forbidden — в каталоге нет файла из index.

502 Bad Gateway

nginx не открыл соединение с бэкендом. Причину называет строка error.log:

В error.log	Что значит
`(111: Connection refused)`	никто не слушает адрес или сокет
`(13: Permission denied)`	у `www-data` нет права на сокет
`(2: No such file or directory)`	нет файла сокета по этому пути

Полностью: connect() failed (111: Connection refused) while connecting to upstream, … upstream: "http://127.0.0.1:3001/". Для сокета — connect() to unix:/run/app/app.sock failed (13: Permission denied). Ошибки 13 и 2 nginx пишет с уровнем [crit], 111 — [error]: поиск только по [error] их пропустит. Сокет остался после остановки приложения — тоже 111. Права и пути сокетов — в статье unix-sockets.

504 Gateway Time-out

Соединение есть, ответа нет: upstream timed out (110: Connection timed out) while reading response header from upstream. Приложение зависло или отвечает дольше proxy_read_timeout (по умолчанию 60 с).

nginx -t: test failed

unexpected "}" in …:5 — в строке перед } нет ;;
a duplicate default server for 0.0.0.0:80 — default_server стоит в двух блоках одного порта;
open() "/run/nginx.pid" failed (13: Permission denied) — nginx -t запущен без sudo.

conflicting server name

[warn] conflicting server name "docs.lab.test" on 0.0.0.0:80, ignored — одно имя стоит в двух блоках одного порта. Проверку это не роняет, но запросы с этим именем получает блок, загруженный первым, а второй его не получает никогда. Найти оба:

bash

grep -n 'docs.lab.test' /etc/nginx/sites-enabled/*

grep -r по каталогу здесь не годится: ссылки в sites-enabled он пропускает.

key values mismatch

SSL_CTX_use_PrivateKey(…) failed (… key values mismatch) — первый сертификат в файле ssl_certificate не пара ключу. Либо ключ чужой, либо в файле цепочки первым стоит промежуточный сертификат. Сертификат сайта — первым.

Новый сертификат не виден

nginx читает сертификаты при старте и reload. Заменил файл — sudo nginx -t && sudo systemctl reload nginx, проверяй через секунду.

Служба не стартует: порт занят

sudo ss -tlnp | grep ':80 ' покажет, кто держит порт. Останови его или смени listen.

Новый listen не применился

Смена адреса на том же порту (listen 80 → listen 127.0.0.1:80) через reload не проходит: systemctl reload возвращает 0, nginx остаётся на старых сокетах, а в error.log — bind() to 127.0.0.1:80 failed (98: Address already in use). Такую правку применяет только sudo systemctl restart nginx; что слушается на самом деле — sudo ss -tlnp | grep nginx.

restart с ошибкой в конфиге

reload при ошибке оставляет работать старый конфиг, restart — останавливает nginx и не может запустить: все сайты на машине лежат. Перед любым применением — sudo nginx -t.