在 nginx 中修改 websocket 代理的响应头,核心做法是在 `location` 块中使用 `proxy_set_header` 设置请求头,并使用 `proxy_hide_header` 或 `more_clear_headers`(需第三方模块)来过滤或修改上游返回的响应头。由于 websocket 升级后连接变为长连接,nginx 默认透传上游的所有响应头,若需移除敏感信息或标准化字段,必须显式配置隐藏规则。

如何配置基础 WebSocket 代理并透传关键头部
要实现基本的 WebSocket 代理,必须在 `location` 块中设置 `Upgrade` 和 `Connection` 头部,并将 `HTTP/1.1` 传递给上游服务器。这确保了 Nginx 能正确识别升级请求并与上游建立双向通道。此时,上游返回的所有响应头(如 `Set-Cookie`、`Cache-Control`)都会默认透传给客户端。

server {
listen 80;
server_name ws.example.com;
location /ws {
proxy_pass http://backend:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header 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_http_version 1.1 是必须的,因为 WebSocket 握手依赖 HTTP/1.1 的 Upgrade 机制。proxy_set_header Connection "upgrade" 覆盖了默认的 close 行为。当客户端连接到 /ws 时,Nginx 会将 Host、X-Real-IP 等头部转发给后端,而后端返回的 200 Switching Protocols 响应中的头部将直接发送给客户端。
如何隐藏或修改上游返回的特定响应头
如果上游服务器返回了不希望客户端看到的头部(如 Server、X-Powered-By 或特定的 Set-Cookie),可以使用 proxy_hide_header 指令。该指令会在 Nginx 将响应发送回客户端之前,从响应头列表中移除指定的字段。注意,proxy_hide_header 仅适用于非 WebSocket 升级后的常规 HTTP 响应阶段,或者在握手阶段的响应头处理上有效;对于 WebSocket 升级后的数据帧,头部不再存在,因此此方法主要针对握手响应及后续可能的 HTTP 短连接交互。
可水平扩展的 WebSocket 中心模式,支持懒加载 Redis 订阅、连接注册表和优雅关闭。适用于构建可跨多实例扩展的实时 WebSocket 服务器。

server {
listen 80;
server_name ws.example.com;
location /ws {
proxy_pass http://backend:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 隐藏上游返回的敏感或冗余头部
proxy_hide_header Server;
proxy_hide_header X-Powered-By;
proxy_hide_header Set-Cookie;
}
}
在上述配置中,proxy_hide_header 会确保即使后端返回了 Server: nginx 或 X-Powered-By: PHP/7.4,这些头部也不会出现在客户端收到的握手响应中。如果需要更复杂的修改(如重命名头部),Nginx 原生不支持直接修改响应头名称,但可以通过 more_set_headers 模块(由 headers-more-nginx-module 提供)来实现。例如:more_set_headers 'X-Custom-Header: value'; 可以添加或覆盖头部。但在纯 WebSocket 场景下,握手完成后即进入二进制/文本帧传输,不再有 HTTP 头部,因此头部修改仅在握手阶段生效。
WebSocket 升级成功后响应头是否还会变化
一旦 WebSocket 连接完成 101 Switching Protocols 升级,通信层将切换为 TCP 层面的帧协议,不再包含 HTTP 头部。这意味着所有在 location 块中配置的 proxy_hide_header 或 more_set_headers 对后续的数据帧传输无效。开发者常误以为可以在 WebSocket 连接期间动态修改响应头,但实际上,握手响应是唯一一次涉及 HTTP 头部的时刻。此后,数据通过 send() 和 recv() 级别的 API 传输,不受 Nginx 头部处理指令影响。










