همه مقالات تخصصی

رفع ۵۰۲ Nginx: upstream sent too big header

رفع خطای ۵۰۲ با پیام upstream sent too big header در Nginx: اندازه‌گیری واقعی هدرها، تنظیم درست بافرهای fastcgi و proxy و کم‌کردن کوکی‌های اضافه، قدم‌به‌قدم.

رفع ۵۰۲ Nginx: upstream sent too big header

صفحه‌ای که برای یک بازدیدکننده درست باز می‌شود و برای نفر بعدی ۵۰۲ می‌دهد، از آن باگ‌هایی است که آدم را کلافه می‌کند. سرور بالاست، PHP-FPM هم کار می‌کند، ولی Nginx وسط راه جواب را رها می‌کند. اگر در لاگ خطا عبارت upstream sent too big header while reading response header from upstream را می‌بینید، یعنی بک‌اند جواب داده است؛ فقط Nginx جایی برای نگه‌داشتن هدرهای آن جواب نداشته.

راه‌حل معمولاً یکی دو خط تنظیم است، اما عددی که می‌نویسید مهم است. اگر کم بگذارید خطا می‌ماند و اگر بی‌حساب بزرگ بگذارید مشکل واقعی زیر فرش می‌رود. در این راهنما اول اندازه می‌گیریم، بعد تغییر می‌دهیم.

۱. این پیام دقیقاً چه می‌گوید؟

Nginx وقتی با بک‌اند حرف می‌زند، جواب را داخل یک بافر می‌خواند. اولین تکه، یعنی خط وضعیت به‌اضافه همه هدرهای پاسخ، باید در همان یک بافر جا شود. اندازه این بافر برای PHP-FPM با fastcgi_buffer_size، برای proxy_pass با proxy_buffer_size و برای uWSGI با uwsgi_buffer_size تعیین می‌شود. مقدار پیش‌فرض یک صفحه حافظه است، معمولاً ۴k یا ۸k بسته به پلتفرم.

اگر هدرها از این بزرگ‌تر باشند، Nginx نمی‌تواند پاسخ را تجزیه کند، اتصال به بک‌اند را می‌بندد و به کاربر ۵۰۲ می‌دهد. بدنه صفحه در این ماجرا نقشی ندارد؛ صفحه‌ای دو مگابایتی با هدرهای کوچک مشکلی ندارد، ولی صفحه‌ای ریز با ۹ کیلوبایت هدر خطا می‌دهد.

۲. در لاگ تأییدش کنید و فیلد upstream را بخوانید

sudo grep "too big header" /var/log/nginx/error.log | tail -n 5

یک خط نمونه این شکلی است (آدرس‌ها نمونه مستندات هستند):

[error] 1421#1421: *88231 upstream sent too big header while reading response header
from upstream, client: 203.0.113.20, server: example.com, request: "GET /wp-admin/ HTTP/2.0",
upstream: "fastcgi://unix:/run/php/php8.3-fpm.sock:", host: "example.com"

قبل از دست‌بردن در تنظیمات، بخش upstream: را نگاه کنید. اگر fastcgi:// است باید دستورهای fastcgi_* را عوض کنید و اگر http:// یا proxy:// است، دستورهای proxy_* را. یکی از رایج‌ترین دلایل «بی‌اثر بودن» راه‌حل، همین است که خانواده اشتباهی ویرایش شده. بخش request: هم سرنخ خوبی است: صفحه‌های ورود، پرداخت و مدیریت زیاد دیده می‌شوند، چون کوکی‌ها آنجا روی هم جمع می‌شوند.

۳. به‌جای حدس زدن، اندازه هدرها را بگیرید

اگر بک‌اند HTTP حرف می‌زند، می‌توانید همان آدرس خراب را مستقیم از خودش بخواهید و حجم هدر را بشمارید:

curl -sS -D headers.txt -o /dev/null -H "Cookie: session=PASTE_REAL_VALUE" http://127.0.0.1:8080/wp-admin/
wc -c headers.txt
grep -ci '^set-cookie' headers.txt

برای PHP-FPM روی سوکت، راحت نمی‌شود مستقیم curl زد. پس دو مرحله‌ای جلو بروید: موقتاً fastcgi_buffer_size 32k; را در location مربوطه بگذارید، reload کنید، همان دستور را این بار از طریق Nginx اجرا کنید و حجم واقعی را از headers.txt بخوانید. بعد مقدار نهایی را یک پله بالاتر از آن عدد بگذارید (۸k، ۱۶k، ۳۲k). کوکی‌هایی را بفرستید که مرورگر واقعاً می‌فرستد، چون برنامه معمولاً وقتی نشست فعال است هدر بیشتری اضافه می‌کند.

۴. معمولاً چه چیزی هدرها را بزرگ می‌کند؟

