Node.js Express中获取入站请求IP异常，返回::1的问题咨询

先明确返回值含义 #

• ::1 是IPv6协议下的本地回环地址，和IPv4的127.0.0.1指向完全一致，出现这个值代表当前请求是从运行Node服务的本机节点直接发起的直连请求，不是代码逻辑运行报错。

分场景排查方向 #

1. 本地开发场景的正常情况 #

• 如果是在本地调试时，通过http://localhost:端口号访问接口，Node默认会优先匹配IPv6的本地回环链路，拿到::1属于正常表现，不需要额外调整。
• 若本地调试需要拿到IPv4格式的回环地址，直接把访问地址从localhost替换为127.0.0.1，拿到的IP值就会变为127.0.0.1。

2. 服务部署在反向代理（Nginx、云负载均衡）后的配置问题 #

• 优先检查Express的信任代理配置：如果服务前置了反向代理，却没有开启app.set('trust proxy', true)，Express会忽略x-forwarded-for请求头的真实IP值，直接取代理和Node服务的直连地址；当代理和Node服务部署在同一台机器时，这个直连地址就会是::1。
  • 单反向代理场景推荐配置app.set('trust proxy', 1)，代表只信任第一层代理传递的IP头
  • 多级代理场景可根据实际代理链路数量配置对应的可信层级，避免被恶意伪造的请求头篡改IP值
• 核对反向代理的请求头配置：确认反向代理是否真的把客户端真实IP写入了x-forwarded-for头，而不是仅传递代理自身的直连地址。

3. 现有IP获取逻辑的缺陷修正 #

• 当前使用的req.headers['x-forwarded-for'] || req.connection.remoteAddress逻辑存在两个漏洞：
  • 未处理x-forwarded-for的多IP格式：这个请求头的标准格式是真实客户端IP, 第一层代理IP, 第二层代理IP，需要取最左侧的第一个值才是真实客户端IP，不能直接把整个头字符串作为IP值
  • 未兼容IPv4映射的IPv6格式：当远端地址为::ffff:192.168.1.1这类格式时，需要提取其中的IPv4部分，不能直接存储压缩后的IPv6字符串
• 可复用的IP获取通用逻辑参考：

  function getClientIp(req) {
    // 优先解析转发头的真实IP
    const xForwardedFor = req.headers['x-forwarded-for'];
    if (xForwardedFor) {
      return xForwardedFor.split(',')[0].trim();
    }
    // 兜底取直连地址，兼容映射格式
    const remoteAddr = req.socket.remoteAddress || req.connection.remoteAddress;
    if (remoteAddr.includes('::ffff:')) {
      return remoteAddr.split('::ffff:')[1];
    }
    return remoteAddr;
  }
  

常见踩坑提醒 #

• 不要长期把req.connection.remoteAddress作为IP获取的兜底来源：当服务前置代理时，这个值永远是代理与Node服务的直连地址，不是真实客户端的公网/局域网IP
• 开启信任代理配置后，可直接调用Express内置的req.ip方法获取已处理格式的客户端IP，不需要自行手写请求头解析逻辑

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