想在网关转发请求前查一下 Redis,判断某个账号能不能访问?用 OpenResty,你不需要去改写 NGINX 的 C 源码,而是可以直接在 NGINX 的请求处理流程中写几行 Lua,再调一下自带的 Redis 客户端库。请求转发依然交给最擅长这件事的 NGINX,额外的业务判断则由灵活的 Lua 代码搞定。

这看似简单的配合,背后其实是几个核心组件在各司其职:ngx_lua 把 Lua 接入请求处理流程,LuaJIT 负责高速执行 Lua 代码,而 lua-resty-redis 则负责与 Redis 通信。

本文将从日常开发任务出发,带你摸清 OpenResty 里都有哪些常用“零件”,以及在遇到问题时,怎么快速确认它们在你的环境里到底能不能用。如果你想先了解平台的整体定位和应用场景,可以先读读上一篇 OpenResty 是什么。

先看几个核心组件怎么配合

我们还是以查询 Redis 为例,看看一条请求进来后发生了什么:首先,NGINX 负责接收请求和管理连接;接着,ngx_lua 让你能够在请求处理的不同阶段插入 Lua 代码;LuaJIT 负责把这些代码跑起来;当代码里需要查 Redis 时,再去调用 lua-resty-redis。

刚接触 OpenResty 时,大家最容易搞混的一件事就是:NGINX 模块和 Lua 库到底有什么区别?

简单来说:NGINX 模块用来扩展服务器本身的能力,而 Lua 库则是给你的 Lua 代码调用的。 比如,ngx_lua 是一个 NGINX 模块,它为你提供了在配置里写 Lua 的入口以及一整套 ngx.* API;而 lua-resty-redis 是一个 Lua 库,你在代码里写一句 require "resty.redis" 就能把它加载进来,帮你跟 Redis 打交道。

除了这些直接跟业务打交道的库,还有一个你可能很少直接调用、但绝对离不开的幕后功臣——lua-resty-core。它用 LuaJIT FFI 重新实现了许多常用的 ngx.* 接口。虽然它不像 Redis 客户端那样对应某项具体业务,却是整个 OpenResty 高性能运行的重要底座。

顺便一提,LuaJIT 也可以通过终端里的 luajit 命令单独拿来跑普通的 Lua 脚本;但只要代码里用到了 ngx.* API,就必须在 OpenResty 提供的环境中运行了。想进一步了解这位“幕后引擎”,可以阅读 OpenResty 中的 LuaJIT。

常用模块和库有哪些?

理清了它们的关系,我们再来盘点一下最常打交道的组件。下面按用途分了三类,方便你在遇到实际需求时按图索骥。

服务器模块

  • ngx_lua(lua-nginx-module):最核心的模块,让你能在 HTTP 请求处理的不同阶段运行 Lua 代码,并提供 ngx.* API。
  • ngx_stream_lua(stream-lua-nginx-module):作用与 ngx_lua 类似,但专门用于处理 TCP/UDP 四层流量。
  • headers-more(headers-more-nginx-module):让你直接通过 NGINX 配置指令,方便地添加、修改或清除 HTTP 请求头与响应头。

这些 NGINX 模块既可以在编译时静态编入服务器,也可以构建为动态模块(视模块支持情况而定),在配置文件中按需加载。

Lua 库

  • lua-resty-core:基于 LuaJIT FFI 实现部分 ngx.* 接口的核心基础库。
  • lua-resty-redis、lua-resty-mysql:非阻塞的 Redis 和 MySQL 客户端库,常用于查询账号、配置或业务状态。
  • lua-cjson:高性能地完成 Lua table 与 JSON 数据之间的互相转换。
  • lua-resty-lrucache、lua-resty-lock:前者提供 Worker 进程内的 LRU 缓存,后者提供基于共享内存字典的非阻塞锁(常用于应对缓存击穿)。
  • lua-resty-limit-traffic:用来控制请求速率和并发连接数,是实现网关限流策略的利器。
  • lua-resty-websocket:在 Lua 中轻松实现 WebSocket 服务端或客户端通信。
  • lua-resty-upstream-healthcheck:主动检查 NGINX 上游(Upstream)服务器的健康状态并自动摘除异常节点,需配合相应的模块与配置使用。

上面列出的只是冰山一角,完整名单可以查阅 OpenResty 官方组件列表。需要注意的是,列表里的组件并不一定全都默认打包进了你的安装包里;即便装了,有些也需要额外配置才能启用。动手写代码前,最好先在自己的环境里确认一下。

