lua-nginx-module

在 *_by_lua_file 指令（如 set_by_lua_file 和 content_by_lua_file）和 Lua 模块中启用或禁用 Lua 代码的 Lua 代码缓存。

关闭时，从 0.9.3 版本开始，ngx_lua 处理的每个请求都将在单独的 Lua VM 实例中运行。因此，set_by_lua_file，content_by_lua_file，access_by_lua_file 等中引用的 Lua 文件不会被缓存，所有使用的 Lua 模块都将从头开始加载。有了这个，开发人员可以编辑代码后可以不用重新加载代码。

但是请注意，在 nginx.conf 中编写内联的 Lua 代码（如 set_by_lua，content_by_lua，access_by_lua 和 rewrite_by_lua 指定的内容），在编辑后不会更新，因为只有 Nginx 配置文件解析器可以正确解析 nginx.conf 文件，唯一的方法是通过发送 HUP 信号重新加载配置文件或重新启动 Nginx。

即使启用了代码缓存，也无法缓存由 *_by_lua_file 中的 dofile 或 loadfile 加载的 Lua 文件（除非您自己缓存结果）。通常可以使用 init_by_lua 或 init_by_lua_file 指令加载所有这些文件，或者让这些 Lua 文件成为真正的 Lua 模块并通过 require 加载它们。

ngx_lua 模块不支持 Apache mod_lua 模块可用的 stat 模式。

强烈不推荐在生产环境中禁用 Lua 代码缓存，该功能只应在开发期间使用，因为它会对整体性能产生显著的负面影响。例如，在禁用 Lua 代码缓存后，“hello world” Lua 示例的性能可能会下降一个数量级。

当 Nginx 主进程加载 Nginx 配置文件时，在全局 Lua VM 级别运行由参数<lua-script-str>指定的 Lua 代码。

当 Nginx 收到 HUP 信号并开始重新加载配置文件时，Lua VM 也将被重新创建，init_by_lua 将在新的 Lua VM 上再次运行。 如果关闭 lua_code_cache 指令（默认打开），init_by_lua 处理程序将在每个请求时运行，因为在此特殊模式下，始终为每个请求创建一个独立的 Lua VM。

通常，可以通过 hook 在服务器启动时预加载 Lua 模块，因为此上下文中的 Lua 代码在 Nginx fork 其工作进程（如果有）之前运行，所以此处加载的数据或代码将享受许多操作系统提供的写时复制（COW）功能，从而节省了很多内存。

不要在此上下文中初始化自己的 Lua 全局变量，因为使用 Lua 全局变量会导致性能损失，并可能导致全局命名空间污染。 推荐的方法是使用正确的 Lua 模块文件（但不要使用标准的 module()来定义 Lua 模块，因为它也会污染全局命名空间），并调用 require() 来在 init_by_lua 或其他上下文中加载您自己的模块文件（require()会将加载的 Lua 模块缓存在 Lua 注册表中的全局 package.loaded 表中，这样该模块对于整个 Lua VM 实例加载一次）。

启用主进程时，在每个 Nginx 工作进程启动时运行指定的 Lua 代码。 当主进程被禁用时，将在 init_by_lua* 之后运行。

此挂钩通常用于创建每个 worker 重复发生的计时器（通过 ngx.timer.at），用于后端运行状况检查或其他定时例行工作。

思考：

• 该指令与 init_by_lua 有何不同？

  init_by_lua 主要声明公共模块。

• 为什么不能在 init_by_lua 中初始化定时器？

  因为 fork 的时候不能 fork 定时器。

请注意，此处理程序始终在标准 ngx_http_access_module 之后运行。

与其他访问阶段处理程序一样，access_by_lua 不会在子请求中运行。

请注意，在 access_by_lua 处理程序中调用 ngx.exit（ngx.OK）时，nginx 请求处理控制流仍将继续到内容处理程序。 要从 access_by_lua 处理程序中终止当前请求，成功退出请调用 ngx.exit(status) （200(ngx.HTTP_OK)<= status<300(ngx.HTTP_SPECIAL_RESPONSE)），失败退出请调用 ngx.exit（ngx.HTTP_INTERNAL_SERVER_ERROR）（或其其他类似）。

用来定义输出的 header 过滤器。

在 v0.9.17 版本之后，不鼓励使用此指令。 请改用 log_by_lua_block 指令。

在日志请求处理阶段运行作为 <lua-script-str> 内联的 Lua 源代码。这不会替换当前的访问日志，而是先与其运行。

请注意，此上下文中当前禁用了以下 API 函数：

• 输出 API 函数（例如，ngx.say 和 ngx.send_headers）
• 控制 API 函数（例如，ngx.exit）
• 子请求 API 函数（例如，ngx.location.capture 和 ngx.location.capture_multi）
• Cosocket API 函数（例如，ngx.socket.tcp 和 ngx.req.socket）。

