GeekIt

OpenResty命令速查

命令行工具、核心配置、请求响应 API、共享字典、代理均衡、定时器与故障排查等 134 条命令

共 134 条命令 · 10 类场景 · 点击右侧图标可复制

命令 / 配置 / API说明复制
openresty -V查看版本与编译参数,确认是否带 lua-nginx-module、http_v2、ssl
resty -V查看 resty 命令行工具版本与内嵌 LuaJIT 版本
luajit -v查看 LuaJIT 版本,OpenResty 默认使用 LuaJIT
openresty -t校验配置文件语法,改完 nginx.conf 必须先执行
openresty -T校验并打印最终生效配置(含 include 展开结果)
openresty -s reload平滑重载配置,不中断现有连接
openresty -s stop 与 openresty -s quitstop 立即停止,quit 等待请求处理完再退出
openresty -s reopen重新打开日志文件,配合 logrotate 使用
resty -e "print(ngx.config.ngx_lua_version)"不启动服务直接运行 Lua 代码,验证环境
resty -I /usr/local/openresty/lualib app.lua指定模块搜索路径运行脚本
resty --http-conf "lua_ssl_trusted_certificate /etc/ssl/certs/ca.pem;" -e "print(1)"命令行注入 nginx 配置指令,测试需要额外配置的逻辑
opm search redis搜索官方 opm 仓库中的 lua-resty 模块
opm get openresty/lua-resty-redis通过 opm 安装模块到 lualib
luarocks install lua-resty-http用 luarocks 安装,兼容更多第三方库
opm list列出已通过 opm 安装的模块
命令 / 配置 / API说明复制
systemctl status openresty查看服务状态与最近日志
systemctl reload openresty生产环境重载配置的标准做法
worker_processes auto;worker 数等于 CPU 核数,IO 密集型可适当放大
events { worker_connections 10240; }单 worker 最大连接数,需同步调整 ulimit
lua_package_path "/data/lualib/?.lua;;";自定义 Lua 模块路径,末尾 ;; 表示追加默认路径
lua_shared_dict cache 100m;声明共享内存字典,跨 worker 共享,需在 http 块内
init_by_lua_block { require "resty.core" }master 进程启动时执行,用于预加载模块
init_worker_by_lua_block { ... }每个 worker 启动时执行,适合注册定时任务
content_by_lua_block { ngx.say("hello") }用 Lua 生成响应内容,替代静态文件或反向代理
access_by_lua_block { ... }访问阶段执行,常用于鉴权、限流、黑白名单
rewrite_by_lua_block { ... }重写阶段执行,可修改 URI 与参数
log_by_lua_block { ... }请求结束后执行,适合异步打点与统计
lua_code_cache off;仅开发环境使用,关闭后每次请求重新加载 Lua,性能极差
resolver 8.8.8.8 114.114.114.114 valid=30s;配置 DNS 解析器,动态域名与 cosocket 域名请求必需
lua_ssl_trusted_certificate /etc/ssl/certs/ca-bundle.crt;HTTPS 上游校验需指定可信 CA
env APP_ENV;把系统环境变量透传给 Lua(ngx.var 或 os.getenv)
命令 / 配置 / API说明复制
local uri = ngx.var.uri获取规范化后的请求路径(不含参数)
local raw = ngx.var.request_uri获取原始请求行路径,含查询串
local args = ngx.req.get_uri_args()解析 URL 查询参数为 table
ngx.req.read_body() 与 local post = ngx.req.get_post_args()读取请求体后再解析表单参数,顺序不能颠倒
local body = ngx.req.get_body_data()获取原始请求体,大文件场景可能为 nil(已落临时文件)
local file = ngx.req.get_body_file()请求体被写入临时文件时返回路径
local headers = ngx.req.get_headers()获取全部请求头(键名小写化处理需注意)
ngx.req.set_header("X-Real-IP", ngx.var.remote_addr)向上游透传真实客户端 IP
ngx.req.clear_header("Cookie")清除敏感请求头
ngx.req.set_uri("/v2/api")重写请求 URI(第二个参数为 true 时会重新匹配 location)
local method = ngx.req.get_method()获取请求方法字符串
ngx.req.set_method(ngx.HTTP_POST)修改请求方法,内部转发时常用
ngx.ctx.user_id = 1001请求级上下文,在同一请求的各阶段间共享数据
local ip = ngx.var.remote_addr获取客户端 IP,经代理时需读 X-Forwarded-For
local ua = ngx.var.http_user_agent获取任意请求头,命名规则为 http_ 加头名
命令 / 配置 / API说明复制
ngx.say("hello")输出内容并追加换行,最常用的响应方式
ngx.print("hello")输出内容不追加换行
ngx.write("chunk")流式输出,配合 flush 实现 SSE 与大文件下载
ngx.status = 201设置响应状态码,需在输出前设置
ngx.header["Content-Type"] = "application/json; charset=utf-8"设置响应头
ngx.header.content_length = nil清空长度头以启用 chunked 传输,流式输出必需
ngx.redirect("https://example.com/login", 302)发起重定向,301 永久 302 临时
return ngx.exit(ngx.HTTP_FORBIDDEN)立即结束请求并返回指定状态码
ngx.exit(ngx.HTTP_OK)结束当前阶段处理并返回 200
ngx.send_headers() 与 ngx.flush(true)先发头再刷新缓冲区,降低首字节延迟
ngx.eof()显式结束响应流,禁止后续输出
return ngx.HTTP_NOT_FOUND在 access/rewrite 阶段直接返回状态码的简写
命令 / 配置 / API说明复制
local dict = ngx.shared.cache获取已声明的共享字典实例
dict:set("k", "v", 60)写入并设置 60 秒过期
local v, flags = dict:get("k")读取值,不存在返回 nil
dict:add("k", 1, 60)仅当键不存在时写入,可用于原子抢占
dict:incr("counter", 1, 0)原子自增,第三个参数为初始值(限流计数核心)
dict:delete("k")删除键
dict:get_keys(100)遍历键(数量大时慎用,会阻塞 worker)
dict:flush_all() 与 dict:flush_expired()清空全部键 / 仅清理过期键释放内存
local cap = dict:capacity(); local free = dict:free_space()查看字典容量与剩余空间,判断是否写满
local redis = require "resty.redis"加载 lua-resty-redis,连接池由 cosocket 自动管理
local cjson = require "cjson.safe"安全版 JSON,解析失败返回 nil 而不抛异常
package.loaded["app.config"] = nil清除模块缓存强制重新加载(配合 lua_code_cache off 调试)
resty -e 'local d = require "resty.core"; print(d.version)'命令行验证模块是否可加载
命令 / 配置 / API说明复制
proxy_pass http://backend;转发到 upstream 集群
upstream backend { server 10.0.0.5:8080 weight=2; server 10.0.0.6:8080; }定义上游集群与权重
keepalive 64; 与 proxy_http_version 1.1;开启长连接,需同时清空 Connection 头才能复用
proxy_set_header Connection "";清空 Connection 头以启用 keepalive 复用
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;透传客户端真实 IP 链
proxy_connect_timeout 3s 与 proxy_read_timeout 30s连接与读取超时,避免上游慢拖垮 worker
proxy_next_upstream error timeout http_502;上游失败时自动切换下一个节点
balancer_by_lua_block { ngx.balancer.set_current_peer("10.0.0.7", 8080) }Lua 动态选择上游节点,实现灰度与自定义负载
local state, err = ngx.balancer.get_last_failure()获取上一次转发失败原因,用于熔断判断
local res = ngx.location.capture("/internal/auth")发起子请求,常用于鉴权与聚合接口
local res1, res2 = ngx.location.capture_multi({ {"/a"}, {"/b"} })并发子请求,聚合多个内部接口
proxy_cache_path /data/cache levels=1:2 keys_zone=my_cache:100m inactive=10m;定义磁盘缓存区
proxy_cache my_cache; proxy_cache_valid 200 5m;开启缓存并设置成功响应的缓存时长
命令 / 配置 / API说明复制
local ok, err = ngx.timer.at(5, handler)延迟 5 秒执行一次(0 表示立即)
local ok, err = ngx.timer.every(60, handler)每 60 秒周期执行,定时任务首选
ngx.timer.running_count() 与 ngx.timer.pending_count()查看运行中与等待中的定时器数量
local th = ngx.thread.spawn(fn, arg)创建轻量协程并发执行
local ok, res = ngx.thread.wait(th)等待协程结束并取回结果
ngx.thread.kill(th)终止协程(谨慎使用,可能留下未释放资源)
ngx.sleep(0.1)非阻塞休眠,不占用 worker
ngx.worker.pid() 与 ngx.worker.id() 与 ngx.worker.count()获取 worker 进程信息,定时任务需按 id 分流
ngx.now() 与 ngx.time() 与 ngx.update_time()获取时间,now 带毫秒;update_time 刷新缓存的时间
local sem = require "ngx.semaphore".new(1)信号量控制并发度
sem:wait(0.1) 与 sem:post(1)获取与释放信号量,超时返回 nil
init_worker_by_lua_block { if ngx.worker.id() == 0 then ngx.timer.every(60, sync) end }只让 0 号 worker 跑定时任务,避免重复执行
ngx.sleep 不能在 init_by_lua 阶段调用cosocket 与 sleep 仅在支持的阶段可用,否则报 API disabled
命令 / 配置 / API说明复制
ngx.log(ngx.ERR, "upstream failed: ", err)写错误日志,级别常量 ERR/WARN/NOTICE/INFO/DEBUG
ngx.log(ngx.INFO, require("cjson").encode(tbl))打印 table 需先序列化,直接拼接 table 会报错
error_log logs/error.log info;设置日志级别与路径,排查问题可临时调至 info
log_format main "$remote_addr $request_time $upstream_response_time $status $request";访问日志加入耗时字段,便于定位慢请求
tail -f /usr/local/openresty/nginx/logs/error.log实时观察错误日志,改配置后必看
openresty -t 2>&1 | tail -n 20配置报错时定位具体行号
resty -e 'local t = {a=1}; print(require("inspect")(t))'命令行调试时用 inspect 打印 table 结构
lua_code_cache off;开发时免 reload 生效,上线必须删除该配置
strace -f -p $(cat logs/nginx.pid) -e trace=network跟踪系统调用,排查连接与阻塞问题
ss -lntp | grep nginx确认监听端口与进程,排查端口未起来
curl -sv -o /dev/null -w "%{http_code} %{time_total}\n" http://127.0.0.1/带耗时统计验证接口响应
ngx.log(ngx.ERR, debug.traceback("checkpoint"))打印调用栈,定位 Lua 异常来源
命令 / 配置 / API说明复制
wrk -t4 -c200 -d30s --latency http://10.0.0.5/多线程压测并输出延迟分布,评估吞吐与长尾
ab -n 10000 -c 200 http://10.0.0.5/简单压测,适合快速验证 QPS
curl -o /dev/null -s -w "%{time_connect} %{time_starttransfer} %{time_total}\n" http://10.0.0.5/分阶段耗时,判断慢在连接、首字节还是传输
echo $request_time 与 $upstream_response_time日志中对比总耗时与上游耗时,区分网关与后端问题
worker_connections 10240;调大单 worker 连接数,同时提高 ulimit -n
ulimit -n 65535提高文件句柄上限,否则并发上不去且报 too many open files
lua_shared_dict cache 256m;共享字典按数据量评估,过小会频繁淘汰
openresty -V 2>&1 | grep -E "with-http_v2|with-http_ssl|luajit"确认 HTTP/2、SSL 与 LuaJIT 支持情况
top -H -p $(cat logs/nginx.pid)按线程查看 CPU 占用,定位热点 worker
ngx.shared.cache:free_space()监控共享字典剩余空间,避免静默写失败
ngx.update_time() 与 ngx.now() 高频调用大量取时间时先 update_time 减少系统调用开销
proxy_buffering on; 与 proxy_buffers 8 16k;开启响应缓冲,平滑上游抖动但会增加内存占用
命令 / 配置 / API说明复制
unknown directive "lua_package_path"当前 nginx 未编译 lua-nginx-module,需使用 openresty 而非原生 nginx
no resolver defined to resolve "api.example.com"proxy_pass 使用域名时必须配置 resolver
API disabled in the context of init_by_lua*init 阶段不支持 cosocket/sleep,需移到 init_worker 或 timer
shared dict "cache" not foundlua_shared_dict 未声明或名字不一致,声明需放在 http 块
lua entry thread aborted: runtime errorLua 运行时异常,看 error.log 中具体行号与变量
upstream timed out (110: Connection timed out)上游响应超时,调大 proxy_read_timeout 或排查后端慢查询
connect() failed (111: Connection refused)上游端口未监听或已挂,检查服务与安全组
502 Bad Gateway网关拿到无效响应:看 error.log 的 upstream 段,多为后端异常退出
SSL_do_handshake() failed证书链或协议版本不匹配,用 openssl s_client 验证
worker process exited on signal 11段错误,多为 C 模块问题;升级模块并抓 core 分析
too many open files句柄耗尽,调整 ulimit 与 worker_connections
content_by_lua_block 与 proxy_pass 同时配置同一 location 内容阶段只能有一个处理器,二选一
openresty -s reload 后配置未生效确认改的是实际加载的配置文件,用 openresty -T 核对

