Nginx 实战配置：WebSocket、流式文件与反向代理

Nginx 反向代理配置看起来只有几行，但 WebSocket、SSE、大文件上传、Range 下载和真实客户端 IP 都有不同要求。公共配置可以复用，协议特性必须按路由明确声明。

基础代理配置

location /api/ {
    proxy_pass http://gateway:12120/;
    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_connect_timeout 5s;
    proxy_read_timeout 60s;
}

proxy_pass 是否带尾斜杠会影响路径替换，修改后用几个真实 URL 验证，不要靠记忆。上游应用只有在代理来源可信时才应读取 X-Forwarded-For，否则客户端可以伪造。

WebSocket

HTTP Hop-by-hop Header 不会自动传给上游，需要显式 Upgrade：

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

location /socket/ {
    proxy_pass http://chat:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_read_timeout 300s;
}

应用应有 Ping/Pong 或心跳，超时时间不能无限大。滚动发布还要处理连接排空和客户端重连。

SSE 与流式响应

流式输出最常见的问题是代理缓冲让客户端一次收到整段：

location /api/stream/ {
    proxy_pass http://gateway:12120;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;
    add_header X-Accel-Buffering no;
}

上游也必须及时 Flush，设置正确 Content-Type，并避免中间层压缩或缓存造成额外聚合。

大文件上传与 Range 预览

client_max_body_size 5g;
client_body_timeout 300s;

分片上传每个请求通常不需要 5G 上限，但完整文件和导入能力要统一规划。视频/PDF 预览依赖 Range，请求应转给支持 Range、206 Partial Content、Content-Range 的鉴权文件服务。不要为了能预览直接把物理目录公开成无鉴权静态资源。

若上游希望边接收边处理，可评估 proxy_request_buffering off，但它会改变重试与流控行为，必须压测慢客户端场景。

静态前端与 SPA

location / {
    try_files $uri $uri/ /index.html;
}

location /assets/ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

带 Hash 的静态资源可长期缓存，index.html 应不缓存或短缓存。发布时先保留旧 Assets，再更新 HTML，避免在线用户加载旧 Chunk 404。

验证与日志

nginx -t
curl -I "$SITE_URL/"
curl -i -H 'Range: bytes=0-1023' "$SITE_URL/api/files/preview/42"

访问日志应包含请求时间、上游时间、状态码和请求 ID；敏感 Query 与认证头不要写入日志。配置变更先 nginx -t，使用 Reload 平滑生效。

参考资料