uWebSockets.js 获取真实客户端IP地址的解决方案

在使用uWebSockets.js构建WebSocket服务时，当服务部署在Nginx反向代理之后，开发者经常会遇到无法获取真实客户端IP地址的问题。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题背景

当uWebSockets.js服务部署在Nginx反向代理之后，通过ws.getRemoteAddressAsText()方法获取的IP地址通常是Nginx服务器的本地地址（如127.0.0.1或0.0.0.1），而非真实客户端的IP地址。这是因为从uWebSockets.js的角度看，连接确实来自Nginx服务器本身。

技术原理分析

Nginx作为反向代理时，客户端与Nginx建立连接，Nginx再与后端uWebSockets.js服务建立连接。因此：

1. 在TCP/IP层面，uWebSockets.js看到的连接始终来自Nginx服务器
2. 真实客户端IP需要通过HTTP头信息传递
3. 常见的传递客户端IP的头字段包括：
   • X-Real-IP：直接传递客户端IP
   • X-Forwarded-For：传递整个代理链路的IP列表

完整解决方案

Nginx配置

在Nginx配置中需要正确设置转发头信息：

location / {
    proxy_pass http://websocket;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    # 关键配置：传递真实客户端IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

uWebSockets.js实现

在uWebSockets.js中，需要通过升级处理器(upgrade handler)获取这些头信息：

const uWS = require('uWebSockets.js');

const app = uWS.App().ws('/*', {
    upgrade: (res, req, context) => {
        // 在升级阶段获取头信息
        const clientIP = req.getHeader('x-real-ip');
        const forwardedFor = req.getHeader('x-forwarded-for');
        
        res.upgrade(
            {
                clientIP,  // 将IP信息附加到WebSocket对象
                forwardedFor
            },
            req.getHeader('sec-websocket-key'),
            req.getHeader('sec-websocket-protocol'),
            req.getHeader('sec-websocket-extensions'),
            context
        );
    },
    open: (ws) => {
        // 在连接打开时访问IP信息
        console.log('客户端真实IP:', ws.clientIP);
        console.log('转发链IP:', ws.forwardedFor);
    }
});

性能考量

这种解决方案的性能影响可以忽略不计，因为：

1. 只在WebSocket升级阶段（即连接建立时）解析头信息
2. 不涉及额外的网络请求
3. 内存开销极小，仅为存储IP字符串

最佳实践建议

1. 在生产环境中建议同时记录X-Real-IP和X-Forwarded-For，以便调试
2. 对于安全性要求高的场景，应验证X-Forwarded-For中的IP是否可信
3. 考虑使用中间件统一处理IP信息的获取和验证

通过这种方案，开发者可以准确获取客户端的真实IP地址，同时保持uWebSockets.js的高性能特性。