اگر NGINX خطای 502 Bad Gateway میدهد، قبل از زیادکردن timeout یا Restartهای پشتسرهم مشخص کنید NGINX دقیقاً در ارتباط با upstream چه خطایی دیده است. در عمل، 502 معمولاً از یکی از این مسیرها میآید: سرویس Backend روی IP/Port مورد انتظار Listen نمیکند، مسیر proxy_pass یا Unix Socket اشتباه است، Permission سوکت اجازه اتصال به Workerهای NGINX را نمیدهد، Backend قبل از ارسال Header اتصال را میبندد، یا NGINX به آدرس/پروتکل اشتباه وصل میشود. مسیر امن عیبیابی این است: error.log → تست مستقیم upstream → بررسی listen/socket → تطبیق proxy_pass → تست config → reload → Verify.
سناریوی واقعی
فرض کنید دامنه از NGINX روی پورت 443 پاسخ میدهد و درخواستها به یک اپلیکیشن روی 127.0.0.1:8000 یا PHP-FPM Unix Socket فرستاده میشوند. کاربر در مرورگر 502 میبیند، اما خود NGINX بالا است. هدف این مقاله این نیست که 502 را با یک Restart موقت پنهان کنیم؛ میخواهیم بفهمیم کدام hop شکسته است.
۱. قبل از تغییر، کانفیگ و وضعیت فعلی را ذخیره کنید
sudo nginx -T > /root/nginx-before-502.txt
sudo nginx -t
sudo systemctl status nginx --no-pager
اگر nginx -t همین حالا Fail است، اول Syntax/Include/Certificate مشکلدار را اصلاح کنید. برای آشنایی با ساختار پایه وبسرور میتوانید راهنمای نصب و کانفیگ NGINX روی Ubuntu را هم ببینید.
۲. مهمترین سرنخ را از error.log بگیرید
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx -n 100 --no-pager
به عبارتهایی مثل اینها دقت کنید:
connect() failed (111: Connection refused) while connecting to upstream: معمولاً Backend روی آن IP/Port Listen نیست یا آدرس اشتباه است.No such file or directory: مسیر Unix Socket وجود ندارد یا بعد از تغییر نسخه PHP عوض شده است.Permission denied while connecting to upstream: مالکیت/Permission یا سیاست امنیتی سیستم مانع دسترسی به Socket شده است.upstream prematurely closed connection: Backend اتصال را قبل از پاسخ کامل بسته؛ Crash، Limit، timeout داخلی برنامه یا خطای Worker را بررسی کنید.upstream timed out: این پیام را با 504 اشتباه نگیرید؛ ابتدا مشخص کنید timeout در مرحله connect/read/send رخ داده و چرا Backend کند یا غیرقابل دسترس است.
۳. upstream را بدون NGINX مستقیم تست کنید
اگر Backend روی TCP است:
sudo ss -lntp
curl -v http://127.0.0.1:8000/
اگر سرویس با systemd مدیریت میشود:
sudo systemctl status myapp --no-pager
sudo journalctl -u myapp -n 100 --no-pager
اگر curl مستقیم هم Fail است، مشکل اصلی NGINX نیست. ابتدا خود اپلیکیشن، Worker، Port یا Dependencyهای آن را رفع کنید. اگر Backend شما PHP-FPM است و کندی/Crash Workerها محتمل است، مقاله عیبیابی PHP-FPM با Slow Log مسیر تکمیلی خوبی است.
۴. proxy_pass را با Listen واقعی تطبیق دهید
کانفیگ مؤثر را پیدا کنید:
sudo nginx -T | grep -nE 'proxy_pass|fastcgi_pass|upstream'
نمونه Reverse Proxy روی TCP:
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
اگر Backend روی HTTPS است ولی در proxy_pass از http:// استفاده شده یا برعکس، اتصال میتواند شکست بخورد. Scheme، Host و Port را با Listener واقعی Backend تطبیق دهید.
۵. اگر PHP-FPM دارید، Unix Socket را بررسی کنید
مسیرهای رایج را ببینید:
sudo find /run -maxdepth 3 -type s -name '*php*fpm*.sock' -o -name 'php*.sock'
sudo ss -xl | grep -E 'php|fpm'
سپس مقدار fastcgi_pass را با Socket واقعی تطبیق دهید. نمونه:
fastcgi_pass unix:/run/php/php8.4-fpm.sock;
نسخه PHP را حدس نزنید. بعد از Upgrade ممکن است NGINX هنوز به Socket نسخه قبلی اشاره کند.
۶. Permission سوکت را بدون chmod 777 اصلاح کنید
namei -l /run/php/php8.4-fpm.sock
ls -l /run/php/php8.4-fpm.sock
ps -eo user,group,comm | grep nginx
مالکیت و گروه Socket را در Pool مربوط به PHP-FPM بررسی کنید و دسترسی NGINX را اصولی تنظیم کنید. استفاده از chmod 777 روی Socket راهحل امنی نیست. بعد از تغییر تنظیمات Pool:
sudo php-fpm8.4 -t
sudo systemctl reload php8.4-fpm
نام سرویس و Binary را با نسخه نصبشده خودتان جایگزین کنید.
۷. Timeout را فقط وقتی افزایش دهید که علت کندی را میدانید
NGINX برای اتصال و خواندن از upstream Directiveهای جدا دارد. نمونه:
location /api/ {
proxy_pass http://127.0.0.1:8000;
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
proxy_send_timeout 60s;
}
زیادکردن کورکورانه timeout ممکن است فقط صف درخواستها را طولانیتر کند. اگر Backend واقعاً زمان پردازش بالایی دارد، همزمان CPU/RAM، Workerها، DB و Log برنامه را بررسی کنید. برای خطاهای ناشی از محدودیت درخواست هم مقاله رفع خطای 413 در NGINX و PHP را با 502 اشتباه نگیرید؛ 413 مشکل اندازه Request است، نه ارتباط با upstream.
۸. اگر upstream group دارید، همه Backendها را جدا تست کنید
upstream app_backend {
server 127.0.0.1:8001;
server 127.0.0.1:8002;
}
هر Backend را مستقیم تست کنید:
curl -v http://127.0.0.1:8001/health
curl -v http://127.0.0.1:8002/health
یک Node خراب میتواند باعث شود خطا فقط روی بخشی از درخواستها دیده شود. Log را با Timestamp درخواست مقایسه کنید تا Backend مشکلدار مشخص شود.
۹. بعد از اصلاح، config را تست و فقط Reload کنید
sudo nginx -t && sudo systemctl reload nginx
تا وقتی نیاز واقعی ندارید از Restart استفاده نکنید؛ Reload کانفیگ معتبر را با اختلال کمتر اعمال میکند. سپس:
curl -I https://example.com/
curl -sS -o /dev/null -w '%{http_code} %{time_connect} %{time_starttransfer}n' https://example.com/
sudo tail -f /var/log/nginx/error.log
انتظار دارید Status دیگر 502 نباشد و در Log خطای upstream تکرار نشود.
۱۰. اگر مشکل فقط زیر Load رخ میدهد
در این حالت فقط «پورت باز است» کافی نیست. تعداد Workerهای Backend، Queue، File Descriptor، Memory و Restartهای سرویس را بررسی کنید:
systemctl --failed
journalctl -p warning..alert --since '-30 min'
ss -s
free -h
اگر در Log به محدودیت File Descriptor رسیدید، راهنمای رفع خطای Too many open files در لینوکس را دنبال کنید. اگر برای تست یا اجرای Backend به ماشین مجازی مستقل نیاز دارید، سرور مجازی وانسرور مقصد مرتبط این سناریو است.
Rollback امن
اگر تغییر جدید باعث بدترشدن وضعیت شد، فایل کانفیگ قبلی را از Backup برگردانید، سپس حتماً قبل از Reload تست کنید:
sudo nginx -t
sudo systemctl reload nginx
اگر مشکل از تغییر Port/Socket Backend بود، ابتدا سرویس را به Listener قبلی برگردانید و با curl یا ss Verify کنید. از حذف گروهی فایلهای کانفیگ، Reset کامل NGINX یا تغییر Permissionهای گسترده برای «امتحان کردن» خودداری کنید.
چکلیست نهایی Verify
nginx -tموفق است.- Backend روی IP/Port یا Socket مورد انتظار Listen میکند.
- تست مستقیم upstream پاسخ سالم میدهد.
proxy_passیاfastcgi_passبا Listener واقعی یکسان است.- NGINX به Unix Socket دسترسی لازم دارد.
- بعد از Reload، درخواست بیرونی دیگر 502 نمیدهد.
- error.log در تستهای جدید خطای upstream تکراری ندارد.