OpenResty 能做什么：把 Nginx 变成可编程服务器

大纲

做后端这些年，我对一类技术一直有偏爱：它不发明新概念，只是把两个成熟的东西焊在一起，然后产生了 1+1 远大于 2 的效果。OpenResty 就是典型——它把 Nginx 和 LuaJIT 焊在一起，让你能用脚本语言，在那个以快著称的 Web 服务器里直接写业务逻辑。

一句话：它是一台能编程的 Nginx

先把最容易混淆的定位说清楚：OpenResty 不是 Nginx 的分叉（fork），而是在 Nginx 基础上扩展出来的平台。 官方自己强调过这一点——它跟随官方 Nginx 版本升级，可执行文件仍然叫 nginx，你现有的 nginx.conf 原样就能跑。

区别在哪？普通 Nginx 想加一段自定义逻辑，你得写 C 模块、重新编译。OpenResty 在每个 Nginx worker 进程里内嵌了一个 LuaJIT 虚拟机，再暴露一套 ngx.* 的非阻塞 API。于是你不用碰 C，直接用 Lua 写请求处理逻辑，一次改一个 location，渐进式地把普通 Nginx 变成应用服务器。

一个最小例子，直接在配置里嵌一段 Lua：

server {
    location /hello {
        content_by_lua_block {
            ngx.say("Hello from OpenResty, worker pid: ", ngx.worker.pid())
        }
    }
}

curl localhost/hello 就能看到输出。这还只是开胃菜——真正值钱的是，这段 Lua 里你能非阻塞地连 Redis、查 MySQL、发 HTTP 请求、起定时器，而这些操作都不会卡住 Nginx 的事件循环。

一句话记住它：如果你需要"可编程的请求逻辑"，用 OpenResty；如果你只要一个不带自定义代码的反向代理或静态文件服务器，光用 Nginx 就够了。

它到底能做什么

OpenResty 最擅长的，是那些逻辑必须跑在请求路径上的活儿。把这类逻辑放到 Nginx 之外的独立服务里，每个请求都要多一次网络往返，还要多部署、多监控一套服务；靠频繁 reload 来更新路由，又会抖动延迟、重置负载均衡状态。OpenResty 的做法是把逻辑直接塞进 Nginx 进程本身。

常见用途：

• 可编程 API 网关：鉴权、限流、路由、协议转换——Kong 和 APISIX 就是干这个的。
• Web 应用防火墙（WAF）：在请求进后端之前，用 Lua 跑规则拦截恶意流量。Cloudflare 早年那套新 WAF 就是"编译成 Lua"在 Nginx 里跑的。
• 带自定义逻辑的反向代理：token 校验、A/B 路由、灰度分流、请求改写，这些原本要靠 sidecar 或一次外部调用的事，现在在事件循环内部纳秒级搞定。
• CDN 边缘节点：动态回源、按地域/设备改写响应。
• 高并发 Web 服务：对延迟和并发要求高的接口，直接在 Nginx 里实现，用非阻塞方式访问 MySQL、PostgreSQL、Redis、Memcached。

还有个常被忽略的小工具：resty 命令行。它在后台偷偷起一个无头 Nginx，让你不写 nginx.conf 就能在终端里直接跑 Lua、测 cosocket、玩 shared dict：

resty -e 'ngx.say("hi")'
resty --shdict 'cache 10m' -e 'ngx.shared.cache:set("k", 1) ngx.say(ngx.shared.cache:get("k"))'

调试、验证想法、写单测，都靠它。

架构：三句话讲明白它为什么快

OpenResty 的工作方式可以浓缩成三句话。理解了这三句，你就理解了它所有优势和所有坑的来源。

第一句：Nginx 负责网络和事件循环。 每个 worker 进程只用一个线程，通过事件驱动的方式同时承载成千上万个连接。这是 Nginx 本来就有的本事，OpenResty 原封不动继承。

第二句：Lua 代码挂在请求处理的各个阶段上。 Nginx 把一个请求的处理切成若干阶段——rewrite、access、content、log 等等，响应发出前还要过 header/body 过滤器。OpenResty 的核心组件 ngx_lua 允许你在这些位置插 Lua 代码：rewrite_by_lua*、access_by_lua*、content_by_lua*；需要转发给上游时，还能用 balancer_by_lua* 按自己的逻辑挑上游节点。每个请求都跑在自己的一个 Lua 协程里。

