lua-nginx-module directives 中文版

阳光穿透心脏的1/2处 2022-05-25 06:42 19阅读 0赞

*文档地址：https://github.com/openresty/lua-nginx-module*

*lua\_package\_path*

syntax: *lua\_package\_path <lua-style-path-str>*

default: *The content of LUA\_PATH environment variable or Lua's compiled-in defaults.*

context: *http*

使用[set\_by\_lua][set_by_lua]， [content\_by\_lua][content_by_lua]等指定的脚本来*设置*Lua module的搜索路径。路径字符串采用标准Lua路径形式，`;;` 可用于表示原始搜索路径。

从`v0.5.0rc29`发行版开始，特殊符号`$prefix`或`${prefix}`可用于搜索路径字符串中，以指示在启动Nginx服务器时`server prefix，该路径`通常由`-p PATH`命令行选项确定的路径。

***lua\_package\_cpath***

syntax: *lua\_package\_cpath <lua-style-cpath-str>*

default: *The content of LUA\_CPATH environment variable or Lua's compiled-in defaults.*

context: *http*

使用[set\_by\_lua][set_by_lua]， [content\_by\_lua][content_by_lua]等指定的脚本*设置*Lua C-module的搜索路径。cpath字符串采用标准的Lua cpath形式，`;;` 用来代表原始cpath。

从`v0.5.0rc29`发行版开始，特殊符号`$prefix`或`${prefix}`可用于搜索路径字符串中，来指示`server prefix在启动Nginx服务器时`通常由`-p PATH`命令行选项来确定该路径。

## init\_by\_lua\_file ##

**syntax:** *init\_by\_lua\_file <path-to-lua-script-file>*

**context:** *http*

**phase:** *loading-config*

同 [init\_by\_lua][init_by_lua], except that the file specified by `<path-to-lua-script-file>` contains the Lua code or [Lua/LuaJIT bytecode][Lua_LuaJIT bytecode] to be executed.

When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.

This directive was first introduced in the `v0.5.5` release.

## init\_worker\_by\_lua ##

**syntax:** *init\_worker\_by\_lua <lua-script-str>*

**context:** *http*

**phase:** *starting-worker*

**NOTE** `v0.9.17` r版本后该指令不建议使用. 使用 [init\_worker\_by\_lua\_block][init_worker_by_lua_block] 指令来代替.

当master进程启动时，在每个nginx worker进程启动时运行指定的lua代码。当master进程被禁用时，这个钩子将在init\_by\_Lua\*之后运行

此钩子通常用于为每个worker创建计时器（通过ngx.timer.at lua api），用于后端健康检查或其他定时例行工作。

*content\_by\_lua\_file*

语法： *content\_by\_lua\_file <path-to-lua-script-file>*

上下文： location, location if

阶段： content

等同于[content\_by\_lua][content_by_lua]，不同之处在于指定的文件`<path-to-lua-script-file>`包含Lua代码，或者从`v0.5.0rc32`发行版开始将执行[Lua / LuaJIT][Lua_LuaJIT bytecode] bytecode。

可以在`<path-to-lua-script-file>`字符串中使用Nginx变量来提供灵活性。然而，这存在一些风险，通常不推荐。

当给出一个相对路径比如*foo/bar.lua*时，在启动Nginx服务器时，它们将变成相对于*由*`-p PATH`*命令行选项确定的*`server prefix`路径的绝对路径。

当Lua代码缓存打开时（默认情况下），用户代码将在第一次请求时加载一次并缓存，并且每次Lua源文件*修改*时都必须重新加载Nginx配置。可*以在开发过程中临时禁用Lua code cache，*通过在*nginx.conf中*通过切换[lua\_code\_cache][lua_code_cache] *off*，以避免重新加载Nginx。

在动态分派的文件路径中支持Nginx变量，例如：

# CAUTION: contents in nginx var must be carefully filtered,

# otherwise there'll be great security risk!
     location ~ ^/app/([-_a-zA-Z0-9/]+) {
         set $path $1;
         content_by_lua_file /path/to/lua/app/root/$path.lua;
     }

但要小心恶意用户输入，并且始终仔细验证或过滤用户提供的路径组件。

*lua\_code\_cache*

语法: *lua\_code\_cache on | off*

默认: *lua\_code\_cache on*

上下文: *http, server, location, location if*

在`*_by_lua_file`指令（如[set\_by\_lua\_file][set_by_lua_file]和 [content\_by\_lua\_file][content_by_lua_file]）和Lua模块中为Lua代码启用或禁用Lua代码缓存。

关闭时，ngx\_lua提供的每个请求将从`0.9.3`发行版开始，在单独的Lua VM实例中运行。因此，[set\_by\_lua\_file][set_by_lua_file]，[content\_by\_lua\_file][content_by_lua_file]，[access\_by\_lua\_file][access_by_lua_file]等中引用的Lua文件不会被缓存，所有使用的Lua模块都将从头开始加载。有了这个，开发人员可以采用编辑和刷新方法。

