企业官网建设流程全解析

接上一个话题，咱们继续聊Nginx。前面的文章把Nginx的负载均衡、反向代理、缓存这些基础能力都过了一遍，但说实话，这些能力本身都不新鲜，Nginx火了几十年，靠的可不光是这些。真正让Nginx在高性能Web容器这个位置上坐得稳、坐得久的，是它的扩展生态——而在所有扩展里，OpenResty绝对是最绕不开的那个。今天这篇就专门讲讲OpenResty，讲清楚它到底是什么、为什么会出现、能解决哪些Nginx原生搞不定的场景，以及怎么在项目里真正把它用起来。

先说个结论：OpenResty本质上是"Nginx + 一堆精选模块 + LuaJIT"的整合发行版，它最大的价值是让Nginx从"配置驱动的静态转发层"变成了"可以写业务逻辑的动态网关层"。你可以在Nginx里直接写Lua代码，操作请求、访问Redis、调用上游接口、动态路由、灰度分流、限流熔断……以前这些要么靠各种第三方模块拼凑，要么只能放到后端服务里去处理，现在全都可以在Nginx这一层直接搞定。适合谁看？正在做网关设计的人、被Nginx配置灵活性逼疯的人、以及对OpenResty感兴趣但不知道从哪下手的同学，这篇应该都能给你一些实质性帮助。

1. 为什么Nginx需要扩展：从静态转发到动态决策

1.1 Nginx自身的边界在哪里

很多人在刚开始接触Nginx的时候，会有一个直观感受：这东西的配置文件看起来像个声明式的规则引擎。location、upstream、proxy_pass，都是"告诉Nginx某个路径对应什么上游"，它照做就行。这种设计的好处是简单、稳定、性能极高，坏处则是——灵活性不够。

举个例子，你有一个接口，希望根据请求参数中的用户ID做灰度，让一部分用户走新版本服务，另一部分走老版本。用原生的Nginx配置怎么写？常规做法是if加upstream切换，或者干脆拆域名、拆路径。但拆域名、拆路径这件事在业务复杂的场景下非常痛苦：路径一旦变多，location规则就爆炸；域名一多，证书管理、跨域配置全是麻烦。更麻烦的是，有些逻辑是动态的，比如"根据Redis里存的开关决定接口是否降级"，这种需求在原生Nginx里基本是无解的，因为Nginx的配置文件是启动时加载的，改配置必须reload。

再一个痛点是Nginx没有标准的分布式协同能力。它本身是个Web服务器，不是一个业务中间件，它不关心你的服务注册中心里有哪些实例，也不关心你的限流阈值是动态变化的。它只会按配置文件里写死的upstream列表做轮询或者哈希。服务实例扩缩容之后，要么手动改配置，要么靠一些额外的工具去同步配置。放到微服务架构里，这显然不够用。

还有一个隐蔽但非常关键的局限：Nginx的配置语言没有函数、没有变量作用域、没有标准库，连字符串拼接都别扭。你很难在配置里表达"如果A且B，则执行C"这种稍微复杂一点的逻辑。用if写复杂判断，Nginx官方自己都警告过if在location里是"邪恶的"。这不是说Nginx做错了什么，而是它的定位决定了它不可能把所有业务逻辑都塞进配置里。但反过来，业务方又确实需要请求入口处做越来越多的灵活控制。这个矛盾，就是OpenResty出现的根本原因。

1.2 OpenResty究竟解决了什么问题

OpenResty的思路很直接：把Lua语言嵌入到Nginx的进程里，让开发者可以用Lua写请求处理逻辑。Lua是一个轻量级脚本语言，运行效率高（通过LuaJIT甚至可以编译成机器码），语法简单，和C语言结合非常容易。嵌入Nginx之后，开发者可以在Nginx的各个处理阶段（rewrite、access、content、log等）挂自己的Lua代码，这些代码直接运行在Nginx的工作进程内，和Nginx共享进程生命周期。

