將閘道器從 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 部落格微信公眾號