Nginx 反向代理 WebSocket 配置指南

WebSocket 是一种全双工通信协议，通过 Nginx 反向代理时需要特殊配置以确保连接能正确升级和维护。以下是详细的配置方法：

基本配置

server {
    listen 80;
    server_name yourdomain.com;

    location /ws/ {
        proxy_pass http://backend_server;

        # WebSocket 必要配置
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # 可选：设置超时时间
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

详细配置说明

1. 核心指令：

   • proxy_http_version 1.1：强制使用 HTTP/1.1 协议
   • proxy_set_header Upgrade $http_upgrade：传递 Upgrade 头
   • proxy_set_header Connection "upgrade"：将 Connection 头设置为 "upgrade"

2. 超时设置（重要）：

   proxy_connect_timeout 7d;
   proxy_send_timeout 7d;
   proxy_read_timeout 7d;
   

   WebSocket 是长连接，需要设置较长的超时时间

3. SSL/TLS 配置（HTTPS/WSS）：

   server {
      listen 443 ssl;
      server_name yourdomain.com;
   
      ssl_certificate /path/to/cert.pem;
      ssl_certificate_key /path/to/key.pem;
   
      location /ws/ {
          proxy_pass http://backend_server;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
          proxy_set_header Host $host;
      }
   }
   

4. 负载均衡配置：

   upstream websocket_servers {
      server 10.0.0.1:8080;
      server 10.0.0.2:8080;
   }
   
   server {
      location /ws/ {
          proxy_pass http://websocket_servers;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection "upgrade";
      }
   }
   

常见问题解决

1. 连接断开问题：

   • 增加超时时间
   • 检查 Nginx 和客户端/服务器端的 keepalive 设置

2. 502 Bad Gateway：

   • 确保后端 WebSocket 服务正在运行
   • 检查防火墙设置，确保端口可访问

3. 跨域问题：

   proxy_set_header Origin "";
   add_header 'Access-Control-Allow-Origin' '*';
   add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';
   add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
   add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
   

完整示例配置

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

server {
    listen 80;
    server_name ws.example.com;

    location /chat/ {
        proxy_pass http://backend_ws_server;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        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_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_connect_timeout 75s;
    }
}

配置完成后，记得测试 WebSocket 连接并检查 Nginx 错误日志 (/var/log/nginx/error.log) 以排查任何潜在问题。