1
浏览器私有缓存
2
    ↓ MISS / 需要验证
3
CDN 边缘共享缓存
4
    ↓ MISS / 回源
5
Nginx 静态文件或代理缓存
6
    ↓ MISS / 回源
7
Spring Boot 与业务数据源

1
GET /api/profile
2
Authorization: Bearer user-a-token

1
正确性与数据隔离
2
    > 一致性边界
3
    > 可用性
4
    > 命中率
5
    > 节省资源

1
Cache-Control: public, max-age=31536000, immutable
2
ETag: "asset-v7"
3
Last-Modified: Tue, 07 Jul 2026 03:00:00 GMT

1
location /assets/ {
2
    root /usr/share/nginx/html;
3
    try_files $uri =404;
4
}

1
客户端 → Nginx → 缓存 MISS → Spring Boot → 写入缓存 → 返回客户端

1
客户端 → Nginx → 缓存 HIT → 直接返回

1
/usr/share/nginx/html/
2
├── index.html
3
├── assets/
4
│   ├── app.8f3a1c.js
5
│   ├── style.4d2e1a.css
6
│   └── logo.a21d9f.svg
7
└── downloads/
8
    └── manual.pdf

1
index.html
2
→ 文件名通常固定
3
→ 内容可能频繁更新
4
→ 短缓存或 no-cache
5

6
assets/app.<content-hash>.js
7
→ 文件名由内容哈希决定
8
→ 内容变化时 URL 变化
9
→ 长缓存 + immutable

1
location /assets/ {
2
    root /usr/share/nginx/html;
3
}

1
/assets/app.8f3a1c.js

1
/usr/share/nginx/html/assets/app.8f3a1c.js

1
location /downloads/ {
2
    alias /data/public-files/;
3
}

1
/downloads/manual.pdf

1
/data/public-files/manual.pdf

1
location /downloads/ {
2
    alias /data/public-files;
3
}

1
location /assets/ {
2
    root /usr/share/nginx/html;
3
    try_files $uri =404;
4
}

1
错误：GET /assets/missing.js → 返回 index.html
2
结果：浏览器按 JavaScript 解析 HTML，出现 MIME 或语法错误

1
location / {
2
    try_files $uri $uri/ /index.html;
3
}

1
location /assets/ {
2
    try_files $uri =404;
3
}

1
include /etc/nginx/mime.types;
2
default_type application/octet-stream;

1
default_type text/plain;

1
sendfile on;

1
sendfile on;
2
tcp_nopush on;

1
open_file_cache          max=10000 inactive=60s;
2
open_file_cache_valid    30s;
3
open_file_cache_min_uses 2;
4
open_file_cache_errors   on;

1
location = /index.html {
2
    root /usr/share/nginx/html;
3
    try_files $uri =404;
4

5
    # 可以保存，但每次复用前向服务器验证。
6
    add_header Cache-Control "no-cache" always;
7
}
8

9
location /assets/ {
10
    root /usr/share/nginx/html;
11
    try_files $uri =404;
12

13
    expires 1y;
14
    add_header Cache-Control "public, max-age=31536000, immutable" always;
15

16
    access_log off;
17
}
18

19
location / {
20
    root /usr/share/nginx/html;
21
    try_files $uri $uri/ /index.html;
22
}

1
Cache-Control: public, max-age=31536000, immutable

1
Cache-Control: no-cache

1
Cache-Control: no-store

1
Cache-Control: private, no-store

1
Cache-Control: public, max-age=60, s-maxage=300

1
expires 7d;

1
Expires: <未来时间>
2
Cache-Control: max-age=<秒数>

1
Vary: Accept-Encoding

1
Vary: Accept-Language

1
Accept-Encoding: br, gzip

1
Content-Encoding: gzip
2
Vary: Accept-Encoding

1
gzip on;
2
gzip_vary on;
3
gzip_min_length 1024;
4
gzip_comp_level 5;
5
gzip_types
6
    text/plain
7
    text/css
8
    text/xml
9
    application/json
10
    application/javascript
11
    application/xml
12
    application/rss+xml
13
    image/svg+xml;

1
app.js
2
app.js.gz

1
gzip_static on;

1
brotli on;
2
brotli_static on;
3
brotli_comp_level 5;
4
brotli_types text/plain text/css application/json application/javascript;

1
proxy_cache_path /var/cache/nginx/api
2
    levels=1:2
3
    keys_zone=api_cache:20m
4
    max_size=512m
5
    inactive=30m
6
    use_temp_path=off;

1
location /api/cacheable/ {
2
    proxy_cache api_cache;
3
    proxy_pass http://backend;
4
}

