1
恢复可信客户端身份
2
    ↓
3
按用户、接口和全局容量实施分级限流
4
    ↓
5
记录结构化请求与 upstream 指标
6
    ↓
7
通过 Request ID 关联应用和下游日志
8
    ↓
9
按状态码、耗时和网络层级定位根因
10
    ↓
11
复盘并调整容量、阈值、降级和告警

1
limit_req_zone $binary_remote_addr zone=per_ip:10m rate=10r/s;

1
入口总限额
2
≈ 后端稳定容量
3
× 安全系数
4
− 内部任务与健康检查预算

1
http {
2
    limit_req_zone $binary_remote_addr
3
                   zone=per_ip:10m
4
                   rate=5r/s;
5

6
    server {
7
        location /api/search {
8
            limit_req zone=per_ip burst=10;
9
            proxy_pass http://backend;
10
        }
11
    }
12
}

1
# 客户端 IP
2
$binary_remote_addr
3

4
# 经过可信 Real IP 处理后的客户端 IP
5
$binary_remote_addr
6

7
# API Key
8
$http_x_api_key
9

10
# 应用鉴权后回传给 Nginx 的用户 ID
11
$http_x_user_id
12

13
# 租户 + 用户
14
"$http_x_tenant_id:$http_x_user_id"
15

16
# 接口 + 用户
17
"$uri:$http_x_user_id"

1
rate=5r/s

1
每个自然秒开始时重置计数，允许瞬间打入 5 个请求

1
rate=10r/s;
2
rate=30r/m;

1
limit_req zone=per_ip;

1
limit_req zone=per_ip burst=10;

1
总延迟
2
= Nginx 排队时间
3
+ upstream 处理时间
4
+ 响应传输时间

1
limit_req zone=per_ip burst=10 nodelay;

1
limit_req zone=per_ip burst=20 delay=5;

1
limit_req_status 429;
2
limit_conn_status 429;

1
log_format api_json escape=json
2
    '{'
3
      '"request_id":"$request_id",'
4
      '"status":$status,'
5
      '"limit_req_status":"$limit_req_status"'
6
    '}';
7

8
access_log /var/log/nginx/access_json.log api_json;

1
limit_req_dry_run on;
2
limit_conn_dry_run on;

1
设计 Key 与阈值
2
→ Dry Run
3
→ 观察至少一个完整业务周期
4
→ 分析误伤和峰值
5
→ 小流量启用
6
→ 监控 429、延迟与业务成功率
7
→ 逐步扩大

1
limit_req_log_level warn;
2
limit_conn_log_level warn;

1
http {
2
    limit_conn_zone $binary_remote_addr zone=per_ip_conn:10m;
3
    limit_conn_zone $server_name zone=per_server_conn:10m;
4

5
    server {
6
        limit_conn per_server_conn 1000;
7

8
        location /download/ {
9
            limit_conn per_ip_conn 2;
10
        }
11
    }
12
}

1
1 条 HTTP/2 TCP 连接
2
≠ limit_conn 只计 1

1
用户
2
→ CDN
3
→ 云负载均衡器
4
→ Nginx

1
X-Forwarded-For: 1.2.3.4

1
set_real_ip_from 10.0.0.0/8;
2
set_real_ip_from 192.168.0.0/16;
3

4
real_ip_header X-Forwarded-For;
5
real_ip_recursive on;

1
只信任 CDN / LB 的固定出口
2
而不是信任 0.0.0.0/0

1
geo $limit_whitelist {
2
    default         0;
3
    10.0.0.0/8      1;
4
    192.168.0.0/16  1;
5
}

1
map $limit_whitelist $limit_key {
2
    1       "";
3
    0       $binary_remote_addr;
4
}

1
limit_req_zone $limit_key zone=public_api:20m rate=20r/s;

1
map $http_x_api_key $client_tier {
2
    default        anonymous;
3
    "partner-a"    premium;
4
    "partner-b"    standard;
5
}

