1
客户端连接：Client  <------ HTTP/TCP ------>  Nginx
2
上游连接：Nginx   <------ HTTP/TCP ------>  Spring Boot

1
1. 客户端与 Nginx 建立 TCP/TLS 连接
2
2. 客户端向 Nginx 发送 HTTP 请求
3
3. Nginx 选择 server 与 location
4
4. Nginx 计算 upstream 地址和转发 URI
5
5. Nginx 生成一份发往后端的新请求
6
6. Nginx 新建或复用到后端的连接
7
7. 后端处理请求并向 Nginx 返回响应
8
8. Nginx 根据缓冲、过滤、错误页等配置处理响应
9
9. Nginx 将响应发送给客户端

1
server {
2
    listen 8088;
3
    server_name _;
4

5
    location /api/ {
6
        proxy_pass http://backend:8080;
7
    }
8
}

1
GET /api/users/42?detail=true HTTP/1.1

1
location /api/ {
2
    proxy_pass http://backend:8080;
3
}

1
/api/users/42?detail=true

1
/api/users/42?detail=true

1
location /api/ {
2
    proxy_pass http://backend:8080/;
3
}

1
/api/users/42?detail=true

1
/users/42?detail=true

1
/api/ + users/42
2
替换为
3
/     + users/42
4
=
5
/users/42

1
location /api/ {
2
    proxy_pass http://backend:8080/service/;
3
}

1
/api/users/42

1
/service/users/42

1
location /api/ {
2
    proxy_pass http://backend:8080/service;
3
}

1
/serviceusers

1
location ~ ^/api/v[0-9]+/ {
2
    proxy_pass http://backend:8080;
3
}

1
location @backend_fallback {
2
    proxy_pass http://backend:8080;
3
}

1
location /legacy/ {
2
    rewrite ^/legacy/(.*)$ /api/$1 break;
3
    proxy_pass http://backend:8080;
4
}

1
set $backend "http://backend:8080";
2

3
location /api/ {
4
    proxy_pass $backend/service/;
5
}

1
proxy_set_header Host $host;

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;
5
proxy_set_header X-Forwarded-Host  $host;
6
proxy_set_header X-Forwarded-Port  $server_port;

1
X-Forwarded-For: 127.0.0.1

1
server:
2
  forward-headers-strategy: native

1
http {
2
    proxy_set_header Host $host;
3
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
4

5
    server {
6
        location /api/ {
7
            proxy_set_header X-Debug true;
8
            proxy_pass http://backend;
9
        }
10
    }
11
}

1
include /etc/nginx/snippets/proxy-headers.conf;
2
proxy_set_header X-Debug true;

1
读取客户端请求头
2
→ 读取客户端请求体
3
→ 连接 upstream
4
→ 向 upstream 发送请求
5
→ 等待 upstream 返回数据
6
→ 向客户端发送响应

1
proxy_connect_timeout 3s;

1
proxy_send_timeout 30s;

1
proxy_read_timeout 60s;

1
proxy_request_buffering off;

1
proxy_buffering off;

1
client_max_body_size 100m;
2
client_body_timeout 60s;

1
proxy_http_version 1.1;
2
proxy_set_header Connection "";

1
upstream backend_pool {
2
    server backend:8080;
3
    keepalive 32;
4
    keepalive_requests 1000;
5
    keepalive_timeout 60s;
6
}

1
Nginx Worker 数
2
× 每 Worker 活跃 upstream 连接
3
× 应用实例数
4
× 应用线程与数据库连接池

1
Upgrade: websocket
2
Connection: Upgrade

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

6
server {
7
    location /ws/ {
8
        proxy_pass http://backend_pool;
9
        proxy_http_version 1.1;
10
        proxy_set_header Upgrade $http_upgrade;
11
        proxy_set_header Connection $connection_upgrade;
12
        proxy_set_header Host $host;
13
        proxy_read_timeout 65s;
14
    }
15
}

1
data: message-1\n\n

1
location /sse/ {
2
    proxy_pass http://backend_pool;
3
    proxy_buffering off;
4
    proxy_cache off;
5
    proxy_read_timeout 75s;
6

7
    proxy_set_header Host $host;
8
    proxy_set_header X-Forwarded-Proto $scheme;
9
}

