Nginx للمطورين: دليل الإعداد الذي ستضيفه فعلاً إلى قائمة المواقع المفضلة
تبدو ملفات تكوين Nginx وكأنها هيروغليفية حتى تفهم النمط الذهني وراءها. يشرح هذا الدليل الوظيفة الفعلية لكل توجيه، مع توفير ملفات تكوين جاهزة للنسخ واللصق لأكثر 5 إعدادات شيوعًا.
النموذج الذهني: Nginx هو غرفة البريد
تخيل أن Nginx عبارة عن غرفة بريد. تصل الطلبات إلى مكتب الاستقبال (المنفذ 80/443). تتحقق غرفة البريد من ملصق العنوان (server_name) لتوجيه الطلب إلى القسم المناسب (server block). وداخل القسم، تتحقق من سطر الموضوع (location) لتوجيه الطلب إلى الشخص المناسب (upstream/file).
هذا كل شيء. كل شيء في Nginx يتمثل في: مطابقة الطلب → القيام بشيء ما به.
التكوين 1: Next.js + Django خلف Nginx (الأكثر شيوعًا)
# Upstream blocks: define your app servers
upstream frontend {
server frontend_container:3000;
keepalive 16; # reuse connections (huge perf win)
}
upstream backend {
server backend_container:8000;
keepalive 8;
}
server {
listen 443 ssl;
server_name yourapp.com;
# SSL (Let's Encrypt)
ssl_certificate /etc/letsencrypt/live/yourapp.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourapp.com/privkey.pem;
# API routes -> Django
location /api/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection ""; # required for keepalive
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Admin -> Django
location /admin/ {
proxy_pass http://backend;
proxy_set_header Host $host;
}
# Static files -> Django (with caching)
location /static/ {
proxy_pass http://backend;
expires 30d;
add_header Cache-Control "public, immutable";
}
# Everything else -> Next.js
location / {
proxy_pass http://frontend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_buffering off; # important for streaming SSR
}
}الإعداد 2: إعادة التوجيه عبر HTTPS + الرابط القياسي لـ www
هناك أمران لا غنى عنهما في أي موقع إنتاجي: فرض استخدام بروتوكول HTTPS واختيار نطاق أساسي واحد (www أو غير www). فبدون ذلك، ستعتبر Google أن هناك موقعين منفصلين، مما يؤدي إلى تشتيت جهود تحسين محركات البحث (SEO) الخاصة بك.
# Redirect HTTP -> HTTPS
server {
listen 80;
server_name yourapp.com www.yourapp.com;
return 301 https://yourapp.com$request_uri;
}
# Redirect www -> non-www
server {
listen 443 ssl;
server_name www.yourapp.com;
ssl_certificate /etc/letsencrypt/live/yourapp.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourapp.com/privkey.pem;
return 301 https://yourapp.com$request_uri;
}
# Main site (canonical)
server {
listen 443 ssl;
server_name yourapp.com;
# ... your config
}التوجيهات الخمسة التي يجب أن تفهمها
| التوجيه | ما الذي يفعله | لماذا هذا مهم |
|---|---|---|
| إصدار proxy_http 1.1 | يستخدم بروتوكول HTTP/1.1 للاتصالات الصادرة | ضروري لتشغيل ميزة "keepalive" |
| proxy_set_header Connection "" | مسح رأس الاتصال | في حالة عدم توفر ذلك، يتم تعطيل ميزة "keepalive" |
| إيقاف التخزين المؤقت للوكيل | يتم إرسال الاستجابة مباشرةً إلى العميل | ضروري للبث باستخدام SSR، SSE، في الوقت الفعلي |
| client_max_body_size 20 ميغابايت | الحجم الأقصى للتحميل | القيمة الافتراضية هي 1 ميغابايت - سيفشل تحميل الملفات |
| proxy_set_header X-Forwarded-Proto $scheme | يُعلم الخادم الخلفي ما إذا كان الطلب عبر بروتوكول HTTPS | يحتاج «Django» إلى هذا من أجل CSRF وعمليات إعادة التوجيه |
تصحيح الأخطاء: عندما تسوء الأمور
502 خطأ في البوابة: يتعذر على Nginx الاتصال بمصدر الخدمة. حاوية التطبيق غير قيد التشغيل، أو أنها موجودة على شبكة Docker مختلفة.
504 انتهت مهلة البوابة: تطبيقك بطيء جدًا. قم بزيادة قيمة proxy_read_timeout أو قم بتحسين أداء تطبيقك.
413 كيان الطلب كبير جدًا: حجم الملف المرفوع يتجاوز القيمة المحددة لـ client_max_body_size. قم بزيادة هذه القيمة.
حلقة إعادة توجيه 301: يقوم تطبيقك بإعادة التوجيه إلى HTTPS، لكن رأس X-Forwarded-Proto غير محدد، لذا يظن دائمًا أنه يعمل عبر HTTP.
# Quick debugging commands
nginx -t # test config syntax
nginx -s reload # reload without downtime
tail -f /var/log/nginx/error.log # watch errors live
curl -I https://yourapp.com # check response headersNginx هو حارس الباب في ناديك. فهو الذي يقرر من يدخل، وأين يتجه، ومدى سرعة ذلك. خصص 30 دقيقة لفهمه وستوفر 30 ساعة من تصحيح أخطاء الإنتاج.
— شركة ألوكنايت للهندسة
