利用ngx_stream_return_module构建简易 TCP/UDP 响应网关

一、模块概述

ngx_stream_return_module 提供了一个极简的指令：

return <value>;

在收到客户端连接后，立即将 <value> 写回并关闭连接。<value> 支持内嵌文本和内置变量（如 $time_iso8601、$remote_addr 等），无需任何上游后端即可快速响应。

二、典型应用场景

1. 心跳与健康检查

   • 监控系统定期拨测 Nginx 端口，若返回预期字符串即视为“服务正常”。

2. 调试与协议探测

   • 临时搭建一个测试端口，快速查看客户端发起连接所带信息（配合 $remote_addr、$proxy_protocol_addr）。

3. 统一版本或配置查询

   • 通过 $nginx_version、自定义静态文本，告知客户端当前网关版本或配置信息。

4. 黑洞吸收

   • 对特定端口或 SNI，直接返回空或固定消息，拒绝后续业务流量。

三、指令语法

server {
    listen 12345;              # TCP/UDP 均可
    return <value>;
}

• <value>：

  • 文本：如 "pong\n"
  • 变量：如 $time_iso8601、$remote_addr
  • 组合："${remote_addr} connected at ${time_local}\n"

• 上下文：仅支持 stream { server { … } } 级别。

四、最小示例

1. 返回当前 ISO 时间

   stream {
       server {
           listen 6000;
           return $time_iso8601 "\n";
       }
   }
   

   • 客户端连入后立刻收到 2025-06-10T12:34:56+02:00

2. Echo 客户端 IP

   stream {
       server {
           listen 6001;
           return "Your IP: $remote_addr\n";
       }
   }
   

   • 便于诊断 NAT / PROXY 协议是否正确透传。

3. 固定心跳响应

   stream {
       server {
           listen 6002 udp;
           return "HEARTBEAT_OK";
       }
   }
   

   • 监控系统可采用 UDP 探测，无需维护 TCP 连接。

五、高级组合

• 条件返回（配合 map）

  stream {
      map $remote_addr $resp {
          10.0.0.0/8  "INTERNAL\n";
          default    "EXTERNAL\n";
      }
      server {
          listen 7000;
          return $resp;
      }
  }
  

  根据源地址段动态返回不同内容。

• SNI 健康（TLS 不解密，仅 HTTP/2 示例）

  stream {
      server {
          listen 443 ssl;
          ssl_preread on;
          return "ServerName: $ssl_preread_server_name\n";
      }
  }
  

  在 TLS 握手后返回客户端发来的 SNI。

六、注意事项

1. 无异步或后端依赖

   • return 执行后即断开连接，不支持延迟或异步逻辑。

2. 变量可用性

   • 仅在 Stream 层可用的变量才会解析，如 $remote_addr、$proxy_protocol_addr、$time_iso8601。

3. 返回长度限制

   • 推荐返回值不超过缓冲区大小（默认 16 KB），否则会被截断。

4. 监控结合

   • 可在 access_log 中记录 "$remote_addr return=$resp_status"，配合 Prometheus/Loki 采集。

七、结语

ngx_stream_return_module 是 Nginx Stream 层最轻量的应答利器，适合任何需要 “即连即回” 的场景：从心跳检测、健康探针，到快速调试、自定义协议探测，都能用极少配置快速落地。无需后端、无额外依赖，只需一行 return，即可让你的流量网关多一份“秒回”能力。