1
X-Accel-Buffering: no
2
Cache-Control: no-cache
3
Content-Type: text/event-stream

1
: heartbeat\n\n

1
connect() failed (111: Connection refused) while connecting to upstream
2
upstream prematurely closed connection while reading response header from upstream

1
客户端超时 < 上层代理超时 < Nginx 超时 < 应用超时

1
proxy_intercept_errors on;
2
error_page 500 502 503 504 /50x.html;

1
nginx-reverse-proxy-lab/
2
├── docker-compose.yml
3
├── backend/
4
│   ├── Dockerfile
5
│   ├── pom.xml
6
│   └── src/main/
7
│       ├── java/com/example/proxylab/
8
│       │   ├── ProxyLabApplication.java
9
│       │   ├── ApiController.java
10
│       │   └── WebSocketConfig.java
11
│       └── resources/
12
│           └── application.yml
13
└── nginx/
14
    ├── nginx.conf
15
    ├── conf.d/
16
    │   └── proxy-lab.conf
17
    ├── snippets/
18
    │   └── proxy-headers.conf
19
    └── html/
20
        └── 50x.html

1
services:
2
  backend:
3
    build:
4
      context: ./backend
5
    container_name: proxy-lab-backend
6
    expose:
7
      - "8080"
8
    ports:
9
      - "18080:8080"
10
    networks:
11
      - proxy-lab
12

13
  nginx:
14
    image: nginx:1.30.3-alpine
15
    container_name: proxy-lab-nginx
16
    depends_on:
17
      - backend
18
    ports:
19
      - "8088:8088"
20
    volumes:
21
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
22
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
23
      - ./nginx/snippets:/etc/nginx/snippets:ro
24
      - ./nginx/html:/usr/share/nginx/html:ro
25
    networks:
26
      - proxy-lab
27

28
networks:
29
  proxy-lab:
30
    driver: bridge

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="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
5
    <modelVersion>4.0.0</modelVersion>
6

7
    <parent>
8
        <groupId>org.springframework.boot</groupId>
9
        <artifactId>spring-boot-starter-parent</artifactId>
10
        <version>3.5.15</version>
11
        <relativePath/>
12
    </parent>
13

14
    <groupId>com.example</groupId>
15
    <artifactId>proxy-lab</artifactId>
16
    <version>0.0.1-SNAPSHOT</version>
17

18
    <properties>
19
        <java.version>21</java.version>
20
    </properties>
21

22
    <dependencies>
23
        <dependency>
24
            <groupId>org.springframework.boot</groupId>
25
            <artifactId>spring-boot-starter-web</artifactId>
26
        </dependency>
27
        <dependency>
28
            <groupId>org.springframework.boot</groupId>
29
            <artifactId>spring-boot-starter-websocket</artifactId>
30
        </dependency>
31
    </dependencies>
32

33
    <build>
34
        <plugins>
35
            <plugin>
36
                <groupId>org.springframework.boot</groupId>
37
                <artifactId>spring-boot-maven-plugin</artifactId>
38
            </plugin>
39
        </plugins>
40
    </build>
41
</project>

1
FROM maven:3.9.11-eclipse-temurin-21-alpine AS build
2
WORKDIR /workspace
3
COPY pom.xml .
4
COPY src ./src
5
RUN mvn -q -DskipTests package
6

7
FROM eclipse-temurin:21-jre-alpine
8
WORKDIR /app
9
COPY --from=build /workspace/target/proxy-lab-0.0.1-SNAPSHOT.jar app.jar
10
EXPOSE 8080
11
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

1
server:
2
  port: 8080
3
  forward-headers-strategy: native
4

5
spring:
6
  application:
7
    name: proxy-lab

1
package com.example.proxylab;
2

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

6
@SpringBootApplication
7
public class ProxyLabApplication {
8
    public static void main(String[] args) {
9
        SpringApplication.run(ProxyLabApplication.class, args);
10
    }
11
}

1
package com.example.proxylab;
2

3
import jakarta.servlet.http.HttpServletRequest;
4
import org.springframework.http.MediaType;
5
import org.springframework.web.bind.annotation.*;
6
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
7

