إذا عمل API مباشرة وأعاد 404 خلف Nginx، فقد يستقبل التطبيق مساراً مختلفاً. يمكن لشرطة في proxy_pass أن تحول /api/users إلى /users أو تبقي Prefix. يشرح الدليل location عادية ذات Prefix وخلفية HTTP ثابتة؛ Regex وNamed Location والمتغيرات لها قواعد مختلفة.
١. حدد عقد المسار في الخلفية
استعن بعقد API أو سجل التطبيق لمعرفة هل يتوقع Router مسار /users أم /api/users. لا تصلح المهلات والمخازن الأكبر اختلاف المسار. قارن GET آمناً مع Query String مباشرة وعبر المسار العام، مع تثبيت Host وسياق المصادقة لتجنب خلط Virtual Host أو التفويض مع إعادة كتابة URI.
٢. وجود URI في proxy_pass يستبدل Prefix
في المثال A، تمثل الشرطة بعد المنفذ URI يساوي /. يستبدل Nginx الجزء المطابق لـlocation /api/ به، فتصل /api/users?id=1 كـ/users?id=1. ادمج المقطع في server الموجود بلا location مكررة واستبدل المنفذ بالمستمع الحقيقي. هذا تحويل مسار للخلفية وليس إعادة توجيه للعميل.
# Example A: strip /api/ from the upstream path
location /api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_set_header Host $host;
}
٣. غياب URI يبقي المسار في هذه الحالة
لا توجد في المثال B شرطة بعد المنفذ، لذا يحدد proxy_pass عنوان الخلفية فقط. للطلب الأصلي دون Rewrite، يبقى /api/users?id=1 كما هو. المثالان بديلان لا تعريفان متزامنان. للطلبات المعاد كتابتها قواعد إضافية؛ لا يكفي النظر إلى الشرطة الأخيرة عند وجود Rewrite.
# Example B: preserve /api/ in the upstream path
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
}
٤. اختبر الحالات الحدية منفصلة
اختبر /api دون الشرطة الأخيرة؛ قد يعاد توجيهه إلى /api/ بما يؤثر على العميل. اختبر المسارات المشفرة والشرطات المكررة وQuery String في Staging. تتطلب Regex وNamed Location عادة proxy_pass بلا URI. تغير المتغيرات وrewrite break قواعد Prefix المبسطة أيضاً؛ تتبع المعالجة كلها بدلاً من تراكم Rewrites.
٥. تحقق من Redirect وCookie والنتيجة
بعد نجاح nginx -t أعد التحميل وافحص URI الفعلي في سجل الخلفية. لا يتبع curl هنا التحويلات لتظهر Location. نجاح GET لا يصلح تلقائياً روابط الملفات أو مسار Cookie أو Redirect التطبيق تحت Prefix جديد. اضبط Base URL واختبر الدخول والخروج والمسارات المصرح بها؛ proxy_redirect ليس مصلحاً لكل الروابط. النجاح URI وQuery صحيحان بلا Loop وجلسة سليمة. عند الفشل استعد الإعداد وافحصه وأعد تحميله.
sudo nginx -t
# Reload only after a successful configuration test:
sudo systemctl reload nginx
curl -sS -D - -o /dev/null 'https://api.example.com/api/users?id=1'
curl -sS -D - -o /dev/null 'https://api.example.com/api'
