WebSocket 配置 wss 访问：从 ws:// 到 wss:// 的完整指南

简介这份资源面向使用 Spring Boot 2.1 开发实时通信功能的 Java 后端开发者聚焦 WebSocket 在 HTTPS 环境下启用 wss 安全访问的完整配置方案。内容涵盖 SSL/TLS 证书准备、keystore 生成、Tomcat 连接器与端口重定向设置、WebSocketConfigurer 注册处理器以及前端 JavaScript 通过 wss 地址建立连接等关键环节可解决明文 ws 在 HTTPS 站点中被浏览器拦截、无法安全通信的常见问题。压缩包共 66 个文件约 61KB以 java 配置类与处理器、xml 依赖与构建配置、properties 属性文件、jks 证书文件为主另含少量 sample 与前端页面资源构成一个可直接运行的 WebSocketDemo 工程骨架。目前已有 13109 人学习下载适合需要快速跑通 wss 链路、对照排查证书与端口配置问题的开发者参考也可作为聊天室、行情推送等实时场景的起步模板。1. webSocket 配置 wss 访问从 ws:// 到 wss:// 到底改了什么本地开发时ws://localhost:8080/ws跑得飞起一上线换成域名就报Mixed Content或者直接连不上这是很多人第一次给 webSocket 配置 wss 访问时踩的坑。ws 和 wss 的关系等价于 http 和 httpswss 就是在 TLS 之上跑的 webSocket握手阶段先走一次标准的 TLS 握手再发 HTTP Upgrade 请求升级成 webSocket。所以「配置 wss」这件事本质上不是改 webSocket 代码而是把证书、反向代理、后端监听方式这三件事理顺。它适合所有要把实时推送搬到生产环境的场景——python django websocket 实现后台有数据前端推送、springboot 整合 websocket、websocket 实时推送数据只要对外暴露就绕不开 wss。下面按「先讲清握手链路再动手配最后排坑」的顺序拆开讲。2. wss 握手链路拆解证书、代理、后端各管哪一段要配 wss先得知道一次成功的 wss 连接里数据包到底经过了谁。很多人配不通就是因为把「证书问题」和「代理转发问题」混在一起查最后查了个寂寞。2.1 一次 wss 连接从浏览器到后端的完整路径浏览器发起wss://example.com/ws时实际发生的事分四步第一步TCP 连接到example.com:443。注意端口是 443不是 webSocket 常写的 8080。wss 默认走 443因为它是复用 HTTPS 端口的。第二步TLS 握手。浏览器校验服务器证书链是否可信、域名是否匹配、是否过期。这一步失败浏览器控制台会直接报证书错误连接根本到不了后端。第三步TLS 通道建立后浏览器在这个加密通道里发一个普通的 HTTP 请求带Upgrade: websocket和Connection: Upgrade头外加Sec-WebSocket-Key。第四步反向代理Nginx / Caddy / 云负载均衡收到这个请求识别出是 Upgrade 请求把它转发给后端真正的 webSocket 服务并把后端返回的101 Switching Protocols原样透传回去。此后这条 TCP 连接就被「劫持」成双向的 webSocket 数据流。关键结论TLS 是在代理这一层终止的后端服务通常还是明文 ws。也就是说你的 Django Channels 或 Spring Boot 后端监听的是ws://127.0.0.1:8000wss 是代理帮你「套」上去的。理解这一点后面所有配置就顺了。2.2 三种常见部署形态选哪种部署形态证书放哪后端监听适用场景Nginx 反代Nginxws://127.0.0.1:port最常见Django/Spring Boot 都适用云负载均衡 后端LB 上ws://内网IP:port上云、多实例后端直接开 TLS后端进程wss://0.0.0.0:port单机、无代理、调试用绝大多数生产环境选第一种。原因很直接证书续期、HTTP 和 webSocket 共用 443、限流和日志统一在 Nginx 做比让每个后端进程自己管证书省心得多。后端直接开 TLS 只在本地验证证书链时用得上生产上很少这么干因为一旦要扩多实例证书就得复制到每台机器。2.3 后端要不要改代码这是被问得最多的问题。答案是基本不用改 webSocket 业务逻辑但要改「信任代理」相关的配置。以 Django Channels 为例走 Nginx 反代后后端看到的连接来源是127.0.0.1request.is_secure()可能返回 False因为它不知道前面有 TLS。这时候需要在配置里声明信任代理头# settings.py # 告诉 Django 信任来自代理的 X-Forwarded-Proto 头 SECURE_PROXY_SSL_HEADER (HTTP_X_FORWARDED_PROTO, https) # Channels 层配置允许的来源 CHANNEL_LAYERS { default: { BACKEND: channels_redis.core.RedisChannelLayer, CONFIG: {hosts: [(127.0.0.1, 6379)]}, }, } # 允许的 host生产环境务必收紧 ALLOWED_HOSTS [example.com]SECURE_PROXY_SSL_HEADER这行的作用是当 Nginx 传来X-Forwarded-Proto: https时Django 就认为当前请求是安全的。参数名必须和 Nginx 里proxy_set_header设置的头发一致写错了不报错但会静默失效这是血泪经验。Spring Boot 侧类似需要在application.yml里配置server: forward-headers-strategy: framework # 让 Spring 识别 X-Forwarded-* 头 tomcat: remoteip: protocol-header: X-Forwarded-Proto remote-ip-header: X-Forwarded-Forforward-headers-strategy设为framework后Spring 会自动处理代理头request.getScheme()就能正确返回 https。如果设成none后端永远以为自己在明文环境生成的重定向链接会退回 http前端就会报 Mixed Content。3. Nginx 反代配置 wss一份能直接抄的 server 块原理清楚了落到配置。这一章给一份完整可用的 Nginx 配置并逐行解释为什么这么写。3.1 完整 server 块与逐行说明# /etc/nginx/conf.d/ws.conf map $http_upgrade $connection_upgrade { default upgrade; close; } server { listen 443 ssl http2; server_name example.com; # 证书路径按实际替换 ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # webSocket 专用 location location /ws/ { proxy_pass http://127.0.0.1:8000; # 这三行是 wss 反代的核心缺一不可 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_set_header X-Forwarded-Proto $scheme; # 长连接超时默认 60s 会被掐断 proxy_read_timeout 3600s; proxy_send_timeout 3600s; } # 普通 HTTP 请求 location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } }逐行说几个关键点。map $http_upgrade $connection_upgrade这段必须放在server块外面它的作用是当请求带Upgrade头时$connection_upgrade取值为upgrade否则取close。如果偷懒直接写proxy_set_header Connection upgrade;普通 HTTP 请求也会带上 upgrade 头某些后端会因此报错。proxy_http_version 1.1是硬性要求。webSocket 的 Upgrade 机制依赖 HTTP/1.1Nginx 默认对上游用 HTTP/1.0不改成 1.1 握手直接失败而且报错信息很含糊只显示 400查半天查不出来。proxy_read_timeout 3600s解决的是「连接莫名其妙断掉」的问题。Nginx 默认 60 秒没有数据传输就断开上游连接而很多实时推送场景比如后台有数据才推可能几分钟没消息连接就被掐了。设长一点或者在前端加心跳。3.2 证书申请与自动续期证书用 Lets Encrypt 的 certbot 最省事# 安装 certbot以 Debian/Ubuntu 为例 sudo apt install certbot python3-certbot-nginx # 自动申请并写入 Nginx 配置 sudo certbot --nginx -d example.com # 测试自动续期是否正常 sudo certbot renew --dry-run--nginx参数会让 certbot 自动修改 Nginx 配置、插入证书路径并 reload。--dry-run是干跑一遍续期流程不真正签发用来验证定时任务是否配好。certbot 安装时会自动加一个 systemd timer 或 cron每天检查一次到期前 30 天自动续。注意续期后需要 reload Nginx 才能加载新证书certbot 的钩子一般会处理但如果你的 Nginx 是容器里跑的得自己加--deploy-hook去触发容器 reload。3.3 前端连接代码与协议自适应前端最容易翻车的地方是协议写死。正确做法是根据当前页面协议自动选 ws 还是 wss// 根据页面协议自动选择 ws / wss避免 Mixed Content const protocol window.location.protocol https: ? wss: : ws:; const wsUrl ${protocol}//${window.location.host}/ws/chat/; const socket new WebSocket(wsUrl); socket.onopen () console.log(wss 连接已建立); socket.onerror (e) console.error(连接出错, e); socket.onclose (e) console.warn(连接关闭, e.code, e.reason); // 心跳防止代理层超时断连 const heartbeat setInterval(() { if (socket.readyState WebSocket.OPEN) { socket.send(JSON.stringify({ type: ping })); } }, 30000); socket.onclose () clearInterval(heartbeat);window.location.host会自动带上域名和端口不用手写。心跳间隔设 30 秒比 Nginx 的proxy_read_timeout小就行这样即使没有业务数据连接也不会被判定为空闲。如果后端不支持 ping 消息发个空字符串也行目的是产生流量。4. 后端侧配置Django Channels 与 Spring Boot 的 wss 适配代理配好了后端还得配合。这一章分别讲两个主流框架在 wss 场景下要动的地方。4.1 Django Channels 走 wss 的关键配置Django Channels 用 ASGI 跑 webSocket生产上一般用 Daphne 或 Uvicorn 起 ASGI 服务监听内网端口前面挂 Nginx。# 用 Daphne 启动 ASGI 服务监听本地 8000 daphne -b 127.0.0.1 -p 8000 myproject.asgi:application-b 127.0.0.1表示只监听本地外部流量必须经过 Nginx这样后端就不用自己管证书。myproject.asgi:application是 ASGI 入口Channels 项目里这个文件负责把 http 和 websocket 两类协议路由到不同消费者。路由配置# routing.py from django.urls import re_path from . import consumers websocket_urlpatterns [ re_path(rws/chat/(?Proom\w)/$, consumers.ChatConsumer.as_asgi()), ]# consumers.py from channels.generic.websocket import AsyncWebsocketConsumer import json class ChatConsumer(AsyncWebsocketConsumer): async def connect(self): self.room self.scope[url_route][kwargs][room] await self.channel_layer.group_add(self.room, self.channel_name) await self.accept() async def disconnect(self, code): await self.channel_layer.group_discard(self.room, self.channel_name) async def receive(self, text_data): data json.loads(text_data) # 收到 ping 直接回 pong维持连接 if data.get(type) ping: await self.send(json.dumps({type: pong})) return await self.channel_layer.group_send( self.room, {type: chat_message, message: data[message]}, ) async def chat_message(self, event): await self.send(json.dumps({message: event[message]}))self.scope里包含了连接的所有上下文包括经过代理传来的头信息。如果要在 consumer 里判断是不是 wss可以读self.scope.get(scheme)走 Nginx 反代且配了X-Forwarded-Proto后这里会是wss。group_add把当前连接加入房间组实现后台有数据时向组内所有连接推送这正是 python django websocket 实现后台数据前端推送的标准做法。4.2 Spring Boot 整合 webSocket 的 wss 适配Spring Boot 用WebSocketConfigurer注册端点走 wss 时后端本身不用改协议但要处理代理头和跨域。Configuration EnableWebSocket public class WebSocketConfig implements WebSocketConfigurer { Override public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) { registry.addHandler(new MyHandler(), /ws/chat) // 生产环境务必写具体域名不要用 * .setAllowedOrigins(https://example.com); } }setAllowedOrigins是跨域白名单。走 wss 后Origin 头是https://example.com如果这里配的是http://example.com或者*前者会被拒后者有安全风险。注意Spring 的 Origin 校验发生在握手阶段被拒时前端只看到连接关闭看不到具体原因得开 DEBUG 日志才看得到Origin header value not allowed。如果用了 Spring Security还要放行 webSocket 端点Override protected void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers(/ws/**).permitAll() .anyRequest().authenticated(); }/ws/**放行是因为 webSocket 握手是普通 HTTP 请求会先过一遍 Security 过滤器链。如果不放行握手请求被重定向到登录页前端拿到的是 302 而不是 101连接直接失败。4.3 用 websocket test client 验证 wss 是否真的通了配完别急着上浏览器先用命令行工具验证能快速定位是代理问题还是后端问题。# 用 websocat 测试 wss 连接需先安装 websocat websocat wss://example.com/ws/chat/ # 如果只想验证 TLS 和握手用 curl 看返回码 curl -i -N \ -H Connection: Upgrade \ -H Upgrade: websocket \ -H Sec-WebSocket-Version: 13 \ -H Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ \ https://example.com/ws/chat/websocat连上后能直接收发消息是最接近真实客户端的验证方式。curl那条命令如果返回101 Switching Protocols说明 TLS、代理、后端三段全通如果返回 400多半是proxy_http_version没设成 1.1如果返回 502是后端没起来或端口不对如果卡住不返回是 TLS 握手或证书问题。这个分层排查法比在浏览器里瞎点高效得多。5. wss 配置避坑5 个高频翻车现场这一章全是踩过的坑每条按「现象 → 原因 → 解决」写照着对号入座。5.1 现象浏览器报 Mixed Contentws 连接被拦原因页面是 https但前端代码里 webSocket 地址写死了ws://。浏览器安全策略禁止 https 页面发起非加密的 ws 连接。解决用第 3.3 节的协议自适应写法根据window.location.protocol动态选wss:或ws:。如果地址是后端下发的后端也要根据X-Forwarded-Proto判断下发对应协议。5.2 现象连接建立后 60 秒左右必断原因Nginx 的proxy_read_timeout默认 60 秒空闲连接被上游断开。很多实时推送场景不是持续有数据很容易触发。解决把proxy_read_timeout和proxy_send_timeout调大如 3600s同时前端加心跳双保险。只调 Nginx 不加心跳遇到中间还有云负载均衡的情况LB 那层也可能有独立的空闲超时心跳是唯一能穿透所有层的办法。5.3 现象Nginx 返回 400日志显示 upgrade 头丢失原因proxy_http_version没设成 1.1或者Connection头写成了固定值upgrade导致普通请求也带 upgrade。解决确认proxy_http_version 1.1;存在Connection用map变量动态取值。这两个是 wss 反代的标配缺一个就 400。5.4 现象后端拿到的 scheme 是 http生成的回调链接不对原因代理没有传X-Forwarded-Proto或者后端没配置信任该头。解决Nginx 里加proxy_set_header X-Forwarded-Proto $scheme;后端按第 2.3 节配置SECURE_PROXY_SSL_HEADER或forward-headers-strategy。两边都要配只配一边无效。5.5 现象证书续期后 wss 突然连不上原因certbot 续期成功但 Nginx 没 reload仍在用旧证书旧证书过期后握手失败。解决检查 certbot 的--deploy-hook是否配置了 reload 命令。容器化部署时reload 要发信号给容器内的 Nginx 进程不能只 reload 宿主机。可以手动nginx -s reload验证再补自动化钩子。6. 进阶wss 连接的可观测性与压测验证配通只是第一步生产上还得能观测、能压测否则出了问题两眼一抹黑。6.1 用 Nginx 日志和连接数指标盯住 wsswebSocket 连接是长连接普通 access log 只在握手时记一条之后的数据收发不记录。要观测连接状态得看 Nginx 的stub_status或商业版的连接指标location /nginx_status { stub_status; allow 127.0.0.1; deny all; }stub_status输出的Active connections里包含了正在保持的 webSocket 连接。如果这个数持续上涨不回落说明有连接泄漏——客户端断开后后端没清理。配合ss -tn state established ( sport :8000 ) | wc -l看后端实际连接数两边对不上就说明代理层和后端层的连接生命周期管理有出入。日志格式上建议给 webSocket 的 location 单独配一个 log_format把$upgrade、$connection_upgrade、$status都记下来排查握手失败时一眼能看出是哪一步的问题。6.2 压测 wss别用普通 HTTP 压测工具普通压测工具ab、wrk 默认模式压不了 webSocket因为它们不会维持 Upgrade 后的长连接。常见做法是用 Python 的websockets库写并发脚本import asyncio import websockets async def one_client(idx, url): try: async with websockets.connect(url) as ws: await ws.send(fhello from {idx}) msg await ws.recv() return True except Exception as e: print(fclient {idx} failed: {e}) return False async def main(): url wss://example.com/ws/chat/ # 并发 500 个连接 tasks [one_client(i, url) for i in range(500)] results await asyncio.gather(*tasks) print(f成功 {sum(results)} / {len(results)}) asyncio.run(main())websockets.connect会自动处理 TLS 和握手wss://直接可用。并发数从 100 起步逐步加观察 Nginx 的worker_connections和后端的文件描述符上限。常见瓶颈是worker_connections默认 512500 并发就顶到天花板了需要调大并同步调ulimit -n。压测时重点看三件事握手成功率、消息往返延迟、连接保持时长。握手成功率低于 99% 就要查证书或代理配置延迟抖动大要查后端消费者是不是阻塞了事件循环。6.3 一个我自己的习惯我现在配任何 wss都先用websocat在服务器本机连一次wss://example.com/ws/再从前端连一次最后才上压测。本机通、前端不通问题在浏览器侧Mixed Content、协议写死本机不通问题在代理或证书。这个顺序帮我省了无数次在浏览器控制台里瞎找的时间。证书和代理这两层永远是 wss 翻车的重灾区把这两层用命令行验证透了剩下的都是业务逻辑的事。希望帮到你。本文还有配套的精品资源点击获取