
رفع خطای وب سرور انجینکس (Nginx)؛ آموزش برطرف کردن خطاها
برای رفع خطای وب سرور انجینکس، باید مشخص کنیم مشکل از خود انجینکس (Nginx) است یا برنامه مقصد. این تشخیص مسیر رفع خطای Nginx را مشخص میکند؛ چون ارور Nginx همیشه از خود وبسرور نیست و خطای HTTP با کد ۵۰۲ معمولا به سرور بالادستی مربوط میشود، درحالیکه ۴۰۳ و ۴۰۴ علتهای دیگری دارند. در […]
رفع خطای وب سرور انجینکس (Nginx)؛ آموزش برطرف کردن خطاها
برای رفع خطای وب سرور انجینکس، باید مشخص کنیم مشکل از خود انجینکس (Nginx) است یا برنامه مقصد. این تشخیص مسیر رفع خطای Nginx را مشخص میکند؛ چون ارور Nginx همیشه از خود وبسرور نیست و خطای HTTP با کد ۵۰۲ معمولا به سرور بالادستی مربوط میشود، درحالیکه ۴۰۳ و ۴۰۴ علتهای دیگری دارند.
در ادامه این مطلب از مجله پارس هاست، روش تشخیص را بررسی میکنیم؛ با ما همراه باشید.
راهنمای سریع تشخیص خطاهای رایج Nginx
جدول زیر کدهای رایج Nginx، علتهای احتمالی و نخستین اقدام برای بررسی هرکدام را خلاصه میکند. این موارد سرنخاند؛ تشخیص نهایی به وضعیت سرویس و لاگها نیاز دارد.
| خطا | علت احتمالی | اولین اقدام برای رفع |
| ۵۰۲ Bad Gateway | اختلال در PHP-FPM یا Upstream | وضعیت سرویس و سوکت یا پورت را بررسی میکنیم |
| ۵۰۴ Gateway Timeout | تاخیر در پاسخ سرویس بالادستی | زمان پاسخ و لاگ برنامه را میسنجیم |
| ۴۰۳ Forbidden | مجوز دسترسی یا قانون محدودکننده | سطح دسترسی و قواعد deny را بررسی میکنیم |
| ۴۰۴ Not Found | مسیر فایل یا مسیریابی نادرست | root و try_files را کنترل میکنیم |
| ۵۰۰ Internal Server Error | خطای برنامه یا چرخه بازنویسی | لاگ همزمان و قواعد rewrite را میخوانیم |
| ۴۱۳ Request Entity Too Large | عبور حجم درخواست از سقف مجاز | client_max_body_size و محدودیت PHP را میسنجیم |
دلایل بروز خطا در وبسرور Nginx چیست؟
انجینایکس (Nginx) یک وبسرور است؛ گاهی فایلهای سایت را مستقیم به مرورگر میفرستد و گاهی در نقش پروکسی معکوس (Reverse Proxy)، درخواست را به برنامهای مثل Node.js، آپاچی یا PHP-FPM در سرور بالادستی میفرستد. بخشی از مشکلات وبسرور Nginx از همین ارتباط با برنامه مقصد ناشی میشود، نه از خود وبسرور. شناخت این مسیر، پایه رفع خطای وب سرور انجینکس است.
میزان استفاده از Nginx در وبسایتهای جهان نیز نشان میدهد که این فناوری تا چه اندازه رایج است. بر اساس آمار W3Techs در ۹ نوامبر ۲۰۲۶، Nginx در ۲۹.۹ درصد از وبسایتهایی استفاده میشود که وبسرورشان قابل شناسایی بوده است؛ در میان یک میلیون وبسایت برتر نیز سهم آن ۲۷.۱ درصد گزارش شده است با این حال بعضی از مواقع خطاهایی گریبان آن را خواهد گرفت که مهمترین کدهای خطای Nginx عبارتاند از:
- ۵۰۲: پاسخ سرویس بالادستی نامعتبر است یا ارتباط با آن قطع شده است.
- ۵۰۴: سرویس بالادستی در مهلت مقرر پاسخ نداده است.
- ۴۰۳: دسترسی به منبع درخواستشده مجاز نیست.
- ۴۰۴: فایل یا مسیر درخواستی پیدا نشده است.
- ۵۰۰: پردازش درخواست با خطای داخلی روبهرو شده است.
- ۴۱۳: حجم درخواست از سقف مجاز بیشتر است.
این کدها علت قطعی را نشان نمیدهند؛ برای تشخیص دقیقتر باید Error Log را هم بخوانیم که در ادامه به آن خواهیم پرداخت.
مراحل اولیه عیبیابی Nginx و رفع خطای وب سرور انجینکس
برای عیبیابی، وضعیت سرویس و تنظیمات Nginx را بررسی میکنیم. این روند در مستندات فنی با عنوان Nginx Troubleshooting شناخته میشود و کمک میکند محل احتمالی خطا را مرحلهبهمرحله محدود کنیم. پیش از ویرایش پیکربندی، نسخه پشتیبان میگیریم. فرمانهای این بخش برای توزیعهای لینوکسی مبتنی بر systemd هستند.
۱. بررسی وضعیت سرویس Nginx
دستور اول نشان میدهد Nginx فعال است یا نه. اگر سرویس متوقف باشد، دستور دوم جزئیات رخداد را در journal نشان میدهد؛ اگر فعال باشد اما سایت هنوز خطا بدهد، با دستور سوم بررسی میکنیم پورتهای ۸۰ و ۴۴۳ در اختیار چه فرایندی هستند.
sudo systemctl status nginx –no-pager
sudo journalctl -u nginx -n 60 –no-pager
sudo ss -ltnp | grep -E ‘:80|:443’

