Nginx 用 proxy_pass 实现 API 网关聚合转发，通过 location 路径匹配路由到后端，需注意 proxy_pass 末尾斜杠对路径截断的影响，并配置请求头透传、超时、健康检查、限流及日志等稳定性与可观测性能力。
用 Nginx 的 proxy_pass 做 API 网关聚合转发，核心是把多个后端服务的接口统一暴露在同一个域名下，按路径做路由分发，同时兼顾请求头、超时、重试等网关常见能力。它轻量、稳定、性能高，适合中小规模或对成本敏感的场景。
路径匹配与服务路由
通过 location 块配合正则或前缀匹配，把不同 API 路径转发到对应后端。关键点是路径截断和重写：
- 以
/user/开头的请求，转发到用户服务：location /user/ { proxy_pass http://user-srv/; }
注意末尾斜杠：proxy_pass后带/表示截掉匹配前缀，否则会原样拼接 - 需要重写路径（如把
/api/v1/order映射为后端的/order）可加rewrite：location /api/v1/order { rewrite ^/api/v1/order(.*) $1 break; proxy_pass http://order-srv; } - 支持正则匹配实现更灵活路由，例如按版本号或租户隔离：
location ~ ^/v(?<ver>\d+)/products { proxy_set_header X-API-Version $ver; proxy_pass http://product-srv; }</ver>
透传与改写关键请求头
后端服务常依赖原始 Host、协议、客户端 IP 等信息，需显式设置才能正确识别：
- 保留原始 Host：
proxy_set_header Host $host;（不设则默认用 upstream 名） - 传递真实客户端 IP：
proxy_set_header X-Real-IP $remote_addr;+proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - 告知后端使用 HTTPS：
proxy_set_header X-Forwarded-Proto $scheme;（尤其影响重定向或资源链接生成） - 添加自定义标头（如网关标识、请求 ID）：
proxy_set_header X-Gateway nginx-api-gw;
稳定性与可观测性配置
生产环境不能只转，还要防雪崩、可追踪、易排查：
- 设置合理超时：
proxy_connect_timeout 5s;、proxy_send_timeout 30s;、proxy_read_timeout 30s; - 启用健康检查（需配合 upstream）：
upstream user-srv { server 10.0.1.10:8080 max_fails=3 fail_timeout=30s; } - 限制单个客户端连接数防爬：
limit_conn addr 10;（配合limit_conn_zone $binary_remote_addr zone=addr:10m;） - 记录上游响应时间与状态码，便于监控：
log_format upstream_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $upstream_addr $upstream_response_time $request_time';
聚合转发的进阶技巧
纯 proxy_pass 不支持响应合并或请求编排，但可通过组合模块扩展能力：
- 用
sub_filter修改响应体（如替换内部地址为公网地址）：sub_filter 'http://internal-api/' 'https://api.example.com/'; sub_filter_once off; - 结合
auth_request模块做统一鉴权：auth_request /auth; location = /auth { proxy_pass https://auth-srv/check; } - 对特定路径启用缓存（如文档、配置类接口）：
proxy_cache my_cache; proxy_cache_valid 200 302 10m; - 错误页统一处理：
error_page 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; }
