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 quit | stop 立即停止,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 found | lua_shared_dict 未声明或名字不一致,声明需放在 http 块 | |
lua entry thread aborted: runtime error | Lua 运行时异常,看 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.loglog_format 加 $request_time/$upstream_response_time → 按耗时排序找慢接口local n = dict:incr(key, 1, 0); if n > limit then return ngx.exit(429) endbalancer_by_lua_block 中 ngx.balancer.set_current_peer(host, port)ngx.location.capture_multi({ {"/a"}, {"/b"} })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,再看后端日志
相关工具
Linux命令速查
文件、文本、权限、进程、网络、磁盘、systemd与防火墙等 Linux 常用命令速查手册
Docker命令速查
镜像、容器、网络、数据卷、Compose、Swarm、清理与排障等 Docker 常用命令速查手册
Nginx命令速查
服务管理、配置指令、反向代理、HTTPS、限流缓存、日志排查等 Nginx 常用命令速查手册
K8S命令速查
集群上下文、Pod调试、工作负载、Service与Ingress、存储、权限、排障等 kubectl 常用命令速查手册
Windows CMD命令速查
文件目录、网络诊断、进程服务、系统信息、用户权限、注册表、批处理等 Windows CMD 常用命令速查手册
systemctl服务管理速查
服务启停、开机自启、unit文件编写、日志查看、定时器、依赖分析与排障等 systemctl 命令速查手册
关于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 限流鉴权、动态负载均衡、共享字典缓存、定时任务与慢接口定位,以及运维面试复习。