1
limit_req_zone $http_x_api_key zone=premium:10m rate=100r/s;
2
limit_req_zone $http_x_api_key zone=standard:10m rate=20r/s;
3
limit_req_zone $binary_remote_addr zone=anonymous:10m rate=5r/s;

1
limit_req_zone $binary_remote_addr zone=per_ip:20m rate=10r/s;
2
limit_req_zone $server_name zone=per_server:10m rate=500r/s;
3

4
location /api/expensive {
5
    limit_req zone=per_ip burst=10 nodelay;
6
    limit_req zone=per_server burst=100;
7
}

1
log_format api_json escape=json
2
    '{'
3
      '"timestamp":"$time_iso8601",'
4
      '"request_id":"$request_id",'
5
      '"remote_addr":"$remote_addr",'
6
      '"realip_remote_addr":"$realip_remote_addr",'
7
      '"host":"$host",'
8
      '"server_name":"$server_name",'
9
      '"method":"$request_method",'
10
      '"request_uri":"$request_uri",'
11
      '"uri":"$uri",'
12
      '"protocol":"$server_protocol",'
13
      '"status":$status,'
14
      '"request_length":$request_length,'
15
      '"bytes_sent":$bytes_sent,'
16
      '"body_bytes_sent":$body_bytes_sent,'
17
      '"request_time":$request_time,'
18
      '"upstream_addr":"$upstream_addr",'
19
      '"upstream_status":"$upstream_status",'
20
      '"upstream_connect_time":"$upstream_connect_time",'
21
      '"upstream_header_time":"$upstream_header_time",'
22
      '"upstream_response_time":"$upstream_response_time",'
23
      '"limit_req_status":"$limit_req_status",'
24
      '"limit_conn_status":"$limit_conn_status",'
25
      '"http_referer":"$http_referer",'
26
      '"http_user_agent":"$http_user_agent"'
27
    '}';

1
escape=json

1
map $request_uri $loggable {
2
    default         1;
3
    /actuator/health 0;
4
}
5

6
access_log /var/log/nginx/access_json.log api_json if=$loggable;

1
request_time 很高
2
不等于
3
后端业务处理一定很慢

1
后端开始返回结果前花了多久

1
{
2
  "upstream_addr": "10.0.1.10:8080, 10.0.1.11:8080",
3
  "upstream_status": "502, 200",
4
  "upstream_connect_time": "0.001, 0.002",
5
  "upstream_response_time": "0.010, 0.120"
6
}

1
proxy_set_header X-Request-ID $request_id;
2
add_header X-Request-ID $request_id always;

1
'"request_id":"$request_id"'

1
Nginx access log
2
request_id=abc...
3

4
Spring Boot log
5
request_id=abc...
6

7
下游调用
8
X-Request-ID: abc...

1
map $http_x_request_id $request_correlation_id {
2
    default $http_x_request_id;
3
    ""      $request_id;
4
}

1
error_log /var/log/nginx/error.log warn;

1
emerg
2
alert
3
crit
4
error
5
warn
6
notice
7
info
8
debug

1
error_log /var/log/nginx/debug.log debug;

1
upstream_status 为空
2
→ 可能 Nginx 直接 404
3

4
upstream_status=404
5
→ 后端返回 404

1
client_max_body_size

1
status
2
upstream_status
3
error_log
4
应用异常栈

1
看到 504
2
→ 把 proxy_read_timeout 从 60s 改成 600s

1
nginx-column-07/
2
├── docker-compose.yml
3
├── nginx/
4
│   ├── nginx.conf
5
│   └── conf.d/
6
│       └── default.conf
7
├── backend/
8
│   ├── Dockerfile
9
│   ├── pom.xml
10
│   └── src/main/java/com/example/demo/
11
│       ├── DemoApplication.java
12
│       ├── RequestIdFilter.java
13
│       └── DemoController.java
14
└── scripts/
15
    ├── test-rate-limit.sh
