كل المقالات التقنية

حل 502 في Nginx: upstream sent too big header

حل خطأ 502 في Nginx مع رسالة upstream sent too big header: قياس ترويسات الرد فعلياً، وضبط مخازن fastcgi وproxy بدقة، وتقليل الكوكيز الزائدة خطوة بخطوة.

حل 502 في Nginx: upstream sent too big header

صفحة تُفتح بسلاسة لزائر ثم تُرجع الخطأ 502 للزائر التالي مشكلة مزعجة في التشخيص. الخادم يعمل، وPHP-FPM يعمل، ومع ذلك يستسلم Nginx في منتصف الطريق. إذا ظهرت في سجل الأخطاء عبارة upstream sent too big header while reading response header from upstream فهذا يعني أن الخادم الخلفي ردّ فعلاً، لكن Nginx لم يجد مساحة تتسع لترويسات هذا الرد.

الحل عادةً سطر أو سطران في الإعدادات، لكن الرقم الذي تكتبه مهم. إذا خفضته بقي الخطأ، وإذا رفعته بلا حساب أخفيت مشكلة حقيقية. سنقيس أولاً ثم نغيّر.

١. ماذا تعني الرسالة بالضبط؟

عندما يتحدث Nginx مع الخادم الخلفي يقرأ الرد داخل مخزن مؤقت (buffer). الجزء الأول، أي سطر الحالة وكل ترويسات الرد، يجب أن يتسع في مخزن واحد. حجمه يحدده fastcgi_buffer_size مع PHP-FPM، وproxy_buffer_size مع proxy_pass، وuwsgi_buffer_size مع uWSGI. القيمة الافتراضية صفحة ذاكرة واحدة، غالباً 4k أو 8k بحسب المنصة.

إذا كانت الترويسات أكبر من ذلك لا يستطيع Nginx تحليل الرد، فيغلق الاتصال بالخادم الخلفي ويرسل للعميل 502. جسم الصفحة ليس طرفاً في المشكلة: صفحة بحجم 2 ميغابايت وترويسات صغيرة تعمل بلا مشاكل، بينما صفحة صغيرة بترويسات حجمها 9 كيلوبايت تفشل.

٢. تأكد من السجل واقرأ حقل 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 عبر socket لا توجد طريقة سهلة لاستخدام curl مباشرة، لذا اتبع خطوتين: ضع مؤقتاً fastcgi_buffer_size 32k; في الـlocation المعني، وأعد التحميل، ثم كرر الأمر نفسه عبر Nginx واقرأ الحجم الفعلي من headers.txt. بعدها اضبط القيمة النهائية على الدرجة المعقولة التالية فوق هذا الرقم (8k أو 16k أو 32k). أرسل الكوكيز التي يرسلها المتصفح فعلاً، لأن التطبيق غالباً يضيف ترويسات أكثر عند وجود جلسة.

٤. ما الذي يضخّم ترويسات الرد عادةً؟

