如何從 NGINX 遷移到 OpenResty:配置檢查、並行驗證與回滾
將閘道器從 NGINX 遷移到 OpenResty 時,最核心的目標是確保現有流量平穩過渡。
雖然 OpenResty 完全相容標準 NGINX 的配置語法,但直接替換線上例項依然存在風險——兩者的編譯模組、預設路徑和執行環境往往存在差異。工程上更穩妥的做法是:先對齊基礎配置,讓新舊例項並行執行並對比請求結果,驗證無誤後再執行切流。
如果在遷移前還想進一步瞭解兩者的定位差異,可以先閱讀 OpenResty vs NGINX:當閘道器開始承載業務邏輯。
遷移的核心原則:先對齊,再改造
OpenResty 本質上就是基於 NGINX 核心構建的,因此絕大多數 NGINX 原生指令都可以直接沿用。但“語法相容”不等於“配置檔案直接複製過去就能正常執行”——兩者的編譯引數、模組列表、預設安裝路徑往往不同,直接替換很容易引發相容性問題。
最穩妥的遷移策略,是將“替換底層閘道器”與“疊加新功能”分步推進:
先原封不動地遷移現有配置,讓原有的 NGINX 和新的 OpenResty 並行執行,用相同的請求對比測試,確保兩者的代理行為完全一致;等平穩跑通後,再逐步引入新的 Lua 業務邏輯(比如用 Lua 實現新的介面鑑權)。這樣一旦出現異常,很容易界定到底是基礎環境配置有誤,還是新增的 Lua 程式碼存在問題。
具體落地時,可以按以下四個步驟推進(如果當前還沒有安裝環境,可以先參考安裝 OpenResty):
1. 梳理現有 NGINX 的構建與配置
在開始遷移前,建議先對線上現有環境做一次全面盤點與備份:
- 檢視版本與編譯引數:找到線上實際執行的 NGINX 二進位制檔案,執行
nginx -V,把版本號和編譯引數(configure arguments)完整記錄下來。 - 匯出全量配置:執行
nginx -T(如果線上服務啟動時帶了-p、-c或-g等命令列引數,這裡也要原樣帶上)。-T不僅會檢查配置語法,還會把主配置檔案和所有透過include引入的子配置檔案全部列印出來,非常適合用來梳理配置依賴。 - 備份與記錄:完整備份原有的配置檔案及目錄結構,同時記錄啟動服務的系統使用者和啟動命令。
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,並重發關鍵請求確認服務恢復。
在實際操作中,還有兩個容易忽略的回滾細節:
- 安全策略對齊:如果在遷移到 OpenResty 的同時,同步上線了新的安全或鑑權邏輯(比如攔截某類非法請求),那麼在準備回滾方案時,必須確認原 NGINX 上也具備兜底的攔截策略,避免一旦回滾導致安全防線失效。
- 埠衝突處理:如果前面沒有負載均衡器,新舊服務只能在同一臺機器上輪流繫結同一個 80/443 埠,那就無法做平滑灰度了。這種情況下,務必提前準備好“停止 OpenResty -> 啟動原 NGINX -> 傳送測試請求驗證”的一鍵回滾指令碼,確保出現意外時能在幾秒鐘內恢復現場。
總結與下一步
從 NGINX 遷移到 OpenResty,關鍵不在於一次性替換,而在於把風險拆開:先原樣遷移現有配置,確認代理行為一致,再逐步疊加 Lua 業務邏輯。
落地時可以按四步走:用 nginx -V 和 nginx -T 摸清現有構建與配置;核對模組、核心版本、動態模組和檔案路徑;在測試環境讓新舊例項並行執行,用相同的請求對比狀態碼、響應體和業務響應頭;最後灰度切流,提前定好回滾紅線和回滾步驟。這樣即使上線後出現異常,也能快速判斷問題出在基礎配置還是新加的 Lua 程式碼上,並及時切回原 NGINX。
本文是 OpenResty 教程系列的一部分。遷移完成後,接下來可以瞭解 OpenResty 包含哪些元件,看看在原有的代理配置之上,可以用哪些模組和 Lua 庫來擴充套件閘道器。
關注我們
歡迎訪問 OpenResty 官方部落格,也歡迎掃碼關注我們的微信公眾號。















