一、模塊概述

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，即可讓你的流量網關多一份“秒回”能力。