1
proxy_cache_valid 200 15s;
2
proxy_cache_valid 404 5s;

1
proxy_ignore_headers Set-Cookie Cache-Control;

1
$scheme$proxy_host$request_uri

1
proxy_cache_key "$scheme$proxy_host$request_uri";

1
proxy_cache_convert_head off;

1
add_header X-Cache-Status $upstream_cache_status always;

1
proxy_cache_lock on;
2
proxy_cache_lock_timeout 5s;
3
proxy_cache_lock_age 5s;

1
proxy_cache_revalidate on;

1
If-None-Match
2
If-Modified-Since

1
proxy_cache_background_update on;
2
proxy_cache_use_stale updating;

1
proxy_cache_use_stale
2
    updating
3
    error
4
    timeout
5
    http_500
6
    http_502
7
    http_503
8
    http_504;

1
最大允许陈旧时间
2
+ 哪些错误允许 stale
3
+ 哪些接口绝不允许
4
+ 如何在响应或日志中标记
5
+ 后端恢复后如何刷新

1
/app.8f3a1c.js
2
/app.291ab7.js

1
proxy_cache_purge ...;

1
Nginx A → Cache A
2
Nginx B → Cache B

1
proxy_cache_valid 200 3s;

1
log_format cache_json escape=json
2
    '{'
3
    '"time":"$time_iso8601",'
4
    '"request_id":"$request_id",'
5
    '"host":"$host",'
6
    '"uri":"$request_uri",'
7
    '"status":$status,'
8
    '"cache_status":"$upstream_cache_status",'
9
    '"upstream":"$upstream_addr",'
10
    '"request_time":$request_time,'
11
    '"upstream_time":"$upstream_response_time",'
12
    '"bytes":$body_bytes_sent'
13
    '}';

1
应用数据是否已更新
2
→ Nginx proxy_cache 是否仍有旧值
3
→ CDN 是否仍有旧值
4
→ 浏览器是否仍有强缓存

1
nginx-cache-lab/
2
├── docker-compose.yml
3
├── nginx/
4
│   ├── nginx.conf
5
│   └── html/
6
│       ├── index.html
7
│       └── assets/
8
│           ├── app.8f3a1c.js
9
│           └── style.4d2e1a.css
10
├── backend/
11
│   ├── Dockerfile
12
│   ├── pom.xml
13
│   └── src/main/java/com/example/cachelab/
14
│       ├── CacheLabApplication.java
15
│       └── CacheController.java
16
└── scripts/
17
    └── verify.sh

1
services:
2
  backend:
3
    build:
4
      context: ./backend
5
    container_name: nginx-cache-backend
6
    environment:
7
      SERVER_PORT: "8080"
8
    expose:
9
      - "8080"
10
    healthcheck:
11
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/actuator/health"]
12
      interval: 5s
13
      timeout: 3s
14
      retries: 20
15
      start_period: 15s
16
    networks:
17
      - cache-lab
18

19
  nginx:
20
    image: nginx:1.30.3-alpine3.23
21
    container_name: nginx-cache-entry
22
    depends_on:
23
      backend:
24
        condition: service_healthy
25
    ports:
26
      - "8088:80"
27
    volumes:
28
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
29
      - ./nginx/html:/usr/share/nginx/html:ro
30
      - nginx_cache:/var/cache/nginx/api
31
    healthcheck:
32
      test: ["CMD", "wget", "-qO-", "http://localhost/healthz"]
33
      interval: 5s
34
      timeout: 3s
35
      retries: 10
36
    networks:
37
      - cache-lab
38

39
networks:
40
  cache-lab:
41
    driver: bridge
42

43
volumes:
44
  nginx_cache:

1
user nginx;
2
worker_processes auto;
3

4
error_log /var/log/nginx/error.log notice;
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
    log_format cache_json escape=json
16
        '{'
17
        '"time":"$time_iso8601",'
18
        '"request_id":"$request_id",'
19
        '"remote_addr":"$remote_addr",'
20
        '"method":"$request_method",'
21
        '"uri":"$request_uri",'
22
        '"status":$status,'
23
        '"cache_status":"$upstream_cache_status",'
24
        '"request_time":$request_time,'
25
        '"upstream_time":"$upstream_response_time",'
26
        '"bytes":$body_bytes_sent'
27
        '}';
28

29
    access_log /var/log/nginx/access.log cache_json;
30

31
    sendfile on;
32
    tcp_nopush on;
33
    keepalive_timeout 65s;
34

35
    open_file_cache          max=10000 inactive=60s;
36
    open_file_cache_valid    30s;
37
    open_file_cache_min_uses 2;
38
    open_file_cache_errors   on;
39

40
    gzip on;
