Nginx基础教程（114）Nginx OpenResty开发之Stream Lua模块：别再用HTTP模块硬扛TCP流量了！Stream Lua让你在Nginx里“开挂”

原创

于 2025-12-02 09:27:05 发布 · 417 阅读

5 ·

CC 4.0 BY-SA版权

文章标签：

#nginx #openresty #lua

一行Lua代码就能让Nginx变身全能流量管家，从MySQL代理到游戏服务器，OpenResty的Stream Lua模块正在重新定义四层网络编程的边界。

01 Stream Lua模块：Nginx的“第二人格”

很多人不知道，Nginx 从 1.9.0 版本开始，通过编译时添加 —with-stream 参数，就能支持原生的 TCP/UDP 代理功能。但这只是基础能力，真正让 Nginx 在四层网络上“开挂”的，是 stream-lua-nginx-module。

这个模块是 ngx_http_lua_module 在 TCP/UDP 领域的“孪生兄弟”，提供了几乎相同的 Lua API 和 Nginx 指令，让你可以用熟悉的 Lua 脚本处理通用流/TCP 请求。

想象一下：你的 Nginx 不仅能处理 HTTP 请求，还能直接处理 Redis、MySQL、Memcached 的连接，甚至自定义的二进制协议。这就是 Stream Lua 模块带来的可能性。

传统的 Nginx 配置更新需要 reload，这个过程会涉及工作进程的新建和关闭。在大流量或频繁更新时，这种切换会造成负担。而 Stream Lua 模块结合共享内存和 Lua 脚本，能够实现真正意义上的动态更新。

02 从零开始：搭建你的第一个Stream Lua环境

安装 Stream Lua 模块最省心的方式是直接使用 OpenResty发行版，它已经集成了 Nginx、ngx_http_lua、ngx_stream_lua（即本模块）、LuaJIT 及其他强大的伴侣模块。

如果你的系统是 CentOS，可以通过 yum 轻松安装 OpenResty。编译安装也很简单，以 OpenResty 1.19.9.1 为例，只需几条命令。

安装完成后，一个基本的 Stream Lua 配置看起来是这样的：

stream {
    server {
        listen 1111;
        content_by_lua_block {
            local sock = assert(ngx.req.socket(true))
            local data = sock:receive()  -- 从下游读取一行数据
            if data == “thunder” then
                ngx.say(“flash”)  -- 输出数据
            else
                ngx.say(“boom”)
            end
            ngx.say(“the end”)
        }
    }
}

这个简单的例子监听 1111 端口，接收一行数据，如果是“thunder”就回复“flash”，否则回复“boom”。虽然简单，但它展示了 Stream Lua 模块的核心能力：直接处理原始 TCP 数据流。