运维常用组合

配置变更标准流程openresty -t && openresty -T | less && openresty -s reload && tail -f logs/error.log
接口耗时定位log_format 加 $request_time/$upstream_response_time → 按耗时排序找慢接口
共享字典限流local n = dict:incr(key, 1, 0); if n > limit then return ngx.exit(429) end
动态上游选择balancer_by_lua_block 中 ngx.balancer.set_current_peer(host, port)
并发聚合内部接口ngx.location.capture_multi({ {"/a"}, {"/b"} })
单 worker 定时任务init_worker_by_lua_block { if ngx.worker.id() == 0 then ngx.timer.every(60, job) end }

常见问题排查

1. 改完配置必做三步

openresty -t 校验 → openresty -T 核对最终配置 → openresty -s reload 平滑重载

2. Lua 代码改了不生效

生产环境 lua_code_cache 为 on,代码变更需 reload;off 仅用于开发,会严重拖慢性能

3. 定时任务重复执行

init_worker_by_lua 每个 worker 都会跑,用 ngx.worker.id() == 0 限定单实例或改用共享字典加锁

4. 共享字典写不进去

容量写满会静默失败,检查 free_space 与返回值;高频计数优先用 incr 而非 get+set

5. DNS 域名转发失败

proxy_pass 或 cosocket 访问域名都依赖 resolver,缓存过期时间用 valid= 控制

