رفع خطای 502 Bad Gateway در Nginx و PHP-FPM لاراول

event 27 آبان 1405
update به‌روزرسانی: 25 آبان 1405
timer 11 دقیقه
کاور مقاله‌ی رفع خطای 502 در لاراول: مسیر اتصال Nginx به PHP-FPM که یه وصله‌ی قطع‌شده‌ی قرمز و نشان 502 روشه
favorite 0

خطای 502 Bad Gateway یعنی Nginx نتونست به PHP-FPM وصل بشه یا ازش جواب معتبر نگرفت؛ این خطا رو Nginx تولید می‌کنه، نه لاراول. برای همین اگه 502 می‌بینی و storage/logs/laravel.log خالیه، یعنی درخواست اصلاً به PHP نرسیده و باید لاگ خطای Nginx رو بخونی. قبل از هر systemctl restart بی‌دلیل، سه چیز رو با همین ترتیب چک کن: (۱) سرویس PHP-FPM زنده‌ست؟ (۲) مسیر socket یا پورت TCP که تو fastcgi_pass نوشتی واقعاً وجود داره؟ (۳) مالک و سطح دسترسی فایل socket درسته؟ تو این مقاله می‌بینی مشکل دقیقاً کجای مسیره، کدوم لاگ رو بخونی و کدوم دستور رو بزنی، و یه نکته‌ی مهم دیگه: بعضی وقتا چیزی که فکر می‌کنی 502 ـه، در واقع 504 Gateway Timeout ـه و علتش فرق داره.

خطای 502 دقیقاً چیه و از کجا میاد؟

وقتی Nginx یه درخواست PHP رو از طریق fastcgi_pass به FPM می‌ده، سه چیز ممکنه خراب بشه: وصل شدن، خوندن هدر جواب، و رسیدن جواب تو زمان مجاز. رفتار Nginx تو هر سه حالت فرق داره:

چیزی که تو لاگ Nginx می‌بینی یعنی چی معمولاً با کدوم خطا
connect() failed (111: Connection refused) while connecting to upstream FPM خاموشه یا مسیر/پورت fastcgi_pass اشتباهه 502
connect() failed (13: Permission denied) while connecting to upstream Nginx اجازه‌ی باز کردن socket رو نداره 502
upstream sent too big header هدر جواب از اندازه‌ی fastcgi_buffer_size بزرگ‌تره 502
recv() failed (104: Connection reset by peer) FPM وسط جواب دادن ری‌استارت شده 502
no live upstreams while connecting to upstream بلوک upstream خالیه یا همه‌ی سرورهاش fail شدن 502
upstream timed out (110: Connection timed out) جواب تو زمان مجاز نیومده معمولاً 504

تفکیک 502 و 504 از خود سورس Nginx درمیاد: خطای timeout به NGX_HTTP_GATEWAY_TIME_OUT (همون 504) می‌رسه و بقیه‌ی خطاها به NGX_HTTP_BAD_GATEWAY (همون 502) (سورس ngx_http_upstream.c). نتیجه‌ی عملی: اگه سایت خیلی دیر جواب می‌ده و بعدش خطا می‌ده، دنبال timeout بگرد؛ اگه فوری خطا می‌ده، دنبال مشکل اتصال.

چرا تو پروژه‌های لاراولی این خطا بیشتر پیش میاد؟

لاراول تو 502 هیچ نقشی نداره؛ مشکل لایه‌ی Nginx ↔ PHP-FPM ـه. ولی سه رفتار رایج پروژه‌های لاراولی احتمالش رو بالا می‌بره:

  • هدرهای جواب بزرگ: با Livewire یا Inertia و کوکی‌های زیاد، هدر جواب ممکنه از اندازه‌ی پیش‌فرض fastcgi_buffer_size (که توی مستندات Nginx مقدار 4k|8k ـه) بزرگ‌تر بشه و upstream sent too big header ببینی.
  • worker pool کم میاد: کوئری‌های کند یا صف‌های سنگین می‌تونن FPM رو تا سقف pm.max_children مشغول کنن؛ بعدش درخواست‌های جدید یا timeout می‌خورن یا جواب نمی‌گیرن. برای همین هر چی مالکیت و فیکس worker رو بهبود بدی، رو نرخ خطا اثر مستقیم داره.
  • عملیات روی production: اجرای composer install یا migration با کاربر root می‌تونه مالکیت فایل‌ها و socket رو عوض کنه و Nginx دیگه نتونه وصل بشه.

