Django Channels部署环境下获取WebSocket客户端IP的NoneType错误排查

问题背景 #

部署Nginx-Gunicorn-Uvicorn-Redis架构的Django服务后，通过self.scope["client"][0]获取WebSocket客户端IP时出现NoneType object is not subscriptable错误，本地开发环境正常。

解决方案 #

1. 修正自定义UvicornWorker配置

原Worker写法错误，CONFIG_KWARGS是类属性，需在类定义时直接赋值，而非实例初始化阶段修改：

from uvicorn.workers import UvicornWorker

class ServerUvicornWorker(UvicornWorker):
    CONFIG_KWARGS = {
        "proxy_headers": True,
        "forwarded_allow_ips": "*"
    }

修改Gunicorn配置中的-k参数，指向该自定义Worker（路径根据实际项目结构调整），例如：

-k src.server.workers.ServerUvicornWorker

2. 补全Nginx WebSocket代理头

在/ws/的location块中添加X-Forwarded-For头，确保客户端IP被正确传递到后端：

location /ws/ {
    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_redirect off;
    proxy_pass http://uvicorn;
}

3. 代码层面兼容IP获取逻辑

为避免依赖scope["client"]的稳定性，优先从代理头解析IP，同时保留降级逻辑：

@database_sync_to_async
def _set_online_if_model(self, set_online: bool) -> None:
    client_ip = None
    
    # 从X-Forwarded-For头解析IP
    headers = self.scope.get("headers", [])
    for name, value in headers:
        if name.lower() == b"x-forwarded-for":
            client_ip = value.decode().split(",")[0].strip()
            break
    
    # 降级使用scope["client"]
    if not client_ip and self.scope.get("client"):
        client_ip = self.scope["client"][0]
    
    if not client_ip:
        return  # 处理IP获取失败的场景
    
    for model in MyModel.objects.all():
        if client_ip == model.ip:
            model.online = set_online
            model.save()

验证操作 #

1. 重启Gunicorn服务，确保自定义Worker加载生效
2. 重启Nginx服务，应用新的代理配置
3. 发起WebSocket连接测试，确认IP获取正常

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