اگر در error.log وبسرور NGINX پیام upstream sent too big header while reading response header from upstream را میبینید، مشکل معمولاً این است که هدر پاسخِ Backend در بافر اولیه NGINX جا نمیشود. ابتدا نوع Upstream را مشخص کنید: برای proxy_pass از proxy_buffer_size و برای PHP-FPM با fastcgi_pass از fastcgi_buffer_size استفاده میشود. بهجای افزایش بیحساب همه بافرها، ابتدا اندازه و علت بزرگشدن هدر (بهویژه Set-Cookie) را بررسی کنید، سپس تغییر محدود را آزمایش و تأیید کنید.
این خطا دقیقاً چه زمانی رخ میدهد؟
فرض کنید NGINX درخواست را به یک برنامه Node.js، Python یا PHP-FPM میفرستد. برنامه پاسخ HTTP را همراه تعداد زیادی کوکی، ریدایرکت یا هدر سفارشی برمیگرداند. اگر هدر پاسخ در بافر اختصاصیافته برای خواندن بخش ابتدایی پاسخ جا نشود، NGINX ممکن است خطای 502 بدهد و متن بالا را در error.log ثبت کند. این وضعیت با خطای Timeout فرق دارد: در راهنمای عیبیابی 504 در NGINX مسئله اصلی انتظار برای پاسخ است، نه بزرگی هدر.
پیشنیاز و نکات ایمنی
- دسترسی SSH و sudo به VPS یا سروری که NGINX روی آن مدیریت میشود.
- دسترسی به فایل پیکربندی vhost و لاگ NGINX؛ مسیرها در توزیعهای مختلف متفاوتاند.
- زمان مناسب برای Reload و امکان بازگرداندن فایل قبلی.
- از هدرهای دارای Cookie، Authorization و توکن، خروجی کامل عمومی یا اسکرینشات منتشر نکنید.
مرحله اول: پیام واقعی را در error.log پیدا کنید
sudo nginx -t
sudo tail -n 120 /var/log/nginx/error.log
sudo grep -F "upstream sent too big header" /var/log/nginx/error.log | tail -n 20
sudo nginx -T 2>&1 | grep -nE 'proxy_pass|fastcgi_pass|proxy_buffer_size|fastcgi_buffer_size'در برخی نصبها لاگ از طریق journalctl -u nginx یا مسیر سفارشی در error_log قابل مشاهده است. اگر متن دقیق بالا وجود ندارد، تغییر Buffer را متوقف کنید؛ برای خطاهای اتصال و Socket، راهنمای بررسی 502 و Upstream در NGINX مناسبتر است.
مرحله دوم: منشأ هدر بزرگ را شناسایی کنید
ابتدا از یک درخواست تستی با احراز هویت و کوکیهای کنترلشده استفاده کنید. اگر مسیر مشکلدار به کوکی جلسه نیاز دارد، تست ناشناس ممکن است خطا را بازتولید نکند. نمونه زیر فقط هدرهای یک درخواست غیرحساس را به فایل محلی محدودشده ذخیره میکند؛ فایل را عمومی نکنید.
umask 077
curl -sS -D /tmp/nginx-response-headers.txt -o /dev/null https://example.com/problem-path
wc -c /tmp/nginx-response-headers.txt
grep -iE '^(set-cookie|location|content-security-policy):' /tmp/nginx-response-headers.txt | cut -c 1-100
rm -f /tmp/nginx-response-headers.txtتوجه: در مثال بالا آدرس دامنه را جایگزین کنید. خروجی curl -D از سمت NGINX است؛ وقتی NGINX با 502 پاسخ میدهد، هدر بزرگ Backend را نشان نمیدهد. برای اندازهگیری واقعی هدر Backend، فقط در شبکه امن و با مجوز، مستقیماً به Upstream درخواست بفرستید یا لاگ برنامه را بررسی کنید. اگر تعداد کوکیها یا حجم Session غیرعادی است، اصلاح در برنامه بهتر از افزایش مداوم بافر است.
مرحله سوم: تفاوت proxy_buffer_size و fastcgi_buffer_size
| مسیر پاسخ | دستور مرتبط | کاربرد |
|---|---|---|
proxy_pass | proxy_buffer_size | بافر خواندن بخش ابتدایی پاسخ HTTP از Upstream، معمولاً شامل هدر |
fastcgi_pass | fastcgi_buffer_size | بافر خواندن بخش ابتدایی پاسخ FastCGI از PHP-FPM |
دستورهای proxy_buffers و fastcgi_buffers برای بافرکردن بدنه پاسخ کاربرد دارند و جایگزین مستقیمِ اندازه بافر اولیه هدر نیستند. همچنین large_client_header_buffers برای هدر درخواست ورودی کلاینت است، نه خطای هدر پاسخ Upstream؛ تغییر آن برای این پیام معمولاً راهحل نیست.
مرحله چهارم: تنظیم کنترلشده با Backup و تست
ابتدا فایل vhost واقعی را از خروجی nginx -T پیدا کنید و از همان فایل نسخه پشتیبان بگیرید. مسیر نمونه را بدون بررسی روی سرور اجرا نکنید:
sudo cp -a /etc/nginx/sites-available/example.conf /etc/nginx/sites-available/example.conf.bak-$(date +%Y%m%d-%H%M%S)
sudo nginx -T > /tmp/nginx-config-before-header-fix.txtاگر Backend از نوع HTTP Proxy است، در location مربوط به همان مسیر، مقدار اولیه محافظهکارانه زیر را آزمایش کنید:
location /api/ {
proxy_pass http://127.0.0.1:3000;
proxy_buffer_size 16k;
}اگر سایت از PHP-FPM استفاده میکند، نمونه مرتبط با fastcgi_pass این است؛ این قطعه کامل پیکربندی PHP نیست و باید صرفاً دستور fastcgi_buffer_size را به location موجود و سالم اضافه کنید، نه اینکه تنظیمات fastcgi_param یا مسیر Socket فعلی را حذف کنید:
# Inside your existing PHP FastCGI location:
fastcgi_buffer_size 16k;مقدار 16k فقط نقطه شروع آزمایشی است، نه نسخه ثابت برای همه سایتها. مصرف حافظه با تعداد اتصالها و تنظیمات دیگر مرتبط است؛ از افزایش سراسری و بدون اندازهگیری به 128k یا 256k خودداری کنید. پس از ذخیره فایل:
sudo nginx -t
sudo systemctl reload nginx
sudo systemctl is-active nginxاگر nginx -t ناموفق بود، Reload نکنید. اگر هنوز پیام خطا رخ میدهد، بررسی کنید دستور در همان server/location مؤثر قرار گرفته باشد و با خروجی nginx -T از بارگذاری آن مطمئن شوید.
مرحله پنجم: Verify و مشاهده اثر تغییر
sudo nginx -t
curl -sS -o /dev/null -w 'HTTP %{http_code} / time %{time_total}sn' https://example.com/problem-path
sudo tail -n 80 /var/log/nginx/error.log
sudo nginx -T 2>&1 | grep -nE 'proxy_buffer_size|fastcgi_buffer_size'همان URL و همان سناریوی Session/Cookie را که خطا ایجاد میکرد تکرار کنید. موفقیت فقط دریافت HTTP 200 نیست؛ باید پیام upstream sent too big header برای درخواست جدید تکرار نشود و برنامه و ورود کاربر درست کار کنند. برای کندی PHP مستقل از این خطا، میتوانید عیبیابی PHP-FPM با Slow Log را دنبال کنید.
Rollback امن در صورت خطا
اگر عملکرد سایت پس از تغییر بدتر شد، نسخه پشتیبان همان vhost را بازگردانید. ابتدا نام واقعی فایل Backup را با ls پیدا کنید؛ از Wildcard غیرقابلکنترل استفاده نکنید.
sudo ls -lt /etc/nginx/sites-available/example.conf.bak-*
# Replace BACKUP_FILE with the exact verified backup path:
sudo cp -a BACKUP_FILE /etc/nginx/sites-available/example.conf
sudo nginx -t && sudo systemctl reload nginxاگر نسخه پشتیبان ندارید، فقط directive جدید را از همان location حذف کنید و بعد از nginx -t، Reload انجام دهید. تغییرات برنامه یا کوکیها نیز باید جداگانه به حالت قبلی برگردند.
چه زمانی منابع سرور را بازبینی کنیم؟
اگر بعد از اصلاح هدرهای غیرضروری و تعیین Buffer متناسب، مصرف RAM یا تعداد اتصالهای همزمان روی NGINX و Backend بالا است، در یک VPS خودمدیریت میتوانید میزان حافظه، محدودیتها و دسترسی مدیریتی را در پلنهای سرور مجازی وانسرور مقایسه کنید. خرید یا ارتقای VPS بهتنهایی هدرهای غیرعادی، کوکیهای حجیم یا پیکربندی اشتباه برنامه را اصلاح نمیکند.
خطاهای رایج و جمعبندی
- تغییر
large_client_header_buffersبرای هدر پاسخ Upstream؛ جهت مسئله اشتباه است. - افزایش
proxy_buffersبدون بررسیproxy_buffer_size. - تغییر FastCGI در مسیری که در واقع
proxy_passدارد یا برعکس. - Reload بدون تست Syntax یا ویرایش فایل vhost اشتباه.
- نادیدهگرفتن کوکیها و Headerهای غیرضروری در برنامه.
روش اصولی این است: پیام دقیق error.log → شناسایی نوع Upstream → بررسی علت هدر بزرگ → تغییر محدود بافر اولیه → nginx -t و Reload → Verify → Rollback در صورت نیاز. مستندات رسمی proxy_buffer_size و fastcgi_buffer_size مرجع نهایی Syntax و Context این دستورها هستند.