6. 接口偶发 502

多为上游超时或连接被重置:对比 $upstream_response_time 与 $request_time,再看后端日志

共 134 条 OpenResty 命令 · 命令默认安装路径 /usr/local/openresty,请按实际环境调整

关于OpenResty命令速查

在线 OpenResty 命令速查手册,按安装版本与命令行、服务管理与核心配置、请求读取与变量、响应输出与重定向、共享内存与模块加载、反向代理与负载均衡、定时器协程与并发、日志与调试、性能与压测、常见故障排查等 10 类场景整理 120+ 条常用命令、配置指令与 ngx_lua API,每条附中文说明与典型写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 openresty -V 编译参数、-t 校验与 -T 打印生效配置、-s reload/stop/quit/reopen、resty -e 直接执行 Lua、-I 指定模块路径、--http-conf 注入配置、opm search/get 与 luarocks install、worker_processes 与 worker_connections、lua_package_path、lua_shared_dict、init_by_lua_block 与 init_worker_by_lua_block、content_by_lua_block 与 access_by_lua_block 与 rewrite_by_lua_block 与 log_by_lua_block、lua_code_cache、resolver 与 lua_ssl_trusted_certificate、ngx.var 系列变量、ngx.req.get_uri_args 与 get_post_args 与 read_body 与 get_headers 与 set_header 与 set_uri、ngx.ctx、ngx.say 与 print 与 write 与 redirect 与 exit 与 flush、ngx.shared.DICT 的 get/set/add/incr/expire/get_keys/flush_all/free_space、require 模块与 package.loaded、proxy_pass 与 upstream keepalive 与 proxy_next_upstream 与 balancer_by_lua_block 与 ngx.balancer.set_current_peer、ngx.location.capture 与 capture_multi、ngx.timer.at 与 timer.every、ngx.thread.spawn 与 semaphore、ngx.worker.id 与 ngx.sleep、ngx.log 与 error_log 与 log_format 耗时字段、wrk 与 ab 压测、curl -w 分段耗时、ulimit 与 too many open files、unknown directive 与 no resolver defined 与 shared dict not found 与 502 与 upstream timed out 等排查。适用于 OpenResty 网关开发与运维、Lua 限流鉴权、动态负载均衡、共享字典缓存、定时任务与慢接口定位,以及运维面试复习。

