将网关从 NGINX 迁移到 OpenResty 时,最核心的目标是确保现有流量平稳过渡。

虽然 OpenResty 完全兼容标准 NGINX 的配置语法,但直接替换线上实例依然存在风险——两者的编译模块、默认路径和运行环境往往存在差异。工程上更稳妥的做法是:先对齐基础配置,让新旧实例并行运行并对比请求结果,验证无误后再执行切流。

如果在迁移前还想进一步了解两者的定位差异,可以先阅读 OpenResty vs NGINX:当网关开始承载业务逻辑。

迁移的核心原则:先对齐,再改造

OpenResty 本质上就是基于 NGINX 核心构建的,因此绝大多数 NGINX 原生指令都可以直接沿用。但“语法兼容”不等于“配置文件直接复制过去就能正常运行”——两者的编译参数、模块列表、默认安装路径往往不同,直接替换很容易引发兼容性问题。

最稳妥的迁移策略,是将“替换底层网关”与“叠加新功能”分步推进:

先原封不动地迁移现有配置,让原有的 NGINX 和新的 OpenResty 并行运行,用相同的请求对比测试,确保两者的代理行为完全一致;等平稳跑通后,再逐步引入新的 Lua 业务逻辑(比如用 Lua 实现新的接口鉴权)。这样一旦出现异常,很容易界定到底是基础环境配置有误,还是新增的 Lua 代码存在问题。

具体落地时,可以按以下四个步骤推进(如果当前还没有安装环境,可以先参考安装 OpenResty):

1. 梳理现有 NGINX 的构建与配置

在开始迁移前,建议先对线上现有环境做一次全面盘点与备份:

  1. 查看版本与编译参数:找到线上实际运行的 NGINX 二进制文件,执行 nginx -V,把版本号和编译参数(configure arguments)完整记录下来。
  2. 导出全量配置:执行 nginx -T(如果线上服务启动时带了 -p、-c 或 -g 等命令行参数,这里也要原样带上)。-T 不仅会检查配置语法,还会把主配置文件和所有通过 include 引入的子配置文件全部打印出来,非常适合用来梳理配置依赖。
  3. 备份与记录:完整备份原有的配置文件及目录结构,同时记录启动服务的系统用户和启动命令。

2. 核对模块、指令与文件路径

整理好现有环境的配置清单后,重点排查以下三类最容易出现兼容问题的地方:

  • 内置模块与核心版本差异:对比 nginx -V 和 openresty -V 的输出。如果测试配置时报 unknown directive,除了检查原 NGINX 是否额外开启了某个非默认模块(如 http_sub_module),还要留意两者的 NGINX 核心版本差异——例如现有环境如果运行的是版本较新的 NGINX Mainline(主线版)并使用了最新特性指令,迁移前需确认目标 OpenResty 所基于的 NGINX 核心版本是否已包含该特性。
  • 第三方 C 模块(高频报错点):检查配置里所有的 load_module(比如用于压缩的 ngx_brotli、用于可观测性的 OpenTelemetry 模块,或是团队早期用 C 自研的内部私有模块)。注意:原 NGINX 编译生成的 .so 文件不能直接用于 OpenResty。 即便两边都开启了 NGINX 的 --with-compat 动态模块兼容选项,启动时依然会严格校验 NGINX 版本号和构建签名:版本号不一致会报错 module "…" version … instead of …,构建签名不兼容则报错 module "…" is not binary compatible,两种情况都会拒绝启动。因此,动态 C 模块必须针对目标 OpenResty 版本重新编译;如果是早期静态编译进原 NGINX 的业务模块,也可以借此机会评估能否直接用 OpenResty 的 Lua 生态重构替代。
  • 文件路径与权限:检查配置中的 include、TLS 证书、日志、PID 和临时目录。绝对路径一般没问题,但相对路径要格外小心——它是相对于启动时的 -p(prefix 工作目录)解析的。切换到 OpenResty 后,默认工作目录发生变化,使用相对路径很容易导致找不到文件。此外,还需确认新实例的运行用户(如 nobody 或 nginx)对这些目录有读写权限。

3. 双实例并行:用同一条请求做对比验证

配置文件能通过 -t 语法检查,只代表“能启动”,不代表“转发行为一致”。最稳妥的办法是在测试环境中,用 -p 参数指定不同的工作目录,让原 NGINX 和新 OpenResty 监听不同端口并行运行,发送相同的请求比对响应结果。

下面我们用一个最小化的本地实验,演示如何在一台机器上并行对比两个实例(假设环境里已安装 nginx、openresty 和 python3)。实验中,NGINX 监听 18080,OpenResty 监听 18082,两者都将 /api/ 转发给同一个监听 18081 的上游服务。

先创建临时目录,并用 Python 启动一个模拟上游:

