إعداد Nginx Reverse Proxy للإنتاج: قائمة مراجعة عملية

تبدأ إعدادات Nginx أمام تطبيق Node أو Laravel أو خدمة داخل حاوية بعدة أسطر. لكن بيئة الإنتاج تحتاج قرارات واضحة لأن Nginx يتحكم في هوية العميل والبروتوكول وحجم الطلب والمهل والتخزين المؤقت وجزء من تجربة الخطأ.

استخدم هذه القائمة بعد أن يعمل الاتصال الأساسي وقبل توجيه النطاق أو فتح الخدمة للجمهور.

ابدأ بإعداد صغير يمكن تفسيره

عرّف الخدمة الخلفية في موضع واضح، ثم مرر الطلب إليها:

upstream app_backend {
    server 127.0.0.1:3000;
    keepalive 32;
}

server {
    listen 443 ssl;
    server_name example.com;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;
    }
}

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

شغّل دائماً:

sudo nginx -t
sudo systemctl reload nginx

يفحص الأمر الأول تركيب الإعداد، لكن نجاحه لا يثبت أن Nginx يستطيع الاتصال بالخدمة الخلفية.

مرر هوية الطلب الأصلية بأمان

يحتاج التطبيق عادة إلى اسم المضيف والبروتوكول وتسلسل عناوين العميل:

location / {
    proxy_pass http://app_backend;
    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;
}

يجب أن يثق التطبيق بهذه العناوين فقط عندما يأتي الطلب عبر وكلاء معروفين. الثقة العمياء في X-Forwarded-For تسمح لعميل مباشر باختراع عنوانه.

إذا كان Cloudflare أو موازن أحمال أمام Nginx، حدد نطاقات الوكيل الموثوق واضبط Real IP Module وفق البنية الفعلية. اختبر عنواناً معروفاً في سجل التطبيق بدلاً من افتراض أن أول قيمة في السلسلة هي المستخدم.

اضبط المهل وفق سلوك كل مسار

المهلة تحدد مدة حجز الاتصال والفشل الذي يراه العميل. ابدأ بقيم محدودة وخصص الاستثناء للمسار الذي يحتاجه:

location /api/ {
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;
    proxy_pass http://app_backend;
}

لا ترفع كل المهل إلى عدة دقائق لأن تقريراً واحداً بطيء. انقل العمل الطويل إلى طابور، وأعد معرفاً للحالة، ثم وفر تنزيلاً عند اكتماله.

عند ظهور 502 Bad Gateway أو upstream timed out اقرأ سجل Nginx والخدمة الخلفية قبل تعديل القيم. اتبع دليل تشخيص خطأ 502 بين Nginx وPHP-FPM عندما تكون PHP هي الخدمة الخلفية.

حدد حجم الطلب في أضيق نطاق

طلبات JSON الصغيرة لا تحتاج إلى حد رفع ملفات ضخم. ضع client_max_body_size داخل location الخاصة بالرفع إن أمكن:

location /uploads/ {
    client_max_body_size 25m;
    proxy_pass http://app_backend;
}

طابق هذا الحد مع CDN وPHP والتطبيق. أصغر حد في المسار هو الذي يحدد النتيجة. يشرح حل خطأ 413 Request Entity Too Large طريقة تحديد الطبقة التي رفضت الملف.

راجع أيضاً التخزين المؤقت لجسم الطلب ومساحة القرص المؤقت عند استقبال ملفات كبيرة متزامنة.

أكمل إعداد WebSocket عند الحاجة فقط

إذا استخدم التطبيق WebSocket، مرر ترقية الاتصال:

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

location /socket/ {
    proxy_pass http://app_backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
}

اختبر اتصالاً طويلاً وإعادة الاتصال بعد نشر الخدمة. لا تضف رؤوس الترقية إلى كل المسارات بلا حاجة.

أنهِ TLS وسياسة التحويل بعناية

استخدم إصدارات TLS الحديثة، وشهادة تغطي الأسماء المطلوبة، وتجديداً آلياً اختُبر قبل موعد الانتهاء. يجب أن يحول منفذ HTTP إلى HTTPS مع الحفاظ على المسار والاستعلام:

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

لا تضف HSTS قبل التأكد أن النطاق وكل النطاقات الفرعية التي ستشملها السياسة تعمل عبر HTTPS دائماً. أما Content Security Policy فتحتاج اختباراً ورصد انتهاكات قبل فرضها.