用户代码中的网络 I/O 操作应该只通过 Nginx Lua API 调用来完成，因为 Nginx 事件循环可能会被阻止，这样性能会急剧下降。 相对少量数据的磁盘操作可以使用标准 Lua io 库完成，但应尽可能避免大量文件读取和写入，因为它们可能会显着阻止 Nginx 进程。 为了获得最佳性能，强烈建议将所有网络和磁盘 I/O 操作委派给 Nginx 的子请求（通过 ngx.location.capture 方法和类似方法）。

用来读写 nginx 变量值。

请注意，只能写入已定义的 nginx 变量。

小心：从 Nginx 变量读取时，Nginx 将在每个请求内存池中分配内存，该内存池仅在请求终止时释放。 因此，当需要在 Lua 代码中重复读取 Nginx 变量时，将 Nginx 变量值缓存到自己的 Lua 变量中，例如，

local val = ngx.var.some_var
 --- use the val repeatedly later

防止（临时）内存在当前请求的生命周期内泄漏。 缓存结果的另一种方法是使用 ngx.ctx 表。

此 API 需要相对昂贵的元方法调用，建议避免在热代码路径上使用它。

不要处于 worker 级别的数据共享，在 module 级别将 ngx.ctx 赋值给本地变量。

ngx.null 常量是一个 NULL light userdata，通常用于表示 Lua 表等中的 nil 值，类似于 lua-cjson 库的 cjson.null 常量。

此表可用于存储每个请求的 Lua 上下文数据，并具有与当前请求相同的生命周期（与 Nginx 变量一样）。

每个请求（包括子请求）都有自己的表 副本 。

内部重定向将销毁原始请求 ngx.ctx 数据（如果有），新请求将具有空的 ngx.ctx 表。

ngx.ctx 查找需要相对昂贵的元方法调用，并且比通过您自己的函数参数显式传递每个请求数据要慢得多。 因此，不要滥用此 API 来保存自己的函数参数，因为它通常会对性能产生很大的影响。

发出同步但仍无阻塞的 Nginx 子请求。

另请注意，子请求只是模仿 HTTP 接口，但没有额外的 HTTP / TCP 流量，也没有涉及 IPC。一切都在内部，高效，在 C 级别上运作。

请注意，ngx.location.capture 发出的子请求默认会继承当前请求的所有请求头部，这可能会对子请求响应产生意外的副作用。在子请求位置将 proxy_pass_request_headers 设为 off 可忽略原始请求头。

每个主要请求可能存在的并发子请求数存在硬编码上限。 在旧版本的 Nginx 中，限制是 50 个并发子请求，而在更新版本中，Nginx 1.1.x 以上，这增加到 200 个并发子请求。 超出此限制时，将在 error.log 文件中添加以下错误消息：

[error] 13983#0: *1 subrequests cycle while processing "/uri"

读取和写入当前请求的响应状态。 应该在发送响应头之前调用它。

返回一个浮点数，表示创建当前请求时的时间戳（包括作为小数部分的毫秒数）。

以下示例在纯 Lua 中模拟 $request_time 变量值（由 ngx_http_log_module 提供）：

local request_time = ngx.now() - ngx.req.start_time()

从 nginx 缓存时间返回当前时间戳记的纪元的经过 秒数 （与 Lua 的日期库不同，不涉及系统调用）。

从 nginx 缓存时间返回从当前时间戳的纪元开始的经过时间（包括作为小数部分的毫秒）的 浮点数 （与 Lua 的日期库不同，不涉及系统调用）。

获取由 lua_shared_dict 指令定义的名为 DICT 的共享内存区域对应的 Lua 字典对象。 共享内存区域始终由当前 nginx 服务器实例中的所有 nginx 工作进程共享。

所有这些方法都是原子操作，也就是说，对于同一个 lua_shared_dict 区域的多个 nginx 工作进程的并发访问是安全的。

检索字典 ngx.shared.DICT 中的 key。如果 key 不存在或已过期，则返回 nil

与 get 方法类似，但即使 key 已经过期，也会返回该值。

无条件的在 ngx.shared.DICT 中设置键值对。value 参数可以是 Lua 布尔值，数字，字符串或 nil。

与 set 方法类似，但在共享内存区域中的存储空间不足时，永远不会覆盖存储中（最近最少使用的）未过期的项目。在这种情况下，它将立即返回 nil 和字符串“no memory”。

类似 set 方法，但是只有键不存在，才将键值对存储到字典 ngx.shared.DICT 中。

如果键参数已存在于字典中（并且未确定过期），则成功返回值将为 false，并且错误返回值将为 “exists”。

与 add 方法类似，但在共享内存区域中的存储空间不足时，永远不会覆盖存储中（最近最少使用的）未过期的项目。在这种情况下，它将立即返回 nil 和字符串“no memory”。

就像 set 方法一样，但是只有 key 确实存在，才将键值对存储到字典 ngx.shared.DICT 中。

