Nginx 反向代理配置文档#

1. 概述#

Nginx 是一款高性能的 HTTP 和反向代理服务器，常用于负载均衡、缓存、安全防护等场景。反向代理是指客户端请求发送到代理服务器，由代理服务器将请求转发给后端真实服务器，并将响应结果返回给客户端，客户端并不知道后端服务器的存在。

1.1 正向代理 vs 反向代理#

类型	代理对象	客户端是否感知	典型用途
正向代理	客户端	知道	翻墙、访问控制
反向代理	服务器	不知道	负载均衡、安全、缓存

2. 基础配置语法#

2.1 基本结构#

1
server {
2
    listen 80;
3
    server_name example.com;
4

5
    location / {
6
        proxy_pass http://backend_server;
7
        proxy_set_header Host $host;
8
        proxy_set_header X-Real-IP $remote_addr;
9
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
10
        proxy_set_header X-Forwarded-Proto $scheme;
11
    }
12
}
13

14
upstream backend_server {
15
    server 192.168.1.10:8080;
16
    server 192.168.1.11:8080;
17
}

3. 关键指令详解#

3.1 `proxy_pass`#

定义后端服务器地址。

1
location /api/ {
2
    proxy_pass http://127.0.0.1:3000/;  # 注意结尾斜杠
3
}

⚠️ 注意：proxy_pass 后是否带 / 会影响 URL 路径转发行为。

3.2 `proxy_set_header`#

设置转发给后端的请求头。

1
proxy_set_header Host $host;
2
proxy_set_header X-Real-IP $remote_addr;
3
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
4
proxy_set_header X-Forwarded-Proto $scheme;

3.3 `proxy_redirect`#

修改后端返回的 Location 和 Refresh 头。

1
proxy_redirect off;
2
# 或
3
proxy_redirect http://backend/ /;

3.4 `proxy_buffering`#

启用/禁用响应缓冲（默认开启）。

1
proxy_buffering on;
2
proxy_buffer_size 4k;
3
proxy_buffers 8 4k;

3.5 `proxy_connect_timeout`, `proxy_read_timeout`#

设置超时时间（单位：秒）。

1
proxy_connect_timeout 60s;
2
proxy_send_timeout 60s;
3
proxy_read_timeout 60s;

4. 实用配置示例#

4.1 单后端服务器代理#

1
server {
2
    listen 80;
3
    server_name myapp.com;
4

5
    location / {
6
        proxy_pass http://localhost:8080;
7
        proxy_set_header Host $host;
8
        proxy_set_header X-Real-IP $remote_addr;
9
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
10
        proxy_set_header X-Forwarded-Proto $scheme;
11
    }
12
}

4.2 负载均衡配置（Upstream）#

1
upstream backend {
2
    server 10.0.0.1:8080 weight=3;   # 权重3
3
    server 10.0.0.2:8080 weight=1;
4
    server 10.0.0.3:8080 backup;     # 备用服务器
5
}
6

7
server {
8
    listen 80;
9
    server_name loadbalance.com;
10

11
    location / {
12
        proxy_pass http://backend;
13
        proxy_set_header Host $host;
14
        proxy_set_header X-Real-IP $remote_addr;
15
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
16
    }
17
}

负载均衡策略：#

轮询（默认）：按顺序分配
weight：权重分配
ip_hash：根据客户端IP分配（会话保持）
least_conn：最少连接优先
hash $request_uri consistent：一致性哈希

4.3 WebSocket 代理支持#

1
location /ws/ {
2
    proxy_pass http://backend;
3
    proxy_http_version 1.1;
4
    proxy_set_header Upgrade $http_upgrade;
5
    proxy_set_header Connection "upgrade";
6
    proxy_set_header Host $host;
7
}

4.4 HTTPS 反向代理#

1
server {
2
    listen 443 ssl http2;
3
    server_name secure.example.com;
4

5
    ssl_certificate /path/to/fullchain.pem;
6
    ssl_certificate_key /path/to/privkey.pem;
7

8
    location / {
9
        proxy_pass http://backend;
10
        proxy_set_header Host $host;
11
        proxy_set_header X-Real-IP $remote_addr;
12
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
13
        proxy_set_header X-Forwarded-Proto $scheme;  # 告知后端是HTTPS
14
    }
15
}