اجعل ملكية رؤوس الحماية واضحة حتى لا يرسل التطبيق وNginx سياسات متعارضة.

اجعل فشل الخدمة الخلفية صريحاً

عندما يتوقف التطبيق، أعد صفحة خطأ صغيرة بالحالة الصحيحة. لا تعرض رسالة نجاح لطلب كتابة لم يصل إلى الخدمة، ولا تعِد المحاولة تلقائياً لطلب غير آمن قد ينفذ مرتين.

استخدم أكثر من نسخة للخدمة فقط عندما تدعم الجلسات والملفات المشتركة ذلك. موازنة الحمل لا تصلح جلسة مخزنة على قرص نسخة واحدة.

أضف نقطة صحة خفيفة تثبت أن العملية جاهزة لاستقبال الطلبات. ولا تجعلها تنفذ استعلاماً مكلفاً أو اتصالاً خارجياً في كل ثانية.

سجل ما تحتاجه للتشخيص

السجل التشغيلي المفيد يتضمن الحالة وزمن الطلب وزمن الخدمة الخلفية وعنوانها ومعرف الطلب والطريقة والمسار:

log_format upstream_timing '$request_id $remote_addr "$request" '
  'status=$status request_time=$request_time '
  'upstream=$upstream_addr upstream_time=$upstream_response_time';

مرر معرف الطلب إلى التطبيق ليظهر في السجلين. لا تسجل رؤوس التفويض أو Cookies أو استعلامات تحمل رموزاً سرية.

ضع تدويراً ومدة احتفاظ، وراقب مساحة القرص. امتلاء الخادم بسبب سجل Debug مشكلة تشغيلية بحد ذاتها.

اختبر الحدود لا الصفحة الرئيسية فقط

قبل الإطلاق اختبر:

1. طلباً عادياً وخدمة خلفية متوقفة.
2. خدمة تستجيب ببطء ثم تتجاوز المهلة.
3. ملفاً أسفل حد الرفع وآخر فوقه.
4. عنوان العميل الحقيقي عبر كل الوكلاء.
5. تحويل HTTP إلى HTTPS وشهادة النطاق وتجديدها.
6. WebSocket وإعادة الاتصال إن كانت مستخدمة.
7. إلغاء العميل للطلب أثناء المعالجة.
8. ظهور معرف الطلب نفسه في سجل Nginx والتطبيق.

استخدم curl من خارج الخادم ومن داخله حتى تفرق بين مشكلة DNS أو CDN ومشكلة الاتصال بالخدمة المحلية.

أخطاء شائعة

• نسخ إعداد طويل من مشروع آخر من دون معرفة وظيفة كل سطر.
• الثقة في أي X-Forwarded-For قادم من الإنترنت.
• رفع المهلة العامة لعلاج مهمة واحدة غير مناسبة للطلب المتزامن.
• إضافة HSTS قبل تجهيز كل النطاقات الفرعية.
• تسجيل بيانات اعتماد أو Query Strings حساسة.
• إعادة تحميل Nginx من دون nginx -t أو اختبار المسار الأصلي.

أسئلة شائعة

هل أستخدم proxy_pass باسم نطاق أم بعنوان محلي؟

استخدم ما يناسب بيئتك. داخل خادم واحد قد يكون عنوان Loopback واضحاً. داخل Docker أو Kubernetes استخدم اسم الخدمة وآلية الاكتشاف المخصصة. المهم أن تفهم متى يحل Nginx الاسم وكيف يتعامل مع تغيّر العناوين.

هل يجب أن يضع Nginx كل رؤوس الحماية؟

ليس شرطاً. يمكن للتطبيق أو Edge إرسال بعضها. اختر مالكاً واحداً لكل سياسة وراجع النتيجة النهائية في الاستجابة حتى لا تتكرر القيم أو تتعارض.

كيف أعرف أن إعداد الوكيل جاهز للإنتاج؟

عندما تختبر النجاح والفشل، وتستطيع ربط طلب واحد بين السجلات، وتعرف حدود الحجم والمهلة، وتملك مراقبة وتجديد شهادة وخطة رجوع للإعداد.

مراجع رسمية

• وحدة HTTP Proxy في Nginx
• وحدة Real IP في Nginx
• إعداد HTTPS في Nginx

لديك سؤال عن هذا الدليل أو فكرة لتعاون تقني؟ تواصل مع بكري عبر المركز التقني.