Nginx+Uvicorn部署Django+django-channels项目时WebSocket连接失败

故障根因 #

1. 初始Nginx配置错误：/ws/路径的proxy_pass指向0.0.0.0:8000，在Docker容器网络环境下，该地址指向Nginx容器自身而非运行Django服务的app容器，导致连接被拒绝。你已将其修改为http://django，该问题已解决。
2. 核心故障：Uvicorn缺少WebSocket处理依赖，当前安装的Uvicorn为精简版本，未自带websockets库，无法处理WebSocket升级请求，直接触发Django侧的警告，导致WebSocket连接建立失败。
3. 补充问题：修改proxy_pass后的/ws/路径配置缺少必要的请求头转发规则，可能导致Django侧无法正确识别请求来源，影响连接校验。

解决方案 #

• 补全WebSocket依赖：在项目依赖清单（如requirements.txt）中添加websockets包，或直接替换原有uvicorn依赖为uvicorn[standard]，重新构建Docker镜像即可。临时验证可直接进入Django容器执行pip install websockets后重启服务。
• 修正Nginx的/ws/路径配置，补全转发头，完整配置如下：

location /ws/ {
    proxy_pass http://django;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_redirect off;
    proxy_buffering off;
}

修改完成后重启Nginx容器生效。

• 可选适配HTTPS场景：修改前端JS代码自动适配WebSocket协议，避免后续部署HTTPS时再次出现连接失败问题：

var wsStart = window.location.protocol === "https:" ? "wss://" : "ws://";
var webSocketEndpoint =  wsStart + window.location.host + '/ws/notifications/';
const notificationSocket = new WebSocket(webSocketEndpoint);

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