Nginx 反向代理配置实战完全指南：从入门到生产部署 | 2026 最新

1
=== 正向代理（隐藏客户端）===
2
客户端 → 正向代理 → 互联网 → 目标服务器
3
          ↑
4
    目标服务器不知道真实客户端 IP
5

6
=== 反向代理（隐藏服务器）===
7
客户端 → 反向代理 → 后端服务器 A
8
                  → 后端服务器 B
9
                  → 后端服务器 C
10
          ↑
11
    客户端不知道后端服务器的存在

1
客户端请求
2
    ↓
3
Nginx 接收（80/443 端口）
4
    ↓
5
server { ... } 匹配域名
6
    ↓
7
location { ... } 匹配路径
8
    ↓
9
proxy_pass 转发到后端
10
    ↓
11
后端处理请求
12
    ↓
13
Nginx 接收后端响应
14
    ↓
15
返回给客户端

1
# === 情况一：proxy_pass 不带 URI（末尾无 /path）===
2
location /api/ {
3
    proxy_pass http://127.0.0.1:3000;  # 不带 URI
4
    # 请求 /api/users → 转发到 http://127.0.0.1:3000/api/users
5
    # 完整路径（含 location 匹配部分）会附加到目标地址
6
}
7

8
# === 情况二：proxy_pass 带 URI（末尾有 /path）===
9
location /api/ {
10
    proxy_pass http://127.0.0.1:3000/v2/;  # 带 URI（末尾有 /）
11
    # 请求 /api/users → 转发到 http://127.0.0.1:3000/v2/users
12
    # location 匹配的部分（/api/）被替换为 proxy_pass 中的 URI（/v2/）
13
}
14

15
# === 情况三：正则表达式 location ===
16
location ~ ^/api/(.*)$ {
17
    proxy_pass http://127.0.0.1:3000/$1;  # 必须用变量形式
18
    # 正则 location 中，proxy_pass 不能带普通 URI，必须用变量
19
}

1
location / {
2
    proxy_pass http://127.0.0.1:3000;
3

4
    # 基础头（必须配置）
5
    proxy_set_header Host $host;
6
    proxy_set_header X-Real-IP $remote_addr;
7
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
8
    proxy_set_header X-Forwarded-Proto $scheme;
9

10
    #  WebSocket 支持（见第 6 节详解）
11
    proxy_http_version 1.1;
12
    proxy_set_header Upgrade $http_upgrade;
13
    proxy_set_header Connection "upgrade";
14

15
    # 超时配置（生产环境必须调整）
16
    proxy_connect_timeout 5s;   # 连接后端超时
17
    proxy_send_timeout 30s;      # 发送请求到后端超时
18
    proxy_read_timeout 30s;      # 读取后端响应超时
19

20
    # 缓冲配置
21
    proxy_buffering on;
22
    proxy_buffer_size 8k;
23
    proxy_buffers 8 8k;
24
}

1
# 定义后端服务器组
2
upstream backend {
3
    server 127.0.0.1:3001;
4
    server 127.0.0.1:3002;
5
    server 127.0.0.1:3003;
6
}
7

8
server {
9
    listen 80;
10
    server_name example.com;
11

12
    location / {
13
        proxy_pass http://backend;  # 使用 upstream 名称
14
        proxy_set_header Host $host;
15
        proxy_set_header X-Real-IP $remote_addr;
16
    }
17
}

1
upstream backend {
2
    # === 策略一：轮询（默认）===
3
    # 依次将请求分发给每个后端，适合后端性能相近的场景
4
    server 127.0.0.1:3001;
5
    server 127.0.0.1:3002;
6
    server 127.0.0.1:3003;
7
}
8

9
upstream backend_weighted {
10
    # === 策略二：加权轮询 ===
11
    # weight 越高，分配到的请求越多，适合后端性能不均
12
    server 127.0.0.1:3001 weight=3;  # 60% 请求
13
    server 127.0.0.1:3002 weight=2;  # 40% 请求
14
    server 127.0.0.1:3003 weight=1;  # 20% 请求
15
}
16

17
upstream backend_iphash {
18
    # === 策略三：ip_hash ===
19
    # 按客户端 IP 哈希分配，保证同一客户端总是访问同一后端
20
    # 适合有状态应用（如未使用共享 Session 的场景）
21
    ip_hash;
22
    server 127.0.0.1:3001;
23
    server 127.0.0.1:3002;
24
    server 127.0.0.1:3003;
25
}
26

