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

一、模块概述

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

nginx 复制代码

return <value>;

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

二、典型应用场景

心跳与健康检查
- 监控系统定期拨测 Nginx 端口，若返回预期字符串即视为"服务正常"。
调试与协议探测
- 临时搭建一个测试端口，快速查看客户端发起连接所带信息（配合 $remote_addr、$proxy_protocol_addr）。
统一版本或配置查询
- 通过 $nginx_version、自定义静态文本，告知客户端当前网关版本或配置信息。
黑洞吸收
- 对特定端口或 SNI，直接返回空或固定消息，拒绝后续业务流量。

三、指令语法

nginx 复制代码

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

<value>：
- 文本：如 "pong\n"
- 变量：如 $time_iso8601、$remote_addr
- 组合："${remote_addr} connected at ${time_local}\n"
上下文 ：仅支持 stream { server { ... } } 级别。

四、最小示例

返回当前 ISO 时间
nginx 复制代码
```
stream {
    server {
        listen 6000;
        return $time_iso8601 "\n";
    }
}
```
- 客户端连入后立刻收到 2025-06-10T12:34:56+02:00

Echo 客户端 IP

nginx 复制代码

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

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

固定心跳响应
nginx 复制代码
```
stream {
    server {
        listen 6002 udp;
        return "HEARTBEAT_OK";
    }
}
```
- 监控系统可采用 UDP 探测，无需维护 TCP 连接。

五、高级组合

条件返回 （配合 map）

nginx 复制代码

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

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

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

nginx 复制代码

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

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

六、注意事项

无异步或后端依赖
- return 执行后即断开连接，不支持延迟或异步逻辑。
变量可用性
- 仅在 Stream 层可用的变量才会解析，如 $remote_addr、$proxy_protocol_addr、$time_iso8601。
返回长度限制
- 推荐返回值不超过缓冲区大小（默认 16 KB），否则会被截断。
监控结合
- 可在 access_log 中记录 "$remote_addr return=$resp_status"，配合 Prometheus/Loki 采集。

七、结语

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