听起来很简单，但这个设计实际上解决了一大堆问题，我来逐个拆解：

第一，动态逻辑有了落脚点。原来Nginx配置写死的那些规则，现在都可以通过Lua代码实时判断。想要按用户ID灰度，不用再拆域名拆路径了，直接写一段Lua读请求头、读参数、计算哈希，然后手动选一个上游地址去proxy。想要动态调整限流阈值，也不需要改配置文件，Lua代码可以每秒去Redis里拉一次最新配置。

第二，网络IO不再需要后端中转。这是OpenResty性能强的一个关键原因。Nginx的工作进程可以同时管理成千上万个连接，每个连接都处于事件驱动模型里，非常适合做高并发IO。OpenResty通过cosocket能力，让Lua代码可以在Nginx进程内直接发起Redis查询、MySQL查询、HTTP调用，整个过程是非阻塞的，不需要像传统后端服务那样，每个请求占用一个线程或者一个协程去等IO返回。这意味着，网关层可以在不增加后端压力的前提下，完成聚合、鉴权、限流、缓存等操作——因为原本这些操作可能要打给Java/Go服务的接口，让后端去查Redis、查数据库，再返回给Nginx。

第三，模块化扩展变得容易了。Nginx的C模块开发门槛很高，要懂Nginx内部的数据结构、内存管理、事件循环，普通业务开发者根本碰不了这个。但Lua代码写起来简单太多了。OpenResty把所有常用能力封装成了一个个指令和API，比如ngx.say、ngx.req.read_body、ngx.location.capture，业务逻辑只需要用这些API拼装即可。可以说，OpenResty把Nginx从"C程序员的玩具"变成了"普通开发者的工具"。

明白了这层背景，再去看OpenResty的架构和用法，思路就会清晰得多。它不是一个独立的新服务器，而是让Nginx这个"高性能执行引擎"拥有了"可编程的大脑"。

2. OpenResty的核心机制：Lua脚本与事件驱动的碰撞

2.1 Lua代码跑在Nginx的哪个阶段

要正确使用OpenResty，首先得搞清楚Nginx处理一个请求时经历了哪些阶段，以及Lua代码可以挂在哪些阶段。Nginx本身处理HTTP请求时会按顺序执行一系列phase（阶段），从接收请求头、解析URL、做rewrite，到查找location并执行内容处理，最后记录日志。OpenResty在每个阶段都开放了对应的*_by_lua指令，这组指令非常关键：

• init_by_lua：Nginx启动时执行，一般用来加载公共模块、初始化全局变量。
• rewrite_by_lua：在rewrite阶段执行，适合做URI重写、鉴权、跳转判断。
• access_by_lua：在访问控制阶段执行，适合做限流、权限校验、IP黑白名单。
• content_by_lua：在内容生成阶段执行，可以直接生成返回内容，也可以配合proxy_pass做动态转发。
• header_filter_by_lua：在响应头发送前执行，可以动态修改返回的header。
• body_filter_by_lua：在响应体发送时执行，可以截获或修改响应体内容。
• log_by_lua：在日志阶段执行，适合记录耗时、统计指标。

初学者最容易犯的错，就是把所有逻辑都塞进content_by_lua里，觉得反正都是Lua，在哪写都一样。实际上各个阶段的执行时机和用途差别非常大。比如说，鉴权逻辑如果写在content_by_lua里，那么请求已经进入content阶段，意味着前面的rewrite阶段、access阶段都已经执行完了，很多东西已经定下来了，此时再做拦截会多浪费资源，而且容易和其他location配置产生冲突。正确的做法是：鉴权和限流放到access_by_lua，URL改写放到rewrite_by_lua，而动态生成响应内容才用content_by_lua。