27
upstream backend_leastconn {
28
    # === 策略四：least_conn ===
29
    # 优先将请求分发到活跃连接数最少的后端（动态负载均衡）
30
    # 适合请求处理时间差异较大的场景
31
    least_conn;
32
    server 127.0.0.1:3001;
33
    server 127.0.0.1:3002;
34
    server 127.0.0.1:3003;
35
}

1
upstream backend {
2
    server 127.0.0.1:3001 weight=5 max_fails=3 fail_timeout=30s;
3
    server 127.0.0.1:3002 weight=3 max_fails=3 fail_timeout=30s;
4
    server 127.0.0.1:3003 weight=2 max_fails=3 fail_timeout=30s;
5
    server 127.0.0.1:3004 backup;   # 备份服务器（其他都宕机时才启用）
6
    server 127.0.0.1:3005 down;     # 标记下线（维护时临时移除）
7
}

1
# 被动健康检查（开源版自带）
2
upstream backend {
3
    server 127.0.0.1:3001 max_fails=2 fail_timeout=10s;
4
    server 127.0.0.1:3002 max_fails=2 fail_timeout=10s;
5
    # 10 秒内失败 2 次，则该后端被标记为不可用 10 秒
6
}

1
# HTTP 自动跳转 HTTPS
2
server {
3
    listen 80;
4
    server_name example.com www.example.com;
5
    return 301 https://$host$request_uri;
6
}
7

8
# HTTPS 反向代理
9
server {
10
    listen 443 ssl http2;
11
    server_name example.com www.example.com;
12

13
    # SSL 证书配置
14
    ssl_certificate /etc/nginx/ssl/example.com.crt;
15
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
16

17
    # SSL 安全配置（推荐）
18
    ssl_protocols TLSv1.2 TLSv1.3;
19
    ssl_ciphers HIGH:!aNULL:!MD5;
20
    ssl_prefer_server_ciphers on;
21
    ssl_session_cache shared:SSL:10m;
22
    ssl_session_timeout 10m;
23

24
    # HSTS（强制 HTTPS）
25
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
26

27
    location / {
28
        proxy_pass http://127.0.0.1:3000;
29
        proxy_set_header Host $host;
30
        proxy_set_header X-Real-IP $remote_addr;
31
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
32
        proxy_set_header X-Forwarded-Proto $scheme;
33
    }
34
}

1
# 定义后端（内网 HTTP，不走 HTTPS）
2
upstream backend {
3
    server 10.0.0.101:8080 weight=3;
4
    server 10.0.0.102:8080 weight=2;
5
    server 10.0.0.103:8080 weight=1 backup;
6
}
7

8
# HTTP 跳转 HTTPS
9
server {
10
    listen 80;
11
    server_name api.example.com;
12
    return 301 https://$host$request_uri;
13
}
14

15
# HTTPS 入口（SSL 终止在这里做）
16
server {
17
    listen 443 ssl http2;
18
    server_name api.example.com;
19

20
    # Let's Encrypt 证书
21
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
22
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
23
    ssl_protocols TLSv1.2 TLSv1.3;
24

25
    # 安全头
26
    add_header Strict-Transport-Security "max-age=31536000" always;
27
    add_header X-Content-Type-Options "nosniff" always;
28
    add_header X-Frame-Options "DENY" always;
29

30
    # API 代理
31
    location / {
32
        proxy_pass http://backend;
33
        proxy_set_header Host $host;
34
        proxy_set_header X-Real-IP $remote_addr;
35
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
36
        proxy_set_header X-Forwarded-Proto $scheme;
37

38
        # API 场景超时时间要长一些
39
        proxy_connect_timeout 5s;
40
        proxy_read_timeout 60s;
41
        proxy_send_timeout 60s;
42
    }
43

44
    # 健康检查端点（负载均衡场景）
45
    location /health {
46
        access_log off;
47
        return 200 "OK\n";
48
        add_header Content-Type "text/plain";
49
    }
50
}

1
# 定义缓存区（在 http 块中配置）
2
http {
3
    # 缓存区：名称=one，缓存路径=/var/cache/nginx，最大 10m 索引，缓存 1g 磁盘空间
4
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=one:10m max_size=1g inactive=60m use_temp_path=off;
5

6
    server {
7
        listen 80;
8
        server_name example.com;
9

10
        location / {
11
            proxy_pass http://127.0.0.1:3000;
12

13
            # 启用缓存
14
            proxy_cache one;
15
            proxy_cache_key $scheme$request_method$host$request_uri;
16
            proxy_cache_valid 200 302 10m;   # 200/302 缓存 10 分钟
17
            proxy_cache_valid 404 1m;        # 404 缓存 1 分钟
18
            proxy_cache_valid any 5m;         # 其他状态码缓存 5 分钟
19

20
            # 缓存命中状态（响应头中可以看到）
21
            add_header X-Cache-Status $upstream_cache_status;
22

23
            # 跳过缓存的条件
24
            proxy_cache_bypass $http_cache_control;  # 带 Cache-Control: no-cache 则不缓存
25
        }
26
    }
27
}

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