اگر فرایند دیگری پورت ۸۰ یا ۴۴۳ را اشغال کرده باشد، پیش از توقف آن وابستگیاش به سرویسهای دیگر را بررسی میکنیم؛ ممکن است سایت دیگری به آن وابسته باشد. برای شناخت معماری، مطلب «Nginx چیست» را ببینید.
۲. تست تنظیمات با nginx -t
پس از بررسی سرویس، پیکربندی را آزمایش میکنیم. یک سمیکالن جاافتاده یا مسیر اشتباه گواهی میتواند مانع اجرای Nginx شود. دستور زیر نحوه تنظیمات و دسترسی به فایلها را میسنجد، نه سلامت برنامه یا دیتابیس.
sudo nginx -t
sudo nginx -T | less
دستور دوم تنظیمات بارگذاریشده و فایلهای include را نمایش میدهد.

پس از اصلاح، nginx -t را اجرا کنید و در صورت موفقیت، reload بزنید:
sudo systemctl reload nginx

۳. بررسی لاگ Nginx؛ فایلهای Error Log و Access Log
وقتی وضعیت سرویس و تنظیمات، علت خطا را روشن نمیکنند، سراغ لاگها میرویم. Access Log زمان و نشانی درخواست را ثبت میکند؛ گزارش خطا (Error Log) یا همان Nginx Error Log جزئیات فنی پاسخ ناموفق را نشان میدهد و journal هم رخدادهای خود سرویس را ثبت میکند. سه دستور زیر این گزارشها را نمایش میدهند.
sudo tail -n 80 /var/log/nginx/error.log
sudo tail -n 80 /var/log/nginx/access.log
sudo journalctl -u nginx –since ’15 minutes ago’