4.5 缓存配置（可选）#

1
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;
2

3
server {
4
    location / {
5
        proxy_cache my_cache;
6
        proxy_cache_valid 200 302 10m;
7
        proxy_cache_valid 404 1m;
8
        proxy_pass http://backend;
9
        add_header X-Cache-Status $upstream_cache_status;
10
    }
11
}

5. 安全与优化建议#

5.1 隐藏 Nginx 版本号#

1
server_tokens off;

5.2 限制请求大小和速率#

1
client_max_body_size 10M;
2
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
3

4
location /api/ {
5
    limit_req zone=api burst=20 nodelay;
6
    proxy_pass http://backend;
7
}

5.3 启用 Gzip 压缩#

1
gzip on;
2
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

5.4 设置合理的超时与缓冲#

1
proxy_connect_timeout 5s;
2
proxy_send_timeout 10s;
3
proxy_read_timeout 30s;
4
proxy_buffering on;
5
proxy_buffer_size 16k;
6
proxy_buffers 4 64k;

6. 调试与日志#

6.1 自定义日志格式#

1
log_format upstream_time '$remote_addr - $remote_user [$time_local] '
2
                         '"$request" $status $body_bytes_sent '
3
                         '"$http_referer" "$http_user_agent" '
4
                         'rt=$request_time uct="$upstream_connect_time" uht="$upstream_header_time" urt="$upstream_response_time"';
5

6
access_log /var/log/nginx/access.log upstream_time;

6.2 调试代理问题#

在 location 块中添加：

1
add_header X-Upstream $upstream_addr;
2
add_header X-Upstream-Status $upstream_status;
3
add_header X-Upstream-Response-Time $upstream_response_time;

7. 重载配置#

修改配置后执行：

1
# 测试配置语法
2
nginx -t
3

4
# 重载配置（不中断服务）
5
nginx -s reload
6

7
# 或使用系统服务
8
systemctl reload nginx

8. 常见问题排查#

❌ 502 Bad Gateway#

后端服务未启动
proxy_pass 地址错误
防火墙/安全组阻止连接

❌ 504 Gateway Timeout#

后端处理超时 → 增大 proxy_read_timeout
网络延迟过高

❌ WebSocket 连接失败#

未设置 proxy_http_version 1.1 和 Upgrade/Connection 头

❌ 静态资源 404#

检查 proxy_pass 路径是否匹配
检查后端应用路由配置

9. 完整示例配置文件#

1
upstream app_servers {
2
    server 127.0.0.1:3000;
3
    server 127.0.0.1:3001;
4
    keepalive 32;
5
}
6

7
server {
8
    listen 80;
9
    server_name myapp.example.com;
10
    return 301 https://$server_name$request_uri;
11
}
12

13
server {
14
    listen 443 ssl http2;
15
    server_name myapp.example.com;
16

17
    ssl_certificate /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
18
    ssl_certificate_key /etc/letsencrypt/live/myapp.example.com/privkey.pem;
19

20
    access_log /var/log/nginx/myapp.access.log;
21
    error_log /var/log/nginx/myapp.error.log;
22

23
    client_max_body_size 20M;
24

25
    location / {
26
        proxy_pass http://app_servers;
27
        proxy_http_version 1.1;
28
        proxy_set_header Host $host;
29
        proxy_set_header X-Real-IP $remote_addr;
30
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
31
        proxy_set_header X-Forwarded-Proto $scheme;
32

33
        proxy_connect_timeout 5s;
34
        proxy_send_timeout 10s;
35
        proxy_read_timeout 30s;
36

37
        proxy_buffering on;
38
        proxy_buffer_size 16k;
39
        proxy_buffers 4 64k;
40

41
        # WebSocket 支持
42
        proxy_set_header Upgrade $http_upgrade;
43
        proxy_set_header Connection "upgrade";
44
    }
45

46
    # 静态资源缓存（可选）
47
    location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
48
        expires 1y;
49
        add_header Cache-Control "public, immutable";
50
    }
51
}

10. 参考资料#

✅ 本配置文档适用于 Nginx 1.18+ 版本，建议在生产环境前进行充分测试。