Как отладить nginx ошибки
nginx errors — чаще всего config syntax (nginx -t catches), permissions (error.log), upstream issues (502/504). Debug steps: tail error.log, curl test из разных angles, strace на process. Top 5 errors: 502 Bad Gateway (upstream down), 504 Gateway Timeout (slow upstream), 403 Forbidden (permissions), 400 Bad Request (header size), worker process crashes.
Ниже: пошаговая инструкция, рабочие примеры, типичные ошибки, FAQ.
Пошаговая настройка
- Test config:
nginx -t— catches syntax errors before reload - Tail error.log:
tail -f /var/log/nginx/error.log - Check access log для request patterns:
tail -f /var/log/nginx/access.log - Increase log level:
error_log /var/log/nginx/error.log debug;в nginx.conf - Check upstream с curl напрямую:
curl -I http://127.0.0.1:3000/(skip nginx) - File permissions:
ls -la /var/www/site/— nginx user должен read - SELinux/AppArmor (RHEL/Ubuntu):
audit2allow -a,aa-status - Reload:
systemctl reload nginx(SIGHUP, no downtime)
Рабочие примеры
| Сценарий | Конфиг |
|---|---|
| Config test | nginx -t
# Ok:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
# Errors:
nginx: [emerg] unknown directive "incude" in /etc/nginx/nginx.conf:5 |
| 502 Bad Gateway debug | # error.log:
# 2026/04/18 upstream connect() failed (111: Connection refused) while connecting to upstream, client: 1.2.3.4, server: example.com, upstream: "http://127.0.0.1:3000/"
# Fix: app на 127.0.0.1:3000 down. Check:
systemctl status myapp
ss -tlnp | grep 3000 |
| 504 Gateway Timeout | # Increase timeouts
location /api/ {
proxy_pass http://backend;
proxy_read_timeout 60s; # default 60s
proxy_connect_timeout 10s;
proxy_send_timeout 60s;
} |
| 413 Entity Too Large | # nginx.conf http {
client_max_body_size 100m;
}
# За file uploads — increase. Default 1M слишком мало |
| Permission debug | sudo -u www-data cat /var/www/site/index.html # проверь если user доступ
ls -la /var/www/site/ # owner должен read
chown -R www-data:www-data /var/www/site
chmod -R 755 /var/www/site
find /var/www/site -type f -exec chmod 644 {} \; |
Типичные ошибки
- Reload без test — broken config crashes nginx. ALWAYS
nginx -tfirst - error.log not rotated — 10 GB file fills disk. Setup logrotate
- Location blocks order matters: exact match > prefix > regex. Check priority
- proxy_pass с и без trailing slash разные behaviour.
proxy_pass http://backend;(без /) vsproxy_pass http://backend/;(с /) - SELinux blocks access если file не labeled correctly.
chcon -R -t httpd_sys_content_t /var/www
Больше по теме
Часто задаваемые вопросы
Как enable debug logging только для одного IP?
<code>events { debug_connection 1.2.3.4; }</code> в nginx.conf — debug только для этого client.
Real IP через proxy?
Настройте <code>set_real_ip_from 10.0.0.0/8;</code> + <code>real_ip_header X-Forwarded-For;</code> — nginx покажет client IP instead of proxy.
Как проверить backend health из nginx?
<code>nginx_upstream_check_module</code> (патч для OSS nginx). Или plain passive health checks через <code>max_fails=3 fail_timeout=30s</code>.
Best tool для debug traffic?
<code>tcpdump</code> на server → capture traffic, analyze в Wireshark. Или DevTools Network tab для client-side.