命令行工具

除了跑服务,OpenResty 还准备了几个顺手的命令行工具(通常由独立的可选软件包提供):

  • resty:直接在终端里跑 OpenResty Lua 脚本,平时用来写个小测试或调试代码非常方便。
  • restydoc:在终端里直接翻阅本机自带的权威文档,不用到处搜网页。
  • opm:官方的包管理器,用来安装和管理社区贡献的第三方 Lua 包。

从安装目录查找组件

装好 OpenResty 后,这些组件都放在哪儿呢?

我们以 Ubuntu 24.04(ARM64)下的官方 DEB 包(1.31.8.1-1~noble1,可参考官方包目录)为例。如果你同时安装了主包 openresty 以及 openresty-resty、openresty-restydoc、openresty-opm 这三个工具包,打开 /usr/local/openresty/ 目录,你会看到类似下面的结构(还没安装的读者可以先看目录建立直观印象,稍后再参考 安装 OpenResty 动手操作):

/usr/local/openresty/
├── bin/                       # openresty、resty、restydoc、opm 命令
├── nginx/
│   ├── conf/nginx.conf        # 默认服务器配置
│   └── sbin/nginx             # 服务器二进制
├── luajit/                    # LuaJIT 命令和运行库
├── lualib/
│   └── resty/
│       ├── core.lua
│       └── redis.lua          # 发行版自带的 Redis 客户端
├── pod/                       # restydoc 的文档数据
└── site/
    └── lualib/                # 系统级 OPM Lua 库的安装位置

在这里,有两个存放 Lua 库的目录值得特别留意:

  1. lualib/:存放 OpenResty 官方发行版自带的 Lua 库,比如开篇提到的 redis.lua 就在这里。
  2. site/lualib/:当你用 opm 全局安装第三方社区库时,它们会落在这个目录下(如果加上 opm --cwd,则会装到你当前的项目目录中)。

平时如果遇到 require 某个库报错找不到的情况,除了去这两个目录看看文件在不在,还要检查一下 nginx.conf 里的 lua_package_path 是不是把库所在的路径给漏掉了。

更多用法可以参考 OPM 官方文档 和 OpenResty Lua 模块教程。

检查自己的安装

写代码或做运维时,我们常会遇到“明明文档里有这个功能,为什么我这里报错用不了”的情况。其实,不同组件的排查路子完全不同:

想确认什么怎么查注意点 / 局限性
终端调用的是哪个程序command -v openresty、openresty -V你在终端敲的,不一定是线上服务正在跑的
C 模块有没有编进去检查目标二进制的 -V 输出编译成了动态模块,不代表配置文件加载了它
配置是否加载动态模块用目标二进制及配置参数执行 -T,查 load_module结果仅针对你指定检查的那份配置文件生效
Lua 库能不能正常加载在对应的运行上下文中执行 require库能加载成功,不代表能连上外部服务
工具命令为什么找不到查软件包安装状态和环境变量 PATH命令行工具没装,不影响服务器本身跑业务

下面我们按顺序一步步来排查。

1. 确认二进制程序和构建参数

排查的第一步,是搞清楚你在终端里敲 openresty 时,调用的到底是哪个程序,以及它在编译时塞进了哪些模块:

command -v openresty
readlink -f "$(command -v openresty)"
openresty -V

在我们的 Ubuntu 示例环境中,/usr/bin/openresty 实际上是一个指向 /usr/local/openresty/nginx/sbin/nginx 的符号链接。执行 openresty -V 后,你会看到类似下面的输出(为了方便阅读,这里做了分行):

nginx version: openresty/1.31.8.1
--prefix=/usr/local/openresty/nginx
--add-module=../ngx_lua-0.10.32rc7
--add-module=../ngx_stream_lua-0.0.20rc3

怎么看这段输出呢?

  • --prefix:编译时设定的默认工作目录前缀(启动时可以通过 -p 参数临时覆盖它)。
  • --add-module:说明这个模块已经静态编译进了服务器二进制里,开箱即用。
  • --add-dynamic-module:说明它被编译成了动态模块。要让它干活,还得看你的配置文件里有没有写 load_module。关于这些参数的更多细节,可以查阅 NGINX 命令行参数 与 NGINX 构建选项。