check_dir=$(mktemp -d)
mkdir -p "$check_dir/conf" "$check_dir/logs" "$check_dir/upstream/api"
printf 'upstream ok\n' > "$check_dir/upstream/api/ping"
python3 -m http.server 18081 --bind 127.0.0.1 --directory "$check_dir/upstream" &
upstream_pid=$!

执行 curl -fsS http://127.0.0.1:18081/api/ping,确认能正常返回 upstream ok。

接着,把待验证的配置文件保存为 $check_dir/conf/nginx.conf(这里顺带加上常见的转发头配置,方便一并验证):

pid logs/nginx.pid;
error_log logs/error.log;

events {}

http {
    access_log logs/access.log;

    server {
        listen 127.0.0.1:18082;
        server_name gateway.test;

        location /api/ {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://127.0.0.1:18081;
        }
    }
}

然后,为原 NGINX 复制一份相同的配置(仅把监听端口改为 18080),并用 -p 指定各自独立的工作目录,检查配置无误后把两个实例都启动起来:

baseline_dir=$(mktemp -d)
mkdir -p "$baseline_dir/conf" "$baseline_dir/logs"
sed 's/127\.0\.0\.1:18082/127.0.0.1:18080/' "$check_dir/conf/nginx.conf" \
    > "$baseline_dir/conf/nginx.conf"

nginx -p "$baseline_dir/" -c conf/nginx.conf -t &&
    nginx -p "$baseline_dir/" -c conf/nginx.conf
openresty -p "$check_dir/" -c conf/nginx.conf -t &&
    openresty -p "$check_dir/" -c conf/nginx.conf

现在,向两个端口发送完全相同的请求,对比代理结果(在 Bash/Zsh 下也可以直接用 diff -u <(curl ...) <(curl ...) 快速比对输出差异):

curl -isS -H 'Host: gateway.test' http://127.0.0.1:18080/api/ping
curl -isS -H 'Host: gateway.test' http://127.0.0.1:18082/api/ping

正常情况下,两边都会返回 200 和 upstream ok;如果请求一个不存在的路径(如 /api/missing),两边都会返回 404。对比时,Server 和 Date 等响应头存在差异是正常的,我们需要重点比对的是客户端强依赖的状态码、响应体和业务响应头。

在实际迁移业务站点时,你可以用同样的思路,复制真实的线上配置,挑选核心路由的代表性请求(包含正常请求和预期的异常请求)进行回放对比,同时检查两边的错误日志、上游收到的请求头与访问日志,以及 TLS 握手情况是否一致。

本地实验结束后,停止这两个临时实例和测试上游即可:

openresty -p "$check_dir/" -c conf/nginx.conf -s quit
nginx -p "$baseline_dir/" -c conf/nginx.conf -s quit
kill "$upstream_pid"

4. 灰度切流,并做好回滚预案

测试环境验证通过后,就可以准备生产环境切流了。

如果网关前面有负载均衡器,切流会非常从容:保持原有的 NGINX 实例继续运行,先挂载 OpenResty 节点承接小比例的灰度流量。切流前,团队需要先明确灰度观察时长,以及放量和触发回滚的指标红线(主要是错误率和延迟)。在灰度期间,密切关注新旧实例的监控指标和上游服务状态,达标后再逐步放大流量;一旦触发红线,立即将流量切回原 NGINX,并重发关键请求确认服务恢复。

在实际操作中,还有两个容易忽略的回滚细节:

  1. 安全策略对齐:如果在迁移到 OpenResty 的同时,同步上线了新的安全或鉴权逻辑(比如拦截某类非法请求),那么在准备回滚方案时,必须确认原 NGINX 上也具备兜底的拦截策略,避免一旦回滚导致安全防线失效。
  2. 端口冲突处理:如果前面没有负载均衡器,新旧服务只能在同一台机器上轮流绑定同一个 80/443 端口,那就无法做平滑灰度了。这种情况下,务必提前准备好“停止 OpenResty -> 启动原 NGINX -> 发送测试请求验证”的一键回滚脚本,确保出现意外时能在几秒钟内恢复现场。

总结与下一步

从 NGINX 迁移到 OpenResty,关键不在于一次性替换,而在于把风险拆开:先原样迁移现有配置,确认代理行为一致,再逐步叠加 Lua 业务逻辑。

落地时可以按四步走:用 nginx -V 和 nginx -T 摸清现有构建与配置;核对模块、核心版本、动态模块和文件路径;在测试环境让新旧实例并行运行,用相同的请求对比状态码、响应体和业务响应头;最后灰度切流,提前定好回滚红线和回滚步骤。这样即使上线后出现异常,也能快速判断问题出在基础配置还是新加的 Lua 代码上,并及时切回原 NGINX。

本文是 OpenResty 教程系列的一部分。迁移完成后,接下来可以了解 OpenResty 包含哪些组件,看看在原有的代理配置之上,可以用哪些模块和 Lua 库来扩展网关。

关注我们

欢迎访问 OpenResty 官方博客,也欢迎扫码关注我们的微信公众号。

OpenResty 博客微信公众号