如何在FastAPI中将WebSocket连接从ws升级为wss（WebSocket Secure）协议

核心原理 #

wss 本质是 WebSocket over TLS，和 HTTP 升级为 HTTPS 的逻辑完全一致，FastAPI 本身的 WebSocket 路由代码无需做任何修改，所有加密逻辑都在传输层或反向代理层处理，wss 连接失败基本都是 TLS 配置或反向代理规则缺失导致的。

分场景解决方案 #

场景1：直接用 Uvicorn/Hypercorn 等ASGI服务器对外暴露服务 #

启动服务时指定对应域名的有效SSL证书和私钥路径即可，启动命令示例：
uvicorn main:app --host 0.0.0.0 --port 443 --ssl-keyfile=./private.key --ssl-certfile=./fullchain.crt
注意事项：

• 若使用非443端口，发起wss请求时需要带上端口，例如 wss://你的域名:8443/ws
• 测试用的自签证书需要在接口测试工具中开启「信任自签/无效SSL证书」选项，否则连接会被工具主动拦截

场景2：使用Nginx/Caddy等反向代理转发FastAPI服务（生产环境最常用场景） #

该场景下大部分失败原因是反向代理没有配置WebSocket升级所需的请求头：

1. 先完成反向代理的基础HTTPS配置，绑定对应域名的SSL证书
2. 在WebSocket路径的匹配规则中添加升级头配置，Nginx配置示例：

location /ws {
proxy_pass http://127.0.0.1:8000;
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-Forwarded-Proto $scheme;
proxy_read_timeout 300s;
}

Caddy 无需额外配置升级头，配置自动HTTPS后直接反代FastAPI服务地址即可正常支持wss。

通用排查步骤 #

• 确认SSL证书在有效期内，且绑定的域名和发起wss请求使用的域名完全一致
• 确认服务器安全组、防火墙放开了wss对应端口的入站规则（默认是443端口）
• 不要直接用IP地址发起wss请求，常规SSL证书不支持IP绑定，会报证书不匹配错误
• 若使用CDN服务，确认CDN已经开启了WebSocket支持和HTTPS配置

内容的提问来源于stack exchange，提问作者AkIonSight