Nginx Lua编程基础

OpenResty通过汇聚各种设计精良的Nginx模块（主要由OpenResty团队自主开发）将Nginx变成一个强大的通用Web应用平台。这样，Web开发人员和系统工程师可以使用Lua脚本语言调动Nginx支持的各种C以及Lua模块，快速构造出足以胜任10KB乃至1000KB以上单机并发连接的高性能Web应用系统。

OpenResty的目标是让Web服务直接跑在Nginx服务内部，充分利用Nginx的非阻塞I/O模型，不仅对HTTP客户端请求，甚至对远程后端（如MySQL、PostgreSQL、Memcached以及Redis等）都进行一致的高性能响应。

实战案例说明

本节用到的配置文件为源码工程中的nginx-lua-demo.conf文件。

运行本节的实例前需要修改openresty-start.bat（或openrestystart.sh）脚本中的PROJECT_CONF变量的值，将其改为nginx-luademo.conf，然后重启OpenRestry。

Nginx Lua的执行原理

在OpenResty中，每个Worker进程使用一个Lua VM（Lua虚拟机），当请求被分配到Worker时，将在这个Lua VM中创建一个协程，协程之间数据隔离，每个协程都具有独立的全局变量。

ngx_lua是将Lua嵌入Nginx，让Nginx执行Lua脚本，并且高并发、非阻塞地处理各种请求。Lua内置协程可以很好地将异步回调转换成顺序调用的形式。ngx_lua在Lua中进行的IO操作都会委托给Nginx的事件模型，从而实现非阻塞调用。开发者可以采用串行的方式编写程序，ngx_lua会在进行阻塞的IO操作时自动中断，保存上下文，然后将IO操作委托给Nginx事件处理机制，在IO操作完成后，ngx_lua会恢复上下文，程序继续执行，这些操作对用户程序都是透明的。

每个Nginx的Worker进程持有一个Lua解释器或LuaJIT实例，被这个Worker处理的所有请求共享这个实例。每个请求的context上下文会被Lua轻量级的协程分隔，从而保证各个请求是独立的，如图8-5所示。

图8-5 工作进程相互独立

（1）每个Worker（工作进程）创建一个LuaJIT VM，Worker内所有协程共享VM。

（2）将Nginx I/O原语封装后注入Lua VM，允许Lua代码直接访问。

（3）每个外部请求都由一个Lua协程处理，协程之间数据隔离。

（4）Lua代码调用I/O操作等异步接口时会挂起当前协程（并保护上下文数据），而不阻塞Worker进程。

（5）I/O等异步操作完成时还原协程相关的上下文数据，并继续运行。

每个Nginx Worker进程持有一个Lua解释器或者LuaJIT实例，被这个Worker处理的所有请求共享这个实例。每个请求的Context会被Lua轻量级的协程分割，从而保证各个请求是独立的。ngx_lua采用onecoroutine-per-request的处理模型，对于每个用户请求，ngx_lua会唤醒一个协程用于执行用户代码处理请求，当请求处理完成后，这个协程会被销毁。每个协程都有一个独立的全局环境（变量空间），继承于全局共享的、只读的公共数据。所以，被用户代码注入全局空间的任何变量都不会影响其他请求的处理，并且这些变量在请求处理完成后会被释放，这样就保证所有的用户代码都运行在一个sandbox（沙箱）中，这个沙箱与请求具有相同的生命周期。得益于Lua协程的支持，ngx_lua在处理10 000个并发请求时只需要很少的内存。根据测试，ngx_lua处理每个请求只需要2KB的内存，如果使用LuaJIT就会更少。所以ngx_lua非常适合用于实现可扩展的、高并发的服务。

 Nginx Lua的配置指令

ngx_lua定义了一系列Nginx配置指令，用于配置何时运行用户Lua脚本以及如何返回Lua脚本的执行结果。

ngx_lua定义的Nginx配置指令大致如表8-2所示。

表8-2 ngx_lua定义的Nginx配置指令