5
    # 静态资源：长缓存
6
    location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff2?)$ {
7
        proxy_pass http://127.0.0.1:3000;
8
        proxy_cache one;
9
        proxy_cache_valid 200 7d;       # 静态资源缓存 7 天
10
        proxy_cache_valid any 1m;
11
        add_header X-Cache-Status $upstream_cache_status;
12
        expires 7d;                       # 浏览器缓存 7 天
13
        add_header Cache-Control "public, max-age=604800";
14
    }
15

16
    # API 接口：短缓存或不缓存
17
    location /api/ {
18
        proxy_pass http://127.0.0.1:3000;
19
        proxy_cache one;
20
        proxy_cache_valid 200 1m;        # API 缓存 1 分钟
21
        proxy_cache_valid any 0s;          # 其他不缓存
22
        proxy_no_cache $http_authorization;  # 有 Authorization 头时不缓存
23
    }
24

25
    # 动态页面：不缓存
26
    location / {
27
        proxy_pass http://127.0.0.1:3000;
28
        proxy_set_header Host $host;
29
        proxy_set_header X-Real-IP $remote_addr;
30
        # 不启用缓存
31
    }
32
}

1
map $http_upgrade $connection_upgrade {
2
    default upgrade;
3
    ''      close;
4
}
5

6
server {
7
    listen 80;
8
    server_name ws.example.com;
9

10
    location /ws/ {
11
        proxy_pass http://127.0.0.1:3000;
12
        proxy_http_version 1.1;
13

14
        # WebSocket 核心配置
15
        proxy_set_header Upgrade $http_upgrade;
16
        proxy_set_header Connection $connection_upgrade;
17

18
        # 延长超时（WebSocket 是长连接）
19
        proxy_read_timeout 3600s;
20
        proxy_send_timeout 3600s;
21

22
        # 传递真实 IP
23
        proxy_set_header X-Real-IP $remote_addr;
24
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
25
    }
26
}

1
# 在 http 块中（不能在 server 或 location 中）
2
http {
3
    map $http_upgrade $connection_upgrade {
4
        default upgrade;   # 默认：Upgrade（WebSocket 握手）
5
        ''      close;     # 如果没有 Upgrade 头：close
6
    }
7
    # ...
8
}

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

5
    location /socket.io/ {
6
        proxy_pass http://127.0.0.1:3000/socket.io/;
7
        proxy_http_version 1.1;
8
        proxy_set_header Upgrade $http_upgrade;
9
        proxy_set_header Connection "upgrade";
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

14
        # Socket.IO 特殊配置
15
        proxy_read_timeout 86400s;  # 24 小时（长轮询兼容）
16
    }
17
}

1
upstream nodeapp {
2
    server 127.0.0.1:3000;
3
    server 127.0.0.1:3001;
4
    server 127.0.0.1:3002;
5
}
6

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

11
    # 压缩（减少传输大小）
12
    gzip on;
13
    gzip_types text/plain text/css application/json application/javascript;
14

15
    # 静态资源直接由 Nginx 提供（不经过 Node.js）
16
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
17
        root /var/www/myapp/public;
18
        expires 30d;
19
        access_log off;
20
    }
21

22
    # Node.js 动态请求
23
    location / {
24
        proxy_pass http://nodeapp;
25
        proxy_http_version 1.1;
26
        proxy_set_header Upgrade $http_upgrade;
27
        proxy_set_header Connection "upgrade";
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
        proxy_read_timeout 300s;
33
    }
34
}

1
upstream django {
2
    # Unix Socket（性能比 TCP 好）
3
    server unix:/run/gunicorn.sock fail_timeout=0;
4
    # 或者用 TCP
5
    # server 127.0.0.1:8000;
6
}
7

8
server {
9
    listen 80;
10
    server_name django.example.com;
11

12
    # 上传文件大小限制
13
    client_max_body_size 100M;
14

15
    # 静态文件（Django 设置 STATIC_ROOT 后 collectstatic 收集到这里）
16
    location /static/ {
17
        alias /var/www/django/static/;
18
        expires 30d;
19
        access_log off;
20
    }
21

22
    # 媒体文件（用户上传）
23
    location /media/ {
24
        alias /var/www/django/media/;
25
        expires 7d;
26
        access_log off;
27
    }
28

29
    # Django 应用
30
    location / {
31
        proxy_pass http://django;
32
        proxy_set_header Host $host;
33
        proxy_set_header X-Real-IP $remote_addr;
34
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
35
        proxy_set_header X-Forwarded-Proto $scheme;
36
    }
37
}