پیامها را با زمان بروز خطا تطبیق میدهیم:
- «Connection refused» معمولا از سرویس خاموش یا پورت اشتباه خبر میدهد
- «Permission denied» به دسترسی و «upstream timed out» به تاخیر برنامه مقصد اشاره دارد.
رفع خطای ۵۰۲ Bad Gateway در Nginx
خطای ۵۰۲ یعنی Nginx از سرویس بالادستی پاسخ معتبر نگرفته است. پیش از تغییر زمان انتظار یا ریاستارت، این سه مورد را بررسی میکنیم:
- خاموش بودن PHP-FPM
- اشتباه بودن مسیر سوکت یا پورت
- قطع ارتباط با برنامه Upstream
در راهنمای پشتیبانی cPanel درباره خطای ۵۰۲ در ساختار Nginx و Apache آمده است:
“When using Nginx as a reverse proxy, this error indicates that an invalid response was passed between Nginx and Apache.” «هنگامی که Nginx در نقش پروکسی معکوس کار میکند، این خطا نشان میدهد که پاسخی نامعتبر میان Nginx و Apache ردوبدل شده است.»
این توضیح نشان میدهد که منشا خطای ۵۰۲ ممکن است ارتباط میان دو وبسرور باشد، نه فقط خود Nginx.
در سرورهایی که Nginx درخواستهای PHP را به PHP-FPM میفرستد، باید سرویس مقصد و مسیر اتصال آن را هم بررسی کنیم. خاموش بودن PHP-FPM یکی از علتهای احتمالی خطای ۵۰۲ است؛ افزایش زمان انتظار در این وضعیت کمکی نمیکند. ابتدا فعال بودن سرویس را میسنجیم و بعد اتصال Nginx به سوکت یا پورت درست را بررسی میکنیم. دستورهای زیر وضعیت سرویس، سوکت و پیامهای خطا را نشان میدهند.
sudo systemctl list-units ‘php*-fpm.service’ –all
sudo ss -lxnp | grep php
sudo tail -n 60 /var/log/nginx/error.log

فرمان اول نام سرویسهای PHP-FPM را نشان میدهد. سرویس مربوط به سایت را از همین فهرست پیدا میکنیم و وضعیتش را بررسی میکنیم؛ سپس مقدار fastcgi_pass را با سوکت یا پورتی که در خروجی ss دیده میشود تطبیق میدهیم. اگر از proxy_pass استفاده شده باشد، وضعیت برنامه مقصد و لاگ آن را بررسی میکنیم.
رفع خطای ۵۰۴ Gateway Timeout در Nginx
خطای ۵۰۴ زمانی رخ میدهد که سرویس بالادستی در مهلت تعیینشده پاسخ ندهد. کوئری سنگین دیتابیس، صف PHP-FPM، کندی API یا اختلال شبکه میتواند علت باشد؛ زمان اجرای درخواست را در لاگ بررسی کنید.
اگر برنامه سالم است اما یک عملیات مشخص طول میکشد، زمان انتظار را متناسب با آن تنظیم کنید. در ارتباط HTTP از proxy_read_timeout و در FastCGI از fastcgi_read_timeout استفاده میشود؛ این پارامترها زمان انتظار برای دریافت پاسخ را کنترل میکنند:
proxy_read_timeout 90s;
# برای مسیر PHP-FPM در بلوک مربوط:
fastcgi_read_timeout 90s;

این دو پارامتر برای مسیرهای متفاوتاند؛ فقط مورد متناسب را تغییر دهید. سپس تنظیمات را تست و reload کنید. اگر صف همچنان طولانی است، عملکرد برنامه یا ظرفیت منابع را بررسی کنید.
رفع خطای ۴۰۳ Forbidden در Nginx
خطای ۴۰۳ یعنی دسترسی به منبع مجاز نیست. نبود فایل index، مجوز نامناسب پوشه یا قانون deny از علتهای رایجاند؛ در معماری پروکسی، ممکن است برنامه مقصد خودش این پاسخ را بدهد.
sudo namei -l /var/www/example.com/index.html
sudo nginx -t