这里我再说一个很多人忽略的点：同一个请求会经过多个阶段，你的Lua代码写到不同阶段，它们之间是通过ngx.ctx这个表来共享数据的。ngx.ctx是请求级别的上下文，在同一个请求内的任意阶段都可以读写。比如说在access_by_lua里把当前用户的ID和角色信息塞进去，到log_by_lua阶段再取出来打日志，中间不需要跨函数传参。这个设计用起来非常顺手，但也伴随一个坑：如果你用了协程（ngx.thread），子协程里操作ngx.ctx要特别小心，因为ngx.ctx的语义在不同协程间并不完全一致，踩过的人都知道，这里先记下一条经验，后面详细说。

2.2 cosocket：为什么OpenResty能撑起高并发

OpenResty性能好，除了Nginx本身的事件驱动模型之外，另一个核心是cosocket。cosocket是OpenResty实现的一套基于协程的非阻塞网络套接字API，它可以让你在Lua代码里写出"看起来是同步的"代码，但底层IO完全非阻塞。

这个设计非常了不起。传统同步网络请求的写法是：

local redis = require "resty.redis" local red = redis:new() red:connect("127.0.0.1", 6379) local res = red:get("some_key")

你看这个代码，connect是没有等返回就不执行下一行吗？看起来像是阻塞的，实际上不是。OpenResty在遇到IO等待时，会把这个Lua协程挂起，释放出当前工作进程去处理其他请求，等IO事件到达后再恢复这个协程继续往下跑。所以整个函数写成同步的样式，但Nginx进程本身并没有被卡住——它的并发能力依然取决于事件循环，而不是你写了多少个连接调用。

这对业务代码的编写方式影响巨大。你不需要像Netty里那样写回调链，也不需要像有些框架那样写响应式代码，就写最简单的顺序逻辑就行。这一点对团队协作非常友好，因为大部分后端开发对同步代码的直觉是根深蒂固的，学习成本瞬间低了很多。

不过，cosocket虽然好用，但有几个限制需要注意。第一，不能在init_by_lua阶段使用cosocket，因为那时候Nginx的worker进程可能还没完全准备好事件循环。第二，cosocket链接需要自己管理连接池，否则每次请求都新建TCP连接，性能会大打折扣。OpenResty里每个cosocket对象都可以通过set_keepalive方法把连接归还给连接池，下次用到相同目标的连接时可以直接复用。实际写代码时，一定记得设置keepalive，经验值来讲，连接池大小设在几十到几百之间比较合理，太小了不同的并发请求会频繁创建销毁连接，太大了又会占着文件描述符不放，具体要根据你的上游连接数和QPS来调节。

2.3 同步非阻塞的IO体验：一次真实的数据聚合场景

光说概念可能还是有点虚，我拿一个具体的场景来说明cosocket带来的编码体验差异。

假设你要在网关层做一个用户中心聚合接口：请求进来之后，需要先查一次Redis拿用户的基础标签，然后根据标签调用两个不同的下游HTTP服务（一个取订单统计，一个取优惠券信息），最后把结果拼成一份JSON返回给前端。放在Java里，你大概率会用CompletableFuture或者协程来做并行IO；放在Node里，你可能要写Promise.all；但用OpenResty的cosocket，代码几乎是线性的：

location /user_center_summary { content_by_lua_block { local redis = require "resty.redis" local http = require "resty.http" -- 第一步：读取Redis local red = redis:new() red:set_timeout(200) local ok, err = red:connect("127.0.0.1", 6379) if not ok then ngx.status = 502 ngx.say("redis connect failed: ", err) return end local tag, err = red:get("user:" .. ngx.var.arg_uid .. ":tag") red:set_keepalive(10000, 50) -- 第二步：根据tag拼装下游请求 local httpc = http:new() local res1, err1 = httpc:request_uri("http://order-service:8080/api/order?uid=" .. ngx.var.arg_uid) local res2, err2 = httpc:request_uri("http://coupon-service:8080/api/coupon?uid=" .. ngx.var.arg_uid) -- 第三步：拼装JSON返回 local result = { tag = tag, order = res1.body, coupon = res2.body } ngx.header.content_type = "application/json" ngx.say(cjson.encode(result)) } }