رفع المخزن يعالج العَرَض فقط، ومن الأفضل أن تعرف ما الذي يملؤه:

  • عدد كبير من ترويسات Set-Cookie من الإضافات أو التحليلات أو اختبارات A/B أو معالجات الجلسات، وقد يبلغ كل منها بضع مئات من البايتات.
  • Content-Security-Policy أو Permissions-Policy طويلة جداً يضيفها التطبيق ثم يضيفها Nginx مرة أخرى.
  • ترويسات Link: rel=preload التي تسرد عشرات الملفات.
  • ترويسات تصحيح أو profiler تُركت مفعّلة بعد جلسة استكشاف أخطاء.
  • رموز كبيرة (مثل 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» فهذه القاعدة هي التي خالفتها. الأسطر الثلاثة أعلاه متسقة، فيمكنك البدء منها.

الذاكرة نادراً ما تكون مصدر القلق، فالمخازن تُخصَّص لكل اتصال عند الحاجة، و16k للترويسات رخيصة. إذا وجدت نفسك تكتب 128k أو 256k لمجرد إسكات الخطأ فتوقف وارجع إلى القسم الرابع.

٦. طبّق التغيير بأمان

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

اختبر الإعدادات قبل إعادة التحميل، واستخدم reload لا restart كي لا تنقطع الاتصالات المفتوحة. ثم أعد الطلب الذي فشل. المطلوب هو رمز 200 وعدم ظهور أسطر جديدة فيها «too big header». اختبر الروابط الثلاثة أو الأربعة التي سببت المشكلة، وليس الصفحة الرئيسية فقط.

٧. عالج مصدر التضخم

بعد عودة الموقع للعمل قلّص السبب نفسه. افتح أدوات المطور في المتصفح، وابحث في تبويب Network عن الطلب المعطوب واقرأ ترويسات الرد. احذف الإضافة التي تضع خمسة كوكيز لا يستخدمها أحد. اختصر الـCSP. لا ترسل preload لملفات لا تحتاجها الصفحة. الترويسات الأصغر أسرع لكل الزوار، لا لـNginx وحده.

٨. مثال عملي: لوحة تحكم ووردبريس خلف Nginx

افترض أن /wp-admin/ يعيد 502 للمستخدمين المسجّلين فقط. يُظهر السجل «too big header» مع upstream من نوع fastcgi://. تسجّل الدخول، وتنسخ ترويسة Cookie من طلب المتصفح، وتضبط المخزن مؤقتاً على 32k، وتنفذ أمر curl من القسم الثالث. النتيجة: 11,400 بايت وسبعة أسطر Set-Cookie. أي رقم فوق الافتراضي 8k يفسّر الفشل، فتضبط 16k وتعيد التحميل وتعمل اللوحة.

كثيرون يتوقفون هنا. النهاية الأفضل أن تنظر في الكوكيز السبعة. إذا كانت أربعة منها من إضافة تتتبع شيئاً لا يقرؤه أحد، فقد يؤدي تعطيلها إلى خفض الحجم تحت 4k ويتبيّن أن الإعداد الافتراضي كان كافياً من الأساس. الترتيب مهم: قِس، ثم اضبط، ثم قلّص.

٩. عندما يوجد CDN أو بروكسي آخر أمام Nginx

نادراً ما يكون Nginx الحلقة الوحيدة. شبكة CDN أو موزّع أحمال أو Nginx ثانٍ لكل منها حدود ترويسات خاصة، وليست موثّقة دائماً بالطريقة نفسها. إذا ظهر الـ502 في صفحة خطأ الـ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: الترويسات تالفة وليست كبيرة. افحص مخرجات التطبيق؛ كثيراً ما يكون بايتاً زائداً أو تحذيراً طُبع قبل إرسال الترويسات.

١١. إعداد كامل لـPHP-FPM والتطبيقات خلف البروكسي

إذا كان ووردبريس يتصل بـPHP-FPM عبر FastCGI فالقيم التالية كافية لمعظم المواقع. وإذا كان Nginx أمام تطبيق Node.js أو Python عبر proxy_pass فاكتب التوجيهات الثلاثة نفسها بالبادئة 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;

التوجيه الأول هو الذي يحمل ترويسة الرد. أما الأخير فيجب ألا يقل عن أكبر مخزن منفرد، وأن يبقى أصغر من مجموع المخازن مطروحاً منه مخزن واحد؛ وقيمة 32k مع ستة عشر مخزناً حجم كل منها 16k تحقق ذلك. وإذا اشتكى nginx -t من هذه العلاقة فصحّح busy_buffers_size.

وإذا بقي الخطأ نفسه بعد إعادة التحميل فـ16k غير كافية. انتقل إلى 32k ثم قس حجم الترويسة الفعلي مرة أخرى. رفع القيمة عشوائياً إلى 128k يخفي المشكلة ويستهلك الذاكرة فقط.

١٢. تأكد أن «upstream sent too big header» اختفى

بعد إعادة التحميل لا تكتفِ بأن تُفتح صفحة واحدة. قارن عدد الأخطاء في السجل قبل التغيير وبعده، وراقب السجل مباشرة:

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

إذا لم يظهر سطر جديد بعد بضع دقائق من الزيارات الحقيقية فقد زالت المشكلة. تذكّر أن الأسطر القديمة تدخل في العدّ، فانظر إلى وقت آخر خطأ للمقارنة الدقيقة.

تستهلك المخازن ذاكرة لكل طلب نشط، فلا ترفع السقف دون سبب. وإذا كانت الترويسات الكبيرة في روابط محددة فقط (بعد تسجيل الدخول مثلاً) فضع الإعداد في location الخاص بها لكي لا يتحمل بقية الموقع كلفته. واكتب أخيراً تعليقاً بجانب الإعداد يذكر القيمة وسببها حتى لا يخفضها أحد لاحقاً دون أن يعرف لماذا.

١٣. أسئلة شائعة

هل يكفي رفع proxy_buffer_size وحده؟ إذا كان الخطأ ناتجاً عن ترويسة الرد فغالباً نعم، لكن اجعل busy_buffers_size متوافقاً معه حتى يمر nginx -t.

لماذا يظهر الخطأ لبعض الزوار فقط؟ لأن حجم الترويسة يتغير مع الكوكيز والمحتوى؛ من لديه كوكيز أكثر أو جلسة نشطة قد يتجاوز الحد بينما لا يتجاوزه الآخرون.

هل المشكلة من PHP-FPM؟ لا، بل من حد المخزن في Nginx؛ PHP-FPM يعمل ويرد، لكن Nginx يرفض ترويسة أكبر من مخزنه.

هل أحتاج إلى إعادة تشغيل Nginx أم تكفي إعادة التحميل؟ تكفي إعادة التحميل (nginx -s reload) بعد أن ينجح nginx -t؛ وهي لا تقطع الاتصالات الجارية.

١٤. قائمة تحقق سريعة

  1. اعثر على سطر السجل وحدد هل الـupstream من نوع fastcgi:// أم http://.
  2. قس الحجم الحقيقي للترويسات بـcurl -D.
  3. اضبط المخزن على الدرجة المعقولة التالية، غالباً 16k أو 32k.
  4. نفّذ nginx -t ثم reload وأعد اختبار الروابط المعطوبة.
  5. قلّل الكوكيز والترويسات التي سببت المشكلة.

إذا بقي الـ502 بعد ذلك فالسبب غالباً شيء آخر: انهيار عمال PHP-FPM أو مهلة زمنية أو نفاد الاتصالات. دليلنا عن ضبط PHP-FPM وحل خطأ 504 يغطي الأولين، ومقال ضبط Keepalive بين Nginx وUpstream يشرح سلوك إعادة استخدام الاتصالات تحت الضغط.

إذا كان الخطأ عند رفع الملفات وليس في رد الخادم الخلفي فالسبب مختلف؛ راجع حل خطأ 413 في Nginx.

تجد المزيد من أدلة استكشاف أخطاء الخوادم في أرشيف المقالات.

المراجع الرسمية

Nginx ngx_http_fastcgi_module · Nginx ngx_http_proxy_module · Nginx ngx_http_core_module