namei مجوز فایل و پوشههای والد را نشان میدهد؛ آن را با root مقایسه میکنیم. از chmod -R 777 استفاده نمیکنیم، چون دسترسی بیشازحد باز میکند. محدودیت IP و احراز هویت را هم میسنجیم.
رفع خطای ۴۰۴ Not Found در Nginx
خطای ۴۰۴ زمانی رخ میدهد که فایل یا مسیر درخواستشده پیدا نشود. مقدار root، نام فایل و بزرگی یا کوچکی حروف را بررسی میکنیم؛ برای مسیرهای پویا نیز try_files باید با ساختار برنامه هماهنگ باشد.
sudo nginx -T | grep -nE ‘server_name|root |try_files’
curl -I http://127.0.0.1/

curl پاسخ سرور محلی را نشان میدهد. اگر چند دامنه روی یک IP میزبانی میشوند، Host header دامنه موردنظر را هم میفرستیم تا Nginx سرور بلاک درست را انتخاب کند. تنظیم try_files وردپرس را بدون بررسی به Node.js تعمیم نمیدهیم.
رفع خطای ۵۰۰ Internal Server Error در Nginx
خطای ۵۰۰ از مشکلی داخلی خبر میدهد، اما بهتنهایی منشا آن را مشخص نمیکند. حلقه rewrite، خطای PHP یا خود برنامه میتواند علت باشد. لاگ Nginx و برنامه را در زمان وقوع خطا کنار هم بررسی میکنیم.
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx -n 50 –no-pager

پیام «rewrite or internal redirection cycle» به قواعد rewrite و try_files مربوط است. اگر خطا از PHP باشد، لاگ PHP-FPM را هم بررسی میکنیم؛ ریاستارت Nginx مشکل برنامه را حل نمیکند.
رفع خطای ۴۱۳ Request Entity Too Large در Nginx
اگر حجم درخواست از سقف Nginx بیشتر باشد، سرور خطای ۴۱۳ میدهد؛ این اتفاق معمولا هنگام آپلود فایل بزرگ رخ میدهد. پارامتر client_max_body_size سقف مجاز را تعیین میکند و مقدار پیشفرض آن ۱m است. مقدار جدید را بر اساس نیاز سایت انتخاب میکنیم.
client_max_body_size 20m;
دستور را در بلوک مناسب http، server یا location قرار میدهیم؛ سپس nginx -t را اجرا میکنیم و در صورت موفقیت reload میزنیم. در سایتهای PHP، مقدار upload_max_filesize و post_max_size را نیز هماهنگ میکنیم؛ Nginx این محدودیتها را تغییر نمیدهد.
رفع مشکل اجرا نشدن Nginx و خطاهای راهاندازی
گاهی خود Nginx اجرا نمیشود یا پس از تغییر تنظیمات بالا نمیآید. ابتدا nginx -t را بررسی میکنیم؛ پیام «address already in use» به اشغال پورت و «cannot load certificate» معمولا به مسیر یا مجوز فایل گواهی اشاره دارد.
sudo nginx -t
sudo systemctl status nginx –no-pager
sudo journalctl -xeu nginx –no-pager
sudo ss -ltnp | grep -E ‘:80|:443’

اگر nginx -t خطا داد، ابتدا آن را اصلاح میکنیم و تا موفق شدن آزمون، سرویس را reload یا restart نمیکنیم. برای اعمال تغییر روی سرویس فعال، معمولا reload کافی است؛ اگر سرویس متوقف باشد، پس از رفع خطا آن را راهاندازی و سایت را آزمایش میکنیم.
رفع مشکل اتصال Nginx به PHP-FPM و سرور Upstream
ممکن است Nginx فعال باشد اما درخواستهای PHP یا API خطا بدهند. در این حالت fastcgi_pass یا proxy_pass را با سوکت یا پورت برنامه مقصد تطبیق میدهیم. سوکت یونیکس باید برای وبسرور قابل دسترسی باشد و پورت TCP نیز در حال شنود باشد.
sudo nginx -T | grep -nE ‘fastcgi_pass|proxy_pass’
sudo ss -ltnp
sudo ss -lxnp | grep php