بزرگ‌کردن بافر فقط علامت را درمان می‌کند. بهتر است بدانید چه چیزی آن را پر کرده:

  • تعداد زیاد Set-Cookie از افزونه‌ها، آنالیتیکس، تست A/B یا مدیریت نشست؛ هر کدام می‌تواند چند صد بایت باشد.
  • Content-Security-Policy یا Permissions-Policy خیلی بلند که هم برنامه اضافه کرده و هم Nginx.
  • هدرهای Link: rel=preload که ده‌ها فایل را فهرست می‌کنند.
  • هدرهای دیباگ یا پروفایلر که بعد از یک عیب‌یابی روشن مانده‌اند.
  • توکن‌های بزرگ (مثل JWT) که داخل هدر برمی‌گردند.
  • هدر Location در ریدایرکتی که رشته کوئری بلندی دارد.

۵. بافرها را درست بزرگ کنید

برای PHP-FPM این دستورها را در بلوک location مربوط به PHP بگذارید:

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;

    fastcgi_buffer_size 16k;        # هدرهای پاسخ (و ابتدای بدنه)
    fastcgi_buffers 16 16k;         # بقیه بدنه
    fastcgi_busy_buffers_size 32k;  # داده‌ای که هنوز در حال خواندن، می‌شود به کاربر فرستاد
}

برای reverse proxy معادلش این است:

proxy_buffer_size 16k;
proxy_buffers 16 16k;
proxy_busy_buffers_size 32k;

فقط دستور اول تعیین می‌کند هدرها جا می‌شوند یا نه. دو دستور دیگر برای این هستند که Nginx آن‌ها را با هم می‌سنجد: اندازه busy باید دست‌کم برابر بزرگ‌ترین بافر تکی باشد و از مجموع همه بافرها منهای یک بافر کوچک‌تر باشد. اگر nginx -t درباره «busy buffers» ایراد گرفت، همین قاعده را شکسته‌اید. سه خط بالا با هم سازگارند و می‌توانید از همین‌ها شروع کنید.

مصرف حافظه معمولاً نگرانی اصلی نیست. بافرها برای هر اتصال و در صورت نیاز ساخته می‌شوند و ۱۶k برای هدر ارزان است. اگر دیدید برای ساکت‌کردن خطا عدد ۱۲۸k یا ۲۵۶k می‌گذارید، یک قدم برگردید و بخش ۴ را دوباره بخوانید.

۶. تغییر را امن اعمال کنید

sudo nginx -t && sudo systemctl reload nginx
sudo tail -f /var/log/nginx/error.log

اول تنظیمات را تست کنید و بعد reload بزنید، نه restart، تا اتصال‌های باز قطع نشوند. سپس همان درخواستی را که خراب بود دوباره امتحان کنید. باید کد ۲۰۰ بگیرید و خط تازه‌ای با «too big header» نبینید. دو سه آدرسی را که مشکل‌ساز بودند تست کنید، نه فقط صفحه اول را.

۷. ریشه حجیم‌شدن را اصلاح کنید

وقتی سایت دوباره کار کرد، علت را کوچک کنید. ابزار توسعه مرورگر را باز کنید، در تب Network درخواست خراب را پیدا کنید و هدرهای پاسخ را بخوانید. افزونه‌ای که پنج کوکی بی‌مصرف می‌گذارد را حذف کنید. CSP را کوتاه کنید. برای فایل‌هایی که صفحه لازم ندارد preload نفرستید. هدر کوچک‌تر برای همه بازدیدکننده‌ها سریع‌تر است، نه فقط برای Nginx.

۸. یک مثال کاربردی: پیشخوان وردپرس پشت Nginx

فرض کنید /wp-admin/ فقط برای کاربران واردشده ۵۰۲ می‌دهد. لاگ خطای «too big header» با upstream از نوع fastcgi:// نشان می‌دهد. وارد می‌شوید، هدر Cookie را از درخواست مرورگر کپی می‌کنید، بافر را موقتاً ۳۲k می‌گذارید و دستور curl بخش ۳ را اجرا می‌کنید. نتیجه: ۱۱٬۴۰۰ بایت و هفت خط Set-Cookie. هر عددی بالای پیش‌فرض ۸k خرابی را توضیح می‌دهد؛ پس ۱۶k می‌گذارید، reload می‌کنید و پیشخوان باز می‌شود.

خیلی‌ها همین‌جا تمام می‌کنند. پایان بهتر این است که سراغ همان هفت کوکی بروید. اگر چهار تای آن‌ها از افزونه‌ای باشد که چیزی را ردیابی می‌کند که کسی نمی‌خواند، خاموش‌کردنش ممکن است حجم را زیر ۴k ببرد و پیش‌فرض از اول هم کافی بوده باشد. ترتیب مهم است: اندازه بگیرید، تنظیم کنید، بعد کوچک کنید.

۹. وقتی CDN یا پروکسی دیگری جلوی Nginx است

