Nginx配置React应用/api/代理至私有网络后端失败排查

问题背景 #

将ReactJS应用部署在Nginx服务器，后端位于私有网络。前端通过http://my-domain.com/访问，前端发起http://my-domain.com/api/请求时，需要Nginx代理到http://my-backend-loadbalancer.com/api/。

初始配置及问题 #

初始配置文件路径：/etc/nginx/sites-available/my-domain.com

server {
    listen 80;
    listen [::]:80;

    root /var/www/my-domain.com/html;
    index index.html index.htm index.nginx-debian.html;

    server_name www.my-domain.com my-domain.com;

    location / {
            try_files $uri $uri/ =404;
    }

    location /api/ {
            proxy_set_header Host my-backend-loadbalancer.com;
            proxy_pass http://my-backend-loadbalancer.com$is_args$args;
    }
}

该配置返回Bad Request错误。

更新后的配置及问题 #

修改后的配置：

server {
    listen 80;
    listen [::]:80;

    root /var/www/my-domain.com/html;
    index index.html index.htm index.nginx-debian.html;

    server_name www.my-domain.com my-domain.com;

    location / {
            try_files $uri $uri/ =404;
    }

    location /api/ {
            proxy_pass http://my-backend-loadbalancer.com;
    }
}

访问http://my-domain.com/api/时，会直接重定向到http://my-backend-loadbalancer.com且丢失请求参数，同时Nginx错误日志error.log中出现：

2022/11/04 15:57:52 [error] 4749#4749: *3 no resolver defined to resolve internal-backend-213123123.us-west-1.elb.amazonaws.com, client: 10.0.0.78, server: www.my-domain.com, request: "GET /api/ HTTP/1.1", host: "my-domain.com", referrer: "http://my-domain.com/"

问题分析 #

核心问题是Nginx无法解析私有网络后端的域名——默认情况下Nginx使用系统Resolver，但私有网络内的域名（如AWS内部ELB域名）需要指定私有DNS服务器才能解析。同时之前的配置在路径传递、参数处理上也存在逻辑问题。

解决方案 #

1. 配置私有Resolver #

在Nginx配置中添加私有网络的DNS服务器地址（比如AWS VPC的DNS通常是VPC网段+2，例：VPC网段为10.0.0.0/16时，DNS地址是10.0.0.2），确保Nginx能解析私有后端域名。

2. 修正代理路径与参数传递 #

确保代理时保留/api/路径，同时正确传递请求参数和头部信息。

最终配置示例：

server {
    listen 80;
    listen [::]:80;

    root /var/www/my-domain.com/html;
    index index.html index.htm index.nginx-debian.html;

    server_name www.my-domain.com my-domain.com;

    # 配置私有网络DNS resolver，替换为你的私有DNS地址
    resolver 10.0.0.2 valid=300s;

    location / {
            try_files $uri $uri/ /index.html; # React单页应用建议用/index.html替代=404，避免路由刷新404
    }

    location /api/ {
            # 传递原始请求Host头部，或根据后端需求调整
            proxy_set_header Host $host;
            # 传递真实客户端IP
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            # 正确传递路径：将/api/开头的请求代理到后端的/api/路径
            proxy_pass http://my-backend-loadbalancer.com/api/;
            # 禁止自动重定向，保持域名统一
            proxy_redirect off;
    }
}

关键配置说明 #

• resolver：指定私有DNS服务器，valid=300s表示缓存DNS解析结果5分钟，提升性能。
• proxy_pass：末尾保留/api/，确保Nginx将/api/xxx代理到http://my-backend-loadbalancer.com/api/xxx，避免路径丢失。
• proxy_set_header：传递必要请求头部，让后端能获取真实客户端信息，避免因头部缺失导致的Bad Request。
• location /：React单页应用使用try_files $uri $uri/ /index.html，解决前端路由刷新返回404的问题。

私有网络后端访问最佳实践 #

• 使用私有DNS解析：必须在Nginx配置中指定私有网络的DNS服务器，确保能解析内部域名。
• 保持路径一致性：代理时尽量保持前后端路径一致，减少路径重写带来的逻辑问题。
• 传递必要请求头部：包括Host、客户端IP、协议等头部，后端服务可能依赖这些信息处理请求。
• 可选：启用代理缓存：对静态API响应可配置proxy_cache提升性能，但动态请求需谨慎使用。
• 安全加固：确保Nginx服务器所在节点有访问后端的网络权限，可添加限流、认证等安全措施。

内容的提问来源于stack exchange，提问作者Erick Villatoro