وضع Nginx أمام تطبيق Node أو Python أو Java يمنحكم TLS وضغطاً ونقطة دخول عامة ثابتة. معظم المشاكل تأتي من ترويسات ناقصة وشرطة مائلة أخيرة خاطئة ومهلات قصيرة. يعرض هذا الدليل إعداد وكيل عكسي واضحاً ودعم WebSocket وروتيناً قصيراً لتشخيص أخطاء 502 و504. الأوامر وفق وثائق nginx؛ لم أشغّلها على خادمكم.
١. وكيل أساسي نظيف
عرّفوا upstream وأرسلوا الترويسات التي يحتاجها التطبيق واستخدموا HTTP/1.1 مع keepalive إلى الخلفية:
upstream app { server 127.0.0.1:3000; keepalive 16; }
server {
listen 80;
server_name app.example.com;
location / {
proxy_pass http://app;
proxy_http_version 1.1;
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;
proxy_set_header Connection "";
}
}
دون ترويسات Host وforwarded قد يولّد التطبيق روابط خاطئة أو يسجل عنوان الوكيل بدل الزائر.
٢. WebSocket
يحتاج WebSocket إلى ترويسات upgrade ومهلة قراءة أطول وإلا انقطعت الاتصالات بصمت:
location /ws/ {
proxy_pass http://app;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
}
استخدموا location منفصلاً لتبقى للطلبات العادية مهلاتها العادية. وقواعد ترتيب location مشروحة في دليل ترتيب location.
٣. اختبروا وشخّصوا
افحصوا الإعداد ثم اختبروا التطبيق مباشرة وعبر nginx. غالباً يعني 502 أن الخلفية متوقفة أو غير قابلة للوصول ويعني 504 أنها تأخرت:
sudo nginx -t && sudo systemctl reload nginx
curl -sI http://app.example.com/ | head -n 8
curl -s http://127.0.0.1:3000/ -o /dev/null -w '%{http_code}\n' # is the app itself up?
sudo tail -n 20 /var/log/nginx/error.log | grep -i -E 'upstream|connect'
تأكدوا أن التطبيق نفسه يعمل كخدمة؛ راجعوا دليل خدمة systemd.
٤. الأمان والحدود
اربطوا التطبيق بـ localhost ليصل إليه nginx فقط. وأضيفوا حدود معدل للمسارات الحساسة بـ دليل limit_req وأبقوا حجم الطلب معقولاً بـ client_max_body_size. ولا تقبلوا عنوان الزائر إلا من وكلاء موثوقين.
٥. أخطاء يجب تجنبها
هذه تسبب معظم المفاجآت:
proxy_pass http://app/; # trailing slash changes the forwarded path
no proxy_set_header Host # app sees 127.0.0.1 and builds wrong links
proxy_read_timeout 5s # long requests end in 504
أعيدوا التحميل فقط بعد نجاح nginx -t.
٦. مثال توضيحي وليس قياساً حقيقياً
افترضوا تطبيق Node (مختلقاً) يعمل على المنفذ 3000 لكنه يعرض نطاقاً خاطئاً في إعادات التوجيه خلف nginx. إضافة ترويستي Host وX-Forwarded-Proto تصلح الروابط. وميزة دردشة كانت تنقطع بعد دقيقة تُحل بـ location خاص بـ WebSocket ومهلة قراءة أطول.
٧. أخطاء شائعة
- نسيان ترويسة Host.
- خلط الشرطة المائلة الأخيرة في proxy_pass.
- مهلات قصيرة للطلبات الطويلة.
- كشف منفذ التطبيق للإنترنت.
- غياب ترويسات upgrade لـ WebSocket.
- إعادة التحميل دون nginx -t.
٨. أسئلة شائعة
ما سبب 502؟ الخلفية متوقفة أو رفضت الاتصال أو انهارت.
ما سبب 504؟ لم تجب الخلفية خلال المهلة.
هل أحتاج keepalive؟ يساعد الأداء بإعادة استخدام اتصالات الخلفية.
كيف يعرف التطبيق عنوان الزائر؟ عبر X-Forwarded-For المقروء من وكلاء موثوقين فقط.
٩. قائمة تحقق سريعة
- عرّفوا upstream.
- أرسلوا Host وترويسات العميل.
- استخدموا HTTP/1.1 وkeepalive.
- أضيفوا location لـ WebSocket عند الحاجة.
- اضبطوا مهلات مناسبة.
- اربطوا التطبيق بـ localhost.
- شغّلوا nginx -t وأعيدوا التحميل واختبروا.
إذا احتجتم إلى مساعدة في مراجعة الأداء أو صيانة الخادم، فراجعوا خدمات إدارة الخوادم.
تجدون المزيد من أدلة الخوادم وووردبريس في أرشيف المقالات.
المراجع الرسمية
nginx: ngx_http_proxy_module · nginx: WebSocket proxying · nginx: ngx_http_upstream_module · nginx: ngx_http_realip_module