Nginx کمتر پیش می‌آید که تنها واسطه باشد. CDN، لودبالانسر یا یک Nginx دیگر محدودیت هدر مخصوص خودش را دارد و همیشه هم یک‌جور مستند نشده است. اگر ۵۰۲ در صفحه خطای CDN دیده می‌شود نه در Nginx شما، لاگِ لایه جلویی را بخوانید. همین روش را در هر لایه تکرار کنید: ببینید کدام لایه خطا را ثبت می‌کند، هدرهایی را که گرفته اندازه بگیرید و همان لایه را تنظیم کنید. بزرگ‌کردن بافر روی سرور داخلی فایده‌ای ندارد اگر پروکسی بیرونی همان باشد که پاسخ را رد می‌کند.

۱۰. با خطاهای شبیهش اشتباه نگیرید

  • upstream sent too big header: هدرهای پاسخ بک‌اند بزرگ است. fastcgi_buffer_size یا proxy_buffer_size را تنظیم کنید.
  • 400 Request Header Or Cookie Too Large: هدرهای درخواست مرورگر بزرگ است. این مسیر دیگری است و به large_client_header_buffers مربوط می‌شود.
  • upstream sent invalid header: هدرها خراب‌اند، نه بزرگ. خروجی برنامه را بررسی کنید؛ اغلب یک بایت اضافه یا warning پیش از ارسال هدر چاپ شده است.

۱۱. نمونه کامل تنظیم برای PHP-FPM و پروکسی

اگر وردپرس شما با FastCGI به PHP-FPM وصل است، مقدارهای زیر برای بیشتر سایت‌ها کافی است. اگر Nginx با proxy_pass جلوی یک اپلیکیشن Node.js یا Python نشسته، همین سه دستور را با پیشوند proxy_ بنویسید.

# FastCGI (PHP-FPM)
fastcgi_buffer_size 16k;
fastcgi_buffers 16 16k;
fastcgi_busy_buffers_size 32k;

# proxy_pass
proxy_buffer_size 16k;
proxy_buffers 16 16k;
proxy_busy_buffers_size 32k;

دستور اول همان است که هدر پاسخ را نگه می‌دارد. دستور آخر باید از بزرگ‌ترین بافر کوچک‌تر نباشد و از مجموع بافرها منهای یک بافر کمتر باشد؛ ۳۲k با ۱۶ بافر ۱۶k این شرط را رعایت می‌کند. اگر nginx -t درباره همین رابطه شکایت کرد، busy_buffers_size را اصلاح کنید.

اگر بعد از reload هنوز همان خطا را می‌بینید، ۱۶k کافی نیست. یک پله به ۳۲k بروید و دوباره اندازه واقعی هدر را اندازه بگیرید. بالابردن کورکورانه تا ۱۲۸k مشکل را پنهان می‌کند و فقط حافظه می‌خورد.

۱۲. مطمئن شوید «upstream sent too big header» تمام شده است

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

grep -c "too big header" /var/log/nginx/error.log
tail -f /var/log/nginx/error.log | grep --line-buffered "too big header"

اگر بعد از چند دقیقه ترافیک واقعی خط جدیدی اضافه نشد، مشکل برطرف شده است. خطوط قدیمی هم در شمارش می‌آیند؛ برای مقایسه دقیق، زمان آخرین خطا را نگاه کنید.

بافرها از حافظه هر درخواست فعال کم می‌کنند، پس سقف را بی‌دلیل بالا نبرید. اگر فقط بعضی آدرس‌ها (مثلاً بعد از ورود) هدر بزرگ دارند، تنظیم را در همان location بگذارید تا بقیه سایت مصرف بیشتری نداشته باشد. در پایان، مقدار انتخابی و دلیلش را کنار تنظیم کامنت کنید تا کسی بعداً بدون دانستن علت آن را پایین نیاورد.

۱۳. چک‌لیست سریع

  1. خط لاگ را پیدا کنید و ببینید upstream از نوع fastcgi:// است یا http://.
  2. اندازه واقعی هدر را با curl -D بگیرید.
  3. بافر را روی پله منطقی بعدی بگذارید، معمولاً ۱۶k یا ۳۲k.
  4. nginx -t بزنید، reload کنید و آدرس‌های خراب را دوباره تست کنید.
  5. کوکی‌ها و هدرهایی را که باعث مشکل شده‌اند کم کنید.

اگر بعد از این کارها هنوز ۵۰۲ می‌بینید، علت احتمالاً چیز دیگری است: کرش‌کردن workerهای PHP-FPM، timeout یا تمام‌شدن اتصال‌ها. برای مورد اول و دوم، راهنمای عیب‌یابی کندی PHP با Slowlog را ببینید و برای رفتار اتصال‌ها زیر بار، تنظیم Keepalive بین Nginx و Upstream را.

اگر خطا هنگام آپلود رخ می‌دهد و نه در پاسخ بک‌اند، علت فرق می‌کند؛ رفع خطای ۴۱۳ در Nginx را ببینید.

راهنماهای بیشتر عیب‌یابی سرور در آرشیو مقالات جمع شده‌اند.

منابع رسمی

Nginx ngx_http_fastcgi_module · Nginx ngx_http_proxy_module · Nginx ngx_http_core_module