Nginx API 網(wǎng)關(guān)配置從零到可用的五個(gè)關(guān)鍵步驟

Nginx API 網(wǎng)關(guān)配置從零到可用的五個(gè)關(guān)鍵步驟

很多團(tuán)隊(duì)在搭建微服務(wù)架構(gòu)時(shí)，都會(huì)把 Nginx 選為 API 網(wǎng)關(guān)的第一站。原因很簡(jiǎn)單：它輕量、穩(wěn)定、生態(tài)成熟，幾乎每臺(tái) Linux 服務(wù)器上都自帶。但真正動(dòng)手配置時(shí)，不少人會(huì)發(fā)現(xiàn)，照著網(wǎng)上教程抄一遍，服務(wù)卻總是不通，要么路由轉(zhuǎn)發(fā)失敗，要么跨域報(bào)錯(cuò)，要么上游服務(wù)收不到真實(shí)客戶端 IP。這些問(wèn)題往往不是 Nginx 本身難用，而是對(duì) API 網(wǎng)關(guān)的配置邏輯缺少系統(tǒng)理解。下面從實(shí)際搭建流程出發(fā)，拆解 Nginx 作為 API 網(wǎng)關(guān)時(shí)必須做好的五個(gè)環(huán)節(jié)。

理解反向代理與路由轉(zhuǎn)發(fā)的基本結(jié)構(gòu)

API 網(wǎng)關(guān)最核心的能力就是反向代理。Nginx 通過(guò) location 指令匹配請(qǐng)求路徑，再通過(guò) proxy_pass 將請(qǐng)求轉(zhuǎn)發(fā)到后端服務(wù)。這一步看似簡(jiǎn)單，但有兩個(gè)容易踩坑的地方。一是 proxy_pass 后面是否帶斜杠，行為完全不同。帶斜杠時(shí)，Nginx 會(huì)去掉 location 中匹配的部分再轉(zhuǎn)發(fā)；不帶斜杠時(shí)，則會(huì)把完整路徑原樣傳遞。比如 location /api/ 和 proxy_pass http://backend/，請(qǐng)求 /api/user 會(huì)被轉(zhuǎn)發(fā)為 /user，而如果 proxy_pass 不帶斜杠，則轉(zhuǎn)發(fā)為 /api/user。二是 upstream 塊的配置，建議用 upstream 定義后端服務(wù)器組，而不是直接在 proxy_pass 里寫(xiě) IP，這樣后續(xù)做負(fù)載均衡或健康檢查時(shí)只需修改一處。

配置請(qǐng)求頭傳遞與客戶端真實(shí) IP 保留

網(wǎng)關(guān)作為中間層，必須把客戶端的原始信息透?jìng)鹘o后端。默認(rèn)情況下，Nginx 轉(zhuǎn)發(fā)請(qǐng)求時(shí)，X-Real-IP 和 X-Forwarded-For 這些頭不會(huì)自動(dòng)設(shè)置。如果后端服務(wù)依賴客戶端 IP 做日志、限流或地理位置判斷，就會(huì)拿到錯(cuò)誤的網(wǎng)關(guān)內(nèi)網(wǎng)地址。正確的做法是在 location 或 http 塊中加入 proxy_set_header 指令，將 $remote_addr 賦值給 X-Real-IP，并將原有的 X-Forwarded-For 追加當(dāng)前 IP。同時(shí)別忘了設(shè)置 proxy_set_header Host $host，保證后端能正確識(shí)別請(qǐng)求的原始域名。對(duì)于使用 HTTPS 的場(chǎng)景，還要考慮 X-Forwarded-Proto，否則后端可能誤判協(xié)議類型，導(dǎo)致重定向地址變成 HTTP。

實(shí)現(xiàn)限流與安全防護(hù)的基本配置

API 網(wǎng)關(guān)的另一項(xiàng)重要職責(zé)是保護(hù)后端服務(wù)不被突發(fā)流量沖垮。Nginx 自帶的 ngx_http_limit_req_module 和 ngx_http_limit_conn_module 就能勝任大部分限流需求。配置時(shí)先定義限流區(qū)域，比如 limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s，然后在需要限流的 location 中引用 limit_req zone=api_limit burst=20 nodelay。這里的 burst 參數(shù)允許短時(shí)間內(nèi)的突發(fā)請(qǐng)求，nodelay 則讓這些請(qǐng)求立即處理而不是排隊(duì)。對(duì)于安全層面，可以配合 allow 和 deny 指令做 IP 白名單，或者用 map 模塊根據(jù) User-Agent 過(guò)濾爬蟲(chóng)。但要注意，Nginx 的限流是基于共享內(nèi)存的，zone 的大小要估算好，避免內(nèi)存溢出導(dǎo)致 worker 進(jìn)程崩潰。

跨域與 HTTPS 卸載的常見(jiàn)處理方式

前后端分離架構(gòu)下，跨域問(wèn)題是 API 網(wǎng)關(guān)必須解決的。Nginx 通過(guò) add_header 指令添加 CORS 頭，但很多人只加了 Access-Control-Allow-Origin，忽略了預(yù)檢請(qǐng)求的處理。瀏覽器在發(fā)送復(fù)雜請(qǐng)求前會(huì)先發(fā)一個(gè) OPTIONS 請(qǐng)求，如果網(wǎng)關(guān)沒(méi)有正確響應(yīng)，前端就會(huì)報(bào)跨域錯(cuò)誤。正確的做法是在 location 中單獨(dú)處理 OPTIONS 方法，返回 204 狀態(tài)碼，并帶上 Allow-Methods、Allow-Headers 等頭。另外，HTTPS 卸載也是網(wǎng)關(guān)的常見(jiàn)角色。在 Nginx 上配置 SSL 證書(shū)后，后端服務(wù)可以只監(jiān)聽(tīng) HTTP，減輕證書(shū)管理的負(fù)擔(dān)。但要注意，卸載后后端收到的請(qǐng)求是 HTTP 的，如果后端有強(qiáng)制 HTTPS 跳轉(zhuǎn)的邏輯，需要關(guān)閉或調(diào)整，否則會(huì)產(chǎn)生重定向循環(huán)。

日志格式與調(diào)試技巧讓問(wèn)題無(wú)處藏身

配置完成后，驗(yàn)證和調(diào)試是必不可少的一步。很多人只靠瀏覽器看返回狀態(tài)碼，遇到 502 或 504 就無(wú)從下手。Nginx 的日志系統(tǒng)其實(shí)非常強(qiáng)大。先在 http 塊中定義一個(gè)詳細(xì)的 log_format，包含 $upstream_addr、$upstream_status、$upstream_response_time 等變量，然后在 server 或 location 中引用。這樣當(dāng)請(qǐng)求出錯(cuò)時(shí)，日志里就能看到請(qǐng)求被轉(zhuǎn)發(fā)到了哪個(gè)后端、后端返回了什么狀態(tài)碼、響應(yīng)耗時(shí)多少。如果后端返回 502，通常意味著上游服務(wù)未啟動(dòng)或端口不對(duì)；如果返回 504，則可能是后端處理超時(shí)，需要調(diào)整 proxy_read_timeout。另外，可以臨時(shí)在 location 中加入 error_page 指令，將 502 頁(yè)面替換為一段包含調(diào)試信息的 JSON 響應(yīng)，方便快速定位問(wèn)題。