ngx_lua配置指令在Nginx的HTTP请求处理阶段所处的位置如图8-6所示。

图8-6 ngx_lua配置指令在Nginx的HTTP请求处理阶段所处的位置

下面介绍Nginx Lua的常用配置指令。

（1）lua_package_path指令，它的格式如下：

lua_package_path lua-style-path-str

lua_package_path指令用于设置“.lua”外部库的搜索路径，此指令的上下文为http配置块。它的默认值为LUA_PATH环境变量内容或者Lua编译的默认值。lua-style-path-str字符串是标准的lua path格式，“；；”常用于表示原始的搜索路径。下面是一个简单的例子：

#设置纯Lua扩展库的搜寻路径(';;' 是默认路径)

lua_package_path '/foo/bar/?.lua;/blah/?.lua;;';

OpenResty可以在搜索路径中使用插值变量。例如，可以使用插值变量$prefix或${prefix}获取虚拟服务器server的前缀路径，server的前缀路径通常在Nginx服务器启动时通过-p PATH命令行选项来指定。

（2）lua_package_cpath指令，它的格式如下：

lua_apckage_cpath lua-style-cpath-str

lua_package_cpath指令用于设置Lua的C语言模块外部库".so"（Linux）或".dll"（Windows）的搜索路径，此指令的上下文为http配置块。lua-style-cpath-str字符串是标准的lua cpath格式，“；；”常用于表示原始的cpath。下面是一个简单的例子：

#设置C编写的Lua扩展模块的搜寻路径(也可以用 ';;')

lua_package_cpath '/bar/baz/?.so;/blah/blah/?.so;;';

同样，OpenResty可以在搜索路径lua-style-cpath-str中使用插值变量，比如通过$prefix或${prefix}获取服务器前缀的路径。

（3）init_by_lua指令，它的格式如下：

init_by_lua lua-script-str

init_by_lua指令只能用于http上下文，运行在配置加载阶段。当Nginx的master进程在加载Nginx配置文件时，在全局Lua VM级别上运行由参数lua-script-str指定的Lua脚本块。当Nginx接收到HUP信号并开始重新加载配置文件时，Lua VM将会被重新创建，并且init_by_lua将在新的VM上再次运行。

如果Lua脚本的缓存是关闭的，那么每一次请求都运行一次init_by_lua处理程序。通过lua_code_cache指令可以关闭Lua脚本缓存，缓存默认是开启的。

注意：在生产场景下都会开启Lua脚本缓存，在init_by_lua调用require所加载的模块文件会缓存在全局的Lua注册表package.loaded中，所以在这里定义的全局变量和函数可能会污染命名空间，当然也会影响性能。

（4）lua_code_cache指令，它的格式如下：

lua_code_cache on | off

lua_code_cache用于启用或者禁用Lua脚本缓存，可以使用的上下文有http、server、location配置块。当缓存关闭时，通过ngx_lua提供的每个请求都将在一个单独的Lua VM实例中运行。在缓存关闭的场景下，在set_by_lua_file、content_by_lua_file、access_by_lua_file等指令中引用的Lua脚本都将不会被缓存，所有的Lua脚本都将从头开始加载。

通过该指令，开发人员可以进行编辑刷新模型的快速开发，改动代码后不需要重启Nginx。

在缓存关闭的情况下，编写在nginx.conf配置文件中的内联Lua脚本并不会重新加载。例如由set_by_lua、content_by_lua、access_by_lua和rewrite_by_lua指定的Lua脚本块将不会被反复更新，Lua代码改动后需要重启Nginx。

关闭缓存会对整体性能产生负面的影响。例如，在禁用Lua脚本缓存后，一个简单的"hello world"Lua示例的性能可能会下降一个数量级。

强烈禁止在生产环境中关闭Lua脚本缓存，仅仅可以在开发期间关闭Lua脚本缓存。

（5）set_by_lua指令，它的格式如下：set_by_lua $destVar lua-script-str paramsset_by_lua指令的功能类似于rewrite模块的set指令，具体来说，是将Lua脚本块的返回结果设置在Nginx的变量中。set_by_lua指令所处的上下文和执行阶段与Nginx的set指令基本相同。