1
upstream java_app {
2
    server 127.0.0.1:8080;
3
    server 127.0.0.1:8081;
4
}
5

6
server {
7
    listen 80;
8
    server_name java.example.com;
9

10
    location / {
11
        proxy_pass http://java_app;
12
        proxy_set_header Host $host;
13
        proxy_set_header X-Real-IP $remote_addr;
14
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
15
        proxy_set_header X-Forwarded-Proto $scheme;
16

17
        # Java 应用通常需要较长的超时时间
18
        proxy_connect_timeout 10s;
19
        proxy_read_timeout 300s;
20
        proxy_send_timeout 300s;
21
    }
22
}

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

5
    root /var/www/spa/dist;
6
    index index.html;
7

8
    # API 请求代理到后端
9
    location /api/ {
10
        proxy_pass http://127.0.0.1:3000/api/;
11
        proxy_set_header Host $host;
12
        proxy_set_header X-Real-IP $remote_addr;
13
    }
14

15
    # WebSocket 代理
16
    location /ws/ {
17
        proxy_pass http://127.0.0.1:3000;
18
        proxy_http_version 1.1;
19
        proxy_set_header Upgrade $http_upgrade;
20
        proxy_set_header Connection "upgrade";
21
    }
22

23
    # SPA 路由：所有非文件请求都返回 index.html
24
    location / {
25
        try_files $uri $uri/ /index.html;
26
    }
27

28
    # 缓存策略
29
    location ~* \.(js|css)$ {
30
        expires 1y;
31
        add_header Cache-Control "public, max-age=31536000, immutable";
32
    }
33

34
    location ~* \.(png|jpg|jpeg|gif|ico|svg)$ {
35
        expires 7d;
36
        access_log off;
37
    }
38
}

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

5
    # 安全头
6
    add_header X-Content-Type-Options "nosniff" always;
7
    add_header X-Frame-Options "DENY" always;
8
    add_header X-XSS-Protection "1; mode=block" always;
9
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
10
    add_header Content-Security-Policy "default-src 'self'" always;
11

12
    location / {
13
        proxy_pass http://127.0.0.1:3000;
14
        proxy_set_header Host $host;
15
        proxy_set_header X-Real-IP $remote_addr;
16
    }
17
}

1
http {
2
    # 定义限流区：名称=one，每秒 10 个请求，内存 10m
3
    limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s;
4

5
    server {
6
        listen 80;
7
        server_name api.example.com;
8

9
        location / {
10
            # 限流：使用 one 区，突发 20 个请求，延迟处理
11
            limit_req zone=one burst=20 nodelay;
12

13
            proxy_pass http://127.0.0.1:3000;
14
            proxy_set_header Host $host;
15
            proxy_set_header X-Real-IP $remote_addr;
16
        }
17
    }
18
}

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

5
    # 黑名单（拒绝访问）
6
    deny 192.168.1.100;
7
    deny 10.0.0.0/8;
8

9
    # 白名单（允许访问，配合 deny all 使用）
10
    allow 203.0.113.0/24;
11
    allow 198.51.100.50;
12
    deny all;   # 拒绝其他所有 IP
13

14
    location / {
15
        proxy_pass http://127.0.0.1:3000;
16
    }
17
}

1
# 在 http 块中
2
http {
3
    server_tokens off;   # 隐藏 Nginx 版本号（响应头中不显示版本）
4
    # ...
5
}

1
http {
2
    gzip on;
3
    gzip_vary on;
4
    gzip_proxied any;
5
    gzip_comp_level 6;           # 压缩级别 1-9，6 是性价比最高的
6
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
7
    gzip_min_length 1024;        # 小于 1KB 不压缩（压缩收益低）
8
}

1
# 需要 Nginx 编译时启用 ngx_brotli 模块
2
http {
3
    brotli on;
4
    brotli_comp_level 6;
5
    brotli_types text/plain text/css application/json application/javascript text/xml;
6
}

1
# root：将 location 路径附加到 root 路径后
2
location /static/ {
3
    root /var/www/app;
4
    # 请求 /static/logo.png → 查找 /var/www/app/static/logo.png
5
}
6

7
# alias：用 alias 路径替换 location 路径
8
location /static/ {
9
    alias /var/www/app/static/;
10
    # 请求 /static/logo.png → 查找 /var/www/app/static/logo.png
11
    # 注意：alias 路径末尾必须有 /（如果 location 末尾有 /）
12
}