但请注意，当您在nginx.conf文件中编辑内联Lua代码时，在nginx.conf中内联写入的Lua代码（如由[set\_by\_lua][set_by_lua]，[content\_by\_lua][content_by_lua]， [access\_by\_lua][access_by_lua]和[rewrite\_by\_lua][rewrite_by_lua]指定的[代码）][set_by_lua]将不会更新。因为只有Nginx配置文件解析器可以正确解析nginx.conf这个文件，所以唯一的方法是通过发送一个`HUP`信号或重新启动Nginx 来重新加载配置文件，。

即使启用代码缓存，由`dofile`或者`loadfile` 装载Lua的文件在\* \_by\_lua\_file不能被缓存（除非你自己缓存结果）。通常你可以使用[init\_by\_lua][init_by_lua] 或者[init\_by\_lua\_file][init_by_lua_file]指令来加载所有这些文件，或者使这些Lua文件成为真正的Lua模块并通过require加载它们。

ngx\_lua模块不支持`stat模式，`Apache `mod_lua`模块。

强烈建议禁用Lua代码缓存以供生产使用，并且仅应在开发过程中使用，因为它会对整体性能产生重大负面影响。例如，禁用Lua代码缓存后，“hello world”Lua示例的性能可能会下降一个数量级

***lua\_shared\_dict***

syntax: *lua\_shared\_dict <name> <size>*

default: *no*

context: *http*

phase: *depends on usage*

声明一个共享内存区域，`<name>`作为存储基于Lua词典的`ngx.shared.<name>的`shm。

在当前的nginx server实例中，共享内存区域总是由所有nginx工作进程共享。

`<size>`参数接受诸如`k`和`m的大小单位`：

http {

lua_shared_dict dogs 10m;
         ...
     }

硬编的最小size为8KB，而实际的最小大小取决于实际的用户数据设置（有些人以12KB开头）。

有关详细信息，请参阅[ngx.shared.DICT][]。

该指令是在`v0.3.1rc22`版本中首次引入的。

## content\_by\_lua ##

**syntax:** *content\_by\_lua <lua-script-str>*

**context:** *location, location if*

**phase:** *content*

**NOTE** 不建议使用该指令在 `v0.9.17` 版本之后. 使用 [content\_by\_lua\_block][content_by_lua_block] 指令代替.

作为一个“内容处理程序”，and executes Lua code string specified in `<lua-script-str>` for every request. Lua代码可以进行API调用，并在独立的全局环境（即沙箱）中作为新的派生辅程序执行。(i.e. a sandbox).

不要在同一location中同时使用该指令和其他内容处理程序指令。例如，在同一个location中不能使用这个指令和[proxy\_pass][proxy_pass] 指令

##  ##

## content\_by\_lua\_block ##

**syntax:** *content\_by\_lua\_block \{ lua-script \}*

**context:** *location, location if*

**phase:** *content*

类似于content\_by\_lua指令，只是这个指令直接在一对花括号(\{\})内联Lua源，而不是在NGINX字符串文本(需要特殊字符转义)中。

示例,

content_by_lua_block {
         ngx.say("I need no extra escaping here, for example: \r\nblah")
     }

该指令是在 `v0.9.17` 版本中首次引入的。

## content\_by\_lua\_file ##

**syntax:** *content\_by\_lua\_file <path-to-lua-script-file>*

**context:** *location, location if*

**phase:** *content*

相当于 [content\_by\_lua][content_by_lua], except that the file specified by `<path-to-lua-script-file>` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode][Lua_LuaJIT bytecode] to be executed.

Nginx 变量可以在`<path-to-lua-script-file>` 格式的string中使用来提供灵活性 . 然而，这会带来一些风险，通常不推荐。

当一个相对路径比如 `foo/bar.lua` is given, 在启动Nginx服务器时，他们将转换为绝对路径根据由-p PATH命令行选项确定的服务器 prefix路径

当Lua code cache 打开时 (默认为on), 在第一次请求时加载用户代码并缓存. 每次修改Lua源文件时都必须重新加载Nginx配置。The Lua code cache can be temporarily disabled during development by switching [lua\_code\_cache][lua_code_cache] `off` in `nginx.conf` to avoid reloading Nginx.

在开发期间通过在nginx.conf中设置lua\_code\_cache off 来暂时禁用Lua代码缓存，以避免重新加载Nginx，。

Nginx variables are supported in the file path for dynamic dispatch, for example:

# CAUTION: contents in nginx var must be carefully filtered,
     # otherwise there'll be great security risk!
     location ~ ^/app/([-_a-zA-Z0-9/]+) {
         set $path $1;
         content_by_lua_file /path/to/lua/app/root/$path.lua;
     }

But be very careful about malicious user inputs and always carefully validate or filter out the user-supplied path components.

操作系统api

### `os.execute ([command])` ###

