OpenResty配置教程 nginx.conf、location与Lua脚本的使用方法

OpenResty安装完成后，需要通过nginx.conf配置监听端口、站点域名和请求处理规则。不同路径可以交给Lua脚本处理，也可以转发到后端应用。掌握server与location的配置方式，是继续实现接口鉴权、动态路由等功能的基础。

以下示例使用安装目录/usr/local/openresty。如果实际路径不同，请相应调整。已有网站正在运行时，不要用最小示例覆盖整个配置文件，应保留原有站点、证书和其他业务配置。

一、修改前先备份配置

备份当前的nginx.conf，在文件名中加入时间，避免反复备份时覆盖旧文件。

sudo cp -p \
  /usr/local/openresty/nginx/conf/nginx.conf \
  /usr/local/openresty/nginx/conf/nginx.conf.bak.$(date +%Y%m%d-%H%M%S)

随后使用文本编辑器打开配置文件。

sudo vi /usr/local/openresty/nginx/conf/nginx.conf

操作前记下备份文件名。后续如果需要恢复，应恢复对应备份，再检查配置并重载。

二、编写最小可用配置

在独立测试环境中，可以先使用以下配置，验证OpenResty能否通过Lua返回内容。

worker_processes 1;

events {
    worker_connections 1024;
}

http {
    server {
        listen 80;
        server_name localhost;

        location / {
            default_type text/plain;

            content_by_lua_block {
                ngx.say("hello openresty")
            }
        }
    }
}

content_by_lua_block中的Lua代码负责生成响应，ngx.say()将内容写入响应正文。完成第六节的检查与重载后，访问首页应返回hello openresty。

这里的location /是前缀匹配，也会处理没有被其他规则接管的路径。它适合入门验证，正式网站需要另外安排正常页面和不存在路径的处理规则。

三、理解server配置

server用于定义一个虚拟服务器，放在http配置块内。同一份配置可以包含多个server，分别处理不同域名或监听端口上的请求。

示例中的两条指令分别负责监听和名称匹配。

listen 80;
server_name localhost;

listen指定监听地址或端口。
server_name指定用于匹配请求的服务器名称。

server_name localhost不等于只允许本机访问。 如果只是做本地测试，可以将监听配置改为绑定回环地址。

listen 127.0.0.1:80;

正式部署时，再结合实际域名、网络访问要求及HTTPS配置调整站点。

四、配置location与反向代理

location负责选择请求路径对应的处理规则。以下配置片段都放在第二节已有的server中，不需要另外建立一个完整的http块。

1. 添加健康检查路径

为/health添加精确匹配规则。

location = /health {
    default_type text/plain;
    return 200 "ok\n";
}

重载后，请求该路径应返回200和ok。这只是当前OpenResty处理入口的简单检查，没有检测数据库或后端应用。

2. 将API请求转发到后端

假设后端应用已经监听127.0.0.1:8080，可以添加以下规则。

location ^~ /api/ {
    proxy_pass http://127.0.0.1:8080;

    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

这个示例中的proxy_pass没有附带URI部分，因此请求/api/users时，后端接收到的路径仍是/api/users。

如果改为末尾带斜杠的形式，则含义不同。

proxy_pass http://127.0.0.1:8080/;

在上述前缀匹配配置中，请求/api/users会被转发为后端的/users。是否保留/api/，应与后端接口路由保持一致。

3. 正确认识匹配顺序

不能简单理解为“越具体的location写在越前面，优先级就越高”。

对于本例这种没有嵌套的配置，可以按以下顺序理解。

优先检查=精确匹配，命中后直接采用。
在前缀规则中找出匹配路径最长的一项。
如果这一项带有^~，则采用它，不再检查正则规则。
否则按书写顺序检查正则规则，采用第一个匹配项；没有正则命中时，使用此前找到的最长前缀规则。

普通前缀规则主要比较匹配长度，正则规则之间才需要特别注意书写顺序。

例如，/admin/可以单独配置访问控制，但仅仅写出这个路径不会自动完成鉴权，还需要相应的检查逻辑。

五、选择合适的Lua执行位置

OpenResty允许在不同请求阶段运行Lua代码，常用指令包括以下几种。

access_by_lua_block在访问控制阶段执行，适合鉴权及访问限制。
content_by_lua_block在内容处理阶段执行，用于生成响应。
log_by_lua_block在日志阶段执行，用于记录请求处理结果。
content_by_lua_file在内容处理阶段加载独立Lua文件。

代码较多时，可以将Lua逻辑单独保存，减少nginx.conf中的业务代码。

先创建目录。

sudo mkdir -p /usr/local/openresty/nginx/lua

创建示例脚本。

sudo tee /usr/local/openresty/nginx/lua/hello.lua > /dev/null <<'EOF'
ngx.say("hello from lua file")
EOF

确保OpenResty的工作进程能够读取该文件，再在server中添加一个独立路径。

location = /hello {
    default_type text/plain;
    content_by_lua_file /usr/local/openresty/nginx/lua/hello.lua;
}

默认开启Lua代码缓存时，修改脚本后也需要重载，才能让新工作进程使用更新后的代码。生产环境不建议为了省去重载而关闭代码缓存。

需要代理后端时，可以使用access_by_lua_block先检查请求，再交给proxy_pass。不要在同一个location中同时用content_by_lua_block和proxy_pass争用内容处理阶段。

六、检查配置并平滑重载

先使用OpenResty自带的Nginx检查配置，避免误调用服务器上另一个Nginx程序。

sudo /usr/local/openresty/nginx/sbin/nginx -t

如果实际使用的是其他配置文件，应通过-c指定；原服务使用了自定义-p或-c参数时，检查和重载也应保持一致。

检查通过后再重载，可以使用&&确保前一条命令成功后才继续。

sudo /usr/local/openresty/nginx/sbin/nginx -t &&
sudo /usr/local/openresty/nginx/sbin/nginx -s reload

重载会让主进程检查并尝试应用新配置，启动新的工作进程，同时让旧工作进程逐步结束已有请求。这里假设OpenResty已经启动，reload不用于首次启动服务。

按实际添加的配置验证访问结果。

curl -i http://127.0.0.1/
curl -i http://127.0.0.1/health
curl -i http://127.0.0.1/hello

预期分别获得首页测试文本、健康检查响应和独立Lua脚本的输出。验证反向代理时，应使用后端真实存在的接口路径。