اگه صف و Supervisor رو هنوز تنظیم نکردی، اول مقاله‌ی رفع مشکل صف لاراول با Supervisor رو بخون؛ worker های گیرکرده یه‌ی از خطرناک‌ترین بارهای روی FPM هستن.

اول بفهم رو کدوم سکویی هستی

مسیر درخواست تو هر محیط فرق داره و همین علت اصلی گیر کردن تو عیب‌یابیه:

سکو PHP چطور صدا می‌شه 502 معمولاً از کجا میاد
VPS با Nginx + FPM fastcgi_pass unix:/run/php/php8.3-fpm.sock یا fastcgi_pass 127.0.0.1:9000 مسیر socket اشتباه (مخصوصاً بعد از آپدیت PHP)، دسترسی، FPM خاموش
cPanel / DirectAdmin FPM رو خود پنل مدیریت می‌کنه و هر کاربر pool خودش رو داره تنظیمات pool رو مستقیم نمی‌تونی عوض کنی؛ باید از بخش مدیریت PHP پنل یا پشتیبانی هاست پیگیری کنی
Docker fastcgi_pass app:9000 (TCP بین کانتینرها) اسم service تو docker-compose.yml اشتباهه، یا کانتینر FPM تو restart loop ـه

روی VPS، مسیر کلی اینه:

Browser → Nginx (:80/:443)
   ├─ فایل‌های استاتیک از public/ رو خودش سرو می‌کنه
   └─ بقیه‌ی درخواست‌ها → fastcgi_pass unix:/run/php/php8.3-fpm.sock
        → pool ی FPM (تا سقف pm.max_children)
        → Laravel (public/index.php) → جواب به Nginx → مرورگر

دو نکته از خود سورس PHP: توی فایل www.conf.in ی php-src، پیش‌فرض listen مقدار 127.0.0.1:9000 ـه و listen.mode پیشنهادی 0660 ـه؛ ولی بسته‌های Ubuntu معمولاً یه unix socket مثل /run/php/php8.3-fpm.sock ست می‌کنن. یعنی چیزی که تو سرورت واقعاً تنظیمه رو باید از کانفیگ pool خودت بخونی، نه از حدس.

مرحله ۱: تشخیص بدون restart

این دستورات چیزی رو تغییر نمی‌دن؛ فقط می‌خوان بفهمی دقیقاً کجای مسیر شکسته:

# ۱. وضعیت سرویس PHP-FPM (نسخه‌ی PHP رو با خودت عوض کن)
sudo systemctl status php8.3-fpm --no-pager

# ۲. آیا اصلاً socket هست؟
ls -la /run/php/

# ۳. مالک و دسترسی socket
stat /run/php/php8.3-fpm.sock

# ۴. Nginx به کجا اشاره می‌کنه؟ (nginx -T همه‌ی کانفیگ‌های include شده رو می‌بینه)
sudo nginx -T 2>/dev/null | grep fastcgi_pass

# ۵. آخرین خطاها
sudo tail -n 50 /var/log/nginx/error.log