一个常见的线上踩坑点:有时候机器上装了不止一个 NGINX 或 OpenResty,你在终端直接敲的命令,根本不是后台正在跑的那个服务。如果服务是通过 systemd 托管的,建议先用 systemctl show -p ExecStart openresty 揪出它真正执行的二进制路径和启动参数(比如 -p、-c、-g),然后用完全一致的二进制和参数加上 -T 去导出完整配置,再在里面搜索 load_module,这样查出来的结果才最靠谱。

2. 验证 Lua 库能否加载

确认了服务器模块,再来试试 Lua 库。自带的 lua-resty-redis 已经随主包安装好了,如果你也装了 resty 命令行工具,直接在终端跑一行代码就能验明正身:

resty -e 'require "resty.redis"; print("resty.redis loaded")'

看到打印出 resty.redis loaded,就说明库文件完好且能被正常加载。

如果终端提示找不到 resty 命令,我们需要去查一下工具包和 PATH(见下一节);如果报错 module not found,那就去前面说的 lualib 目录找找文件,并核对 Lua 的搜索路径。当然,这行命令只是在 resty 的默认环境里测试加载,并没有真正去连 Redis;如果你的网关项目自己改写了 lua_package_path,别忘了回到实际的服务实例里再验证一次。

3. 检查命令行工具包

有时候服务器跑得好好的,但你想用 restydoc 查个文档,或者用 opm 装个包,终端却提示 command not found。这通常是因为它们被拆分到了独立的可选包里:

命令用途Debian / Ubuntu 和 AlpineRPM 系统(RHEL / CentOS 等)
openresty启动服务器或检查配置openrestyopenresty
resty在终端运行 OpenResty Lua 脚本openresty-restyopenresty-resty
restydoc在终端查阅本机离线文档openresty-restydocopenresty-doc
opm安装和管理社区 Lua 包openresty-opmopenresty-opm

比如在 Ubuntu 下,安装 openresty 主包时,APT 通常会顺带把推荐的 openresty-resty 和 openresty-opm 一起装上,但 openresty-restydoc 往往需要你手动补装。遇到命令找不到时,你可以先用 dpkg -s openresty-restydoc 看看装没装,再用 dpkg -L openresty-restydoc 看看它被装到了哪个目录、在不在你的 PATH 里。不同系统的包拆分规则可以查阅官方的 DEB 包说明、RPM 包说明 和 Alpine 包说明。

顺带提一个特例:如果你听说过 OpenResty 社区里大名鼎鼎的测试框架 Test::Nginx,去安装目录里却怎么也找不着它——别慌,因为它是直接安装在 Perl 环境里的独立模块,并不在 /usr/local/openresty/ 下。在本系列教程的后续文章中,我们会专门请出它来测试我们写好的小网关。

常见问题

可以去掉用不到的模块或工具吗?

这要看你想去掉的是哪一类组件:

  • 静态模块:它们在编译时就已经和服务器二进制文件融为一体了。如果你对二进制体积或安全性有极高要求,非剔除不可,那就只能在重新编译构建 OpenResty 时,去掉对应的 --add-module 参数。
  • 动态模块:处理起来简单得多。先确认你的业务配置和其他模块都没有依赖它,然后删掉配置文件里的相关指令和 load_module 语句,最后用目标二进制加上 -t 测试一下配置语法即可。
  • 命令行工具:像 restydoc、opm 这些独立工具,直接通过系统的包管理器(如 apt 或 yum)卸载对应的可选包就行,卸载时留意一下包依赖提示即可。

总结与下一步

刚开始接触 OpenResty 时,你完全不需要把上面那长串组件名全都背下来。

你只需要先在脑海里建立起最核心的三角骨架——NGINX 管网络与转发,ngx_lua 搭桥,LuaJIT 跑代码——等业务上真正需要查数据库、做缓存或限流时,再去翻出对应的 lua-resty-* 库即可。万一遇到模块或库加载报错,先别急着改代码,按本文的方法先确认“是不是找对了实例”,再去查编译参数、库路径或工具包,绝大多数环境问题都能迎刃而解。

本文是 OpenResty 教程系列 的一部分。摸清了家底之后,接下来可以阅读「在 NGINX 里写 Lua 脚本入门」,正式动手看看“在 NGINX 配置文件里直接写 Lua 代码”到底是怎么一回事。

关注我们

欢迎访问 OpenResty 官方博客,也欢迎扫码关注我们的微信公众号。

OpenResty 博客微信公众号