lua-nginx-module directives 中文版
作者：互联网
文档地址：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， 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， 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, except that the file specified by <path-to-lua-script-file> contains the Lua code or 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 指令来代替.
当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，不同之处在于指定的文件<path-to-lua-script-file>包含Lua代码，或者从v0.5.0rc32发行版开始将执行Lua / LuaJIT 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 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和 content_by_lua_file）和Lua模块中为Lua代码启用或禁用Lua代码缓存。
关闭时，ngx_lua提供的每个请求将从0.9.3发行版开始，在单独的Lua VM实例中运行。因此，set_by_lua_file，content_by_lua_file，access_by_lua_file等中引用的Lua文件不会被缓存，所有使用的Lua模块都将从头开始加载。有了这个，开发人员可以采用编辑和刷新方法。
但请注意，当您在nginx.conf文件中编辑内联Lua代码时，在nginx.conf中内联写入的Lua代码（如由set_by_lua，content_by_lua， access_by_lua和rewrite_by_lua指定的代码）将不会更新。因为只有Nginx配置文件解析器可以正确解析nginx.conf这个文件，所以唯一的方法是通过发送一个HUP信号或重新启动Nginx 来重新加载配置文件，。
即使启用代码缓存，由dofile或者loadfile 装载Lua的文件在* _by_lua_file不能被缓存（除非你自己缓存结果）。通常你可以使用init_by_lua 或者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 指令代替.
作为一个“内容处理程序”，and executes Lua code string specified in <lua-script-str> for every request. Lua代码可以进行API调用，并在独立的全局环境（即沙箱）中作为新的派生辅程序执行。(i.e. a sandbox).
不要在同一location中同时使用该指令和其他内容处理程序指令。例如，在同一个location中不能使用这个指令和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, 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 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 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, 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代码正在从创建定时器的原始请求完全分离的“轻线程”中运行。因此，与创建它们的请求（如子仓）具有相同生命周期的对象不能在原始请求和定时器用户回调函数之间共享。
标签：Nginx,module,content,lua,directives,file,Lua,ngx 来源： https://blog.51cto.com/u_15284125/2990191