OpenResty 包含哪些元件?常用模組、Lua 庫與檢查方法
想在閘道器轉發請求前查一下 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 庫的目錄值得特別留意:
lualib/:存放 OpenResty 官方發行版自帶的 Lua 庫,比如開篇提到的redis.lua就在這裡。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 和 Alpine | RPM 系統(RHEL / CentOS 等) |
|---|---|---|---|
openresty | 啟動伺服器或檢查配置 | openresty | openresty |
resty | 在終端執行 OpenResty Lua 指令碼 | openresty-resty | openresty-resty |
restydoc | 在終端查閱本機離線文件 | openresty-restydoc | openresty-doc |
opm | 安裝和管理社群 Lua 包 | openresty-opm | openresty-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 官方部落格,也歡迎掃碼關注我們的微信公眾號。














