NGINX 設定查看與 reload 改走 HTTP API
NGINX Blog · 2026-09-21
NGINX 這次直接把「查設定、觸發 reload」搬進 HTTP 世界：新增的 Control API 讓維運可以用一支 HTTP 請求讀出記憶體中正在生效的設定，也能用另一支請求觸發 reload，不必再對著 master process 送 Unix signal。這項功能隨 NGINX 1.31.5 與 NGINX Plus 37，於 2026 年 9 月 21 日由 Ava Hahn 發布上線。
背景
長期以來 NGINX 的設定管理只能靠 signal-based reload：改完設定檔後對 master process 送 SIGHUP，NGINX 才會重新讀取設定並嘗試優雅換掉 worker process。問題是這條路徑完全沒有回饋管道，reload 送出去之後成功或失敗都要回頭翻 log 才能確認。官方部落格點名的痛點是「使用者常常掉進一個陷阱，搞不清楚 NGINX 目前實際跑的是哪一份設定」，尤其是重載後才冒出的 socket 權限錯誤，過去只能從 log 裡撈。這種不透明在容器化與 Kubernetes 環境下更麻煩，自動化腳本沒辦法判斷 reload 是否真的成功。
核心改動
Control API 這次新增兩支端點，共用同一個 /1/control/config 路徑，只靠 HTTP method 分工，並在啟動時用 -l 參數開啟：
GET /1/control/config：取出目前記憶體內正在生效的完整設定PATCH /1/control/config：觸發 reload，並用 HTTP 狀態碼回報成功或失敗
最大差異在於 reload 的回饋方式：以前送 SIGHUP 只能盲等、只能盯 log；現在 PATCH 請求連 reload 之後才浮現的 socket 權限錯誤都能直接回報，不用再回頭爬 log。下面是兩種做法的對照：
# before：signal-based reload，沒有回饋
kill -HUP $(cat /var/run/nginx.pid)
tail -f /var/log/nginx/error.log # 只能盯 log 猜成功與否
# after：HTTP-based reload，直接拿到結果
curl --unix-socket /tmp/unix 0.0.0.0/1/control/config | jq
curl --unix-socket /tmp/unix 0.0.0.0/1/control/config -X PATCH影響範圍
這項改動直接影響所有寫自動化部署與 config-reload 腳本的維運工程師：原本包一層送 signal、等幾秒、再爬 log 判斷成敗的邏輯，現在可以整段換成檢查 HTTP 狀態碼的邏輯，CI/CD 或 Kubernetes readiness 檢查也能直接串接。官方文件同時提醒 Control API 本身沒有內建身份驗證，強烈建議只用 Unix socket 並限制檔案權限，不要直接對外開網路監聽；把它接進既有自動化流程時，這段存取控管必須自己補上。對於還停留在純 signal reload 的環境，這也代表設定漂移（設定檔與實際生效設定不一致）第一次有了官方提供、可直接查詢比對的管道。