第三句：访问后端时走 cosocket，不阻塞线程。 这是整个架构的灵魂。cosocket 是 OpenResty 提供的一套非阻塞网络 API。当你的 Lua 代码去连 Redis、MySQL 或上游 HTTP 服务时，cosocket 会在等数据期间把当前协程挂起（yield），让 worker 腾出手去处理别的请求；数据到了，Nginx 再唤醒（resume）这个协程。

妙在哪？对写代码的人来说，这看起来就是普通的同步调用。 你写的是一行行顺序的 Lua，底层却是异步非阻塞的。没有回调地狱，没有 Promise 链，却拿到了异步的性能。

local redis = require "resty.redis"
local red = redis:new()
red:set_timeout(1000)

local ok, err = red:connect("127.0.0.1", 6379)   -- 这里会 yield，worker 去干别的
if not ok then
    ngx.log(ngx.ERR, "connect redis failed: ", err)
    return ngx.exit(500)
end

local res = red:get("some_key")                   -- 同样 yield，代码读起来却是同步的
ngx.say(res)

再补两个关键点：每个 worker 各有一个独立的 LuaJIT 虚拟机，热点代码会被 JIT 即时编译成机器码，这是它快的另一半原因；worker 之间要共享的数据——计数器、限流状态、缓存——放在 lua_shared_dict 这块共享内存里。

下面这张图把一个请求从进来到出去的路径画全了：

@startuml
skinparam monochrome false
skinparam shadowing false
skinparam defaultFontSize 13

participant "Client" as C
box "Nginx Worker（单线程 + 事件循环）" #F8F9FA
participant "请求协程\n(Lua coroutine)" as L
participant "LuaJIT VM" as VM
end box
participant "后端\nRedis/MySQL/HTTP" as B

C -> L : 请求到达
activate L
L -> L : rewrite_by_lua\naccess_by_lua（鉴权/限流）
L -> VM : 热点代码 JIT 编译
L -> B : cosocket 发起连接
note right of L : yield 挂起\nworker 去处理其它请求
B --> L : 数据就绪
note right of L : Nginx resume 唤醒
L -> L : content_by_lua（生成响应）
L --> C : 响应返回
L -> L : log_by_lua（埋点/指标）
deactivate L
@enduml

优势：好在把逻辑放进了请求路径

• 逻辑和流量零距离：业务代码就在请求路径上，不用多一跳网络往返，延迟是亚毫秒级的。Kong 官方博客就说过，正是靠 OpenResty 它才能做到 sub-millisecond 的处理延迟。
• 改路由不用 reload：传统 Nginx 改配置得 reload，会抖动连接、重置负载均衡状态。OpenResty 可以把路由规则放进共享内存或后端，运行时动态更新，不中断服务。
• 单机高并发：官方的说法是单机能扛 10K 到 1000K+ 连接。得益于 Nginx 的事件模型加 Lua 协程，这不是吹的——前提是你没写出阻塞代码（这条下面会重点讲）。
• 用脚本语言写业务：开发效率比写 C 模块高一个数量级，部署运维又完全沿用 Nginx 那一套，团队不用学全新的东西。
• 开源免费：BSD 许可，和 Nginx 一样，生产环境用不花一分钱授权费。

劣势：坑也都在那条请求路径上

好东西总有代价，OpenResty 的代价和它的优势是同一枚硬币的两面。

• Lua 生态小：和 Python、Java、Go 比，Lua 的第三方库少得可怜。很多轮子你得自己造，或者用 lua-resty-* 系列（够用，但覆盖面有限）。
• 调试门槛高：出了问题，开源版主要靠日志、指标和人工分析。CPU 飙高、内存上涨、请求变慢时，定位起来比常规服务难。官方为此专门做了商业工具 OpenResty XRay（用动态追踪画火焰图，不改代码不重启就能定位热点），但那是付费的，不是必需品。
• 一行阻塞拖垮全局：单线程事件循环是双刃剑。一个协程里只要有一次真正的阻塞调用，整个 worker 上排队的其他请求全被卡住。这是 OpenResty 最大的"新手杀手"，下一节细说。
• 开源版没控制台：节点一多，开源 OpenResty 本身不提供配置分发和集中管理的控制台。要么自己搭一套，要么上商业的 OpenResty Edge。
• Lua 本身的坑：从别的语言切过来的人，会在数组从 1 开始、nil 不能当值、表比较引用这些地方反复栽跟头。这些我在另一篇讲 Lua 三十个常见错误里专门拆过，这里不展开。

成功案例：你的流量大概率过过它

空谈架构不如看谁在用。OpenResty 的作者章亦春（GitHub ID: agentzh）曾在 Cloudflare、雅虎、阿里巴巴工作过，这也解释了它为什么从诞生起就奔着超大规模流量去。