看得明白吧？整个代码没有显式开协程并发，但两个HTTP请求request_uri在底层其实是交替执行的——第一个请求发出后等IO时，协程挂起，事件循环去处理第二个请求，等数据都返回后继续往下跑。这个IO模型保证了网关层不会因为依赖了外部服务而把并发能力锁死，整体吞吐量远高于"一请求一线程"的阻塞模型。

但注意，这里只是展示编码体验。真实项目中我不建议在nginx层做这么重的业务聚合，毕竟网关层职责越重，故障面越大。如果确实要做，也要把每个下游调用的超时时间、失败兜底逻辑写周全，避免某一个下游慢拖垮整个网关。这类问题排查起来会非常痛苦，后面在常见问题部分专门讲。

3. 高频应用场景与核心实操：从灰度到限流到缓存风暴

3.1 场景一：基于Redis的灰度发布与流量染色

灰度发布是网关层最典型的扩展需求。早期没有OpenResty时，技术团队做灰度通常需要整个发布平台配合，改Nginx配置、切流量、观察日志，再来回调整。有了OpenResty之后，灰度的逻辑可以极其灵活地落在Nginx这一层。

我见过一种很常见的做法：把所有灰度判断收敛到Redis的一个key里，例如gray:user:123456存的是new_version。请求进来时，access_by_lua阶段读取当前用户ID，查一下Redis，如果命中灰度标记就把流量转发到新版本服务的upstream，否则走老版本。这个方案的优点在于运维侧不需要动任何Nginx配置，只需要往Redis写key就能实时调整灰度名单。

Lua代码大概长这样：

access_by_lua_block { local redis = require "resty.redis" local red = redis:new() red:set_timeout(100) local ok, err = red:connect("127.0.0.1", 6379) if not ok then -- 如果Redis挂了，宁可流量全部走老版本，也不要引入不确定因素 ngx.ctx.backend = "old" return end local uid = ngx.var.cookie_user_id or ngx.var.arg_uid or "" local gray, err = red:get("gray:user:" .. uid) red:set_keepalive(10000, 50) if gray == "new" then ngx.ctx.backend = "new" else ngx.ctx.backend = "old" end }

然后在content_by_lua阶段或者直接在location里根据ngx.ctx.backend选择对应的upstream转发即可。这里要注意：灰度名单放Redis而不是放共享内存，是因为共享内存是每台网关机器一份，如果你的网关有多台机器，直接改某一台的内存变量无法同步到其他机器。非要只用共享内存，就得先在多个机器间做同步，复杂度反而上去了。Redis虽然多了一次网络调用，但换来的是配置全局一致、修改实时生效。当然了，如果可以承受Redis访问的延迟或者用本地缓存做二次加速，那另说。

还有一点值得提：灰度流量最好在进入业务逻辑前"染色"，也就是在请求头里注入一个自定义头部，比如X-Env: gray，这样下游服务可以在日志里记录到灰度标记，方便排查问题。在OpenResty里加请求头很简单：

ngx.req.set_header("X-Env", "gray")

注意set_header要在rewrite_by_lua或access_by_lua阶段调用，如果在content阶段再设置，上游收到时可能已经太晚了，因为代理转发的请求头可能在更早就被Nginx内部处理过。

3.2 场景二：动态限流——不用改conf，实时再调

Nginx原生的limit_req模块可以做令牌桶限流，但它的问题大家应该都知道：配置是写死的，限流速率要改就得改配置reload。在业务突增或者大促场景下，运维的核心诉求是"不改配置文件、不中断现有连接，就能调整限流阈值"。OpenResty实现动态限流的方案就可以做到实时生效。