چطور خروجی رو تفسیر کنی:

  • systemctl status: اگه active (running) دیدی، مشکل از سرویس نیست و برو سراغ socket و دسترسی. اگه inactive (dead) یا failed دیدی، journalctl -xeu php8.3-fpm --no-pager رو بزن؛ معمولاً یه syntax error تو کانفیگ pool پیداش می‌کنه.
  • ls /run/php/: اگه فایل socket نیس، یعنی سرویس هنوز شروع نشده یا listen توی کانفیگ pool جای دیگه‌ای رو نشون می‌ده. دقت کن مسیری که nginx -T نشون می‌ده با مسیر واقعی فایل یکی باشه؛ ناهماهنگی این دو، رایج‌ترین علت 502 بعد از آپدیت PHP ـه. ضمناً nginx -T فقط برای fastcgi نیست؛ مشکلات دیگه‌ی کانفیگ Nginx رو هم با همون رو پیدا می‌کنی، مثل خطای 404 لینک storage لاراول در Nginx.
  • stat: نمونه‌ی خروجی سالم توی اوبونتو چیزی شبیه Access: (0660) Uid: ( 33/www-data) Gid: ( 33/www-data) ـه؛ اگه group با کاربرِ worker ی Nginx یکی نیست، همون خطای Permission denied رو می‌بینی.
  • یه تست مستقیم دیگه، بدون Nginx: با ابزار cgi-fcgi (روی اوبونتو تو بسته‌ی libfcgi-bin) یه اتصال تمیز به خود FPM باز کن:
sudo cgi-fcgi -bind -connect /run/php/php8.3-fpm.sock || echo "SOCKET FAIL"
sudo cgi-fcgi -bind -connect 127.0.0.1:9000 || echo "TCP FAIL"

اگه SOCKET FAIL یا TCP FAIL چاپ شد، مشکل تو خود FPM ـه، نه تو کانفیگ Nginx؛ قبل از هر تغییری لاگ FPM و journalctl رو بخون.

مرحله ۲: رفع سریع (وقتی الان downtime داری)

قانون این مرحله: باید بدونی چرا restart می‌کنی. هر restart بی‌دلیل، درخواست‌های فعال رو قطع می‌کنه.

۲.۱ اگه FPM خاموشه

sudo systemctl start php8.3-fpm
sudo systemctl enable php8.3-fpm

اگه start نشد، خروجی journalctl -xeu php8.3-fpm --no-pager رو برای syntax error بخون، فیکس کن و دوباره start کن.

۲.۲ اگه Permission denied می‌بینی

بذار Nginx به socket برسه. دو راه داری: یا کاربر worker ی Nginx رو به گروه مالک socket اضافه کن، یا توی کانفیگ pool مالک socket رو تنظیم کن:

# /etc/php/8.3/fpm/pool.d/www.conf
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

و بعد:

sudo systemctl reload php8.3-fpm

نکته‌ی مهم: reload کانفیگ رو دوباره می‌خونه و برخلاف restart، کار درخواست‌های در حال پردازش رو به هم نمی‌زنه. برای بیشتر فیکس‌ها reload کافیه.

۲.۳ اگه بعد از آپدیت PHP همه‌ی سایت‌ها 502 شدن

بعد از ارتقا از PHP 8.2 به 8.3، مسیر socket از php8.2-fpm.sock به php8.3-fpm.sock عوض می‌شه ولی کانفیگ Nginx هنوز به مسیر قدیم اشاره می‌کنه:

# مسیر فعلی socket ها
ls /run/php/