一个具体数字：Kong Cloud 用 OpenResty 在边缘层收集请求指标，重构后用更少的算力扛住了 100 万+ RPS 的监控流量。它的做法很典型——在每个请求的 log 阶段跑 Lua，把指标存进 worker 本地内存，再汇总上报。这正是"逻辑挂在请求阶段上"的教科书式用法。

生态圈：核心、社区库、商业库，三层

前面说 OpenResty 的劣势之一是"Lua 生态小"。这话对，也不全对——通用 Lua 库确实少，但围绕 OpenResty 自己的那套 lua-resty-* 生态，其实相当成熟。理解它的生态，按三层看最清楚。

第一层：核心与官方子项目。 人们常把 OpenResty 等同于 lua-nginx-module（ngx_lua），但那只是冰山一角。OpenResty 仓库下有近七十个子项目，常打交道的有这么几个：

第二层：社区的 lua-resty-* 库。 这是日常开发真正高频用到的部分，覆盖了后端开发的大半需求：

• 数据库 / 缓存：lua-resty-redis、lua-resty-mysql、lua-resty-memcached
• 网络：lua-resty-http（社区最常用的 HTTP 客户端）、lua-resty-dns、lua-resty-websocket
• 限流 / 锁 / 健康检查：lua-resty-limit-traffic、lua-resty-lock、lua-resty-upstream-healthcheck
• 其它：lua-resty-mail（发邮件）、lua-resty-jwt、lua-resty-signal（非阻塞杀进程）

挑库有一条铁律（上一节也强调过）：优先选 lua-resty-* 这类基于 cosocket 的非阻塞库，别用 Lua 标准库里那些同步阻塞的实现。 一个阻塞库能让你前面所有的架构优势清零。

第三层：商业私有库。 OpenResty Inc.（就是做出 OpenResty 的那家公司）还卖一套"*-fast"私有库，用纯 C 核心重写了常见组件，接口和开源版保持一致、可无痛替换：lua-resty-redis-fast（官方说最高到开源版的 2.5 倍）、lua-resty-http-fast、lua-resty-mysql-fast、jit.cjson 等。这些是付费订阅、闭源的，开源项目用不到——但它解释了为什么大流量公司愿意为 OpenResty 生态付费：瓶颈往往就卡在这几个客户端上。

opm 的用法：OpenResty 的包管理器

有了生态，就得有装包的工具。opm 是 OpenResty 官方的包管理器，定位类似 Perl 的 CPAN、Node 的 npm——从中央仓库 opm.openresty.org 拉社区发布的包。

先确认它在不在。 从 1.11.2.2 版本起，Linux 版 OpenResty 默认就带 opm，一般装在 /usr/local/openresty/bin/opm，你不用自己装。它运行只依赖 perl、tar、curl 这三样。

一个容易踩的坑：Docker 的 alpine 镜像为了瘦身，默认不带 curl 和 perl，opm 就跑不起来。需要 apk add --no-cache curl perl 补上，或者直接用 alpine-fat 这类完整镜像。用 apt/dnf 装时，CLI 工具也是单独的包：openresty-opm、openresty-resty、openresty-restydoc。

日常命令，照着用就行：

# 搜包：按名字和简介里的关键词搜，可以多个词叠加
opm search lock
opm search lru cache

# 装包：推荐用「作者/包名」的全限定名，避免重名歧义
opm get pintsized/lua-resty-http
opm get openresty/lua-resty-lock

# 还能指定版本约束
opm get openresty/lua-resty-lock '=0.08'

# 看、列、升、删
opm info lua-resty-http     # 看某个已装包的详情
opm list                    # 列出所有已装包和版本
opm upgrade lua-resty-http  # 升级指定包
opm update                  # 升级所有已装包
opm remove lua-resty-http   # 卸载

全局装 vs 项目内装。 默认 opm get 装到系统级目录（要 sudo），全机共享。但生产项目更推荐用 --cwd 装进项目自己的 ./resty_modules/，依赖跟着项目走，不污染全局、便于复现：

# 装进当前目录的 ./resty_modules/，不碰系统目录
opm --cwd get pintsized/lua-resty-http

用了 --cwd，记得在 nginx.conf 的 http {} 块里把搜索路径指过去，否则 require 找不到模块：

http {
    lua_package_path  "$prefix/resty_modules/lualib/?.lua;;";
    lua_package_cpath "$prefix/resty_modules/lualib/?.so;;";
}

然后从项目目录启动：openresty -p $PWD/。

