همه مقالات تخصصی

تفاوت اسلش در proxy_pass؛ رفع مسیر اشتباه و 404 پشت Nginx

درک تفاوت proxy_pass با URI و بدون URI، تست مسیر و Query String و اصلاح 404 بدون Rewrite حدسی.

تفاوت اسلش در proxy_pass؛ رفع مسیر اشتباه و 404 پشت Nginx

وقتی API مستقیم کار می‌کند اما پشت Nginx پاسخ 404 می‌دهد، شاید بک‌اند اصلاً مسیر موردنظر شما را نمی‌بیند. یک اسلش در proxy_pass می‌تواند /api/users را به /users تبدیل کند یا Prefix را نگه دارد. این مقاله برای location معمولی Prefix و Upstream HTTP ثابت است؛ Regex، Named Location و متغیرها قواعد متفاوتی دارند.

۱. قرارداد مسیر بک‌اند را مشخص کنید

از مستند API یا لاگ برنامه بفهمید Router بک‌اند /users می‌خواهد یا /api/users. افزایش Timeout و Buffer مشکل مسیر را حل نمی‌کند. قبل از تغییر، یک GET بی‌خطر با Query String را مستقیم و از مسیر عمومی مقایسه کنید. Host و مجوز دسترسی را ثابت نگه دارید تا اختلاف Virtual Host یا Authentication را با اختلاف URI اشتباه نگیرید.

۲. URI در proxy_pass یعنی جایگزینی Prefix

در نمونه A اسلش پس از پورت، URI برابر / می‌سازد. Nginx بخش منطبق با location /api/ را با / جایگزین می‌کند؛ بنابراین /api/users?id=1 به /users?id=1 می‌رود. نمونه را با server موجود ادغام کنید، نه با ساختن location تکراری. عدد پورت نمونه است و باید با Listener واقعی تطبیق داده شود.

# Example A: strip /api/ from the upstream path
location /api/ {
    proxy_pass http://127.0.0.1:8080/;
    proxy_set_header Host $host;
}

۳. بدون URI، Prefix در این مسیر حفظ می‌شود

در نمونه B بعد از پورت اسلش نیست و proxy_pass فقط آدرس Upstream را دارد. در درخواست اصلی بدون Rewrite، /api/users?id=1 با همان مسیر به بک‌اند می‌رسد. دو نمونه A و B گزینه جایگزین هستند، نه تنظیم هم‌زمان. اگر URI قبلاً 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/ Redirect شود و نوع درخواست یا قرارداد کلاینت را تحت تأثیر قرار دهد؛ آن را مستقلاً تست کنید. مسیرهای Encodeشده، اسلش مضاعف و Query String را در محیط آزمایش بررسی کنید. برای location مبتنی بر Regex و Named Location معمولاً proxy_pass بدون URI لازم است. افزودن متغیر یا rewrite break نیز الگوریتم ساده Prefix را تغییر می‌دهد؛ به جای انباشتن Rewrite، مسیر کامل پردازش را بخوانید.

۵. Redirect، Cookie و نتیجه را تأیید کنید

پس از موفقیت nginx -t، Reload کنید و در لاگ بک‌اند URI واقعی را ببینید. curl زیر Redirect را دنبال نمی‌کند تا Location قابل بررسی باشد. حتی اگر GET درست شود، Asset URL، مسیر Cookie و Redirect برنامه‌ای که زیر Prefix جدید است ممکن است هنوز خراب باشند. Base URL برنامه را متناسب تنظیم و ورود، خروج و مسیرهای مجاز را تست کنید؛ proxy_redirect جای اصلاح همه لینک‌ها نیست. معیار تأیید: URI و Query درست، بدون Loop و با Session سالم. در شکست، تنظیم قبلی را برگردانید، تست و Reload کنید.

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'

منابع رسمی

NGINX proxy_pass