基本思路是：把限流的阈值放到Redis或共享字典中，每次请求过来时从共享字典读取最新阈值，再配合自己的滑动窗口算法或令牌桶实现限流。这里我推荐优先用lua_shared_dict，因为它是本机内存级别的操作，没有网络IO，性能损耗极小。动态更新时，只需要用一个后台任务定期从Redis同步阈值到共享字典，或者由管理接口直接写共享字典，所有worker进程都能读到。

一个简易的固定窗口限流示例：

lua_shared_dict my_limit 10m; access_by_lua_block { local limit = require "resty.limit.count" local red_limit = ngx.shared.my_limit -- 从共享字典中动态获取阈值，默认5qps local rate = red_limit:get("rate") or 5 local timeout = 60 local lim, err = limit.new("my_limit", rate, timeout) if not lim then return end local key = ngx.var.binary_remote_addr local delay, err = lim:incoming(key, true) if not delay then -- 限流触发，返回503 ngx.exit(503) end }

用resty.limit.count是固定窗口算法，它在每个时间窗口内允许固定的请求次数，适合简单的限流场景。如果面对的是突发流量不断变化的场景，可以考虑resty.limit.sliding_window或者resty.limit.req（漏桶）。实际项目里，我通常会用两层：一层是硬性兜底限流（写在配置里，保证Nginx不会被打挂），一层是动态限流（从Redis或管理接口实时调整，针对具体业务接口）。这么做的好处是，动态限流即使调整出错，也有底限挡着。

这里再提醒一个容易掉坑的点：resty.limit.count这种限流器是进程内维护的，Nginx每个worker进程各有一份独立的计数器。如果你的服务器有4核，开了4个worker，每个worker的限流阈值都是rate，那么整体实际限流就是rate * worker数。这是很多人配置了限流却总感觉"限不住"的原因之一。想要全局限流，要么把限流计数放到Redis里做原子操作，要么在init_by_lua里统一获取worker数量并按总QPS折算每台机器的阈值。最稳妥的还是将每台机器的限额设置为"全局限额 / 机器数"，多台机器之间依靠负载均衡天然摊分流量。

3.3 场景三：接口聚合与缓存风暴治理

业务上经常会遇到这种需求：前端要展示一个页面，需要同时调3个后端接口，而每个接口都要到数据库查数据。如果让前端自己并发调3个接口，后端会重复打DB，压力大、耗时长。但如果在网关层把3个下游调用聚合起来，并且对聚合结果做短时间缓存，效果会好很多——一方面前端只需要一次请求，另一方面下游DB的压力也能显著降低。

这个需求用OpenResty做起来很顺手。利用ngx.location.capture可以发起子请求，而这些子请求可以打到Nginx内部的其它location上，也可以作为反向代理打到外部的服务。一个典型的聚合location：

