Nginx 反向代理后端 API 服务完整配置指南

后端服务通常不会直接暴露给公网用户，而是放在 Nginx 后面。Nginx 负责监听 80/443 端口、处理域名、转发请求、设置超时、限制上传大小，并统一管理访问日志。

本文以一个运行在 127.0.0.1:3000 的 API 服务为例，讲清楚 Nginx 反向代理的常用配置和排查方法。

一、基础代理配置

创建站点配置：

1	sudo vim /etc/nginx/conf.d/api.example.com.conf

写入：

server {
    listen 80;
    server_name api.example.com;

    access_log /var/log/nginx/api.example.com.access.log;
    error_log  /var/log/nginx/api.example.com.error.log;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        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;
    }
}

验证配置：

1	sudo nginx -t

重新加载：

1	sudo systemctl reload nginx

二、为什么要设置转发头

后端服务看到的直接来源是 Nginx，如果不传递头信息，后端可能拿不到真实客户端 IP。

常用头：

Host                 原始访问域名
X-Real-IP            客户端真实 IP
X-Forwarded-For      代理链路上的 IP 列表
X-Forwarded-Proto    原始协议，http 或 https

后端生成回调地址、跳转地址、日志审计时，经常依赖这些信息。

三、代理超时配置

默认超时不一定适合所有 API。可以按接口特点设置：

location / {
    proxy_pass http://127.0.0.1:3000;

    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;
}

含义：

proxy_connect_timeout：Nginx 连接后端的超时时间
proxy_send_timeout：Nginx 向后端发送请求的超时时间
proxy_read_timeout：Nginx 等待后端响应的超时时间

普通 API 不建议把超时设置得过长。长任务应该改成异步任务，由前端轮询任务状态。

四、上传大小限制

如果接口需要上传文件，可能遇到 413 Request Entity Too Large。

可以设置：

1
2
3

server {
    client_max_body_size 50m;
}

也可以只对某个路径开放：

location /upload {
    client_max_body_size 100m;
    proxy_pass http://127.0.0.1:3000;
}

不要全站无脑设置很大。上传接口应该单独限制，避免异常请求占用过多资源。

五、WebSocket 代理

如果后端使用 WebSocket，需要增加升级头：

location /ws {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    proxy_set_header Host $host;
    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，可以这样组织：

server {
    listen 80;
    server_name example.com;

    root /var/www/example.com;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        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;
    }
}

注意 proxy_pass 末尾的 / 会影响路径拼接。配置后一定要用实际接口测试路径是否正确。

七、常见错误排查

1. 502 Bad Gateway

通常表示 Nginx 连不上后端。

检查后端进程：

1	sudo ss -lntp \| grep 3000

检查 Nginx 错误日志：

1	sudo tail -n 100 /var/log/nginx/api.example.com.error.log

常见原因：

后端服务没启动
端口写错
后端只监听了容器内地址
防火墙或 SELinux 限制

2. 504 Gateway Timeout

后端没有在规定时间内返回。需要判断是接口真的慢，还是后端卡死。

1	curl -v http://127.0.0.1:3000/health

如果本机访问也慢，问题在后端，不在 Nginx。

3. 404 路径不对

重点检查 location 和 proxy_pass 的尾部斜杠。路径转发问题很多都出在这里。

八、生产配置建议

生产环境至少要考虑：

为每个站点单独配置 access log 和 error log
设置合理的超时和上传限制
后端只监听 127.0.0.1 或内网地址
使用 HTTPS 终止 TLS
健康检查接口单独提供
发布后用 curl 验证关键路径

Nginx 配置不复杂，但细节会直接影响线上稳定性。每次改配置后先 nginx -t，再 reload，这是最低成本的风险控制。