# کانفیگ رو اصلاح کن و قبل از reload حتماً تست بگیر
sudo sed -i 's|php8.2-fpm.sock|php8.3-fpm.sock|g' /etc/nginx/sites-enabled/*
sudo nginx -t && sudo nginx -s reload

همیشه اول nginx -t رو بزن؛ اگه syntax error باشه reload رد می‌شه و کانفیگ قدیمی سر جاش می‌مونه و سایت قطع نمی‌مونه.

مرحله ۳: ریشه‌ای، وقتی 502 برمی‌گرده

اگه فیکس سریع جواب داد ولی بعد از یه مدت دوباره 502 دیدی، یه علت ساختاری داری. سه تا از رایج‌ترین‌هاش:

۳.۱ tuning ی pm.* ی pool

پیش‌فرض‌های www.conf ی php-src pm = dynamic، pm.max_children = 5، pm.start_servers = 2، pm.min_spare_servers = 1، pm.max_spare_servers = 3 و pm.max_requests = 0 هستن؛ یعنی pool کوچیک و بدون recycle ی worker. برای یه سایت لاراولی، این مقادیر رو بر اساس رم سرورت بالا ببر. به‌عنوان مثال فرضی (نه نسخه‌ی آماده): سرور ۴ گیگ رم، حدود ۲ گیگ برای PHP، با فرض ۵۰ مگابایت مصرف هر درخواست، یعنی pm.max_children حدود ۴۰؛ و یه فاصله‌ی احتیاطی هم نگه دار:

# فقط مثال؛ اعداد رو بر اساس رم واقعی سرور خودت بذار
pm = dynamic
pm.max_children = 40
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.max_requests = 500

pm.max_requests هر worker رو بعد از n درخواست recycle می‌کنه که مسیر نشت حافظه‌ی کتابخانه‌ها رو جمع می‌کنه. یادت باشه تغییر این فایل‌ها خودش اعمال نمی‌شه؛ باید systemctl reload php8.3-fpm بزنی تا master process کانفیگ رو دوباره بخونه.

۳.۲ اندازه‌ی بافر ی هدر تو Nginx

مطابق مستندات Nginx، پیش‌فرض fastcgi_buffer_size 4k|8k و fastcgi_buffers 8 4k|8k ـه (واحد 4k یا 8k به اندازه‌ی صفحه‌ی سیستم‌عامل وابسته‌ست). هدرهای جواب لاراول (مخصوصاً با Inertia) ممکنه از این بزرگ‌تر بشن:

# تو بلوک http یا server یا location
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

این مقادیر رو متناسب با هدرهای واقعی جواب‌هات تنظیم کن، نه بی‌دلیل حداکثری.

۳.۳ OPcache بعد از deploy

از سورس php-src، پیش‌فرض‌های OPcache این‌هاست: opcache.enable = 1، opcache.validate_timestamps = 1 و opcache.revalidate_freq = 2. یعنی به‌طور پیش‌فرض فایل‌ها هر ۲ ثانیه چک می‌شن و بعد از deploy بالاخره کد جدید لود می‌شه. ولی اگه جایی opcache.validate_timestamps = 0 گذاشته باشی، PHP تا reload بعدی کد قدیمی رو از حافظه سرو می‌کنه؛ نتیجه‌ش رفتارهای عجیب بعد از هر دیپلویه. برای دیپلوی‌های پیوسته، بعد از هر deploy یه systemctl reload php8.3-fpm بزن تا مطمئن باشی کد جدید سرو می‌شه.

۳.۴ چطور دفعه‌ی بعد زودتر بفهمی؟

از Laravel 11 به بعد یه مسیر سلامت داخلی به اسم /up داری (مستندات Deployment ی لاراول): اگه اپ بدون exception بالا اومده باشه 200 می‌ده و در غیر این صورت 500. می‌تونی یه چک ساده‌ی هر یک دقیقه ست کنی که اگه جواب سالم نیومد، بهت خبر بده:

# در crontab؛ هر یک دقیقه
* * * * * curl -fsS http://localhost/up >/dev/null || echo "502 ALERT: site down"

یادت باشه این خط باید از طریق crontab سرور به‌موقع اجرا بشه؛ بعد از ست کردنش هم چند دقیقه خروجی رو چک کن که واقعاً درست کار می‌کنه.

جدول مرجع سریع: هر خطا، یک کار

خطای Nginx معنی کار اصلی
Connection refused FPM خاموش یا مسیر اشتباه systemctl status php8.3-fpm و ls /run/php/
Permission denied مالکیت socket تنظیم listen.owner/group تو pool و reload
upstream sent too big header هدر بزرگ‌تر از بافر بالا بردن fastcgi_buffer_size و fastcgi_buffers
Connection reset by peer FPM وسط کار ری‌استارت شده لاگ FPM و journalctl رو چک کن
no live upstreams upstream خالی یا همه fail بلوک upstream و fastcgi_pass رو بررسی کن
upstream timed out جواب دیر رسید (معمولاً 504) کوئری‌های کند و ظرفیت pool رو مدیریت کن

کی واقعاً به restart کامل نیاز داره؟

reload برای بیشتر فیکس‌ها کافیه. restart کامل معمولاً وقتی لازمه که:

  • توی php.ini یه تغییر ساختاری دادی (مثل memory_limit).
  • یه extension ی PHP جدید نصب کردی.
  • تنظیم OPcache رو کامل عوض کردی.

و هیچ‌وقت به پروسه‌های FPM kill -9 نزن؛ این کار درخواست‌های فعال رو وسط کار قطع می‌کنه و ممکنه وضعیت سرویس رو بدتر کنه. کد اصلی تغییرات پی‌درپی رو هم روی production قبلش یه جایی مثل staging امتحان کن؛ برای خطاهای رایج بعد از دیپلوی، مقاله‌ی رفع خطای Vite manifest در production رو ببین.

سوالات متداول

۱. فرق 502 و 504 چیه؟ 502 یعنی Nginx نونست وصل بشه یا جواب معتبر نگرفت؛ 504 یعنی وصل شده ولی جواب تو زمان مجاز (fastcgi_read_timeout، پیش‌فرض ۶۰ ثانیه) نرسید. اگه سایت قبل از خطا چند ثانیه معطلی داره، احتمالاً 504 ـه و سراغ timeout و کندی کد برو.

۲. چرا storage/logs/laravel.log خالیه ولی سایت 502 می‌ده؟ چون 502 قبل از رسیدن به PHP اتفاق می‌افته؛ خطا تو لایه‌ی اتصال Nginx به FPM ـه. لاگ خطای Nginx (/var/log/nginx/error.log) رو بخون؛ الگوی connect() failed یا upstream sent too big header همون‌جاست.

۳. چطور بفهمم PHP-FPM با socket کار می‌کنه یا TCP؟ توی کانفیگ pool (مثل /etc/php/8.3/fpm/pool.d/www.conf) دنبال listen بگرد. اگه با unix: شروع بشه، socket ـه؛ اگه 127.0.0.1:9000 باشه، TCP ـه. پیش‌فرض خود php-src مقدار TCP ـه و بسته‌های Ubuntu معمولاً socket می‌ذارن.

۴. بعد از آپدیت PHP، همه‌ی سایت‌هام 502 شدن. چیکار کنم؟ تقریباً همیشه یعنی مسیر socket تو کانفیگ Nginx قدیمیه. با ls /run/php/ مسیر جدید رو پیدا کن، fastcgi_pass رو اصلاح کن و بعد nginx -t و nginx -s reload.

۵. تغییر pm.max_children بدون reload اعمال می‌شه؟ نه. این تنظیم تو فایل pool نوشته می‌شه ولی تا وقتی FPM کانفیگ رو دوباره نخونه، بی‌اثره. systemctl reload php8.3-fpm بزن؛ reload برخلاف restart درخواست‌های فعال رو قطع نمی‌کنه.

۶. مسیر /up چیه و چی کار به 502 داره؟ از Laravel 11 به بعد، یه مسیر سلامت داخلی هست که اگه اپ بدون exception بالا اومده باشه 200 و در غیر این صورت 500 می‌ده. اگه /up خطا بده ولی بقیه‌ی مسیرها 502 بدن، یعنی مشکل تو اتصال Nginx به FPM ـه نه تو یه route خاص.

جمع‌بندی

502 رو Nginx می‌سازه، نه لاراول؛ ترتیب چک هم همیشه یکی‌ست: سرویس PHP-FPM، مسیر و نوع اتصال تو fastcgi_pass، مالکیت و دسترسی socket، بعد اندازه‌ی بافر و ظرفیت pool. با این ترتیب، بیشتر موارد رو بدون restart تصادفی حل می‌کنی. اگه دنبال دیباگ سریع‌تری، Nyx رو امتحان کن؛ و اگه یه پروژه‌ی لاراولی داری که عیب‌یابیش سنگین شده، از صفحه‌ی تماس کاپیتان کد بهمون بگو.

Captain Code
verified
نویسنده

Captain Code

مشاهده پروفایل arrow_back

عاشق دنیای کدنویسی و به اشتراک‌گذاری دانش. ما در کاپیتان کد تلاش می‌کنیم بهترین محتوا را برای شما تولید کنیم.

مفید بود؟ لایک کنید 👋
اشتراک‌گذاری:

پرسش‌های متداول

فرق 502 و 504 چیه؟

502 یعنی Nginx نتونست وصل بشه یا جواب معتبر نگرفت؛ 504 یعنی وصل شده ولی جواب تو زمان مجاز (fastcgi_read_timeout، پیش‌فرض ۶۰ ثانیه) نرسید. اگه سایت قبل از خطا چند ثانیه معطلی داره، احتمالاً 504 ـه و سراغ timeout و کندی کد برو.

چرا storage/logs/laravel.log خالیه ولی سایت 502 می‌ده؟

چون 502 قبل از رسیدن به PHP اتفاق می‌افته؛ خطا تو لایه‌ی اتصال Nginx به FPM ـه. لاگ خطای Nginx (/var/log/nginx/error.log) رو بخون؛ الگوی connect() failed یا upstream sent too big header همون‌جاست.

چطور بفهمم PHP-FPM با socket کار می‌کنه یا TCP؟

توی کانفیگ pool (مثل /etc/php/8.3/fpm/pool.d/www.conf) دنبال listen بگرد. اگه با unix: شروع بشه، socket ـه؛ اگه 127.0.0.1:9000 باشه، TCP ـه. پیش‌فرض خود php-src مقدار TCP ـه و بسته‌های Ubuntu معمولاً socket می‌ذارن.

بعد از آپدیت PHP، همه‌ی سایت‌هام 502 شدن. چیکار کنم؟

تقریباً همیشه یعنی مسیر socket تو کانفیگ Nginx قدیمیه. با ls /run/php/ مسیر جدید رو پیدا کن، fastcgi_pass رو اصلاح کن و بعد nginx -t و nginx -s reload بزن.

تغییر pm.max_children بدون reload اعمال می‌شه؟

نه. این تنظیم تو فایل pool نوشته می‌شه ولی تا وقتی FPM کانفیگ رو دوباره نخونه، بی‌اثره. systemctl reload php8.3-fpm بزن؛ reload برخلاف restart درخواست‌های فعال رو قطع نمی‌کنه.

مسیر /up چیه و چی کار به 502 داره؟

از Laravel 11 به بعد، یه مسیر سلامت داخلی هست که اگه اپ بدون exception بالا اومده باشه 200 و در غیر این صورت 500 می‌ده. اگه /up خطا بده ولی بقیه‌ی مسیرها 502 بدن، یعنی مشکل تو اتصال Nginx به FPM ـه نه تو یه route خاص.

کاپیتان کد

این را برای پروژه‌ات می‌خواهی؟

پروژه را به کاپیتان کد بسپار، یا با نیکس همین مسئله را دیباگ کن.

forum

نظرات

lock_person

برای ثبت نظر وارد شوید

برای شرکت در گفتگو، لطفاً ابتدا وارد حساب کاربری‌تان شوید.

login ورود
chat_bubble_outline

هنوز نظری ثبت نشده

اولین نفری باشید که نظر خود را درباره این مطلب به اشتراک می‌گذارد!