16
    ├── test-connection-limit.sh
17
    └── test-errors.sh

1
services:
2
  nginx:
3
    image: nginx:1.30.3
4
    container_name: nginx-column-07
5
    ports:
6
      - "8088:8088"
7
    volumes:
8
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
9
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
10
    depends_on:
11
      backend:
12
        condition: service_healthy
13
    networks:
14
      - nginx-lab
15

16
  backend:
17
    build:
18
      context: ./backend
19
    container_name: nginx-column-07-backend
20
    expose:
21
      - "8080"
22
    environment:
23
      SERVER_PORT: "8080"
24
    healthcheck:
25
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/actuator/health"]
26
      interval: 5s
27
      timeout: 2s
28
      retries: 20
29
    networks:
30
      - nginx-lab
31

32
networks:
33
  nginx-lab:
34
    driver: bridge

1
user  nginx;
2
worker_processes auto;
3

4
error_log /var/log/nginx/error.log warn;
5
pid       /var/run/nginx.pid;
6

7
events {
8
    worker_connections 4096;
9
}
10

11
http {
12
    include       /etc/nginx/mime.types;
13
    default_type  application/octet-stream;
14

15
    # 日志格式只能定义在 http 上下文。
16
    log_format api_json escape=json
17
        '{'
18
          '"timestamp":"$time_iso8601",'
19
          '"request_id":"$request_id",'
20
          '"remote_addr":"$remote_addr",'
21
          '"method":"$request_method",'
22
          '"request_uri":"$request_uri",'
23
          '"status":$status,'
24
          '"request_length":$request_length,'
25
          '"bytes_sent":$bytes_sent,'
26
          '"request_time":$request_time,'
27
          '"upstream_addr":"$upstream_addr",'
28
          '"upstream_status":"$upstream_status",'
29
          '"upstream_connect_time":"$upstream_connect_time",'
30
          '"upstream_header_time":"$upstream_header_time",'
31
          '"upstream_response_time":"$upstream_response_time",'
32
          '"limit_req_status":"$limit_req_status",'
33
          '"limit_conn_status":"$limit_conn_status",'
34
          '"user_agent":"$http_user_agent"'
35
        '}';
36

37
    access_log /var/log/nginx/access.log api_json;
38

39
    # 按客户端 IP 的请求速率。
40
    limit_req_zone $binary_remote_addr
41
                   zone=per_ip_api:10m
42
                   rate=5r/s;
43

44
    # 全局接口保护：所有请求共用 server_name 作为 Key。
45
    limit_req_zone $server_name
46
                   zone=per_server_api:10m
47
                   rate=100r/s;
48

49
    # 并发限制。
50
    limit_conn_zone $binary_remote_addr
51
                    zone=per_ip_conn:10m;
52

53
    sendfile on;
54
    keepalive_timeout 65s;
55

56
    include /etc/nginx/conf.d/*.conf;
57
}

1
upstream backend {
2
    server backend:8080;
3
}
4

5
server {
6
    listen 8088 default_server;
7
    server_name _;
8

9
    limit_req_status 429;
10
    limit_conn_status 429;
11

12
    add_header X-Request-ID $request_id always;
13

14
    location = /healthz {
15
        access_log off;
16
        return 200 "ok\n";
17
    }
18

19
    location /api/normal {
20
        limit_req zone=per_ip_api burst=5 nodelay;
21
        limit_req zone=per_server_api burst=20;
22

23
        proxy_set_header Host $host;
24
        proxy_set_header X-Request-ID $request_id;
25
        proxy_set_header X-Real-IP $remote_addr;
26
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
27

28
        proxy_connect_timeout 2s;
29
        proxy_read_timeout 10s;
30
        proxy_pass http://backend;
31
    }
32

33
    location /api/limited {
34
        # 用低阈值观察排队和拒绝。
35
        limit_req zone=per_ip_api burst=2;
36

37
        proxy_set_header X-Request-ID $request_id;
38
        proxy_pass http://backend;
39
    }
40

41
    location /api/slow {
42
        limit_req zone=per_ip_api burst=3;
43
        limit_conn per_ip_conn 2;
44

45
        proxy_set_header X-Request-ID $request_id;
46
        proxy_connect_timeout 2s;
47
        proxy_read_timeout 3s;
48
        proxy_pass http://backend;
49
    }
50

51
    location /api/download {
52
        limit_conn per_ip_conn 1;
53
        limit_rate_after 1m;
54
        limit_rate 512k;
55

56
        proxy_set_header X-Request-ID $request_id;
57
        proxy_pass http://backend;
58
    }
59

60
    location /api/stream {
61
        limit_conn per_ip_conn 2;
62

63
        proxy_buffering off;
64
        proxy_read_timeout 30s;
65
        proxy_set_header X-Request-ID $request_id;
66
        proxy_pass http://backend;
67
    }
68

69
    location /api/error {
70
        proxy_set_header X-Request-ID $request_id;
71
        proxy_pass http://backend;
72
    }
73
}

1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0"
3
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
         xsi:schemaLocation="
5
           http://maven.apache.org/POM/4.0.0
6
           https://maven.apache.org/xsd/maven-4.0.0.xsd">
7

8
    <modelVersion>4.0.0</modelVersion>
9

10
    <parent>
11
        <groupId>org.springframework.boot</groupId>
12
        <artifactId>spring-boot-starter-parent</artifactId>
13
        <version>4.1.0</version>
14
        <relativePath/>
15
    </parent>
16

17
    <groupId>com.example</groupId>
18
    <artifactId>nginx-column-07</artifactId>
19
    <version>1.0.0</version>
20

21
    <properties>
22
        <java.version>21</java.version>
23
    </properties>
24

25
    <dependencies>
26
        <dependency>
27
            <groupId>org.springframework.boot</groupId>
28
            <artifactId>spring-boot-starter-web</artifactId>
29
        </dependency>
30

31
        <dependency>
32
            <groupId>org.springframework.boot</groupId>
33
            <artifactId>spring-boot-starter-actuator</artifactId>
34
        </dependency>
35
    </dependencies>
36

37
    <build>
38
        <plugins>
39
            <plugin>
40
                <groupId>org.springframework.boot</groupId>
41
                <artifactId>spring-boot-maven-plugin</artifactId>
42
            </plugin>
43
        </plugins>
44
    </build>
45
</project>

1
FROM maven:3.9.11-eclipse-temurin-21 AS build
2
WORKDIR /workspace
3

4
COPY pom.xml .
5
RUN mvn -q -DskipTests dependency:go-offline
6

7
COPY src ./src
8
RUN mvn -q -DskipTests package
9

10
FROM eclipse-temurin:21-jre
11
WORKDIR /app
12

13
COPY --from=build \
14
  /workspace/target/nginx-column-07-1.0.0.jar \
15
  /app/app.jar
16

17
EXPOSE 8080
18

19
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

1
package com.example.demo;
2

3
import org.springframework.boot.SpringApplication;
4
import org.springframework.boot.autoconfigure.SpringBootApplication;
5

6
@SpringBootApplication
7
public class DemoApplication {
8

9
    public static void main(String[] args) {
10
        SpringApplication.run(DemoApplication.class, args);
11
    }
12
}

1
package com.example.demo;
2

3
import jakarta.servlet.FilterChain;
4
import jakarta.servlet.ServletException;
5
import jakarta.servlet.http.HttpServletRequest;
6
import jakarta.servlet.http.HttpServletResponse;
7
import org.slf4j.MDC;
8
import org.springframework.stereotype.Component;
9
import org.springframework.web.filter.OncePerRequestFilter;
10

11
import java.io.IOException;
12

13
@Component
14
public class RequestIdFilter extends OncePerRequestFilter {
15

16
    private static final String HEADER = "X-Request-ID";
17
    private static final String MDC_KEY = "requestId";
18

19
    @Override
20
    protected void doFilterInternal(
21
            HttpServletRequest request,
22
            HttpServletResponse response,
23
            FilterChain filterChain
24
    ) throws ServletException, IOException {
25

26
        String requestId = request.getHeader(HEADER);
27

28
        if (requestId == null || requestId.isBlank()) {
29
            requestId = "application-generated";
30
        }
31

32
        MDC.put(MDC_KEY, requestId);
33
        response.setHeader(HEADER, requestId);
34

35
        try {
36
            filterChain.doFilter(request, response);
37
        } finally {
38
            MDC.remove(MDC_KEY);
39
        }
40
    }
41
}

1
package com.example.demo;
2

3
import jakarta.servlet.http.HttpServletRequest;
4
import org.springframework.http.MediaType;
5
import org.springframework.web.bind.annotation.GetMapping;
6
import org.springframework.web.bind.annotation.RestController;
7
import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody;
8

9
import java.nio.charset.StandardCharsets;
10
import java.time.Instant;
11
import java.util.Map;
12

13
@RestController
14
public class DemoController {
15

16
    @GetMapping("/api/normal")
17
    public Map<String, Object> normal(HttpServletRequest request) {
18
        return Map.of(
19
                "message", "normal response",
20
                "requestId", request.getHeader("X-Request-ID"),
21
                "time", Instant.now().toString()
22
        );
23
    }
24

25
    @GetMapping("/api/limited")
26
    public Map<String, Object> limited(HttpServletRequest request) {
27
        return Map.of(
28
                "message", "limited endpoint",
29
                "requestId", request.getHeader("X-Request-ID")
30
        );
31
    }
32

33
    @GetMapping("/api/slow")
34
    public Map<String, Object> slow(HttpServletRequest request)
35
            throws InterruptedException {
36

37
        Thread.sleep(5_000);
38

39
        return Map.of(
40
                "message", "slow response",
41
                "requestId", request.getHeader("X-Request-ID")
42
        );
43
    }
44

45
    @GetMapping(
46
            value = "/api/download",
47
            produces = MediaType.APPLICATION_OCTET_STREAM_VALUE
48
    )
49
    public byte[] download() {
50
        return new byte[5 * 1024 * 1024];
51
    }
52

53
    @GetMapping(
54
            value = "/api/stream",
55
            produces = MediaType.TEXT_EVENT_STREAM_VALUE
56
    )
57
    public StreamingResponseBody stream() {
58
        return outputStream -> {
59
            for (int i = 1; i <= 10; i++) {
60
                String event = "data: event-" + i + "\n\n";
61
                outputStream.write(event.getBytes(StandardCharsets.UTF_8));
62
                outputStream.flush();
63
                Thread.sleep(1_000);
64
            }
65
        };
66
    }
67

68
    @GetMapping("/api/error")
69
    public Map<String, Object> error() {
70
        throw new IllegalStateException("intentional test error");
71
    }
72
}

1
limit_req_dry_run on;
2
limit_conn_dry_run on;

1
limit_req_status
2
limit_conn_status
3
request_time
4
upstream_response_time
5
URI
6
用户或租户维度

1
limit_req zone=per_user ...;
2
limit_req zone=per_server ...;

1
Nginx 粗粒度保护
2
+ API Gateway / 应用配额
3
+ 应用线程池隔离
4
+ 下游熔断
5
+ 降级与异步任务

1
status
2
limit_req_status
3
limit_conn_status
4
upstream_addr 是否为空

1
upstream_addr
2
upstream_status
3
upstream_connect_time
4
upstream_header_time
5
upstream_response_time