شرح إعداد nginx كوكيل عكسي خطوة بخطوة
تعلّم إعداد كتلة خادم nginx على Ubuntu 24.04، مع proxy_pass والرؤوس الأربعة وWebSocket والشرطات المائلة ورفع الملفات، واختبره باستخدام nginx -t.
ما الذي يفعله إعداد nginx للـReverse Proxy
يستقبل nginx للـReverse Proxy الطلبات الواردة على المنفذين 80 و443، ويمرّر كل طلب إلى تطبيق يستمع مسبقاً على منفذ محلي، ثم يعيد إجابة ذلك التطبيق إلى المتصفح. يتكوّن الإعداد من كتلة واحدة من نوع server، وهذه الكتلة قصيرة. تتركز معظم الصعوبة في خمسة أو ستة أسطر تحدد للتطبيق هوية العميل الفعلية والبروتوكول الذي استخدمه ذلك العميل.
تُبنى جميع الخطوات التالية من الصفر على Ubuntu 24.04، باستخدام حزمة nginx التي يوفرها التوزيع. نقطة البداية هي تطبيق يستجيب مسبقاً على 127.0.0.1:3000. إذا لم تكن قد اخترت Reverse Proxy بعد، فاقرأ أولاً مقارنة nginx مع Caddy وTraefik. يوضح ما يلي شكل إعداد nginx، سطراً بعد سطر.
شغّل هذه الإعدادات على خادمك الخاص. اختبر كل تغيير باستخدام sudo nginx -t قبل إعادة التحميل، واقرأ الناتج الذي يعرضه.
موقع حفظ nginx لملفات الإعداد في Ubuntu
sudo apt update
sudo apt install -y nginx
ls -l /etc/nginx/sites-enabled/الملف الرئيسي هو /etc/nginx/nginx.conf. يضبط الخيارات العامة داخل كتلة http { }، ثم يضم محتويات الدليلين /etc/nginx/conf.d/*.conf و/etc/nginx/sites-enabled/*. في Ubuntu وDebian، تنشئ ملفاً واحداً لكل موقع داخل /etc/nginx/sites-available/، ثم تفعّله بإنشاء رابط رمزي له داخل /etc/nginx/sites-enabled/. يؤدي حذف الرابط الرمزي إلى تعطيل الموقع مع الإبقاء على الملف.
لا تعمل التوجيهات المستخدمة لاحقاً إلا في سياق http، ولا تعمل مطلقاً داخل كتلة server: map وupstream. ضع هذه التوجيهات في ملف مستقل داخل /etc/nginx/conf.d/، لأن هذا الدليل مُضمَّن على مستوى http.
تأتي الحزمة مع موقع مفعّل اسمه default. وهو معلَّم بوسم default_server، ما يعني أنه يستجيب لأي طلب لا يطابق رأس Host قيمة server_name في أي مكان ضمن إعداداتك. ما دام مفعّلاً، ستصل الطلبات التي لا تطابق أسماء نطاقك إلى هذا الموقع بدلاً من تطبيقك. احذف الرابط الرمزي بعد التأكد من عمل موقعك.
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginxأصغر كتلة خادم توجّه الطلبات إلى تطبيق واحد
server {
listen 80;
listen [::]:80;
server_name app.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
}
}احفظها باسم /etc/nginx/sites-available/app.example.com، ثم فعّلها وحمّلها.
sudo ln -s /etc/nginx/sites-available/app.example.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
curl -sI -H 'Host: app.example.com' http://127.0.0.1/يربط listen 80; اتصالات IPv4، بينما يربط listen [::]:80; اتصالات IPv6. إذا حذفت السطر الثاني، فسيُرفض كل اتصال IPv6 بخادمك. عادةً ما يعود المتصفح الذي يدعم المكدس المزدوج، والذي يعيد استعلام DNS الخاص به سجل AAAA، إلى IPv4 ويخفي المشكلة. لكن الزائر الذي يستخدم IPv6 فقط، أو العميل الذي يجرّب العنوان الأول فقط من العناوين التي يحصل عليها، يرى رفضاً للاتصال، بينما يرى جميع المستخدمين عبر IPv4 موقعاً يعمل. ستكون رسالة الخطأ التي تصلك: "يعمل لدي".
تتم مطابقة server_name مع ترويسة Host التي يرسلها المتصفح. يمكنك إدراج عدة أسماء تفصل بينها مسافات. إذا لم تطابق أي كتلة، يستخدم nginx الكتلة التي تحمل default_server، ولهذا كان يجب إزالة الموقع المضمّن مع الحزمة.
location / هي مطابقة بادئة لمسار الطلب، بينما تطابق / كل المسارات. يحدد proxy_pass العنوان الذي يفتح nginx اتصالاً به. أبقِ التطبيق مرتبطاً بالعنوان 127.0.0.1، بحيث يمر المسار الوحيد إلى التطبيق عبر nginx. إذا كان التطبيق يعمل داخل حاوية، فانشره على 127.0.0.1:3000:3000 وليس على 3000:3000، لأن يكتب Docker قواعده الخاصة وينشر المنافذ متجاوزاً ufw مباشرة، ولذلك يمكن الوصول إلى منفذ منشور عارٍ من الإنترنت مهما كانت إعدادات ufw. يوضّح Docker أن سلسلة DOCKER-USER هي المكان المخصص لتصفية حركة المرور هذه، لكن ربط التطبيق بالعنوان 127.0.0.1 هو الحل الأبسط.
يرسل السطر curl ترويسة Host الصحيحة من الخادم نفسه، لذلك يمكنك اختبار الكتلة قبل أن يشير DNS إلى أي مكان.
ما يرسله nginx إلى الخادم الخلفي عندما لا تكتب أي إعدادات أخرى
يُخفي proxy_pass وحده أربعة أمور عن تطبيقك.
تتحدث حزمة nginx 1.24.0 التي تأتي مع Ubuntu 24.04 مع الخادم الخلفي باستخدام HTTP/1.0 افتراضياً، وترسل Connection: close. لذلك يفتح كل طلب اتصالاً جديداً بالخادم الخلفي، ولا يمكن إجراء ترقية للبروتوكول. غيّر nginx 1.29.7، الذي صدر في مارس 2026، هذه القيم الافتراضية: بدءاً من هذا الإصدار، يتحدث nginx مع الخادم الخلفي باستخدام HTTP/1.1، ولا يرسل ترويسة Connection، ويعيد استخدام الاتصالات المجمّعة بدلاً من فتح اتصال جديد لكل طلب. وحتى في هذه الحالة، ما زلت تحتاج إلى ترويسات ترقية WebSocket الموضحة أدناه.
تُعاد كتابة ترويسة Host إلى القيمة الموجودة في proxy_pass، وهي 127.0.0.1:3000. لذلك ينشئ التطبيق الذي يبني الروابط المطلقة من Host روابط لا يستطيع أي شخص خارج الخادم فتحها.
يصل الاتصال إلى التطبيق من nginx، ولذلك يرى التطبيق عنوان العميل على أنه 127.0.0.1. عندئذ يسجّل كل سطر في السجل وكل حد لمعدل الطلبات داخل التطبيق عنوان الـproxy بدلاً من عنوان الزائر.
لا يستطيع التطبيق معرفة أن المتصفح استخدم HTTPS، لأن الاتصال الذي استلمه هو اتصال HTTP عادي على عنوان loopback.
تُصلح أربعة أسطر كل ذلك.
الرؤوس الأربعة التي يجب ضبطها، وما الذي يتيح كل منها للخلفية رؤيته
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}Host يحمل الاسم الذي أدخله الزائر. $host هو الاسم الوارد في الطلب، بعد إزالة المنفذ وتحويل الأحرف إلى صغيرة. اضبطه كي ينشئ تطبيقك عناوين مطلقة صحيحة، مثل إعادة التوجيه بعد تسجيل الدخول أو الرابط الموجود في رسالة إعادة تعيين كلمة المرور. إذا حذفته، فسيتخذ التطبيق 127.0.0.1:3000 اسماً له. يعيد proxy_redirect الافتراضي في nginx كتابة رأس Location أو Refresh يشير إلى العنوان proxy_pass، لذلك تصل إعادة التوجيه العادية بعد تسجيل الدخول عادةً إلى المكان الصحيح. لكن العناوين المطلقة التي يكتبها التطبيق في صفحاته ورسائله، مثل رابط إعادة تعيين كلمة المرور، تشير إلى 127.0.0.1:3000، وهو عنوان لا يستطيع متصفح الزائر فتحه. إذا كان تطبيقك يحتاج إلى المنفذ أيضاً، لأنك تخدمه على 8080، فاستخدم $http_host، وهو الرأس كما أرسله العميل تماماً.
X-Real-IP يحمل قيمة واحدة: $remote_addr، وهو العنوان الذي قبل nginx الاتصال منه. تقرأه التطبيقات في سجلات الوصول الخاصة بها ولتطبيق تحديد معدل الطلبات الخاص بها.
X-Forwarded-For يحمل قائمة. يضيف $proxy_add_x_forwarded_for القيمة $remote_addr إلى ما وضعه العميل مسبقاً في ذلك الرأس، لذلك تكون القيمة مفصولة بفواصل، ويكون الإدخال الذي أضافه nginx هو الأخير. تحدد هذه التفاصيل ما إذا كان يمكن الوثوق بالرأس: يستطيع العميل إرسال أي X-Forwarded-For يريده، لذلك يمكن إخبار تطبيق يقرأ الإدخال الأول بأي عنوان. عندما يكون nginx هو خادم الحافة، اكتب $remote_addr بدلاً من ذلك وتجاهل نسخة العميل. عندما توجد CDN أو وحدة proxy أخرى أمامه، استخدم set_real_ip_from وreal_ip_header من وحدة realip، بحيث يصبح $remote_addr نفسه عنوان العميل الحقيقي.
X-Forwarded-Proto يحمل http أو https. تقرأ أطر العمل هذه القيمة لتقرر ما إذا كانت ستضع على ملفات تعريف الارتباط السمة Secure وما إذا كانت ستفرض إعادة التوجيه إلى HTTPS. إذا حذفتها من موقع TLS وكان التطبيق مضبوطاً لفرض HTTPS، فسيرى http، ويرد بإعادة توجيه إلى عنوان HTTPS، ثم يتلقى الطلب التالي عبر nginx، ويظل يرى http، ويعيد التوجيه مرة أخرى. عندها يتوقف المتصفح عن المحاولة ويعرض ERR_TOO_MANY_REDIRECTS.
يؤدي تكرار هذه الأسطر الأربعة في كل location إلى اختلافها بمرور الوقت. ضعها في ملف واحد ثم أدرجه.
# /etc/nginx/snippets/proxy-headers.conf
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
}توجد هنا مشكلة في الوراثة. يرث location توجيهات proxy_set_header من كتلة server فقط ما دام لا يعرّف أي توجيهات خاصة به. إذا أضفت proxy_set_header واحداً داخل location، فستُحذف كل الرؤوس المعرّفة على مستوى server من ذلك location. لذلك أبقِ جميع الرؤوس على مستوى واحد، أو include المقتطف في كل location يستخدم proxy.
لماذا يتصل تطبيق WebSocket ثم ينقطع؟
لأن الإعدادات الافتراضية تمنع الترقية، ولأن مهلة القراءة الافتراضية تغلق النفق الخامل بعد 60 ثانية. يبدأ WebSocket كطلب HTTP يحتوي على Upgrade: websocket وConnection: Upgrade. هذان رأسا hop-by-hop، ما يعني أن من المتوقع أن يستهلكهما الـproxy بدلاً من تمريرهما. وفي nginx 1.24.0 على Ubuntu 24.04، يكون بروتوكول الاتصال بالخادم الخلفي افتراضياً هو HTTP/1.0، الذي لا يوفّر آلية للترقية أصلاً. يجب إعادة تفعيل الأمرين يدوياً.
يوضع map في سياق http، داخل ملف مستقل.
# /etc/nginx/conf.d/websocket.conf
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}ثم أضف location.
location / {
include snippets/proxy-headers.conf;
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}يُستخدم map حتى يتمكن location واحد من خدمة نوعي حركة المرور. في الطلب العادي يكون $http_upgrade فارغاً، لذلك يصبح $connection_upgrade هو close. أما في طلب الترقية، فيحتوي على websocket، ولذلك يصبح الرأس المرسل إلى الخادم الخلفي هو Connection: upgrade. يؤدي تثبيت proxy_set_header Connection "upgrade"; إلى إرسال هذا الرأس مع كل طلب صفحة عادي أيضاً، وقد يعيد بعض الخوادم الخلفية 400 عند تلقي مثل هذا الطلب.
يكون proxy_http_version 1.1; هو الإعداد الافتراضي ابتداءً من nginx 1.29.7، ولذلك لا يغيّر السطر شيئاً ولا يسبب ضرراً في هذه الإصدارات. أما في حزمة 1.24.0، فهو مطلوب. ويجب استخدام السطرين Upgrade وConnection في كل إصدار، لأن nginx لا يمرر هذين الرأسين تلقائياً.
يتسبب proxy_read_timeout في ظهور تقارير من نوع "يُحمّل ثم يتوقف عن التحديث". قيمته الافتراضية 60 ثانية، وهو يقيس الفاصل بين قراءتين من الخادم الخلفي، وليس مدة بقاء الاتصال. إذا بقي WebSocket بلا نشاط لمدة 60 ثانية، يغلقه nginx، وتعرض وحدة تحكم المتصفح إغلاق المقبس بالرمز 1006. لا تلاحظ التطبيقات التي ترسل إشارة نبض خاصة بها بوتيرة أعلى من مرة كل دقيقة المشكلة. أما التطبيقات التي لا تفعل ذلك، فتنقطع بعد دقيقة واحدة. تظهر المشكلة أولاً في المحررات المباشرة ولوحات المعلومات، ومن الأمثلة الشائعة مثيل n8n مستضاف ذاتياً خلف HTTPS.
لماذا تغيّر الشرطة المائلة النهائية في proxy_pass عناوين URL؟
القاعدة في جملة واحدة: إذا انتهى proxy_pass بمسار URI، حتى إذا كان مجرد /، فإن nginx يزيل جزء مسار الطلب الذي طابق البادئة location، ويضع URI مكانه. أما إذا توقف proxy_pass عند المضيف والمنفذ، فيمرّر مسار الطلب كما هو دون تغيير.
location /app/ {
proxy_pass http://127.0.0.1:3000/;
}يصل طلب /app/status إلى الواجهة الخلفية بصيغة /status.
location /app/ {
proxy_pass http://127.0.0.1:3000;
}يصل طلب /app/status إلى الواجهة الخلفية بصيغة /app/status.
يعتمد الشكل المطلوب على التطبيق. يحتاج التطبيق الذي يضبط base-path أو المجلد الفرعي إلى الشكل الثاني، مع تعريف /app في هذا الإعداد. أما التطبيق الذي لا يعرف شيئاً عن البادئات فيحتاج إلى الشكل الأول. وللشكل الأول كلفة تظهر مباشرة: يظل HTML الذي يعيده التطبيق متضمناً مسارات مطلقة مثل /static/main.css، فيطلبها المتصفح من جذر الموقع، ولا يطابقها أي location، فتُعرض الصفحة من دون تنسيق. تعرض علامة تبويب الشبكة في المتصفح طلبات هذه الملفات مع الاستجابة 404. يتمثل الإصلاح في ضبط base-path الخاص بالتطبيق، أو إضافة location /static/ ثانية تشير إلى الواجهة الخلفية نفسها.
لا يمكن لـlocation الذي يستخدم تعبيراً نمطياً أن يتضمن URI في proxy_pass. يرفض sudo nginx -t الإعداد ويذكر السبب: "proxy_pass" cannot have URI part in location given by regular expression, or inside named location, or inside "if" statement, or inside "limit_except" block.
تختفي هذه الفئة كاملة من المشكلات عندما يحصل كل تطبيق على اسم خاص به، وهو app.example.com، ويُمرَّر عبر proxy من location /. لا تستحق المسارات الفرعية هذا التعقيد إلا عندما يتعذر عليك إضافة سجلات DNS.
كيف أضع أكثر من خادم خلفي واحداً باستخدام اسم واحد؟
باستخدام كتلة upstream. تنتمي هذه الكتلة إلى سياق http، لذلك اكتبها قبل كتلة server في الملف نفسه، أو في /etc/nginx/conf.d/.
upstream app_backend {
least_conn;
server 127.0.0.1:3000 max_fails=3 fail_timeout=30s;
server 127.0.0.1:3001 max_fails=3 fail_timeout=30s;
keepalive 32;
}تستخدم كتلة location هذا الاسم: proxy_pass http://app_backend;.
الطريقة الافتراضية هي round robin. يرسل least_conn كل طلب إلى الخادم الخلفي الذي لديه أقل عدد من الاتصالات النشطة، وهذا يناسب الطلبات ذات المدد المختلفة. يربط ip_hash عنوان عميل واحداً بخادم خلفي واحد. تحتاج إلى ip_hash عندما يحتفظ التطبيق بالجلسات في ذاكرته الخاصة، لأن توزيع الطلبات بالتناوب على خادمين من هذا النوع يؤدي إلى تسجيل خروج المستخدمين عشوائياً عندما تصل طلباتهم إلى النسخة التي لم تتعامل معها من قبل. نقل الجلسات إلى مساحة تخزين مشتركة هو الحل الأفضل.
يعني max_fails=3 fail_timeout=30s أن 3 محاولات فاشلة خلال 30 ثانية تخرج ذلك الخادم من الخدمة لمدة 30 ثانية. عندما تكون جميع الخوادم في الكتلة بهذه الحالة، يتلقى العملاء الخطأ 502، ويذكر سجل الأخطاء no live upstreams while connecting to upstream.
تُبقي keepalive 32 ما يصل إلى 32 اتصالاً خاملاً مفتوحاً مع الخوادم الخلفية لكل عملية worker، مما يلغي عملية مصافحة TCP من معظم الطلبات. في Ubuntu 24.04 بإصدار 1.24.0، هذا السطر هو ما يفعّل التخزين المؤقت. منذ nginx 1.29.7، يكون التخزين المؤقت مفعّلاً افتراضياً، لكن القيمة الافتراضية الموثقة هي keepalive 32 local;، وتمنع معلمة local مشاركة الاتصالات المخزنة مؤقتاً بين مواقع مختلفة. لذلك، في الإصدار 1.29.7 والإصدارات الأحدث، لا يقتصر keepalive 32; المجرد على إعادة ذكر القيمة الافتراضية: فعند حذف local، يسمح لأي موقع يمرر الطلبات إلى خادم upstream نفسه بإعادة استخدام اتصال من تجمع الاتصالات، وهذا يغيّر السلوك الافتراضي. في هذه الإصدارات، اترك السطر محذوفاً أو اكتب keepalive 32 local; للحفاظ على القيمة الافتراضية، واكتب الصيغة المجردة فقط إذا أردت تفعيل هذه المشاركة. معلمة local جديدة في الإصدار 1.29.7، لذلك لا تقبلها حزمة 1.24.0. بالنسبة إلى خوادم HTTP الخلفية، توصي nginx بإعداد التجمع بحيث تكون proxy_http_version مضبوطة على 1.1، أو 2 في nginx 1.29.4 والإصدارات الأحدث، مع حذف ترويسة Connection عند إرسالها إلى الخادم الخلفي. توثّق nginx أيضاً الاتصالات المستمرة باستخدام HTTP/1.0، وذلك بإرسال Connection: Keep-Alive إلى خادم خلفي يدعمها، لكنها لا توصي بهذه الطريقة. منذ 1.29.7، يصبح كلا جزأي الإعداد الموصى به قيمة افتراضية. في 1.24.0، أضف proxy_http_version 1.1; وproxy_set_header Connection ""; إلى location بنفسك، وإلا ستستمر nginx في إرسال HTTP/1.0 مع Connection: close ولن يُعاد استخدام التجمع. إذا كان location نفسه يستخدم أيضاً WebSocket map، فغيّر الحالة الفارغة من close إلى سلسلة فارغة، حتى لا تحمل الطلبات العادية ترويسة Connection ويُعاد استخدام الاتصال من التجمع.
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}تُحل الأسماء داخل كتلة upstream عند بدء nginx. إذا كان الخادم الخلفي عبارة عن حاوية تحصل على عنوان جديد عند إعادة تشغيلها، فستستمر nginx في استخدام العنوان القديم إلى أن تعيد تحميل إعداداتها. يمكن للإصدار 1.27.3 والإصدارات الأحدث متابعة هذه التغييرات دون إعادة تحميل، عبر resolver، وإضافة zone في كتلة upstream، وإضافة المعلمة resolve إلى كل سطر server، لكن حزمة 1.24.0 أقدم من هذه الميزة. داخل شبكة Docker، يمكنك نقل عملية البحث عن العنوان إلى وقت الطلب باستخدام embedded resolver.
resolver 127.0.0.11 valid=10s;
set $backend http://app:3000;
proxy_pass $backend;عندما تبدأ الحاويات في الظهور والاختفاء بوتيرة تجعلك تعدّل nginx باستمرار لمواكبتها، يكون استخدام proxy يقرأ labels الخاصة بالحاويات أفضل. يبني Traefik أمام عدة تطبيقات Docker Compose مساراته من الحاويات نفسها.
لماذا تفشل عمليات الرفع مع الخطأ 413 Request Entity Too Large؟
يكون الإعداد الافتراضي لـ client_max_body_size هو 1 ميغابايت. يرفض nginx جسم طلب أكبر من ذلك بالخطأ 413، ويسجل سجل الأخطاء client intended to send too large body. ارفع القيمة في server block، أو في location التي تحدث فيها عمليات الرفع.
client_max_body_size 512m;تؤدي قيمة 0 إلى تعطيل الفحص بالكامل. مع 512m، يواصل nginx رفض أجسام الطلبات التي تتجاوز هذا الحد، لذلك لا يثبت استمرار ظهور الخطأ 413 بعد هذا التغيير أن مصدره هو الخادم الخلفي. تحقّق من القيمة الفعلية لـ client_max_body_size في location التي تعالج الرفع، وراجع سجل أخطاء nginx، قبل فحص حد الرفع الخاص بالتطبيق.
يقرأ nginx جسم الطلب بالكامل افتراضياً قبل أن يفتح اتصالاً بالخادم upstream، ويكتب الأجزاء الكبيرة أولاً في ملف مؤقت على القرص. يحمي ذلك التطبيق من العملاء البطيئين، لأن الخادم الخلفي يستقبل الرفع بالسرعة المحلية الكاملة. ويمكنك استخدام البث بدلاً من ذلك عند التعامل مع عمليات الرفع الكبيرة جداً.
proxy_request_buffering off;بالنسبة إلى عمليات الرفع المقطعة وفق HTTP/1.1 في الحزمة 1.24.0، اضبط proxy_http_version 1.1; أيضاً في تلك location، وإلا فسيواصل nginx تخزين الجسم مؤقتاً. يستقبل الخادم الخلفي الجسم أثناء وصوله، ولذلك يجب أن يكون قادراً على معالجته بهذه الطريقة. بعد أن يبدأ nginx بإرسال الجسم إلى الخادم upstream، لا يمكنه إعادة محاولة الطلب مع خادم upstream آخر.
ينطبق client_body_timeout، الذي تبلغ قيمته الافتراضية 60 ثانية، بين قراءتين متتاليتين للجسم، وليس على عملية الرفع كاملة. تستمر عملية الرفع البطيئة والثابتة. أما العملية المتوقفة مؤقتاً فتُسقط.
التخزين المؤقت للاستجابات، والإعداد الذي يعطّل الإخراج المباشر
يكون proxy_buffering مفعّلاً افتراضياً، وهو عادةً الإعداد المطلوب. يقرأ nginx الاستجابة من تطبيقك بالسرعة التي يستطيع التطبيق الكتابة بها، ويحتفظ بها، ثم يرسلها إلى العميل البطيء وفق سرعته. ينهي عامل التطبيق عمله مبكراً بدلاً من أن يظل مشغولاً طوال عملية التنزيل البطيئة.
لكن هذا يعطّل الاستجابات المتدفقة. لا تعرض Server-sent events وإخراج السجلات المباشر أي شيء للقارئ إلى أن يمتلئ أحد المخازن المؤقتة. عطّل التخزين المؤقت في ذلك الموضع فقط.
proxy_buffering off;إذا كنت تتحكم في التطبيق، فالأفضل أن يرسل الترويسة X-Accel-Buffering: no مع الاستجابات المتدفقة فقط. يقرأ nginx هذه الترويسة لكل استجابة، ويعطّل التخزين المؤقت لها وحدها، بينما تحتفظ الصفحات العادية بفائدته.
عندما يعرض سجل الأخطاء upstream sent too big header while reading response header from upstream، فهذا يعني أن ترويسات الاستجابة لم تتسع لها ذاكرة مؤقتة واحدة. تكون قيمة proxy_buffer_size افتراضياً بحجم صفحة ذاكرة واحدة، أي 4 أو 8 كيلوبايت وفقاً للمنصة، وقد تتجاوزها ملفات تعريف ارتباط طويلة أو ترويسات مصادقة كبيرة. ارفع القيمتين.
proxy_buffer_size 16k;
proxy_buffers 8 16k;أين يجب وضع TLS في هذا الإعداد؟
في Nginx، أمام كل ما سبق. تنتهي جلسة TLS (أمن طبقة النقل) عند الـproxy، ويبقى الاتصال من Nginx إلى التطبيق عبر HTTP عادي باستخدام عنوان loopback، حيث لا يمكن لأي جهة أخرى على الشبكة قراءته. يعرف التطبيق أن الزائر استخدم HTTPS من خلال X-Forwarded-Proto، وهو الرابع ضمن الرؤوس الأربعة.
لا تكتب مسارات الشهادات يدوياً. وجّه سجل DNS إلى الخادم، وافتح المنفذ في جدار الحماية، ودَع Certbot يعدّل كتلة الخادم نفسها: سيضيف السطر listen 443 ssl مع المسارات ssl_certificate، إضافةً إلى إعادة التوجيه من المنفذ 80. يشرح إصدار شهادة Let's Encrypt لـNginx باستخدام Certbot عملية الإصدار ومؤقت التجديد.
sudo ufw allow 'Nginx Full'
sudo ufw statusNginx Full هو ملف تعريف لتطبيق يثبّته حزمة Nginx، ويفتح المنفذين 80 و443 معاً. يجب أن يبقى المنفذ 80 مفتوحاً لتحدي التجديد HTTP-01، حتى بعد إعادة توجيه كل زائر إلى HTTPS.
اختبر الإعدادات، ثم أعد التحميل
sudo nginx -t
sudo systemctl reload nginxيفحص nginx -t كل ملف مضمّن، ثم يعرض نجاح الاختبار أو يطبع اسم الملف ورقم السطر الذي توقف عنده. اقرأ هذه النتيجة قبل إعادة التحميل. لا تُطبّق إعادة التحميل إعدادات معطّلة؛ يواصل nginx تقديم الخدمة باستخدام الإعدادات السابقة، لذلك يبقى الموقع متاحاً بينما لا يُطبَّق التغيير بصمت. يعمل systemctl restart بطريقة مختلفة وأسوأ، لأن إعادة التشغيل توقف الخادم العامل أولاً، ولذلك قد يتركك خطأ الإعدادات مع توقف nginx بالكامل. استخدم إعادة التحميل افتراضياً، واحتفظ بإعادة التشغيل للتغييرات النادرة التي تتطلبها.
sudo tail -f /var/log/nginx/error.log
sudo ss -lntp | grep -E ':(80|443|3000)'يوضح السطر ss العملية التي تشغل كل منفذ، ولذلك يمكنك التأكد من أن التطبيق يستمع فعلاً على العنوان الذي يشير إليه proxy_pass.
حالات الفشل التي ستواجهها فعلياً
502 Bad Gateway، مع ظهور connect() failed (111: Connection refused) while connecting to upstream في سجل الأخطاء. لا توجد أي خدمة تستمع على العنوان المحدد في proxy_pass. قد يكون التطبيق متوقفاً، أو مرتبطاً بمنفذ آخر، أو مرتبطاً بعنوان داخلي لحاوية لا يستطيع المضيف الوصول إليه.
502 مع ظهور no live upstreams while connecting to upstream. يضع max_fails حالياً علامة فشل على كل خادم في الكتلة upstream. أصلح الخوادم الخلفية. يعاود nginx محاولة الاتصال بها بعد انتهاء fail_timeout.
504 Gateway Time-out، مع ظهور upstream timed out (110: Connection timed out) while reading response header from upstream. قبل الخادم الخلفي الاتصال، ثم لم يرسل أي بيانات طوال proxy_read_timeout ثانية. تكون زيادة مهلة الانتظار صحيحة عند إنشاء تقرير بطيء فعلاً، لكنها ليست الحل لتطبيق متعطل.
يعيد التطبيق 404 لكل مسار. أعادت قاعدة الشرطة المائلة اللاحقة كتابة المسار. قارن المسار الذي يسجله التطبيق بالمسار الذي طلبته.
يستجيب موقع مختلف. لا يطابق server_name ترويسة Host، لذلك انتقل الطلب إلى كتلة default_server.
تُحمّل الصفحة، ثم تتجمد الواجهة بعد نحو دقيقة. هذه حالة WebSocket: إعداد التعامل مع Upgrade مفقود، أو أن proxy_read_timeout ما زال مضبوطاً على 60 ثانية.
FAQ
لماذا يعرض nginx الخطأ 502 Bad Gateway بعد إضافة proxy_pass؟
تعذّر على nginx فتح اتصال بالعنوان الموجود في proxy_pass. يوضح سجل الأخطاء في /var/log/nginx/error.log السبب: يعني connect() failed (111: Connection refused) while connecting to upstream أنه لا توجد أي خدمة تستمع على ذلك العنوان، ويعني no live upstreams أنه تم وضع علامة فشل على كل خادم في كتلة upstream. شغّل sudo ss -lntp | grep 3000 لمعرفة العملية التي تشغل المنفذ والعنوان المرتبطة به. يؤدي ربط التطبيق بعنوان داخلي للحاوية، أو بمنفذ يختلف عن المنفذ الذي كتبته، إلى ظهور هذا الخطأ في كل مرة.
لماذا ينقطع اتصال تطبيقي بعد نحو دقيقة عند تشغيله خلف nginx؟
الاتصال هو WebSocket، وما زالت قيمة proxy_read_timeout مضبوطة على الإعداد الافتراضي البالغ 60 ثانية، وهي تقيس الفاصل بين عمليتي قراءة من الواجهة الخلفية. يغلق nginx المقبس الخامل، ويعرض سجل المتصفح رمز الإغلاق 1006. اضبط proxy_http_version 1.1، وهو الإعداد الافتراضي منذ nginx 1.29.7، لكنه غير موجود في الحزمة 1.24.0 التي توفّرها Ubuntu 24.04، ومرّر Upgrade وConnection باستخدام map على $http_upgrade، وارفع قيمة proxy_read_timeout إلى قيمة مثل 3600s. من دون ترويسة Upgrade، لا تتم الترقية أصلاً، ولذلك يعود التطبيق إلى الاستطلاع أو لا يعرض تحديثات مباشرة.
هل تؤثر الشرطة المائلة في نهاية proxy_pass؟
نعم، فهي تغيّر المسار الذي تستقبله الواجهة الخلفية. عند استخدام location /app/ وproxy_pass http://127.0.0.1:3000/، يصل طلب /app/status إلى الواجهة الخلفية بصيغة /status، لأن أي URI يأتي بعد المضيف والمنفذ يستبدل بادئة location المطابقة. إذا حذفت الشرطة المائلة الأخيرة، يصل الطلب نفسه بصيغة /app/status. يؤدي حذف البادئة غالباً إلى تعطيل روابط الأصول الخاصة بالتطبيق، إذ تبقى هذه الروابط مطلقة ثم تعيد 404 في جذر الموقع. لذلك يكون الشكل الذي يمرر المسار كما هو أنسب لتطبيق يملك إعداداً لمسار أساسي.
لماذا يسجل تطبيقي 127.0.0.1 عنوان IP لكل زائر؟
لأن الاتصال الذي يستقبله التطبيق يأتي فعلاً من nginx على عنوان loopback. لا يصل عنوان الزائر إلى التطبيق إلا في ترويسة تضبطها أنت: proxy_set_header X-Real-IP $remote_addr; لقيمة واحدة، وproxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; للسلسلة المضافة. بعد ذلك يجب ضبط التطبيق ليثق بهذه الترويسات. تذكّر أن العميل يستطيع إرسال ترويسة X-Forwarded-For الخاصة به، ولذلك يجب على nginx، عندما يكون خادم الحافة، استبدالها بـ$remote_addr بدلاً من إلحاق قيمة بها.
هل أحتاج إلى TLS على الاتصال بين nginx وتطبيقي؟
ليس عندما يعمل التطبيق على الخادم نفسه ويستمع على 127.0.0.1، لأن هذه الحركة لا تغادر الجهاز. أنهِ TLS عند nginx، وأبقِ proxy_pass على HTTP عادي عبر loopback، وأرسل X-Forwarded-Proto $scheme حتى يعرف التطبيق أن الزائر استخدم HTTPS. إذا كانت الواجهة الخلفية موجودة على مضيف مختلف عبر شبكة لا تتحكم بها، فيحتاج هذا المسار إلى حماية مستقلة، إما باستخدام HTTPS إلى الواجهة الخلفية أو نفق خاص بين الجهازين.