核心能力

  • 涵盖 openresty -V 编译参数、-t 校验与 -T 打印生效配置、-s reload/stop/quit/reopen、resty -e 直接执行 Lua、-I 指定模块路径、--http-conf 注入配置、opm search/get 与 luarocks install、worker_processes 与 worker_connections、lua_package_path、lua_shared_dict、init_by_lua_block 与 init_worker_by_lua_block、content_by_lua_block 与 access_by_lua_block 与 rewrite_by_lua_block 与 log_by_lua_block、lua_code_cache、resolver 与 lua_ssl_trusted_certificate、ngx.var 系列变量、ngx.req.get_uri_args 与 get_post_args 与 read_body 与 get_headers 与 set_header 与 set_uri、ngx.ctx、ngx.say 与 print 与 write 与 redirect 与 exit 与 flush、ngx.shared.DICT 的 get/set/add/incr/expire/get_keys/flush_all/free_space、require 模块与 package.loaded、proxy_pass 与 upstream keepalive 与 proxy_next_upstream 与 balancer_by_lua_block 与 ngx.balancer.set_current_peer、ngx.location.capture 与 capture_multi、ngx.timer.at 与 timer.every、ngx.thread.spawn 与 semaphore、ngx.worker.id 与 ngx.sleep、ngx.log 与 error_log 与 log_format 耗时字段、wrk 与 ab 压测、curl -w 分段耗时、ulimit 与 too many open files、unknown directive 与 no resolver defined 与 shared dict not found 与 502 与 upstream timed out 等排查