8
import java.time.Instant;
9
import java.util.LinkedHashMap;
10
import java.util.Map;
11
import java.util.concurrent.CompletableFuture;
12

13
@RestController
14
public class ApiController {
15

16
    @GetMapping({"/api/hello", "/hello", "/service/hello", "/keep-prefix/api/hello"})
17
    public Map<String, Object> hello(HttpServletRequest request) {
18
        return Map.of(
19
                "message", "hello from Spring Boot",
20
                "requestUri", request.getRequestURI(),
21
                "query", String.valueOf(request.getQueryString()),
22
                "time", Instant.now().toString()
23
        );
24
    }
25

26
    @GetMapping("/api/headers")
27
    public Map<String, Object> headers(HttpServletRequest request) {
28
        Map<String, Object> result = new LinkedHashMap<>();
29
        result.put("remoteAddr", request.getRemoteAddr());
30
        result.put("scheme", request.getScheme());
31
        result.put("serverName", request.getServerName());
32
        result.put("serverPort", request.getServerPort());
33
        result.put("host", request.getHeader("Host"));
34
        result.put("xRealIp", request.getHeader("X-Real-IP"));
35
        result.put("xForwardedFor", request.getHeader("X-Forwarded-For"));
36
        result.put("xForwardedProto", request.getHeader("X-Forwarded-Proto"));
37
        return result;
38
    }
39

40
    @GetMapping("/api/slow")
41
    public Map<String, Object> slow(@RequestParam(defaultValue = "3") long seconds)
42
            throws InterruptedException {
43
        Thread.sleep(seconds * 1000);
44
        return Map.of("sleptSeconds", seconds);
45
    }
46

47
    @PostMapping(value = "/api/upload", consumes = MediaType.ALL_VALUE)
48
    public Map<String, Object> upload(@RequestBody byte[] body) {
49
        return Map.of("receivedBytes", body.length);
50
    }
51

52
    @GetMapping("/api/error")
53
    public void error() {
54
        throw new IllegalStateException("intentional error");
55
    }
56

57
    @GetMapping(value = "/api/sse", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
58
    public SseEmitter sse() {
59
        SseEmitter emitter = new SseEmitter(0L);
60
        CompletableFuture.runAsync(() -> {
61
            try {
62
                for (int i = 1; i <= 5; i++) {
63
                    emitter.send(SseEmitter.event()
64
                            .name("message")
65
                            .data("event-" + i));
66
                    Thread.sleep(1000);
67
                }
68
                emitter.complete();
69
            } catch (Exception ex) {
70
                emitter.completeWithError(ex);
71
            }
72
        });
73
        return emitter;
74
    }
75
}

1
package com.example.proxylab;
2

3
import org.springframework.context.annotation.Configuration;
4
import org.springframework.web.socket.*;
5
import org.springframework.web.socket.config.annotation.*;
6

7
@Configuration
8
@EnableWebSocket
9
public class WebSocketConfig implements WebSocketConfigurer {
10
    @Override
11
    public void registerWebSocketHandlers(WebSocketHandlerRegistry registry) {
12
        registry.addHandler(new TextWebSocketHandler() {
13
            @Override
14
            protected void handleTextMessage(
15
                    WebSocketSession session,
16
                    TextMessage message) throws Exception {
17
                session.sendMessage(new TextMessage("echo: " + message.getPayload()));
18
            }
19
        }, "/ws/echo").setAllowedOriginPatterns("*");
20
    }
21
}

1
user nginx;
2
worker_processes auto;
3
error_log /var/log/nginx/error.log notice;
4
pid /var/run/nginx.pid;
5

6
events {
7
    worker_connections 1024;
8
}
9

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

14
    log_format proxy_lab
15
        '$remote_addr - $host "$request" status=$status '
16
        'request_time=$request_time upstream_addr=$upstream_addr '
17
        'upstream_status=$upstream_status connect=$upstream_connect_time '
18
        'header=$upstream_header_time response=$upstream_response_time';
19

20
    access_log /var/log/nginx/access.log proxy_lab;
21
    sendfile on;
22
    keepalive_timeout 65s;
23

24
    include /etc/nginx/conf.d/*.conf;
25
}

1
proxy_set_header Host              $host;
2
proxy_set_header X-Real-IP         $remote_addr;
3
proxy_set_header X-Forwarded-For   $remote_addr;
4
proxy_set_header X-Forwarded-Proto $scheme;
5
proxy_set_header X-Forwarded-Host  $host;
6
proxy_set_header X-Forwarded-Port  $server_port;

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

6
upstream backend_pool {
7
    server backend:8080;
8
    keepalive 32;
9
    keepalive_requests 1000;
10
    keepalive_timeout 60s;
11
}
12

13
server {
14
    listen 8088;
15
    server_name _;
16

17
    client_max_body_size 2m;
18

19
    # 1. 保留 /api/ 前缀
20
    location /keep-prefix/ {
21
        proxy_pass http://backend_pool;
22
        include /etc/nginx/snippets/proxy-headers.conf;
23
    }
24

25
    # 2. 删除 /strip/ 前缀
26
    location /strip/ {
27
        proxy_pass http://backend_pool/;
28
        include /etc/nginx/snippets/proxy-headers.conf;
29
    }
30

31
    # 3. 将 /replace/ 替换为 /service/
32
    location /replace/ {
33
        proxy_pass http://backend_pool/service/;
34
        include /etc/nginx/snippets/proxy-headers.conf;
35
    }
36

37
    # 4. 普通 API
38
    location /api/ {
39
        proxy_pass http://backend_pool;
40
        include /etc/nginx/snippets/proxy-headers.conf;
41

42
        proxy_connect_timeout 3s;
43
        proxy_send_timeout 30s;
44
        proxy_read_timeout 10s;
45
    }
46

47
    # 5. SSE
48
    location /sse/ {
49
        rewrite ^/sse/(.*)$ /api/$1 break;
50
        proxy_pass http://backend_pool;
51
        include /etc/nginx/snippets/proxy-headers.conf;
52

53
        proxy_buffering off;
54
        proxy_cache off;
55
        proxy_read_timeout 75s;
56
    }
57

58
    # 6. WebSocket
59
    location /ws/ {
60
        proxy_pass http://backend_pool;
61
        include /etc/nginx/snippets/proxy-headers.conf;
62

63
        proxy_http_version 1.1;
64
        proxy_set_header Upgrade $http_upgrade;
65
        proxy_set_header Connection $connection_upgrade;
66
        proxy_read_timeout 65s;
67
    }
68

69
    proxy_intercept_errors on;
70
    error_page 502 503 504 /50x.html;
71

72
    location = /50x.html {
73
        internal;
74
        root /usr/share/nginx/html;
75
    }
76
}

1
<!doctype html>
2
<html lang="zh-CN">
3
<head><meta charset="utf-8"><title>Upstream unavailable</title></head>
4
<body><h1>后端服务暂时不可用</h1></body>
5
</html>

1
hello

1
echo: hello

1
location /api/ {
2
    proxy_pass http://backend:8080;
3
}

1
location /api/ {
2
    proxy_pass http://backend:8080;
3
    proxy_set_header Host $host;
4
    proxy_set_header X-Real-IP $remote_addr;
5
    proxy_set_header X-Forwarded-For $remote_addr;
6
    proxy_set_header X-Forwarded-Proto $scheme;
7
}

1
proxy_connect_timeout 3s;
2
proxy_send_timeout 30s;
3
proxy_read_timeout 15s;

1
request_time
2
upstream_addr
3
upstream_status
4
upstream_connect_time
5
upstream_header_time
6
upstream_response_time
7
request_id

1
生成配置
2
→ nginx -t
3
→ nginx -T 留档
4
→ reload
5
→ 冒烟验证
6
→ 观察 4xx/5xx 与 upstream 指标
7
→ 异常时恢复旧配置并 reload

1
remoteAddr
2
Host
3
X-Real-IP
4
X-Forwarded-For
5
X-Forwarded-Proto

1
$status
2
$upstream_status
3
error_log
4
应用日志

1
Client
2
→ CDN/WAF
3
→ Cloud Load Balancer
4
→ Nginx
5
→ API Gateway
6
→ Spring Boot