41
    gzip_vary on;
42
    gzip_min_length 1024;
43
    gzip_comp_level 5;
44
    gzip_types
45
        text/plain
46
        text/css
47
        text/xml
48
        application/json
49
        application/javascript
50
        application/xml
51
        application/rss+xml
52
        image/svg+xml;
53

54
    proxy_cache_path /var/cache/nginx/api
55
        levels=1:2
56
        keys_zone=api_cache:20m
57
        max_size=512m
58
        inactive=30m
59
        use_temp_path=off;
60

61
    map $request_method $skip_method {
62
        default 1;
63
        GET     0;
64
        HEAD    0;
65
    }
66

67
    map $http_authorization $skip_authorization {
68
        default 1;
69
        ""      0;
70
    }
71

72
    map $cookie_session $skip_session {
73
        default 1;
74
        ""      0;
75
    }
76

77
    map $arg_nocache $skip_query {
78
        default 0;
79
        1       1;
80
    }
81

82
    map "$skip_method:$skip_authorization:$skip_session:$skip_query" $skip_cache {
83
        default     1;
84
        "0:0:0:0"  0;
85
    }
86

87
    upstream backend {
88
        server backend:8080;
89
        keepalive 32;
90
    }
91

92
    server {
93
        listen 80 default_server;
94
        server_name _;
95

96
        location = /healthz {
97
            access_log off;
98
            default_type text/plain;
99
            return 200 "ok\n";
100
        }
101

102
        location = /index.html {
103
            root /usr/share/nginx/html;
104
            try_files $uri =404;
105
            add_header Cache-Control "no-cache" always;
106
        }
107

108
        location /assets/ {
109
            root /usr/share/nginx/html;
110
            try_files $uri =404;
111

112
            expires 1y;
113
            add_header Cache-Control "public, max-age=31536000, immutable" always;
114

115
            access_log off;
116
        }
117

118
        location /api/cacheable/ {
119
            proxy_pass http://backend;
120
            proxy_http_version 1.1;
121
            proxy_set_header Host $host;
122
            proxy_set_header X-Request-ID $request_id;
123
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
124
            proxy_set_header X-Forwarded-Proto $scheme;
125

126
            proxy_cache api_cache;
127
            proxy_cache_key "$scheme$proxy_host$request_uri";
128
            proxy_cache_methods GET HEAD;
129
            proxy_cache_valid 200 15s;
130
            proxy_cache_valid 404 5s;
131

132
            proxy_cache_lock on;
133
            proxy_cache_lock_timeout 5s;
134
            proxy_cache_lock_age 5s;
135

136
            proxy_cache_revalidate on;
137
            proxy_cache_background_update on;
138
            proxy_cache_use_stale
139
                updating
140
                error
141
                timeout
142
                http_500
143
                http_502
144
                http_503
145
                http_504;
146

147
            proxy_cache_bypass $skip_cache;
148
            proxy_no_cache $skip_cache $upstream_http_set_cookie;
149

150
            add_header X-Cache-Status $upstream_cache_status always;
151
        }
152

153
        location /api/private/ {
154
            proxy_pass http://backend;
155
            proxy_http_version 1.1;
156
            proxy_set_header Host $host;
157
            proxy_set_header X-Request-ID $request_id;
158
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
159
            proxy_set_header X-Forwarded-Proto $scheme;
160

161
            add_header X-Cache-Status BYPASS always;
162
        }
163

164
        location / {
165
            root /usr/share/nginx/html;
166
            try_files $uri $uri/ /index.html;
167
        }
168
    }
169
}

1
<!doctype html>
2
<html lang="zh-CN">
3
<head>
4
  <meta charset="UTF-8" />
5
  <meta name="viewport" content="width=device-width, initial-scale=1" />
6
  <title>Nginx Cache Lab</title>
7
  <link rel="stylesheet" href="/assets/style.4d2e1a.css" />
8
</head>
9
<body>
10
  <main>
11
    <h1>Nginx Cache Lab</h1>
12
    <button id="load">请求可缓存时间接口</button>
13
    <pre id="result"></pre>
14
  </main>
15
  <script src="/assets/app.8f3a1c.js"></script>
16
</body>
17
</html>

1
const button = document.querySelector('#load');
2
const result = document.querySelector('#result');
3

4
button.addEventListener('click', async () => {
5
  const response = await fetch('/api/cacheable/time');
6
  const body = await response.json();
7

8
  result.textContent = JSON.stringify({
9
    cacheStatus: response.headers.get('X-Cache-Status'),
10
    body
11
  }, null, 2);
12
});

1
body {
2
  font-family: system-ui, sans-serif;
3
  margin: 0;
4
  background: #f5f7fb;
5
  color: #172033;
6
}
7