适用场景

适用于 OpenResty 网关开发与运维、Lua 限流鉴权、动态负载均衡、共享字典缓存、定时任务与慢接口定位,以及运维面试复习。OpenResty命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

OpenResty命令速查是免费的吗?需要注册或安装吗?
OpenResty命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
OpenResty命令速查支持哪些功能?
涵盖 openresty -V 编译参数、-t 校验与 -T 打印生效配置、-s reload/stop/quit/reopen、resty -e 直接执行 Lua、-I 指定模块路径、--http-conf 注入配置、opm search/get 与 luarocks install、worker_processes 与 worker_connections、lua_package_path、lua_shared_dict、init_by_lua_block 与 init_worker_by_lua_block、content_by_lua_block 与 access_by_lua_block 与 rewrite_by_lua_block 与 log_by_lua_block、lua_code_cache、resolver 与 lua_ssl_trusted_certificate、ngx.var 系列变量、ngx.req.get_uri_args 与 get_post_args 与 read_body 与 get_headers 与 set_header 与 set_uri、ngx.ctx、ngx.say 与 print 与 write 与 redirect 与 exit 与 flush、ngx.shared.DICT 的 get/set/add/incr/expire/get_keys/flush_all/free_space、require 模块与 package.loaded、proxy_pass 与 upstream keepalive 与 proxy_next_upstream 与 balancer_by_lua_block 与 ngx.balancer.set_current_peer、ngx.location.capture 与 capture_multi、ngx.timer.at 与 timer.every、ngx.thread.spawn 与 semaphore、ngx.worker.id 与 ngx.sleep、ngx.log 与 error_log 与 log_format 耗时字段、wrk 与 ab 压测、curl -w 分段耗时、ulimit 与 too many open files、unknown directive 与 no resolver defined 与 shared dict not found 与 502 与 upstream timed out 等排查。
OpenResty命令速查适合哪些场景使用?
适用于 OpenResty 网关开发与运维、Lua 限流鉴权、动态负载均衡、共享字典缓存、定时任务与慢接口定位,以及运维面试复习。