opm 和 LuaRocks 怎么选？ LuaRocks 是 Lua 通用的包管理器，鼎盛时轮子最多；opm 是 OpenResty 专用的。官方的态度很明确：在 OpenResty 里优先用 opm，不推荐用 LuaRocks（官网那页 LuaRocks 教程直接标了 deprecated）。原因也和那条铁律一脉相承——LuaRocks 里混着大量"与 OpenResty 无关"的通用 Lua 模块，它们大概率是同步阻塞的，装进来一不留神就会阻塞 worker。opm 收的包基本都是为 OpenResty 非阻塞模型写的，踩雷概率低得多。opm 目前主要支持纯 Lua 库，并提供了一个实验性的 opm get luarocks/<包名> 通道去装 LuaRocks 包——但官方自己都提醒：这有引入阻塞模块的风险，用的时候心里要有数。

发布自己的包也走 opm：在项目目录里 opm build 打包、opm upload 上传到中央仓库，和 npm publish 的体验差不多。

最佳实践：五条能救命的规矩

写了这么多架构，落到实处就是几条朴素但致命的规矩。按重要性排：

1. 永远不要阻塞（这条值 15 倍性能）

这是 OpenResty 开发的第一铁律，没有之一。单线程事件循环下，一次阻塞调用会让整个 worker 上的其他请求全部排队等待。

有人做过一个经典对比实验，两个接口都 sleep 10 毫秒：

location /sleep_1 {
    content_by_lua_block {
        ngx.sleep(0.01)      -- OpenResty 的非阻塞 sleep，只切协程
        ngx.say("ok")
    }
}

location /sleep_2 {
    content_by_lua_block {
        os.execute("sleep 0.01")  -- 系统阻塞调用，整个进程睡过去
        ngx.say("ok")
    }
}

压测结果：用了 os.execute 的阻塞版本，Nginx 的并发处理能力下降了约 15 倍。原因很简单——ngx.sleep 只触发进程内协程切换，进程还在跑别的请求；os.execute("sleep") 却让整个进程睡过去，CPU 直接空转。

所以有一条基本原则：尽量用 OpenResty 的库函数，尽量别用 Lua 标准库——因为 Lua 的库大多是同步阻塞的。 查文档时，lua-nginx-module 的文档是你的首选。

2. 实在要调外部命令，用 FFI 或专用库绕开

有时你确实得调外部命令——杀进程、生成密钥、拷文件。os.execute 在 OpenResty 里会阻塞当前请求，命令跑几百毫秒，服务性能就塌一截。两种解法：

• 优先用 FFI 调 C 函数。比如要生成 RSA 密钥，别 os.execute("openssl ...")，改成用 FFI 调 OpenSSL 的 C 函数；要杀进程，用 OpenResty 自带的 lua-resty-signal（它底层也是 FFI）。
• 或者用基于 ngx.pipe 的 lua-resty-shell，在 shell.run 里跑命令，这是非阻塞的。

一句话：阻塞不可避免时，别阻塞主 worker 线程，把它甩给别的线程或进程。

3. 跨 worker 共享状态，认准 lua_shared_dict

OpenResty 的 worker 是相互隔离的操作系统进程，默认不共享内存。想做计数器、限流、全局开关这类跨 worker 的共享状态，用 lua_shared_dict——它的 incr、add、set 都是原子操作。

而如果只是单 worker 内的缓存或配置，用 Lua 模块级变量（配合 lua-resty-lrucache）更快，因为它能存任意 Lua 类型，不受 shared dict 只能存字符串/数字/布尔的限制。别搞混这两者的作用域。

4. 连接池：别每个请求都新建连接

cosocket 连接用完别直接关，调 set_keepalive 放回连接池，下个请求复用。否则高并发下频繁建连会把后端和自己都拖垮。这是性能差距最大的细节之一。

5. 善用 init_by_lua 预加载，别在请求里 require

模块加载、配置解析这类一次性的活儿，放到 init_by_lua_block 里在启动时做一遍，别每个请求都 require 一次。请求路径上的每一行代码都在和延迟赛跑。

常见错误与陷阱清单

把高频翻车点整理成一张自查表，发布前对一遍：

最需要刻进肌肉记忆的，还是第一条：写 OpenResty 代码时，对任何可能阻塞 I/O 的函数调用都要多想三秒。一行阻塞代码，足以让整个服务性能掉一个数量级。

学习资料与可跑的实例

OpenResty 早年被人诟病"资料少、全靠摸着石头过河"。现在好多了，下面这几份足够你从入门到实战：

官方资料（权威，优先）