下面是一个简单的例子，将Lua脚本的相加结果设置给Nginx的变量$sum，具体的代码如下：

 location /set_by_lua_demo {
 #set指令定义两个Nginx变量
 set $foo 1;
 set $bar 2;
 #调用内联代码，将结果放入Nginx变量$sum
 set_by_lua $sum 'return tonumber(ngx.arg[1]) + tonumber(ngx.arg[2])' $foo $bar;
 echo $sum;
 }

在上面的代码中，set_by_lua指令调用一段非常简单的Lua脚本，将两个输入参数$a、$b累积起来，然后将相加的结果设置到Nginx变量$sum中。

启动Nginx，访问
http://nginx.server/set_by_lua_demo?foo=bar地址，得到的结果如图8-7所示。

图8-7 set_by_lua指令通过Lua脚本为Nginx变量设置值

使用set_by_lua配置指令时，可以在Lua脚本的后面带上一个调用参数列表。在Lua脚本中可以通过Nginx Lua模块内部内置的ngx.arg表容器读取实际参数。

（6）access_by_lua指令，它的格式如下：access_by_lua $destVar 
lua-script-straccess_by_lua执行在HTTP请求处理11个阶段的access阶段，使用Lua脚本进行访问控制。access_by_lua指令运行于access阶段的末尾，因此总是在allow和deny这样的指令之后运行，虽然它们同属access阶段。一般可以通过access_by_lua进行比较复杂的用户权限验证，因为能借助Lua脚本执行一系列复杂的验证操作，比如实时查询数据库或者其他后端服务。

我们来看一个简单的例子，利用access_by_lua实现ngx_access模块的IP地址过滤功能：

 location /access_demo {
 access_by_lua '
 ngx.log(ngx.DEBUG, "remote_addr ="..ngx.var.remote_addr);
 if ngx.var.remote_addr == "192.168.233.128" then
 return;
 end
 ngx.exit(ngx.HTTP_UNAUTHORIZED);
 ';
 echo "hello world";
 }

以上代码中能放行的IP地址为192.168.233.128，此IP为笔者机器上的虚拟CentOS地址。重启Nginx，在CentOS上通过curl命令访问/access_demo，得到的结果如下：

[root@localhost ~]#curl http://192.168.233.1/access_demo
hello world

如果请求的来源IP不是192.168.233.128，就通过ngx_lua模块提供的Lua函数ngx.exit中断当前的整个请求处理流程，直接返回401（表示未授权错误）给客户端。如果access_by_lua指令没有将HTTP请求处理流程中断，处于access阶段后面的content阶段就会顺利执行，echo指令的结果就能输出给客户端。

（7）content_by_lua指令，它的格式如下：

content_by_lua lua-script-str

content_by_lua指令用于设置执行在content阶段的Lua代码块，执行结果将作为请求响应的内容。该指令可以用于location上下文，执行于content阶段。

需要注意的是，lua-script-str代码块用于在Nginx配置文件中编写字符串形式的Lua脚本，可能需要进行特殊字符转义，所以在OpenRestyv0.9.17发行版之后的版本不鼓励使用此指令，改为使用content_by_lua_block指令代替。content_by_lua_block指令Lua代码块使用花括号“{}”定义，不再使用字符串分隔符。

至此，主要的Nginx Lua配置指令介绍完了。但是，以上只是介绍了set_by_lua、access_by_lua、content_by_lua，没有介绍set_by_lua_file、access_by_lua_file、content_by_lua_file等指令，后面的系列指令和前面对应的指令功能是一样的，只是Lua脚本所在的位置不是内联在Nginx配置文件中，而是写在了单独的脚本文件中。

 Nginx Lua的内置常量和变量

Nginx Lua常用的内置变量如表8-3所示。

表8-3 Nginx Lua常用的内置变量

Nginx Lua常用的内置常量大致如表8-4所示。

表8-4 Nginx Lua常用的内置常量