location = /api/aggregate { content_by_lua_block { local res1 = ngx.location.capture("/api/order", { args = ngx.var.args }) local res2 = ngx.location.capture("/api/user", { args = ngx.var.args }) local res3 = ngx.location.capture("/api/coupon", { args = ngx.var.args }) local result = { order = cjson.decode(res1.body), user = cjson.decode(res2.body), coupon = cjson.decode(res3.body) } ngx.header.content_type = "application/json" ngx.say(cjson.encode(result)) } } location = /api/order { proxy_pass http://order_service_backend; }

默认情况下ngx.location.capture是并发执行的，也就是说三个子请求会同时发出，不用等一个返回再发下一个。这一点非常关键，可以把聚合接口的响应时间控制到最慢的那个下游接口的耗时，而不是三者之和。

但缓存这块就要多做考虑了。Nginx自带的proxy_cache是按URL做缓存，和Lua逻辑结合的时候有点僵硬。在OpenResty里我们更适合用lua_shared_dict做应用级缓存，或者用resty.lrucache做进程内的LRU缓存。

我举一个实际场景：接口下游是数据库查询，QPS一高DB就扛不住。方案是这样——在access_by_lua阶段先查共享字典里的缓存，命中则直接返回；未命中才会走到后端，同时把结果异步写回缓存。这里有一个细节：一定要加"锁"，否则在缓存失效的瞬间，并发请求会同时穿透到后端，这在高并发场景就是缓存雪崩。加锁的方式有很多种，最简单的可以用ngx.shared.dict:add方法，用dict的原子操作setnx来模拟一个锁：

-- 尝试加锁，key为 cache:order:1001，value设为时间戳 local lock_key = "lock:" .. cache_key local ok, err = cache_dict:add(lock_key, 1, 5) if ok then -- 获取到锁，执行真实查询并回填缓存 local res = fetch_from_backend() cache_dict:set(cache_key, res, 30) cache_dict:delete(lock_key) -- 释放锁 return res else -- 没拿到锁，说明有其他请求正在刷新缓存，可以短暂等待或直接返回null -- 实际项目中可以sleep 100ms后重试 ngx.sleep(0.1) return cache_dict:get(cache_key) end

这个"缓存锁"的实现虽然简单，但在网关层非常实用。不过ngx.sleep在access阶段是可以用的，如果是在init_by_lua这种不允许sleep的地方就不行了，所以锁逻辑尽量放在请求处理阶段执行。 需要注意的是：如果缓存字典里存的是复杂对象（table），共享字典要求value必须能被序列化，所以通常存的是JSON字符串。大对象序列化反序列化本身也有成本，如果缓存的数据很大、读多写少，用Lua的resty.lrucache（进程内对象缓存）反而更合适，因为不需要序列化，直接在内存里复用table。

3.4 场景四：动态服务发现与上游选取

微服务架构中服务实例是动态变化的，网关层需要实时感知服务列表的变化。传统Nginx的upstream配置是静态的，扩容了或缩容了都需要手动改配置。OpenResty可以完全绕过静态upstream，用Lua代码自己在运行时决定将请求转发到哪里。

一个灵活的做法是：从注册中心（或直接从一个配置中心）拉取最新的上游列表，然后写到共享字典里；每次转发时从共享字典取一个可用的IP，通过ngx.location.capture或ngx.req.set_uri+ 动态host的方式发起反向代理。示例：

set_by_lua_block $backend { local ip_list = ngx.shared.service_dict:get("service:order:v1") if not ip_list then -- 没有可用服务，返回一个默认错误值，Nginx会走下面的fallback return "unavailable" end local ips = cjson.decode(ip_list) -- 简单轮询：用ngx.var.request_id作为随机种子到这里取一个 local index = ngx.var.request_id:len() % #ips + 1 return ips[index] } location /api/order { if ($backend = "unavailable") { return 503; } proxy_pass http://$backend:8080; }

这个方案在实践中非常可行，但要注意几个问题：一是$backend是在set阶段由Lua设置的变量，它只能用于字符串变量，不能做太重的操作，所以拉取IP列表的逻辑不建议直接写在set_by_lua_block里，最好由后台定时任务（如ngx.timer.every）周期性拉取并写入共享字典，请求处理阶段只做读取和选择。二是如果后端服务有多个端口，IP列表里要同时包含端口信息，或者后面的端口写法要动态可配。三是健康检查，动态服务发现最容易踩的坑就是转发的目标服务可能已经宕机，但列表里还留着它的IP，导致请求频繁超时。所以在拉取列表时，可以顺带用resty.healthcheck这类库做主动健康检查，把不健康的实例从共享字典里剔除。

4. 常见问题与排查技巧实录

4.1 共享字典内存耗尽与"worker crashed"

用lua_shared_dict的人，早晚会遇到一个问题：shared dict大小设置不合理，热点key太多，内存被打满，然后看到Nginx报出类似no memory的错误，严重时worker进程直接crash。这往往不是代码逻辑错误，而是对共享字典的容量管理缺失。

排查思路是这样的：先用ngx.shared:get_keys(0)看当前字典里有多少key，再统计value的平均大小，算出总体占用。如果确实接近上限，就做过期清理策略。共享字典的set方法可以设置过期时间，但要注意它的过期是一种惰性回收机制——只有当key被访问到过期时间，或者字典空间不够需要淘汰时，才会真正释放内存。如果你的key很多而且持续写入，即使设置了过期时间，也可能看到内存占用一直很高，实际上是还没来得及回收。

我建议在项目里对共享字典做一下容量监控，比如每隔一段时间统计字典的ffi_size和当前key数量，如果超过80%就告警。另外，不要把大的JSON字符串整个塞进共享字典，最好先压缩（zlib）或精简后再存。某些情况下，把字典大小从10m调到50m确实是必要的，但更应该先看看是不是有key只写不删。

4.2 cosocket连接池耗尽与超时抖动

用cosocket比较密集的场景下，可能遇到这样的现象：接口整体耗时偶尔飙到几百毫秒甚至几秒，但CPU和内存占用都不高。这种时候十有八九是cosocket连接池出问题了。

连接池的复用建立在set_keepalive的参数上。假设你设置了red:set_keepalive(10000, 50)，意思是连接空闲10秒就释放，连接池最大50条空闲连接。但如果你的QPS很高，瞬时有500个并发同时要Redis连接，连接池只有50个空闲连接，剩下的就得新建TCP连接。新建连接要做TCP三次握手，堆栈上就会多出不少耗时。更糟的是，如果连接池大小设置的过小，大量连接频繁建立销毁，请求耗时波动就会很明显。

解决办法是合理评估pool_size。怎么评估？看网关的worker进程数和每个worker的QPS比例。一般建议每个worker的连接池大小设为QPS * 下游平均响应时间，比如一个worker的QPS是1000，下游平均响应5ms，那么连接池大小在50左右就够了，再翻个倍数留余量到100是比较健康的值。但是要注意，连接池越大，空闲连接占用的文件描述符也越多，所以不是越大越好。如果机器文件描述符本身就很紧张，需要先提高worker_rlimit_nofile。

还有一个容易被忽略的点：set_timeout超时时间设得太短，会在下游节点稍微抖动时触发大量连接超时，而这些超时连接会进一步消耗连接池资源。我的习惯是：Redis超时设100-200ms，HTTP下游超时设200-500ms，且必须设置合理的connect_timeout、send_timeout、read_timeout三个值，不能只设一个总超时。只有read_timeout设大了但connect_timeout没有调整，下游网络不通时还是会快速失败，并不优雅。

4.3 全局变量滥用导致的数据错乱

Lua的全局变量给很多初学者埋过雷。默认情况下，Lua里定义的全局变量会放在全局表_G里，这些变量在整个worker进程生命周期里是共享的。如果在请求处理里把你认为的"临时数据"直接写成全局变量，那么多个并发请求之间就可能互相污染。

举个典型例子：某个同学在content_by_lua_block里写了一句user_info = get_user_info(uid)，想在后面的代码里直接用user_info。表面上在测试环境单个请求跑得好好的，一压并发就出现各种奇怪的user信息串号。原因就在于这个user_info被所有并发请求共享了。正确的做法是：把请求级数据放到ngx.ctx或局部变量中，只有需要跨阶段共享且确实是进程级的配置数据（比如从Redis拉下来的更新列表）才放到全局表里。

我之前被这种问题折磨过，后来定了一条团队纪律：禁止在请求阶段直接往全局表写数据；进程级配置全部走共享字典；请求级数据全部通过ngx.ctx传递；函数传参一律显式声明。执行这条纪律之后，关于"数据串了"的Bug几乎绝迹。

另外，init_by_lua里加载的模块是worker进程间共享的吗？这个要弄清楚。每个worker进程都有自己独立的Lua VM，所以init_by_lua是在每个worker启动时各自执行一次，模块缓存也是每worker一份。全局变量在整个worker级别共享，但跨worker不共享。需要跨worker共享数据，一定使用lua_shared_dict而不是全局变量。

4.4 定时器泄漏与后台任务失控

OpenResty里用ngx.timer.at或者ngx.timer.every做后台定时任务是常规操作，但定时器用不好，也会给Nginx带来很大压力。最常见的坑是：定时器回调里做了耗时的同步操作，导致定时器堆积，下一轮定时器还没跑完，新一轮又来了，进程CPU持续升高。

ngx.timer.every的语义是每隔固定时间创建一个新的定时器。如果回调执行时间大于定时周期，就会产生重叠执行。怎么避免？我通常在回调的最开头加个防重入检查：

local running = ngx.shared.dict:safe_add("timer:sync_order_list", 1, 5) if not running then return -- 上一轮还没结束，跳过这一轮 end -- 执行任务 -- 任务结束后不要把锁设死，可以用set替换value为0，或直接删除 ngx.shared.dict:delete("timer:sync_order_list")

用add方法的语义是"key不存在才能写入成功"，这样同一时刻只有一个定时器回调能进入任务主体。这个方法虽然简单，但能有效防止定时器叠加导致的CPU尖刺。

另外要注意定时器回调中尽量不要再使用ngx.location.capture去请求外部接口，因为定时器回调是在一个独立的轻量线程里运行的，与普通请求的上下文不同，很多在请求阶段可用的API在定时器上下文里会有限制。如果确实需要周期性地刷新配置，建议定时器只负责把数据从Redis拉下来写入共享字典，而不要在回调里做复杂的业务逻辑。

4.5 常见问题速查表

5. 一点实战经验与收尾

前面聊了这么多，最后再补一些我在实际项目中积累的体会吧。

第一，OpenResty适合做"薄的、灵活的网关逻辑"，但不要把它当成后端服务来用。你可以在网关层做鉴权、限流、灰度、路由、简单的聚合和缓存，但如果你发现自己开始用Lua写很复杂的业务状态机，或者动辄几百行的数据计算，那大概率是职责放错了地方。网关层最重要的是稳定和性能，业务复杂度越高，后面排查问题就越难。我见过某个团队把折扣计算逻辑写在OpenResty里，结果每次需求变更都要重新lua代码并reload Nginx，风险可想而知。

第二，Lua代码的测试和上线流程一定要规范化。很多团队把OpenResty当成"写一段代码贴进去就行"的东西，没有单测、没有回归、没有灰度，上线全靠直改生产配置。一旦出问题，回滚都麻烦。我的做法是：所有Lua模块尽量拆成纯函数，不要直接在请求阶段里调全局API，这样可以用resty命令行或OpenResty官方提供的测试框架在本地跑单元测试。线上切换的时候，先在一台机器上加载新配置观察日志，确认无误再全量。

第三，记得加观测。只要是网关层，每个请求的耗时、上游响应码、被限流的次数、灰度的命中率，都应该有对应的日志或指标输出。OpenResty的log_by_lua阶段非常适合干这个，你可以在这个阶段把请求的各个阶段耗时记录成结构化日志，发到日志平台。平时可能感觉不到，但真正到线上出故障的时候，这套观测体系就是救命稻草。

作为一个把Nginx从"能用"用到"顺手"的过来人，我真心觉得OpenResty是Nginx生态里被低估的东西之一。它并没有改变Nginx的底层架构，也没有用什么黑魔法，无非是想清楚了"让配置层少管动态逻辑、让脚本层补齐业务决策"这件事。你要是正在做网关设计、微服务接入层、或者想把Nginx的灵活性再往上提一个档次，OpenResty值得花两周时间认真啃一啃。真上手之后你会发现，很多以前要改代码改配置的痛点，现在一行Lua就搞定了。