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

Nginx به‌عنوان reverse proxy: هدرها، timeoutها و WebSocket را درست تنظیم کنید

با proxy_pass برنامه را پروکسی کنید، هدرهای Host و IP کلاینت را بفرستید، timeout بگذارید، WebSocket را پشتیبانی کنید و خطای ۵۰۲ یا ۵۰۴ را عیب‌یابی کنید.

Nginx به‌عنوان reverse proxy: هدرها، timeoutها و WebSocket را درست تنظیم کنید

قراردادن Nginx جلوی برنامهٔ Node، Python یا Java به شما TLS، فشرده‌سازی و ورودی عمومی پایدار می‌دهد. بیشتر مشکل‌ها از هدرهای جاافتاده، اسلش انتهایی اشتباه و timeoutهای کوتاه می‌آیند. این راهنما پیکربندی روشن reverse proxy، پشتیبانی WebSocket و روال کوتاه عیب‌یابی خطاهای ۵۰۲ و ۵۰۴ را نشان می‌دهد. دستورها از مستندات nginx آمده‌اند؛ روی سرور شما اجرایشان نکرده‌ام.

۱. یک پروکسی پایهٔ تمیز

upstream را تعریف کنید، هدرهای موردنیاز برنامه را بفرستید و با backend از 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 و read timeout بلندتر نیاز دارد، وگرنه اتصال‌ها بی‌صدا قطع می‌شوند:

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 جدا استفاده کنید تا درخواست‌های عادی timeout عادی داشته باشند. قاعده‌های ترتیب location در راهنمای ترتیب location توضیح داده شده است.

۳. تست و عیب‌یابی

پیکربندی را بررسی کنید، بعد برنامه را مستقیم و از طریق nginx تست کنید. ۵۰۲ معمولاً یعنی backend پایین یا غیرقابل‌دسترس است و ۵۰۴ یعنی بیش از حد طول کشیده:

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 bind کنید تا فقط 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 reload کنید.

۶. مثال توضیحی، نه اندازه‌گیری واقعی

فرض کنید برنامهٔ Node ای (ساختگی) روی پورت ۳۰۰۰ کار می‌کند اما پشت nginx در ریدایرکت‌ها دامنهٔ اشتباه نشان می‌دهد. افزودن هدرهای Host و X-Forwarded-Proto لینک‌ها را درست می‌کند. قابلیت چتی که بعد از یک دقیقه قطع می‌شد با location مخصوص WebSocket و read timeout بلندتر حل می‌شود.

۷. اشتباه‌های رایج

  • فراموشی هدر Host.
  • قاطی‌کردن اسلش انتهایی در proxy_pass.
  • timeout کوتاه برای درخواست‌های طولانی.
  • در معرض اینترنت گذاشتن پورت برنامه.
  • نبود هدرهای upgrade برای WebSocket.
  • reload بدون nginx -t.

۸. پرسش‌های متداول

علت ۵۰۲ چیست؟ backend پایین است، اتصال را رد کرده یا کرش کرده.

علت ۵۰۴ چیست؟ backend در مهلت پاسخ نداده.

keepalive لازم است؟ با استفادهٔ مجدد از اتصال‌های backend به کارایی کمک می‌کند.

برنامه آدرس بازدیدکننده را از کجا بفهمد؟ از X-Forwarded-For که فقط از پروکسی‌های مورد اعتماد خوانده شود.

۹. چک‌لیست سریع

  1. upstream را تعریف کنید.
  2. Host و هدرهای کلاینت را بفرستید.
  3. HTTP/1.1 و keepalive بگذارید.
  4. در صورت نیاز location مخصوص WebSocket بیفزایید.
  5. timeoutهای مناسب بگذارید.
  6. برنامه را به localhost bind کنید.
  7. nginx -t بزنید، reload و تست کنید.

اگر برای بررسی عملکرد یا نگهداری سرور به همکاری نیاز دارید، محدودهٔ خدمات مدیریت سرور را ببینید.

راهنماهای بیشتر سرور و وردپرس در آرشیو مقالات جمع شده‌اند.

منابع رسمی

nginx: ngx_http_proxy_module · nginx: WebSocket proxying · nginx: ngx_http_upstream_module · nginx: ngx_http_realip_module