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

راه‌اندازی WebSocket پشت Nginx؛ رفع قطع اتصال و خطای Upgrade

وقتی HTTP سایت سالم است اما چت یا داشبورد زنده قطع می‌شود، مشکل الزاماً از برنامه نیست.

راه‌اندازی WebSocket پشت Nginx؛ رفع قطع اتصال و خطای Upgrade

WebSocket به عبور درست Upgrade، پاسخ 101 و حفظ اتصال طولانی نیاز دارد. این راهنما مسیر مرورگر تا Nginx و برنامه را جداگانه آزمایش می‌کند.

دامنه و پیش‌نیازها

این نمونه برای Reverse Proxy به برنامه HTTP روی Loopback است، نه FastCGI. مسیر /ws/ و پورت 3000 را با برنامه واقعی هماهنگ کنید. از پیکربندی فعلی نسخه بگیرید؛ احراز هویت، بررسی Origin و TLS باید در طراحی حفظ شوند.

۱. شواهد را جمع‌آوری کنید

در Network مرورگر، handshake و کد پاسخ را ثبت کنید: 400 معمولاً به درخواست یا هدر، 401/403 به دسترسی و 502 به Backend مربوط است. برنامه را مستقیم و از همان سرور آزمایش کنید. اگر اتصال بعد از مدت ثابتی بسته می‌شود، زمان قطع را با لاگ برنامه و Proxy تطبیق دهید.

curl -I http://127.0.0.1:3000/
sudo nginx -T | less

۲. تغییر کنترل‌شده

هدرهای Upgrade و Connection از نوع hop-by-hop هستند و باید صریح منتقل شوند. map در سطح http و location داخل server قرار می‌گیرد. HTTP/1.1 را صریح بنویسید تا نمونه با نسخه‌های قدیمی نیز سازگار باشد. مسیر Backend و معنای اسلش proxy_pass را تغییر ناخواسته ندهید.

# http context
map $http_upgrade $connection_upgrade {
    default upgrade;
    "" close;
}
# inside server
location /ws/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_read_timeout 75s;
}

۳. نتیجه را آزمایش کنید

بعد nginx -t و reload، در مرورگر پاسخ 101 و تبادل پیام دوطرفه را ببینید. اتصال را بیش از مهلهٔ پیشین بدون پیام نگه دارید و reconnect را نیز امتحان کنید. timeout بزرگ جای heartbeat نیست؛ ping برنامه باید با مهلهٔ تمام Proxyهای مسیر هماهنگ باشد.

sudo nginx -t && sudo systemctl reload nginx

بازگشت و پیشگیری

اگر نرخ خطا یا مصرف اتصال بالا رفت، فقط فایل تغییرکرده را برگردانید، syntax را آزمایش و reload کنید. تعداد اتصال‌های هم‌زمان، مدت نشست و شکست handshake را پایش کنید. proxy_read_timeout فاصله بین خواندن‌هاست، نه حداکثر عمر کل نشست؛ افزایش بی‌حد آن مشکل Backend را درمان نمی‌کند.

برای بررسی بخش‌های مرتبط این مسیر، راهنماهای ثبت IP واقعی کاربر پشت CDN در Nginx؛ مرز اعتماد هدرها و Reverse Proxy آپاچی؛ رفع Redirect Loop و Host اشتباه را نیز ببینید.

منابع فنی