无条件地从 ngx.shared.DICT 中删除键值对。

通过步长值增加 ngx.shared.DICT 中的 key 的 value（数值）。如果操作成功完成，则返回新的结果数，否则返回 nil 和错误消息。

当 key 不存在或已在共享字典中过期时：

1. 如果未指定 init 参数或取值为 nil，则此方法将返回 nil 并且错误字符串 “not found”，或者
2. 如果 init 参数采用数字值，则此方法将创建一个值为 init + value 的新 key。

类似 add 方法，当共享内存区域中的存储空间不足时，它还会覆盖存储中（最近最少使用的）未过期的项目。

可选的 init_ttl 参数指定了在以 init 参数初始化后 key 的到期时间（以秒为单位）。时间分辨率为 0.001 秒。如果 init_ttl 取值 0（默认值），则该项将永不过期。该参数必须和 init 一起使用，并且如果该值已经存在则无效（例如，如果它先前是通过 set 或其他类似操作）。

更新 ngx.shared.DICT 中键值对的 exptime（以秒为单位）。 如果操作完成返回指示成功的布尔值，否则返回 nil 和错误消息。

如果该键不存在，则此方法将返回 nil 并且错误字符串 “not found”。

exptime 参数的分辨率为 0.001 秒。 如果 exptime 为 0，则该项将永不过期。

刷新字典中的所有项目。此方法不会释放字典中的所有内存块，而只是将所有现有项目标记为已过期。

刷新字典中的过期项，直到可选的 max_count 参数指定的最大数量。 当 max_count 参数给定 0 或根本没有给出时，则表示无限制。 返回实际刷新的项目数。

与 flush_all 方法不同，此方法实际上释放了过期项目使用的内存。

检索 ngx.shared.DICT 的可用页面大小（以字节为单位）。可用于告警。

创建并返回一个 TCP 或面向流的 unix 域套接字对象（也称为“cosocket”对象的一种类型）。此对象支持以下方法：

syntax: hdl, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)

Nginx 核心将自动调用用户回调，其参数为 premature，user_arg1，user_arg2 等，其中，premature 参数采用一个布尔值，指示它是否是一个 premature timer expiration。

premature timer expiration 发生在当 Nginx worker 进程尝试关闭时，例如在 HUP 信号触发的 Nginx 配置重新加载或 Nginx 服务器关闭时。 当 Nginx 工作者试图关闭时，人们不能再调用 ngx.timer.at 来创建具有非零延迟的新计时器，在这种情况下，ngx.timer.at 将返回 “conditional false” 值和描述错误的字符串 ，即 “process exiting”。

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

该字段采用整数值表示当前使用的 ngx_lua 模块的版本号。例如，版本号 0.9.3 导致 Lua 号 9003。

要在同一个 nginx 工作进程处理的所有请求之间全局共享数据，需要将共享数据封装到 Lua 模块中，使用 Lua require 导入模块，然后使用 Lua 操作共享数据。 之所以可以这么做是因为所需的 Lua 模块只加载一次，并且所有协程将共享模块的 相同副本（包括其代码和数据） 。 但请注意，由于每个请求的一个协程的隔离设计，Lua 全局变量（注意，不是模块级变量）不会在请求之间保持不变。

请注意，此数据共享基于 per-worker 而不是基于 per-server。也就是说，当 Nginx 主机下有多个 nginx 工作进程时，数据共享不能跨越这些工作进程之间的进程边界。

通常建议以这种方式共享只读数据。只要在计算过程中没有非阻塞 I/O 操作（包括 ngx.sleep），也可以在每个 nginx 工作进程的所有并发请求之间共享可更改的数据。只要不将控制权交给 nginx 事件循环和 ngx_lua 的轻量级线程调度程序（包括隐式的转移控制权），就不会有任何竞争条件。因此，当想要在 worker 级别共享可更改数据时，请务必非常小心。可能导致 bug 的优化很容易导致以调试的竞争条件。

如果需要服务器范围的数据共享，请使用以下一种或多种方法：

• 使用此模块提供的 ngx.shared.DICT API。
• 仅使用单个 nginx 工作器和单个服务器（但是，如果在单个计算机中存在多核 CPU 或多个 CPU，则不建议使用此方法）。
• 使用数据存储机制，如 memcached，redis，MySQL 或 PostgreSQL。内嵌该模块的 OpenResty 软件包附带了一组配套的 Nginx 模块和 Lua 库，它们提供与这些数据存储机制交互的接口。

待补充

待补充

待补充

主要提供了一系列 to_hex() 和 atoi()两个函数。

这个 lua 库是 ngx_lua 的远程日志记录模块。旨在取代 Nginx 的标准 ngx_http_log_module，以通过非阻塞套接字将访问日志推送到远程服务器。该库利用了 ngx_lua 的 cosocket API，后者确保了 100％的非阻塞行为。