8
main {
9
  max-width: 760px;
10
  margin: 80px auto;
11
  padding: 32px;
12
  background: white;
13
  border-radius: 16px;
14
}

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

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

15
    <groupId>com.example</groupId>
16
    <artifactId>cache-lab</artifactId>
17
    <version>1.0.0</version>
18

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

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

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

1
package com.example.cachelab;
2

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

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

1
package com.example.cachelab;
2

3
import java.time.Instant;
4
import java.util.Map;
5
import java.util.concurrent.atomic.AtomicLong;
6

7
import org.springframework.http.HttpHeaders;
8
import org.springframework.http.ResponseCookie;
9
import org.springframework.http.ResponseEntity;
10
import org.springframework.web.bind.annotation.GetMapping;
11
import org.springframework.web.bind.annotation.RequestHeader;
12
import org.springframework.web.bind.annotation.RequestMapping;
13
import org.springframework.web.bind.annotation.RestController;
14

15
@RestController
16
@RequestMapping("/api")
17
public class CacheController {
18

19
    private final AtomicLong invocationCounter = new AtomicLong();
20

21
    @GetMapping("/cacheable/time")
22
    public ResponseEntity<Map<String, Object>> cacheableTime() {
23
        long invocation = invocationCounter.incrementAndGet();
24

25
        return ResponseEntity.ok()
26
                .header(HttpHeaders.CACHE_CONTROL,
27
                        "public, max-age=5, s-maxage=15")
28
                .body(Map.of(
29
                        "generatedAt", Instant.now().toString(),
30
                        "backendInvocation", invocation));
31
    }
32

33
    @GetMapping("/cacheable/slow")
34
    public ResponseEntity<Map<String, Object>> slow() throws InterruptedException {
35
        long invocation = invocationCounter.incrementAndGet();
36
        Thread.sleep(2000);
37

38
        return ResponseEntity.ok()
39
                .header(HttpHeaders.CACHE_CONTROL,
40
                        "public, max-age=5, s-maxage=15")
41
                .body(Map.of(
42
                        "generatedAt", Instant.now().toString(),
43
                        "backendInvocation", invocation,
44
                        "message", "slow response"));
45
    }
46

47
    @GetMapping("/cacheable/large")
48
    public ResponseEntity<Map<String, Object>> large() {
49
        return ResponseEntity.ok()
50
                .header(HttpHeaders.CACHE_CONTROL,
51
                        "public, max-age=5, s-maxage=15")
52
                .body(Map.of(
53
                        "generatedAt", Instant.now().toString(),
54
                        "payload", "x".repeat(4096)));
55
    }
56

57
    @GetMapping("/cacheable/language")
58
    public ResponseEntity<Map<String, Object>> language(
59
            @RequestHeader(value = "Accept-Language", defaultValue = "en") String language) {
60

61
        String message = language.toLowerCase().startsWith("zh")
62
                ? "你好"
63
                : "hello";
64

65
        return ResponseEntity.ok()
66
                .header(HttpHeaders.CACHE_CONTROL,
67
                        "public, max-age=10, s-maxage=30")
68
                .header(HttpHeaders.VARY, HttpHeaders.ACCEPT_LANGUAGE)
69
                .body(Map.of("language", language, "message", message));
70
    }
71

72
    @GetMapping("/private/profile")
73
    public ResponseEntity<Map<String, Object>> privateProfile() {
74
        ResponseCookie cookie = ResponseCookie.from("session", "demo-session")
75
                .httpOnly(true)
76
                .sameSite("Lax")
77
                .path("/")
78
                .build();
79

80
        return ResponseEntity.ok()
81
                .header(HttpHeaders.CACHE_CONTROL, "private, no-store")
82
                .header(HttpHeaders.SET_COOKIE, cookie.toString())
83
                .body(Map.of(
84
                        "user", "demo-user",
85
                        "generatedAt", Instant.now().toString()));
86
    }
87
}

1
FROM maven:3.9.11-eclipse-temurin-21 AS builder
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=builder /workspace/target/cache-lab-1.0.0.jar /app/app.jar
10
EXPOSE 8080
11
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

1
Cache-Control: no-cache

1
Cache-Control: public, max-age=31536000, immutable
2
Expires: ...
3
Content-Type: application/javascript

1
Content-Encoding: gzip
2
Vary: Accept-Encoding

1
X-Cache-Status: MISS

1
X-Cache-Status: HIT

1
X-Cache-Status: EXPIRED

1
X-Cache-Status: BYPASS

1
Cache-Control: private, no-store
2
Set-Cookie: session=...
3
X-Cache-Status: BYPASS