Nginx API 网关配置从零到可用的五个关键步骤

Nginx API 网关配置从零到可用的五个关键步骤

很多团队在搭建微服务架构时，都会把 Nginx 选为 API 网关的第一站。原因很简单：它轻量、稳定、生态成熟，几乎每台 Linux 服务器上都自带。但真正动手配置时，不少人会发现，照着网上教程抄一遍，服务却总是不通，要么路由转发失败，要么跨域报错，要么上游服务收不到真实客户端 IP。这些问题往往不是 Nginx 本身难用，而是对 API 网关的配置逻辑缺少系统理解。下面从实际搭建流程出发，拆解 Nginx 作为 API 网关时必须做好的五个环节。

理解反向代理与路由转发的基本结构

API 网关最核心的能力就是反向代理。Nginx 通过 location 指令匹配请求路径，再通过 proxy_pass 将请求转发到后端服务。这一步看似简单，但有两个容易踩坑的地方。一是 proxy_pass 后面是否带斜杠，行为完全不同。带斜杠时，Nginx 会去掉 location 中匹配的部分再转发；不带斜杠时，则会把完整路径原样传递。比如 location /api/ 和 proxy_pass http://backend/，请求 /api/user 会被转发为 /user，而如果 proxy_pass 不带斜杠，则转发为 /api/user。二是 upstream 块的配置，建议用 upstream 定义后端服务器组，而不是直接在 proxy_pass 里写 IP，这样后续做负载均衡或健康检查时只需修改一处。

配置请求头传递与客户端真实 IP 保留

网关作为中间层，必须把客户端的原始信息透传给后端。默认情况下，Nginx 转发请求时，X-Real-IP 和 X-Forwarded-For 这些头不会自动设置。如果后端服务依赖客户端 IP 做日志、限流或地理位置判断，就会拿到错误的网关内网地址。正确的做法是在 location 或 http 块中加入 proxy_set_header 指令，将 $remote_addr 赋值给 X-Real-IP，并将原有的 X-Forwarded-For 追加当前 IP。同时别忘了设置 proxy_set_header Host $host，保证后端能正确识别请求的原始域名。对于使用 HTTPS 的场景，还要考虑 X-Forwarded-Proto，否则后端可能误判协议类型，导致重定向地址变成 HTTP。

实现限流与安全防护的基本配置

API 网关的另一项重要职责是保护后端服务不被突发流量冲垮。Nginx 自带的 ngx_http_limit_req_module 和 ngx_http_limit_conn_module 就能胜任大部分限流需求。配置时先定义限流区域，比如 limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s，然后在需要限流的 location 中引用 limit_req zone=api_limit burst=20 nodelay。这里的 burst 参数允许短时间内的突发请求，nodelay 则让这些请求立即处理而不是排队。对于安全层面，可以配合 allow 和 deny 指令做 IP 白名单，或者用 map 模块根据 User-Agent 过滤爬虫。但要注意，Nginx 的限流是基于共享内存的，zone 的大小要估算好，避免内存溢出导致 worker 进程崩溃。

跨域与 HTTPS 卸载的常见处理方式

前后端分离架构下，跨域问题是 API 网关必须解决的。Nginx 通过 add_header 指令添加 CORS 头，但很多人只加了 Access-Control-Allow-Origin，忽略了预检请求的处理。浏览器在发送复杂请求前会先发一个 OPTIONS 请求，如果网关没有正确响应，前端就会报跨域错误。正确的做法是在 location 中单独处理 OPTIONS 方法，返回 204 状态码，并带上 Allow-Methods、Allow-Headers 等头。另外，HTTPS 卸载也是网关的常见角色。在 Nginx 上配置 SSL 证书后，后端服务可以只监听 HTTP，减轻证书管理的负担。但要注意，卸载后后端收到的请求是 HTTP 的，如果后端有强制 HTTPS 跳转的逻辑，需要关闭或调整，否则会产生重定向循环。

日志格式与调试技巧让问题无处藏身

配置完成后，验证和调试是必不可少的一步。很多人只靠浏览器看返回状态码，遇到 502 或 504 就无从下手。Nginx 的日志系统其实非常强大。先在 http 块中定义一个详细的 log_format，包含 $upstream_addr、$upstream_status、$upstream_response_time 等变量，然后在 server 或 location 中引用。这样当请求出错时，日志里就能看到请求被转发到了哪个后端、后端返回了什么状态码、响应耗时多少。如果后端返回 502，通常意味着上游服务未启动或端口不对；如果返回 504，则可能是后端处理超时，需要调整 proxy_read_timeout。另外，可以临时在 location 中加入 error_page 指令，将 502 页面替换为一段包含调试信息的 JSON 响应，方便快速定位问题。