This function is equivalent to the C function `system`. It passes `command` to be executed by an operating system shell. It returns a status code, which is system-dependent. If `command` is absent, then it returns nonzero if a shell is available and zero otherwise.

这个函数相当于C函数 `system, 它向操作系统shell传递要执行的command。它返回依赖系统的status状态码。如果command为空，那么返回非0，如果shell可用，那么可能返回0`

## Input and Output Facilities ##

### `io.popen (prog [, mode])` ###

Starts program `prog` in a separated process and returns a file handle that you can use to read data from this program (if `mode` is `"r"`, the default) or to write data to this program (if `mode` is `"w"`).

This function is system dependent and is not available on all platforms.

开始程序prog于额外的进程,并返回用于prog的文件句柄(并不支持所有的系统平台)

file:read(...)

功能：按指定的格式读取一个文件,按每个格式函数将返回一个字串或数字,如果不能正确读取将返回nil,若没有指定格式将指默认按行方式进行读取

格式：

"\*n": 读取一个数字

"\*a": 从当前位置读取整个文件,若为文件尾，则返回空字串

"\*l": \[默认\]读取下一行的内容,若为文件尾，则返回nil

number: 读取指定字节数的字符,若为文件尾，则返回nil;如果number为0则返回空字串,若为文件尾，则返回nil;

# Nginx API for Lua #

## ngx.hmac\_sha1 ##

**syntax:** *digest = ngx.hmac\_sha1(secret\_key, str)*

Computes the [HMAC-SHA1][] digest of the argument `str` and turns the result using the secret key `<secret_key>`.

The raw binary form of the `HMAC-SHA1` digest will be generated, use [ngx.encode\_base64][ngx.encode_base64], for example, to encode the result to a textual representation if desired.

## ngx.timer.at ##

**syntax:** *hdl, err = ngx.timer.at(delay, callback, user\_arg1, user\_arg2, ...)*

创建一个带有用户回调函数的Nginx定时器以及可选的用户参数。

**第一个参数**

**　　**delay指定定时器的延迟（以秒为单位）。可以指定小数秒0.001，这意味着1毫秒。0也可以指定延迟，在这种情况下，当当前处理程序产生执行时，定时器将立即过期。

**第二个参数**

**　　**callback可以是任何Lua函数，后面将在后面的“light thread”中调用延迟指定。用户回调将自动Nginx的芯与参数调用premature， user\_arg1，user\_arg2，和等等，其中，所述premature 参数采用一个布尔值指示是否它是一个过早的计时器期满或没有，和user\_arg1，user\_arg2和等等，是那些（额外的）用户调用ngx.timer.at 作为剩余参数时指定的参数。

当Nginx工作进程正在尝试关闭时，会发生提前定时器到期，如在Nginx配置中由HUP信号触发的重新加载或Nginx服务器关闭。当Nginx工作器试图关闭时，不能再调用ngx.timer.at创建具有非零延迟的新定时器，在这种情况下ngx.timer.at将返回nil，还有一个描述错误的字符串，即“进程退出”。

从v0.9.3发行版开始，即使Nginx工作进程开始关闭，也允许创建零延迟定时器。

当定时器到期时，定时器回调中的用户Lua代码正在从创建定时器的原始请求完全分离的“轻线程”中运行。因此，与创建它们的请求（如子仓）具有相同生命周期的对象不能在原始请求和定时器用户回调函数之间共享。

[set_by_lua]: https://github.com/openresty/lua-nginx-module#set_by_lua
[content_by_lua]: https://github.com/openresty/lua-nginx-module#content_by_lua
[init_by_lua]: https://github.com/openresty/lua-nginx-module#init_by_lua
[Lua_LuaJIT bytecode]: https://github.com/openresty/lua-nginx-module#lualuajit-bytecode-support
[init_worker_by_lua_block]: https://github.com/openresty/lua-nginx-module#init_worker_by_lua_block
[lua_code_cache]: https://github.com/openresty/lua-nginx-module#lua_code_cache
[set_by_lua_file]: https://github.com/openresty/lua-nginx-module#set_by_lua_file
[content_by_lua_file]: https://github.com/openresty/lua-nginx-module#content_by_lua_file
[access_by_lua_file]: https://github.com/openresty/lua-nginx-module#access_by_lua_file
[access_by_lua]: https://github.com/openresty/lua-nginx-module#access_by_lua
[rewrite_by_lua]: https://github.com/openresty/lua-nginx-module#rewrite_by_lua
[init_by_lua_file]: https://github.com/openresty/lua-nginx-module#init-by_lua_file
[ngx.shared.DICT]: https://github.com/openresty/lua-nginx-module#ngxshareddict
[content_by_lua_block]: https://github.com/openresty/lua-nginx-module#content_by_lua_block
[proxy_pass]: http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass
[HMAC-SHA1]: http://en.wikipedia.org/wiki/HMAC
[ngx.encode_base64]: https://github.com/openresty/lua-nginx-module#ngxencode_base64