اگر برنامه روی localhost:3000 اجرا میشود، از همان سرور به آن درخواست میفرستیم و پاسخ مستقیم را با مسیر Nginx مقایسه میکنیم. اگر درخواست مستقیم موفق است اما دامنه خطا میدهد، Host header و تنظیمات proxy را بررسی میکنیم؛ در غیر این صورت لاگ برنامه را میخوانیم.
چگونه احتمال بازگشت خطاهای Nginx را کم کنیم؟
پس از رفع خطا، فقط صفحه اصلی را آزمایش نمیکنیم؛ ممکن است مسیرهای دیگر یا سرویسهای وابسته همچنان مشکل داشته باشند. این موارد را هم بررسی میکنیم:
- آزمایش دوباره نشانی خطادار
- بررسی فضای دیسک و حافظه
- پایش پاسخهای ۵xx و حجم لاگها
- کنترل سلامت PHP-FPM و برنامه اصلی
تاریخ، دلیل و نتیجه هر تغییر را ثبت میکنیم. اگر خطا برگردد، این یادداشتها کمک میکنند تغییر مشکلساز را سریعتر پیدا کنیم.
اگر کمبود CPU یا حافظه عامل تکرار خطاست، زیرساخت را هم ارزیابی میکنیم. «خرید سرور مجازی لینوکس» برای تیمی که مدیریت سیستم عامل و وبسرور را برعهده میگیرد، کنترل بیشتری فراهم میکند؛ اما فقط انتقال سرور مشکل را حل نمیکند.
آزمایش نهایی پس از رفع خطا
در پایان، نشانی خطادار را دوباره باز میکنیم و مسیرهای مهم سایت را میآزماییم. این آزمایشها مرحله پایانی رفع خطای وب سرور انجینکس هستند و مشخص میکنند که حل مشکل Nginx فقط به حذف پیام خطا محدود نمیشود؛ مسیرهای اصلی سایت هم باید درست پاسخ بدهند. ورود به پنل، باز شدن صفحه داخلی و ارسال فرم یا آپلود فایل را هم بررسی میکنیم. اگر خطا برگشت، زمان آن را با لاگ و آخرین تغییرات تطبیق میدهیم.
اگر سایت پرترافیکی دارید یا برای اجرای سرویسهایی مثل Nginx به منابع و دسترسی مدیریتی بیشتری نیاز دارید، انتخاب سرور مناسب اهمیت زیادی دارد.
سوالات متداول درباره رفع خطای وب سرور انجینکس
۱. آیا دستور nginx -t همه خطاهای سایت را پیدا میکند؟
خیر. nginx -t نحو تنظیمات و دسترسی به فایلها را بررسی میکند، اما خاموش بودن PHP-FPM، خطای دیتابیس یا مشکل برنامه را تشخیص نمیدهد. برای رفع ارور انجینکس باید این سرویسها و لاگهایشان را جداگانه بررسی کنید.
۲. برای خطای ۵۰۲ اول Nginx را ریاستارت کنیم؟
نه، نه پیش از بررسی علت. ابتدا لاگ Nginx و وضعیت سرویس بالادستی را بررسی میکنیم. اگر برنامه مقصد خاموش یا پورت و سوکت اشتباه باشد، ریاستارت Nginx مشکل را حل نمیکند.
۳. تفاوت خطاهای ۵۰۲ و ۵۰۴ چیست؟
در ۵۰۲ ارتباط با سرویس بالادستی قطع میشود یا پاسخ نامعتبر است؛ در ۵۰۴ پاسخ در مهلت تعیینشده نمیرسد. برای تشخیص دقیق، پیام Error Log را بررسی میکنیم.
۴. آیا تغییر client_max_body_size برای آپلود کافی است؟
خیر. client_max_body_size فقط محدودیت Nginx را تغییر میدهد. در سایتهای PHP، upload_max_filesize و post_max_size نیز باید با حجم فایل هماهنگ باشند؛ وگرنه PHP ممکن است درخواست را رد کند.
۰