• 《Programming OpenResty》（章亦春著，官网免费 HTML 版）——作者亲笔，讲设计哲学最到位。
• agentzh's Nginx Tutorials（中英文都有，GitHub 仓库）——把 Nginx 本身讲透，是理解 OpenResty 的地基。
• 官方博客 blog.openresty.com——内存管理、LuaJIT GC64、真实故障排查案例，干货很硬。
• restydoc 命令行：装完 OpenResty 后，restydoc -s ngx.flush、restydoc resty.redis 直接在终端查 API，不用开浏览器。

系统课程与开源书

• 极客时间《OpenResty 从入门到实战》（温铭，APISIX 项目 VP、OpenResty 软件基金会首任主席）——52 讲，从入门、API、测试、性能优化到实战搭网关，体系最完整的中文课程。
• 《OpenResty 最佳实践》（开源书，moonbingbing/openresty-best-practices）——社区攒的踩坑合集，免费，适合当手册查。

动手练习

光看不练记不牢。Lua 是 OpenResty 的半壁江山，它的坑和 OpenResty 的坑会叠加。我自己攒了一个 Lua 练习仓库 walter-fan/lua-playground，把常见语法、陷阱、小例子都整理成了能直接跑的脚本。建议先把 Lua 的基本功打牢，再上 OpenResty——不然你会分不清一个 bug 到底是 Lua 的坑还是 OpenResty 的坑。

一条务实的学习路径：先用 resty -e 在终端把 Lua 玩熟 → 照官方教程搭一个 Hello World 的 nginx.conf → 加鉴权、限流、连 Redis，一步步把它变成一个迷你 API 网关 → 遇到性能问题，学着用火焰图定位，而不是靠猜。

总结：它的全部优劣，都来自"逻辑跑在请求路径上"

OpenResty 的价值，一句话就能概括：它让你用脚本语言，在 Nginx 那条本就高效的请求流水线上直接写业务逻辑。 逻辑和流量零距离，省掉一跳网络、省掉一套独立服务、省掉 reload 的抖动——这是它所有优势的根。

但同一个设计也埋下了所有的坑。单线程事件循环意味着一行阻塞代码就能拖垮整个 worker；高性能的前提是你全程非阻塞。记住那三句架构（Nginx 管网络、Lua 挂阶段、cosocket 不阻塞），再守住那五条规矩，你就拿到了它的大部分红利。

如果你正在做网关、WAF、边缘计算，或者任何"逻辑必须在请求路径上"的活儿，OpenResty 值得认真评估。 先用 resty -e 在终端跑个 Hello World，花十分钟，比看十篇文章都管用。

把成熟的东西焊在一起，有时比发明新东西更难，也更值钱——前提是你得懂两边的脾气。

全文思维导图

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor #F8F9FA
    RoundCorner 10
    Padding 10
    FontSize 13
  }
  :depth(0) {
    BackgroundColor #1E3A5F
    FontColor white
    FontSize 18
    FontStyle bold
  }
  :depth(1) {
    FontSize 15
    FontStyle bold
  }
  :depth(2) {
    FontSize 13
  }
}
</style>

* OpenResty
** 是什么
*** 内嵌 LuaJIT 的 Nginx
*** 不是 fork，是超集
*** nginx.conf 原样能跑
** 能做什么
*** 可编程 API 网关
*** WAF / 限流鉴权
*** 动态路由 / CDN 边缘
*** 高并发直连后端
** 架构三句话
*** Nginx 管网络与事件循环
*** Lua 挂在请求阶段上
*** cosocket 访问后端不阻塞
** 优势
*** 逻辑在请求路径上
*** 改路由不用 reload
*** 单机高并发
*** 脚本写业务
** 劣势
*** Lua 生态小
*** 调试门槛高
*** 一行阻塞拖垮全局
*** 开源版没控制台
** 成功案例
*** Kong / APISIX
*** Cloudflare / Shopify
*** TikTok / 淘宝
** 生态圈
*** 核心子项目 ngx_lua / lua-resty-core
*** 社区 lua-resty-* 库
*** 商业 *-fast 私有库
** opm 包管理
*** search / get / list
*** --cwd 项目内安装
*** 优先 opm 而非 LuaRocks
** 最佳实践
*** 永不阻塞
*** FFI 绕外部命令
*** shared dict 共享状态
*** 连接池 keepalive
** 学习资料
*** Programming OpenResty
*** 极客时间专栏
*** OpenResty 最佳实践
*** lua-playground 练习
@endmindmap

本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。 欢迎在我的个人网站 https://www.fanyamin.com 访问原文并评论。